@agent-ui-kit/web-components 0.0.8 → 0.0.15

package/dist/docs/components/input.yaml

@@ -2,190 +2,182 @@ name: aui-input
 tag: aui-input
 type: component
 summary: Text input with type variants, slots, and clearable mode.
-description: >
-  Single-line text input. The wrapper element owns the visual chrome
-  (border, radius, padding, focus ring). A native <input> lives
-  inside as a light DOM child with all browser chrome stripped.
-  Supports leading/trailing icon slots and a clearable button.
-  Defaults to width: 20ch for standalone use. Automatically stretches
-  to full width when placed inside aui-field. Use width="full" on the
-  element to override the default width in other contexts.
-
+description: |
+  Single-line text input. The wrapper element owns the visual chrome (border, radius, padding, focus ring). A native <input> lives inside as a light DOM child with all browser chrome stripped. Supports leading/trailing icon slots and a clearable button. Defaults to width: 20ch for standalone use. Automatically stretches to full width when placed inside aui-field. Use width="full" on the element to override the default width in other contexts.
 base: AgentElement
-
-# ── Presentational attributes ─────────────────────────────
-
 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 height, font size, and icon size.
-
   radius:
     syntax: boolean
     exclusive: true
     cascades: true
     default: medium
-    values: [sharp, round]
+    values:
+      - sharp
+      - round
     description: Controls border radius.
-
   density:
     syntax: key-value
     attribute: density
     cascades: true
     default: regular
-    values: [compact, spacious]
+    values:
+      - compact
+      - spacious
     description: Controls padding compression.
-
   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 input border and focus ring.
-
-# ── Component attributes ──────────────────────────────────
-
 attributes:
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Prevents interaction. Dims visually.
-
   readonly:
     syntax: boolean
     type: boolean
     default: false
     description: Allows selection but prevents editing. Dashed border.
-
   required:
     syntax: boolean
     type: boolean
     default: false
     description: Marks the input as required for form validation.
-
   clearable:
     syntax: boolean
     type: boolean
     default: false
     description: Shows a clear button when the input has a value.
-
   autofocus:
     syntax: boolean
     type: boolean
     default: false
     description: Focuses the input on mount.
-
   type:
     syntax: key-value
     type: enum
-    values: [text, email, password, search, url, tel, number]
+    values:
+      - text
+      - email
+      - password
+      - search
+      - url
+      - tel
+      - number
     default: text
     description: HTML input type. Forwarded to the native input.
-
   placeholder:
     syntax: key-value
     type: string
     default: ""
     description: Placeholder text. Forwarded to the native input.
-
   value:
     syntax: key-value
     type: string
     default: ""
     description: Current input value. Two-way synced with the native input.
-
   name:
     syntax: key-value
     type: string
     default: ""
     description: Form submission name. Forwarded to the native input.
-
   pattern:
     syntax: key-value
     type: string
     default: ""
     description: Regex validation pattern. Forwarded to the native input.
-
   minlength:
     syntax: key-value
     type: string
     default: ""
     description: Minimum character count.
-
   maxlength:
     syntax: key-value
     type: string
     default: ""
     description: Maximum character count.
-
   autocomplete:
     syntax: key-value
     type: string
     default: ""
     description: Browser autocomplete hint. Forwarded to the native input.
-
-# ── Modifiers ─────────────────────────────────────────────
-
-# None — clearable is a component attribute, not a modifier.
-
-# ── Content model ─────────────────────────────────────────
-
+  debounce:
+    syntax: key-value
+    type: string
+    default: "200"
+    description: Debounce delay in ms for the search event. Only applies when type="search".
+  no-clear:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Hides the auto-stamped clear button. Only applies when type="search".
 content:
   model: mixed
-  accepts: [input, span, svg, button]
+  accepts:
+    - input
+    - span
+    - svg
+    - button
   required: false
-  description: >
-    The component auto-stamps a native <input> if none exists.
-    Slot elements (leading/trailing) are optional. Do not place
-    block elements inside.
-
-# ── Slots ─────────────────────────────────────────────────
-
+  description: |
+    The component auto-stamps a native <input> if none exists. Slot elements (leading/trailing) are optional. Do not place block elements inside.
 slots:
   default:
-    accepts: [input]
+    accepts:
+      - input
     required: false
-    description: >
+    description: |
       The native input element. Auto-stamped if not provided.
-
   leading:
-    accepts: [span, svg, img]
+    accepts:
+      - span
+      - svg
+      - img
     required: false
     description: Leading icon. Adapts grid to auto 1fr.
-
   trailing:
-    accepts: [span, svg, img]
+    accepts:
+      - span
+      - svg
+      - img
     required: false
     description: Trailing icon. Adapts grid to 1fr auto.
-
-# ── Composition ───────────────────────────────────────────
-
 composition:
-  parents: [aui-field, aui-stack, aui-grid, form, div]
+  parents:
+    - aui-field
+    - aui-stack
+    - aui-grid
+    - form
+    - div
   children: null
-  context: >
-    Use inside aui-field for labeled form inputs. Can also be
-    used standalone in search bars, inline editors, or compact
-    toolbars. The wrapper is the styling surface — the inner
-    input is a plain native element.
-
-# ── Constraints ───────────────────────────────────────────
-
+  context: |
+    Use inside aui-field for labeled form inputs. Can also be used standalone in search bars, inline editors, or compact toolbars. The wrapper is the styling surface — the inner input is a plain native element.
 constraints:
   - when: inside aui-field
     require: aui-field[label]
-    reason: >
-      Inputs need an accessible label. When used inside aui-field,
-      the field provides the label. When standalone, add aria-label.
-
-# ── Accessibility ─────────────────────────────────────────
-
+    reason: |
+      Inputs need an accessible label. When used inside aui-field, the field provides the label. When standalone, add aria-label.
 a11y:
   role: implicit (native input)
   keyboard:
@@ -195,27 +187,21 @@ a11y:
     aria-disabled: Reflected from disabled attribute.
     aria-readonly: Reflected from readonly attribute.
     aria-required: Reflected from required attribute.
-
-# ── Events ────────────────────────────────────────────────
-
 events:
   input:
     description: Fires on every keystroke. Value attribute syncs automatically.
   change:
     description: Fires on blur or enter. Bubbles from the native input.
-
-# ── CSS implementation notes ──────────────────────────────
-
+  search:
+    description: |
+      Debounced event fired after typing stops (type="search" only). Detail contains { value: string }.
 css-notes:
   attr-audit:
     - "AB1: [disabled], [readonly], [clearable] — all visual states via attributes"
     - "AB5: No classes used — all state is attribute-driven"
-    - ":focus-within on wrapper — delegates focus ring to the container"
-    - ":has(> [slot='leading']) — slot-adaptive grid, same pattern as button"
-    - ":not(:has(> input:not(:placeholder-shown))) — hides clear button when empty"
-
-# ── CSS tokens consumed ──────────────────────────────────
-
+    - :focus-within on wrapper — delegates focus ring to the container
+    - :has(> [slot='leading']) — slot-adaptive grid, same pattern as button
+    - :not(:has(> input:not(:placeholder-shown))) — hides clear button when empty
 tokens:
   - name: --aui-input-size
     default: var(--aui-size)
@@ -268,49 +254,48 @@ tokens:
   - name: --aui-input-border-focus
     default: var(--aui-focus)
     description: Border and outline color on focus.
-
-# ── Examples ──────────────────────────────────────────────
-
 examples:
-  - html: <aui-input placeholder="Enter text"></aui-input>
-    description: Basic text input.
-
-  - html: <aui-input type="email" placeholder="you@example.com"></aui-input>
-    description: Email input.
-
-  - html: <aui-input type="password" placeholder="Password"></aui-input>
-    description: Password input.
-
-  - html: <aui-input placeholder="Search" clearable></aui-input>
-    description: Clearable input with clear button.
-
-  - html: <aui-input placeholder="Disabled" disabled></aui-input>
-    description: Disabled input.
-
-  - html: <aui-input value="Read only" readonly></aui-input>
-    description: Read-only input with dashed border.
-
-  - html: |
+  - description: Basic text input
+    html: <aui-input placeholder="Enter text"></aui-input>
+  - description: Email input
+    html: <aui-input type="email" placeholder="you@example.com"></aui-input>
+  - description: Password input
+    html: <aui-input type="password" placeholder="Password"></aui-input>
+  - description: Clearable input with clear button
+    html: <aui-input placeholder="Search" clearable></aui-input>
+  - description: Disabled input
+    html: <aui-input placeholder="Disabled" disabled></aui-input>
+  - description: Read-only input with dashed border
+    html: <aui-input value="Read only" readonly></aui-input>
+  - description: Input with leading icon
+    html: |-
       <aui-input placeholder="Search">
         <span slot="leading">🔍</span>
       </aui-input>
-    description: Input with leading icon.
-
-  - html: |
+  - description: Input with leading and trailing icons
+    html: |-
       <aui-input type="email" placeholder="Email">
         <span slot="leading">✉</span>
         <span slot="trailing">✓</span>
       </aui-input>
