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

package/dist/docs/components/button.yaml

@@ -2,328 +2,274 @@ name: aui-button
 tag: aui-button
 type: component
 summary: Polymorphic action trigger with press semantics and resize-responsive collapse.
-description: >
-  The foundational interactive element. Uses inline-flex layout with a
-  CSS-generated label (::after { content: attr(label) }). Supports solid,
-  outline, ghost, and scrim variants across all intent families. Renders as
-  a button by default; set href to switch to link mode. Icon-only mode
-  available via the hide-label attribute. Icons are stamped as
-  <aui-icon slot="leading/trailing"> by JS from icon-leading / icon-trailing
-  attributes. Text adornments are stamped as <span slot="leading-text/trailing-text">
-  from text-leading / text-trailing attributes. The component auto-detects
-  icon-only state when no label attribute and no child text nodes are present.
-  Progressive collapse via the resize trait hides adornments as the
-  container shrinks.
-
+description: |
+  The foundational interactive element. Uses inline-flex layout with a CSS-generated label (::after { content: attr(label) }). Supports solid, outline, ghost, and scrim variants across all intent families. Renders as a button by default; set href to switch to link mode. Icon-only mode available via the hide-label attribute. Icons are stamped as <aui-icon slot="leading/trailing"> by JS from icon-leading / icon-trailing attributes. Text adornments are stamped as <span slot="leading-text/trailing-text"> from text-leading / text-trailing attributes. The component auto-detects icon-only state when no label attribute and no child text nodes are present. Progressive collapse via the resize trait hides adornments as the container shrinks.
 base: AgentElement
-
-# ── Layout ───────────────────────────────────────────────
-# Button uses inline-flex (not inline-grid).
-# Label text is rendered via CSS ::after { content: attr(label) } — no JS stamping.
-# Height is fixed at var(--aui-size), min-width at var(--aui-size).
-# Padding: padding-block var(--aui-pad-control-block), padding-inline calc(var(--aui-space) * 3).
-
-# ── Presentational attributes ─────────────────────────────
-# Boolean HTML attributes. Each group is mutually exclusive.
-# All cascade to descendants via CSS custom property inheritance.
-# Default appearance = absence of attribute (no "medium", no "neutral").
-
 presentational:
   size:
     syntax: key-value
     attribute: size
     cascades: true
     default: medium
-    values: [xs, sm, md, lg, xl]
-    description: >
-      Controls dimensions, typography, icon size, and spacing
-      simultaneously. Swaps 7 tokens at once.
-
+    values:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
+      - fill
+    description: |
+      Controls dimensions, typography, icon size, and spacing simultaneously. Swaps 7 tokens at once. The special "fill" value stretches the button to 100% width and height of its parent cell with no minimum constraints.
   radius:
     syntax: boolean
     exclusive: true
     cascades: true
     default: medium
-    values: [sharp, round]
+    values:
+      - sharp
+      - round
     description: Controls border radius. Default is a medium radius.
-
   density:
     syntax: key-value
     attribute: density
     cascades: true
     default: regular
-    values: [compact, spacious]
-    description: >
-      Controls padding and spacing compression. Unlike size (which
-      shifts the active step), density redefines the entire scale.
-
+    values:
+      - compact
+      - spacious
+    description: |
+      Controls padding and spacing compression. Unlike size (which shifts the active step), density redefines the entire scale.
   variant:
     syntax: boolean
     exclusive: true
     cascades: true
     default: default
-    values: [primary, outline, ghost, scrim]
-    description: >
-      Surface expression — how the component fills its space.
-      Default is a standard fill with role-appropriate background.
-
+    values:
+      - primary
+      - outline
+      - ghost
+      - scrim
+    description: |
+      Surface expression — how the component fills its space. Default is a standard fill with role-appropriate background.
   intent:
     syntax: boolean
     exclusive: true
     cascades: true
     default: neutral
-    values: [accent, info, success, warning, danger]
-    description: >
-      Color family. All color tokens remap to the selected palette.
-      Default is the neutral palette.
-
+    values:
+      - accent
+      - info
+      - success
+      - warning
+      - danger
+    description: |
+      Color family. All color tokens remap to the selected palette. Default is the neutral palette.
   state:
     syntax: boolean
     exclusive: false
     cascades: false
     default: none
