@agent-ui-kit/web-components 0.0.2 → 0.0.4

package/dist/docs/components/select.yaml

@@ -0,0 +1,241 @@
+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.
+
+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.
+
+  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…"
+    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).
+
+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.
+  data-priority:
+    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).
+
+  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:
+    ArrowDown: Navigate options or open dropdown.
+    ArrowUp: Navigate options or open dropdown.
+    ArrowRight: Next item (bar mode).
+    ArrowLeft: Previous item (bar mode).
+    Enter: Select option or activate action.
+    Space: Select option or activate action.
+    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.
+  overflow:
+    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)]
+
+examples:
+  - 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: |
+      <aui-select placeholder="Category">
+        <aui-optgroup label="Fruits">
+          <aui-option value="apple">Apple</aui-option>
+          <aui-option value="banana">Banana</aui-option>
+        </aui-optgroup>
+        <aui-optgroup label="Vegetables" divider>
+          <aui-option value="carrot">Carrot</aui-option>
+          <aui-option value="spinach">Spinach</aui-option>
+        </aui-optgroup>
+      </aui-select>
+    description: Grouped options with a divider between sections.
+
+  - 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: |
+      <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: |
+      <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: |
+      <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>
+          <aui-option>Copy</aui-option>
+          <aui-option>Paste</aui-option>
+          <hr>
+          <aui-option>Undo</aui-option>
+          <aui-option>Redo</aui-option>
+          <hr>
+          <aui-option>Bold</aui-option>
+          <aui-option>Italic</aui-option>
+          <aui-option>Underline</aui-option>
+        </aui-select>
+      </div>
+    description: Bar mode (toolbar) — drag to resize, items overflow into a ··· menu.
+
+  - html: |
+      <aui-select mode="bar" width="full">
+        <aui-option overflow-pin>Home</aui-option>
+        <aui-option>Projects</aui-option>
+        <aui-option>Tasks</aui-option>
+        <aui-option>Analytics</aui-option>
+        <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.

package/dist/docs/components/sidebar-content.yaml

@@ -0,0 +1,32 @@
+name: aui-sidebar-content
+tag: aui-sidebar-content
+type: component
+summary: Scrollable content area within a sidebar.
+description: >
+  Sits between the header and footer overlays inside aui-sidebar.
+  Positioned absolutely to fill the sidebar, with vertical scroll
+  and edge-fade mask-image for smooth content clipping.
+
+base: AgentElement
+
+a11y:
+  role: none
+
+composition:
+  parents: [aui-sidebar]
+  children:
+    typical: [aui-nav-item, aui-sidebar-label]
+    pattern: >
+      Contains the primary navigation items and section labels.
+      Scrolls independently with hidden scrollbar and gradient
+      mask at top and bottom edges.
+
+examples:
+  - html: |
+      <aui-sidebar-content>
+        <aui-sidebar-label>Navigation</aui-sidebar-label>
+        <aui-nav-item label="Dashboard" icon="home"></aui-nav-item>
+        <aui-nav-item label="Projects" icon="folder"></aui-nav-item>
+        <aui-nav-item label="Settings" icon="settings"></aui-nav-item>
+      </aui-sidebar-content>
+    description: Scrollable nav content with a section label.

package/dist/docs/components/sidebar-footer.yaml

@@ -0,0 +1,28 @@
+name: aui-sidebar-footer
+tag: aui-sidebar-footer
+type: component
+summary: Sticky bottom overlay within a sidebar.
+description: >
+  Pinned below the scrollable content area of aui-sidebar.
+  Positioned absolutely at the bottom of the sidebar, overlaying
+  the content with a z-index above the scroll area.
+
+base: AgentElement
+
+a11y:
+  role: none
+
+composition:
+  parents: [aui-sidebar]
+  children:
+    typical: [aui-nav-item]
+    pattern: >
+      Typically contains user account or settings nav-items.
+      Items use select-trigger styling with hover background.
+
+examples:
+  - html: |
+      <aui-sidebar-footer>
+        <aui-nav-item label="Account" icon="user"></aui-nav-item>
+      </aui-sidebar-footer>
+    description: Sidebar footer with a user account item.

package/dist/docs/components/sidebar-header.yaml

@@ -0,0 +1,28 @@
+name: aui-sidebar-header
+tag: aui-sidebar-header
+type: component
+summary: Sticky top overlay within a sidebar.
+description: >
+  Pinned above the scrollable content area of aui-sidebar.
+  Positioned absolutely at the top of the sidebar, overlaying
+  the content with a z-index above the scroll area.
+
+base: AgentElement
+
+a11y:
+  role: none
+
+composition:
+  parents: [aui-sidebar]
+  children:
+    typical: [aui-nav-item]
+    pattern: >
+      Typically contains a workspace switcher or branding nav-item.
+      Items use select-trigger styling with hover background.
+
+examples:
+  - html: |
+      <aui-sidebar-header>
+        <aui-nav-item label="My Workspace" icon="grid"></aui-nav-item>
+      </aui-sidebar-header>
+    description: Sidebar header with a workspace switcher item.

