@agent-ui-kit/web-components 0.0.3 → 0.0.5

package/dist/docs/traits/resize.yaml

@@ -0,0 +1,39 @@
+name: resize
+type: trait
+category: gesture
+summary: Handle-based resize of the host element at configured edges and corners.
+description: >
+  Creates transparent draggable handles at the specified edges and corners
+  of the host element. Pointer drag on a handle resizes the host with
+  configurable minimum dimensions. Emits aui:resize-start, aui:resize-move, and
+  aui:resize-end events with current width and height.
+config:
+  - name: handles
+    type: string
+    default: "se"
+    description: Comma-separated edges/corners to add handles ('n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw').
+  - name: min-width
+    type: string
+    default: "50"
+    description: Minimum width in pixels.
+  - name: min-height
+    type: string
+    default: "50"
+    description: Minimum height in pixels.
+events:
+  - name: aui:resize-start
+    description: Fires on resize begin, detail contains width and height.
+  - name: aui:resize-move
+    description: Fires on each pointer move during resize, detail contains width and height.
+  - name: aui:resize-end
+    description: Fires on resize end, detail contains width and height.
+exposes:
+  - name: data-resize-resizing
+    description: Present while a resize drag is in progress.
+examples:
+  - html: |
+      <aui-panel traits="resize">Resizable panel</aui-panel>
+    description: Basic resizable panel with south-east handle.
+  - html: |
+      <aui-panel traits="{ trait: 'resize', handles: 'se,e,s', min-width: '100', min-height: '100' }">Panel</aui-panel>
+    description: Resize from three edges with larger minimums.

package/dist/docs/traits/ripple.yaml

@@ -0,0 +1,20 @@
+name: ripple
+type: trait
+category: effect
+summary: Adds a Material-style expanding ripple effect on pointer press.
+description: >
+  Creates an expanding circular ripple originating from the pointer
+  position on pointerdown. The ripple is a span element with CSS
+  animation that auto-removes on animationend. Requires companion
+  CSS for the .aui-ripple class (position, animation, opacity).
+
+config: []
+
+events: []
+
+exposes: []
+
+examples:
+  - html: |
+      <aui-button traits="ripple">Click me</aui-button>
+    description: Basic ripple effect on a button.

package/dist/docs/traits/roving-focus.yaml

@@ -0,0 +1,30 @@
+name: roving-focus
+type: trait
+category: focus
+summary: Arrow key navigation within the host's focusable children.
+description: >
+  Implements roving tabindex pattern where all focusable children are set
+  to tabindex=-1 except the active one (tabindex=0), making the group a
+  single tab stop. Supports horizontal, vertical, or both orientations,
+  optional wrapping, Home/End keys, and a configurable child selector.
+config:
+  - orientation: Arrow key direction ('horizontal' | 'vertical' | 'both', default 'both')
+  - wrap: Wrap around at edges ('true' | 'false', default 'true')
+  - selector: CSS selector for focusable children (default includes buttons, links, inputs)
+events: []
+exposes:
+  - data-roving-focus-active: Index of the currently focused child
+examples:
+  - html: |
+      <aui-select mode="bar" traits="roving-focus">
+        <span tabindex="0">Item 1</span>
+        <span tabindex="0">Item 2</span>
+        <span tabindex="0">Item 3</span>
+      </aui-select>
+    description: Basic roving focus toolbar.
+  - html: |
+      <aui-select mode="bar" traits="{ trait: 'roving-focus', orientation: 'horizontal', wrap: 'false' }">
+        <span tabindex="0">A</span>
+        <span tabindex="0">B</span>
+      </aui-select>
+    description: Horizontal-only navigation without wrapping.

package/dist/docs/traits/search.yaml

@@ -0,0 +1,44 @@
+name: search
+type: trait
+category: state
+summary: Full-text search filter that shows/hides host children by substring match.
+description: >
+  Filters the host's children by case-insensitive substring match against
+  their textContent or a configurable attribute. Responds to search custom
+  events and input events from child input elements. Applies a configurable
+  debounce delay and exposes the current query and match count.
+config:
+  - name: selector
+    type: string
+    default: "> *"
+    description: CSS selector for filterable children.
+  - name: attr
+    type: string
+    default: "textContent"
+    description: Attribute or 'textContent' to match against.
+  - name: debounce
+    type: string
+    default: "150"
+    description: Debounce delay in milliseconds.
+events:
+  - name: search-results
+    description: Fires after filtering, detail contains count and query.
+exposes:
+  - name: data-search-count
+    description: Number of visible matches.
+  - name: data-search-query
+    description: Current query string.
+examples:
+  - html: |
+      <aui-list traits="search">
+        <div>Apple</div>
+        <div>Banana</div>
+        <div>Cherry</div>
+      </aui-list>
+    description: Basic searchable list.
+  - html: |
+      <aui-list traits="{ trait: 'search', debounce: '200', attr: 'data-label' }">
+        <div data-label="Apple">Item 1</div>
+        <div data-label="Banana">Item 2</div>
+      </aui-list>
+    description: Search by data-label attribute with custom debounce.

