@adia-ai/web-components 0.6.21 → 0.6.23

package/components/textarea/textarea.yaml

@@ -6,7 +6,15 @@ tag: textarea-ui
 component: Textarea
 category: layout
 version: 1
-description: Multiline text input. The host IS the interactive surface.
+description: |
+  Multi-line text input primitive — the host IS the contenteditable
+  surface (per ADR-0025, no native <textarea> wrapped underneath).
+  Form-bearing via UIFormElement: [name], [value], [required],
+  [disabled], [readonly], fires `change` on blur and `input` per
+  keystroke. Enter inserts a newline — does NOT fire `submit` (for
+  Enter-to-send composers use <chat-input-ui submit-on-enter> inside
+  <chat-composer>). Wrap in <field-ui label="…"> for the canonical
+  labeled stack.
 props:
   disabled:
     description: Disables interaction, removes contenteditable, and dims the control. Inherited from UIFormElement.
@@ -86,7 +94,31 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      <textarea-ui> is the canonical multi-line text input. The host
+      IS the contenteditable surface — NEVER use a native <textarea>
+      (banned by ADR-0025).
+    - >-
+      Wrap <textarea-ui> in <field-ui label="…" hint="…" error="…"> for
+      the canonical labeled stack. The inline [label] / [hint] /
+      [error] props are also supported on the primitive for compact
+      use.
+    - >-
+      Form participation is implicit via UIFormElement. Set [name] for
+      FormData submission; [required] / [disabled] / [readonly]
+      reflect; listen for `change` (on blur after value change) and
+      `input` (per keystroke).
+    - >-
+      Use [rows] to set initial height (default 3) and [resize]
+      (vertical | horizontal | both | none; default vertical) to
+      control user resize. Never substitute a native <textarea> just
+      to get rows / resize.
+    - >-
+      Enter inserts a newline — <textarea-ui> does NOT emit a `submit`
+      event. For Enter-to-send multi-line composers, use
+      <chat-input-ui submit-on-enter> inside <chat-composer>, not
+      textarea-ui.
 anti_patterns: []
 examples:
   - name: basic-textarea
@@ -116,5 +148,10 @@ examples:
       ]
 keywords:
   - textarea
-synonyms: {}
-related: []
+synonyms:
+  textarea: [multiline-input, text-area, comment-input, long-text-input]
+related:
+  - Input
+  - Field
+  - ChatInput
+  - Code

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

@@ -62,12 +62,29 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "timeline-item",
+      "timeline-row",
+      "activity-entry",
+      "event-entry",
+      "history-row"
+    ],
     "name": "UITimelineItem",
-    "related": [],
+    "related": [
+      "Timeline",
+      "FeedItem",
+      "Stepper"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "timeline-item": [
+        "timeline-row",
+        "activity-row",
+        "event-row",
+        "history-entry"
+      ]
+    },
     "tag": "timeline-item-ui",
     "tokens": {},
     "traits": [],

package/components/timeline/timeline-item.yaml

@@ -45,3 +45,27 @@ props:
     description: Show a spinner instead of the icon while status=pending.
     type: boolean
     default: false
+
+keywords:
+  - timeline-item
+  - timeline-row
+  - activity-entry
+  - event-entry
+  - history-row
+
+synonyms:
+  timeline-item: [timeline-row, activity-row, event-row, history-entry]
+
+related:
+  - Timeline
+  - FeedItem
+  - Stepper
+
+a2ui:
+  rules:
+    - rule: 'Child of <timeline-ui> — one chronological event with timestamp + content + optional icon dot.'
+      reason: 'Timeline cluster contract.'
+    - rule: 'Different from <stepper-item-ui> (process steps with completion state) — timeline-item is event history.'
+      reason: 'Process vs history.'
+    - rule: 'Order is DOM-order — no auto-sort by timestamp.'
+      reason: 'Author-controlled order.'

package/components/timeline/timeline.a2ui.json

@@ -81,7 +81,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "timeline": [
+        "activity-log",
+        "event-log",
+        "history",
+        "audit-trail"
+      ]
+    },
     "tag": "timeline-ui",
     "tokens": {},
     "traits": [],

package/components/timeline/timeline.yaml

