@agent-ui-kit/web-components 0.0.2 → 0.0.4

package/dist/docs/components/checkbox.yaml

@@ -0,0 +1,141 @@
+name: aui-checkbox
+tag: aui-checkbox
+type: component
+summary: Checkbox with custom check and indeterminate indicators.
+description: >
+  Custom checkbox. A hidden native input participates in forms.
+  A visual [data-box] element renders the check/indeterminate icon
+  via ::before pseudo-element. Label rendered via CSS
+  ::after { content: attr(label) } — JS only sets aria-label for
+  accessibility, no DOM stamping for the visible label.
+
+base: AgentElement
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: Controls checkbox and label size.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values: [accent, info, success, warning, danger]
+    description: Color family for the checked state fill.
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction.
+
+  checked:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the checkbox is checked.
+
+  indeterminate:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Shows a dash indicator instead of a check.
+
+  required:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Marks as required for form validation.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Label text displayed next to the checkbox.
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form submission name.
+
+  value:
+    syntax: key-value
+    type: string
+    default: "on"
+    description: Form submission value when checked.
+
+content:
+  model: inline
+  accepts: [input]
+  required: false
+  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]
+  children: null
+  context: >
+    Use inside aui-field for labeled form checkboxes, or standalone
+    with the label attribute. Group in aui-stack for checkbox lists.
+
+a11y:
+  role: checkbox
+  keyboard:
+    Space: Toggles checked state.
+    Enter: Toggles checked state.
+  aria:
+    aria-checked: true, false, or mixed (indeterminate).
+    aria-disabled: Reflected from disabled.
+
+events:
+  change:
+    description: Fires when checked state changes.
+
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-widget-size
+    - --aui-font-size
+  color:
+    - --aui-ink
+    - --aui-control
+    - --aui-fill
+    - --aui-stroke
+    - --aui-solid
+    - --aui-on-solid
+    - --aui-focus
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+css-notes:
+  attr-audit:
+    - "AB1: [checked], [indeterminate], [disabled] — all visual via attributes"
+    - "CG2: ::before on [data-box] for check/dash icon"
+    - "CG3: ::after { content: attr(label) } — label rendered in CSS, overflow: hidden on ::after only"
+    - "CG4: gap uses 2 * space (tightened from 3 * space)"
+    - ":has(> input:focus-visible) — focus ring on visual box"
+
+examples:
+  - html: <aui-checkbox label="Accept terms"></aui-checkbox>
+    description: Default unchecked checkbox.
+
+  - html: <aui-checkbox label="Newsletter" checked></aui-checkbox>
+    description: Pre-checked checkbox.
+
+  - html: <aui-checkbox label="Select all" indeterminate></aui-checkbox>
+    description: Indeterminate state.
+
+  - html: <aui-checkbox label="Unavailable" disabled></aui-checkbox>
+    description: Disabled checkbox.
+
+  - html: <aui-checkbox label="Enabled" checked accent></aui-checkbox>
+    description: Accent-colored checked checkbox.

package/dist/docs/components/command-empty.yaml

@@ -0,0 +1,13 @@
+name: aui-command-empty
+tag: aui-command-empty
+type: component
+summary: Empty state shown when no command items match the query.
+base: AgentElement
+a11y:
+  role: status
+composition:
+  parents: [aui-command]
+  children: null
+examples:
+  - html: <aui-command-empty>No results found.</aui-command-empty>
+    description: Empty state message.

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

@@ -0,0 +1,23 @@
+name: aui-command-group
+tag: aui-command-group
+type: component
+summary: Groups command items under a heading.
+base: AgentElement
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Group heading text.
+a11y:
+  role: group
+composition:
+  parents: [aui-command-list]
+  children: [aui-command-item]
+examples:
+  - html: |
+      <aui-command-group label="Actions">
+        <aui-command-item value="copy">Copy</aui-command-item>
+        <aui-command-item value="paste">Paste</aui-command-item>
+      </aui-command-group>
+    description: Grouped command items.

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

@@ -0,0 +1,19 @@
+name: aui-command-input
+tag: aui-command-input
+type: component
+summary: Search input for the command palette.
+base: AgentElement
+attributes:
+  placeholder:
+    syntax: key-value
+    type: string
+    default: "Search…"
+    description: Placeholder text.
+a11y:
+  role: searchbox
+composition:
+  parents: [aui-command]
+  children: null
+examples:
+  - html: <aui-command-input placeholder="Type a command…"></aui-command-input>
+    description: Command search input.

package/dist/docs/components/command-item.yaml

