@adia-ai/web-components 0.6.21 → 0.6.22

package/components/skeleton/skeleton.yaml

@@ -6,7 +6,11 @@ tag: skeleton-ui
 component: Skeleton
 category: display
 version: 1
-description: Placeholder shimmer for loading states. Purely presentational.
+description: >-
+  Placeholder shimmer for loading states. Purely presentational — animated
+  pulse background with configurable shape via CSS sizing. Use as a
+  structural placeholder while data loads; for zero-state messaging after
+  loading completes use <empty-state-ui> instead.
 props:
   height:
     description: Height of the placeholder.
@@ -38,7 +42,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use to placeholder content during loading. Shape via CSS sizing (width/height/border-radius); shimmer is automatic.'
+      reason: 'Purely structural placeholder.'
+    - rule: 'Compose multiple <skeleton-ui> blocks to mock the actual content shape (card-skeleton, row-skeleton, etc.).'
+      reason: 'Better UX than single block — preview structure.'
+    - rule: 'For post-load empty states use <empty-state-ui> instead; skeleton is pre-load only.'
+      reason: 'Different lifecycle phase.'
 anti_patterns: []
 examples:
   - name: loading-skeleton
@@ -145,4 +155,8 @@ synonyms:
     - loading
     - skeleton
     - progress
-related: []
+related:
+  - EmptyState
+  - Card
+  - Table
+  - List

package/components/slider/slider.yaml

@@ -92,7 +92,13 @@ tokens:
   --slider-track-height:
     description: Full track height (scales via universal [size] attribute)
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Single-handle slider for selecting one value in a range. Form-associated; emits numeric change events.'
+      reason: 'Single-value range-input contract.'
+    - rule: 'For two-handle range selection use <range-ui> instead.'
+      reason: 'Single vs range sibling.'
+    - rule: 'Step attribute controls increments; show-value enables an inline value label.'
+      reason: 'Standard slider knobs.'
 anti_patterns: []
 examples:
   - name: slider-range

package/components/stack/stack.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stack.json",
   "title": "Stack",
