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

package/dist/docs/components/range.yaml

@@ -2,59 +2,45 @@ name: aui-range
 tag: aui-range
 type: component
 summary: Slider control with custom track and thumb.
-description: >
-  A range slider that wraps a native input[type="range"] for form
-  participation and full keyboard/ARIA support. The wrapper renders
-  a custom track, fill, and wide iOS-style thumb contained within the
-  track — the native input is visually hidden. The thumb uses a scaleX
-  animation on press (:active) with transform-origin: center for
-  centered scaling.
-
+description: |
+  A range slider that wraps a native input[type="range"] for form participation and full keyboard/ARIA support. The wrapper renders a custom track, fill, and wide iOS-style thumb contained within the track — the native input is visually hidden. The thumb uses a scaleX animation on press (:active) with transform-origin: center for centered scaling.
 base: AgentElement
-
 attributes:
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Prevents interaction. Dims visually.
-
   min:
     syntax: key-value
     type: string
     default: "0"
     description: Minimum value.
-
   max:
     syntax: key-value
     type: string
     default: "100"
     description: Maximum value.
-
   step:
     syntax: key-value
     type: string
     default: "1"
     description: Step increment.
-
   value:
     syntax: key-value
     type: string
     default: "50"
     description: Current value.
-
   label:
     syntax: key-value
     type: string
     default: ""
     description: Accessible label (maps to aria-label on the native input).
-
   name:
     syntax: key-value
     type: string
     default: ""
     description: Form field name.
-
 a11y:
   role: slider (via native input)
   keyboard:
@@ -64,11 +50,9 @@ a11y:
     End: Set to max.
   aria:
     aria-label: Set from label attribute.
-
 form:
   associated: true
   value: Current slider value.
-
 tokens:
   - name: --aui-range-track-background
     default: var(--aui-control)
@@ -94,13 +78,26 @@ tokens:
   - name: --aui-range-thumb-shadow
     default: var(--aui-shadow-sm, 0 1px 4px oklch(0% 0 0 / 0.15))
     description: Thumb drop shadow.
-
 examples:
-  - html: <aui-range></aui-range>
-    description: Default slider (0–100, value 50).
-
-  - html: <aui-range min="0" max="10" step="1" value="3" label="Volume"></aui-range>
-    description: Slider with custom range and label.
-
-  - html: <aui-range disabled value="75"></aui-range>
-    description: Disabled slider.
+  - description: Default slider (0–100, value 50)
+    html: <aui-range></aui-range>
+  - description: Slider with custom range and label
+    html: <aui-range min="0" max="10" step="1" value="3" label="Volume"></aui-range>
+  - description: Disabled slider
+    html: <aui-range disabled value="75"></aui-range>
+  - description: Range with visible value label (0–100, step 10)
+    html: <aui-range min="0" max="100" step="10" value="40" label="Brightness"></aui-range>
+  - description: Fine-grained range (0–1, step 0.01)
+    html: <aui-range min="0" max="1" step="0.01" value="0.65" label="Opacity"></aui-range>
+  - description: Negative to positive range
+    html: <aui-range min="-50" max="50" step="5" value="0" label="Balance"></aui-range>
+  - description: Range inside aui-field with label
+    html: |-
+      <aui-field label="Volume">
+        <aui-range min="0" max="100" step="1" value="70" name="volume"></aui-range>
+      </aui-field>
+  - description: Range inside aui-field, disabled
+    html: |-
+      <aui-field label="Locked setting">
+        <aui-range disabled min="0" max="10" step="1" value="5" name="locked"></aui-range>
+      </aui-field>

package/dist/docs/components/segmented-control.yaml

@@ -2,26 +2,20 @@ name: aui-segmented-control
 tag: aui-segmented-control
 type: component
 summary: Toggle between mutually exclusive options.
-description: >
-  A radiogroup-style control for switching between views or values.
-  Contains aui-segment children. Selected segment gets a raised
-  pill appearance.
-
+description: |
+  A radiogroup-style control for switching between views or values. Contains aui-segment children. Selected segment gets a raised pill appearance.
 base: AgentElement
-
 attributes:
   value:
     syntax: key-value
     type: string
     default: ""
     description: Currently selected segment value.
-
   name:
     syntax: key-value
     type: string
     default: ""
     description: Form field name.
-
 a11y:
   role: radiogroup
   keyboard:
@@ -29,19 +23,17 @@ a11y:
     ArrowLeft: Select previous segment.
     Home: Select first segment.
     End: Select last segment.
-
 events:
   change:
     description: Fired when selection changes. detail.value is the new value.
