@adia-ai/web-components 0.6.35 → 0.6.37

package/components/tag/tag.yaml

@@ -51,6 +51,26 @@ props:
       - success
       - warning
       - danger
+  tone:
+    description: |
+      Fill style — orthogonal to [variant]. Three values:
+        - `solid` (default for family variants) — saturated bg + on-strong
+          (near-white) text. The chip IS the state.
+        - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s
+          default look. Use on metadata chips in dense lists where the
+          saturated default would compete for attention.
+        - `outline` — transparent bg + family-colored border + family-colored
+          text. The lightest visual weight; good in dense data tables or
+          faceted filter rows where multiple chips would otherwise compete.
+      The `default` variant (no family) stays quiet chrome regardless of
+      tone unless `tone="solid"` is set explicitly (high-contrast neutral
+      inverse), or `tone="outline"` (fg-muted text + subtle border).
+    type: string
+    default: solid
+    enum:
+      - solid
+      - muted
+      - outline
 events:
   remove:
     description: Fired when the dismiss button is activated.

package/components/tags-input/tags-input.class.js

@@ -518,12 +518,19 @@ export class UITagsInput extends UIFormElement {
   #handleChipRemove(e) {
     const chip = e.target.closest('tag-ui[data-index]');
     if (!chip) return;
-    // Stop the bubbling `remove` from <tag-ui> — tag-ui auto-removes the node
-    // itself on dispatch, but we own the list. Rebuild to keep the source of
-    // truth in `#value`.
+    // tag-ui's `remove` CustomEvent bubbles SYNCHRONOUSLY before tag-ui's
+    // own `this.remove()` runs (see tag/tag.class.js:59-63 — dispatch then
+    // remove). If we react inside the bubble (call `#renderChips()` now),
+    // the DOM still contains the about-to-be-removed chip and the
+    // positional reconcile in `#renderChips()` mutates the WRONG chip's
+    // text — visually erasing one or more adjacent chips. Pre-emptively
+    // detach the source chip ourselves so the DOM matches `#value` before
+    // render. tag-ui's later `this.remove()` is a harmless no-op on an
+    // already-detached node.
     e.stopPropagation();
     const idx = Number(chip.dataset.index);
     if (!Number.isInteger(idx)) return;
+    chip.remove();
     this.#removeByIndex(idx, 'chip-click');
   }
 

package/components/tags-input/tags-input.css

@@ -110,14 +110,23 @@
     white-space: pre-wrap;
     overflow-wrap: anywhere;
     cursor: text;
+    /* Positioning context for the [data-empty]::before placeholder pseudo
+       (kept out of inline flow so the caret renders at content-start). */
+    position: relative;
   }
-  /* Empty-state placeholder via ::before pseudo so the contenteditable
-     surface participates in inline layout (the same pattern the input-ui
-     + combobox-ui editable surfaces use). */
+  /* Empty-state placeholder. The pseudo is absolutely positioned (NOT
+     inline) so an in-flow pseudo box doesn't push the caret-at-position-0
+     to the right of the placeholder text after type-then-delete. Same
+     pattern input-ui + textarea-ui + combobox-ui use. */
   [data-inline-input][data-empty]::before {
     content: attr(data-placeholder);
     color: var(--tags-input-placeholder-fg, var(--tags-input-placeholder-fg-default));
     pointer-events: none;
+    position: absolute;
+    inset: 0;
+    padding: inherit;
+    display: flex;
+    align-items: center;
   }
 
   /* ── Spinner (async validator) ── */

package/components/textarea/textarea.css