-  "description": "Grid overlay layout — children stack on top of each other.",
+  "description": "Grid-overlay layout primitive — children stack on TOP of each\nother in a single grid cell (z-axis layering). Distinct from\n<col-ui> (vertical) / <row-ui> (horizontal) / <grid-ui> (2D\ngrid with cells). Use stack-ui for badge overlays on avatars,\nabsolute-positioned UI on top of charts, loading spinners over\ncontent, or any case where children must occupy the same physical\nspace. [align] controls how children align within the shared\ncell.\n",
   "type": "object",
   "allOf": [
     {
@@ -42,7 +42,11 @@
       "stack"
     ],
     "name": "UIStack",
-    "related": [],
+    "related": [
+      "Col",
+      "Row",
+      "Grid"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."
@@ -54,7 +58,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "stack": [
+        "overlay-stack",
+        "z-stack",
+        "grid-overlay",
+        "layer"
+      ]
+    },
     "tag": "stack-ui",
     "tokens": {},
     "traits": [],

package/components/stack/stack.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<stack-ui>` — Grid overlay layout — children stack on top of each other.
+ * `<stack-ui>` — Grid-overlay layout primitive — children stack on TOP of each
+other in a single grid cell (z-axis layering). Distinct from
+<col-ui> (vertical) / <row-ui> (horizontal) / <grid-ui> (2D
+grid with cells). Use stack-ui for badge overlays on avatars,
+absolute-positioned UI on top of charts, loading spinners over
+content, or any case where children must occupy the same physical
+space. [align] controls how children align within the shared
+cell.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/stack
  *

package/components/stack/stack.yaml

@@ -6,7 +6,15 @@ tag: stack-ui
 component: Stack
 category: layout
 version: 1
-description: Grid overlay layout — children stack on top of each other.
+description: |
+  Grid-overlay layout primitive — children stack on TOP of each
+  other in a single grid cell (z-axis layering). Distinct from
+  <col-ui> (vertical) / <row-ui> (horizontal) / <grid-ui> (2D
+  grid with cells). Use stack-ui for badge overlays on avatars,
+  absolute-positioned UI on top of charts, loading spinners over
+  content, or any case where children must occupy the same physical
+  space. [align] controls how children align within the shared
+  cell.
 props:
   align:
     description: Alignment of stacked items
@@ -22,7 +30,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Overlay/layer stacking container — children occupy the same area, stacked on the z-axis.'
+      reason: 'Different from row/col which lay out side-by-side.'
+    - rule: 'Use for overlapping content (image + overlay, badge-over-avatar, drop-shadow stacks).'
+      reason: 'Z-axis composition.'
+    - rule: 'Do not use for vertical content flow — that''s <col-ui>. Stack-ui is overlap-only.'
+      reason: 'Naming pitfall (stack ≠ vstack).'
 anti_patterns: []
 examples:
   - name: basic-stack
@@ -50,5 +64,9 @@ examples:
       ]
 keywords:
   - stack
-synonyms: {}
-related: []
+synonyms:
+  stack: [overlay-stack, z-stack, grid-overlay, layer]
+related:
+  - Col
+  - Row
+  - Grid

package/components/stat/stat.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stat.json",
   "title": "Stat",
-  "description": "Metric/KPI display — value + label + optional change indicator and trend.",
+  "description": "Metric/KPI display — value + label + optional change indicator and trend icon. Renders as a stacked block with prominent value and small caption; supports positive/negative delta coloring. Use inside dashboard cards or summary headers; for inline percentages or progress use <progress-ui>.",
   "type": "object",
   "allOf": [
     {
@@ -87,7 +87,11 @@
       "scoreboard"
     ],
     "name": "UIStat",
-    "related": [],
+    "related": [
+      "Card",
+      "Badge",
+      "Progress"
+    ],
     "slots": {
       "change": {
         "description": "Child content region for the `change` slot."

package/components/stat/stat.css

@@ -13,8 +13,8 @@
     --stat-icon-fg:      var(--a-fg-muted);
 
     /* ── Spacing ── */
-    --stat-column-gap:   var(--a-space-3);
-    --stat-row-gap:      var(--a-space-2);
+    --stat-column-gap:   var(--a-gap);
+    --stat-row-gap:      var(--a-gap-sm);
   }
 
   :scope {
@@ -74,6 +74,9 @@
     color: var(--stat-label-fg);
     line-height: 1.4;
     min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
   /* ── Change delta (under value) ── */

package/components/stat/stat.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<stat-ui>` — Metric/KPI display — value + label + optional change indicator and trend.
+ * `<stat-ui>` — Metric/KPI display — value + label + optional change indicator and trend icon. Renders as a stacked block with prominent value and small caption; supports positive/negative delta coloring. Use inside dashboard cards or summary headers; for inline percentages or progress use <progress-ui>.
  *
  * @see https://ui-kit.exe.xyz/site/components/stat
  *

package/components/stat/stat.yaml

@@ -9,7 +9,11 @@ composes:
 component: Stat
 category: display
 version: 1
-description: Metric/KPI display — value + label + optional change indicator and trend.
+description: >-
+  Metric/KPI display — value + label + optional change indicator and trend
+  icon. Renders as a stacked block with prominent value and small caption;
+  supports positive/negative delta coloring. Use inside dashboard cards or
+  summary headers; for inline percentages or progress use <progress-ui>.
 props:
   change:
     description: Change indicator text (e.g. '+12%', '-3%')
@@ -86,7 +90,13 @@ tokens:
   --stat-value-weight:
     description: Font weight for the primary value
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for prominent metric/KPI displays inside dashboard cards. Value + label + optional delta indicator.'
+      reason: 'Canonical metric primitive — dashboard surfaces compose 3-6 of these.'
+    - rule: 'For inline percent/progress displays use <progress-ui>; stat is for standalone metrics, progress for completion bars.'
+      reason: 'Different visual + semantic role.'
+    - rule: 'Delta indicator uses positive/negative semantic tokens; pass change= attribute with sign.'
+      reason: 'Built-in trend coloring; no manual styling needed.'
 anti_patterns: []
 examples:
   - name: basic-stat
@@ -220,4 +230,7 @@ synonyms:
     - metric
     - chart
     - stat
-related: []
+related:
+  - Card
+  - Badge
+  - Progress

package/components/step-progress/step-progress.yaml

@@ -45,7 +45,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Compact step indicator — N dots/segments showing current step out of total.'
+      reason: 'Minimal stepper visualization.'
+    - rule: 'Different from <stepper-ui> (labeled, expanded) — step-progress is dense and label-free.'
+      reason: 'Density boundary.'
+    - rule: 'For multi-task progress bars (multiple labeled rows) use <progress-row-ui> stack.'
+      reason: 'Different layout.'
 anti_patterns: []
 
 examples:

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

@@ -53,9 +53,19 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "stepper-item",
+      "step",
+      "wizard-step",
+      "progress-step",
+      "step-row"
+    ],
     "name": "UIStepperItem",
