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

package/dist/docs/components/header.yaml

@@ -0,0 +1,168 @@
+name: aui-header
+tag: aui-header
+type: element
+summary: Float-based layout container for top bars.
+description: |
+  Uses float-based slot layout with three zones: leading (float left), content (absolute centered), and trailing (float right). The leading and trailing slots maintain natural text alignment. The content slot is centered via flexbox with text-align: center scoped to it only. Use for page headers, section headers, toolbar bars.
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
+    description: Controls min-height and font-size.
+  density:
+    syntax: key-value
+    attribute: density
+    cascades: true
+    default: regular
+    values:
+      - compact
+      - spacious
+    description: Controls padding compression.
+  responsive:
+    syntax: boolean
+    attribute: responsive
+    cascades: false
+    default: false
+    description: |
+      Enables progressive collapse via container queries. The header becomes a container provider (container-type: inline-size) and slotted children hide progressively as the container shrinks: trailing hides first (< 8rem), then leading (< 5rem), then everything except the leading icon (< 3rem). Use aui-button in slots for best collapse behavior — buttons with icon-leading and label degrade gracefully to icon-only at narrow widths.
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values:
+      - accent
+      - info
+      - success
+      - warning
+      - danger
+    description: Color family — cascades to all children.
+content:
+  model: mixed
+  accepts:
+    - text
+    - inline elements
+    - aui-button
+    - aui-badge
+    - aui-avatar
+    - span
+    - div
+  required: true
+  description: |
+    Title text in the default slot, icons/buttons in leading/trailing. At minimum, provide a default slot child with the header title.
+slots:
+  default:
+    accepts:
+      - text
+      - span
+      - h1
+      - h2
+      - h3
+      - div
+    required: true
+    description: Center/main content — typically the title text.
+  content:
+    accepts:
+      - text
+      - span
+      - h1
+      - h2
+      - h3
+      - div
+    required: false
+    description: |
+      Centered title content. Rendered with position: absolute, inset: 0 and flexbox centering. Text-align: center is scoped to this slot only — it does not cascade to leading/trailing. Prefer this slot when visual centering matters.
+  leading:
+    accepts:
+      - span
+      - svg
+      - aui-button
+      - aui-avatar
+    required: false
+    description: |
+      Leading element (menu icon, back button). Floats left with natural text alignment and z-index above the content slot.
+  trailing:
+    accepts:
+      - span
+      - svg
+      - aui-button
+      - aui-badge
+      - div
+    required: false
+    description: |
+      Trailing element (actions, settings icon). Floats right with natural text alignment and z-index above the content slot.
+composition:
+  parents:
+    - aui-stack
+    - div
+    - section
+    - main
+    - nav
+  siblings:
+    typical:
+      - aui-content
+      - aui-footer
+    pattern: |
+      aui-header is typically the first child in a vertical container, followed by aui-content and optionally aui-footer.
+  context: |
+    Use as the top bar of a page, section, card, or dialog. Pair with aui-content for scrollable content below, and aui-footer for bottom actions. The adaptive grid means you only populate the slots you need — no empty placeholders.
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-font-size
+  spacing:
+    - --aui-pad-control-block
+    - --aui-pad-control-inline
+    - --aui-pad-gap-container
+examples:
+  - description: Simple centered title
+    html: |-
+      <aui-header dividers>
+        Page Title
+      </aui-header>
+  - description: Responsive toolbar — leading collapses to icon-only, trailing survives
+    html: |-
+      <aui-header dividers responsive>
+        <aui-button ghost slot="leading" label="Dashboard" icon-leading="house"></aui-button>
+        <aui-button ghost slot="trailing" icon-leading="gear" label="Settings" hide-label></aui-button>
+      </aui-header>
+  - description: Navigation header — back button, centered title, close action
+    html: |-
+      <aui-header dividers responsive>
+        <aui-button ghost slot="leading" label="Back" icon-leading="caret-left"></aui-button>
+        <span slot="content">Settings</span>
+        <aui-button ghost slot="trailing" icon-leading="x" label="Close" hide-label></aui-button>
+      </aui-header>
+  - description: Notification header with badge
+    html: |-
+      <aui-header dividers>
+        <aui-icon name="bell" slot="leading"></aui-icon>
+        <span slot="content">Notifications</span>
+        <aui-badge accent slot="trailing">3</aui-badge>
+      </aui-header>
+  - description: Toolbar with multiple actions
+    html: |-
+      <aui-header dividers responsive>
+        <aui-button ghost slot="leading" label="New document" icon-leading="plus"></aui-button>
+        <span slot="content">Documents</span>
+        <span slot="trailing">
+          <aui-button ghost icon-leading="magnifying-glass" label="Search" hide-label></aui-button>
+          <aui-button ghost icon-leading="funnel" label="Filter" hide-label></aui-button>
+          <aui-button ghost icon-leading="dots-three" label="More" hide-label></aui-button>
+        </span>
+      </aui-header>
+  - description: Compact density header
+    html: |-
+      <aui-header dividers density="compact">
+        <aui-icon name="chat-dots" slot="leading"></aui-icon>
+        <span slot="content">Chat</span>
+        <aui-button ghost slot="trailing" icon-leading="x" label="Close" hide-label density="compact"></aui-button>
+      </aui-header>

