@agent-ui-kit/web-components 0.0.14 → 0.0.16

package/dist/docs/components/stack.yaml

@@ -0,0 +1,126 @@
+name: aui-stack
+tag: aui-stack
+type: element
+summary: Flex column or row layout container.
+description: |
+  The primary layout primitive. Arranges children in a column (default) or row. Default gap is direction-dependent: column (default) uses gap 6, row (direction="row") uses gap 4. An explicit gap="N" attribute overrides both defaults. Accepts layout utility attributes for alignment and wrapping.
+presentational:
+  density:
+    syntax: key-value
+    attribute: density
+    cascades: true
+    default: regular
+    values:
+      - compact
+      - spacious
+    description: |
+      Controls gap and spacing compression for the stack and all descendants.
+attributes:
+  direction:
+    syntax: key-value
+    type: enum
+    values:
+      - row
+      - row-reverse
+      - column-reverse
+    default: null
+    description: |
+      Flex direction. Column is the default — no attribute needed. Set direction="row" for horizontal layout.
+modifiers:
+  wrap:
+    syntax: boolean
+    description: Enables flex-wrap for wrapping children when they overflow.
+layout:
+  alignment:
+    syntax: key-value
+    attribute: align-items
+    values:
+      - start
+      - center
+      - end
+      - stretch
+      - baseline
+    description: |
+      Controls cross-axis alignment (align-items). Apply one value.
+  justification:
+    syntax: key-value
+    attribute: justify-content
+    values:
+      - start
+      - center
+      - end
+      - between
+      - around
+      - evenly
+    description: |
+      Controls main-axis distribution (justify-content). Apply one value.
+  gap:
+    syntax: key-value
+    attribute: gap
+    values:
+      - "0"
+      - "1"
+      - "2"
+      - "3"
+      - "4"
+      - "5"
+      - "6"
+      - "7"
+    description: |
+      Explicit gap size (0–7 space units). Overrides the direction-dependent defaults (6 for column, 4 for row).
+content:
+  model: block
+  accepts: any
+  required: true
+  min-children: 1
+  description: |
+    Any block or inline elements. Stack is the general-purpose layout container — it accepts everything.
+slots:
+  default:
+    accepts:
+      - any
+    required: true
+    description: Stack children. Order in DOM = visual order.
+composition:
+  parents:
+    - aui-stack
+    - aui-grid
+    - aui-content
+    - aui-inset
+    - div
+    - section
+    - main
+    - form
+  children: any
+  context: |
+    The most-used layout element. Use for vertical lists, horizontal button groups, form layouts, card content. Nesting stacks is the standard pattern for complex layouts. Use direction="row" for horizontal arrangements, no attribute for vertical.
+tokens:
+  spacing:
+    - --aui-pad-gap-container
+examples:
+  - description: Default column stack
+    html: |-
+      <aui-stack>
+        <div>Item 1</div>
+        <div>Item 2</div>
+        <div>Item 3</div>
+      </aui-stack>
+  - description: Horizontal row stack
+    html: |-
+      <aui-stack direction="row">
+        <div>Left</div>
+        <div>Right</div>
+      </aui-stack>
+  - description: Wrapping row of badges
+    html: |-
+      <aui-stack direction="row" wrap>
+        <aui-badge accent>Tag 1</aui-badge>
+        <aui-badge info>Tag 2</aui-badge>
+        <aui-badge success>Tag 3</aui-badge>
+      </aui-stack>
+  - description: Row with space-between alignment
+    html: |-
+      <aui-stack direction="row" justify-content="between" align-items="center">
+        <span>Start</span>
+        <span>End</span>
+      </aui-stack>

package/dist/docs/components/stat.yaml

