@adia-ai/web-components 0.6.21 → 0.6.22

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": [],

package/components/nav/nav.yaml

@@ -66,7 +66,38 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Composition: place <nav-ui> inside <admin-sidebar slot="leading">
+      wrapped in <section-ui> for app sidebars; inside an
+      <aside data-subnav> with variant="section" for section / subnav
+      rails; standalone on docs / auth pages. Children: <nav-group-ui>,
+      <nav-item-ui>, optional <hr data-nav-divider>.
+    - >-
+      Variants: variant="primary" (default) — app sidebar; ResizeObserver
+      collapses to icon-only ≤96px; collapsible groups open as a popover
+      when collapsed. variant="section" — subnav rail; quieter chrome;
+      optional [heading] kicker rendered via ::before.
+    - >-
+      Section-variant cascade (ADR-0015 § Nav consolidation):
+      variant="section" on <nav-ui> cascades visually to direct
+      <nav-group-ui> / <nav-item-ui> descendants via CSS
+      `:not([variant])`. Children's JS state is NOT mutated; the cascade
+      is purely visual. Explicit [variant] on a child always wins — use
+      it to escape the cascade or style a standalone group/item.
+    - >-
+      Decision rule: if the user navigates AWAY (different page, route,
+      or anchor) → <nav-ui>. If the user switches VIEWS within the same
+      logical page → <tabs-ui>. Never use <nav-ui> as an in-page section
+      switcher.
+    - >-
+      Anti-patterns: do NOT wrap <nav-ui> children in <col-ui> /
+      <row-ui> — wrapping breaks selection bubbling + the variant
+      cascade. Do NOT nest <nav-ui> inside <nav-ui>. The legacy 6-element
+      family (<app-nav-ui> / <section-nav-ui> / <app-nav-item-ui> /
+      <section-nav-item-ui> / <app-nav-group-ui> / <section-nav-group-ui>)
+      was retired in ADR-0015 — only <nav-ui> / <nav-group-ui> /
+      <nav-item-ui> remain.
 anti_patterns: []
 
 examples:
@@ -126,5 +157,11 @@ examples:
       ]
 
 keywords: [nav, navigation, sidebar, menu, links]
-synonyms: {}
-related: []
+synonyms:
+  nav: [sidebar, side-nav, navigation-rail, primary-nav, section-nav]
+related:
+  - NavGroup
+  - NavItem
+  - Tabs
+  - Breadcrumb
+  - AdminSidebar

package/components/nav-group/nav-group.a2ui.json

@@ -87,7 +87,11 @@
       "menu"
     ],
     "name": "UINavGroup",
-    "related": [],
+    "related": [
+      "Nav",
+      "NavItem",
+      "Accordion"
+    ],
     "slots": {
       "default": {
         "description": "Children — typically <nav-item-ui> rows."
@@ -106,7 +110,13 @@
         "name": "open"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "nav-group": [
+        "nav-section",
+        "sidebar-group",
+        "menu-group"
+      ]
+    },
     "tag": "nav-group-ui",
     "tokens": {},
     "traits": [],

package/components/nav-group/nav-group.yaml

@@ -72,10 +72,44 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Composition: <nav-group-ui> MUST be a direct child of <nav-ui>
+      (or standalone with explicit variant="section" outside a rail).
+      Default slot accepts <nav-item-ui> children; do NOT wrap them in
+      layout primitives — selection, keyboard, and the section-variant
+      cascade all rely on direct descendancy.
+    - >-
+      Variant cascade: when parent <nav-ui variant="section">, this
+      group inherits section styling (static kicker header, children
+      always visible) via CSS — without touching its JS state. Set
+      [variant="section"] explicitly only when there is no <nav-ui>
+      parent, OR to override a primary-rail context.
+    - >-
+      Collapsibility: primary variant — [collapsible] (default true)
+      toggles [open] via header click / Enter / Space; fires
+      `group-toggle` event with detail {text, open}. When the parent
+      <nav-ui> is collapsed to icon-only, the header opens a popover
+      with this group's children instead. Section variant ignores
+      [open] / [collapsible] (children always visible).
+    - >-
+      Decision rule: use <nav-group-ui> to group ≥2 related navigation
+      links under one label inside <nav-ui>. For a single link, use
+      <nav-item-ui> directly. For switching sub-views inside one page,
+      use <tabs-ui> / <tab-ui>, never <nav-group-ui>.
+    - >-
+      Anti-patterns: do NOT nest <nav-group-ui> inside another
+      <nav-group-ui> (flatten the hierarchy or split into two groups).
+      Do NOT place non-<nav-item-ui> content in the default slot. Do
+      NOT use it as a generic disclosure — for that use <accordion-ui>
+      or <details>.
 anti_patterns: []
 examples: []
 
 keywords: [nav, navigation, group, sidebar, menu]
-synonyms: {}
-related: []
+synonyms:
+  nav-group: [nav-section, sidebar-group, menu-group]
+related:
+  - Nav
+  - NavItem
+  - Accordion