package/dist/docs/components/heading.yaml

@@ -0,0 +1,58 @@
+name: aui-heading
+tag: aui-heading
+type: element
+summary: Block-level heading text with size and weight attributes.
+description: |
+  A CSS-only heading element that replaces styled <strong> tags. Size maps to the --aui-font-* scale. Weight defaults to 500 (medium). Uses --aui-ink-strong for maximum contrast. No JavaScript required.
+presentational:
+  size:
+    syntax: key-value
+    type: enum
+    default: md
+    values:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
+      - 2xl
+    description: Font size from the type scale.
+  weight:
+    syntax: key-value
+    type: enum
+    default: semibold
+    values:
+      - normal
+      - medium
+      - bold
+    description: Font weight override.
+modifiers:
+  muted:
+    syntax: boolean
+    description: Sets color to --aui-ink-muted for de-emphasised headings.
+examples:
+  - description: Full size scale
+    html: |-
+      <aui-stack gap="3">
+        <aui-heading size="6xl">Heading 6XL — Hero</aui-heading>
+        <aui-heading size="5xl">Heading 5XL — Display</aui-heading>
+        <aui-heading size="4xl">Heading 4XL — Landing</aui-heading>
+        <aui-heading size="3xl">Heading 3XL — Page hero</aui-heading>
+        <aui-heading size="2xl">Heading 2XL — Page title</aui-heading>
+        <aui-heading size="xl">Heading XL — Section title</aui-heading>
+        <aui-heading size="lg">Heading LG — Card title</aui-heading>
+        <aui-heading size="md">Heading MD — List item name</aui-heading>
+        <aui-heading size="sm">Heading SM — Label</aui-heading>
+      </aui-stack>
+  - description: Weight variants
+    html: |-
+      <aui-stack gap="3">
+        <aui-heading size="lg" weight="semibold">Semibold (default)</aui-heading>
+        <aui-heading size="lg" weight="medium">Medium weight</aui-heading>
+      </aui-stack>
+  - description: Muted headings
+    html: |-
+      <aui-stack gap="3">
+        <aui-heading size="xl" muted>Muted XL heading</aui-heading>
+        <aui-heading size="md" muted>Muted MD heading</aui-heading>
+      </aui-stack>

package/dist/docs/components/hover-card.yaml

@@ -2,14 +2,9 @@ name: aui-hover-card
 tag: aui-hover-card
 type: component
 summary: Rich preview card shown on hover/focus with configurable delay.