-    "related": [],
+    "related": [
+      "Stepper",
+      "Timeline",
+      "StepProgress"
+    ],
     "slots": {
       "description": {
         "description": "Custom description content; falls through to `[description]` prop if not slotted."
@@ -65,7 +75,14 @@
       }
     },
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "stepper-item": [
+        "step",
+        "wizard-step",
+        "progress-step",
+        "checkpoint"
+      ]
+    },
     "tag": "stepper-item-ui",
     "tokens": {},
     "traits": [],

package/components/stepper/stepper-item.yaml

@@ -43,3 +43,27 @@ slots:
     description: Custom label content; falls through to `[text]` prop if not slotted.
   description:
     description: Custom description content; falls through to `[description]` prop if not slotted.
+
+keywords:
+  - stepper-item
+  - step
+  - wizard-step
+  - progress-step
+  - step-row
+
+synonyms:
+  stepper-item: [step, wizard-step, progress-step, checkpoint]
+
+related:
+  - Stepper
+  - Timeline
+  - StepProgress
+
+a2ui:
+  rules:
+    - rule: 'Child of <stepper-ui> — one numbered step with label + complete/current/upcoming state.'
+      reason: 'Cluster contract.'
+    - rule: 'State driven by parent''s active-index; do not set state directly on stepper-item.'
+      reason: 'Parent owns step progression.'
+    - rule: 'For chronological events (no completion semantics) use <timeline-item-ui> instead.'
+      reason: 'Stepper is process; timeline is history.'

package/components/stepper/stepper.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stepper.json",
   "title": "Stepper",