@@ -44,7 +44,13 @@ requiredIcons:
   - caret-down
   - caret-right
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for chronological event lists (audit log, activity feed, version history).'
+      reason: 'Visual rhythm: line + dot + content per row.'
+    - rule: 'Hosts <timeline-item-ui> children only.'
+      reason: 'Cluster contract — children are family-scoped.'
+    - rule: 'For multi-step processes with progress state use <stepper-ui> instead; timeline is read-only history.'
+      reason: 'Stepper has current/upcoming/complete states; timeline is event-time.'
 anti_patterns: []
 examples:
   - name: order-tracking
@@ -188,6 +194,7 @@ examples:
       ]
 keywords:
   - timeline
-synonyms: {}
+synonyms:
+  timeline: [activity-log, event-log, history, audit-trail]
 related:
   - timeline-item

package/components/toast/toast.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Toast.json",
   "title": "Toast",
-  "description": "Notification popup with auto-dismiss. Animated enter/exit.",
+  "description": "Transient global notification popup with auto-dismiss + animated\nenter/exit. Variants map to severity (info / success / warning /\ndanger). Distinct from <alert-ui> (inline persistent banner) and\n<empty-state-ui> (zero-data placeholder). Use toast-ui for\nshort-lived feedback after user actions (\"Saved\", \"Copied to\nclipboard\"); the toast positions itself relative to viewport\n[position] regardless of where in the DOM it's rendered.\n",
   "type": "object",
   "allOf": [
     {
@@ -86,7 +86,11 @@
       "alert"
     ],
     "name": "UIToast",
-    "related": [],
+    "related": [
+      "Feed",
+      "Alert",
+      "FeedItem"
+    ],
     "slots": {},
     "states": [
       {

package/components/toast/toast.yaml

@@ -6,7 +6,14 @@ tag: toast-ui
 component: Toast
 category: container
 version: 1
-description: Notification popup with auto-dismiss. Animated enter/exit.
+description: |
+  Transient global notification popup with auto-dismiss + animated
+  enter/exit. Variants map to severity (info / success / warning /
+  danger). Distinct from <alert-ui> (inline persistent banner) and
+  <empty-state-ui> (zero-data placeholder). Use toast-ui for
+  short-lived feedback after user actions ("Saved", "Copied to
+  clipboard"); the toast positions itself relative to viewport
+  [position] regardless of where in the DOM it's rendered.
 props:
   duration:
     description: Auto-dismiss time in milliseconds. 0 disables auto-dismiss.
@@ -73,7 +80,13 @@ tokens:
   --toast-foreground:
     description: Override text color
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Single ephemeral notification item — auto-dismissing or manually-closable.'
+      reason: 'Toast pattern.'
+    - rule: 'Typically posted into <feed-ui> via UIFeed.post(...); for inline persistent alerts use <alert-ui> instead.'
+      reason: 'Posting model + surface boundary.'
+    - rule: 'Variant maps to severity (info, success, warn, error); same tokens as <alert-ui>.'
+      reason: 'Visual consistency.'
 anti_patterns: []
 examples:
   - name: toast-notification
@@ -184,4 +197,7 @@ synonyms:
     - alert
     - error
     - toast
-related: []
+related:
+  - Feed
+  - Alert
+  - FeedItem

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ToggleGroup.json",
   "title": "ToggleGroup",
-  "description": "Multi-select button group (unlike segmented which is single-select).",
+  "description": "Multi-select button group (unlike <segmented-ui> which is single-select). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set. Use for filter chips or feature flag clusters; for single-select option groups use <segmented-ui> instead.",
   "type": "object",
   "allOf": [
     {
@@ -60,7 +60,11 @@
       "group"
     ],
     "name": "UIToggleGroup",
-    "related": [],
+    "related": [
+      "ToggleOption",
+      "Segmented",
+      "Radio"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."
@@ -72,7 +76,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "toggle-group": [
+        "segmented-control",
+        "option-group",
+        "toggle-set"
+      ]
+    },
     "tag": "toggle-group-ui",
     "tokens": {
       "--toggle-group-border": {

package/components/toggle-group/toggle-group.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<toggle-group-ui>` — Multi-select button group (unlike segmented which is single-select).
+ * `<toggle-group-ui>` — Multi-select button group (unlike <segmented-ui> which is single-select). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set. Use for filter chips or feature flag clusters; for single-select option groups use <segmented-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/toggle-group
  *

package/components/toggle-group/toggle-group.yaml

@@ -6,7 +6,12 @@ tag: toggle-group-ui
 component: ToggleGroup
 category: navigation
 version: 1
-description: Multi-select button group (unlike segmented which is single-select).
+description: >-
+  Multi-select button group (unlike <segmented-ui> which is
+  single-select). Hosts <toggle-option-ui> children, each independently
+  toggleable; emits change events with the active value set. Use for
+  filter chips or feature flag clusters; for single-select option groups
+  use <segmented-ui> instead.
 props:
   single:
     description: When true, restrict to one active option (single-select).
@@ -66,7 +71,13 @@ tokens:
   --toggle-option-selected-fg:
     description: Text color when selected
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Multi-select button cluster — hosts <toggle-option-ui> children, each independently toggleable.'
+      reason: 'Multi-select cluster contract.'
+    - rule: 'Different from <segmented-ui> (single-select) — toggle-group emits a SET of active values.'
+      reason: 'Selection model distinction.'
+    - rule: 'Use for filter chips, multi-flag toggles, day-of-week pickers; for binary on/off use <switch-ui>.'
+      reason: 'Capacity guidance.'
 anti_patterns: []
 examples:
   - name: basic-toggle-group
@@ -98,5 +109,9 @@ keywords:
   - toggle-group
   - toggle
   - group
-synonyms: {}
-related: []
+synonyms:
+  toggle-group: [segmented-control, option-group, toggle-set]
+related:
+  - ToggleOption
+  - Segmented
+  - Radio

package/components/toggle-group/toggle-option.a2ui.json

@@ -47,12 +47,27 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "toggle-option",
+      "toggle-segment",
+      "option-toggle",
+      "segmented-option"
+    ],
     "name": "UIToggleOption",
-    "related": [],
+    "related": [
+      "ToggleGroup",
+      "Segment",
+      "Radio"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "toggle-option": [
+        "toggle-segment",
+        "option-button",
+        "segmented-option"
+      ]
+    },
     "tag": "toggle-option-ui",
     "tokens": {},
     "traits": [],

package/components/toggle-group/toggle-option.yaml

@@ -31,3 +31,26 @@ props:
     description: Disabled state — blocks pointer + keyboard activation.
     type: boolean
     default: false
+
+keywords:
+  - toggle-option
+  - toggle-segment
+  - option-toggle
+  - segmented-option
+
+synonyms:
+  toggle-option: [toggle-segment, option-button, segmented-option]
+
+related:
+  - ToggleGroup
+  - Segment
+  - Radio
+
+a2ui:
+  rules:
+    - rule: 'Child of <toggle-group-ui> — one independently-toggleable button in a multi-select cluster.'
+      reason: 'Multi-select cluster contract.'
+    - rule: 'Different from <segment-ui> (which is single-select inside <segmented-ui>).'
+      reason: 'Selection model boundary.'
+    - rule: 'Active state controlled via the toggle-option''s own active attribute (independent of siblings).'
+      reason: 'Parent does not own state in multi-select.'

package/components/toggle-scheme/toggle-scheme.yaml

@@ -156,6 +156,10 @@ a2ui:
       <admin-content>. It is a persistent, app-wide preference control;
       never put it in a sidebar footer / <admin-statusbar>, which hosts
       user-account items only.
+    - rule: 'Stores user override in localStorage and writes color-scheme inline-style to the target; falls back to prefers-color-scheme if no override is set.'
+      reason: 'Behavior contract — explains why first-paint resolution happens correctly.'
+    - rule: 'Singleton per page — placing more than one in DOM creates conflicting writes to the same target.'
+      reason: 'Cardinality constraint.'
 anti_patterns: []
 examples:
   - name: header-action

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

@@ -27,12 +27,27 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "toolbar-group",
+      "button-group",
+      "action-cluster",
+      "toolbar-cluster"
+    ],
     "name": "UIToolbarGroup",
-    "related": [],
+    "related": [
+      "Toolbar",
+      "Button",
+      "Divider"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "toolbar-group": [
+        "button-group",
+        "action-cluster",
+        "toolbar-section"
+      ]
+    },
     "tag": "toolbar-group-ui",
     "tokens": {},
     "traits": [],

package/components/toolbar/toolbar-group.yaml

@@ -14,3 +14,26 @@ category: navigation
 version: 1
 description: |-
   Visual cluster of related actions inside a `<toolbar-ui>`. Provides role="group" for assistive-tech grouping; no own visual chrome beyond a margin-collapsing gap with sibling groups.
+
+keywords:
+  - toolbar-group
+  - button-group
+  - action-cluster
+  - toolbar-cluster
+
+synonyms:
+  toolbar-group: [button-group, action-cluster, toolbar-section]
+
+related:
+  - Toolbar
+  - Button
+  - Divider
+
+a2ui:
+  rules:
+    - rule: 'Child of <toolbar-ui> — clusters related action buttons with token-driven internal gap.'
+      reason: 'Visual grouping primitive.'
+    - rule: 'Separate clusters with <divider-ui> siblings inside <toolbar-ui>.'
+      reason: 'Convention for toolbar rhythm.'
+    - rule: 'Do not nest toolbar-groups; flat hierarchy only.'
+      reason: 'Visual complexity guard.'

package/components/toolbar/toolbar.yaml

@@ -41,7 +41,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Horizontal action bar — hosts <button-ui>, <toolbar-group-ui>, and <divider-ui> children.'
+      reason: 'Canonical action-row primitive.'
+    - rule: 'Cluster related buttons inside <toolbar-group-ui> with <divider-ui> separating clusters.'
+      reason: 'Visual grouping convention.'
+    - rule: 'For navigation use <nav-ui>; for modal/popover action bars use the modal''s footer slot. Toolbar is for inline action bars within content regions.'
+      reason: 'Context boundary.'
 anti_patterns: []
 examples:
   - name: toolbar-buttons

package/components/tooltip/tooltip.yaml

@@ -71,7 +71,30 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <tooltip-ui> to label icon-only <button-ui> elements
+      (text="Save" on a save-icon button, etc.) and for short
+      descriptive hover hints. Never use it for content the user
+      must read carefully (the bubble is transient + non-focusable).
+    - >-
+      Never place INTERACTIVE children inside <tooltip-ui> — it is a
+      read-only hint, not a surface. If the user must click or type,
+      use <popover-ui> instead. Tooltips never receive keyboard focus.
+    - >-
+      [follows="pointer"] mode requires [for] pointing at a <chart-ui>
+      or <heatmap-ui> [id]; the tooltip subscribes to that target's
+      `chart-hover` / `chart-leave` events to render data-viz
+      annotations that track the cursor. Without [for] the tooltip
+      renders nothing in pointer mode.
+    - >-
+      Set [delay=0] only for high-frequency exploratory surfaces
+      (sparkline ticks, chart hover). Keep the default 400ms delay
+      elsewhere to avoid hover noise.
+    - >-
+      [indicator] (dot | line | dashed) is meaningful only in pointer
+      mode for per-series swatches. Omit it or leave default "none"
+      for text-mode tooltips.
 anti_patterns: []
 examples:
   - name: tooltip-buttons

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

@@ -51,12 +51,28 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "tree-item",
+      "tree-row",
+      "tree-node",
+      "hierarchy-item"
+    ],
     "name": "UITreeItem",
-    "related": [],
+    "related": [
+      "Tree",
+      "List",
+      "Nav",
+      "Accordion"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "tree-item": [
+        "tree-node",
+        "tree-row",
+        "hierarchy-row"
+      ]
+    },
     "tag": "tree-item-ui",
     "tokens": {},
     "traits": [],

package/components/tree/tree-item.yaml

@@ -39,3 +39,45 @@ props:
 
       Added in §184 (v0.5.5, FEEDBACK-08 §1).
     type: string
+
+a2ui:
+  rules:
+    - >-
+      <tree-item-ui> MUST be a direct or nested descendant of
+      <tree-ui>. It is not a standalone primitive — outside a <tree-ui>
+      parent, selection / expansion / keyboard nav don't wire.
+    - >-
+      Provide a stable [value] attribute on every <tree-item-ui> that
+      consumers will select. The `tree-select` event's detail.value is
+      the identifier downstream code reads to know which node was
+      picked.
+    - >-
+      Use [open] to pre-expand branch nodes on initial render. Do NOT
+      set [selected] declaratively on more than one item — the parent
+      <tree-ui> manages selection. The host listens for click /
+      Enter / Space / ArrowRight (expand) / ArrowLeft (collapse) per
+      WAI-ARIA tree-view APG.
+    - >-
+      Use [icon] (Phosphor name) for affordance (folder / file /
+      component icons); use [badge] for counts or short status labels
+      (§184 v0.5.5).
+    - >-
+      Nest further <tree-item-ui> in the default slot only — no
+      <list-item-ui>, <nav-item-ui>, or arbitrary content inside a
+      tree row. The chevron is auto-stamped when the row has nested
+      tree-item-ui children.
+
+keywords:
+  - tree-item
+  - tree-row
+  - tree-node
+  - hierarchy-item
+
+related:
+  - Tree
+  - List
+  - Nav
+  - Accordion
+
+synonyms:
+  tree-item: [tree-node, tree-row, hierarchy-row]

package/components/tree/tree.a2ui.json

@@ -70,7 +70,12 @@
       "folder"
     ],
     "name": "UITree",
-    "related": [],
+    "related": [
+      "TreeItem",
+      "Nav",
+      "List",
+      "Accordion"
+    ],
     "slots": {
       "default (tree-item-ui children)": {
         "description": "Child content region for the `default (tree-item-ui children)` slot."

package/components/tree/tree.yaml

@@ -92,7 +92,32 @@ tokens:
 requiredIcons:
   - caret-right
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <tree-ui> only when data is hierarchical with arbitrary
+      nesting AND a single selected node is meaningful. For flat
+      lists use <list-ui>; for flat sidebar navigation use <nav-ui>;
+      for one-level collapsible groups use <accordion-ui>.
+    - >-
+      Canonical mount: inside <editor-sidebar slot="leading"> →
+      <pane-ui side="leading" resizable> → <section> → <tree-ui id="…">
+      as the structure / navigator pane of the three-pane editor shell.
+      Pair with a <header> in the same pane (e.g. "Structure",
+      "Layers", "Files").
+    - >-
+      Direct children of <tree-ui> MUST be <tree-item-ui>. No other
+      element types in the default slot. <tree-ui> manages
+      single-selection across the whole subtree and implements
+      WAI-ARIA tree-view keyboard navigation (Arrow keys, Enter /
+      Space, Home / End).
+    - >-
+      Listen for `tree-select` on the <tree-ui>, NOT on individual
+      rows — selection is managed by the parent and bubbles once.
+      Detail = {item, text, value, ctrlKey, metaKey, shiftKey}.
+    - >-
+      Per ADR-0027, <tree-ui> composes <icon-ui> (for chevrons) but
+      does NOT auto-import its children. Consumer pages must
+      explicitly import both <tree-ui> and <tree-item-ui>.
 anti_patterns: []
 examples:
   - name: basic-tree
@@ -128,4 +153,8 @@ synonyms:
     - sidebar
     - nav
     - tree
-related: []
+related:
+  - TreeItem
+  - Nav
+  - List
+  - Accordion

package/components/upload/upload.yaml

@@ -66,7 +66,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'File-upload input with drop zone + browse button. Form-associated; emits file-list change events.'
+      reason: 'File-input canonical primitive.'
+    - rule: 'Multiple attribute enables multi-file selection; accept= constrains file types.'
+      reason: 'Standard file-input knobs.'
+    - rule: 'For agent chat attachments use <chat-composer-ui>''s built-in upload affordance instead.'
+      reason: 'Chat composer has its own attachment lane.'
 anti_patterns: []
 examples:
   - name: data-import

package/core/index.js

@@ -31,3 +31,4 @@ export * from './transport.js';
 export * from './polyfills.js';
 export { streams, whenStream } from './data-stream.js';
 export * from './streams-bridge.js';
+export * from './responsive.js';