-description: >
-  A popover card that appears after a hover delay on an anchor element.
-  Uses the Popover API with CSS anchor positioning. The card stays visible
-  when the pointer moves into it, and hides after a leave delay. Supports
-  side placement (top/bottom/left/right) and custom show/hide delays.
-
+description: |
+  A popover card that appears after a hover delay on an anchor element. Uses the Popover API with CSS anchor positioning. The card stays visible when the pointer moves into it, and hides after a leave delay. Supports side placement (top/bottom/left/right) and custom show/hide delays.
 base: AgentElement
-
 attributes:
   anchor:
     syntax: key-value
@@ -29,14 +24,12 @@ attributes:
   side:
     syntax: key-value
     type: string
-    default: "bottom"
+    default: bottom
     description: Preferred placement side — top, bottom, left, or right.
-
 modifiers:
   open:
     syntax: boolean
     description: Whether the hover card is currently visible.
-
 tokens:
   - name: --aui-hover-card-background
     default: var(--aui-modal, var(--aui-doc))
@@ -56,30 +49,29 @@ tokens:
   - name: --aui-hover-card-max-width
     default: 20rem
     description: Maximum width of the card.
-
 a11y:
   role: tooltip (popover)
   keyboard:
     Escape: Close the hover card.
-
 events: {}
-
 composition:
-  parents: [any]
-  children: [any]
-
+  parents:
+    - any
+  children:
+    - any
 examples:
-  - html: |
+  - description: Basic hover card — hover to show, move pointer away to hide
+    html: |-
       <span id="hc-anchor" style="text-decoration: underline; cursor: pointer; color: var(--aui-ink);">Hover over me</span>
       <aui-hover-card anchor="#hc-anchor">
         <aui-heading size="sm">Preview Card</aui-heading>
         <aui-text muted>This is a rich hover preview with any content.</aui-text>
       </aui-hover-card>
-    description: Basic hover card — hover to show, move pointer away to hide.
-
-  - html: |
-      <span id="hc-top" style="text-decoration: underline; cursor: pointer; color: var(--aui-ink);">Hover (top side)</span>
-      <aui-hover-card anchor="#hc-top" side="top" delay="200">
-        <aui-text>This card appears above the anchor.</aui-text>
-      </aui-hover-card>
-    description: Hover card positioned above the anchor with shorter delay.
+  - description: Hover card positioned above the anchor with shorter delay
+    html: |-
+      <div style="margin-top: 6rem;">
+        <span id="hc-top" style="text-decoration: underline; cursor: pointer; color: var(--aui-ink);">Hover (top side)</span>
+        <aui-hover-card anchor="#hc-top" side="top" delay="200">
+          <aui-text>This card appears above the anchor.</aui-text>
+        </aui-hover-card>
+      </div>

package/dist/docs/components/icon.yaml

@@ -2,83 +2,56 @@ name: aui-icon
 tag: aui-icon
 type: component
 summary: SVG icon rendered from a global registry.
-description: >
-  Displays an icon by name from the global icon registry. Icons are
-  registered via registerIcon() or registerIcons() — the component
-  itself is icon-set agnostic. Inherits color from its parent via
-  currentColor. Size follows --aui-icon-size or explicit size attribute.
-
+description: |
+  Displays an icon by name from the global icon registry. Icons are registered via registerIcon() or registerIcons() — the component itself is icon-set agnostic. Inherits color from its parent via currentColor. Size follows --aui-icon-size or explicit size attribute.
 base: AgentElement
-
-# ── Presentational attributes ─────────────────────────────
-
 presentational:
   size:
     syntax: key-value
     cascades: false
     default: medium
-    values: [xs, sm, lg, xl]
-    description: >
-      Overrides the inherited --aui-icon-size token.
-      Default (no attribute) uses the token value from context.
-
-# ── Component attributes ──────────────────────────────────
-
+    values:
+      - xs
+      - sm
+      - lg
+      - xl
+    description: |
+      Overrides the inherited --aui-icon-size token. Default (no attribute) uses the token value from context.
 attributes:
   name:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Icon name matching a key in the global registry.