-
 form:
   associated: true
   value: Selected segment value.
-
 composition:
-  parents: [any]
-  children: [aui-segment]
-
+  parents:
+    - any
+  children:
+    - aui-segment
 tokens:
   - name: --aui-segmented-control-background
     default: var(--aui-control, var(--aui-fill))
@@ -64,12 +56,61 @@ tokens:
   - name: --aui-segmented-control-indicator-shadow
     default: var(--aui-shadow-sm)
     description: Box shadow of the floating selection indicator.
-
 examples:
-  - html: |
+  - description: 3-segment view mode toggle
+    html: |-
       <aui-segmented-control value="list">
         <aui-segment value="list" selected>List</aui-segment>
         <aui-segment value="grid">Grid</aui-segment>
         <aui-segment value="board">Board</aui-segment>
       </aui-segmented-control>
-    description: View mode toggle.
+  - description: 2-segment binary toggle (Light / Dark)
+    html: |-
+      <aui-segmented-control value="light">
+        <aui-segment value="light" selected>Light</aui-segment>
+        <aui-segment value="dark">Dark</aui-segment>
+      </aui-segmented-control>
+  - description: 2-segment on/off toggle
+    html: |-
+      <aui-segmented-control value="on">
+        <aui-segment value="on" selected>On</aui-segment>
+        <aui-segment value="off">Off</aui-segment>
+      </aui-segmented-control>
+  - description: 4 segments — time period selector
+    html: |-
+      <aui-segmented-control value="monthly">
+        <aui-segment value="daily">Daily</aui-segment>
+        <aui-segment value="weekly">Weekly</aui-segment>
+        <aui-segment value="monthly" selected>Monthly</aui-segment>
+        <aui-segment value="yearly">Yearly</aui-segment>
+      </aui-segmented-control>
+  - description: 5 segments — rating scale
+    html: |-
+      <aui-segmented-control value="3">
+        <aui-segment value="1">1</aui-segment>
+        <aui-segment value="2">2</aui-segment>
+        <aui-segment value="3" selected>3</aui-segment>
+        <aui-segment value="4">4</aui-segment>
+        <aui-segment value="5">5</aui-segment>
+      </aui-segmented-control>
+  - description: Disabled individual segment
+    html: |-
+      <aui-segmented-control value="active">
+        <aui-segment value="active" selected>Active</aui-segment>
+        <aui-segment value="pending">Pending</aui-segment>
+        <aui-segment value="archived" disabled>Archived</aui-segment>
+      </aui-segmented-control>
+  - description: Segments with icons
+    html: |-
+      <aui-segmented-control value="list">
+        <aui-segment value="list" selected><aui-icon name="list"></aui-icon> List</aui-segment>
+        <aui-segment value="grid"><aui-icon name="grid"></aui-icon> Grid</aui-segment>
+        <aui-segment value="board"><aui-icon name="kanban"></aui-icon> Board</aui-segment>
+      </aui-segmented-control>
+  - description: Icon-only segments
+    html: |-
+      <aui-segmented-control value="left">
+        <aui-segment value="left" selected><aui-icon name="align-left"></aui-icon></aui-segment>
+        <aui-segment value="center"><aui-icon name="align-center"></aui-icon></aui-segment>
+        <aui-segment value="right"><aui-icon name="align-right"></aui-icon></aui-segment>
+      </aui-segmented-control>

package/dist/docs/components/select.yaml

@@ -2,90 +2,66 @@ name: aui-select
 tag: aui-select
 type: component
 summary: Universal collection surface — dropdown, toolbar, listbox, and combobox in one element.
-description: >
-  A single component with four presentation modes controlled by the mode
-  attribute. Default is a dropdown select. mode="bar" renders as a toolbar
-  with overflow management. mode="list" is a standalone scrollable listbox.
-  mode="combobox" adds a searchable input. Supports nested aui-select for
-  submenus, aui-optgroup for labeled sections, and aui-option as leaf items.
-  In dropdown mode, the trigger sizes to the widest option content,
-  matching the native <select> intrinsic sizing behavior. Automatically
-  stretches to full width when placed inside aui-field. Use width="full"
-  to override the default width in other contexts.
-
+description: |
+  A single component with four presentation modes controlled by the mode attribute. Default is a dropdown select. mode="bar" renders as a toolbar with overflow management. mode="list" is a standalone scrollable listbox. mode="combobox" adds a searchable input. Supports nested aui-select for submenus, aui-optgroup for labeled sections, and aui-option as leaf items. In dropdown mode, the trigger sizes to the widest option content, matching the native <select> intrinsic sizing behavior. Automatically stretches to full width when placed inside aui-field. Use width="full" to override the default width in other contexts.
 base: AgentElement