@@ -0,0 +1,164 @@
+name: aui-stat
+tag: aui-stat
+type: component
+summary: Stat display with label, value, trend indicator, and optional animation.
+description: |
+  Displays a metric with label, formatted value, and optional trend arrow. Stamps three internal spans: [data-stat-label], [data-stat-value], [data-stat-change]. Supports count-up and character-scramble animations with configurable duration. Value formatting preserves prefixes, suffixes, commas, and decimals. Intent attributes (accent, success, warning, danger) color the value.
+base: AgentElement
+presentational:
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: neutral
+    values:
+      - accent
+      - success
+      - warning
+      - danger
+    description: |
+      Colors the stat value text. Default is ink-strong (neutral).
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Stat label text shown above the value.
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: |
+      Formatted stat value (e.g. "$1,234.56", "89%", "12.4K"). Preserves prefix, suffix, commas, and decimals during animation.
+  trend:
+    syntax: key-value
+    type: enum
+    values:
+      - up
+      - down
+      - neutral
+    default: ""
+    description: |
+      Trend direction. "up" shows a green up-arrow, "down" shows a red down-arrow, "neutral" shows muted text with no arrow.
+  change:
+    syntax: key-value
+    type: string
+    default: ""
+    description: |
+      Change description text (e.g. "+12.5%", "-3 units"). Displayed next to the trend arrow.
+  animate-count:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: |
+      Enables count-up animation from animate-count-start to the target value. Uses ease-out cubic easing.
+  animate-count-start:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: |
+      Starting value for count-up animation. Can include prefix/suffix matching the value format.
+  animate-scramble:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: |
+      Enables character-scramble animation. Digit characters randomize and resolve left-to-right. Non-digit characters pass through unchanged.
+  duration-ms:
+    syntax: key-value
+    type: string
+    default: "2000"
+    description: |
+      Animation duration in milliseconds for both animate-count and animate-scramble.
+content:
+  model: block
+  accepts:
+    - aui-sparkline
+  required: false
+  description: |
+    Optional aui-sparkline child for inline chart below the stat value.
+composition:
+  parents:
+    - aui-container
+    - aui-inset
+    - aui-stack
+    - aui-grid
+    - div
+  children:
+    - aui-sparkline
+  context: |
+    Typically placed inside aui-container kind="widget" for KPI cards. Multiple stats in a grid for dashboard layouts.
+tokens:
+  - name: font-size (label)
+    default: var(--aui-font-xs)
+    description: Label font size.
+  - name: font-size (value)
+    default: var(--aui-font-2xl)
+    description: Value font size.
+  - name: font-size (change)
+    default: var(--aui-font-xs)
+    description: Change text font size.
+examples:
+  - description: Basic stat with label and value
+    html: |-
+      <aui-stat label="Total Users" value="12,450"></aui-stat>
+
+      <!-- ===============================================================
+           TREND -- up/down/neutral
+           =============================================================== -->
+  - description: Upward trend stat
+    html: <aui-stat label="Revenue" value="$48,200" trend="up" change="+12.5%"></aui-stat>
+  - description: Downward trend stat
+    html: <aui-stat label="Churn Rate" value="3.2%" trend="down" change="-0.8%"></aui-stat>
+  - description: Neutral trend stat
+    html: |-
+      <aui-stat label="Active Sessions" value="1,234" trend="neutral" change="0%"></aui-stat>
+
+      <!-- ===============================================================
+           INTENT VARIANTS
+           =============================================================== -->
+  - description: Success intent stat
+    html: <aui-stat label="Uptime" value="99.9%" success trend="up" change="+0.1%"></aui-stat>
+  - description: Danger intent stat
+    html: |-
+      <aui-stat label="Error Rate" value="4.7%" danger trend="up" change="+2.1%"></aui-stat>
+
+      <!-- ===============================================================
+           WITH SPARKLINE
+           =============================================================== -->
+  - description: Stat with inline sparkline
+    html: |-
+      <aui-stat label="Weekly Revenue" value="$12,450" trend="up" change="+12%">
+        <aui-sparkline values="3,5,4,7,6,8,9,11" color="1"></aui-sparkline>
+      </aui-stat>
+
+      <!-- ===============================================================
+           GROUP -- row of stats
+           =============================================================== -->
+  - description: Row of KPI stats in a grid
+    html: |-
+      <aui-grid cols="4" gap="4">
+        <aui-stat label="Revenue" value="$48,200" trend="up" change="+12.5%"></aui-stat>
+        <aui-stat label="Users" value="12,450" trend="up" change="+8.2%"></aui-stat>
+        <aui-stat label="Orders" value="1,234" trend="down" change="-3.1%"></aui-stat>
+        <aui-stat label="Conversion" value="3.2%" trend="neutral" change="0%"></aui-stat>
+      </aui-grid>
+
+      <!-- ===============================================================
+           ANIMATE COUNT -- smooth count-up animation
+           =============================================================== -->
+  - description: Count-up from 0 to $48,200 over 2s
+    html: <aui-stat label="Revenue" value="$48,200" animate-count></aui-stat>
+  - description: Count-up from 5,000 to 12,450 over 3s
+    html: <aui-stat label="Users" value="12,450" animate-count animate-count-start="5000" duration-ms="3000" trend="up" change="+8.2%"></aui-stat>
+  - description: Count-up percentage
+    html: |-
+      <aui-stat label="Conversion" value="87.3%" animate-count duration-ms="1500"></aui-stat>
+
+      <!-- ===============================================================
+           ANIMATE SCRAMBLE -- character scramble reveal
+           =============================================================== -->
+  - description: Scramble reveal of a revenue figure
+    html: <aui-stat label="Total Sales" value="$2,847,200" animate-scramble duration-ms="2500"></aui-stat>
+  - description: Scramble reveal of a percentage
+    html: <aui-stat label="Accuracy" value="99.7%" animate-scramble></aui-stat>