@@ -0,0 +1,37 @@
+name: aui-command-item
+tag: aui-command-item
+type: component
+summary: Selectable item within a command palette.
+description: >
+  A single action within aui-command-list. Supports value,
+  disabled state, and keywords for supplementary search terms.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Value emitted on selection.
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents selection.
+  keywords:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Extra search terms not visible in the label.
+
+a11y:
+  role: option
+
+composition:
+  parents: [aui-command-list, aui-command-group]
+  children: null
+
+examples:
+  - html: <aui-command-item value="copy">Copy</aui-command-item>
+    description: Simple command item.

package/dist/docs/components/command-list.yaml

@@ -0,0 +1,17 @@
+name: aui-command-list
+tag: aui-command-list
+type: component
+summary: Scrollable container for command items.
+base: AgentElement
+a11y:
+  role: listbox
+composition:
+  parents: [aui-command]
+  children: [aui-command-item, aui-command-group]
+examples:
+  - html: |
+      <aui-command-list>
+        <aui-command-item value="copy">Copy</aui-command-item>
+        <aui-command-item value="paste">Paste</aui-command-item>
+      </aui-command-list>
+    description: Command list with items.

package/dist/docs/components/command.yaml

@@ -0,0 +1,64 @@
+name: aui-command
+tag: aui-command
+type: component
+summary: Command palette with search, keyboard navigation, and grouping.
+description: >
+  Root component for the command palette. Composes aui-command-input
+  (search), aui-command-list (scrollable results), aui-command-item
+  (actions), aui-command-group (grouping), and aui-command-empty
+  (no results). Place inside aui-dialog for modal usage.
+
+base: AgentElement
+
+a11y:
+  role: search
+  keyboard:
+    ArrowDown: Highlight next item.
+    ArrowUp: Highlight previous item.
+    Home: Highlight first item.
+    End: Highlight last item.
+    Enter: Select highlighted item.
+    Escape: Dismiss (fires dismiss event).
+
+events:
+  select:
+    description: Fired when an item is selected. detail contains value, label, item.
+  dismiss:
+    description: Fired on Escape key. Parent dialog can listen to close.
+
+composition:
+  parents: [aui-dialog, any]
+  children: [aui-command-input, aui-command-list, aui-command-empty]
+
+examples:
+  - html: |
+      <aui-command max-width="prose">
+        <aui-command-input placeholder="Type a command…"></aui-command-input>
+        <aui-command-list>
+          <aui-command-group label="Actions">
+            <aui-command-item value="copy">Copy</aui-command-item>
+            <aui-command-item value="paste">Paste</aui-command-item>
+            <aui-command-item value="cut">Cut</aui-command-item>
+          </aui-command-group>
+          <aui-command-group label="Navigation">
+            <aui-command-item value="home" keywords="dashboard">Home</aui-command-item>
+            <aui-command-item value="settings" keywords="preferences config">Settings</aui-command-item>
+            <aui-command-item value="profile" keywords="account user">Profile</aui-command-item>
+          </aui-command-group>
+        </aui-command-list>
+        <aui-command-empty>No results found.</aui-command-empty>
+      </aui-command>
+    description: Command palette with grouped items and search.
+
+  - html: |
+      <aui-command max-width="md">
+        <aui-command-input placeholder="Search actions…"></aui-command-input>
+        <aui-command-list>
+          <aui-command-item value="new-file">New File</aui-command-item>
+          <aui-command-item value="open-file">Open File</aui-command-item>
+          <aui-command-item value="save">Save</aui-command-item>
+          <aui-command-item value="export">Export</aui-command-item>
+        </aui-command-list>
+        <aui-command-empty>No matching commands.</aui-command-empty>
+      </aui-command>
+    description: Simple flat command palette.

package/dist/docs/components/container.yaml

