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

package/dist/docs/components/dropdown-menu.yaml

@@ -0,0 +1,137 @@
+name: aui-dropdown-menu
+tag: aui-dropdown-menu
+type: component
+summary: Trigger button + popover menu for actions (not selection).
+description: |
+  A dropdown menu that stamps a trigger button and opens a popover with action items. Unlike aui-select, does not track selection state — items are fire-and-forget actions that emit a select event. Supports label, icon-leading, hide-label for icon-only triggers, and grouped items via aui-optgroup. Keyboard accessible with arrow navigation, Enter to select, and Escape to close.
+base: AgentElement
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Text label for the trigger button.
+  icon-leading:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Icon name for leading position in trigger.
+  icon-trailing:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Icon name for trailing position in trigger.
+  hide-label:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Visually hide the label text (keeps aria-label).
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction.
+  open:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the menu popover is currently open.
+tokens:
+  - name: --aui-dropdown-menu-font-family
+    default: var(--aui-font-family)
+    description: Font family for the trigger and menu items.
+  - name: --aui-dropdown-menu-font-size
+    default: var(--aui-font-size)
+    description: Font size for the trigger and menu items.
+  - name: --aui-dropdown-menu-font-weight
+    default: var(--aui-control-font-weight)
+    description: Font weight for the trigger label.
+  - name: --aui-dropdown-menu-color
+    default: var(--aui-ink)
+    description: Default text color.
+  - name: --aui-dropdown-menu-background
+    default: var(--aui-control, var(--aui-fill))
+    description: Background color of the trigger button.
+  - name: --aui-dropdown-menu-border-color
+    default: var(--aui-stroke)
+    description: Border color of the trigger button.
+  - name: --aui-dropdown-menu-border-radius
+    default: var(--aui-radius)
+    description: Border radius for the trigger and dropdown.
+  - name: --aui-dropdown-menu-size
+    default: var(--aui-size)
+    description: Height of the trigger button.
+  - name: --aui-dropdown-menu-padding-inline
+    default: var(--aui-pad-control-inline)
+    description: Inline padding for the trigger.
+  - name: --aui-dropdown-menu-gap
+    default: var(--aui-pad-gap-control)
+    description: Gap between trigger icon, label, and chevron.
+  - name: --aui-dropdown-menu-icon-size
+    default: var(--aui-icon-size)
+    description: Size of the chevron icon.
+  - name: --aui-dropdown-menu-chevron-color
+    default: var(--aui-ink-muted)
+    description: Color of the dropdown chevron.
+  - name: --aui-dropdown-menu-dropdown-background
+    default: var(--aui-modal, var(--aui-doc))
+    description: Background of the dropdown popover.
+  - name: --aui-dropdown-menu-dropdown-border-color
+    default: var(--aui-border-muted)
+    description: Border color of the dropdown popover.
+  - name: --aui-dropdown-menu-dropdown-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the dropdown popover.
+  - name: --aui-dropdown-menu-dropdown-shadow
+    default: var(--aui-shadow-lg)
+    description: Box shadow of the dropdown popover.
+a11y:
+  role: button (trigger), menu (popover)
+  keyboard:
+    ArrowDown: Open menu or navigate to next item.
+    ArrowUp: Open menu or navigate to previous item.
+    Enter: Open menu or select active item.
+    Space: Open menu or select active item.
+    Escape: Close menu and return focus to trigger.
+    Home: First item.
+    End: Last item.
+events:
+  select:
+    description: Fired when a menu item is activated. Detail contains { value }.
+dependencies:
+  - aui-option
+  - aui-optgroup
+composition:
+  parents:
+    - aui-header
+    - aui-footer
+    - aui-stack
+    - any
+  children:
+    - aui-option
+    - aui-optgroup
+examples:
+  - description: Basic dropdown menu with labeled trigger
+    html: |-
+      <aui-dropdown-menu label="Actions">
+        <aui-option value="edit">Edit</aui-option>
+        <aui-option value="duplicate">Duplicate</aui-option>
+        <aui-option value="delete">Delete</aui-option>
+      </aui-dropdown-menu>
+  - description: Ghost-style dropdown with grouped options
+    html: |-
+      <aui-dropdown-menu label="Actions" ghost>
+        <aui-optgroup label="Edit">
+          <aui-option value="cut">Cut</aui-option>
+          <aui-option value="copy">Copy</aui-option>
+          <aui-option value="paste">Paste</aui-option>
+        </aui-optgroup>
+        <aui-optgroup label="Danger" divider>
+          <aui-option value="delete">Delete</aui-option>
+        </aui-optgroup>
+      </aui-dropdown-menu>
+  - description: Disabled dropdown menu
+    html: |-
+      <aui-dropdown-menu label="Actions" disabled>
+        <aui-option value="edit">Edit</aui-option>
+      </aui-dropdown-menu>