package/dist/docs/components/stepper.yaml

@@ -2,90 +2,83 @@ name: aui-stepper
 tag: aui-stepper
 type: component
 summary: Multi-step progress container with connector lines.
-description: >
-  Vertical step sequence container. Each child aui-step draws
-  a connector line to the next step. CSS-only element with no
-  JS behavior beyond extending AgentElement.
-
+description: |
+  Vertical step sequence container. Each child aui-step draws a connector line to the next step. CSS-only element with no JS behavior beyond extending AgentElement.
 base: AgentElement
-
-# ── Content model ─────────────────────────────────────────
-
 content:
   model: block
-  accepts: [aui-step]
+  accepts:
+    - aui-step
   required: true
-  description: >
-    Contains one or more aui-step children. Each step draws
-    a connector line to the next sibling.
-
-# ── Slots ─────────────────────────────────────────────────
-
+  description: |
+    Contains one or more aui-step children. Each step draws a connector line to the next sibling.
 slots:
   default:
-    accepts: [aui-step]
+    accepts:
+      - aui-step
     required: true
     description: Step children.
-
-# ── CSS tokens consumed ──────────────────────────────────
-
 tokens:
   sizing:
     - --aui-stepper-gap
     - --aui-stepper-connector-width
   color:
     - --aui-stepper-connector-color
-
-# ── Examples ──────────────────────────────────────────────
-
 examples:
-  - html: |
+  - description: Vertical stepper with done, running, and pending steps
+    html: |-
       <aui-stepper>
         <aui-step state="done">
-          <aui-badge success>1</aui-badge>
-          <aui-text>Account created</aui-text>
+          <aui-avatar size="xs" success solid><aui-icon name="check"></aui-icon></aui-avatar>
+          <aui-stack gap="1">
+            <aui-heading size="sm">Account created</aui-heading>
+            <aui-text muted size="xs">Email verified</aui-text>
+          </aui-stack>
         </aui-step>
         <aui-step state="running">
-          <aui-badge accent>2</aui-badge>
-          <aui-text>Profile setup</aui-text>
+          <aui-avatar size="xs" accent solid><aui-icon name="circle-notch"></aui-icon></aui-avatar>
+          <aui-stack gap="1">
+            <aui-heading size="sm">Profile setup</aui-heading>
+            <aui-text muted size="xs">Add your details</aui-text>
+          </aui-stack>
         </aui-step>
         <aui-step>
-          <aui-badge>3</aui-badge>
-          <aui-text>Complete</aui-text>
+          <aui-avatar size="xs" style="background: var(--aui-neutral-highest);">3</aui-avatar>
+          <aui-stack gap="1">
+            <aui-heading size="sm">Complete</aui-heading>
+            <aui-text muted size="xs">Ready to go</aui-text>
+          </aui-stack>
         </aui-step>
       </aui-stepper>
-    description: Vertical stepper with done, running, and pending steps.
-
-  - html: |
+  - description: All steps completed
+    html: |-
       <aui-stepper>
-        <aui-step completed>
-          <aui-badge success>1</aui-badge>
-          <aui-text>Order placed</aui-text>
+        <aui-step state="done">
+          <aui-avatar size="xs" success solid><aui-icon name="check"></aui-icon></aui-avatar>
+          <aui-heading size="sm">Order placed</aui-heading>
         </aui-step>
-        <aui-step completed>
-          <aui-badge success>2</aui-badge>
-          <aui-text>Payment confirmed</aui-text>
+        <aui-step state="done">
+          <aui-avatar size="xs" success solid><aui-icon name="check"></aui-icon></aui-avatar>
+          <aui-heading size="sm">Payment confirmed</aui-heading>
         </aui-step>