@@ -0,0 +1,298 @@
+name: aui-container
+tag: aui-container
+type: component
+summary: Unified card and panel surface.
+description: >
+  The standard surface element for cards, panels, and sections.
+  Replaces separate Card and Panel components — a single element
+  with bordered, elevation, shadow, and interactive modifiers. Composes
+  aui-header, aui-content, aui-footer as children.
+
+base: AgentElement
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: Cascades size to all children (header, body, footer).
+
+  density:
+    syntax: key-value
+    attribute: density
+    cascades: true
+    default: regular
+    values: [compact, spacious]
+    description: Cascades density to all children.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values: [accent, info, success, warning, danger]
+    description: Cascades color family to all children.
+
+  radius:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: medium
+    values: [sharp, round]
+    description: Controls corner radius of the container.
+
+attributes:
+  kind:
+    syntax: key-value
+    type: enum
+    values: [widget, card, panel]
+    default: card
+    description: >
+      Sets the padding and gap scale for all children.
+      widget: 0.75rem (compact, 1/6–1/4 page).
+      card: 1rem (default, 1/4–1/3 page).
+      panel: 1.75rem (spacious, 1/3–3/4 page, modals).
+
+  href:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Navigation target when interactive. Clicking the container
+      navigates to this URL.
+
+  elevation:
+    syntax: key-value
+    type: enum
+    values: ["1", "2", "3", "4", "5", "6", "7"]
+    default: ""
+    description: >
+      Surface brightness level. 1=doc (dimmest) through
+      7=modal (brightest). Controls background color.
+
+  shadow:
+    syntax: key-value
+    type: enum
+    values: ["1", "2", "3"]
+    default: ""
+    description: >
+      Shadow depth. 1=subtle, 2=medium, 3=prominent.
+
+modifiers:
+  bordered:
+    syntax: boolean
+    description: Adds a visible border around the container.
+
+  interactive:
+    syntax: boolean
+    description: >
+      Makes the container clickable with hover/active states.
+
+content:
+  model: block
+  accepts: [aui-header, aui-content, aui-footer, aui-inset, aui-stack, aui-grid, div, p, any]
+  required: true
+  description: >
+    Typically aui-header + aui-content + aui-footer for structured
+    cards. Or aui-inset for simple content cards. Child headers
+    and footers automatically get separator borders.
+
+slots:
+  default:
+    accepts: [any]
+    required: true
+    description: Container content.
+
+composition:
+  parents: [aui-stack, aui-grid, div, section, main]
+  children:
+    typical: [aui-header, aui-content, aui-footer, aui-inset]
+    pattern: >
+      The standard card pattern is header + body + footer.
+      For simple content, use aui-inset directly.
+  context: >
+    Use for cards in grids, settings panels, dashboard tiles,
+    detail panes. The bordered modifier is the most common —
+    shadow/elevation is for floating/overlay surfaces.
+
+constraints:
+  - when: interactive
+    require: href or click handler
+    reason: Interactive containers need a destination or action.
+
+a11y:
+  role: When interactive, role="button" is set automatically.
+  keyboard:
+    Enter: Navigates to href (when interactive).
+    Space: Navigates to href (when interactive).
+  focus:
+    default: Not focusable unless interactive.
+    interactive: tabindex="0".
+
+events:
+  click:
+    description: Fires on interactive containers. Navigates to href if set.
+
+tokens:
+  color:
+    - --aui-card
+    - --aui-doc
+    - --aui-border-muted
+    - --aui-border-hover
+    - --aui-focus
+  shape:
+    - --aui-radius
+  shadow:
+    - --aui-shadow-sm
+    - --aui-shadow-md
+    - --aui-shadow-lg
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+examples:
+  - html: |
+      <aui-container kind="card" bordered max-width="prose">
+        <aui-header>
+          <aui-stack gap="1">
+            <aui-heading>Project Settings</aui-heading>
+            <aui-text muted size="sm">Make changes to your project here. Click save when you're done.</aui-text>
+          </aui-stack>
+        </aui-header>
+        <aui-content>
+          <aui-inset>
+            <aui-stack gap="4">
+              <aui-field label="Name">
+                <aui-input placeholder="Acme Dashboard"></aui-input>
+              </aui-field>
+              <aui-field label="Description" description="This will be visible to all team members.">
+                <aui-textarea placeholder="A real-time analytics dashboard for the Acme team."></aui-textarea>
+              </aui-field>
+            </aui-stack>
+          </aui-inset>
+        </aui-content>
+        <aui-footer>
+          <span slot="trailing">
+            <aui-stack direction="row" gap="2">
+              <aui-button scrim>Cancel</aui-button>
+              <aui-button primary accent>Save changes</aui-button>
+            </aui-stack>
+          </span>
+        </aui-footer>
+      </aui-container>
+    description: Card kind — Settings form (1.25rem padding).
+
+  - html: |
+      <aui-stack direction="row" gap="3" style="flex-wrap: wrap;">
+        <aui-container kind="widget" bordered style="flex: 1; min-width: 12rem;">
+          <aui-inset>
+            <aui-stack gap="2">
+              <aui-text muted size="sm">Active Users</aui-text>
+              <aui-stack direction="row" gap="2" align-items="center">
+                <aui-heading size="2xl" style="flex: 1;">12</aui-heading>
+                <aui-badge accent>+3 today</aui-badge>
+              </aui-stack>
+            </aui-stack>
+          </aui-inset>
+        </aui-container>
+        <aui-container kind="widget" bordered style="flex: 1; min-width: 12rem;">
+          <aui-inset>
+            <aui-stack gap="2">
+              <aui-text muted size="sm">Uptime</aui-text>
+              <aui-stack direction="row" gap="2" align-items="center">
+                <aui-heading size="2xl" style="flex: 1;">99.9%</aui-heading>
+                <aui-badge success>All systems operational</aui-badge>
+              </aui-stack>
+            </aui-stack>
+          </aui-inset>
+        </aui-container>
+        <aui-container kind="widget" bordered style="flex: 1; min-width: 12rem;">
+          <aui-inset>
+            <aui-stack gap="2">
+              <aui-text muted size="sm">Open Issues</aui-text>
+              <aui-stack direction="row" gap="2" align-items="center">
+                <aui-heading size="2xl" style="flex: 1;">3</aui-heading>
+                <aui-badge warning>Needs review</aui-badge>
+              </aui-stack>
+            </aui-stack>
+          </aui-inset>
+        </aui-container>
+      </aui-stack>
+    description: Widget kind — Compact dashboard stat cards (0.75rem padding).
+
+  - html: |
+      <aui-container kind="panel" bordered max-width="xl">
+        <aui-header>
+          <span slot="leading">
+            <aui-stack direction="row" gap="3" align-items="center">
+              <aui-avatar size="lg" square><aui-icon name="user"></aui-icon></aui-avatar>
+              <aui-stack gap="1">
+                <aui-heading size="xl">Team Members</aui-heading>
+                <aui-text muted size="sm">Manage who has access to this project.</aui-text>
+              </aui-stack>
+            </aui-stack>
+          </span>
+          <span slot="trailing"><aui-button primary accent>Invite</aui-button></span>
+        </aui-header>
+        <aui-content>
+          <aui-inset>
+            <aui-stack gap="4">
+              <aui-stack direction="row" gap="2" align-items="center">
+                <aui-avatar>AJ</aui-avatar>
+                <aui-stack gap="1" style="flex: 1;">
+                  <aui-heading size="md">Alice Johnson</aui-heading>
+                  <aui-text muted size="sm">alice@acme.com · Engineer</aui-text>
+                </aui-stack>
+                <aui-badge>Admin</aui-badge>
+              </aui-stack>
+              <aui-stack direction="row" gap="2" align-items="center">
+                <aui-avatar>BK</aui-avatar>
+                <aui-stack gap="1" style="flex: 1;">
+                  <aui-heading size="md">Bob Kim</aui-heading>
+                  <aui-text muted size="sm">bob@acme.com · Designer</aui-text>
+                </aui-stack>
+                <aui-badge>Member</aui-badge>
+              </aui-stack>
+              <aui-stack direction="row" gap="2" align-items="center">
+                <aui-avatar>CL</aui-avatar>
+                <aui-stack gap="1" style="flex: 1;">
+                  <aui-heading size="md">Carol Lee</aui-heading>
+                  <aui-text muted size="sm">carol@acme.com · Product Manager</aui-text>
+                </aui-stack>
+                <aui-badge>Member</aui-badge>
+              </aui-stack>
+            </aui-stack>
+          </aui-inset>
+        </aui-content>
+      </aui-container>
+    description: Panel kind — Spacious member list (1.75rem padding).
+
+  - html: |
+      <aui-container kind="card" bordered shadow="2" success max-width="md">
+        <aui-inset>
+          <aui-stack gap="4" align-items="center" style="text-align: center;">
+            <aui-icon name="check" size="xl"></aui-icon>
+            <aui-heading size="xl">Payment Successful</aui-heading>
+            <aui-text muted>Your subscription has been renewed. You'll receive a confirmation email shortly.</aui-text>
+            <aui-button primary>Go to Dashboard</aui-button>
+          </aui-stack>
+        </aui-inset>
+      </aui-container>
+    description: Elevated success card with centered content.
+
+  - html: |
+      <aui-container kind="widget" bordered interactive href="#" max-width="sm">
+        <aui-inset>
+          <aui-stack direction="row" gap="2" align-items="center">
+            <aui-avatar square><aui-icon name="gear"></aui-icon></aui-avatar>
+            <aui-stack gap="1" style="flex: 1;">
+              <aui-heading size="md" weight="medium">Preferences</aui-heading>
+              <aui-text muted size="sm">Language, theme, and notifications</aui-text>
+            </aui-stack>
+            <aui-icon name="caret-right" muted></aui-icon>
+          </aui-stack>
+        </aui-inset>
+      </aui-container>
+    description: Widget kind — Compact clickable navigation card.