-    description: Input with leading and trailing icons.
-
-  - html: |
+  - description: Input inside a labeled field
+    html: |-
       <aui-field label="Email" required>
         <aui-input type="email" placeholder="you@example.com"></aui-input>
       </aui-field>
-    description: Input inside a labeled field.
-
-  - html: |
+  - description: Input with error state via parent field
+    html: |-
       <aui-field label="Username" error="Already taken.">
         <aui-input value="admin"></aui-input>
       </aui-field>
-    description: Input with error state via parent field.
+  - description: Search input with auto icon and clear
+    html: <aui-input type="search" placeholder="Search..."></aui-input>
+  - description: Search input with custom debounce (500ms)
+    html: <aui-input type="search" placeholder="Search..." debounce="500"></aui-input>
+  - description: Search input without clear button
+    html: <aui-input type="search" placeholder="Search..." no-clear></aui-input>
+  - description: Search input inside a field
+    html: |-
+      <aui-field label="Filter">
+        <aui-input type="search" placeholder="Filter items..." width="full"></aui-input>
+      </aui-field>

package/dist/docs/components/inset.yaml

@@ -0,0 +1,59 @@
+name: aui-inset
+tag: aui-inset
+type: element
+summary: Density-aware padding wrapper.
+description: |
+  Block-level padding container. Padding scales with density via --aui-pad-* tokens. Use inside containers for consistent content spacing without adding padding to the container itself.
+presentational:
+  density:
+    syntax: key-value
+    attribute: density
+    cascades: true
+    default: regular
+    values:
+      - compact
+      - spacious
+    description: |
+      Controls padding scale. Typically inherited from a parent rather than set directly on the inset.
+content:
+  model: block
+  accepts: any
+  required: true
+  description: |
+    Any content — text, block elements, other aui elements. Inset only adds padding; it does not alter layout flow.
+slots:
+  default:
+    accepts:
+      - any
+    required: true
+    description: Inset content.
+composition:
+  parents:
+    - aui-content
+    - aui-stack
+    - div
+    - section
+    - main
+    - article
+  children: any
+  context: |
+    The standard way to add content padding. Use inside aui-content for padded scrollable content. Use inside cards or dialogs for consistent insets. Density inherits from ancestors — a compact parent automatically tightens the inset padding.
+tokens:
+  spacing:
+    - --aui-pad-container
+examples:
+  - description: Default density inset
+    html: |-
+      <div style="border: 1px dashed var(--aui-border-muted);">
+        <aui-inset>Default density padding</aui-inset>
+      </div>
+  - description: Compact density inset (density set on parent, cascades down)
+    html: |-
+      <div density="compact" style="border: 1px dashed var(--aui-border-muted);">
+        <aui-inset>Compact density padding</aui-inset>
+      </div>
+  - description: Spacious density inset
+    html: |-
+      <div density="spacious" style="border: 1px dashed var(--aui-border-muted);">
+        <aui-inset>Spacious density padding</aui-inset>
+      </div>

package/dist/docs/components/kbd.yaml

@@ -0,0 +1,57 @@
+name: aui-kbd
+tag: aui-kbd
+type: element
+summary: Keyboard shortcut indicator styled as a key cap.
+description: |
+  Inline element styled like a physical key cap. Uses monospace font. Compose multiple aui-kbd in a row to show key combinations. Purely decorative — no keyboard interaction handling.
+content:
+  model: inline
+  accepts:
+    - text
+  required: true
+  description: |
+    Single key label — one character (K, ⌘, ⇧) or short word (Ctrl, Shift, Enter). Keep to one key per element.
+slots:
+  default:
+    accepts:
+      - text
+    required: true
+    description: Key label text.
+composition:
+  parents:
+    - aui-stack
+    - span
+    - p
+    - div
+    - td
+  children: null
+  pattern: |
+    Compose multiple aui-kbd elements in a row to show key combinations. Use aui-stack direction="row" gap="1" as the container, or inline within text.
+  context: |
+    Use in documentation, tooltips, menu item hints. For a "Cmd+K" shortcut, render as two adjacent aui-kbd elements.
+tokens:
+  typography:
+    - --aui-font-family-mono
+    - --aui-widget-font
+  color:
+    - --aui-ink-muted
+    - --aui-control
+    - --aui-border-muted
+  shape:
+    - --aui-radius-sharp
+examples:
+  - description: Single key
+    html: <aui-kbd>K</aui-kbd>
+  - description: Key combination (Cmd+K)
+    html: |-
+      <aui-stack direction="row" gap="1" align-items="center">
+        <aui-kbd>⌘</aui-kbd>
+        <aui-kbd>K</aui-kbd>
+      </aui-stack>
+  - description: Multi-key shortcut
+    html: |-
+      <aui-stack direction="row" gap="1" align-items="center">
+        <aui-kbd>Ctrl</aui-kbd>
+        <aui-kbd>Shift</aui-kbd>
+        <aui-kbd>P</aui-kbd>
+      </aui-stack>