@@ -60,6 +60,10 @@ textarea-ui:not([disabled]) [slot="text"]:hover {
   [slot="label"][label]::after { content: attr(label); }
 
   [slot="text"] {
+    /* Positioning context for the [data-empty]::before placeholder pseudo,
+       which is absolutely positioned (out of inline flow) so the caret
+       renders at content-start instead of after the placeholder text. */
+    position: relative;
     min-height: var(--textarea-min-height, var(--textarea-min-height-default));
     padding: var(--textarea-py, var(--textarea-py-default)) var(--textarea-px, var(--textarea-px-default));
     border: 1px solid var(--textarea-border, var(--textarea-border-default));
@@ -99,11 +103,16 @@ textarea-ui:not([disabled]) [slot="text"]:hover {
     color: var(--textarea-label-fg-focus, var(--textarea-label-fg-focus-default));
   }
 
-  /* Placeholder */
+  /* Placeholder — see input.css companion comment. Out-of-flow positioning
+     prevents the inline pseudo box from pushing the caret position to the
+     right of the placeholder text after type-then-delete. */
   [slot="text"][data-empty]::before {
     content: attr(data-placeholder);
     color: var(--textarea-placeholder-fg, var(--textarea-placeholder-fg-default));
     pointer-events: none;
+    position: absolute;
+    inset: 0;
+    padding: inherit;
   }
 
   /* Disabled */

package/components/toast/toast.class.js

@@ -78,10 +78,14 @@ export class UIToast extends UIElement {
    * @param {string} [opts.variant='info']  — `error` aliases to `danger`.
    * @param {number} [opts.duration=4000]
    * @param {string} [opts.position='bottom-right']
+   * @param {boolean} [opts.dismissible]  Force-show the close button on auto-
+   *                                fade toasts (sticky toasts always show it).
+   * @param {string} [opts.action]  Optional action button label (e.g. 'Undo').
+   * @param {function} [opts.onAction]  Action button click handler.
    * @returns {{id:string|null, dismiss:function, update:function}}  FeedHandle.
    */
   static show(opts = {}) {
-    const { text, variant = 'info', duration = 4000, position = 'bottom-right' } = opts;
+    const { text, variant = 'info', position = 'bottom-right', action, onAction } = opts;
     // §224 (v0.5.9, FEEDBACK-10 §2): mark the spawned feed container so
     // DOM-query consumers (Playwright, devtools, instrumentation) can
     // distinguish toast-spawned <feed-ui> from user-authored ones. The marker
@@ -91,11 +95,15 @@ export class UIToast extends UIElement {
     if (container && !container.hasAttribute('data-spawned-by')) {
       container.setAttribute('data-spawned-by', 'toast');
     }
-    return UIFeed.post({
+    const payload = {
       text,
       variant: variant === 'error' ? 'danger' : variant,
-      duration,
       position,
-    });
+    };
+    if ('duration' in opts) payload.duration = opts.duration;
+    if ('dismissible' in opts) payload.dismissible = !!opts.dismissible;
+    if (action) payload.action = action;
+    if (typeof onAction === 'function') payload.onAction = onAction;
+    return UIFeed.post(payload);
   }
 }

package/components/toc/toc.a2ui.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/TableOfContents.json",
+  "title": "TableOfContents",
+  "description": "Auto-generated in-page table of contents. Scans a target container\nfor headings (default `h2,h3`), ensures each has an `id` (slugifies\nthe text content if missing), and stamps a `<nav>` list of anchor\nlinks. An `IntersectionObserver` tracks the active heading and\napplies `[data-active]` to the matching link so consumers can style\nthe currently-visible section. Smooth-scroll on click is handled by\nthe global `scroll-behavior: smooth` set in resets.css.\n\nPair with a sticky container (`position: sticky; top: <offset>;`) in\nan aside / right rail for the classic docs-site outline pattern.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "TableOfContents"
+    },
+    "headings": {
+      "description": "CSS selector listing the heading tags to include (e.g. `h2,h3`).\nThe selector is matched against the target container's\ndescendants. Default `h2,h3` produces the common two-level\noutline.\n",
+      "type": "string",
+      "default": "h2,h3"
+    },
+    "label": {
+      "description": "`aria-label` for the nav. Defaults to `Table of contents`.\n",
+      "type": "string",
+      "default": "Table of contents"
+    },
+    "offset": {
+      "description": "Top offset in pixels for active-state detection. The\nIntersectionObserver's `rootMargin` is set to\n`-<offset>px 0px -50% 0px` so the active item becomes the\nheading nearest the top of the viewport BELOW any sticky header\nchrome. Tune to match the height of your sticky topbar (default\n`80` is a reasonable docs-shell value).\n",
+      "type": "number",
+      "default": 80
+    },
+    "target": {
+      "description": "CSS selector pointing to the container to scan. Empty (default)\nscans the toc-ui's parent element. Set to `#article` /\n`[data-toc-target]` / `main` for a specific scope.\n",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<toc-ui target=\"#article\"></toc-ui>\n<article id=\"article\">\n  <h2>...</h2><h3>...</h3>\n</article>\n",
+        "why": "toc-ui's default scans its PARENT for headings. If toc-ui is a\nsibling of the content (not inside it), the scan finds the\nheadings inside the toc-ui's parent which usually means the\nheadings + the toc itself — works only by coincidence. Set\n[target] explicitly for clarity.\n",
+        "wrong": "<toc-ui></toc-ui>\n<h2>...</h2><h3>...</h3>\n"
+      }
+    ],
+    "category": "navigation",
+    "composes": [],
+    "events": {
+      "section-change": {
+        "description": "Fired when the active heading changes (the user scrolls into a new section). Detail carries the new active id.",
+        "detail": {
+          "activeId": "string"
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "TOC scanning the parent container.",
+        "a2ui": "[\n  {\n    \"id\": \"page\",\n    \"component\": \"Section\",\n    \"children\": [\"toc\", \"h1\", \"h2-1\", \"p-1\", \"h2-2\", \"p-2\"]\n  },\n  {\"id\": \"toc\",  \"component\": \"TableOfContents\"},\n  {\"id\": \"h1\",   \"component\": \"Text\", \"variant\": \"title\", \"textContent\": \"Article title\"},\n  {\"id\": \"h2-1\", \"component\": \"Text\", \"variant\": \"heading\", \"textContent\": \"Introduction\"},\n  {\"id\": \"p-1\",  \"component\": \"Text\", \"textContent\": \"...\"},\n  {\"id\": \"h2-2\", \"component\": \"Text\", \"variant\": \"heading\", \"textContent\": \"Conclusion\"},\n  {\"id\": \"p-2\",  \"component\": \"Text\", \"textContent\": \"...\"}\n]\n",
+        "name": "default"
+      },
+      {
+        "description": "TOC scanning a specific article container.",
+        "a2ui": "[\n  {\n    \"id\": \"shell\",\n    \"component\": \"Row\",\n    \"children\": [\"toc\", \"article\"]\n  },\n  {\n    \"id\": \"toc\",\n    \"component\": \"TableOfContents\",\n    \"target\": \"#main-article\",\n    \"headings\": \"h2,h3,h4\"\n  },\n  {\n    \"id\": \"article\",\n    \"component\": \"Section\",\n    \"attrs\": { \"id\": \"main-article\" },\n    \"children\": []\n  }\n]\n",
+        "name": "targeted"
+      }
+    ],
+    "keywords": [
+      "toc",
+      "table-of-contents",
+      "outline",
+      "sub-nav",
+      "page-nav",
+      "in-page-nav",
+      "heading-nav"
+    ],
+    "name": "UITableOfContents",
+    "related": [
+      "aside",
+      "nav",
+      "link",
+      "text"
+    ],
+    "slots": {
+      "default": {
+        "description": "Stamped automatically — a `<nav>` containing a flat `<ul>` of `<a href=\"#id\">` links. Override by authoring your own content; auto-stamp is skipped when a `<nav>` is already present."
+      }
+    },
+    "states": [
+      {
+        "description": "Default — no active section yet.",
+        "name": "idle"
+      },
+      {
+        "description": "A section is in view; the matching `<a>` carries `[data-active]`.",
+        "attribute": "data-active",
+        "name": "active"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "outline": [
+        "toc",
+        "table-of-contents"
+      ],
+      "toc": [
+        "table-of-contents",
+        "outline"
+      ]
+    },
+    "tag": "toc-ui",
+    "tokens": {
+      "--toc-fg": {
+        "description": "Default link color.",
+        "default": "var(--a-fg-muted)"
+      },
+      "--toc-fg-active": {
+        "description": "Active-link color.",
+        "default": "var(--a-fg)"
+      },
+      "--toc-fg-hover": {
+        "description": "Hover color.",
+        "default": "var(--a-fg)"
+      },
+      "--toc-gap": {
+        "description": "Vertical gap between links.",
+        "default": "var(--a-space-1)"
+      },
+      "--toc-indent": {
+        "description": "Per-depth-level indent.",
+        "default": "var(--a-space-3)"
+      },
+      "--toc-padding-block": {
+        "description": "Per-link block padding (top/bottom).",
+        "default": "var(--a-space-1)"
+      },
+      "--toc-padding-inline": {
+        "description": "Per-link inline padding.",
+        "default": "var(--a-space-2)"
+      },
+      "--toc-rule-active": {
+        "description": "Active-item indicator rule color (left border).",
+        "default": "var(--a-accent-bg)"
+      },
+      "--toc-size": {
+        "description": "Link font-size.",
+        "default": "var(--a-ui-sm)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/toc/toc.class.js

@@ -0,0 +1,222 @@
+/**
+ * Non-side-effect class export for `<toc-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the
+ * tag. Useful for test isolation, subclassing with tag-name override,
+ * or selective composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/toc`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <toc-ui target="#article" headings="h2,h3"></toc-ui>
+ *
+ * Layout:
+ *   <nav aria-label="Table of contents">
+ *     <ul>
+ *       <li><a href="#intro"    data-depth="0">Introduction</a></li>
+ *       <li><a href="#setup"    data-depth="1">Setup</a></li>
+ *       <li><a href="#conclude" data-depth="0">Conclusion</a></li>
+ *     </ul>
+ *   </nav>
+ *
+ * Depth is relative — the shallowest heading found becomes depth 0,
+ * each level deeper gets +1. CSS indents via `[data-depth=N]`.
+ *
+ * Active state: an IntersectionObserver picks the heading nearest the
+ * top of the viewport (below the configured offset). That heading's
+ * link gets `[data-active]`. The `section-change` event fires when
+ * the active id changes.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+function slugify(text) {
+  return (text || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    || 'section';
+}
+
+export class UITableOfContents extends UIElement {
+  static properties = {
+    target:   { type: String, default: '',                    reflect: true },
+    headings: { type: String, default: 'h2,h3',               reflect: true },
+    offset:   { type: Number, default: 80,                    reflect: true },
+    label:    { type: String, default: 'Table of contents',   reflect: true },
+  };
+
+  static template = () => null;
+
+  #observer = null;
+  #activeId = null;
+  #lastRoot = null;
+  #lastHeadingsKey = '';
+  #scheduledScan = false;
+
+  #resolveRoot() {
+    if (this.target) {
+      const found = this.ownerDocument?.querySelector(this.target) || document.querySelector(this.target);
+      if (!found) return null;
+      return found;
+    }
+    return this.parentElement;
+  }
+
+  #scanHeadings() {
+    const root = this.#resolveRoot();
+    if (!root) return [];
+    const selector = (this.headings || 'h2,h3').trim();
+    const headings = Array.from(root.querySelectorAll(selector));
+    // Exclude any headings that are descendants of this toc-ui itself
+    // (avoid the toc reading its own stamped <a> labels when they
+    // contain header tags, and avoid recursion when toc-ui is inside
+    // the scan root).
+    return headings.filter((h) => !this.contains(h));
+  }
+
+  #ensureIds(headings) {
+    const doc = this.ownerDocument || document;
+    for (const h of headings) {
+      if (h.id) continue;
+      const base = slugify(h.textContent);
+      let id = base;
+      let i = 1;
+      while (doc.getElementById(id) && doc.getElementById(id) !== h) {
+        id = `${base}-${i++}`;
+      }
+      h.id = id;
+    }
+  }
+
+  #computeDepths(headings) {
+    if (headings.length === 0) return [];
+    // Heading levels (1..6) — find the shallowest as the depth-0 baseline.
+    const levels = headings.map((h) => {
+      const m = /^h([1-6])$/i.exec(h.tagName);
+      return m ? parseInt(m[1], 10) : 6;
+    });
+    const minLevel = Math.min(...levels);
+    return levels.map((l) => l - minLevel);
+  }
+
+  #render() {
+    const headings = this.#scanHeadings();
+    this.#ensureIds(headings);
+    const depths = this.#computeDepths(headings);
+
+    // Compute a key from id+depth to skip re-stamping when nothing
+    // structurally changed (cheap idempotence).
+    const key = headings.map((h, i) => `${h.id}:${depths[i]}`).join('|');
+    if (key === this.#lastHeadingsKey && this.querySelector('nav')) {
+      this.#setupObserver(headings);
+      return;
+    }
+    this.#lastHeadingsKey = key;
+
+    // Clear prior stamp (preserve any consumer-authored non-stamped
+    // content by checking the data-stamped marker).
+    const prior = this.querySelector('nav[data-stamped]');
+    if (prior) prior.remove();
+
+    if (headings.length === 0) {
+      this.removeAttribute('aria-label');
+      return;
+    }
+
+    const nav = document.createElement('nav');
+    nav.setAttribute('data-stamped', '');
+    nav.setAttribute('aria-label', this.label || 'Table of contents');
+
+    const ul = document.createElement('ul');
+
+    headings.forEach((h, i) => {
+      const li = document.createElement('li');
+      const a = document.createElement('a');
+      a.setAttribute('href', `#${h.id}`);
+      a.setAttribute('data-target-id', h.id);
+      a.setAttribute('data-depth', String(depths[i]));
+      a.textContent = (h.textContent || '').trim();
+      li.appendChild(a);
+      ul.appendChild(li);
+    });
+
+    nav.appendChild(ul);
+    this.appendChild(nav);
+
+    this.#setupObserver(headings);
+  }
+
+  #setupObserver(headings) {
+    this.#observer?.disconnect();
+    if (typeof IntersectionObserver === 'undefined') return;
+    if (headings.length === 0) return;
+
+    const offset = Number.isFinite(this.offset) ? this.offset : 80;
+    this.#observer = new IntersectionObserver((entries) => {
+      // Among entries currently intersecting, pick the one nearest the
+      // top of the viewport (smallest boundingClientRect.top ≥ 0).
+      const visible = entries
+        .filter((e) => e.isIntersecting)
+        .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+      if (visible.length === 0) return;
+      this.#setActive(visible[0].target.id);
+    }, {
+      rootMargin: `-${offset}px 0px -50% 0px`,
+      threshold: 0,
+    });
+
+    headings.forEach((h) => this.#observer.observe(h));
+  }
+
+  #setActive(id) {
+    if (id === this.#activeId) return;
+    this.#activeId = id;
+    this.querySelectorAll('a[data-target-id]').forEach((a) => {
+      if (a.dataset.targetId === id) a.setAttribute('data-active', '');
+      else a.removeAttribute('data-active');
+    });
+    this.dispatchEvent(new CustomEvent('section-change', {
+      bubbles: true,
+      detail: { activeId: id },
+    }));
+  }
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'navigation');
+    if (!this.hasAttribute('aria-label')) {
+      this.setAttribute('aria-label', this.label || 'Table of contents');
+    }
+    // Defer scan to the next microtask so any sibling content stamped
+    // by the same render pass has time to mount before we read its
+    // heading structure.
+    if (!this.#scheduledScan) {
+      this.#scheduledScan = true;
+      queueMicrotask(() => {
+        this.#scheduledScan = false;
+        this.#render();
+      });
+    }
+  }
+
+  render() {
+    // Re-scan when target / headings / offset / label change. The
+    // first render after connection is handled by the microtask in
+    // connected(); this catches dynamic prop updates.
+    if (this.#lastHeadingsKey || this.querySelector('nav[data-stamped]')) {
+      this.#render();
+    }
+  }
+
+  disconnected() {
+    super.disconnected();
+    this.#observer?.disconnect();
+    this.#observer = null;
+  }
+}

package/components/toc/toc.css

@@ -0,0 +1,92 @@
+/* ═══════════════════════════════════════════════════════════════
+   TOC-UI — Auto-generated table-of-contents navigation.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (toc-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --toc-gap-default:              var(--a-space-1);
+    --toc-indent-default:           var(--a-space-3);
+    --toc-padding-block-default:    var(--a-space-1);
+    --toc-padding-inline-default:   var(--a-space-2);
+
+    /* ── Colors ── */
+    --toc-fg-default:               var(--a-fg-muted);
+    --toc-fg-active-default:        var(--a-fg);
+    --toc-fg-hover-default:         var(--a-fg);
+    --toc-rule-active-default:      var(--a-accent-bg);
+    --toc-rule-inactive-default:    transparent;
+
+    /* ── Typography ── */
+    --toc-size-default:             var(--a-ui-sm);
+    --toc-weight-default:           var(--a-weight);
+    --toc-weight-active-default:    var(--a-weight-medium);
+  }
+
+  /* ── Host ── */
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    color: var(--toc-fg, var(--toc-fg-default));
+    font-size: var(--toc-size, var(--toc-size-default));
+  }
+
+  /* ── Nav scaffold ── */
+  nav {
+    display: block;
+  }
+
+  ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--toc-gap, var(--toc-gap-default));
+  }
+
+  li {
+    /* Flush — the link element carries its own block padding so the
+       hit-target is the entire row. */
+    list-style: none;
+  }
+
+  /* ── Link ── */
+  a {
+    display: block;
+    box-sizing: border-box;
+    padding-block: var(--toc-padding-block, var(--toc-padding-block-default));
+    padding-inline: var(--toc-padding-inline, var(--toc-padding-inline-default));
+    text-decoration: none;
+    color: inherit;
+    line-height: 1.4;
+    border-inline-start: 2px solid var(--toc-rule-inactive, var(--toc-rule-inactive-default));
+    transition:
+      color  var(--a-duration-fast) var(--a-easing),
+      border-color var(--a-duration-fast) var(--a-easing);
+  }
+
+  a:hover {
+    color: var(--toc-fg-hover, var(--toc-fg-hover-default));
+  }
+
+  a[data-active] {
+    color: var(--toc-fg-active, var(--toc-fg-active-default));
+    border-inline-start-color: var(--toc-rule-active, var(--toc-rule-active-default));
+    font-weight: var(--toc-weight-active, var(--toc-weight-active-default));
+  }
+
+  a:focus-visible {
+    outline: none;
+    box-shadow: var(--a-focus-ring);
+    border-radius: var(--a-radius-sm);
+  }
+
+  /* ── Indentation by depth ── */
+  a[data-depth="0"] { padding-inline-start: var(--toc-padding-inline, var(--toc-padding-inline-default)); }
+  a[data-depth="1"] { padding-inline-start: calc(var(--toc-padding-inline, var(--toc-padding-inline-default)) + var(--toc-indent, var(--toc-indent-default)) * 1); }
+  a[data-depth="2"] { padding-inline-start: calc(var(--toc-padding-inline, var(--toc-padding-inline-default)) + var(--toc-indent, var(--toc-indent-default)) * 2); }
+  a[data-depth="3"] { padding-inline-start: calc(var(--toc-padding-inline, var(--toc-padding-inline-default)) + var(--toc-indent, var(--toc-indent-default)) * 3); }
+  a[data-depth="4"] { padding-inline-start: calc(var(--toc-padding-inline, var(--toc-padding-inline-default)) + var(--toc-indent, var(--toc-indent-default)) * 4); }
+  a[data-depth="5"] { padding-inline-start: calc(var(--toc-padding-inline, var(--toc-padding-inline-default)) + var(--toc-indent, var(--toc-indent-default)) * 5); }
+}