package/dist/docs/components/feed.yaml

@@ -7,7 +7,8 @@ attributes:
   align:
     syntax: key-value
     type: enum
-    values: [end]
+    values:
+      - end
     default: ""
     description: Bottom-anchor content (chat-style).
   scrollable:
@@ -20,39 +21,32 @@ attributes:
     type: boolean
     default: false
     description: Auto-scroll to bottom on new children (when pinned).
-description: >
-  Scrollable feed for messages and activity streams. Uses block layout
-  (not flex) so aui-feed-item margins collapse, giving natural vertical
-  rhythm without explicit gap management.
-
+description: |
+  Scrollable feed for messages and activity streams. Uses block layout (not flex) so aui-feed-item margins collapse, giving natural vertical rhythm without explicit gap management.
 a11y:
   role: feed
 composition:
-  parents: [any]
-  children: [aui-feed-item, any]
-
-# ── Child element ──────────────────────────────────────────
+  parents:
+    - any
+  children:
+    - aui-feed-item
+    - any
 children:
   aui-feed-item:
     tag: aui-feed-item
     summary: Individual item in a feed with margin-based vertical rhythm.
-    description: >
-      Uses margin-block for spacing that collapses between siblings.
-      Consecutive items with the same role attribute (e.g. role="user",
-      role="assistant") receive tighter spacing via adjacent-sibling
-      selectors, producing compact clusters of same-sender messages.
+    description: |
+      Uses margin-block for spacing that collapses between siblings. Consecutive items with the same role attribute (e.g. role="user", role="assistant") receive tighter spacing via adjacent-sibling selectors, producing compact clusters of same-sender messages.
     attributes:
       role:
         syntax: key-value
         type: string
         default: ""
-        description: >
-          Semantic role of the feed item (e.g. "user", "assistant", "system").
-          Consecutive items sharing the same role get tighter margin-block-start
-          (50% of normal spacing).
-
+        description: |
+          Semantic role of the feed item (e.g. "user", "assistant", "system"). Consecutive items sharing the same role get tighter margin-block-start (50% of normal spacing).
 examples:
-  - html: |
+  - description: Scrollable message feed with feed items
+    html: |-
       <aui-feed scrollable style="height: 16rem; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
         <aui-feed-item role="user">
           <aui-inset><aui-text>Hey, how's the project going?</aui-text></aui-inset>
@@ -67,6 +61,3 @@ examples:
           <aui-inset><aui-text>Nice, let's review it together.</aui-text></aui-inset>
         </aui-feed-item>
       </aui-feed>
-    description: >
-      Scrollable message feed with aui-feed-item elements. Consecutive
-      assistant items get tighter spacing via same-role margin collapsing.

package/dist/docs/components/field.yaml

@@ -2,87 +2,76 @@ name: aui-field
 tag: aui-field
 type: element
 summary: Form field wrapper with label, description, and error.
