@fluid-topics/ftds-toc

Install

npm install @fluid-topics/ftds-toc
yarn add @fluid-topics/ftds-toc

Usage

The design system table of contents (TOC). It is a navigation component with two levels (section and sub-section) that links to anchors of a page.

The link matching the current page location is flagged with aria-current="page". It is updated on click and on hashchange, or can be forced with the current property.

It is sticky, and hidden on screens up to 1440px wide.

import { html } from "lit"
import "@fluid-topics/ftds-toc"

function render() {
    return html`
        <ftds-toc
            label="Content"
            .items=${ [
                { value: "general", label: "General", href: "#general" },
                {
                    value: "provider",
                    label: "Provider",
                    href: "#provider",
                    children: [
                        { value: "settings", label: "Settings", href: "#settings" },
                    ],
                },
            ] }
        ></ftds-toc>`
}

Keyboard navigation

It follows the APG treeview navigation pattern, without expand and collapse. Only one item is in the tab sequence (the current one, or the first).

Events

item-selected (TocItemSelectedEvent, detail is the selected item) is dispatched when an item is clicked or activated with the keyboard. It is cancelable: calling preventDefault() on it cancels the native navigation of the link, so the host can scroll to the section itself.

Building the items from the page

Instead of writing the items by hand, FtTocController (from @fluid-topics/ft-wc-utils) can build them from the sections of a host component and track the section currently in view.

Mark each section of the host's light DOM with data-toc-label. Add data-toc-level="1" to make a sub-section of the previous section. An element without an id is given one. The sections are rescanned whenever the host's light DOM changes.

import { html } from "lit"
import { FtLitElement, FtTocController } from "@fluid-topics/ft-wc-utils"
import { TocItemSelectedEvent } from "@fluid-topics/ftds-toc"
import "@fluid-topics/ftds-toc"

class MyPage extends FtLitElement {
    private readonly toc = new FtTocController(this, {
        scrollContainer: () => this.renderRoot.querySelector("main"),
    })

    protected render() {
        return html`
            <ftds-toc label="Content"
                      .items=${ this.toc.items }
                      .current=${ this.toc.current }
                      @item-selected=${ this.onItemSelected }>
            </ftds-toc>
            <main>
                <slot></slot>
            </main>`
    }

    private onItemSelected(e: TocItemSelectedEvent) {
        if (this.toc.scrollTo(e.detail.value)) {
            e.preventDefault()
        }
    }
}

html`
    <my-page>
        <section data-toc-label="General">...</section>
        <section data-toc-label="Provider">...</section>
        <section data-toc-label="Settings" data-toc-level="1">...</section>
    </my-page>`

ftds-page-layout does this for you with its withToc property.