package/dist/docs/traits/selection.yaml

@@ -0,0 +1,41 @@
+name: selection
+type: trait
+category: state
+summary: Single or multi-select state management for host children.
+description: >
+  Manages selection state on host's child elements via press events.
+  Supports single-select (deselects others on press) and multiple-select
+  (toggles individual items) modes. Tracks selection via the "selected"
+  attribute on children and emits select events with value details.
+
+config:
+  - name: mode
+    type: string
+    default: "single"
+    description: Selection mode — "single" or "multiple".
+  - name: selector
+    type: string
+    default: "> *"
+    description: CSS selector for selectable children.
+
+events:
+  - name: select
+    description: Fires on selection change with value, selected boolean, and all selected values.
+
+exposes:
+  - name: data-selection-count
+    description: Number of currently selected items.
+
+examples:
+  - html: |
+      <aui-list traits="selection">
+        <div data-value="a">Option A</div>
+        <div data-value="b">Option B</div>
+      </aui-list>
+    description: Basic single-select list.
+  - html: |
+      <aui-list traits="{ trait: 'selection', mode: 'multiple' }">
+        <div data-value="1">Item 1</div>
+        <div data-value="2">Item 2</div>
+      </aui-list>
+    description: Multi-select mode.

package/dist/docs/traits/shortcut.yaml

@@ -0,0 +1,25 @@
+name: shortcut
+type: trait
+category: state
+summary: Keyboard shortcut binding that emits press on key combo match.
+description: >
+  Parses a key combo string (e.g. ctrl+k, meta+shift+p) and listens
+  for matching keydown events. When matched, prevents default and
+  emits shortcut and press events on the host.
+config:
+  - name: key
+    type: string
+    default: ""
+    description: "Key combo string (e.g. ctrl+k, meta+shift+p)."
+  - name: global
+    type: string
+    default: "false"
+    description: "Listen on document instead of host."
+events:
+  - name: shortcut-trigger
+    description: Fires on key combo match with { key } detail.
+exposes: []
+examples:
+  - html: |
+      <aui-button traits="{ trait: 'shortcut', key: 'ctrl+k' }">Search</aui-button>
+    description: Keyboard shortcut on the host element.

package/dist/docs/traits/slash-command.yaml

@@ -0,0 +1,40 @@
+name: slash-command
+type: trait
+category: state
+summary: Detects /commands in text input and emits command events.
+description: >
+  Watches for a trigger character (default: /) at the start of input
+  and emits command-input events as the user types for autocomplete.
+  On Enter, parses the command and arguments and emits a command event.
+  Optionally restricts to a whitelist of known commands. Works with
+  both contenteditable elements and native inputs.
+
+config:
+  - name: trigger
+    type: string
+    default: "/"
+    description: Character that starts a command.
+  - name: commands
+    type: string
+    default: ""
+    description: Comma-separated whitelist of valid commands (empty allows all).
+
+events:
+  - name: command
+    description: Fires on Enter with command name and args in detail.
+  - name: command-input
+    description: Fires as the user types with the partial command text.
+
+exposes:
+  - name: data-slash-command-active
+    description: Present while the user is actively typing a command.
+
+examples:
+  - html: |
+      <aui-input traits="slash-command">Type /help</aui-input>
+    description: Basic slash command detection.
+  - html: |
+      <aui-input traits="{ trait: 'slash-command', trigger: '/', commands: 'search,help,clear' }">
+        Restricted commands
+      </aui-input>
+    description: Only emit for known commands.

package/dist/docs/traits/snap-resize.yaml