-description: >
-  Wraps a form control with a label, optional description, and
-  error message. All text is rendered CSS-first via content: attr()
-  from HTML attributes — zero JavaScript stamping required. Uses
-  display: flex with column direction, so child controls (aui-input,
-  aui-textarea, aui-select) stretch to full width automatically —
-  no width="full" needed on the child.
-
-# ── Component attributes ──────────────────────────────────
-
+description: |
+  Wraps a form control with a label, optional description, and error message. All text is rendered CSS-first via content: attr() from HTML attributes — zero JavaScript stamping required. Uses display: flex with column direction, so child controls (aui-input, aui-textarea, aui-select) stretch to full width automatically — no width="full" needed on the child.
 attributes:
   label:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Field label text. Rendered via ::before { content: attr(label) }.
-      No JS needed — CSS reads the attribute directly.
-
+    description: |
+      Field label text. Rendered via ::before { content: attr(label) }. No JS needed — CSS reads the attribute directly.
   description:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Help text below the control. Rendered via ::after.
-      Replaced by error text when error attribute is set.
-
+    description: |
+      Help text below the control. Rendered via ::after. Replaced by error text when error attribute is set.
   error:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Error message. When set, replaces description text and
-      cascades danger intent to child controls via CSS custom
-      properties.
-
+    description: |
+      Error message. When set, replaces description text and cascades danger intent to child controls via CSS custom properties.
   required:
     syntax: boolean
     type: boolean
     default: false
-    description: >
-      Appends " *" to the label text via CSS content concatenation.
-      Also sets the required constraint on the wrapped control.
-
+    description: |
+      Appends " *" to the label text via CSS content concatenation. Also sets the required constraint on the wrapped control.
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Dims the field and disables pointer events.
-
-# ── Content model ─────────────────────────────────────────
-
 content:
   model: block
-  accepts: [aui-input, aui-textarea, aui-checkbox, aui-switch, aui-select, aui-radio-group]
+  accepts:
+    - aui-input
+    - aui-textarea
+    - aui-checkbox
+    - aui-switch
+    - aui-select
+    - aui-radio-group
   required: true
-  description: >
-    Exactly one form control as the direct child. The field wrapper
-    provides the label and messages; the control provides the input.
-
-# ── Slots ─────────────────────────────────────────────────
-
+  description: |
+    Exactly one form control as the direct child. The field wrapper provides the label and messages; the control provides the input.
 slots:
   default:
-    accepts: [aui-input, aui-textarea, aui-checkbox, aui-switch, aui-select]
+    accepts:
+      - aui-input
+      - aui-textarea
+      - aui-checkbox
+      - aui-switch
+      - aui-select
     required: true
     description: The form control.
-
-# ── Composition ───────────────────────────────────────────
-
 composition:
-  parents: [aui-stack, aui-grid, form, div, section]
-  children: [aui-input, aui-textarea, aui-checkbox, aui-switch, aui-select, aui-radio-group]
-  context: >
-    Use inside forms, settings panels, registration/login pages.
-    Stack multiple aui-field elements vertically in an aui-stack.
-    The field handles layout (label above, description below);
-    the control handles input behavior.
-
-# ── CSS implementation notes ──────────────────────────────
-
+  parents:
+    - aui-stack
+    - aui-grid
+    - form
+    - div
+    - section
+  children:
+    - aui-input
+    - aui-textarea
+    - aui-checkbox
+    - aui-switch
+    - aui-select
+    - aui-radio-group
+  context: |
+    Use inside forms, settings panels, registration/login pages. Stack multiple aui-field elements vertically in an aui-stack. The field handles layout (label above, description below); the control handles input behavior.
 css-notes:
   attr-bindings:
     - "::before { content: attr(label) } — AB2: label from attribute"
@@ -93,9 +82,6 @@ css-notes:
     - "[error] cascades --aui-stroke to danger color"
     - "[disabled] dims with opacity"
     - "[required] appends asterisk to label"
