@adia-ai/web-components 0.6.20 → 0.6.22

package/components/inspector/inspector.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Inspector.json",
   "title": "Inspector",
-  "description": "Developer tools pane for inspecting A2UI state.",
+  "description": "Developer-tools pane for inspecting A2UI runtime state — composes\n<tabs-ui> + <code-ui> to show the live document JSON, rendered\nHTML, and event log for the bound <canvas-ui> / <a2ui-root>. The\nright-pane inspector of the a2ui-editor app. Use inside an\n<editor-sidebar slot=\"trailing\"> for debugging A2UI playgrounds;\nnot for end-user inspector panes (build those bespoke with\n<field-ui> + form rows per the editor-inspector-pane recipe in\npatterns-recipes.md).\n",
   "type": "object",
   "allOf": [
     {
@@ -46,7 +46,12 @@
       "inspector"
     ],
     "name": "UIInspector",
-    "related": [],
+    "related": [
+      "A2uiRoot",
+      "EditorSidebar",
+      "Code",
+      "Tabs"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."

package/components/inspector/inspector.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<inspector-ui>` — Developer tools pane for inspecting A2UI state.
+ * `<inspector-ui>` — Developer-tools pane for inspecting A2UI runtime state — composes
+<tabs-ui> + <code-ui> to show the live document JSON, rendered
+HTML, and event log for the bound <canvas-ui> / <a2ui-root>. The
+right-pane inspector of the a2ui-editor app. Use inside an
+<editor-sidebar slot="trailing"> for debugging A2UI playgrounds;
+not for end-user inspector panes (build those bespoke with
+<field-ui> + form rows per the editor-inspector-pane recipe in
+patterns-recipes.md).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/inspector
  *

package/components/inspector/inspector.yaml

@@ -4,7 +4,15 @@ tag: inspector-ui
 component: Inspector
 category: agent
 version: 1
-description: Developer tools pane for inspecting A2UI state.
+description: |
+  Developer-tools pane for inspecting A2UI runtime state — composes
+  <tabs-ui> + <code-ui> to show the live document JSON, rendered
+  HTML, and event log for the bound <canvas-ui> / <a2ui-root>. The
+  right-pane inspector of the a2ui-editor app. Use inside an
+  <editor-sidebar slot="trailing"> for debugging A2UI playgrounds;
+  not for end-user inspector panes (build those bespoke with
+  <field-ui> + form rows per the editor-inspector-pane recipe in
+  patterns-recipes.md).
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -26,7 +34,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Developer-tools pane for A2UI runtime state — composes <tabs-ui> + <code-ui> internally.'
+      reason: 'Devtools composition.'
+    - rule: 'Binds to a <canvas-ui> / <a2ui-root> via value= or implicit selector; shows live doc JSON + rendered HTML + event log.'
+      reason: 'Binding contract.'
+    - rule: 'Use only in dev/debug surfaces; not for product UI.'
+      reason: 'Surface scope.'
+    - rule: 'Place in a right-pane inside <editor-shell-ui>''s editor-sidebar slot for editor-style inspector layouts.'
+      reason: 'Canonical inspector placement.'
 anti_patterns: []
 examples:
 - name: basic-inspector
@@ -42,4 +58,8 @@ synonyms:
   - property-grid
   - record-detail
   - devtools-pane
-related: []
+related:
+  - A2uiRoot
+  - EditorSidebar
+  - Code
+  - Tabs

package/components/kbd/kbd.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Kbd.json",
   "title": "Kbd",
-  "description": "Keyboard key cap. Purely decorative, content from innerHTML.",
+  "description": "Keyboard key cap. Purely decorative, content from innerHTML — typically a single key or short chord like \"⌘K\" or \"Ctrl+Shift+P\". Use inline in menu items, tooltips, command hints, and shortcut documentation.",
   "type": "object",
   "allOf": [
     {

package/components/kbd/kbd.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<kbd-ui>` — Keyboard key cap. Purely decorative, content from innerHTML.
+ * `<kbd-ui>` — Keyboard key cap. Purely decorative, content from innerHTML — typically a single key or short chord like "⌘K" or "Ctrl+Shift+P". Use inline in menu items, tooltips, command hints, and shortcut documentation.
  *
  * @see https://ui-kit.exe.xyz/site/components/kbd
  *

package/components/kbd/kbd.yaml

@@ -4,7 +4,10 @@ tag: kbd-ui
 component: Kbd
 category: display
 version: 1
-description: Keyboard key cap. Purely decorative, content from innerHTML.
+description: >-
+  Keyboard key cap. Purely decorative, content from innerHTML — typically
+  a single key or short chord like "⌘K" or "Ctrl+Shift+P". Use inline in
+  menu items, tooltips, command hints, and shortcut documentation.
 props:
   size:
     description: Sizing scale (compact tier — sm / md only).
@@ -24,7 +27,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Inline-only — content from innerHTML, typically one or two key labels.'
+      reason: 'Decorative; do not place block content inside.'
+    - rule: 'In menu items, use the kbd= attribute on <menu-item-ui> instead of nesting <kbd-ui> directly.'
+      reason: 'Menu-item has positioning logic for shortcut hints.'
+    - rule: 'Chord notation uses + between keys (Ctrl+Shift+P); platform-symbol variants ⌘⌥⇧ are fine.'
+      reason: 'Convention for cross-platform docs.'
 anti_patterns: []
 examples:
 - name: kbd-shortcuts

package/components/list/list-item.a2ui.json

@@ -39,12 +39,30 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "list-item",
+      "list-row",
+      "list-entry",
+      "item-row",
+      "row"
+    ],
     "name": "UIListItem",
-    "related": [],
+    "related": [
+      "List",
+      "NavItem",
+      "MenuItem",
+      "TreeItem"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "list-item": [
+        "row",
+        "entry",
+        "list-row",
+        "item"
+      ]
+    },
     "tag": "list-item-ui",
     "tokens": {},
     "traits": [],

package/components/list/list-item.yaml

@@ -27,3 +27,28 @@ props:
   description:
     description: Secondary line below the primary text. Subtle color.
     type: string
+
+keywords:
+  - list-item
+  - list-row
+  - list-entry
+  - item-row
+  - row
+
+synonyms:
+  list-item: [row, entry, list-row, item]
+
+related:
+  - List
+  - NavItem
+  - MenuItem
+  - TreeItem
+
+a2ui:
+  rules:
+    - rule: 'Child of <list-ui> — one row of generic-list content.'
+      reason: 'Cluster contract.'
+    - rule: 'For navigation lists use <nav-item-ui> inside <nav-ui>; for menu items use <menu-item-ui>; for tree rows use <tree-item-ui>.'
+      reason: 'Per-context list-row primitives — list-item is generic.'
+    - rule: 'Interactive list-items should have role=''button'' or be wrapped in <button-ui>; default is non-interactive.'
+      reason: 'Accessibility — semantic clarity.'

package/components/list/list.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/List.json",
   "title": "List",
-  "description": "Styled list with optional icons and dividers.",
+  "description": "Styled flat list with optional row dividers and icons — each row\nis a <list-item-ui> child. Selectable mode via [selectable] +\n[selectedKey] / `select` event. Composes <icon-ui> for row leading\nglyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),\n<tree-ui> (hierarchical with arbitrary nesting), and <table-ui>\n(tabular data with columns). Use list-ui for non-navigable,\nnon-tabular vertical rows — comment lists, file lists, message\nstreams outside chat-shell.\n",
   "type": "object",
   "allOf": [
     {
@@ -79,7 +79,12 @@
       "star"
     ],
     "name": "UIList",
-    "related": [],
+    "related": [
+      "ListItem",
+      "Tree",
+      "Nav",
+      "Table"
+    ],
     "slots": {},
     "states": [
       {

package/components/list/list.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<list-ui>` — Styled list with optional icons and dividers.
+ * `<list-ui>` — Styled flat list with optional row dividers and icons — each row
+is a <list-item-ui> child. Selectable mode via [selectable] +
+[selectedKey] / `select` event. Composes <icon-ui> for row leading
+glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
+<tree-ui> (hierarchical with arbitrary nesting), and <table-ui>
+(tabular data with columns). Use list-ui for non-navigable,
+non-tabular vertical rows — comment lists, file lists, message
+streams outside chat-shell.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/list
  *

package/components/list/list.yaml

@@ -6,7 +6,15 @@ tag: list-ui
 component: List
 category: layout
 version: 1
-description: Styled list with optional icons and dividers.
+description: |
+  Styled flat list with optional row dividers and icons — each row
+  is a <list-item-ui> child. Selectable mode via [selectable] +
+  [selectedKey] / `select` event. Composes <icon-ui> for row leading
+  glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),
+  <tree-ui> (hierarchical with arbitrary nesting), and <table-ui>
+  (tabular data with columns). Use list-ui for non-navigable,
+  non-tabular vertical rows — comment lists, file lists, message
+  streams outside chat-shell.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -46,7 +54,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Generic vertical list container — hosts <list-item-ui> or arbitrary children.'
+      reason: 'Lowest-friction list primitive.'
+    - rule: 'For interactive selection lists use <nav-ui> (single-select navigation) or <menu-ui> (action menu); list-ui is content display.'
+      reason: 'Different interaction contracts.'
+    - rule: 'For data-grid / sortable / sticky-header needs use <table-ui> instead.'
+      reason: 'Table has different semantics.'
 anti_patterns: []
 examples:
   - name: basic-list
@@ -103,4 +117,8 @@ synonyms:
     - bookmark
     - list
     - leaderboard
-related: []
+related:
+  - ListItem
+  - Tree
+  - Nav
+  - Table

package/components/menu/menu-divider.a2ui.json

@@ -27,12 +27,26 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "menu-divider",
+      "separator",
+      "menu-rule"
+    ],
     "name": "UIMenuDivider",
-    "related": [],
+    "related": [
+      "Menu",
+      "MenuItem",
+      "Divider"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "menu-divider": [
+        "menu-separator",
+        "menu-rule",
+        "popover-divider"
+      ]
+    },
     "tag": "menu-divider-ui",
     "tokens": {},
     "traits": [],

package/components/menu/menu-divider.yaml

@@ -13,3 +13,38 @@ category: navigation
 version: 1
 description: |-
   Visual separator between groups of `<menu-item-ui>` rows. Renders as a horizontal rule with role="separator".
+
+a2ui:
+  rules:
+    - >-
+      <menu-divider-ui> MUST be a direct child of <menu-ui>; a raw
+      <hr> will render OUTSIDE the popover because <menu-ui> only
+      hoists <menu-item-ui> and <menu-divider-ui> children via its
+      direct-child selector.
+    - >-
+      Use to group items by semantic tier — primary actions →
+      secondary → destructive (danger). Avoid leading / trailing
+      dividers and consecutive dividers; they produce visual noise
+      without grouping value.
+    - >-
+      Do not place a divider as the first or last child of <menu-ui> —
+      the top / bottom popover padding already provides separation
+      from the chrome.
+    - >-
+      Has no props, slots, or events. Treat as an inert separator with
+      role="separator". If you need a labeled group, split into
+      multiple <menu-ui> instances stacked, not custom content inside
+      a divider.
+
+keywords:
+  - menu-divider
+  - separator
+  - menu-rule
+
+related:
+  - Menu
+  - MenuItem
+  - Divider
+
+synonyms:
+  menu-divider: [menu-separator, menu-rule, popover-divider]

package/components/menu/menu-item.a2ui.json

@@ -56,9 +56,19 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "menu-item",
+      "menu-row",
+      "popover-action",
+      "dropdown-item"
+    ],
     "name": "UIMenuItem",
-    "related": [],
+    "related": [
+      "Menu",
+      "MenuDivider",
+      "Button",
+      "NavItem"
+    ],
     "slots": {
       "icon": {
         "description": "Custom leading element override; falls through to `[icon]` prop if not slotted."
@@ -68,7 +78,13 @@
       }
     },
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "menu-item": [
+        "dropdown-item",
+        "menu-row",
+        "popover-action"
+      ]
+    },
     "tag": "menu-item-ui",
     "tokens": {},
     "traits": [],

package/components/menu/menu-item.yaml

@@ -43,3 +43,45 @@ slots:
     description: Custom leading element override; falls through to `[icon]` prop if not slotted.
   text:
     description: Custom label content; falls through to `[text]` prop if not slotted.
+
+a2ui:
+  rules:
+    - >-
+      <menu-item-ui> MUST be a direct child of <menu-ui>; do not place
+      inside arbitrary containers or other components — <menu-ui>
+      hoists items into its top-layer popover via a `:scope > menu-item-ui`
+      selector that requires direct descendancy.
+    - >-
+      Always set a stable [value] — it is the only identifier surfaced
+      on the parent's `action` event detail. [text] is the visible
+      label; optional [icon] is a Phosphor icon name shown leading the
+      label.
+    - >-
+      Use [variant="danger"] exclusively for destructive / irreversible
+      actions (Delete, Remove). "Sign out" is NOT danger. Pair danger
+      items with an explicit confirm flow (<modal-ui> destructive-confirm
+      pattern) when the action cannot be undone.
+    - >-
+      Set [disabled] (not [hidden]) when an action is contextually
+      unavailable — disabled items remain visible for affordance
+      discoverability but skip roving focus + don't fire `action`.
+    - >-
+      Prefer [icon] + [text] props over slotted markup for consistency.
+      Use slot="icon" / slot="text" only when you need custom markup
+      (e.g. <avatar-ui slot="icon">, <kbd slot="trailing"> shortcut
+      hint).
+
+keywords:
+  - menu-item
+  - menu-row
+  - popover-action
+  - dropdown-item
+
+related:
+  - Menu
+  - MenuDivider
+  - Button
+  - NavItem
+
+synonyms:
+  menu-item: [dropdown-item, menu-row, popover-action]

package/components/menu/menu.a2ui.json

@@ -81,7 +81,13 @@
       "right-click"
     ],
     "name": "UIMenu",
-    "related": [],
+    "related": [
+      "MenuItem",
+      "MenuDivider",
+      "Popover",
+      "Command",
+      "Button"
+    ],
     "slots": {
       "default": {
         "description": "Menu items with role=\"menuitem\" and optional <hr> dividers"

package/components/menu/menu.yaml

@@ -49,7 +49,33 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      <menu-ui> MUST have exactly one child with slot="trigger" (typically
+      <button-ui>, but any focusable element works). Without it the menu
+      cannot open. The trigger lives in light DOM; the items are hoisted
+      to a top-layer popover on open.
+    - >-
+      Default slot accepts only <menu-item-ui> and <menu-divider-ui>
+      children — no submenus, headers, or arbitrary content. Roving
+      tabindex + Arrow / Home / End / Enter / Escape keyboard nav is
+      built in.
+    - >-
+      Listen for the `action` event on <menu-ui> (or an ancestor —
+      bubbles). Detail = { value, text }. Do NOT treat menu-ui as a
+      value-holder; for single-select form input use <select-ui>
+      instead. Menu fires actions, doesn't store state.
+    - >-
+      Use <menu-ui> for transient action surfaces (kebab / ⋯ row
+      actions, workspace / user switchers, view-as toggles). For
+      persistent side navigation use <nav-ui>; for inline (non-popover)
+      command lists use <action-list-ui>; for searchable command
+      palettes use <command-ui> inside <admin-command>.
+    - >-
+      Set [placement="top-start"] or [placement="top-end"] when the
+      trigger sits near the bottom of the viewport (statusbar / footer
+      menus); default [placement="bottom-start"] otherwise. Adjust
+      [gap] (default 4px) only when chrome demands it.
 anti_patterns: []
 examples:
   - name: basic-menu
@@ -123,4 +149,9 @@ synonyms:
   right-click:
     - popover
     - menu
-related: []
+related:
+  - MenuItem
+  - MenuDivider
+  - Popover
+  - Command
+  - Button

package/components/modal/modal.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Modal.json",
   "title": "Modal",
-  "description": "Centered dialog overlay using native <dialog>. Focus trapping, Escape key, backdrop.",
+  "description": "Centered dialog overlay using native <dialog> — same portal /\nbackdrop / focus-trap / Escape-dismiss primitives as <drawer-ui>,\nbut anchored to the viewport center with size presets. Canonical\ninner shape mirrors drawer / card: <header> + one or more <section>\n+ optional <footer>. The header stamps a built-in title bar from\n[text] plus an auto-close button (unless [permanent]). Use modal-ui\nfor centered confirmations, destructive prompts, transient previews,\nand short focused interactions; use <drawer-ui> instead for\nedge-anchored multi-field editors and mobile sheet patterns.\n",
   "type": "object",
   "allOf": [
     {
@@ -67,7 +67,12 @@
       "modal"
     ],
     "name": "UIModal",
-    "related": [],
+    "related": [
+      "Drawer",
+      "Card",
+      "Popover",
+      "AdminCommand"
+    ],
     "slots": {
       "default": {
         "description": "Content placed inside the modal surface. Accepts any elements (card-ui, command-ui, custom markup)."

package/components/modal/modal.d.ts

@@ -1,5 +1,14 @@
 /**
- * `<modal-ui>` — Centered dialog overlay using native <dialog>. Focus trapping, Escape key, backdrop.
+ * `<modal-ui>` — Centered dialog overlay using native <dialog> — same portal /
+backdrop / focus-trap / Escape-dismiss primitives as <drawer-ui>,
+but anchored to the viewport center with size presets. Canonical
+inner shape mirrors drawer / card: <header> + one or more <section>
++ optional <footer>. The header stamps a built-in title bar from
+[text] plus an auto-close button (unless [permanent]). Use modal-ui
+for centered confirmations, destructive prompts, transient previews,
+and short focused interactions; use <drawer-ui> instead for
+edge-anchored multi-field editors and mobile sheet patterns.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/modal
  *

package/components/modal/modal.yaml

@@ -4,7 +4,16 @@ tag: modal-ui
 component: Modal
 category: container
 version: 1
-description: Centered dialog overlay using native <dialog>. Focus trapping, Escape key, backdrop.
+description: |
+  Centered dialog overlay using native <dialog> — same portal /
+  backdrop / focus-trap / Escape-dismiss primitives as <drawer-ui>,
+  but anchored to the viewport center with size presets. Canonical
+  inner shape mirrors drawer / card: <header> + one or more <section>
+  + optional <footer>. The header stamps a built-in title bar from
+  [text] plus an auto-close button (unless [permanent]). Use modal-ui
+  for centered confirmations, destructive prompts, transient previews,
+  and short focused interactions; use <drawer-ui> instead for
+  edge-anchored multi-field editors and mobile sheet patterns.
 props:
   open:
     description: Controls overlay visibility. Setting to true opens the surface with entry animation.
@@ -57,7 +66,39 @@ tokens:
   --modal-shadow:
     description: Override surface box shadow
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Reflect modal visibility via the [open] boolean attribute on the
+      host (open=true / open=false). Do NOT toggle [hidden], CSS
+      display, or wrap in a sibling visibility container — modal-ui
+      owns the native <dialog> lifecycle, focus trap, ::backdrop, and
+      Escape-dismiss. Listen for the `close` event to react to
+      dismiss.
+    - >-
+      Compose modal-ui with the same triplet as drawer-ui / card-ui:
+      <header> (or [slot="header"]) + <section> (or default body) +
+      <footer> (or [slot="footer"]). Set the title via [text] (which
+      stamps the heading + aria-label) or a <span slot="heading">. Do
+      not author your own close button unless using [permanent].
+    - >-
+      Use modal-ui (centered, interruptive) for short confirmations,
+      destructive prompts, and transient previews — typically ≤2 form
+      fields or a single decision. For edge-anchored multi-field detail
+      editors and mobile sheets, use <drawer-ui> instead. The
+      destructive-confirm-modal pattern lives at
+      catalog/ui-patterns/app/destructive-confirm-modal/ as the
+      canonical reference.
+    - >-
+      modal-ui is NOT the Cmd+K command palette. The palette is a
+      bespoke shell-tier component (<admin-command> under <admin-shell>);
+      do not model command palettes as modal-ui surfaces even though
+      the visual is overlay-like. The palette owns its own keyboard /
+      filter loop.
+    - >-
+      Use [size] presets (sm = 24rem | md = 32rem | lg = 48rem | xl =
+      95vw) to scale width. Do not override width with inline style or
+      wrap modal-ui in a sizing container — the [size] attribute is
+      the only supported width contract.
 anti_patterns: []
 examples:
 - name: basic-modal
@@ -70,4 +111,8 @@ keywords:
 synonyms:
   tags:
   - Dialog
-related: []
+related:
+  - Drawer
+  - Card
+  - Popover
+  - AdminCommand

package/components/nav/nav.a2ui.json

@@ -93,7 +93,13 @@
       "links"
     ],
     "name": "UINav",
-    "related": [],
+    "related": [
+      "NavGroup",
+      "NavItem",
+      "Tabs",
+      "Breadcrumb",
+      "AdminSidebar"
+    ],
     "slots": {
       "default": {
         "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
@@ -109,7 +115,15 @@
         "name": "collapsed"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "nav": [
+        "sidebar",
+        "side-nav",
+        "navigation-rail",
+        "primary-nav",
+        "section-nav"
+      ]
+    },
     "tag": "nav-ui",
     "tokens": {},
     "traits": [],