-    values: [active, selected, highlighted]
-    description: >
-      Visual state indicators. Unlike other presentational groups,
-      state values can combine (e.g. selected + highlighted).
-
-# ── Cross-product sections ────────────────────────────────
-
+    values:
+      - active
+      - selected
+      - highlighted
+    description: |
+      Visual state indicators. Unlike other presentational groups, state values can combine (e.g. selected + highlighted).
 cross:
-  - dimensions: [variant, intent]
+  - dimensions:
+      - variant
+      - intent
     label: Variant x Intent
-    description: >
-      Each variant with each intent color. The most common
-      composition pattern for buttons.
-
-# ── Component attributes ──────────────────────────────────
-# Signal-backed, observed. Key-value or boolean HTML attributes.
-
+    description: |
+      Each variant with each intent color. The most common composition pattern for buttons.
 attributes:
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Prevents interaction. Dims visually.
-
   loading:
     syntax: boolean
     type: boolean
     default: false
     description: Shows loading state. Blocks interaction but not focus.
-
   type:
     syntax: key-value
     type: enum
-    values: [button, submit, reset]
+    values:
+      - button
+      - submit
+      - reset
     default: button
-    description: >
-      Button behavior within a form. submit calls form.requestSubmit(),
-      reset calls form.reset().
-
+    description: |
+      Button behavior within a form. submit calls form.requestSubmit(), reset calls form.reset().
   label:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Primary button label. Rendered via CSS ::after { content: attr(label) }
-      — no JS stamping. Also maps to aria-label for accessibility.
-      When omitted and no child text nodes exist, the button auto-detects
-      icon-only mode.
-
+    description: |
+      Primary button label. Rendered via CSS ::after { content: attr(label) } — no JS stamping. Also maps to aria-label for accessibility. When omitted and no child text nodes exist, the button auto-detects icon-only mode.
   icon-leading:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Icon registry name for the leading icon. JS stamps an
-      <aui-icon name="..." slot="leading"> element into the button.
-
+    description: |
+      Icon registry name for the leading icon. JS stamps an <aui-icon name="..." slot="leading"> element into the button.
   icon-trailing:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Icon registry name for the trailing icon. JS stamps an
-      <aui-icon name="..." slot="trailing"> element into the button.
-
+    description: |
+      Icon registry name for the trailing icon. JS stamps an <aui-icon name="..." slot="trailing"> element into the button.
   text-leading:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Text adornment before the label. JS stamps a
-      <span slot="leading-text"> element. Separate from the icon slot.
-
+    description: |
+      Text adornment before the label. JS stamps a <span slot="leading-text"> element. Separate from the icon slot.
   text-trailing:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Text adornment after the label. JS stamps a
-      <span slot="trailing-text"> element. Separate from the icon slot.
-
+    description: |
+      Text adornment after the label. JS stamps a <span slot="trailing-text"> element. Separate from the icon slot.
   icon:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Shorthand icon name from the icon registry. Convenience for
-      hide-label buttons — equivalent to icon-leading.
-
+    description: |
+      Shorthand icon name from the icon registry. Convenience for hide-label buttons — equivalent to icon-leading.
   href:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      When set, button acts as a navigation link. Clicking navigates
-      to the given URL.
-
-# ── Modifiers ─────────────────────────────────────────────
-
+    description: |
+      When set, button acts as a navigation link. Clicking navigates to the given URL.
 modifiers:
   hide-label:
     syntax: boolean
-    description: >
-      Hides the label text and collapses the button to icon-only.
-      Square button sized to --aui-size. Removes inline padding.
-      Use with a slotted icon, icon-leading, or the icon attribute.
-
+    description: |
+      Hides the label text and collapses the button to icon-only. Square button sized to --aui-size with width/height = var(--aui-size) and padding: 0. Use with a slotted icon, icon-leading, or the icon attribute. Auto-detected when no label attribute and no child text nodes are present.
+  icon-size:
+    syntax: key-value
+    values:
+      - half
+      - sm
+      - md
+      - lg
+      - full
+    description: |
+      Percentage-based icon sizing within fill-mode buttons (size="fill"). Maps to 50%, 62.5%, 75%, 87.5%, 100% respectively.
   text:
     syntax: key-value