-      When the name changes, the SVG is re-rendered.
-      Registered names: arrow-up, caret-down, caret-left, caret-right,
-      caret-up, chat-dots, check, check-circle, circle, clock, crosshair,
-      dots-three, envelope, file-text, flask, gear, globe-simple, house,
-      image, lightbulb, list-checks, magnifying-glass, microphone, minus,
-      paperclip, pencil, plus, robot, sliders, sparkle, star, stop, user,
-      warning, warning-circle, x, chart-bar, sun, moon, heart, trash,
-      info, copy, thumbs-up, thumbs-down, arrow-clockwise.
-
+    description: |
+      Icon name matching a key in the global registry. When the name changes, the SVG is re-rendered. Registered names: arrow-up, caret-down, caret-left, caret-right, caret-up, chat-dots, check, check-circle, circle, clock, crosshair, dots-three, envelope, file-text, flask, gear, globe-simple, house, image, lightbulb, list-checks, magnifying-glass, microphone, minus, paperclip, pencil, plus, robot, sliders, sparkle, star, stop, user, warning, warning-circle, x, chart-bar, sun, moon, heart, trash, info, copy, thumbs-up, thumbs-down, arrow-clockwise.
   label:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Accessible label for meaningful icons. When set, the element
-      gets role="img" and aria-label. When absent, it is treated
-      as decorative (role="presentation", aria-hidden="true").
-
-# ── Content model ─────────────────────────────────────────
-
+    description: |
+      Accessible label for meaningful icons. When set, the element gets role="img" and aria-label. When absent, it is treated as decorative (role="presentation", aria-hidden="true").
 content:
   model: empty
   accepts: []
   required: false
-  description: >
-    Content is auto-rendered from the registry. Do not place
-    children inside aui-icon.
-
-# ── Composition ───────────────────────────────────────────
-
+  description: |
+    Content is auto-rendered from the registry. Do not place children inside aui-icon.
 composition:
-  parents: [aui-button, aui-input, aui-select, aui-header, aui-footer, any]
+  parents:
+    - aui-button
+    - aui-input
+    - aui-select
+    - aui-header
+    - aui-footer
+    - any
   children: null
-  context: >
-    Icons appear inside button slots, input leading/trailing,
-    toolbar items, or standalone. Inherits color and size from
-    the parent context.
-
-# ── Accessibility ─────────────────────────────────────────
-
+  context: |
+    Icons appear inside button slots, input leading/trailing, toolbar items, or standalone. Inherits color and size from the parent context.
 a11y:
   role: img (when label set) / presentation (decorative)
   aria:
     aria-label: Set from label attribute when present.
     aria-hidden: Set to "true" when no label (decorative icon).
-
-# ── CSS tokens consumed ──────────────────────────────────
-
 tokens:
   - name: --aui-icon-width
     default: var(--aui-icon-size)
@@ -89,11 +62,9 @@ tokens:
   - name: --aui-icon-color
     default: currentColor
     description: Icon fill color, inherited from parent.
-
-# ── Examples ──────────────────────────────────────────────
-
 examples:
-  - html: |
+  - description: Icon gallery from the Phosphor icon set
+    html: |-
       <aui-stack direction="row" gap="2" align-items="center">
         <aui-icon name="house"></aui-icon>
         <aui-icon name="gear"></aui-icon>
@@ -108,9 +79,8 @@ examples:
         <aui-icon name="warning"></aui-icon>
         <aui-icon name="info"></aui-icon>
       </aui-stack>
-    description: Icon gallery from the Phosphor icon set.
-
-  - html: |
+  - description: Size scale from xs to xl
+    html: |-
       <aui-stack direction="row" gap="2" align-items="center">
         <aui-icon name="star" size="xs"></aui-icon>
         <aui-icon name="star" size="sm"></aui-icon>
