include table of contents & index on type aliases that contain properties

[techfg]

Search Terms

type alias, table of contents, index

Problem

Type Aliases are often extremely short pages that simply point to the type that is being aliased. However, they can also be actual types with properties or use tags (e.g., @useDeclaredType) in which case properties will be emitted.

Currently, on type alias output pages, page navigation can be challenging, especially in situations where there are lots of properties on a type and/or comments & information included. Interfaces contain a table of contents and index section (even when there is only one group with one item in that group) to improve navigation of the page, where type alias pages do not.

Suggested Solution

When a type (likely also applies to variable pages as well) contains properties (either directly, via @useDeclaredType, etc.), include a table of contents and index section in the default theme.

Below is an interface and a type that are essentially equivalent other than one being an interface and one being a type, yet interface contains the additional navigation elements while type alias does not.

Repro: https://stackblitz.com/edit/vitejs-vite-ek1829mh?file=src%2Findex.ts

Thank you!

[Gerrit0]

This would be a super ugly change... those properties are inside the type declaration for the alias, and types never get added to the index... so to implement this, I'd want to move object literal types to regular properties, which is then a significant breaking change.

[techfg]

Thanks @Gerrit0, makes sense. In reviewing the code, it didn't look trivial to accomplish.

It's definitely not a must have, but assuming you agree with the concept, possibly something to consider for next major as, in addition to toc & index, things like @group, @groupDescription, etc. don't work on type declarations, variables, etc. from what I've tested.

[Gerrit0]

Yes, that's correct. Those are meant for usage in organizing exports. Attempting to shove so much content into a type that it needs something that is rather insane in my opinion. Split up your types! If object type aliases are reworked to be represented like interfaces, they'd get support for group/interface for free.

[techfg]

Yeah, agreed, don't see much of a benefit/need for things like @group, etc., just mentioned because it's related to a potential re-work as you mention.

I do think there is benefit to a toc & index for types that have props though 😄