@adia-ai/web-components 0.6.21 → 0.6.22

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';

package/core/responsive.d.ts

@@ -0,0 +1,29 @@
+import type { Signal } from './signals.js';
+
+/** Min-width px thresholds keyed by breakpoint name. */
+export declare const BREAKPOINTS: { xs: 0; sm: 480; md: 768; lg: 1024; xl: 1280 };
+
+/** Ordered breakpoint names, narrowest → widest. */
+export declare const BP_NAMES: string[];
+
+/**
+ * Shared signal holding the current viewport breakpoint name.
+ * Read inside a UIElement `render()` to subscribe; the component
+ * re-renders automatically on breakpoint change.
+ */
+export declare const breakpoint: Signal<'xs' | 'sm' | 'md' | 'lg' | 'xl'>;
+
+/**
+ * Resolve a responsive attribute value for the given breakpoint.
+ *
+ * Syntax: `"base @bp:override ..."` — e.g. `"1 2@sm 4@lg"`.
+ * Mobile-first: `@bp` applies at that breakpoint and all wider ones.
+ * Returns the unannotated default when no annotation matches.
+ *
+ * @param value    Raw attribute string (e.g. `"1 2@sm 4@lg"`).
+ * @param activeBp Breakpoint to resolve for. Defaults to `breakpoint.value`.
+ */
+export declare function parseResponsive(
+  value: string | null | undefined,
+  activeBp?: string,
+): string | null;

package/core/responsive.js

@@ -0,0 +1,120 @@
+/**
+ * AdiaUI Responsive — viewport-breakpoint signal + `@bp` attribute parser.
+ *
+ * Components that support responsive attribute values read `breakpoint.value`
+ * inside their `render()` method. UIElement wraps render() in an effect, so
+ * the component automatically re-renders whenever the viewport crosses a
+ * breakpoint boundary — no manual subscription needed.
+ *
+ * ## Syntax
+ *
+ *   "4"             → scalar, fast-path (no parsing)
+ *   "1 2@sm 4@lg"   → 1 on xs, 2 from sm, 4 from lg/xl
+ *   "4 1@sm"        → 4 on md/lg/xl, 1 on xs/sm
+ *   "2@md"          → 2 from md+, inherits component default below md
+ *
+ * Semantics: mobile-first / min-width — `@bp` means "apply at this
+ * breakpoint and all wider viewports, unless overridden by a larger
+ * annotation". The unannotated value is the base (smallest screens).
+ *
+ * Resolution: largest `@bp` whose index ≤ active-bp-index wins.
+ * If no annotation matches, the unannotated default is returned.
+ *
+ * @example
+ *   import { parseResponsive, breakpoint } from '../../core/responsive.js';
+ *
+ *   render() {
+ *     const bp   = breakpoint.value;              // subscribe
+ *     const cols = parseResponsive(this.columns, bp);
+ *     this.style.gridTemplateColumns = `repeat(${cols}, 1fr)`;
+ *   }
+ */
+
+import { signal } from './signals.js';
+
+// ─── Breakpoint scale ─────────────────────────────────────────────────────────
+
+/** Min-width px thresholds, narrowest first. */
+export const BREAKPOINTS = /** @type {Record<string, number>} */ ({
+  xs:    0,
+  sm:  480,
+  md:  768,
+  lg: 1024,
+  xl: 1280,
+});
+
+/** Ordered list of breakpoint names, narrowest → widest. */
+export const BP_NAMES = /** @type {string[]} */ (Object.keys(BREAKPOINTS));
+const BP_VALS          = /** @type {number[]} */ (Object.values(BREAKPOINTS));
+
+// ─── Active-breakpoint signal ─────────────────────────────────────────────────
+
+function _detect() {
+  if (typeof window === 'undefined') return 'lg'; // SSR / non-browser fallback
+  const w = window.innerWidth;
+  for (let i = BP_NAMES.length - 1; i >= 0; i--) {
+    if (w >= BP_VALS[i]) return BP_NAMES[i];
+  }
+  return 'xs';
+}
+
+/**
+ * Shared signal — current viewport breakpoint name.
+ * Reading `.value` inside a UIElement `render()` creates a subscription;
+ * the component re-renders automatically on breakpoint change.
+ *
+ * @type {import('./signals.js').Signal<string>}
+ */
+export const breakpoint = signal(_detect());
+
+// Wire matchMedia listeners once (browser only, skipped in SSR / tests)
+if (typeof window !== 'undefined') {
+  // One listener per non-zero threshold; fires whenever the viewport crosses
+  // that boundary in either direction.
+  for (let i = 1; i < BP_VALS.length; i++) {
+    window
+      .matchMedia(`(min-width: ${BP_VALS[i]}px)`)
+      .addEventListener('change', () => { breakpoint.value = _detect(); });
+  }
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a responsive attribute value for the given breakpoint.
+ *
+ * @param {string | null | undefined} value    Raw attribute string.
+ * @param {string}                    activeBp Current breakpoint name.
+ * @returns {string | null}                    Resolved scalar, or null.
+ */
+export function parseResponsive(value, activeBp = breakpoint.value) {
+  if (!value) return null;
+  if (!value.includes('@')) return value; // fast path — plain scalar
+
+  let defaultVal = /** @type {string | null} */ (null);
+  const bpMap    = /** @type {Map<string, string>} */ (new Map());
+
+  for (const token of value.trim().split(/\s+/)) {
+    const at = token.lastIndexOf('@');
+    if (at === -1) {
+      defaultVal = token;
+    } else {
+      bpMap.set(token.slice(at + 1), token.slice(0, at));
+    }
+  }
+
+  // Find the largest @bp annotation whose index ≤ active-bp index.
+  const activeIdx = BP_NAMES.indexOf(activeBp);
+  let   best      = /** @type {string | null} */ (null);
+  let   bestIdx   = -1;
+
+  for (const [bp, val] of bpMap) {
+    const idx = BP_NAMES.indexOf(bp);
+    if (idx !== -1 && idx <= activeIdx && idx > bestIdx) {
+      best    = val;
+      bestIdx = idx;
+    }
+  }
+
+  return best ?? defaultVal;
+}