@fluid-topics/ftds-toc 0.0.0-stage → 2.2.28

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+## Install
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```shell
+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.
+
+```typescript
+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](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/examples/treeview-navigation/), without expand and collapse. Only one item is in the tab sequence (the current one, or the first).
+
+| Key                 | Action                                                   |
+|---------------------|----------------------------------------------------------|
+| `ArrowDown` / `Up`  | Moves the focus to the next / previous item              |
+| `ArrowRight`        | Moves the focus to the first child of the item           |
+| `ArrowLeft`         | Moves the focus to the parent of a child item            |
+| `Home` / `End`      | Moves the focus to the first / last item                 |
+| A letter            | Moves the focus to the next item starting with that letter |
+| `Space` / `Enter`   | Activates the link                                       |
+
+## 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.
+
+```typescript
+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()
+        }
+    }
+}
+```
+
+```typescript
+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>`
+```
+
+| Member                            | Description                                                                                               |
+|-----------------------------------|-----------------------------------------------------------------------------------------------------------|
+| `scrollContainer` (option)        | The element scrolling the sections.                                                                       |
+| `isVisible` (option)              | Returns whether the TOC is visible. The scroll is not tracked while it returns `false`. Defaults to always visible. |
+| `scrollOffset` (option)           | Distance in pixels from the top of the container at which a section is reached. Defaults to `24`.         |
+| `scrollSettleDelay` (option)      | Milliseconds without scroll event after which a scroll triggered by `scrollTo` is over. Defaults to `150`. |
+| `items`                           | The items to give to `ftds-toc`.                                                                          |
+| `current`                         | The value of the section in view, to give to `ftds-toc`.                                                  |
+| `scrollTo(value)`                 | Scrolls to the section, makes it current and keeps it current until the scroll ends.                      |
+| `refresh()`                       | Rescans the sections.                                                                                     |
+
+`ftds-page-layout` does this for you with its `withToc` property.

package/build/define.d.ts

@@ -0,0 +1 @@
+export {};

package/build/define.js

@@ -0,0 +1,3 @@
+import { customElements } from "@fluid-topics/ft-wc-utils";
+import definitions from "./definitions";
+customElements(definitions);

package/build/definitions.d.ts

@@ -0,0 +1,5 @@
+import { FtdsToc } from "./ftds-toc";
+declare const _default: {
+    "ftds-toc": typeof FtdsToc;
+};
+export default _default;

package/build/definitions.js

@@ -0,0 +1,4 @@
+import { FtdsToc } from "./ftds-toc";
+export default {
+    "ftds-toc": FtdsToc,
+};

package/build/ftds-toc.d.ts

@@ -0,0 +1,28 @@
+import { PropertyValues, TemplateResult } from "lit";
+import { ElementDefinitionsMap, FtLitElement } from "@fluid-topics/ft-wc-utils";
+import { FtdsTocItem, FtdsTocProperties } from "./ftds-toc.properties";
+export declare class TocItemSelectedEvent extends CustomEvent<FtdsTocItem> {
+    constructor(item: FtdsTocItem);
+}
+export declare class FtdsToc extends FtLitElement implements FtdsTocProperties {
+    static elementDefinitions: ElementDefinitionsMap;
+    static styles: import("lit").CSSResult;
+    items: FtdsTocItem[];
+    label: string;
+    current?: string;
+    private focusedValue?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected render(): TemplateResult<1>;
+    protected renderRootItem(item: FtdsTocItem): TemplateResult;
+    protected renderLink(item: FtdsTocItem, isChild: boolean, childrenActive: boolean, ownedGroupId?: string): TemplateResult;
+    protected willUpdate(props: PropertyValues): void;
+    private readonly onHashChange;
+    private get allItems();
+    private get tabbableValue();
+    private focusItem;
+    private onFocusOut;
+    private onKeydown;
+    private select;
+    private currentFromLocation;
+}

package/build/ftds-toc.js

@@ -0,0 +1,199 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing, } from "lit";
+import { property, state, } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { repeat } from "lit/directives/repeat.js";
+import { FtLitElement, jsonProperty, } from "@fluid-topics/ft-wc-utils";
+import { FtdsTypography, FtdsTypographyVariants, } from "@fluid-topics/ftds-typography";
+import { styles } from "./ftds-toc.styles";
+export class TocItemSelectedEvent extends CustomEvent {
+    constructor(item) {
+        super("item-selected", { detail: item, cancelable: true });
+    }
+}
+export class FtdsToc extends FtLitElement {
+    constructor() {
+        super(...arguments);
+        this.items = [];
+        this.label = "";
+        this.onHashChange = () => this.currentFromLocation();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        window.addEventListener("hashchange", this.onHashChange);
+    }
+    disconnectedCallback() {
+        window.removeEventListener("hashchange", this.onHashChange);
+        super.disconnectedCallback();
+    }
+    render() {
+        return html `
+            <nav aria-label="${ifDefined(this.label || undefined)}" @focusout=${this.onFocusOut}>
+                ${this.label ? html `
+                    <ftds-typography class="title" variant="${FtdsTypographyVariants.caption1semibold}">
+                        ${this.label}
+                    </ftds-typography>` : nothing}
+                <ul role="tree" aria-label="${ifDefined(this.label || undefined)}" @keydown=${this.onKeydown}>
+                    ${repeat(this.items, (item) => item.value, (item) => this.renderRootItem(item))}
+                </ul>
+            </nav>
+        `;
+    }
+    renderRootItem(item) {
+        var _a;
+        const children = (_a = item.children) !== null && _a !== void 0 ? _a : [];
+        const groupId = `group-${this.items.indexOf(item)}`;
+        const childrenActive = children.some((child) => child.value === this.current);
+        return html `
+            <li role="none">
+                ${this.renderLink(item, false, childrenActive, children.length > 0 ? groupId : undefined)}
+                ${children.length > 0 ? html `
+                    <ul role="group" id="${groupId}">
+                        ${repeat(children, (child) => child.value, (child) => html `
+                            <li role="none">${this.renderLink(child, true, false)}</li>`)}
+                    </ul>` : nothing}
+            </li>
+        `;
+    }
+    renderLink(item, isChild, childrenActive, ownedGroupId) {
+        const isCurrent = item.value === this.current;
+        const emphasized = isCurrent || childrenActive;
+        return html `
+            <a
+                part="${isChild ? "child-item" : "root-item"}"
+                class="${classMap({ child: isChild, "children-active": childrenActive })}"
+                role="treeitem"
+                href="${item.href}"
+                data-value="${item.value}"
+                tabindex="${item.value === this.tabbableValue ? 0 : -1}"
+                aria-owns="${ifDefined(ownedGroupId)}"
+                aria-current="${ifDefined(isCurrent ? "page" : undefined)}"
+                @click=${(e) => this.select(item, e)}
+            >
+                ${isChild ? html `<span class="bullet" aria-hidden="true">•</span>` : nothing}
+                <ftds-typography
+                    class="label"
+                    variant="${emphasized ? FtdsTypographyVariants.body1semibold : FtdsTypographyVariants.body1medium}"
+                >
+                    ${item.label}
+                </ftds-typography>
+            </a>
+        `;
+    }
+    willUpdate(props) {
+        super.willUpdate(props);
+        if (props.has("items") && this.current === undefined) {
+            this.currentFromLocation();
+        }
+    }
+    get allItems() {
+        return this.items.flatMap((item) => { var _a; return [item, ...((_a = item.children) !== null && _a !== void 0 ? _a : [])]; });
+    }
+    get tabbableValue() {
+        var _a;
+        const values = this.allItems.map((item) => item.value);
+        return (_a = [this.focusedValue, this.current].find((v) => v !== undefined && values.includes(v))) !== null && _a !== void 0 ? _a : values[0];
+    }
+    focusItem(item) {
+        var _a, _b;
+        if (item) {
+            this.focusedValue = item.value;
+            (_b = (_a = this.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector(`a[data-value="${item.value}"]`)) === null || _b === void 0 ? void 0 : _b.focus();
+        }
+    }
+    onFocusOut(e) {
+        if (!this.shadowRoot.contains(e.relatedTarget)) {
+            this.focusedValue = undefined;
+        }
+    }
+    onKeydown(e) {
+        var _a;
+        if (e.ctrlKey || e.altKey || e.metaKey) {
+            return;
+        }
+        const target = e.target.closest("a[data-value]");
+        const items = this.allItems;
+        const index = items.findIndex((item) => item.value === (target === null || target === void 0 ? void 0 : target.dataset.value));
+        if (index < 0) {
+            return;
+        }
+        const item = items[index];
+        const parent = this.items.find((root) => { var _a; return (_a = root.children) === null || _a === void 0 ? void 0 : _a.includes(item); });
+        let handled = true;
+        switch (e.key) {
+            case " ":
+                target.click();
+                break;
+            case "ArrowDown":
+                this.focusItem(items[index + 1]);
+                break;
+            case "ArrowUp":
+                this.focusItem(items[index - 1]);
+                break;
+            case "Home":
+                this.focusItem(items[0]);
+                break;
+            case "End":
+                this.focusItem(items[items.length - 1]);
+                break;
+            case "ArrowRight":
+                this.focusItem((_a = item.children) === null || _a === void 0 ? void 0 : _a[0]);
+                break;
+            case "ArrowLeft":
+                this.focusItem(parent);
+                break;
+            default:
+                if (e.key.length === 1 && /\p{L}/u.test(e.key)) {
+                    const char = e.key.toLowerCase();
+                    const ordered = [...items.slice(index + 1), ...items.slice(0, index)];
+                    this.focusItem(ordered.find((i) => i.label.trim().toLowerCase().startsWith(char)));
+                }
+                else {
+                    handled = false;
+                }
+        }
+        if (handled) {
+            e.preventDefault();
+            e.stopPropagation();
+        }
+    }
+    select(item, click) {
+        this.current = item.value;
+        if (!this.dispatchEvent(new TocItemSelectedEvent(item))) {
+            click.preventDefault();
+        }
+    }
+    currentFromLocation() {
+        const hash = window.location.hash;
+        if (!hash) {
+            return;
+        }
+        const all = this.items.flatMap((item) => { var _a; return [item, ...((_a = item.children) !== null && _a !== void 0 ? _a : [])]; });
+        const match = all.find((item) => item.href === hash || item.href.endsWith(hash));
+        if (match) {
+            this.current = match.value;
+        }
+    }
+}
+FtdsToc.elementDefinitions = {
+    "ftds-typography": FtdsTypography,
+};
+FtdsToc.styles = styles;
+__decorate([
+    jsonProperty([])
+], FtdsToc.prototype, "items", void 0);
+__decorate([
+    property()
+], FtdsToc.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], FtdsToc.prototype, "current", void 0);
+__decorate([
+    state()
+], FtdsToc.prototype, "focusedValue", void 0);