-
 attributes:
   mode:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Presentation mode. Empty (default) = dropdown select.
-      "bar" = inline toolbar with overflow.
-      "list" = standalone scrollable listbox.
-      "combobox" = searchable dropdown with type-ahead filtering.
-
+    description: |
+      Presentation mode. Empty (default) = dropdown select. "bar" = inline toolbar with overflow. "list" = standalone scrollable listbox. "combobox" = searchable dropdown with type-ahead filtering.
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Prevents interaction.
-
   required:
     syntax: boolean
     type: boolean
     default: false
     description: Marks the field as required (dropdown/combobox modes).
-
   placeholder:
     syntax: key-value
     type: string
-    default: "Select…"
+    default: Select…
     description: Placeholder text (dropdown/combobox trigger).
-
   value:
     syntax: key-value
     type: string
     default: ""
     description: Currently selected value(s). Comma-separated for multiple.
-
   name:
     syntax: key-value
     type: string
     default: ""
     description: Form field name.
-
   open:
     syntax: boolean
     type: boolean
     default: false
     description: Whether the dropdown/combobox popover is open.
-
   multiple:
     syntax: boolean
     type: boolean
     default: false
     description: Allow multiple selection (list mode).
-
   orientation:
     syntax: key-value
     type: string
     default: ""
     description: Set to "vertical" for vertical bar/list layout.
-
   transparent:
     syntax: boolean
     type: boolean
     default: false
     description: Remove background and border (bar mode).
-
   fill:
     syntax: boolean
     type: boolean
     default: false
     description: Children fill available space equally (bar mode).
-
 tokens:
   - name: --aui-select-font-family
     default: var(--aui-font-family)
@@ -141,34 +117,27 @@ tokens:
   - name: --aui-select-dropdown-shadow
     default: var(--aui-shadow-lg, 0 4px 16px oklch(0% 0 0 / 0.12))
     description: Box shadow for the dropdown popover.
-
 bar-overflow:
-  description: >
-    In bar mode, items overflow into a "..." popover menu when the container
-    is too narrow. Control which items overflow first using data-priority
-    on children. Groups (aui-optgroup) overflow as a unit — all items in a
-    group move to the overflow menu together. In the bar, group labels are
-    hidden and auto-stamped dividers separate adjacent groups. In the
-    overflow menu, groups render with a horizontal divider + uppercase
-    group header label above their items.
+  description: |
+    In bar mode, items overflow into a "..." popover menu when the container is too narrow. Control which items overflow first using data-priority on children. Groups (aui-optgroup) overflow as a unit — all items in a group move to the overflow menu together. In the bar, group labels are hidden and auto-stamped dividers separate adjacent groups. In the overflow menu, groups render with a horizontal divider + uppercase group header label above their items.
   data-priority:
-    values: ["0", "1", "2", "pin"]
-    aliases: { low: "0", normal: "1", high: "2" }
+    values:
+      - "0"
+      - "1"
+      - "2"
+      - pin
+    aliases:
+      low: "0"
+      normal: "1"
+      high: "2"
     default: "1"
-    description: >
-      Overflow priority for bar mode children.
-      0 (low)    — collapses first.
-      1 (normal) — default, collapses at standard threshold.
-      2 (high)   — collapses last.
-      pin        — never collapses (always visible).
-      Items at the same priority collapse in reverse DOM order (end first).
-
+    description: |
+      Overflow priority for bar mode children. 0 (low)    — collapses first. 1 (normal) — default, collapses at standard threshold. 2 (high)   — collapses last. pin        — never collapses (always visible). Items at the same priority collapse in reverse DOM order (end first).
   padding:
     syntax: key-value
     type: string
     default: ""
     description: Padding variant — none, tight, regular, relaxed (bar mode).
-
 a11y:
   role: Depends on mode — combobox (dropdown), toolbar (bar), listbox (list).
   keyboard:
@@ -181,35 +150,37 @@ a11y:
     Escape: Close dropdown or cancel.
     Home: First item.
     End: Last item.
-
 events:
   change:
-    description: >
-      Fired when selection changes (dropdown/list/combobox modes).
-      detail contains value, option, and label.
+    description: |
+      Fired when selection changes (dropdown/list/combobox modes). detail contains value, option, and label.
   overflow:
-    description: >
-      Fired when overflow state changes (bar mode).
-      detail contains visibleCount and overflowedCount.
-
+    description: |
+      Fired when overflow state changes (bar mode). detail contains visibleCount and overflowedCount.
 form:
   associated: true
   value: Selected option value(s).
