Do we need a component for Table of contents?

[methomps]

This was lingering in our Trello board in "Ready for development". Chris Doherty has been managing updates to the pattern in WebRH to service the needs of this pattern in the Drupal HTML resource template(s). Not sure if this needs to be built as a web component or not. Deserves some discussion.

[markcaron]

I could be wrong, but I believe there was some back and forth about whether a "Table of Contents" was the same as "Jump Links". If so, I feel like they're different, and in our use cases across Red Hat we would need different components. For example, Documentation in the Customer Portal has a need for a very different Table of Contents than what our Jump Links provides.

Thoughts @wesruv or @KrystalMoore16?

[wesruv]

I have a confuse. Are there any more details, a design or description?
If there's no design, I vote no, we don't make a new component.

My confusion:
I can't think of anything particular to "table of contents" from an HTML/CSS/behavior perspective that doesn't also apply to a "menu".

We could have a design that specifies a different look and behavior to something it defines as a "table of contents", but then I'd recommend naming the component after how it looks or behaves and not "table of contents". If it's the gray box with links like at the top of Wikipedia articles, it's just the CSS for a box?

Feels a bit pedantic, very much like this explanation of my confusion.

pfe-jump-links could be a "Table of Contents", but I think the name is better at implying the behavior.

[methomps]

FWIW- here is an example of how the WebRH pattern for Table of Contents is being used in our new templates for HTML assets at the Resource Library: https://www.redhat.com/en/resources/self-managed-openshift-sizing-subscription-guide

[wesruv]

But that example is the pfe-jump-links component:

The term "table of contents" is about it's function to the content, more than a good description of an interactive component. So what would a "table of contents" component even be, what problem would it solve?

I can't think of one where I wouldn't just use pfe-jump-links or the <details>, or pfe-accordion, and then add a few type styles and maybe a background color and/or border.

If there's another component that we could make that'd make a cool table of contents, I wouldn't name it pfe-table-of-contents, there'd probably be a better name that described it's style and behavior.

[KrystalMoore16]

We should ask Adela to weigh in since she used both a TOC and jump link section in the new docs experience. I can't tag her here, but will call it out in our design leads chat.

There's certainly some overlap, but I'm pretty sure that her TOC is bringing the user to a new page whereas jump links are jumping you to sections on the same page. Adela, please correct me if I'm wrong! They feel similar, but a TOC is different in my opinion. With that being said though, I don't feel like we have enough use cases to prioritize a TOC component over more critical ones.

[KrystalMoore16]

@bennypowers - I'm simply providing our best example from the Customer Portal.
https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.11/html/migrating_3scale/index

This is not treated as hash links to sections and I don't know that I've ever seen any documentation to support that a ToC is always treated like a jump link section.

[markcaron]

I see both sides, here, as being valid.

Perhaps, there's a misalignment of the term "Table of Contents" in its visual representation (or use case) and its implementation?

While a ToC on the web is commonly made up of hash links (like in a wiki), the use case on the Portal's Documentation requires a ToC-like pattern to serve a "side navigation". And, because it's part of documentation—which traditionally was viewed as "books"—it's called "Table of Contents". In addition to the "books" context, Documentation was also (at one point) a single page where hash links were used. We no longer do single page docs (because performance), and the design and the term has remained—hence the misalignment on terminology. One is wiki-based, and the other is book-based. I've seen both on the web.

So, we have 2 patterns to solve for, which is what I was referencing in my earlier comment.

1. Jump Links — which we could call "Table of Contents" (if we like), that would follow the expected hash link behavior (including scroll spy, etc.).
2. Documentation Table of Contents — which is what Krystal is referencing above in documentation, and would be a kind of "side nav" that links to separate pages in the "book" structure of documentation.

In my mind, these are 2 separate components. And, maybe we should name them specific to their use case to avoid confusion.

I hope that makes sense, anyway.

[bennypowers]

Point taken! thanks for bringing your case @KrystalMoore16. I don't see a contradiction here, though.

<rh-table-of-contents>
  <nav>
    ... any valid nav content here
  </nav>
</rh-table-of-contents>

We should support arbitrary (valid) content in the slotted <nav>. The one practical difference I'm imagining right now is scroll spy, which can be handled easily enough (i.e. simply don't scroll spy non-hash links)

To Mark's point of separate components, again I don't see why we have to go that far, we should be able to handle either case with one component.

The question is better asked - How uniform do we want our experience to be here, i.e. how many different visual representations do we want to support both from a design and software perspective.

[markcaron]

The style might be different, so...we could handle that with a variant style.

We might need to hash out (pun intended 😉) the acceptance criteria for both ToC variants, because I suspect there might be some difference in behaviors (e.g. stickiness).

[bennypowers]

if it can be done in css we don't need js for it, so e.g. a sticky toc could be one with the host or a css part set to

position: sticky;

[bennypowers]

See #22

[marionnegp]

In that issue, there's this note from Kelsey Swanson:

table of contents is way more useful in general especially for A11y.

Can anyone explain why this would be the case?