@@ -118,9 +88,8 @@ examples:
         <aui-icon name="star" size="lg"></aui-icon>
         <aui-icon name="star" size="xl"></aui-icon>
       </aui-stack>
-    description: Size scale from xs to xl.
-
-  - html: |
+  - description: Icons inside button slots
+    html: |-
       <aui-stack direction="row" gap="2" align-items="center">
         <aui-button outline accent>
           <aui-icon name="pencil" slot="leading"></aui-icon>
@@ -134,7 +103,5 @@ examples:
           <aui-icon name="magnifying-glass" slot="leading"></aui-icon>
         </aui-button>
       </aui-stack>
-    description: Icons inside button slots.
-
-  - html: <aui-icon name="warning" label="Warning" size="xl"></aui-icon>
-    description: Meaningful icon with accessible label.
+  - description: Meaningful icon with accessible label
+    html: <aui-icon name="warning" label="Warning" size="xl"></aui-icon>

package/dist/docs/components/index.yaml

@@ -49,10 +49,20 @@ aui-radio-group:
   uses: [plan selection in pricing, payment method chooser, frequency toggle in settings]
   children: [aui-radio]
 
+aui-checkbox-group:
+  summary: Container that coordinates checkbox multi-selection with min/max constraints.
+  uses: [multi-select form fields, feature toggles, preference checkboxes, filter groups]
+  children: [aui-checkbox]
+
 aui-field:
   summary: Form field wrapper with label, description, and error.
   uses: [labeled login input, settings form row, registration field with validation, inline error display]
-  children: [aui-input, aui-textarea, aui-select, aui-checkbox, aui-switch, aui-radio-group]
+  children: [aui-input, aui-textarea, aui-select, aui-checkbox, aui-switch, aui-radio-group, aui-checkbox-group]
+
+aui-form:
+  summary: Form coordinator with validation and structured submit events.
+  uses: [settings forms, registration pages, profile editors, search forms, inline data entry]
+  children: [aui-field, aui-button, aui-checkbox-group, aui-fieldset]
 
 aui-tooltip:
   summary: Hover/focus tooltip with popover-based positioning.

package/dist/docs/components/input-group.yaml

@@ -0,0 +1,102 @@
+name: aui-input-group
+tag: aui-input-group
+type: element
+summary: Wrapper that connects an input with prefix and/or suffix addons.
+description: |
+  CSS-only wrapper that shares a unified border treatment between an input and its prefix/suffix addons. Use for currency fields, URL inputs, unit inputs, and search fields with button suffixes.
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: md
+    values:
+      - sm
+      - md
+      - lg
+    description: Matches size to child input.
+modifiers:
+  disabled:
+    syntax: boolean
+    description: |
+      Dims the entire group and disables pointer events.
+content:
+  model: flow
+  accepts:
+    - aui-input
+    - span
+    - aui-button
+  required: true
+  description: |
+    Must contain an aui-input. May include span[slot="prefix"] and/or span[slot="suffix"] for addon labels. Buttons can also be used as suffix addons.
+slots:
+  prefix:
+    accepts:
+      - span
+      - aui-button
+    required: false
+    description: Addon before the input (e.g. currency symbol, protocol).
+  default:
+    accepts:
+      - aui-input
+    required: true
+    description: The input element.
+  suffix:
+    accepts:
+      - span
+      - aui-button
+    required: false
+    description: Addon after the input (e.g. unit, action button).
+composition:
+  parents:
+    - aui-field
+    - aui-stack
+    - aui-grid
+    - div
+  children:
+    - aui-input
+    - span
+    - aui-button
+  context: |
+    Use inside aui-field for labeled form fields. The group removes the child input's border so only the group border is visible. Focus-within highlights the entire group.
+tokens:
+  color:
+    - --aui-border
+    - --aui-surface
+    - --aui-control
+    - --aui-text-muted
+    - --aui-accent-500
+  shape:
+    - --aui-radius
+examples:
+  - description: Currency input with dollar prefix
+    html: |-
+      <aui-input-group>
+        <span slot="prefix">$</span>
+        <aui-input placeholder="0.00"></aui-input>
+      </aui-input-group>
+  - description: Domain input with suffix
+    html: |-
+      <aui-input-group>
+        <aui-input placeholder="example.com"></aui-input>
+        <span slot="suffix">.com</span>
+      </aui-input-group>
+  - description: URL input with both prefix and suffix
+    html: |-
+      <aui-input-group>
+        <span slot="prefix">https://</span>
+        <aui-input placeholder="example.com"></aui-input>
+        <span slot="suffix">/path</span>
+      </aui-input-group>
+  - description: Unit input with suffix
+    html: |-
+      <aui-input-group>
+        <aui-input placeholder="Weight"></aui-input>
+        <span slot="suffix">kg</span>
+      </aui-input-group>
+  - description: Disabled input group
+    html: |-
+      <aui-input-group disabled>
+        <span slot="prefix">$</span>
+        <aui-input placeholder="0.00"></aui-input>
+      </aui-input-group>

