@adia-ai/web-components 0.8.37 → 0.8.39

package/components/drilldown/drilldown.css

@@ -0,0 +1,304 @@
+@scope (drilldown-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --drilldown-row-height:  var(--a-size, 2.25rem);
+    --drilldown-row-radius:  var(--a-radius-sm);
+    --drilldown-row-px:      var(--a-space-2);
+    --drilldown-row-gap:     var(--a-space-2);
+    --drilldown-header-px:   var(--a-space-3);
+    --drilldown-header-py:   var(--a-space-2);
+    --drilldown-list-py:     var(--a-space-1);
+    --drilldown-dot-size:    0.5rem;
+    --drilldown-chevron-size: var(--a-caret-size);
+
+    /* ── Typography ── */
+    --drilldown-font-size:      var(--a-ui-size);
+    --drilldown-meta-font-size: var(--a-ui-xs);
+    --drilldown-title-font-size: var(--a-ui-size);
+    --drilldown-title-weight:   var(--a-weight-medium);
+
+    /* ── Colors ── */
+    --drilldown-fg:            var(--md-sys-color-neutral-on-surface);
+    --drilldown-fg-muted:      var(--a-fg-muted);
+    --drilldown-bg-hover:      var(--a-bg-hover);
+    --drilldown-bg-active:     var(--a-bg-muted);
+    --drilldown-border:        var(--md-sys-color-neutral-outline-variant);
+
+    /* ── Count chip (row-native — deliberately NOT badge-ui's chrome,
+       which reads oversized at this row density; gh#1285) ── */
+    --drilldown-count-chip-px:        var(--a-space-1);
+    --drilldown-count-chip-py:        var(--a-space-px);
+    --drilldown-count-chip-font-size: var(--a-ui-2xs, 0.6875rem);
+    --drilldown-count-chip-radius:    var(--a-radius-sm);
+    --drilldown-count-chip-bg:        var(--md-sys-color-neutral-container-low);
+    --drilldown-count-chip-fg:        var(--a-fg-muted);
+
+    /* ── Transition ── */
+    --drilldown-duration:  var(--a-duration-fast);
+    --drilldown-easing:    var(--a-easing);
+
+    /* ── Focus ── */
+    --drilldown-focus-ring: var(--a-focus-ring);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    font-size: var(--drilldown-font-size);
+    color: var(--drilldown-fg);
+  }
+
+  /* ── Header ── */
+  [slot="header"] {
+    display: flex;
+    align-items: center;
+    gap: var(--drilldown-row-gap);
+    padding: var(--drilldown-header-py) var(--drilldown-header-px);
+    border-bottom: 1px solid var(--drilldown-border);
+    flex-shrink: 0;
+  }
+
+  [slot="back"] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--a-space-1);
+    border: none;
+    background: transparent;
+    color: var(--drilldown-fg-muted);
+    font: inherit;
+    font-size: var(--drilldown-meta-font-size);
+    padding: var(--a-space-1);
+    margin-inline-start: calc(-1 * var(--a-space-1));
+    border-radius: var(--drilldown-row-radius);
+    cursor: pointer;
+    white-space: nowrap;
+    max-width: 40%;
+    overflow: hidden;
+  }
+  [slot="back"] icon-ui {
+    --a-icon-size: var(--drilldown-chevron-size);
+    flex-shrink: 0;
+  }
+  [slot="back"] [data-back-label] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  [slot="back"]:hover {
+    background: var(--drilldown-bg-hover);
+    color: var(--drilldown-fg);
+  }
+  [slot="back"]:focus-visible {
+    box-shadow: var(--drilldown-focus-ring);
+    outline: none;
+  }
+  [slot="back"][hidden] {
+    display: none;
+  }
+
+  [slot="breadcrumb"]:empty {
+    display: none;
+  }
+
+  [slot="title"] {
+    display: flex;
+    align-items: baseline;
+    gap: var(--a-space-1-5);
+    min-width: 0;
+    flex: 1;
+  }
+  [data-level-title] {
+    font-weight: var(--drilldown-title-weight);
+    font-size: var(--drilldown-title-font-size);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  [data-level-title]:empty {
+    display: none;
+  }
+  [data-level-count] {
+    color: var(--drilldown-fg-muted);
+    font-size: var(--drilldown-meta-font-size);
+    font-variant-numeric: tabular-nums;
+    flex-shrink: 0;
+  }
+  [data-level-count]:empty {
+    display: none;
+  }
+
+  /* ── Filter ── */
+  [slot="filter"] {
+    display: flex;
+    align-items: center;
+    gap: var(--a-space-2);
+    padding: var(--a-space-2) var(--drilldown-header-px);
+    border-bottom: 1px solid var(--drilldown-border);
+    flex-shrink: 0;
+  }
+  [slot="filter"][hidden] {
+    display: none;
+  }
+  [slot="filter"] icon-ui {
+    --a-icon-size: 0.875rem;
+    color: var(--drilldown-fg-muted);
+    flex-shrink: 0;
+  }
+  /* Composed <input-ui raw> (per ADR-0055 / ADR-0025 — no native <input>
+     wrap; the search-ui precedent). `raw` already strips input-ui's own
+     border/background/padding (input.css); re-point its own tokens so the
+     text inherits this row's chrome instead of input-ui's defaults. */
+  [slot="filter"] input-ui {
+    flex: 1;
+    min-width: 0;
+    --input-fg: var(--drilldown-fg);
+    --input-placeholder-fg: var(--drilldown-fg-muted);
+    font: inherit;
+  }
+
+  /* ── Viewport / panel ── */
+  [slot="viewport"] {
+    flex: 1;
+    min-height: 0;
+    overflow: hidden;
+    position: relative;
+  }
+
+  [slot="panel"] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--a-space-0-5);
+    padding: var(--drilldown-list-py) var(--a-space-1);
+    height: 100%;
+    overflow-y: auto;
+  }
+
+  [slot="panel"][data-anim="forward"] {
+    animation: drilldown-enter-forward var(--drilldown-duration) var(--drilldown-easing);
+  }
+  [slot="panel"][data-anim="backward"] {
+    animation: drilldown-enter-backward var(--drilldown-duration) var(--drilldown-easing);
+  }
+
+  @keyframes drilldown-enter-forward {
+    from { transform: translateX(var(--a-space-4)); opacity: 0; }
+    to   { transform: none; opacity: 1; }
+  }
+  @keyframes drilldown-enter-backward {
+    from { transform: translateX(calc(-1 * var(--a-space-4))); opacity: 0; }
+    to   { transform: none; opacity: 1; }
+  }
+
+  /* ── Rows ── */
+  [role="option"] {
+    display: flex;
+    align-items: center;
+    gap: var(--drilldown-row-gap);
+    min-height: var(--drilldown-row-height);
+    padding-inline: var(--drilldown-row-px);
+    border-radius: var(--drilldown-row-radius);
+    cursor: pointer;
+    outline: none;
+    transition: background var(--drilldown-duration) var(--drilldown-easing);
+  }
+  [role="option"]:hover {
+    background: var(--drilldown-bg-hover);
+  }
+  [role="option"]:focus-visible,
+  [role="option"][tabindex="0"] {
+    background: var(--drilldown-bg-active);
+  }
+  [role="option"]:focus-visible {
+    box-shadow: var(--drilldown-focus-ring);
+  }
+
+  [slot="dot"] {
+    inline-size: var(--drilldown-dot-size);
+    block-size: var(--drilldown-dot-size);
+    border-radius: var(--a-radius-full);
+    flex-shrink: 0;
+    background: var(--md-sys-color-neutral);
+  }
+  [slot="dot"][data-tone="info"]    { background: var(--a-info-bg); }
+  [slot="dot"][data-tone="success"] { background: var(--a-success-bg); }
+  [slot="dot"][data-tone="warning"] { background: var(--a-warning-bg); }
+  [slot="dot"][data-tone="danger"]  { background: var(--a-danger-bg); }
+  [slot="dot"][data-tone="primary"] { background: var(--a-primary-bg); }
+
+  [slot="main"] {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    flex: 1;
+    line-height: 1.3;
+  }
+  [slot="label"] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  [slot="meta"] {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--drilldown-fg-muted);
+    font-size: var(--drilldown-meta-font-size);
+  }
+
+  [slot="counts"] {
+    display: flex;
+    align-items: center;
+    gap: var(--a-space-1);
+    flex-shrink: 0;
+  }
+  [data-count-chip] {
+    padding: var(--drilldown-count-chip-py) var(--drilldown-count-chip-px);
+    border-radius: var(--drilldown-count-chip-radius);
+    font-size: var(--drilldown-count-chip-font-size);
+    font-variant-numeric: tabular-nums;
+    line-height: 1;
+    background: var(--drilldown-count-chip-bg);
+    color: var(--drilldown-count-chip-fg);
+    white-space: nowrap;
+  }
+  [data-count-chip][data-tone="info"]    { background: var(--a-info-bg);    color: var(--md-sys-color-info-on-info); }
+  [data-count-chip][data-tone="success"] { background: var(--a-success-bg); color: var(--md-sys-color-success-on-success); }
+  [data-count-chip][data-tone="warning"] { background: var(--a-warning-bg); color: var(--md-sys-color-warning-on-warning); }
+  [data-count-chip][data-tone="danger"]  { background: var(--a-danger-bg);  color: var(--md-sys-color-danger-on-danger); }
+  [data-count-chip][data-tone="primary"] { background: var(--a-primary-bg); color: var(--md-sys-color-primary-on-primary); }
+
+  [slot="chevron"] {
+    --a-icon-size: var(--drilldown-chevron-size);
+    color: var(--drilldown-fg-muted);
+    flex-shrink: 0;
+  }
+
+  /* ── Loading / empty ── */
+  [data-drilldown-skeleton] {
+    margin: var(--a-space-0-5) var(--a-space-1);
+  }
+
+  /* ── Live region (visually hidden, still announced) ── */
+  [data-visually-hidden] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [slot="panel"][data-anim] {
+      animation: none;
+    }
+  }
+
+  /* `[static]` — explicit opt-out, same effect as prefers-reduced-motion. */
+  :scope[static] [slot="panel"][data-anim] {
+    animation: none;
+  }
+}