-
-# ── CSS tokens consumed ──────────────────────────────────
-
 tokens:
   - name: --aui-field-gap
     default: calc(var(--aui-space) * 2)
@@ -121,36 +107,29 @@ tokens:
   - name: --aui-field-error-color
     default: var(--aui-danger, oklch(0.65 0.2 25))
     description: Error message text color.
-
-# ── Examples ──────────────────────────────────────────────
-
 examples:
-  - html: |
+  - description: Basic field with label and input
+    html: |-
       <aui-field label="Email">
         <aui-input type="email" placeholder="you@example.com"></aui-input>
       </aui-field>
-    description: Basic field with label and input.
-
-  - html: |
+  - description: Field with description text
+    html: |-
       <aui-field label="Password" description="Must be at least 8 characters.">
         <aui-input type="password" placeholder="Enter password"></aui-input>
       </aui-field>
-    description: Field with description text.
-
-  - html: |
+  - description: Required field — label shows asterisk
+    html: |-
       <aui-field label="Username" required>
         <aui-input placeholder="Choose a username"></aui-input>
       </aui-field>
-    description: Required field — label shows asterisk.
-
-  - html: |
+  - description: Field with error state
+    html: |-
       <aui-field label="Email" error="This email is already registered.">
         <aui-input type="email" value="taken@example.com"></aui-input>
       </aui-field>
-    description: Field with error state.
-
-  - html: |
+  - description: Disabled field
+    html: |-
       <aui-field label="Name" disabled>
         <aui-input value="Read only" disabled></aui-input>
       </aui-field>
-    description: Disabled field.

package/dist/docs/components/fieldset.yaml

@@ -0,0 +1,92 @@
+name: aui-fieldset
+tag: aui-fieldset
+type: element
+summary: Groups form fields under a legend heading with consistent spacing.
+description: |
+  CSS-only fieldset element that provides consistent legend positioning, border treatment, and spacing. Avoids the cross-browser rendering quirks of the native fieldset element. Legend text is rendered via the legend attribute using ::before.
+presentational:
+  legend:
+    syntax: key-value
+    attribute: legend
+    cascades: false
+    default: null
+    description: Heading text for the group, rendered via CSS attr().
+  description:
+    syntax: key-value
+    attribute: description
+    cascades: false
+    default: null
+    description: Optional description text below the legend.
+modifiers:
+  borderless:
+    syntax: boolean
+    description: |
+      Removes the border, keeps the legend and spacing. Use for ungrouped form sections that still need a heading.
+content:
+  model: flow
+  accepts:
+    - aui-field
+    - aui-input
+    - aui-select
+    - aui-stack
+    - aui-grid
+    - div
+  required: true
+  description: |
+    Form fields and layout containers. Typically aui-field elements with labels and controls.
+slots:
+  default:
+    accepts:
+      - aui-field
+      - aui-stack
+      - aui-grid
+      - aui-divider
+    required: true
+    description: The grouped form fields.
+composition:
+  parents:
+    - aui-stack
+    - aui-content
+    - aui-inset
+    - form
+    - div
+  children:
+    - aui-field
+    - aui-stack
+    - aui-grid
+    - aui-divider
+  context: |
+    Use for multi-section forms and settings pages. Nest inside aui-stack for vertical form layouts. Combine with aui-divider for additional section separation.
+tokens:
+  spacing:
+    - --aui-space
+  color:
+    - --aui-border
+    - --aui-text
+    - --aui-text-muted
+  shape:
+    - --aui-radius
+  typography:
+    - --aui-font-sm
+    - --aui-font-xs
+    - --aui-font-weight-medium
+examples:
+  - description: Basic fieldset with legend
+    html: |-
+      <aui-fieldset legend="Personal Information">
+        <aui-field label="Name"><aui-input></aui-input></aui-field>
+        <aui-field label="Email"><aui-input type="email"></aui-input></aui-field>
+      </aui-fieldset>
+  - description: Fieldset with description
+    html: |-
+      <aui-fieldset legend="Notifications">
+        <span data-fieldset-description>Choose how you want to be notified.</span>
+        <aui-field label="Email"><aui-switch></aui-switch></aui-field>
+        <aui-field label="SMS"><aui-switch></aui-switch></aui-field>
+      </aui-fieldset>
+  - description: Borderless fieldset
+    html: |-
+      <aui-fieldset legend="Billing Address" borderless>
+        <aui-field label="Street"><aui-input></aui-input></aui-field>
+        <aui-field label="City"><aui-input></aui-input></aui-field>
+      </aui-fieldset>

