@adia-ai/web-components 0.6.20 → 0.6.22

package/components/text/class.js

@@ -25,6 +25,10 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { parseResponsive, breakpoint } from '../../core/responsive.js';
+
+const _SIZE = { sm: 'var(--a-body-sm)', md: 'var(--a-body-md)', lg: 'var(--a-body-lg)' };
+function _sizeToCss(v) { return _SIZE[v] ?? v; }
 
 export class UIText extends UIElement {
   static properties = {
@@ -52,5 +56,14 @@ export class UIText extends UIElement {
     } else {
       this.style.removeProperty('--_text-lines');
     }
+
+    // Responsive size — e.g. size="sm sm@md lg@lg"
+    const size = this.size;
+    if (size?.includes('@')) {
+      const bp = breakpoint.value; // subscribe only when needed
+      this.style.setProperty('--text-size', _sizeToCss(parseResponsive(size, bp)));
+    } else {
+      this.style.removeProperty('--text-size');
+    }
   }
 }

package/components/text/text.a2ui.json

@@ -36,7 +36,7 @@
       "default": 0
     },
     "size": {
-      "description": "Override the variant's font-size on the body ladder. Maps to --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values are no-ops (variant size wins). Added v0.6.18 (FB-10).",
+      "description": "Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg). Accepts `@bp` notation: size=\"sm md@lg\" = sm below lg, md from lg up. Added v0.6.18 (FB-10).",
       "type": "string",
       "enum": [
         "sm",
@@ -154,7 +154,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "text": [
+        "typography",
+        "prose",
+        "label-text",
+        "paragraph"
+      ]
+    },
     "tag": "text-ui",
     "tokens": {},
     "traits": [],

package/components/text/text.d.ts

@@ -43,7 +43,7 @@ export class UIText extends UIElement {
   color: 'default' | 'subtle' | 'strong' | 'accent' | 'danger' | 'success' | 'warning';
   /** Multi-line clamp count (0 = no clamp) */
   lines: number;
-  /** Override the variant's font-size on the body ladder. Maps to --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values are no-ops (variant size wins). Added v0.6.18 (FB-10). */
+  /** Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg). Accepts `@bp` notation: size="sm md@lg" = sm below lg, md from lg up. Added v0.6.18 (FB-10). */
   size: 'sm' | 'md' | 'lg';
   /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
   strong: boolean;

package/components/text/text.yaml

@@ -22,9 +22,9 @@ props:
     default: 0
   size:
     description: >-
-      Override the variant's font-size on the body ladder. Maps to
-      --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values
-      are no-ops (variant size wins). Added v0.6.18 (FB-10).
+      Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg).
+      Accepts `@bp` notation: size="sm md@lg" = sm below lg, md from lg up.
+      Added v0.6.18 (FB-10).
     type: string
     enum: ["sm", "md", "lg"]
     default: ""
@@ -112,7 +112,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for typographic content with semantic role (heading, body, label, caption). Variant attribute sets the role.'
+      reason: 'Token-driven font/size/weight per variant — better than raw <p>/<h*> with overrides.'
+    - rule: 'For inline-flow rich content with multiple paragraphs, use <richtext-ui> instead.'
+      reason: 'Richtext handles paragraph rhythm + rich formatting.'
+    - rule: 'Heading variants (h1, h2, ...) are not auto-tagged — set the role explicitly via variant.'
+      reason: 'Visual variant decoupled from DOM tag.'
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -414,7 +420,8 @@ examples:
       ]
 keywords:
   - text
-synonyms: {}
+synonyms:
+  text: [typography, prose, label-text, paragraph]
 related:
   - avatar
   - input

package/components/textarea/textarea.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Textarea.json",
   "title": "Textarea",
-  "description": "Multiline text input. The host IS the interactive surface.",
+  "description": "Multi-line text input primitive — the host IS the contenteditable\nsurface (per ADR-0025, no native <textarea> wrapped underneath).\nForm-bearing via UIFormElement: [name], [value], [required],\n[disabled], [readonly], fires `change` on blur and `input` per\nkeystroke. Enter inserts a newline — does NOT fire `submit` (for\nEnter-to-send composers use <chat-input-ui submit-on-enter> inside\n<chat-composer>). Wrap in <field-ui label=\"…\"> for the canonical\nlabeled stack.\n",
   "type": "object",
   "allOf": [
     {
@@ -110,7 +110,12 @@
       "textarea"
     ],
     "name": "UITextarea",
-    "related": [],
+    "related": [
+      "Input",
+      "Field",
+      "ChatInput",
+      "Code"
+    ],
     "slots": {},
     "states": [
       {
@@ -118,7 +123,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "textarea": [
+        "multiline-input",
+        "text-area",
+        "comment-input",
+        "long-text-input"
+      ]
+    },
     "tag": "textarea-ui",
     "tokens": {},
     "traits": [],

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