-
 composition:
-  parents: [aui-field, form, aui-stack, any]
-  children: [aui-option, aui-optgroup, aui-select (submenu), aui-button (bar mode)]
-
+  parents:
+    - aui-field
+    - form
+    - aui-stack
+    - any
+  children:
+    - aui-option
+    - aui-optgroup
+    - aui-select (submenu)
+    - aui-button (bar mode)
 examples:
-  - html: |
+  - description: Dropdown select — click to open, arrow keys to navigate, Enter to select
+    html: |-
       <aui-select placeholder="Choose a fruit">
         <aui-option value="apple">Apple</aui-option>
         <aui-option value="banana">Banana</aui-option>
         <aui-option value="cherry">Cherry</aui-option>
       </aui-select>
-    description: Dropdown select — click to open, arrow keys to navigate, Enter to select.
-
-  - html: |
+  - description: Grouped options with a divider between sections
+    html: |-
       <aui-select placeholder="Category">
         <aui-optgroup label="Fruits">
           <aui-option value="apple">Apple</aui-option>
@@ -220,36 +191,32 @@ examples:
           <aui-option value="spinach">Spinach</aui-option>
         </aui-optgroup>
       </aui-select>
-    description: Grouped options with a divider between sections.
-
-  - html: |
+  - description: Combobox — type to filter options
+    html: |-
       <aui-select mode="combobox" placeholder="Search colors...">
         <aui-option value="red">Red</aui-option>
         <aui-option value="green">Green</aui-option>
         <aui-option value="blue">Blue</aui-option>
         <aui-option value="yellow">Yellow</aui-option>
       </aui-select>
-    description: Combobox — type to filter options.
-
-  - html: |
+  - description: Standalone listbox — all options visible, scrollable
+    html: |-
       <aui-select mode="list" max-width="xs">
         <aui-option value="alpha">Alpha</aui-option>
         <aui-option value="beta" selected>Beta</aui-option>
         <aui-option value="gamma">Gamma</aui-option>
         <aui-option value="delta">Delta</aui-option>
       </aui-select>
-    description: Standalone listbox — all options visible, scrollable.
-
-  - html: |
+  - description: Multi-select listbox — click to toggle, multiple selections allowed
+    html: |-
       <aui-select mode="list" multiple max-width="xs">
         <aui-option value="a" selected>Engineering</aui-option>
         <aui-option value="b">Design</aui-option>
         <aui-option value="c" selected>Product</aui-option>
         <aui-option value="d">Marketing</aui-option>
       </aui-select>
-    description: Multi-select listbox — click to toggle, multiple selections allowed.
-
-  - html: |
+  - description: Bar mode (toolbar) — drag to resize, items overflow into a ··· menu
+    html: |-
       <div style="resize: horizontal; overflow: hidden; border: 1px dashed var(--aui-border-muted); border-radius: var(--aui-radius); padding: 0.5rem; min-width: 10rem; max-width: 100%; width: 100%;">
         <aui-select mode="bar" transparent width="full">
           <aui-option>Cut</aui-option>
@@ -264,9 +231,8 @@ examples:
           <aui-option>Underline</aui-option>
         </aui-select>
       </div>
-    description: Bar mode (toolbar) — drag to resize, items overflow into a ··· menu.
-
-  - html: |
+  - description: Bar mode with pinned item — Home never overflows
+    html: |-
       <aui-select mode="bar" width="full">
         <aui-option overflow-pin>Home</aui-option>
         <aui-option>Projects</aui-option>
@@ -275,23 +241,37 @@ examples:
         <aui-option>Reports</aui-option>
         <aui-option>Settings</aui-option>
       </aui-select>