@@ -0,0 +1,39 @@
+name: snap-resize
+type: trait
+category: effect
+summary: Snaps pane resize operations to grid increments.
+description: >
+  Listens for aui:panes-resize events and rounds sizes to the nearest grid
+  increment. Optionally only snaps while a modifier key is held. Applies
+  snapped sizes as flex-basis on the host's children. Designed to work
+  with pane layout components.
+
+config:
+  - name: grid
+    type: string
+    default: "50"
+    description: Snap increment in pixels.
+  - name: modifier
+    type: string
+    default: ""
+    description: Key that must be held to enable snapping (e.g., "Shift"). Empty means always snap.
+
+events: []
+
+exposes:
+  - name: data-snap-resize-grid
+    description: The current grid increment value.
+
+examples:
+  - html: |
+      <aui-panes traits="snap-resize">
+        <div>Pane 1</div>
+        <div>Pane 2</div>
+      </aui-panes>
+    description: Basic snap resize with default 50px grid.
+  - html: |
+      <aui-panes traits="{ trait: 'snap-resize', grid: '100', modifier: 'Shift' }">
+        <div>Pane 1</div>
+        <div>Pane 2</div>
+      </aui-panes>
+    description: Snap to 100px grid only while Shift is held.

package/dist/docs/traits/sort.yaml

@@ -0,0 +1,47 @@
+name: sort
+type: trait
+category: gesture
+summary: Drag-to-reorder with automatic DOM reordering on drop.
+description: >
+  Convenience trait that provides drag-to-reorder with a popover ghost
+  and automatic DOM repositioning on drop. Shows a gap indicator in
+  list modes. Supports axis constraint and optional drag handle.
+  For more control (cross-zone, preview mode, drop targets), use
+  the drag trait directly.
+
+config:
+  - name: selector
+    type: string
+    default: "> *"
+    description: CSS selector for sortable children.
+  - name: handle
+    type: string
+    default: ""
+    description: CSS selector for drag handle within each child.
+  - name: axis
+    type: string
+    default: "vertical"
+    description: Constraint axis ('vertical' | 'horizontal' | 'both').
+
+events:
+  - name: sort
+    description: Fires on reorder complete. Detail { order } contains string array of data-sort-key values or indices.
+
+exposes:
+  - name: data-sort-dragging
+    description: Present while a sort drag is in progress.
+
+examples:
+  - html: |
+      <div traits="sort">
+        <div>Item 1</div>
+        <div>Item 2</div>
+        <div>Item 3</div>
+      </div>
+    description: Basic vertical drag-to-reorder list.
+  - html: |
+      <div traits="{ trait: 'sort', handle: '.grip', axis: 'vertical' }">
+        <div><span class="grip">⁞</span> Item 1</div>
+        <div><span class="grip">⁞</span> Item 2</div>
+      </div>
+    description: Sort with a dedicated drag handle.

package/dist/docs/traits/store.yaml

@@ -0,0 +1,32 @@
+name: store
+type: trait
+category: state
+summary: Data-driven DOM stamping for list-like components.
+description: >
+  Reads data from a ListStore (signal-backed), store attribute, or
+  options attribute and stamps aui-option elements into the host or
+  a target container. Supports grouped data with configurable group
+  wrapper tag names. Reactively re-stamps when the data source changes
+  and observes attribute mutations on the host.
+
+config:
+  - name: target
+    type: string
+    default: ":scope"
+    description: CSS selector for the stamping container (default is the host itself).
+  - name: group-tag
+    type: string
+    default: "aui-group"
+    description: Tag name for group wrapper elements.
+
+events: []
+
+exposes:
+  - name: data-store-count
+    description: Total number of stamped items.
+
+examples:
+  - html: |
+      <aui-select traits="store" options='[{"id":"a","label":"Alpha"}]'>
+      </aui-select>
+    description: Stamp options from a JSON attribute.

package/dist/docs/traits/swipe.yaml

@@ -0,0 +1,38 @@
+name: swipe
+type: trait
+category: gesture
+summary: Detects swipe gestures and emits direction, distance, and velocity.
+description: >
+  Tracks pointer down and up events to detect swipe gestures. A swipe
+  is recognized when the pointer travels beyond the distance threshold
+  within the timeout window. Emits direction (left, right, up, down),
+  total distance, and velocity. Temporarily exposes the swipe direction
+  as a data attribute for CSS-driven transitions.
+
+config:
+  - name: threshold
+    type: string
+    default: "50"
+    description: Minimum distance in pixels to qualify as a swipe.
+  - name: timeout
+    type: string
+    default: "300"
+    description: Maximum elapsed time in milliseconds for the gesture to count.
+
+events:
+  - name: swipe
+    description: Fires on a successful swipe. Detail contains { direction, distance, velocity }.
+
+exposes:
+  - name: data-swipe-direction
+    description: Set to "left", "right", "up", or "down" after a swipe. Cleared after 500ms.
+
+examples:
+  - html: |
+      <aui-card traits="swipe">Swipe me</aui-card>
+    description: Basic swipe detection with default thresholds.
+  - html: |
+      <aui-surface traits="{ trait: 'swipe', threshold: '80', timeout: '400' }">
+        Content
+      </aui-surface>
+    description: Swipe with a longer distance threshold and timeout.