package/dist/docs/components/sidebar.yaml

@@ -0,0 +1,133 @@
+name: aui-sidebar
+tag: aui-sidebar
+type: component
+summary: Resizable, collapsible sidebar navigation shell.
+description: >
+  Layout shell for sidebar navigation. Flex column, sticky, resizable via
+  drag handle, collapsible to icon-rail via container queries. Supports
+  left or right placement and emits resize/collapse events.
+
+base: AgentElement
+
+attributes:
+  width:
+    syntax: key-value
+    type: string
+    default: "240"
+    description: Initial sidebar width in pixels.
+
+  min-width:
+    syntax: key-value
+    type: string
+    default: "56"
+    description: Minimum width during resize in pixels.
+
+  max-width:
+    syntax: key-value
+    type: string
+    default: "480"
+    description: Maximum width during resize in pixels.
+
+  collapsed:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the sidebar is collapsed to its minimum width.
+
+  collapsible:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the sidebar supports collapsing.
+
+  side:
+    syntax: key-value
+    type: enum
+    values: [left, right]
+    default: left
+    description: Which side of the app shell the sidebar anchors to.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Disables resize interaction and dims the sidebar.
+
+methods:
+  collapse:
+    description: Collapses the sidebar and fires aui:sidebar-collapse.
+  expand:
+    description: Expands the sidebar and fires aui:sidebar-collapse.
+  toggle:
+    description: Toggles between collapsed and expanded states.
+
+events:
+  aui:sidebar-resize:
+    description: Fires when a drag-resize ends. Detail contains { width }.
+    bubbles: true
+  aui:sidebar-collapse:
+    description: Fires when collapsed state changes. Detail contains { collapsed }.
+    bubbles: true
+
+composition:
+  parents: [aui-app-shell]
+  children:
+    typical: [aui-sidebar-header, aui-sidebar-content, aui-sidebar-footer]
+    pattern: >
+      Header for branding/workspace switcher, content for scrollable
+      navigation items, footer for user/settings. Resize handle is
+      auto-stamped.
+  context: >
+    Used as the primary navigation column inside aui-app-shell.
+    Progressively collapses labels, groups, and icons via container
+    queries at 200px, 140px, and 80px breakpoints.
+
+a11y:
+  role: complementary
+  keyboard:
+    Drag: Resize handle supports pointer drag to resize width.
+
+tokens:
+  sizing:
+    - --aui-sidebar-width
+    - --aui-sidebar-width-min
+    - --aui-sidebar-width-max
+    - --aui-sidebar-width-collapsed
+    - --aui-sidebar-header-height
+  color:
+    - --aui-doc
+    - --aui-border
+    - --aui-action-active
+    - --aui-ink
+    - --aui-ink-muted
+    - --aui-ink-strong
+    - --aui-focus
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+examples:
+  - html: |
+      <aui-sidebar width="260" collapsible>
+        <aui-sidebar-header>
+          <aui-nav-item label="Workspace" icon="grid"></aui-nav-item>
+        </aui-sidebar-header>
+        <aui-sidebar-content>
+          <aui-nav-item label="Dashboard" icon="home"></aui-nav-item>
+          <aui-nav-item label="Settings" icon="settings"></aui-nav-item>
+        </aui-sidebar-content>
+        <aui-sidebar-footer>
+          <aui-nav-item label="Account" icon="user"></aui-nav-item>
+        </aui-sidebar-footer>
+      </aui-sidebar>
+    description: >
+      Collapsible sidebar with header, scrollable content, and footer.
+
+  - html: |
+      <aui-sidebar side="right" width="300">
+        <aui-sidebar-content>
+          <aui-nav-item label="Inspector" icon="sliders"></aui-nav-item>
+          <aui-nav-item label="Properties" icon="list"></aui-nav-item>
+        </aui-sidebar-content>
+      </aui-sidebar>
+    description: Right-side sidebar for detail panels or inspectors.

package/dist/docs/components/switch.yaml