-        <aui-step active>
-          <aui-badge accent>3</aui-badge>
-          <aui-text>Shipping</aui-text>
+        <aui-step state="done">
+          <aui-avatar size="xs" success solid><aui-icon name="check"></aui-icon></aui-avatar>
+          <aui-heading size="sm">Shipped</aui-heading>
         </aui-step>
       </aui-stepper>
-    description: Stepper with completed and active steps.
-
-  - html: |
+  - description: Stepper with error state
+    html: |-
       <aui-stepper>
-        <aui-step completed>
-          <aui-badge success>1</aui-badge>
-          <aui-text>Build</aui-text>
+        <aui-step state="done">
+          <aui-avatar size="xs" success solid><aui-icon name="check"></aui-icon></aui-avatar>
+          <aui-heading size="sm">Build</aui-heading>
         </aui-step>
-        <aui-step error>
-          <aui-badge danger>2</aui-badge>
-          <aui-text>Deploy</aui-text>
+        <aui-step state="running">
+          <aui-avatar size="xs" danger solid><aui-icon name="warning"></aui-icon></aui-avatar>
+          <aui-heading size="sm">Deploy</aui-heading>
         </aui-step>
         <aui-step>
-          <aui-badge>3</aui-badge>
-          <aui-text>Verify</aui-text>
+          <aui-avatar size="xs" style="background: var(--aui-neutral-highest);">3</aui-avatar>
+          <aui-heading size="sm">Verify</aui-heading>
         </aui-step>
       </aui-stepper>
-    description: Stepper with an error state step.

package/dist/docs/components/switch.yaml

@@ -2,80 +2,76 @@ name: aui-switch
 tag: aui-switch
 type: component
 summary: Toggle switch with track and sliding thumb.
-description: >
-  Binary toggle rendered as an iOS-style wide track with a pill-shaped
-  sliding thumb. Hidden native checkbox for form participation. Label
-  rendered via CSS ::after { content: attr(label) } — JS only sets
-  aria-label for accessibility, no DOM stamping for the visible label.
-  Animated transitions use offset timing (thumb moves before track
-  fill). Press animation stretches the thumb wider on :active.
-
+description: |
+  Binary toggle rendered as an iOS-style wide track with a pill-shaped sliding thumb. Hidden native checkbox for form participation. Label rendered via CSS ::after { content: attr(label) } — JS only sets aria-label for accessibility, no DOM stamping for the visible label. Animated transitions use offset timing (thumb moves before track fill). Press animation stretches the thumb wider on :active.
 base: AgentElement
-
 presentational:
   size:
     syntax: key-value
     attribute: size
     cascades: true
     default: medium
-    values: [xs, sm, md, lg, xl]
+    values:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
     description: Controls track and thumb dimensions.
-
   intent:
     syntax: boolean
     exclusive: true
     cascades: true
     default: neutral
-    values: [accent, info, success, warning, danger]
+    values:
+      - accent
+      - info
+      - success
+      - warning
+      - danger
     description: Color family for the checked track fill.
-
 attributes:
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Prevents interaction.
-
   checked:
     syntax: boolean
     type: boolean
     default: false
     description: Whether the switch is on.
-
   label:
     syntax: key-value
     type: string
     default: ""
     description: Label text displayed next to the switch.
-
   name:
     syntax: key-value
     type: string
     default: ""
     description: Form submission name.
-
   value:
     syntax: key-value
     type: string
-    default: "on"
+    default: on
     description: Form submission value when checked.
-
 content:
   model: inline
-  accepts: [input]
+  accepts:
+    - input
   required: false
-  description: >
-    Auto-stamps hidden input for form participation. Label is
-    rendered purely via CSS ::after on :scope — no stamped span.
-
+  description: |
+    Auto-stamps hidden input for form participation. Label is rendered purely via CSS ::after on :scope — no stamped span.
 composition:
-  parents: [aui-field, aui-stack, form, div]
+  parents:
+    - aui-field
+    - aui-stack
+    - form
+    - div
   children: null
-  context: >
-    Use for on/off toggles in settings panels. Place inside
-    aui-field for labeled form switches, or standalone with
-    the label attribute.
-
+  context: |
+    Use for on/off toggles in settings panels. Place inside aui-field for labeled form switches, or standalone with the label attribute.
 a11y:
   role: switch
   keyboard:
@@ -84,11 +80,9 @@ a11y:
   aria:
     aria-checked: Mirrors checked attribute.
     aria-disabled: Mirrors disabled attribute.
-
 events:
   change:
     description: Fires when checked state changes.
-
 tokens:
   - name: --aui-switch-gap
     default: calc(var(--aui-space) * 2)
@@ -138,24 +132,19 @@ tokens:
   - name: --aui-switch-border-disabled
     default: var(--aui-stroke-disabled, var(--aui-border-disabled))
     description: Track border when disabled.
-
 css-notes:
   attr-audit:
     - "AB1: [checked], [disabled] — visual state via attributes"
-    - "::before on [data-track] for thumb — pure CSS sliding"
+    - ::before on [data-track] for thumb — pure CSS sliding
     - "CG3: ::after { content: attr(label) } — label rendered in CSS, no JS-stamped [data-label]"
-    - ":active thumb stretches wider (press animation)"
+    - :active thumb stretches wider (press animation)
     - "Offset timing: thumb translate transitions before track fill color"
-
 examples:
-  - html: <aui-switch label="Notifications"></aui-switch>
-    description: Default off switch.
-
-  - html: <aui-switch label="Dark mode" checked></aui-switch>
-    description: Pre-enabled switch.
-
-  - html: <aui-switch label="Locked" disabled></aui-switch>
-    description: Disabled switch.
-
-  - html: <aui-switch label="Active" checked accent></aui-switch>
-    description: Accent-colored enabled switch.
+  - description: Default off switch
+    html: <aui-switch label="Notifications"></aui-switch>
+  - description: Pre-enabled switch
+    html: <aui-switch label="Dark mode" checked></aui-switch>
+  - description: Disabled switch
+    html: <aui-switch label="Locked" disabled></aui-switch>
+  - description: Accent-colored enabled switch
+    html: <aui-switch label="Active" checked accent></aui-switch>

package/dist/docs/components/tab-panel.yaml

@@ -2,40 +2,49 @@ name: aui-tab-panel
 tag: aui-tab-panel
 type: component
 summary: Content panel associated with a tab.
-description: >
-  Shown when the matching tab is selected, hidden otherwise.
-  The parent aui-tabs coordinates visibility.
-
+description: |
+  Shown when the matching tab is selected, hidden otherwise. The parent aui-tabs coordinates visibility.
 base: AgentElement
-
 attributes:
   value:
     syntax: key-value
     type: string
     default: ""
     description: Panel identifier, matched against aui-tab value.
-
   active:
     syntax: boolean
     type: boolean
     default: false
     description: Whether this panel is currently visible.
-
 a11y:
   role: tabpanel
   aria:
     aria-hidden: true when not active.
-
 composition:
-  parents: [aui-tabs]
-  children: [any]
-
+  parents:
+    - aui-tabs
+  children:
+    - any
 examples:
-  - html: |
-      <aui-tabs value="overview">
-        <aui-tab value="overview">Overview</aui-tab>
-        <aui-tab value="details">Details</aui-tab>
-        <aui-tab-panel value="overview">Overview panel with content.</aui-tab-panel>
-        <aui-tab-panel value="details">Details panel with more content.</aui-tab-panel>
+  - description: Tab panels with rich content
+    html: |-
+      <aui-tabs value="info">
+        <aui-tab value="info">Info</aui-tab>
+        <aui-tab value="stats">Stats</aui-tab>
+        <aui-tab value="logs">Logs</aui-tab>
+        <aui-tab-panel value="info">
+          <aui-stack gap="sm">
+            <aui-text size="lg" weight="medium">System Information</aui-text>
+            <aui-text>Running on version 3.2.1 with all services operational.</aui-text>
+          </aui-stack>
+        </aui-tab-panel>
+        <aui-tab-panel value="stats">
+          <aui-stack gap="sm">
+            <aui-text size="lg" weight="medium">Usage Statistics</aui-text>
+            <aui-text>CPU: 42% | Memory: 68% | Disk: 31%</aui-text>
+          </aui-stack>
+        </aui-tab-panel>
+        <aui-tab-panel value="logs">
+          <aui-text>No recent log entries.</aui-text>
+        </aui-tab-panel>
       </aui-tabs>
-    description: Tab panels shown within a full tabs context.