package/dist/docs/components/input-otp.yaml

@@ -2,38 +2,30 @@ name: aui-input-otp
 tag: aui-input-otp
 type: component
 summary: Segmented one-time password input.
-description: >
-  A multi-cell input for one-time codes. Auto-advances on entry,
-  navigates on backspace/arrows, and distributes pasted values
-  across cells. A hidden input holds the combined value for forms.
-
+description: |
+  A multi-cell input for one-time codes. Auto-advances on entry, navigates on backspace/arrows, and distributes pasted values across cells. A hidden input holds the combined value for forms.
 base: AgentElement
-
 attributes:
   length:
     syntax: key-value
     type: string
     default: "6"
     description: Number of digit cells to render.
-
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Prevents interaction. Dims visually.
-
   value:
     syntax: key-value
     type: string
     default: ""
     description: Current combined value.
-
   name:
     syntax: key-value
     type: string
     default: ""
     description: Form field name.
-
 a11y:
   role: group
   aria:
@@ -42,7 +34,6 @@ a11y:
     ArrowLeft: Move to previous cell.
     ArrowRight: Move to next cell.
     Backspace: Clear current cell and move to previous.
-
 tokens:
   - name: --aui-input-otp-gap
     default: var(--aui-pad-gap-control)
@@ -86,18 +77,28 @@ tokens:
   - name: --aui-input-otp-border-disabled
     default: var(--aui-stroke-disabled, var(--aui-border-disabled))
     description: Cell border color when disabled.
-
 events:
   aui:complete:
     description: Fired when all cells are filled. detail.value contains the code.
-
 form:
   associated: true
   value: Combined string of all cells.
-
 examples:
-  - html: <aui-input-otp length="6"></aui-input-otp>
-    description: Default 6-digit OTP input.
-
-  - html: <aui-input-otp length="4" name="code"></aui-input-otp>
-    description: 4-digit OTP with form name.
+  - description: Default 6-digit OTP input
+    html: <aui-input-otp length="6"></aui-input-otp>
+  - description: 4-digit OTP with form name
+    html: <aui-input-otp length="4" name="code"></aui-input-otp>
+  - description: Pre-filled OTP value
+    html: <aui-input-otp length="6" value="482910"></aui-input-otp>
+  - description: Disabled OTP input
+    html: <aui-input-otp length="6" value="739201" disabled></aui-input-otp>
+  - description: OTP inside aui-field with label and description
+    html: |-
+      <aui-field label="Verification code" description="Enter the 6-digit code sent to your email.">
+        <aui-input-otp length="6" name="verification"></aui-input-otp>
+      </aui-field>
+  - description: 4-digit OTP inside aui-field with required marker
+    html: |-
+      <aui-field label="PIN code" description="4-digit code from your authenticator app." required>
+        <aui-input-otp length="4" name="pin"></aui-input-otp>
+      </aui-field>