package/components/drilldown/drilldown.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `<drilldown-ui>` — Single-panel, multi-level drill-in menu. One list panel slides between
+levels (a level header with back navigation replaces stacking a column
+per level) — for hierarchical data where miller columns don't fit the
+viewport (>2 levels, >12 top-level entries, or narrow layouts). Rows
+compose a leading dot/icon, primary label, optional meta line, and
+trailing row-native count chips (not full <badge-ui>, which reads
+oversized at row density) — plus a drill-in chevron on branch items.
+Set `.items` to a tree of `{value, label, meta?, dot?, counts?, children?}`
+nodes; `children` may be an array (sync) or a function returning an
+array/Promise (lazy, fetched on drill-in — a loading level is shown via
+<skeleton-ui> while it resolves). Distinct from <tree-ui> (inline
+expand/collapse — right for file-tree shapes, wrong for wide/deep data
+where the expanded tree becomes a wall of rows), <nav-ui> (flat app
+navigation, not hierarchical drill-in), and <context-menu> (transient
+popover submenus, not a persistent content panel).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/drilldown
+ *
+ * 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 DrilldownNavigateEventDetail {
+  /** The newly-shown level's ancestor value chain. */
+  path: string[];
+}
+
+export type DrilldownNavigateEvent = CustomEvent<DrilldownNavigateEventDetail>;
+export interface DrilldownSelectEventDetail {
+  /** The activated node object. */
+  item: Record<string, unknown>;
+  /** Ancestor value chain the selected item lives at. */
+  path: string[];
+}
+
+export type DrilldownSelectEvent = CustomEvent<DrilldownSelectEventDetail>;
+
+export class UIDrilldown extends UIElement {
+  /** Root-level array of node objects: {value, label, meta?, dot?, counts?, children?, leaf?}. `value` is the stable id used in `path` and event details. `dot` names a semantic tone (info, success, warning, danger, primary, neutral) rendered as a small leading color swatch. `counts` is an array of {variant?, value} rendered as compact trailing chips. `children` is either an array of child nodes (resolved synchronously) or a function `(item) => array | Promise<array>` for lazy per-level fetch — a loading level renders while the promise is pending. `leaf: true` forces no drill chevron even when `children` is present (rare — normally omit `children` instead). */
+  items: string;
+  /** Show a filter input pinned above the list, filtering the current level's rows by label/meta. */
+  filterable: boolean;
+  /** Current drilled-in level, as an array of ancestor item `value`s (root = `[]`). Setting `.path` restores directly to that nested level without animating through every intermediate level — the deep-link/URL-restore path. Hand-managed (not the generic `reflect:` mechanism, which can't JSON-encode arrays) — it still genuinely reflects to a JSON-encoded `path` attribute both ways (property → attribute and attribute → property), unlike most array props on this kit. */
+  path: string;
+  /** Placeholder text for the filter input (only rendered when `[filterable]`). */
+  placeholder: string;
+  /** Level-header title shown at the root level (depth 0). Empty by default (no title row). */
+  rootLabel: string;
+  /** When true, clicking/activating a branch item (one with children) BOTH fires `select` and drills into it — the Schema Manager shape, where picking a namespace is both a selection and a navigation. Default false: branch activation only drills in; only leaf activation fires `select`. */
+  selectOnDrill: boolean;
+  /** Suppress the horizontal slide transition between levels — instant swap. Also honored automatically under `prefers-reduced-motion: reduce`. */
+  static: boolean;
+
+  addEventListener(type: 'navigate', listener: (ev: DrilldownNavigateEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'select', listener: (ev: DrilldownSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIDrilldown, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}

package/components/drilldown/drilldown.examples.md

@@ -0,0 +1,20 @@
+# drilldown — Examples
+
+## Schema Manager — namespace → node type → detail
+
+```html
+<drilldown-ui id="drilldown-schema" root-label="Namespaces" style="width:22rem; height:24rem; border:1px solid var(--md-sys-color-neutral-outline); border-radius:var(--a-radius-lg);"></drilldown-ui>
+```
+
+## filterable
+
+```html
+<drilldown-ui id="drilldown-filter" filterable placeholder="Filter namespaces…" root-label="Namespaces" style="width:22rem; height:20rem; border:1px solid var(--md-sys-color-neutral-outline); border-radius:var(--a-radius-lg);"></drilldown-ui>
+```
+
+## select-on-drill
+
+```html
+<drilldown-ui id="drilldown-select-on-drill" select-on-drill root-label="Namespaces" style="width:22rem; height:18rem; border:1px solid var(--md-sys-color-neutral-outline); border-radius:var(--a-radius-lg);"></drilldown-ui>
+<p data-drilldown-log style="margin-top: var(--a-space-2);">Activate a namespace — it selects AND drills in.</p>
+```

package/components/drilldown/drilldown.js

@@ -0,0 +1,17 @@
+/**
+ * `<drilldown-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIDrilldown } from '@adia-ai/web-components/components/drilldown/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIDrilldown } from './drilldown.class.js';
+
+defineIfFree('drilldown-ui', UIDrilldown);
+
+export { UIDrilldown };

package/components/drilldown/drilldown.yaml

@@ -0,0 +1,273 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIDrilldown
+tag: drilldown-ui
+status: beta
+component: Drilldown
+category: navigation
+version: 1
+description: |
+  Single-panel, multi-level drill-in menu. One list panel slides between
+  levels (a level header with back navigation replaces stacking a column
+  per level) — for hierarchical data where miller columns don't fit the
+  viewport (>2 levels, >12 top-level entries, or narrow layouts). Rows
+  compose a leading dot/icon, primary label, optional meta line, and
+  trailing row-native count chips (not full <badge-ui>, which reads
+  oversized at row density) — plus a drill-in chevron on branch items.
+  Set `.items` to a tree of `{value, label, meta?, dot?, counts?, children?}`
+  nodes; `children` may be an array (sync) or a function returning an
+  array/Promise (lazy, fetched on drill-in — a loading level is shown via
+  <skeleton-ui> while it resolves). Distinct from <tree-ui> (inline
+  expand/collapse — right for file-tree shapes, wrong for wide/deep data
+  where the expanded tree becomes a wall of rows), <nav-ui> (flat app
+  navigation, not hierarchical drill-in), and <context-menu> (transient
+  popover submenus, not a persistent content panel).
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
+  - skeleton-ui
+  - empty-state-ui
+  - input-ui    # filter row's text field (ADR-0055 — no native <input> in stamped DOM)
+  - button-ui   # back-navigation affordance
+props:
+  items:
+    description: >-
+      Root-level array of node objects: {value, label, meta?, dot?,
+      counts?, children?, leaf?}. `value` is the stable id used in `path`
+      and event details. `dot` names a semantic tone (info, success,
+      warning, danger, primary, neutral) rendered as a small leading
+      color swatch. `counts` is an array of {variant?, value} rendered as
+      compact trailing chips. `children` is either an array of child
+      nodes (resolved synchronously) or a function `(item) => array |
+      Promise<array>` for lazy per-level fetch — a loading level renders
+      while the promise is pending. `leaf: true` forces no drill chevron
+      even when `children` is present (rare — normally omit `children`
+      instead).
+    type: array
+    items:
+      type: object
+    default: []
+    dynamic: true
+  path:
+    description: >-
+      Current drilled-in level, as an array of ancestor item `value`s
+      (root = `[]`). Setting `.path` restores directly to that nested
+      level without animating through every intermediate level — the
+      deep-link/URL-restore path. Hand-managed (not the generic
+      `reflect:` mechanism, which can't JSON-encode arrays) — it still
+      genuinely reflects to a JSON-encoded `path` attribute both ways
+      (property → attribute and attribute → property), unlike most array
+      props on this kit.
+    type: array
+    items:
+      type: string
+    default: []
+    dynamic: true
+  rootLabel:
+    description: Level-header title shown at the root level (depth 0). Empty by default (no title row).
+    type: string
+    default: ""
+    reflect: true
+  filterable:
+    description: Show a filter input pinned above the list, filtering the current level's rows by label/meta.
+    type: boolean
+    default: false
+    reflect: true
+  placeholder:
+    description: Placeholder text for the filter input (only rendered when `[filterable]`).
+    type: string
+    default: "Filter…"
+    reflect: true
+  selectOnDrill:
+    description: >-
+      When true, clicking/activating a branch item (one with children)
+      BOTH fires `select` and drills into it — the Schema Manager shape,
+      where picking a namespace is both a selection and a navigation.
+      Default false: branch activation only drills in; only leaf
+      activation fires `select`.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: select-on-drill
+  static:
+    description: >-
+      Suppress the horizontal slide transition between levels — instant
+      swap. Also honored automatically under `prefers-reduced-motion: reduce`.
+    type: boolean
+    default: false
+    reflect: true
+events:
+  select:
+    description: >
+      Fired when a leaf item is activated (click/Enter), or when a branch
+      item is activated with `[select-on-drill]` set. detail: { path,
+      item }. `path` is the drilled-in level the item lives at (the
+      current `.path` at the time of activation); `item` is the raw node
+      object.
+    detail:
+      path:
+        type: array
+        items:
+          type: string
+        description: Ancestor value chain the selected item lives at.
+      item:
+        type: object
+        description: The activated node object.
+  navigate:
+    description: >
+      Fired whenever the shown level changes — drill-in, back, breadcrumb
+      jump, or a programmatic `.path` assignment. detail: { path }. Hosts
+      mirror this to the URL instead of listening to `select`.
+    detail:
+      path:
+        type: array
+        items:
+          type: string
+        description: The newly-shown level's ancestor value chain.
+slots:
+  breadcrumb:
+    description: >-
+      Optional slot for a consumer-supplied <breadcrumb-ui> in the level
+      header, for deep hierarchies. Not managed by drilldown-ui — the
+      consumer wires jump clicks to `.path = [...]` itself.
+  header:
+    description: Auto-stamped level-header container (back affordance + breadcrumb + title/count). Structural — not consumer-overridable.
+  back:
+    description: Auto-stamped back-affordance <button> (chevron + parent-level label). Hidden at the root level.
+  title:
+    description: Auto-stamped title cluster (current-level label + item count) inside the header.
+  filter:
+    description: Auto-stamped filter-input row, shown only when `[filterable]` is set.
+  viewport:
+    description: Auto-stamped clipping container for the current level's panel (hosts the slide-transition overflow clip).
+  dot:
+    description: Auto-stamped per-row leading color swatch, rendered when the row's data item declares a `dot` tone.
+  main:
+    description: Auto-stamped per-row content column (label + optional meta line).
+  meta:
+    description: Auto-stamped per-row secondary meta line, rendered when the row's data item declares `meta`.
+  counts:
+    description: Auto-stamped per-row trailing count-chip cluster, rendered when the row's data item declares `counts`.
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: loading
+    description: A lazy level's children are being resolved (async `children` function pending).
+  - name: empty
+    description: The current level has no items.
+traits: []
+tokens:
+  --drilldown-row-height:
+    description: Height of each row.
+  --drilldown-row-radius:
+    description: Border radius of each row.
+  --drilldown-row-px:
+    description: Inline padding of each row.
+  --drilldown-row-gap:
+    description: Gap between row elements (dot / main / counts / chevron).
+  --drilldown-bg-hover:
+    description: Row background on hover.
+  --drilldown-bg-active:
+    description: Row background when focused/active (roving tabindex).
+  --drilldown-fg:
+    description: Primary row text color.
+  --drilldown-fg-muted:
+    description: Muted text color (meta line, chevron, back affordance).
+  --drilldown-dot-size:
+    description: Diameter of the leading color dot.
+  --drilldown-count-chip-px:
+    description: Inline padding of a trailing count chip.
+  --drilldown-count-chip-font-size:
+    description: Font size of a trailing count chip.
+  --drilldown-count-chip-radius:
+    description: Border radius of a trailing count chip.
+  --drilldown-header-px:
+    description: Inline padding of the level header.
+  --drilldown-header-py:
+    description: Block padding of the level header.
+  --drilldown-duration:
+    description: Slide-transition duration.
+  --drilldown-easing:
+    description: Slide-transition easing function.
+  --drilldown-focus-ring:
+    description: Focus ring box-shadow for rows and the back button.
+requiredIcons:
+  - caret-left
+  - caret-right
+  - magnifying-glass
+a2ui:
+  rules:
+    - >-
+      Use <drilldown-ui> for a hierarchical namespace/category → item
+      drill-in over a SINGLE panel — the sibling shape to miller columns,
+      chosen when the viewport can't afford a column per level (>2
+      levels, or a level with more than ~12 entries). For inline
+      expand/collapse trees, use <tree-ui>. For flat app navigation, use
+      <nav-ui>. For a small non-searchable popover of actions, use
+      <menu-ui> or <context-menu>.
+    - >-
+      Set `.items` programmatically (array of node objects), NOT
+      declarative children — drilldown-ui is a content-only, data-driven
+      primitive with no children markup contract.
+    - >-
+      Listen for `select` (leaf activation, or branch activation with
+      `[select-on-drill]`) and `navigate` (any level change) — mirror
+      `navigate`'s `path` to the URL, not `select`'s.
+    - >-
+      A `path` array restores directly to a nested level (deep link)
+      without animating through intermediates — set it once on mount
+      rather than calling drill-in repeatedly.
+anti_patterns: []
+examples:
+  - name: basic-drilldown
+    description: Basic Drilldown usage
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Card",
+          "children": [
+            "sec"
+          ]
+        },
+        {
+          "id": "sec",
+          "component": "Section",
+          "children": [
+            "comp"
+          ]
+        },
+        {
+          "id": "comp",
+          "component": "Drilldown"
+        }
+      ]
+keywords:
+  - drilldown
+  - drill-down
+  - miller
+  - miller-columns
+  - namespace
+  - hierarchy
+  - navigator
+  - catalog-browser
+synonyms:
+  hierarchy:
+    - tree
+    - nav
+    - drilldown
+  miller:
+    - drilldown
+    - tree
+    - column
+  navigator:
+    - tree
+    - nav
+    - drilldown
+    - sidebar
+related:
+  - Tree
+  - List
+  - Nav
+  - Breadcrumb
+  - Menu

package/components/index.js

@@ -34,6 +34,7 @@ export { UISegment } from './segment/segment.js';
 export { UISegmented } from './segmented/segmented.js';
 export { UIRange } from './range/range.js';
 export { UITree, UITreeItem } from './tree/tree.js';
+export { UIDrilldown } from './drilldown/drilldown.js';
 export { UIPane } from './pane/pane.js';
 export { UIPage } from './page/page.js';
 export { UIChatInput } from './chat-thread/chat-input.js';