package/dist/docs/traits/text-trigger.yaml

@@ -0,0 +1,35 @@
+name: text-trigger
+type: trait
+category: state
+summary: Generic text pattern trigger that emits on regex match.
+description: >
+  Watches the host's input value and tests it against a configurable
+  regex pattern. Emits a text-trigger event when the pattern matches,
+  with the match and capture groups in detail. Optionally requires a
+  trigger character to be present before matching. Exposes a matched
+  state for CSS styling.
+
+config:
+  - name: pattern
+    type: string
+    default: ""
+    description: Regular expression pattern to match against input value (required).
+  - name: trigger
+    type: string
+    default: ""
+    description: Character that must be present in the value before matching.
+
+events:
+  - name: text-trigger
+    description: Fires when the pattern matches, with match and groups in detail.
+
+exposes:
+  - name: data-text-trigger-matched
+    description: Present when the pattern currently matches the input value.
+
+examples:
+  - html: |
+      <aui-input traits="{ trait: 'text-trigger', pattern: '#[a-zA-Z]+' }">
+        Type a hashtag
+      </aui-input>
+    description: Detect hashtag patterns in input.

package/dist/docs/traits/toast.yaml

@@ -0,0 +1,41 @@
+name: toast
+type: trait
+category: present
+summary: Transient notification that auto-dismisses and stacks.
+description: >
+  Positions the host as a fixed toast notification on screen with
+  configurable position and auto-dismiss duration. Stacks with other
+  visible toasts by calculating offset from existing notifications.
+  Uses CSS transition states for enter and dismiss animations.
+
+config:
+  - name: duration
+    type: string
+    default: "3000"
+    description: Auto-dismiss delay in milliseconds (0 for manual dismiss).
+  - name: position
+    type: string
+    default: "bottom-right"
+    description: Screen position — "top-right", "top-left", "bottom-right", "bottom-left", "top-center", or "bottom-center".
+  - name: stack
+    type: string
+    default: "true"
+    description: Whether to stack with other visible toasts.
+
+events:
+  - name: toast-dismiss
+    description: Fires when the toast is dismissed.
+
+exposes:
+  - name: data-toast-visible
+    description: Present while the toast is visible.
+
+examples:
+  - html: |
+      <aui-toast traits="toast">Notification message</aui-toast>
+    description: Basic toast with default position and duration.
+  - html: |
+      <aui-toast traits="{ trait: 'toast', position: 'top-center', duration: '5000' }">
+        Important notice
+      </aui-toast>
+    description: Top-center toast with 5-second duration.

package/dist/docs/traits/toggle-scheme.yaml

@@ -0,0 +1,40 @@
+name: toggle-scheme
+type: trait
+category: state
+summary: Cycles color-scheme on a target element between system, light, and dark.
+description: >
+  On each press event, advances through the configured scheme list
+  (system, light, dark), applying color-scheme and data-color-scheme
+  to the target element. Updates the host's icon and label attributes
+  to reflect the current scheme. Optionally persists the selection
+  to localStorage and reacts to system preference changes.
+config:
+  - name: scheme
+    type: string
+    default: "system"
+    description: Initial scheme ('system' | 'light' | 'dark').
+  - name: schemes
+    type: string
+    default: "system,light,dark"
+    description: Comma-separated list of available schemes.
+  - name: target
+    type: string
+    default: "document"
+    description: CSS selector or 'document' for the target element.
+  - name: persist
+    type: string
+    default: "false"
+    description: Persist selection to localStorage ('true' | 'false').
+events:
+  - name: scheme-change
+    description: Fires on scheme change, detail contains scheme string.
+exposes:
+  - name: data-toggle-scheme-scheme
+    description: Current scheme value ('system' | 'light' | 'dark').
+examples:
+  - html: |
+      <aui-button traits="toggle-scheme">Theme</aui-button>
+    description: Basic color scheme toggle.
+  - html: |
+      <aui-button traits="{ trait: 'toggle-scheme', persist: 'true' }">Theme</aui-button>
+    description: Persists the selected scheme across sessions.