package/dist/docs/components/link.yaml

@@ -0,0 +1,76 @@
+name: aui-link
+tag: aui-link
+type: component
+summary: Styled anchor for inline and standalone links.
+description: |
+  Inline link element with consistent styling, hover underline, and focus ring. Supports muted and intent coloring. External attribute appends an arrow icon via CSS ::after pseudo-element.
+base: AgentElement
+presentational:
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: accent
+    values:
+      - accent
+      - success
+      - warning
+      - danger
+    description: Link color family.
+modifiers:
+  muted:
+    syntax: boolean
+    description: |
+      Uses muted text color instead of accent. Hover restores full text color.
+  external:
+    syntax: boolean
+    description: |
+      Appends an external-link arrow icon via CSS ::after. Indicates the link opens an external destination.
+attributes:
+  href:
+    type: URL
+    required: false
+    description: Link destination URL.
+content:
+  model: inline
+  accepts:
+    - text
+    - aui-icon
+  required: true
+  description: |
+    Link label text. Keep concise — one to a few words.
+slots:
+  default:
+    accepts:
+      - text
+      - aui-icon
+    required: true
+    description: Link label text.
+tokens:
+  color:
+    - --aui-link-color
+    - --aui-link-color-hover
+  shape:
+    - --aui-link-radius
+examples:
+  - description: Basic accent link
+    html: <aui-link href="/about">Learn more</aui-link>
+  - description: Muted secondary link
+    html: <aui-link href="/docs" muted>Documentation</aui-link>
+  - description: External link with arrow icon
+    html: <aui-link href="https://example.com" external>Visit site</aui-link>
+  - description: Danger intent link
+    html: <aui-link href="/delete" danger>Delete account</aui-link>
+  - description: Inline link within text flow
+    html: |-
+      <aui-text>
+        Read the <aui-link href="/terms">terms of service</aui-link> before continuing.
+      </aui-text>
+  - description: Row of link variants
+    html: |-
+      <aui-stack direction="row" gap="4">
+        <aui-link href="/about">About</aui-link>
+        <aui-link href="/docs" muted>Docs</aui-link>
+        <aui-link href="https://github.com" external>GitHub</aui-link>
+        <aui-link href="/delete" danger>Delete</aui-link>
+      </aui-stack>

package/dist/docs/components/meter.yaml

@@ -0,0 +1,78 @@
+name: aui-meter
+tag: aui-meter
+type: component
+summary: Visual gauge for known-range scalar values.
+description: |
+  Static measurement gauge within a known range. Fill width driven by --aui-meter-pct CSS custom property computed from value, min, and max attributes. Semantically distinct from aui-progress — meters represent a static measurement (disk usage, budget), not task completion. Intent colors indicate threshold states.
+base: AgentElement
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: md
+    values:
+      - sm
+      - md
+      - lg
+    description: Track height — sm (4px), md (6px), lg (10px).
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: accent
+    values:
+      - accent
+      - success
+      - warning
+      - danger
+    description: Fill color reflecting threshold state.
+attributes:
+  value:
+    type: number
+    default: "0"
+    description: Current measurement value.
+  min:
+    type: number
+    default: "0"
+    description: Range minimum.
+  max:
+    type: number
+    default: "100"
+    description: Range maximum.
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: |
+    No content — meter is a visual gauge only.
+slots: {}
+tokens:
+  sizing:
+    - --aui-meter-height
+  color:
+    - --aui-meter-background
+    - --aui-meter-fill
+  shape:
+    - --aui-meter-radius
+examples:
+  - description: Default accent meter at 45%
+    html: <aui-meter value="45"></aui-meter>
+  - description: Warning meter at 75%
+    html: <aui-meter value="75" warning></aui-meter>
+  - description: Danger meter at 95%
+    html: <aui-meter value="95" danger></aui-meter>
+  - description: Three sizes with different values
+    html: |-
+      <aui-stack gap="3">
+        <aui-meter value="30" size="sm"></aui-meter>
+        <aui-meter value="60"></aui-meter>
+        <aui-meter value="85" size="lg" warning></aui-meter>
+      </aui-stack>
+  - description: Meter with context labels in a row
+    html: |-
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-text size="xs" muted>Disk usage</aui-text>
+        <aui-meter value="82" warning style="flex: 1"></aui-meter>
+        <aui-text size="xs" muted>82%</aui-text>
+      </aui-stack>