package/dist/docs/components/footer.yaml

@@ -0,0 +1,147 @@
+name: aui-footer
+tag: aui-footer
+type: element
+summary: Float-based layout container for bottom bars.
+description: |
+  Same float-based slot layout as aui-header. Leading floats left, trailing floats right, content slot centers absolutely. Text-align center is scoped to the content slot only. Use for page footers, card action bars, dialog button rows.
+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. Same behavior as aui-header: the footer becomes a container provider and slotted children hide progressively as the container shrinks (trailing < 8rem, leading < 5rem, icon-only < 3rem). Use aui-button in slots for best collapse behavior.
+  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
+    - span
+    - div
+  required: true
+  description: |
+    Action buttons, status text, or metadata in slots. At minimum, provide content in at least one slot.
+slots:
+  default:
+    accepts:
+      - text
+      - span
+      - div
+      - aui-button
+    required: false
+    description: Center/main content.
+  content:
+    accepts:
+      - text
+      - span
+      - div
+      - aui-button
+    required: false
+    description: |
+      Centered 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.
+  leading:
+    accepts:
+      - text
+      - span
+      - aui-button
+    required: false
+    description: Leading element. Floats left with natural text alignment.
+  trailing:
+    accepts:
+      - text
+      - span
+      - aui-button
+      - div
+    required: false
+    description: Trailing element. Floats right with natural text alignment.
+composition:
+  parents:
+    - aui-stack
+    - div
+    - section
+    - main
+  siblings:
+    typical:
+      - aui-content
+      - aui-header
+    pattern: |
+      aui-footer is typically the last child in a vertical container, after aui-content. Pair with aui-header at the top for a full page/card/dialog frame.
+  context: |
+    Use as the bottom bar of a page, section, card, or dialog. Common patterns: copyright line, pagination, confirm/cancel button pairs.
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-font-size
+  spacing:
+    - --aui-pad-control-block
+    - --aui-pad-control-inline
+    - --aui-pad-gap-container
+examples:
+  - description: Simple copyright footer
+    html: |-
+      <aui-footer dividers>
+        <span slot="leading">© 2026 AgentUI</span>
+        <span slot="trailing">v0.0.1</span>
+      </aui-footer>
+  - description: Dialog action footer — cancel + save
+    html: |-
+      <aui-footer dividers>
+        <span slot="trailing">
+          <aui-button ghost label="Cancel"></aui-button>
+          <aui-button primary accent label="Save" icon-leading="check"></aui-button>
+        </span>
+      </aui-footer>
+  - description: Status footer with centered text
+    html: |-
+      <aui-footer dividers>
+        <aui-icon name="check-circle" slot="leading"></aui-icon>
+        <span slot="content">All changes saved</span>
+        <span slot="trailing">
+          <aui-button ghost label="Undo" icon-leading="arrow-up"></aui-button>
+        </span>
+      </aui-footer>
+  - description: Pagination footer
+    html: |-
+      <aui-footer dividers>
+        <span slot="leading">1–10 of 48</span>
+        <span slot="trailing">
+          <aui-button ghost icon-leading="caret-left" label="Previous" hide-label></aui-button>
+          <aui-button ghost icon-leading="caret-right" label="Next" hide-label></aui-button>
+        </span>
+      </aui-footer>