@@ -0,0 +1,131 @@
+name: aui-switch
+tag: aui-switch
+type: component
+summary: Toggle switch with track and sliding thumb.
+description: >
+  Binary toggle rendered as an iOS-style wide track with a pill-shaped
+  sliding thumb. Hidden native checkbox for form participation. Label
+  rendered via CSS ::after { content: attr(label) } — JS only sets
+  aria-label for accessibility, no DOM stamping for the visible label.
+  Animated transitions use offset timing (thumb moves before track
+  fill). Press animation stretches the thumb wider on :active.
+
+base: AgentElement
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: Controls track and thumb dimensions.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values: [accent, info, success, warning, danger]
+    description: Color family for the checked track fill.
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction.
+
+  checked:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the switch is on.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Label text displayed next to the switch.
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form submission name.
+
+  value:
+    syntax: key-value
+    type: string
+    default: "on"
+    description: Form submission value when checked.
+
+content:
+  model: inline
+  accepts: [input]
+  required: false
+  description: >
+    Auto-stamps hidden input for form participation. Label is
+    rendered purely via CSS ::after on :scope — no stamped span.
+
+composition:
+  parents: [aui-field, aui-stack, form, div]
+  children: null
+  context: >
+    Use for on/off toggles in settings panels. Place inside
+    aui-field for labeled form switches, or standalone with
+    the label attribute.
+
+a11y:
+  role: switch
+  keyboard:
+    Space: Toggles checked state.
+    Enter: Toggles checked state.
+  aria:
+    aria-checked: Mirrors checked attribute.
+    aria-disabled: Mirrors disabled attribute.
+
+events:
+  change:
+    description: Fires when checked state changes.
+
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-widget-size
+    - --aui-font-size
+  color:
+    - --aui-ink
+    - --aui-ink-muted
+    - --aui-control
+    - --aui-fill
+    - --aui-stroke
+    - --aui-solid
+    - --aui-on-solid
+    - --aui-focus
+  shape:
+    - --aui-radius-round
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+css-notes:
+  attr-audit:
+    - "AB1: [checked], [disabled] — visual state via attributes"
+    - "::before on [data-track] for thumb — pure CSS sliding"
+    - "CG3: ::after { content: attr(label) } — label rendered in CSS, no JS-stamped [data-label]"
+    - ":active thumb stretches wider (press animation)"
+    - "Offset timing: thumb translate transitions before track fill color"
+
+examples:
+  - html: <aui-switch label="Notifications"></aui-switch>
+    description: Default off switch.
+
+  - html: <aui-switch label="Dark mode" checked></aui-switch>
+    description: Pre-enabled switch.
+
+  - html: <aui-switch label="Locked" disabled></aui-switch>
+    description: Disabled switch.
+
+  - html: <aui-switch label="Active" checked accent></aui-switch>
+    description: Accent-colored enabled switch.

package/dist/docs/components/tab-panel.yaml

@@ -0,0 +1,41 @@
+name: aui-tab-panel
+tag: aui-tab-panel
+type: component
+summary: Content panel associated with a tab.
+description: >
+  Shown when the matching tab is selected, hidden otherwise.
+  The parent aui-tabs coordinates visibility.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Panel identifier, matched against aui-tab value.
+
+  active:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether this panel is currently visible.
+
+a11y:
+  role: tabpanel
+  aria:
+    aria-hidden: true when not active.
+
+composition:
+  parents: [aui-tabs]
+  children: [any]
+
+examples:
+  - html: |
+      <aui-tabs value="overview">
+        <aui-tab value="overview">Overview</aui-tab>
+        <aui-tab value="details">Details</aui-tab>
+        <aui-tab-panel value="overview">Overview panel with content.</aui-tab-panel>
+        <aui-tab-panel value="details">Details panel with more content.</aui-tab-panel>
+      </aui-tabs>
+    description: Tab panels shown within a full tabs context.

package/dist/docs/components/tab.yaml

@@ -0,0 +1,51 @@
+name: aui-tab
+tag: aui-tab
+type: component
+summary: Individual tab trigger within a tabbed interface.
+description: >
+  A single tab button within aui-tabs. Visual states driven by
+  selected and disabled attributes. Parent aui-tabs coordinates
+  selection and keyboard navigation.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Tab identifier, matched against aui-tab-panel value.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents selection.
+
+  selected:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether this tab is currently active.
+
+a11y:
+  role: tab
+  aria:
+    aria-selected: Reflects selected attribute.
+    aria-disabled: Reflects disabled attribute.
+
+composition:
+  parents: [aui-tabs]
+  children: null
+
+examples:
+  - html: |
+      <aui-tabs value="general">
+        <aui-tab value="general">General</aui-tab>
+        <aui-tab value="advanced">Advanced</aui-tab>
+        <aui-tab value="security">Security</aui-tab>
+        <aui-tab-panel value="general">General settings content.</aui-tab-panel>
+        <aui-tab-panel value="advanced">Advanced settings content.</aui-tab-panel>
+        <aui-tab-panel value="security">Security settings content.</aui-tab-panel>
+      </aui-tabs>
+    description: Tab triggers shown within a full tabs context.

package/dist/docs/components/table-body.yaml

@@ -0,0 +1,11 @@
+name: aui-table-body
+tag: aui-table-body
+type: component
+summary: Table body section using display contents
+base: AgentElement
+composition:
+  parents: [aui-table]
+  children: [aui-table-row]
+examples:
+  - html: See aui-table for full usage.
+    description: Used within aui-table structure.