package/dist/docs/traits/toggle-state.yaml

@@ -0,0 +1,23 @@
+name: toggle-state
+type: trait
+category: state
+summary: Generic boolean toggle that flips on press and exposes active state.
+description: >
+  Maintains a reactive boolean state that toggles on each press event.
+  Exposes the active state as a data attribute and sets aria-pressed
+  for accessibility. Emits a toggle event with the new active value.
+config:
+  - name: active
+    type: string
+    default: "false"
+    description: Initial active state ('true' or 'false').
+events:
+  - name: toggle
+    description: Fires on state change, detail contains { active }.
+exposes:
+  - name: data-toggle-state-active
+    description: Present when the toggle is active.
+examples:
+  - html: |
+      <aui-button traits="toggle-state">Toggle me</aui-button>
+    description: Basic toggle button.

package/dist/docs/traits/tooltip.yaml

@@ -0,0 +1,39 @@
+name: tooltip
+type: trait
+category: present
+summary: Shows a tooltip on hover or focus using the Popover API.
+description: >
+  Displays a tooltip after a configurable delay when the host is hovered
+  or focused. Uses the Popover API (popover=manual) and CSS anchor
+  positioning for placement. The tooltip is appended to the host and
+  removed on mouseleave or focusout.
+
+config:
+  - name: text
+    type: string
+    default: ""
+    description: The text content displayed inside the tooltip.
+  - name: delay
+    type: string
+    default: "500"
+    description: Milliseconds to wait before showing the tooltip.
+  - name: position
+    type: string
+    default: "top"
+    description: Tooltip placement relative to the host (top, bottom, left, right).
+
+events: []
+
+exposes:
+  - name: data-tooltip-open
+    description: Set to "true" while the tooltip is visible, "false" when hidden.
+
+examples:
+  - html: |
+      <aui-button traits="{ trait: 'tooltip', text: 'Save document' }">Save</aui-button>
+    description: Basic tooltip on a button.
+  - html: |
+      <aui-button traits="{ trait: 'tooltip', text: 'Delete item', position: 'bottom', delay: '200' }">
+        Delete
+      </aui-button>
+    description: Tooltip positioned below with a shorter delay.

package/dist/docs/traits/toss.yaml

@@ -0,0 +1,40 @@
+name: toss
+type: trait
+category: effect
+summary: Physics-based throw that flings the host and springs back to origin.
+description: >
+  Samples pointer velocity during movement and, on pointer release,
+  applies that velocity as a physics-based fling animation. The host
+  translates in the throw direction with configurable friction, then
+  springs back toward its original position. Uses requestAnimationFrame
+  for smooth animation with no CSS transitions.
+
+config:
+  - name: friction
+    type: string
+    default: "0.92"
+    description: Velocity decay per frame. Lower values slow faster (0-1 range).
+  - name: bounce
+    type: string
+    default: "0.15"
+    description: Spring-back force toward origin per frame (0-1 range).
+  - name: max
+    type: string
+    default: "200"
+    description: Maximum displacement in pixels before clamping.
+
+events: []
+
+exposes:
+  - name: data-toss-active
+    description: Present while the toss animation is running.
+
+examples:
+  - html: |
+      <aui-card traits="toss">Toss me</aui-card>
+    description: Basic toss with default physics.
+  - html: |
+      <aui-card traits="{ trait: 'toss', friction: '0.90', bounce: '0.2' }">
+        Flick me
+      </aui-card>
+    description: Slightly more damped toss with stronger spring-back.

package/dist/docs/traits/trap-focus.yaml

@@ -0,0 +1,20 @@
+name: trap-focus
+type: trait
+category: focus
+summary: Traps keyboard focus within the host element.
+description: >
+  Intercepts Tab and Shift+Tab keydown events to cycle focus through
+  the host's focusable children without escaping. Automatically focuses
+  the first focusable child on attach. Targets standard focusable elements
+  including links, buttons, inputs, selects, textareas, and elements with
+  tabindex.
+config: []
+events: []
+exposes: []
+examples:
+  - html: |
+      <aui-container traits="trap-focus">
+        <a href="#">Link</a>
+        <span tabindex="0">Focusable</span>
+      </aui-container>
+    description: Basic focus trap around focusable children.