@0001-labs/design-system-1 0.3.0-alpha.27 → 0.3.0

package/DS1/3-unit/ds-carousel.ts

@@ -9,7 +9,7 @@
 import { LitElement, html, nothing, unsafeCSS, type PropertyValues } from "lit";
 import { getText } from "../0-face/i18n";
 import { define } from "../0-face/define";
-import { COPY, autoplayInterval, bleedOf, driveCarousel, nearestSlide, prefersReducedMotion, scrollToSlide, type CarouselDrive } from "../0-face/carousel";
+import { COPY, autoplayInterval, bleedOf, dragTrack, driveCarousel, nearestSlide, prefersReducedMotion, scrollToSlide, type CarouselDrive } from "../0-face/carousel";
 import "../2-core/ds-icon";
 import "../2-core/ds-progress";
 import type { ProgressSelectDetail } from "../2-core/ds-progress";
@@ -113,6 +113,8 @@ export class Carousel extends LitElement {
   declare paused: boolean;
   /** The strip's drive: the bleed's measures, the loop's copies and autoplay. */
   private drive: CarouselDrive | null = null;
+  /** Stops the strip's drag (dragTrack); started with the track, again when the element comes back to a page. */
+  private undrag: (() => void) | undefined;
 
   /** Attributes this element wrote, so what the page wrote is left alone. */
   private readonly own = new Map<Element, Set<string>>();
@@ -165,8 +167,14 @@ export class Carousel extends LitElement {
     return Math.max(0, Math.min(this.count - 1, current));
   }
 
+  private startDrag() {
+    const track = this.track;
+    if (track && !this.undrag) this.undrag = dragTrack(track, () => { if (!this.loop) this.move(nearestSlide(track, this.slides, this.index)); });
+  }
+
   connectedCallback() {
     super.connectedCallback();
+    if (this.hasUpdated) this.startDrag();
     window.addEventListener("language-changed", this.relabel);
     window.addEventListener("translations-loaded", this.relabel);
   }
@@ -178,6 +186,8 @@ export class Carousel extends LitElement {
     clearTimeout(this.settle);
     this.drive?.stop();
     this.drive = null;
+    this.undrag?.();
+    this.undrag = undefined;
     super.disconnectedCallback();
   }
 
@@ -225,6 +235,8 @@ export class Carousel extends LitElement {
   protected firstUpdated() {
     // The strip's drive starts once, from the options the element was given.
     const track = this.track;
+    // A mouse drags the strip, and a press that ends a drag or a swipe chooses nothing (dragTrack).
+    this.startDrag();
     const bleed = bleedOf(this.bleed);
     if (track && (bleed !== "none" || this.loop || this.every > 0)) {
       this.drive = driveCarousel(this, track, this, { bleed, loop: this.loop, autoplay: this.every });

package/DS1/3-unit/ds-context.ts

@@ -2,7 +2,7 @@ import { unsafeCSS, type PropertyValues } from "lit";
 import { define } from "../0-face/define";
 import menuStyles from "./styles/ds-menu.css?inline";
 import styles from "./styles/ds-context.css?inline";
-import { Menu, type MenuCloseReason } from "./ds-menu";
+import { Menu, type MenuAnchor, type MenuCloseReason } from "./ds-menu";
 
 const ROW = '[role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"]';
 /** A refused change shows on its row this long, as Ezo shows it. */
@@ -25,20 +25,31 @@ const REFUSED = 1400;
  * says `data-keep-open` or its click was prevented. `pending` holds every row
  * and the menu open while an answer is awaited; `refuse(row)` shows a refused
  * change on its row.
+ *
+ * `bar` lays the same rows side by side, the context bar over what is
+ * selected: one row high, the cells a pixel apart and groups two, a cell
+ * holding only an icon one square, a cell with words 4px in. It stands half a
+ * square above its anchor (below when there is no room), its start at the
+ * anchor's, and opens without taking the focus, so the writing keeps the
+ * caret: `openOver(rect)`. ← and → move along it.
  */
 export class Context extends Menu {
   static properties = {
     ...Menu.properties,
     pending: { type: Boolean, reflect: true },
+    bar: { type: Boolean, reflect: true },
   };
   static styles = [unsafeCSS(menuStyles), unsafeCSS(styles)];
   /** Hold every row and keep the menu open while a chosen change is awaited. */
   declare pending: boolean;
+  /** The context bar: the rows side by side, over what is selected. */
+  declare bar: boolean;
   private quietObserver = new MutationObserver(() => this.quietSeparators());
 
   constructor() {
     super();
     this.pending = false;
+    this.bar = false;
     this.triggerMode = "context";
     this.floating = true;
     this.closesOnChoice = true;
@@ -57,11 +68,23 @@ export class Context extends Menu {
     // Always a context menu, always floating.
     this.triggerMode = "context";
     this.floating = true;
-    this.toggleAttribute("data-ds-hug", true);
+    // A menu hugs its words in whole squares; a bar is as long as its cells.
+    this.toggleAttribute("data-ds-hug", !this.bar);
+    if (this.bar) {
+      this.setAttribute("aria-orientation", "horizontal");
+      this.placement = "top";
+      // The writing under a bar keeps the caret; the page moves the focus in with a key of its own.
+      this.focusOnOpen = false;
+    } else if (changed.has("bar")) {
+      this.removeAttribute("aria-orientation");
+      this.placement = "bottom";
+      this.focusOnOpen = true;
+    }
     super.willUpdate(changed);
   }
   updated() {
     super.updated();
+    this.markIcons();
     // Pending holds the rows that were free, and frees only those again.
     for (const row of this.querySelectorAll<HTMLElement>(ROW)) {
       if (this.pending && row.getAttribute("aria-disabled") !== "true") { row.setAttribute("aria-disabled", "true"); row.dataset.dsContextHeld = ""; }
@@ -84,8 +107,23 @@ export class Context extends Menu {
     setTimeout(() => row.removeAttribute("data-ds-refused"), REFUSED);
   }
 
+  /** Open the bar over what is selected (a rectangle, or an element), keeping the focus where it is. */
+  openOver(anchor: MenuAnchor) {
+    this.anchor = anchor;
+    this.open = true;
+  }
+
+  /** In a bar, a cell holding only an icon is one square. */
+  private markIcons() {
+    for (const row of this.querySelectorAll<HTMLElement>(ROW)) {
+      if (row.closest("ds-context") !== this) continue;
+      row.toggleAttribute("data-ds-context-icon", this.bar && !(row.textContent ?? "").trim() && !!row.querySelector("ds-icon, svg, img"));
+    }
+  }
+
   /** Groups without rows leave no gap: a separator first, last or after another is quiet. */
   private quietSeparators() {
+    this.markIcons();
     let previousWasGap = true;
     const children = [...this.children] as HTMLElement[];
     const visible = children.filter(child => !child.hidden);

package/DS1/3-unit/ds-form.ts

@@ -12,6 +12,9 @@ export interface FormValidationResult {
   errors: { [key: string]: string };
 }
 
+/** Inputs Enter does not submit from: it presses or toggles them instead. */
+const IMPLICIT_SUBMIT_SKIPS = new Set(["button", "submit", "reset", "image", "checkbox", "radio", "file", "color", "range"]);
+
 export class Form extends LitElement {
   static properties = {
     action: { type: String },
@@ -275,17 +278,50 @@ export class Form extends LitElement {
     void this.submit();
   }
 
-  private _handleKeydown(e: KeyboardEvent): void {
-    if (e.key === "Enter" && !e.shiftKey) {
-      const target = e.target as HTMLElement;
-      // Don't submit if in a textarea
-      if (target.tagName.toLowerCase() !== "textarea") {
-        e.preventDefault();
-        void this.submit();
-      }
-    }
+  connectedCallback(): void {
+    super.connectedCallback();
+    this.addEventListener("click", this._handleButtonClick);
+    this.addEventListener("keydown", this._handleKeydown);
   }
 
+  disconnectedCallback(): void {
+    this.removeEventListener("click", this._handleButtonClick);
+    this.removeEventListener("keydown", this._handleKeydown);
+    super.disconnectedCallback();
+  }
+
+  /**
+   * The form is drawn in this element's shadow, so a submit or reset button
+   * put inside it belongs to no form of its own. Its click does what it would
+   * in a form: a native button (bare or in `ds-button control="slotted"`), or
+   * `<ds-button type="submit">`. A button in a real <form> is left to that form.
+   */
+  private _handleButtonClick = (e: Event): void => {
+    if (e.defaultPrevented) return;
+    const control = (e.target as Element | null)?.closest?.("button, input, ds-button[type]");
+    if (!control || !this.contains(control)) return;
+    let type: string | null;
+    if (control instanceof HTMLButtonElement || control instanceof HTMLInputElement) {
+      if (control.form || control.disabled) return;
+      type = control.type;
+    } else {
+      if (control.hasAttribute("disabled") || control.hasAttribute("href")) return;
+      type = control.getAttribute("type");
+    }
+    if (type === "submit") void this.submit();
+    else if (type === "reset") this.reset();
+  };
+
+  private _handleKeydown = (e: KeyboardEvent): void => {
+    if (e.key !== "Enter" || e.shiftKey || e.defaultPrevented) return;
+    // Enter submits from a field, as in a form: on a button it presses that
+    // button, and in a textarea (a multiline ds-input's too) it starts a line.
+    const origin = e.composedPath()[0];
+    if (!(origin instanceof HTMLInputElement) || origin.form || IMPLICIT_SUBMIT_SKIPS.has(origin.type)) return;
+    e.preventDefault();
+    void this.submit();
+  };
+
   render() {
     return html`
       <form
@@ -295,7 +331,6 @@ export class Form extends LitElement {
         ?novalidate=${this.novalidate}
         autocomplete=${this.autocomplete}
         @submit=${this._handleSubmit}
-        @keydown=${this._handleKeydown}
       >
         <slot></slot>
       </form>

package/DS1/3-unit/ds-list.ts

@@ -1,6 +1,7 @@
-import { LitElement, html, unsafeCSS } from "lit";
+import { LitElement, html, nothing, unsafeCSS } from "lit";
 import styles from "./styles/ds-list.css?inline";
 import { define } from "../0-face/define";
+import { CutFades } from "../0-face/cut-fade";
 
 /** Children that are never items of the list. */
 const NOT_ITEMS = new Set(["template", "script", "style", "slot"]);
@@ -15,21 +16,34 @@ const CONTROLS = new Set(["a", "button", "input", "select", "textarea", "summary
  * A link, button or other control directly inside keeps its own role: wrap it
  * in a row (or another element) to make it an item.
  *
+ * `heading` names the group on the square above its rows (a day, a month),
+ * the words in the muted ink: the list takes it as its accessible name, so
+ * the drawn words are hidden from assistive technology and a page that
+ * writes its own `aria-label` keeps it.
+ *
  * @element ds-list
  * @attr columns - Lay the items out in this many equal columns.
+ * @attr heading - The group's name, drawn on the square above the rows and given to the list as its name.
+ * @csspart heading - The heading's line.
  */
 export class List extends LitElement {
   static properties = {
     columns: { type: Number, reflect: true },
+    heading: { type: String, reflect: true },
   };
 
   declare columns: number | undefined;
+  declare heading: string | undefined;
 
   static styles = unsafeCSS(styles);
+  /** Words cut short fade over their last square, never an ellipsis: marks them `data-cut="end"` while they do not fit. */
+  protected readonly cuts = new CutFades(this, { selector: ".heading" });
 
   /** The items this element gave a role, so roles the page wrote are left alone. */
   private ownItems = new Set<Element>();
   private ownRole = false;
+  /** Whether the list's `aria-label` is its heading, so the page's own name is never replaced. */
+  private ownLabel = false;
 
   connectedCallback(): void {
     super.connectedCallback();
@@ -64,13 +78,27 @@ export class List extends LitElement {
     this.syncItems();
   }
 
-  updated(): void {
+  updated(changed: Map<string, unknown>): void {
     if (typeof this.columns === "number" && Number.isInteger(this.columns) && this.columns > 0) this.style.setProperty("--ds-list-columns", String(this.columns));
     else this.style.removeProperty("--ds-list-columns");
+    if (changed.has("heading")) this.nameByHeading();
+  }
+
+  /** The heading names the list, unless the page wrote a name of its own. */
+  private nameByHeading() {
+    const heading = this.heading?.trim();
+    if (heading && (this.ownLabel || !this.hasAttribute("aria-label"))) {
+      this.setAttribute("aria-label", heading);
+      this.ownLabel = true;
+    } else if (!heading && this.ownLabel) {
+      this.removeAttribute("aria-label");
+      this.ownLabel = false;
+    }
   }
 
   render() {
-    return html`<slot @slotchange=${this.syncItems}></slot>`;
+    const heading = this.heading?.trim();
+    return html`${heading ? html`<span class="heading" part="heading" aria-hidden="true">${heading}</span>` : nothing}<slot @slotchange=${this.syncItems}></slot>`;
   }
 }
 

package/DS1/3-unit/ds-matrix.ts

@@ -7,6 +7,7 @@
 
 import { LitElement, html, nothing, unsafeCSS, type PropertyValues } from "lit";
 import { define } from "../0-face/define";
+import { CutFades } from "../0-face/cut-fade";
 import { getText } from "../0-face/i18n";
 import metrics from "../1-root/component-metrics.css?inline";
 import styles from "./styles/ds-matrix.css?inline";
@@ -107,6 +108,8 @@ export class Matrix extends LitElement {
   };
 
   static styles = [unsafeCSS(metrics), unsafeCSS(styles)];
+  /** Words cut short fade over their last square, never an ellipsis: marks them `data-cut="end"` while they do not fit. */
+  protected readonly cuts = new CutFades(this, { selector: ".name" });
 
   declare rows: MatrixAxis[];
   declare columns: MatrixAxis[];

package/DS1/3-unit/ds-menu.ts

@@ -222,7 +222,8 @@ export class Menu extends LitElement {
   }
   private onTriggerClick = (event: MouseEvent) => {
     if (this.triggerMode === "context" || this.triggerMode === "manual" || event.defaultPrevented) return;
-    if (this.hover && this.trigger?.matches("a[href]")) return;
+    // A hover menu's trigger that is a link (`a href`, `ds-button href`) follows its link when pressed.
+    if (this.hover && this.trigger?.matches("a[href], ds-button[href]")) return;
     this.focusOnOpen = true;
     this.openingEdge = "first";
     this.toggleFromTrigger(this.triggerMode === "submenu" || !this.open);
@@ -449,12 +450,15 @@ export class Menu extends LitElement {
     const items = this.items(true); if (!items.some(item => this.enabled(item))) return;
     const current = external ? items.findIndex(item => item.id === this.activeId) : items.findIndex(item => event.composedPath().includes(item));
     const columns = Math.max(1, Math.floor(this.columns || 1));
+    // A menu laid out in one line (Context's bar) steps sideways, in the reading direction.
+    const across = this.getAttribute("aria-orientation") === "horizontal";
+    const forward = this.ownerDocument.defaultView?.getComputedStyle(this).direction === "rtl" ? -1 : 1;
     let next: number;
     switch (event.key) {
-      case "ArrowDown": next = columns > 1 ? this.gridStep(items, current, columns, 1) : this.step(items, current, 1, 1); break;
-      case "ArrowUp": next = columns > 1 ? this.gridStep(items, current, columns, -1) : this.step(items, current, 1, -1); break;
-      case "ArrowRight": if (columns === 1 || external) return; next = this.step(items, current, 1, 1); break;
-      case "ArrowLeft": if (columns === 1 || external) return; next = this.step(items, current, 1, -1); break;
+      case "ArrowDown": if (across) return; next = columns > 1 ? this.gridStep(items, current, columns, 1) : this.step(items, current, 1, 1); break;
+      case "ArrowUp": if (across) return; next = columns > 1 ? this.gridStep(items, current, columns, -1) : this.step(items, current, 1, -1); break;
+      case "ArrowRight": if (across) { next = this.step(items, current, 1, forward); break; } if (columns === 1 || external) return; next = this.step(items, current, 1, 1); break;
+      case "ArrowLeft": if (across) { next = this.step(items, current, 1, -forward); break; } if (columns === 1 || external) return; next = this.step(items, current, 1, -1); break;
       case "Home": if (external) return; next = items.findIndex(item => this.enabled(item)); break;
       case "End": if (external) return; next = this.lastEnabled(items); break;
       case "Enter":

package/DS1/3-unit/ds-row.ts

@@ -2,6 +2,7 @@ import { LitElement, html, unsafeCSS } from "lit";
 import { ifDefined } from "lit/directives/if-defined.js";
 import styles from "./styles/ds-row.css?inline";
 import { define } from "../0-face/define";
+import { CutFades } from "../0-face/cut-fade";
 
 /** The values `aria-current` takes besides `page`. */
 const CURRENT = new Set(["page", "step", "location", "date", "time", "true"]);
@@ -30,6 +31,14 @@ const CURRENT = new Set(["page", "step", "location", "date", "time", "true"]);
  * @attr label - The accessible name, when the row's words do not say it.
  * @attr target - Where a link opens (`_blank`, …).
  * @attr rel - The link's relationship (`noopener`, …).
+ * A record's row puts its parts in classes: `ds-row__name` for the words,
+ * which hug and give way first, and `ds-row__value` for the figure or date at
+ * the row's end; a 16px picture (an avatar tile, a large icon) before the
+ * name stands on its square with the row's gap putting the words on the next.
+ * The element measures each name and marks it `data-cut="end"` while its
+ * words do not fit, so the stylesheet fades them over the last square, never
+ * an ellipsis; a `ds-text literal` name fades the same way.
+ *
  * @slot - The row's content, inside its press target.
  * @slot end - Controls of their own after the content, outside the press target.
  * @fires ds-row-press - `{ href }`: the row was pressed. Cancel it to route a link yourself; a modified click on a link is left to the browser.
@@ -88,6 +97,12 @@ export class Row extends LitElement {
 
   static styles = unsafeCSS(styles);
 
+  /** Marks each `.ds-row__name` `data-cut="end"` while its words are wider than its box, measured again as they resize or change. */
+  protected readonly cuts = new CutFades(this, { targets: () => this.querySelectorAll(":scope > .ds-row__name"), text: true });
+
+  /** Measures the names again, as when the slotted content changes. */
+  private measureNames = () => this.cuts.measure();
+
   /** The `aria-current` value, or none. */
   private get currentValue(): string | undefined {
     const value = this.current;
@@ -111,10 +126,10 @@ export class Row extends LitElement {
   }
 
   render() {
-    if (!this.href && !this.interactive) return html`<slot></slot>`;
+    if (!this.href && !this.interactive) return html`<slot @slotchange=${this.measureNames}></slot>`;
     const current = this.currentValue;
     const label = this.label || undefined;
-    const content = html`<slot></slot>`;
+    const content = html`<slot @slotchange=${this.measureNames}></slot>`;
     const target = this.href
       ? this.disabled
         ? html`<a class="target" part="target" role="link" aria-disabled="true" aria-label=${ifDefined(label)}>${content}</a>`

package/DS1/3-unit/ds-select.ts

@@ -1,7 +1,7 @@
 import { html, nothing, unsafeCSS, type PropertyValues, type TemplateResult } from "lit";
 import { define } from "../0-face/define";
 import { shortcutLabel } from "../0-face/keys";
-import down from "../x-icon/down.svg?raw";
+import down from "../x-icon/chevron-down.svg?raw";
 import check from "../x-icon/check.svg?raw";
 import menuStyles from "./styles/ds-menu.css?inline";
 import styles from "./styles/ds-select.css?inline";

package/DS1/3-unit/ds-sidebar.ts

@@ -2,6 +2,7 @@ import { LitElement, html, nothing, unsafeCSS } from "lit";
 import { repeat } from "lit/directives/repeat.js";
 import { ifDefined } from "lit/directives/if-defined.js";
 import { define } from "../0-face/define";
+import { CutFades } from "../0-face/cut-fade";
 import { treeStep } from "../0-face/sidebar";
 import "../0-face/tooltips";
 import "../2-core/ds-button";
@@ -28,6 +29,8 @@ export interface SidebarItem {
   disabled?: boolean;
   /** Small muted words at the row's end: a count, a size. */
   meta?: string;
+  /** Small muted words just after the label, read with it: a version. */
+  detail?: string;
   /** Optional application content following this navigation row. */
   afterSlot?: string;
   action?: { id: string; label: string; icon?: string; disabled?: boolean };
@@ -52,9 +55,15 @@ export interface SidebarMoveDetail { id: string; targetId: string; position: "be
  * `0-face/sidebar.ts`). The application keeps the rows: it passes the
  * visible ones in `items`, in order, and answers the events.
  *
+ * With `narrow`, the navigation is eight squares wide and each row hugs its
+ * words: the pointer's and the current row's fill wraps the label, its meta
+ * and its disclosure, 4px either side, instead of running across the column.
+ * For an application's few places beside its work.
+ *
  * @element ds-sidebar
  * @attr label - The navigation's or the tree's accessible name.
  * @attr tree - A tree of nested things instead of navigation.
+ * @attr narrow - Navigation eight squares wide, each row hugging its words.
  * @fires sidebar-toggle - `{ id, expanded }`: a row asks to open or close.
  * @fires sidebar-activate - `{ id }`: a row was pressed (navigation), or Enter or a double click opened one (a tree).
  * @fires sidebar-select - `{ id }`: a click, Space or Enter chose a tree row.
@@ -69,6 +78,7 @@ export class Sidebar extends LitElement {
     collapseIcon: { type: String, attribute: "collapse-icon" },
     disclosurePosition: { type: String, attribute: "disclosure-position", reflect: true },
     tree: { type: Boolean, reflect: true },
+    narrow: { type: Boolean, reflect: true },
     reorderable: { type: Boolean, reflect: true },
   };
   declare items: SidebarItem[];
@@ -80,9 +90,13 @@ export class Sidebar extends LitElement {
   /** Place navigation disclosures before the label; default preserves trailing disclosures. */
   declare disclosurePosition?: "start" | "end";
   declare tree: boolean;
+  /** Eight squares wide, each row hugging its words (navigation only). */
+  declare narrow: boolean;
   declare reorderable: boolean;
   private dragId?: string;
   static styles = unsafeCSS(styles);
+  /** Words cut short fade over their last square, never an ellipsis: marks them `data-cut="end"` while they do not fit. */
+  protected readonly cuts = new CutFades(this, { selector: ".name, .tree .label" });
 
   /** In a tree, the row that holds the Tab stop. */
   private focusId?: string;
@@ -93,6 +107,7 @@ export class Sidebar extends LitElement {
     this.label = "Navigation";
     this.empty = "No items";
     this.tree = false;
+    this.narrow = false;
     this.reorderable = false;
   }
 
@@ -233,7 +248,7 @@ export class Sidebar extends LitElement {
           @focus=${() => { this.focusId = item.id; }}>
           <span class="disclosure" aria-hidden="true">${item.expanded === undefined ? nothing : html`<ds-icon type="right" ?data-open=${item.expanded}></ds-icon>`}</span>
           ${item.icon ? html`<span class="icon" aria-hidden="true"><ds-icon type=${item.icon}></ds-icon></span>` : nothing}
-          <span class="label">${item.label}</span>
+          <span class="label">${item.label}${item.detail ? html`<span class="detail">${item.detail}</span>` : nothing}</span>
           ${item.meta ? html`<span class="meta">${item.meta}</span>` : nothing}
         </div>`;
       })}
@@ -345,12 +360,12 @@ export class Sidebar extends LitElement {
             ${item.href && !item.disabled ? html`
               <a href=${item.href} draggable=${ifDefined(this.reorderable ? "false" : undefined)} data-item=${item.id} aria-current=${ifDefined(item.current ? "page" : undefined)}
                 @click=${(event: MouseEvent) => this.activate(event, item)}
-                @keydown=${(event: KeyboardEvent) => this.navigate(event, item)}><span class="name">${item.icon ? html`<ds-icon type=${item.icon} aria-hidden="true"></ds-icon>` : nothing}${item.label}</span></a>` : html`
+                @keydown=${(event: KeyboardEvent) => this.navigate(event, item)}><span class="name">${item.icon ? html`<ds-icon type=${item.icon} aria-hidden="true"></ds-icon>` : nothing}${item.label}${item.detail ? html`<span class="detail">${item.detail}</span>` : nothing}</span></a>` : html`
               <button type="button" data-item=${item.id} ?disabled=${item.disabled}
                 aria-expanded=${ifDefined(item.expanded === undefined ? undefined : String(item.expanded))}
                 aria-current=${ifDefined(item.current ? "page" : undefined)}
                 @click=${(event: MouseEvent) => this.activate(event, item)}
-                @keydown=${(event: KeyboardEvent) => this.navigate(event, item)}><span class="name">${item.icon ? html`<ds-icon type=${item.icon} aria-hidden="true"></ds-icon>` : nothing}${item.label}</span></button>`}
+                @keydown=${(event: KeyboardEvent) => this.navigate(event, item)}><span class="name">${item.icon ? html`<ds-icon type=${item.icon} aria-hidden="true"></ds-icon>` : nothing}${item.label}${item.detail ? html`<span class="detail">${item.detail}</span>` : nothing}</span></button>`}
           </ds-button>
           ${this.disclosurePosition !== "start" ? this.renderDisclosure(item) : nothing}
           <span class="spacer" aria-hidden="true"></span>

package/DS1/3-unit/ds-table-of-contents.ts

@@ -0,0 +1,166 @@
+import { LitElement, html, nothing, unsafeCSS } from 'lit';
+import { define } from '../0-face/define';
+import { CutFades } from '../0-face/cut-fade';
+import { getText } from '../0-face/i18n';
+import '../0-face/tooltips';
+import '../2-core/ds-text';
+import styles from './styles/ds-table-of-contents.css?inline';
+
+export interface TableOfContentsItem { href: string; label: string; depth?: number; }
+
+/** A page's section links. Placement belongs to the page, not this Unit.
+ * Supply items or slot native anchors with data-depth. Same-page links track
+ * their headings inside the actual scrolling container, including a shadow root.
+ * @element ds-table-of-contents
+ * @fires toc-change - { href }: the section in view changed.
+ */
+export class TableOfContents extends LitElement {
+  static properties = {
+    items: { attribute: false }, label: { type: String }, literal: { type: Boolean },
+    target: { attribute: false }, current: { state: true },
+  };
+  static styles = unsafeCSS(styles);
+  /** A cut label fades over its last square, never an ellipsis: marks it `data-cut="end"` while it does not fit. */
+  protected readonly cuts = new CutFades(this, { selector: 'a', targets: () => this.querySelectorAll(':scope > a'), text: true });
+  declare items: TableOfContentsItem[];
+  declare label: string;
+  declare literal: boolean;
+  /** Optional content scope, especially when the contents stand inside another component's shadow. */
+  declare target?: HTMLElement;
+  declare current: string;
+  private links: HTMLAnchorElement[] = [];
+  private sections: { link: HTMLAnchorElement; heading: HTMLElement }[] = [];
+  private scroller: HTMLElement | null = null;
+  private frame = 0;
+  private observer?: MutationObserver;
+  private resize?: ResizeObserver;
+  private readonly relabel = () => this.requestUpdate();
+  constructor() {
+    super(); this.items = []; this.label = 'Contents'; this.literal = false; this.current = '';
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', this.follow);
+    window.addEventListener('scroll', this.schedule, { passive: true });
+    window.addEventListener('resize', this.schedule, { passive: true });
+    window.addEventListener('hashchange', this.schedule);
+    window.addEventListener('language-changed', this.relabel);
+    window.addEventListener('translations-loaded', this.relabel);
+    this.observer = new MutationObserver(() => this.refresh());
+    this.observer.observe(this, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ['href', 'data-depth'] });
+    if (typeof ResizeObserver !== 'undefined') this.resize = new ResizeObserver(this.schedule);
+    void this.updateComplete.then(() => { if (this.isConnected) this.refresh(); });
+    void this.ownerDocument.fonts?.ready.then(this.schedule);
+  }
+  disconnectedCallback() {
+    this.removeEventListener('click', this.follow);
+    window.removeEventListener('scroll', this.schedule);
+    this.scroller?.removeEventListener('scroll', this.schedule);
+    window.removeEventListener('resize', this.schedule);
+    window.removeEventListener('hashchange', this.schedule);
+    window.removeEventListener('language-changed', this.relabel);
+    window.removeEventListener('translations-loaded', this.relabel);
+    this.observer?.disconnect(); this.resize?.disconnect(); cancelAnimationFrame(this.frame);
+    super.disconnectedCallback();
+  }
+  protected updated(changed: Map<PropertyKey, unknown>) {
+    if (changed.has('items') || changed.has('target')) this.refresh();
+  }
+  private destination(link: HTMLAnchorElement): HTMLElement | null {
+    try {
+      const url = new URL(link.href, this.ownerDocument.baseURI);
+      const page = new URL(this.ownerDocument.URL);
+      if (!url.hash || url.origin !== page.origin || url.pathname !== page.pathname || url.search !== page.search) return null;
+      const id = decodeURIComponent(url.hash.slice(1));
+      if (this.target) return [...this.target.querySelectorAll<HTMLElement>('[id]')].find(node => node.id === id) ?? null;
+      const root = this.getRootNode() as Document | ShadowRoot;
+      return root.getElementById(id) ?? null;
+    } catch { return null; }
+  }
+  /** Read links and targets again after replacing content or moving the Unit. */
+  refresh() {
+    if (!this.isConnected) return;
+    this.links = this.items.length ? [...this.renderRoot.querySelectorAll<HTMLAnchorElement>('a')]
+      : [...this.querySelectorAll<HTMLAnchorElement>('a[href]')];
+    this.sections = this.links.flatMap(link => {
+      const heading = this.destination(link);
+      return heading ? [{ link, heading }] : [];
+    });
+    for (const link of this.links) {
+      const depth = Number(link.dataset.depth ?? 0);
+      link.style.setProperty('--toc-depth', String(Number.isFinite(depth) ? Math.max(0, depth) : 0));
+    }
+    this.scroller?.removeEventListener('scroll', this.schedule);
+    this.scroller = null;
+    const parentOf = (node: Element): HTMLElement | null => node.parentElement ?? (node.getRootNode() instanceof ShadowRoot ? (node.getRootNode() as ShadowRoot).host as HTMLElement : null);
+    for (let parent = this.sections[0] ? parentOf(this.sections[0].heading) : null; parent; parent = parentOf(parent)) {
+      if (/(auto|scroll)/.test(getComputedStyle(parent).overflowY)) { this.scroller = parent; break; }
+    }
+    this.scroller?.addEventListener('scroll', this.schedule, { passive: true });
+    this.resize?.disconnect();
+    this.resize?.observe(this);
+    if (this.target) this.resize?.observe(this.target);
+    if (this.scroller) this.resize?.observe(this.scroller);
+    this.schedule();
+  }
+  private schedule = () => {
+    if (!this.isConnected) return;
+    cancelAnimationFrame(this.frame);
+    this.frame = requestAnimationFrame(() => this.track());
+  };
+  private track() {
+    for (const link of this.links) {
+      if (link.scrollWidth > link.clientWidth) link.setAttribute('data-tooltip', link.textContent?.trim() ?? '');
+      else link.removeAttribute('data-tooltip');
+    }
+    if (!this.sections.length) { this.mark(''); return; }
+    const box = this.scroller?.getBoundingClientRect();
+    const top = box?.top ?? 0;
+    const height = this.scroller?.clientHeight ?? window.innerHeight;
+    const scrollTop = this.scroller?.scrollTop ?? window.scrollY;
+    const scrollHeight = this.scroller?.scrollHeight ?? this.ownerDocument.documentElement.scrollHeight;
+    const end = scrollTop > 0 && scrollTop + height >= scrollHeight - 1;
+    // The rendered row resolves nested scale and calc() tokens to actual pixels.
+    const unit = this.renderRoot.querySelector<HTMLElement>('.title')?.getBoundingClientRect().height || 20;
+    const line = top + (end ? height : unit);
+    let current = this.sections[0].link.getAttribute('href')!;
+    for (const { link, heading } of this.sections) {
+      if (heading.getBoundingClientRect().top <= line) current = link.getAttribute('href')!;
+      else break;
+    }
+    this.mark(current);
+  }
+  private mark(href: string) {
+    for (const link of this.links) {
+      if (link.getAttribute('href') === href) link.setAttribute('aria-current', 'location');
+      else link.removeAttribute('aria-current');
+    }
+    if (this.current === href) return;
+    this.current = href;
+    this.dispatchEvent(new CustomEvent('toc-change', { detail: { href }, bubbles: true, composed: true }));
+  }
+  private follow = (event: MouseEvent) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
+    const link = event.composedPath().find((node): node is HTMLAnchorElement => node instanceof HTMLAnchorElement);
+    if (!link || !this.links.includes(link) || link.target === '_blank' || link.hasAttribute('download')) return;
+    const heading = this.destination(link); if (!heading) return;
+    event.preventDefault();
+    heading.scrollIntoView({ block: 'start', behavior: 'auto' });
+    if (!heading.hasAttribute('tabindex')) heading.setAttribute('tabindex', '-1');
+    heading.focus({ preventScroll: true });
+    history.pushState(history.state, '', link.href);
+    this.mark(link.getAttribute('href')!);
+  };
+  render() {
+    const words = this.label || 'Contents';
+    const label = this.literal ? words : getText(words) || words;
+    return html`<nav aria-label=${label} part="navigation">
+      <div class="title"><ds-text literal strong role="heading" aria-level="2" part="title">${label}</ds-text></div>
+      <div class="links" part="links"><slot @slotchange=${() => this.refresh()}>
+        ${this.items.map(item => html`<a href=${item.href} data-depth=${item.depth ?? 0} aria-current=${this.current === item.href ? 'location' : nothing} part="link">${item.label}</a>`)}
+      </slot></div>
+    </nav>`;
+  }
+}
+define('ds-table-of-contents', TableOfContents);
+declare global { interface HTMLElementTagNameMap { 'ds-table-of-contents': TableOfContents; } }