-  "description": "Wizard / process stepper — parent step index drives numbered children.",
+  "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.",
   "type": "object",
   "allOf": [
     {

package/components/stepper/stepper.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<stepper-ui>` — Wizard / process stepper — parent step index drives numbered children.
+ * `<stepper-ui>` — Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/stepper
  *

package/components/stepper/stepper.yaml

@@ -6,7 +6,12 @@ tag: stepper-ui
 component: Stepper
 category: navigation
 version: 1
-description: Wizard / process stepper — parent step index drives numbered children.
+description: >-
+  Wizard / process stepper — parent step index drives numbered children's
+  complete/current/upcoming states automatically. Renders horizontally as
+  a labeled step bar with connectors. Use for multi-step forms,
+  onboarding, or pipelines; for read-only event history use <timeline-ui>
+  instead.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -30,7 +35,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Hosts <stepper-item-ui> children with a parent active-index driving complete/current/upcoming states.'
+      reason: 'Process visualization cluster.'
+    - rule: 'Use for wizards, onboarding flows, multi-step forms.'
+      reason: 'Surface examples.'
+    - rule: 'For read-only event history use <timeline-ui>; stepper requires forward progress semantics.'
+      reason: 'Decision rule vs timeline.'
 anti_patterns: []
 examples:
   - name: basic

package/components/stream/stream.a2ui.json

@@ -68,7 +68,11 @@
       "stream"
     ],
     "name": "UIStream",
-    "related": [],
+    "related": [
+      "ChatThreadUI",
+      "Text",
+      "Code"
+    ],
     "slots": {
       "default": {
         "description": "Default slot — primary child content."
@@ -80,7 +84,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "stream": [
+        "streaming-text",
+        "live-text",
+        "incremental-text"
+      ]
+    },
     "tag": "stream-ui",
     "tokens": {
       "--stream-color": {

package/components/stream/stream.yaml

@@ -50,7 +50,15 @@ tokens:
   --stream-line-height:
     description: Line height
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Renders an AsyncIterable<string> as streaming text — canonical for LLM token streaming.'
+      reason: 'Streaming primitive.'
+    - rule: 'Place inside <chat-thread-ui> message bodies for LLM responses; standalone for log tailing.'
+      reason: 'Composition pattern.'
+    - rule: 'pace attribute controls typewriter-effect speed; hide-cursor disables the blinking caret.'
+      reason: 'Visual knobs.'
+    - rule: 'For static (post-stream) display use <text-ui> or <richtext-ui>; stream-ui assumes live token feed.'
+      reason: 'Live vs static.'
 anti_patterns: []
 examples:
   - name: streaming-response
@@ -87,5 +95,9 @@ examples:
       ]
 keywords:
   - stream
-synonyms: {}
-related: []
+synonyms:
+  stream: [streaming-text, live-text, incremental-text]
+related:
+  - ChatThreadUI
+  - Text
+  - Code

package/components/swatch/swatch.yaml

@@ -150,7 +150,13 @@ tokens:
   --swatch-select-ring:
     description: Color of the focus + selected ring when [selectable] is set.
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use to display a single color sample with optional label. For interactive color picking use <color-picker-ui>.'
+      reason: 'Swatch is read-only display; picker is input.'
+    - rule: 'Inside design-token displays or palette grids; not for general decoration.'
+      reason: 'Semantic purpose: color sample.'
+    - rule: 'Color value accepts hex, rgb, hsl, or oklch; oklch preferred for AdiaUI token alignment.'
+      reason: 'Canonical color space.'
 anti_patterns: []
 examples:
   - name: basic-swatch

package/components/swiper/swiper.yaml

@@ -95,7 +95,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Horizontal slide carousel with touch + arrow nav. Hosts arbitrary children as slides.'
+      reason: 'Slide-based content discovery.'
+    - rule: 'For tab-switched peer views use <tabs-ui>; swiper is for content browsing, not panel switching.'
+      reason: 'Different interaction model.'
+    - rule: 'Set autoplay attribute for timed-rotation; otherwise user-driven only.'
+      reason: 'Affordance knob.'
 anti_patterns: []
 examples:
 - name: image-carousel

package/components/switch/switch.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Switch.json",
   "title": "Switch",
-  "description": "Toggle switch. The host IS the control.",
+  "description": "Toggle switch primitive — binary on/off control where the host IS\nthe control (per ADR-0025, no native <input type=\"checkbox\"> wrapped\nunderneath). Form-bearing via UIFormElement: [name], [value],\n[checked] (reflect), [required], [disabled]. Distinct from <check-ui>\n— use switch-ui for setting-style toggles (notifications on/off,\ndark mode, feature flags), check-ui for opt-in lists, terms\nacceptance, multi-select rows.\n",
   "type": "object",
   "allOf": [
     {
@@ -95,7 +95,11 @@
       "switch"
     ],
     "name": "UISwitch",
-    "related": [],
+    "related": [
+      "Check",
+      "Radio",
+      "Field"
+    ],
     "slots": {
       "hint": {
         "description": "Help text below the label"

package/components/switch/switch.yaml

@@ -4,7 +4,14 @@ tag: switch-ui
 component: Switch
 category: layout
 version: 1
-description: Toggle switch. The host IS the control.
+description: |
+  Toggle switch primitive — binary on/off control where the host IS
+  the control (per ADR-0025, no native <input type="checkbox"> wrapped
+  underneath). Form-bearing via UIFormElement: [name], [value],
+  [checked] (reflect), [required], [disabled]. Distinct from <check-ui>
+  — use switch-ui for setting-style toggles (notifications on/off,
+  dark mode, feature flags), check-ui for opt-in lists, terms
+  acceptance, multi-select rows.
 props:
   name:
     description: Form field name
@@ -86,6 +93,10 @@ a2ui:
     inline via CSS attr() pattern. For settings rows (label-left, switch-right), put the descriptive text in switch-ui's own
     [label] attribute; do not introduce a field-ui wrapper. For descriptive helper text below the switch, use <text-ui variant='caption'>
     as a sibling — not field-ui's hint slot.
+  - rule: 'Binary on/off only — no third state. For tri-state controls use <check-ui> with [indeterminate].'
+    reason: 'State-model boundary vs check-ui.'
+  - rule: 'Use for settings toggles, feature flags, mode switches; for form gates / consent / multi-select use <check-ui> instead.'
+    reason: 'Semantic role — switch = setting, check = selection/acceptance.'
 anti_patterns:
 - description: Wrapping a switch-ui in field-ui. The widget already self-labels.
   wrong: "<field-ui inline label=\"Email notifications\">\n  <switch-ui></switch-ui>\n</field-ui>\n"
@@ -140,4 +151,7 @@ synonyms:
   tags:
   - Toggle
   - Switch
-related: []
+related:
+  - Check
+  - Radio
+  - Field

package/components/table/cell-types.js

@@ -6,6 +6,19 @@ function registerCellType(name, config) {
   cellTypes[name] = config;
 }
 
+// text-overflow:ellipsis on a flex container doesn't reach text nodes —
+// they become anonymous flex items that the container can't truncate.
+// Wrapping in a <span> gives CSS a real element to target.
+function _t(cell, text) {
+  let s = cell.firstElementChild;
+  if (!s || s.tagName !== 'SPAN') {
+    cell.replaceChildren();
+    s = cell.appendChild(document.createElement('span'));
+  }
+  s.textContent = text;
+  cell.title = text;
+}
+
 // Sort functions
 export const sortFns = {
   basic: (a, b) => (a < b ? -1 : a > b ? 1 : 0),
@@ -22,7 +35,7 @@ export const sortFns = {
 // 1. text (default)
 registerCellType('text', {
   render(value, row, cell) {
-    cell.textContent = value ?? '';
+    _t(cell, String(value ?? ''));
   },
   format(value) {
     return String(value ?? '');
@@ -34,8 +47,7 @@ registerCellType('text', {
 // 2. number
 registerCellType('number', {
   render(value, row, cell) {
-    cell.textContent =
-      value != null ? new Intl.NumberFormat().format(value) : '';
+    _t(cell, value != null ? new Intl.NumberFormat().format(value) : '');
   },
   format(value) {
     return String(value ?? '');
@@ -47,13 +59,13 @@ registerCellType('number', {
 // 3. currency
 registerCellType('currency', {
   render(value, row, cell, meta) {
-    cell.textContent =
+    _t(cell,
       value != null
         ? new Intl.NumberFormat('en-US', {
             style: 'currency',
             currency: meta?.currency || 'USD',
           }).format(value)
-        : '';
+        : '');
   },
   format(value, row, meta) {
     return value != null
@@ -70,7 +82,7 @@ registerCellType('currency', {
 // 4. percent
 registerCellType('percent', {
   render(value, row, cell) {
-    cell.textContent = value != null ? `${value}%` : '';
+    _t(cell, value != null ? `${value}%` : '');
   },
   format(value) {
     return value != null ? `${value}%` : '';
@@ -84,9 +96,9 @@ const dateFmtOpts = { year: 'numeric', month: 'short', day: 'numeric' };
 
 registerCellType('date', {
   render(value, row, cell) {
-    cell.textContent = value
+    _t(cell, value
       ? new Intl.DateTimeFormat('en-US', dateFmtOpts).format(new Date(value))
-      : '';
+      : '');
   },
   format(value) {
     return value
@@ -108,11 +120,11 @@ const datetimeFmtOpts = {
 
 registerCellType('datetime', {
   render(value, row, cell) {
-    cell.textContent = value
+    _t(cell, value
       ? new Intl.DateTimeFormat('en-US', datetimeFmtOpts).format(
           new Date(value)
         )
-      : '';
+      : '');
   },
   format(value) {
     return value
@@ -188,6 +200,7 @@ registerCellType('avatar', {
     const span = wrapper.querySelector('span');
     av.setAttribute('text', String(value ?? ''));
     span.textContent = String(value ?? '');
+    cell.title = String(value ?? '');
   },
   format(value) {
     return String(value ?? '');

package/components/table/class.js

@@ -807,13 +807,17 @@ export class UITable extends UIElement {
           cell.innerHTML = result;
         }
       } else if (typeof col.format === 'function') {
-        cell.textContent = col.format(value, data);
+        const t = col.format(value, data);
+        cell.appendChild(Object.assign(document.createElement('span'), { textContent: t }));
+        cell.title = t;
       } else {
         const typeDef = cellTypes[col.type || 'text'];
         if (typeDef?.render) {
           typeDef.render(value, data, cell, col.meta);
         } else {
-          cell.textContent = value != null ? value : '';
+          const t = value != null ? String(value) : '';
+          cell.appendChild(Object.assign(document.createElement('span'), { textContent: t }));
+          cell.title = t;
         }
       }