@adia-ai/web-components 0.8.36 → 0.8.38

package/components/drilldown/drilldown.a2ui.json

@@ -0,0 +1,242 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Drilldown.json",
+  "title": "Drilldown",
+  "description": "Single-panel, multi-level drill-in menu. One list panel slides between\nlevels (a level header with back navigation replaces stacking a column\nper level) — for hierarchical data where miller columns don't fit the\nviewport (>2 levels, >12 top-level entries, or narrow layouts). Rows\ncompose a leading dot/icon, primary label, optional meta line, and\ntrailing row-native count chips (not full <badge-ui>, which reads\noversized at row density) — plus a drill-in chevron on branch items.\nSet `.items` to a tree of `{value, label, meta?, dot?, counts?, children?}`\nnodes; `children` may be an array (sync) or a function returning an\narray/Promise (lazy, fetched on drill-in — a loading level is shown via\n<skeleton-ui> while it resolves). Distinct from <tree-ui> (inline\nexpand/collapse — right for file-tree shapes, wrong for wide/deep data\nwhere the expanded tree becomes a wall of rows), <nav-ui> (flat app\nnavigation, not hierarchical drill-in), and <context-menu> (transient\npopover submenus, not a persistent content panel).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "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).",
+      "$ref": "common_types.json#/$defs/DynamicObjectList"
+    },
+    "component": {
+      "const": "Drilldown"
+    },
+    "filterable": {
+      "description": "Show a filter input pinned above the list, filtering the current level's rows by label/meta.",
+      "type": "boolean",
+      "default": false
+    },
+    "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.",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "placeholder": {
+      "description": "Placeholder text for the filter input (only rendered when `[filterable]`).",
+      "type": "string",
+      "default": "Filter…"
+    },
+    "rootLabel": {
+      "description": "Level-header title shown at the root level (depth 0). Empty by default (no title row).",
+      "type": "string",
+      "default": ""
+    },
+    "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
+    },
+    "static": {
+      "description": "Suppress the horizontal slide transition between levels — instant swap. Also honored automatically under `prefers-reduced-motion: reduce`.",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "navigation",
+    "composes": [
+      "icon-ui",
+      "skeleton-ui",
+      "empty-state-ui"
+    ],
+    "events": {
+      "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`.\n",
+        "detail": {
+          "path": {
+            "description": "The newly-shown level's ancestor value chain.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "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.\n",
+        "detail": {
+          "item": {
+            "description": "The activated node object.",
+            "type": "object"
+          },
+          "path": {
+            "description": "Ancestor value chain the selected item lives at.",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Basic Drilldown usage",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"comp\"\n    ]\n  },\n  {\n    \"id\": \"comp\",\n    \"component\": \"Drilldown\"\n  }\n]",
+        "name": "basic-drilldown"
+      }
+    ],
+    "keywords": [
+      "drilldown",
+      "drill-down",
+      "miller",
+      "miller-columns",
+      "namespace",
+      "hierarchy",
+      "navigator",
+      "catalog-browser"
+    ],
+    "name": "UIDrilldown",
+    "related": [
+      "Tree",
+      "List",
+      "Nav",
+      "Breadcrumb",
+      "Menu"
+    ],
+    "slots": {
+      "title": {
+        "description": "Auto-stamped title cluster (current-level label + item count) inside the header."
+      },
+      "back": {
+        "description": "Auto-stamped back-affordance <button> (chevron + parent-level label). Hidden at the root level."
+      },
+      "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."
+      },
+      "counts": {
+        "description": "Auto-stamped per-row trailing count-chip cluster, rendered when the row's data item declares `counts`."
+      },
+      "dot": {
+        "description": "Auto-stamped per-row leading color swatch, rendered when the row's data item declares a `dot` tone."
+      },
+      "filter": {
+        "description": "Auto-stamped filter-input row, shown only when `[filterable]` is set."
+      },
+      "header": {
+        "description": "Auto-stamped level-header container (back affordance + breadcrumb + title/count). Structural — not consumer-overridable."
+      },
+      "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`."
+      },
+      "viewport": {
+        "description": "Auto-stamped clipping container for the current level's panel (hosts the slide-transition overflow clip)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "A lazy level's children are being resolved (async `children` function pending).",
+        "name": "loading"
+      },
+      {
+        "description": "The current level has no items.",
+        "name": "empty"
+      }
+    ],
+    "status": "beta",
+    "synonyms": {
+      "hierarchy": [
+        "tree",
+        "nav",
+        "drilldown"
+      ],
+      "miller": [
+        "drilldown",
+        "tree",
+        "column"
+      ],
+      "navigator": [
+        "tree",
+        "nav",
+        "drilldown",
+        "sidebar"
+      ]
+    },
+    "tag": "drilldown-ui",
+    "tokens": {
+      "--drilldown-bg-active": {
+        "description": "Row background when focused/active (roving tabindex)."
+      },
+      "--drilldown-bg-hover": {
+        "description": "Row background on hover."
+      },
+      "--drilldown-count-chip-font-size": {
+        "description": "Font size of a trailing count chip."
+      },
+      "--drilldown-count-chip-px": {
+        "description": "Inline padding of a trailing count chip."
+      },
+      "--drilldown-count-chip-radius": {
+        "description": "Border radius of a trailing count chip."
+      },
+      "--drilldown-dot-size": {
+        "description": "Diameter of the leading color dot."
+      },
+      "--drilldown-duration": {
+        "description": "Slide-transition duration."
+      },
+      "--drilldown-easing": {
+        "description": "Slide-transition easing function."
+      },
+      "--drilldown-fg": {
+        "description": "Primary row text color."
+      },
+      "--drilldown-fg-muted": {
+        "description": "Muted text color (meta line, chevron, back affordance)."
+      },
+      "--drilldown-focus-ring": {
+        "description": "Focus ring box-shadow for rows and the back button."
+      },
+      "--drilldown-header-px": {
+        "description": "Inline padding of the level header."
+      },
+      "--drilldown-header-py": {
+        "description": "Block padding of the level header."
+      },
+      "--drilldown-row-gap": {
+        "description": "Gap between row elements (dot / main / counts / chevron)."
+      },
+      "--drilldown-row-height": {
+        "description": "Height of each row."
+      },
+      "--drilldown-row-px": {
+        "description": "Inline padding of each row."
+      },
+      "--drilldown-row-radius": {
+        "description": "Border radius of each row."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}