package/components/toc/toc.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `<toc-ui>` — Auto-generated in-page table of contents. Scans a target container
+for headings (default `h2,h3`), ensures each has an `id` (slugifies
+the text content if missing), and stamps a `<nav>` list of anchor
+links. An `IntersectionObserver` tracks the active heading and
+applies `[data-active]` to the matching link so consumers can style
+the currently-visible section. Smooth-scroll on click is handled by
+the global `scroll-behavior: smooth` set in resets.css.
+
+Pair with a sticky container (`position: sticky; top: <offset>;`) in
+an aside / right rail for the classic docs-site outline pattern.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/toc
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export interface TableOfContentsSectionChangeEventDetail {
+  activeId: string;
+}
+
+export type TableOfContentsSectionChangeEvent = CustomEvent<TableOfContentsSectionChangeEventDetail>;
+
+export class UITableOfContents extends UIElement {
+  /** CSS selector listing the heading tags to include (e.g. `h2,h3`).
+The selector is matched against the target container's
+descendants. Default `h2,h3` produces the common two-level
+outline.
+ */
+  headings: string;
+  /** `aria-label` for the nav. Defaults to `Table of contents`.
+ */
+  label: string;
+  /** Top offset in pixels for active-state detection. The
+IntersectionObserver's `rootMargin` is set to
+`-<offset>px 0px -50% 0px` so the active item becomes the
+heading nearest the top of the viewport BELOW any sticky header
+chrome. Tune to match the height of your sticky topbar (default
+`80` is a reasonable docs-shell value).
+ */
+  offset: number;
+  /** CSS selector pointing to the container to scan. Empty (default)
+scans the toc-ui's parent element. Set to `#article` /
+`[data-toc-target]` / `main` for a specific scope.
+ */
+  target: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITableOfContents, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'section-change', listener: (ev: TableOfContentsSectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}