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

package/dist/docs/components/grid.yaml

@@ -0,0 +1,87 @@
+name: aui-grid
+tag: aui-grid
+type: element
+summary: CSS grid container with column shorthand.
+description: |
+  Grid layout container. Accepts cols attribute for equal-width columns. Default is a single column. Gap scales with density.
+presentational:
+  density:
+    syntax: key-value
+    attribute: density
+    cascades: true
+    default: regular
+    values:
+      - compact
+      - spacious
+    description: Controls gap compression.
+attributes:
+  cols:
+    syntax: key-value
+    type: enum
+    values:
+      - "2"
+      - "3"
+      - "4"
+      - "5"
+      - "6"
+    default: null
+    description: |
+      Number of equal-width grid columns via repeat(N, 1fr). Default is a single column when absent.
+layout:
+  gap:
+    syntax: key-value
+    attribute: gap
+    values:
+      - "0"
+      - "1"
+      - "2"
+      - "3"
+      - "4"
+      - "5"
+      - "6"
+      - "7"
+    description: Explicit gap size (0–7 space units). Overrides density-driven gap.
+content:
+  model: block
+  accepts: any
+  required: true
+  min-children: 1
+  description: |
+    Grid children become grid items. Each child occupies one cell by default. Use CSS grid-column/grid-row on children for spanning.
+slots:
+  default:
+    accepts:
+      - any
+    required: true
+    description: Grid cell children.
+composition:
+  parents:
+    - aui-stack
+    - aui-content
+    - aui-inset
+    - div
+    - section
+    - main
+  children: any
+  context: |
+    Use for card grids, form layouts with columns, dashboard panels. For simple vertical/horizontal stacking, prefer aui-stack.
+tokens:
+  spacing:
+    - --aui-pad-gap-container
+examples:
+  - description: Three-column grid
+    html: |-
+      <aui-grid cols="3">
+        <div>1</div>
+        <div>2</div>
+        <div>3</div>
+        <div>4</div>
+        <div>5</div>
+        <div>6</div>
+      </aui-grid>
+  - description: Two-column grid
+    html: |-
+      <aui-grid cols="2">
+        <div>Left</div>
+        <div>Right</div>
+      </aui-grid>

package/dist/docs/components/gripper.yaml

@@ -2,32 +2,24 @@ name: aui-gripper
 tag: aui-gripper
 type: component
 summary: Resize handle for panes and resizable containers.
-description: >
-  A draggable separator that emits resize events with delta values.
-  Supports both horizontal (col-resize) and vertical (row-resize)
-  orientations. Keyboard resizing via arrow keys. Has a 10px hit area
-  with a 2px feedback line at rest (border-muted) that expands to a
-  6px accent bar on click. Width/height transition is animated between
-  rest and active states.
-
+description: |
+  A draggable separator that emits resize events with delta values. Supports both horizontal (col-resize) and vertical (row-resize) orientations. Keyboard resizing via arrow keys. Has a 10px hit area with a 2px feedback line at rest (border-muted) that expands to a 6px accent bar on click. Width/height transition is animated between rest and active states.
 base: AgentElement
-
 attributes:
   orientation:
     syntax: key-value
     type: enum
-    values: [horizontal, vertical]
+    values:
+      - horizontal
+      - vertical
     default: horizontal
-    description: >
-      Drag axis. Horizontal = vertical divider (drag left/right).
-      Vertical = horizontal divider (drag up/down).
-
+    description: |
+      Drag axis. Horizontal = vertical divider (drag left/right). Vertical = horizontal divider (drag up/down).
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Prevents drag interaction.
-
 a11y:
   role: separator
   keyboard:
@@ -38,7 +30,6 @@ a11y:
     Shift+Arrow: Resize by 10px instead of 1px.
   aria:
     aria-orientation: Set from orientation attribute.
-
 tokens:
   - name: --aui-gripper-color
     default: var(--aui-border-muted)
@@ -61,7 +52,6 @@ tokens:
   - name: --aui-gripper-border-radius-dragging
     default: 6px
     description: Border radius of the accent bar while dragging.
-
 events:
   aui:resize-start:
     description: Fired when drag begins.
@@ -69,10 +59,8 @@ events:
     description: Fired on drag movement. detail contains dx, dy, delta.
   aui:resize-end:
     description: Fired when drag ends. detail contains final dx, dy, delta.
-
 examples:
-  - html: <aui-gripper></aui-gripper>
-    description: Default horizontal gripper (drag left/right).
-
-  - html: <aui-gripper orientation="vertical"></aui-gripper>
-    description: Vertical gripper (drag up/down).
+  - description: Default horizontal gripper (drag left/right)
+    html: <aui-gripper></aui-gripper>
+  - description: Vertical gripper (drag up/down)
+    html: <aui-gripper orientation="vertical"></aui-gripper>

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,54 @@
+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="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

@@ -0,0 +1,77 @@
+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.
+base: AgentElement
+attributes:
+  anchor:
+    syntax: key-value
+    type: string
+    default: ""
+    description: CSS selector for the anchor element. Falls back to previous sibling or parent.
+  delay:
+    syntax: key-value
+    type: string
+    default: "300"
+    description: Show delay in milliseconds after hover starts.
+  hide-delay:
+    syntax: key-value
+    type: string
+    default: "200"
+    description: Hide delay in milliseconds after hover ends.
+  side:
+    syntax: key-value
+    type: string
+    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))
+    description: Background color of the card.
+  - name: --aui-hover-card-border-color
+    default: var(--aui-border-muted)
+    description: Border color of the card.
+  - name: --aui-hover-card-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the card.
+  - name: --aui-hover-card-shadow
+    default: var(--aui-shadow-lg)
+    description: Box shadow of the card.
+  - name: --aui-hover-card-padding
+    default: calc(var(--aui-space) * 3)
+    description: Padding inside the card.
+  - 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
+examples:
+  - 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: 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>