-    values: [left, right]
-    description: >
-      Overrides the default centered text alignment.
-      Useful for wide buttons where left- or right-aligned labels
-      feel more natural.
-
-# ── Internal data attributes ─────────────────────────────
-
+    values:
+      - left
+      - right
+    description: |
+      Overrides the default centered text alignment. Useful for wide buttons where left- or right-aligned labels feel more natural.
 data-attributes:
   data-has-text:
     set-by: JS
-    description: >
-      Set automatically by JS when the button has child text nodes.
-      Used in the auto icon-only detection selector:
-      :not([label]):not([data-has-text]):has(> [slot]):not(:has(> :not([slot])))
-
-# ── Resize-responsive collapse ───────────────────────────
-# These data attributes are set by the resize trait based on
-# the button's own measured width. CSS hides adornments accordingly.
-
+    description: |
+      Set automatically by JS when the button has child text nodes. Used in the auto icon-only detection selector: :not([label]):not([data-has-text]):has(> [slot]):not(:has(> :not([slot])))
 resize:
   data-resize-small:
-    threshold: "< 128px"
-    description: >
+    threshold: < 128px
+    description: |
       Hides leading icon and leading-text adornment.
-
   data-resize-xsmall:
-    threshold: "< 96px"
-    description: >
+    threshold: < 96px
+    description: |
       Hides trailing icon and trailing-text adornment.
-
   data-resize-compact:
-    threshold: "< 72px"
-    description: >
-      Hides everything except the leading icon. Applies tight padding.
-      Button collapses to near icon-only appearance.
-
-# ── Content model ─────────────────────────────────────────
-
+    threshold: < 72px
+    description: |
+      Hides everything except the leading icon. Applies tight padding. Button collapses to near icon-only appearance.
 content:
   model: inline
-  accepts: [text, span, svg, img, aui-icon]
+  accepts:
+    - text
+    - span
+    - svg
+    - img
+    - aui-icon
   required: false
-  description: >
-    Inline text label or icon content. The preferred API is to use
-    the label attribute (rendered via CSS ::after) and icon-leading /
-    icon-trailing attributes (stamped by JS as <aui-icon> children).
-    Manual slotting of <aui-icon slot="leading/trailing"> is also supported.
-
-# ── Slots ─────────────────────────────────────────────────
-
+  description: |
+    Inline text label or icon content. The preferred API is to use the label attribute (rendered via CSS ::after) and icon-leading / icon-trailing attributes (stamped by JS as <aui-icon> children). Manual slotting of <aui-icon slot="leading/trailing"> is also supported.
 slots:
   default:
-    accepts: [text, inline elements]
+    accepts:
+      - text
+      - inline elements
     required: false
-    description: >
-      Button label text content. Prefer using the label attribute instead,
-      which renders the label via CSS ::after without JS.
-
+    description: |
+      Button label text content. Prefer using the label attribute instead, which renders the label via CSS ::after without JS.
   leading:
-    accepts: [aui-icon, span, svg, img]
+    accepts:
+      - aui-icon
+      - span
+      - svg
+      - img
     required: false
-    description: >
-      Leading icon. Typically stamped by JS from icon-leading attribute
-      as <aui-icon slot="leading">. Manual slotting is also supported.
-
+    description: |
+      Leading icon. Typically stamped by JS from icon-leading attribute as <aui-icon slot="leading">. Manual slotting is also supported.
   trailing:
-    accepts: [aui-icon, span, svg, img]
+    accepts:
+      - aui-icon
+      - span
+      - svg
+      - img
     required: false
-    description: >
-      Trailing icon. Typically stamped by JS from icon-trailing attribute
-      as <aui-icon slot="trailing">. Manual slotting is also supported.
-
+    description: |
+      Trailing icon. Typically stamped by JS from icon-trailing attribute as <aui-icon slot="trailing">. Manual slotting is also supported.
   leading-text:
-    accepts: [span]
+    accepts:
+      - span
     required: false
-    description: >
-      Text adornment before the label. Stamped by JS from text-leading
-      attribute as <span slot="leading-text">.
-
+    description: |
+      Text adornment before the label. Stamped by JS from text-leading attribute as <span slot="leading-text">.
   trailing-text:
-    accepts: [span]
+    accepts:
+      - span
     required: false