-    description: Bar mode with pinned item — Home never overflows.
-
-  - html: |
-      <aui-select mode="bar" transparent width="full">
-        <aui-option overflow-pin>Home</aui-option>
-        <aui-optgroup label="Content">
-          <aui-option>Pages</aui-option>
-          <aui-option>Posts</aui-option>
-          <aui-option>Media</aui-option>
-        </aui-optgroup>
-        <aui-optgroup label="Settings">
-          <aui-option>General</aui-option>
-          <aui-option>Users</aui-option>
-          <aui-option>Billing</aui-option>
-        </aui-optgroup>
-      </aui-select>
-    description: >
-      Bar mode with grouped overflow — groups separated by auto-stamped
-      dividers inline. When overflowed, groups render in the menu with
-      divider + uppercase header + items. Group labels hidden in bar.
+  - description: Bar mode with grouped overflow — groups spill as a unit with divider + header in the overflow menu. Resize to see
+    html: |-
+      <div style="resize: horizontal; overflow: hidden; border: 1px dashed var(--aui-border-muted); border-radius: var(--aui-radius); padding: 0.5rem; min-width: 10rem; max-width: 100%; width: 100%;">
+        <aui-select mode="bar" transparent width="full">
+          <aui-option overflow-pin>Home</aui-option>
+          <aui-optgroup label="Content">
+            <aui-option>Pages</aui-option>
+            <aui-option>Posts</aui-option>
+            <aui-option>Media</aui-option>
+          </aui-optgroup>
+          <aui-optgroup label="Settings">
+            <aui-option>General</aui-option>
+            <aui-option>Users</aui-option>
+            <aui-option>Billing</aui-option>
+          </aui-optgroup>
+        </aui-select>
+      </div>
+  - description: Bar mode with mixed pinned items and groups — pinned items stay, groups overflow together
+    html: |-
+      <div style="resize: horizontal; overflow: hidden; border: 1px dashed var(--aui-border-muted); border-radius: var(--aui-radius); padding: 0.5rem; min-width: 10rem; max-width: 100%; width: 100%;">
+        <aui-select mode="bar" width="full">
+          <aui-option overflow-pin>Dashboard</aui-option>
+          <aui-optgroup label="Data">
+            <aui-option>Tables</aui-option>
+            <aui-option>Queries</aui-option>
+            <aui-option>Schemas</aui-option>
+          </aui-optgroup>
+          <aui-optgroup label="Tools">
+            <aui-option>Import</aui-option>
+            <aui-option>Export</aui-option>
+          </aui-optgroup>
+          <aui-option overflow-pin>Help</aui-option>
+        </aui-select>
+      </div>

package/dist/docs/components/skeleton.yaml

@@ -0,0 +1,81 @@
+name: aui-skeleton
+tag: aui-skeleton
+type: component
+summary: Loading placeholder with shimmer animation.
+description: |
+  Animated placeholder element for content that has not yet loaded. Uses a gradient shimmer animation. Shape variants for text lines, circles, and rectangles. Width and height set via inline style bridging to CSS custom properties.
+base: AgentElement
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: md
+    values:
+      - xs
+      - sm
+      - md
+      - lg
+    description: Controls placeholder height. xs=0.5rem, sm=0.75rem, md=1rem, lg=1.5rem.
+  type:
+    syntax: key-value
+    attribute: type
+    cascades: false
+    default: text
+    values:
+      - text
+      - circle
+      - rect
+    description: Shape variant — text line, avatar circle, or image rectangle.
+modifiers:
+  round:
+    syntax: boolean
+    description: |
+      Fully rounded corners (pill shape). Applies radius-full regardless of type.
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: |
+    No content — skeleton is a visual placeholder only.
+slots: {}
+tokens:
+  sizing:
+    - --aui-skeleton-width
+    - --aui-skeleton-height
+  color:
+    - --aui-skeleton-base
+    - --aui-skeleton-highlight
+  shape:
+    - --aui-skeleton-radius
+examples:
+  - description: Default text line placeholder
+    html: <aui-skeleton></aui-skeleton>
+  - description: Circle placeholder for avatars
+    html: <aui-skeleton type="circle"></aui-skeleton>
+  - description: Rectangle placeholder for images or cards
+    html: <aui-skeleton type="rect"></aui-skeleton>
+  - description: Size variants
+    html: |-
+      <aui-stack gap="2">
+        <aui-skeleton size="xs"></aui-skeleton>
+        <aui-skeleton size="sm"></aui-skeleton>
+        <aui-skeleton></aui-skeleton>
+        <aui-skeleton size="lg"></aui-skeleton>
+      </aui-stack>
+  - description: Multiple text lines with decreasing widths
+    html: |-
+      <aui-stack gap="2">
+        <aui-skeleton></aui-skeleton>
+        <aui-skeleton style="--aui-skeleton-width: 80%"></aui-skeleton>
+        <aui-skeleton style="--aui-skeleton-width: 60%"></aui-skeleton>
+      </aui-stack>
+  - description: Avatar with text lines loading state
+    html: |-
+      <aui-stack direction="row" gap="3" align-items="center">
+        <aui-skeleton type="circle"></aui-skeleton>
+        <aui-stack gap="2" style="flex: 1">
+          <aui-skeleton></aui-skeleton>
+          <aui-skeleton style="--aui-skeleton-width: 60%"></aui-skeleton>
+        </aui-stack>
+      </aui-stack>