-    description: >
-      Text adornment after the label. Stamped by JS from text-trailing
-      attribute as <span slot="trailing-text">.
-
-# ── Composition ───────────────────────────────────────────
-
+    description: |
+      Text adornment after the label. Stamped by JS from text-trailing attribute as <span slot="trailing-text">.
 composition:
-  parents: [aui-stack, aui-grid, aui-header, aui-footer, aui-inset, form, div, section]
+  parents:
+    - aui-stack
+    - aui-grid
+    - aui-header
+    - aui-footer
+    - aui-inset
+    - form
+    - div
+    - section
   children: null
-  context: >
-    Buttons are leaf-level interactive elements. They appear in
-    action bars, forms, headers, toolbars. Use aui-stack direction="row"
-    to group multiple buttons.
-
-# ── Constraints ───────────────────────────────────────────
-
+  context: |
+    Buttons are leaf-level interactive elements. They appear in action bars, forms, headers, toolbars. Use aui-stack direction="row" to group multiple buttons.
 constraints:
   - when: hide-label
     require: label
-    reason: >
-      Screen readers need accessible text when no visible label
-      is present. The label attribute maps to aria-label.
-
+    reason: |
+      Screen readers need accessible text when no visible label is present. The label attribute maps to aria-label.
   - when: href
-    conflicts-with: [type]
-    reason: >
-      Link-mode buttons navigate via href. Form type attributes
-      (submit/reset) are meaningless in link mode.
-
-# ── Deprecated / Removed ─────────────────────────────────
-
+    conflicts-with:
+      - type
+    reason: |
+      Link-mode buttons navigate via href. Form type attributes (submit/reset) are meaningless in link mode.
 deprecated:
   aui-icon-button:
     status: removed
-    replacement: >
+    replacement: |
       Use <aui-button hide-label label="..." icon-leading="..."> instead.
-
   icon-only:
     status: removed
-    replacement: >
+    replacement: |
       Renamed to hide-label attribute on <aui-button>.
-
   name-on-aui-icon:
     status: removed
-    replacement: >
-      The name attribute on <aui-icon> is renamed to registry.
-      Use <aui-icon name="..."> instead of <aui-icon name="...">.
-
-# ── Accessibility ─────────────────────────────────────────
-
+    replacement: |
+      The name attribute on <aui-icon> is renamed to registry. Use <aui-icon name="..."> instead of <aui-icon name="...">.
 a11y:
   role: button
   keyboard:
@@ -335,24 +281,14 @@ a11y:
   focus:
     default: tabindex="0"
     disabled: tabindex="-1"
-
-# ── Form association ──────────────────────────────────────
-
 form:
   associated: true
   submit: Calls form.requestSubmit() when type="submit".
   reset: Calls form.reset() when type="reset".
-
-# ── Events ────────────────────────────────────────────────
-
 events:
   click:
-    description: >
-      Native click event. Blocked when disabled or loading.
-      Fires form submit/reset when type is set. Navigates when href is set.
-
-# ── CSS tokens consumed ──────────────────────────────────
-
+    description: |
+      Native click event. Blocked when disabled or loading. Fires form submit/reset when type is set. Navigates when href is set.
 tokens:
   - name: --aui-button-size
     default: var(--aui-size)
@@ -405,9 +341,6 @@ tokens:
   - name: --aui-button-border-hover
     default: var(--aui-stroke-hover)
     description: Border color on hover.
-
-# ── Use cases ─────────────────────────────────────────────
-
 use-cases:
   - Primary call-to-action in forms and action bars.
   - Ghost/outline secondary actions alongside primary buttons.
@@ -416,54 +349,48 @@ use-cases:
   - Form submit/reset triggers.
   - Buttons with text adornments (e.g. "AI" badge via text-leading).
   - Resize-responsive buttons that collapse adornments as space shrinks.
-
-# ── Examples ──────────────────────────────────────────────
-
 examples:
-  - html: <aui-button label="Default Action"></aui-button>
-    description: Declarative label via attribute (rendered by CSS ::after).
-
-  - html: <aui-button label="Save" icon-leading="check" primary accent></aui-button>
-    description: Leading icon + label, primary accent.
-
-  - html: <aui-button label="Delete" icon-leading="warning" primary danger></aui-button>
-    description: Danger button with leading warning icon.
-
-  - html: <aui-button label="Cancel" outline></aui-button>
-    description: Outlined button.
-
-  - html: <aui-button label="Skip" ghost></aui-button>
-    description: Ghost button with no chrome.
-
-  - html: <aui-button label="Settings" icon-leading="gear" ghost hide-label></aui-button>
-    description: Icon-only ghost button with accessible label via hide-label.
-
-  - html: <aui-button label="Generate" icon-leading="robot" text-leading="AI" primary></aui-button>
-    description: Leading icon + text adornment + label.
-
-  - html: <aui-button label="Suggestions" icon-leading="lightbulb" icon-trailing="caret-right"></aui-button>
-    description: Leading + trailing icons with label.
-
-  - html: <aui-button href="/about" label="Learn More"></aui-button>
-    description: Link-mode button.
-
-  - html: <aui-button type="submit" label="Submit" primary accent></aui-button>
-    description: Form submit button.
-
-  - html: |
+  - description: Text only
+    html: <aui-button>Default</aui-button>
+  - description: Declarative label
+    html: <aui-button label="Default Action"></aui-button>
+  - description: Leading icon + label
+    html: <aui-button label="Create project" icon-leading="plus" primary accent></aui-button>
+  - description: Leading icon + text-leading + label
+    html: <aui-button label="Generate" icon-leading="robot" text-leading="AI" primary></aui-button>
+  - description: Leading + trailing icons + label
+    html: <aui-button label="Suggestions" icon-leading="lightbulb" icon-trailing="caret-right"></aui-button>
+  - description: Icon-only (label hidden, used for aria)
+    html: <aui-button label="Settings" icon-leading="gear" ghost hide-label></aui-button>
+  - description: Primary accent
+    html: <aui-button label="Save" icon-leading="check" primary accent></aui-button>
+  - description: Outline
+    html: <aui-button label="Cancel" outline></aui-button>
+  - description: Ghost
+    html: <aui-button label="Skip" ghost></aui-button>
+  - description: Danger
+    html: <aui-button label="Delete" icon-leading="warning" primary danger></aui-button>
+  - description: Success
+    html: <aui-button label="Approved" icon-leading="check-circle" primary success></aui-button>
+  - description: Progressive collapse — resize the container to see buttons adapt
+    html: |-
+      <div responsive style="resize: horizontal; overflow: hidden; border: 1px dashed var(--aui-border-muted); border-radius: var(--aui-radius); padding: 1rem; width: 24rem; min-width: 3rem; display: flex; gap: 0.5rem; flex-wrap: nowrap;">
+        <aui-button label="Toggle scheme" icon-leading="sun" icon-trailing="caret-right" outline></aui-button>
+        <aui-button label="Search" icon-leading="magnifying-glass" outline></aui-button>
+        <aui-button label="More" icon-trailing="dots-three" ghost></aui-button>
+      </div>
+  - description: Disabled
+    html: <aui-button label="Disabled" icon-leading="x" primary accent disabled></aui-button>
+  - description: Loading
+    html: <aui-button label="Saving…" primary accent loading></aui-button>
+  - description: Compact density
+    html: <aui-button label="Add" icon-leading="plus" primary accent density="compact"></aui-button>
+  - description: Round pill
+    html: <aui-button label="Favorite" icon-leading="star" outline round></aui-button>
+  - description: Manual slots — inline SVG + text children
+    html: |-
       <aui-button outline>
         <aui-icon name="robot" slot="leading"></aui-icon>
         Ask AI
         <aui-icon name="sparkle" slot="trailing"></aui-icon>
       </aui-button>
-    description: Manual slot pattern with inline text and aui-icon children.
-
-  - html: |
-      <div responsive style="resize: horizontal; overflow: hidden; width: 24rem; min-width: 3rem; display: flex; gap: 0.5rem;">
-        <aui-button label="Toggle scheme" icon-leading="sun" icon-trailing="caret-right" outline></aui-button>
-        <aui-button label="Search" icon-leading="magnifying-glass" outline></aui-button>
-      </div>
-    description: >
-      Resize-responsive collapse demo. Drag to shrink — buttons progressively
-      hide leading icons/text (< 128px), trailing icons/text (< 96px),
-      then collapse to icon-only with tight padding (< 72px).