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

package/dist/docs/traits/hover.yaml

@@ -0,0 +1,39 @@
+name: hover
+type: trait
+category: state
+summary: Tracks hover state with optional enter/leave delays.
+description: >
+  Monitors mouseenter and mouseleave events on the host element, exposing
+  a boolean active state via data-hover-active. Supports configurable
+  enter and leave delays to debounce rapid pointer movement. Pending
+  timers are cancelled when the opposite event fires, preventing flicker.
+
+config:
+  - name: delay
+    type: string
+    default: "0"
+    description: Milliseconds to wait after mouseenter before activating.
+  - name: leave-delay
+    type: string
+    default: "0"
+    description: Milliseconds to wait after mouseleave before deactivating.
+
+events:
+  - name: hover-enter
+    description: Fires when the host becomes hovered (after delay).
+  - name: hover-leave
+    description: Fires when the host is no longer hovered (after leave-delay).
+
+exposes:
+  - name: data-hover-active
+    description: Present and set to "true" while the host is hovered.
+
+examples:
+  - html: |
+      <aui-button traits="hover">Hover me</aui-button>
+    description: Basic hover tracking with no delay.
+  - html: |
+      <aui-card traits="{ trait: 'hover', delay: '200', leave-delay: '100' }">
+        Content
+      </aui-card>
+    description: Debounced hover with 200ms enter delay and 100ms leave delay.

package/dist/docs/traits/intersect.yaml

@@ -0,0 +1,42 @@
+name: intersect
+type: trait
+category: state
+summary: IntersectionObserver wrapper exposing viewport visibility state.
+description: >
+  Wraps the IntersectionObserver API to track whether the host element
+  is visible in the viewport. Exposes a visible boolean state and emits
+  intersect events with intersection ratio. Supports configurable
+  threshold, root margin, and a once mode that disconnects after first
+  intersection.
+
+config:
+  - name: threshold
+    type: string
+    default: "0"
+    description: Intersection ratio threshold (0 to 1) to trigger visibility.
+  - name: root-margin
+    type: string
+    default: "0px"
+    description: Root margin for the IntersectionObserver.
+  - name: once
+    type: string
+    default: "false"
+    description: When "true", disconnects the observer after the first intersection.
+
+events:
+  - name: intersect
+    description: Fires when intersection state changes, with isIntersecting and ratio in detail.
+
+exposes:
+  - name: data-intersect-visible
+    description: Present and set to "true" when the host is intersecting the viewport.
+
+examples:
+  - html: |
+      <aui-card traits="intersect">Lazy content</aui-card>
+    description: Basic viewport visibility tracking.
+  - html: |
+      <aui-card traits="{ trait: 'intersect', threshold: '0.5', once: 'true' }">
+        Animate once visible
+      </aui-card>
+    description: Fire once when 50% of the element is visible.

package/dist/docs/traits/link-paste.yaml

@@ -0,0 +1,28 @@
+name: link-paste
+type: trait
+category: state
+summary: Detects URLs in pasted text and emits link-paste events.
+description: >
+  Listens for paste events on the host element and scans the pasted
+  text for URLs. When a URL is detected, exposes it via data-link-paste-url
+  and emits a link-paste event with the URL and full pasted text. Useful
+  for embed previews and automatic link handling.
+
+config:
+  - name: auto
+    type: string
+    default: "true"
+    description: When "true", automatically detects URLs on paste.
+
+events:
+  - name: link-paste
+    description: Fires when a URL is detected in pasted text, with url and text in detail.
+
+exposes:
+  - name: data-link-paste-url
+    description: The detected URL from the most recent paste, or empty when none.
+
+examples:
+  - html: |
+      <aui-editor traits="link-paste">Paste a URL here</aui-editor>
+    description: Basic link paste detection.

package/dist/docs/traits/linked-scroll.yaml

@@ -0,0 +1,37 @@
+name: linked-scroll
+type: trait
+category: state
+summary: Bidirectional scroll sync between two elements by percentage.
+description: >
+  Synchronizes scroll position between the host and a target element
+  using scroll percentage rather than absolute pixels, so it works
+  with different-sized content. Supports restricting sync to x, y,
+  or both axes. Uses a syncing guard to prevent infinite feedback loops.
+
+config:
+  - name: target
+    type: string
+    default: ""
+    description: CSS selector for the scroll sync partner (required).
+  - name: axis
+    type: string
+    default: "both"
+    description: Axis to sync — "both", "x", or "y".
+
+events: []
+
+exposes:
+  - name: data-linked-scroll-syncing
+    description: Present and set to "true" during active scroll synchronization.
+
+examples:
+  - html: |
+      <div traits="{ trait: 'linked-scroll', target: '#preview' }">
+        Editor content
+      </div>
+    description: Sync scroll with a preview pane.
+  - html: |
+      <div traits="{ trait: 'linked-scroll', target: '#preview', axis: 'y' }">
+        Vertical sync only
+      </div>
+    description: Sync only vertical scroll position.

package/dist/docs/traits/list-navigate.yaml

@@ -0,0 +1,46 @@
+name: list-navigate
+type: trait
+category: focus
+summary: Arrow key navigation and type-ahead search in a list.
+description: >
+  Adds keyboard navigation to a list of child elements. Supports arrow
+  keys for moving a highlight indicator, Home/End for jumping to
+  extremes, Enter for activation, and type-ahead character search that
+  matches against child text content with a configurable timeout.
+
+config:
+  - name: selector
+    type: string
+    default: "> *"
+    description: CSS selector for navigable children.
+  - name: typeahead
+    type: string
+    default: "true"
+    description: Enable type-ahead character search.
+  - name: timeout
+    type: string
+    default: "500"
+    description: Milliseconds before the type-ahead buffer resets.
+
+events:
+  - name: activate
+    description: Fires on Enter with the current highlight index in detail.
+
+exposes:
+  - name: data-list-navigate-index
+    description: The current highlighted item index.
+
+examples:
+  - html: |
+      <aui-list traits="list-navigate">
+        <li>Apple</li>
+        <li>Banana</li>
+        <li>Cherry</li>
+      </aui-list>
+    description: Basic arrow key navigation in a list.
+  - html: |
+      <aui-list traits="{ trait: 'list-navigate', selector: '> li', typeahead: 'false' }">
+        <li>Item 1</li>
+        <li>Item 2</li>
+      </aui-list>
+    description: Navigation without type-ahead search.

package/dist/docs/traits/magnet.yaml

@@ -0,0 +1,33 @@
+name: magnet
+type: trait
+category: effect
+summary: Host subtly follows and tilts toward the cursor on hover.
+description: >
+  Applies perspective-based transforms to the host element so it
+  follows and tilts toward the mouse cursor. Uses CSS custom properties
+  for translation and rotation values. Animates smoothly back to
+  center on mouse leave. Configurable strength and tilt intensity.
+
+config:
+  - name: strength
+    type: string
+    default: "10"
+    description: Maximum translation distance in pixels.
+  - name: tilt
+    type: string
+    default: "5"
+    description: Maximum tilt rotation in degrees.
+
+events: []
+
+exposes: []
+
+examples:
+  - html: |
+      <aui-card traits="magnet">Hover to see the effect</aui-card>
+    description: Basic magnetic follow effect.
+  - html: |
+      <aui-card traits="{ trait: 'magnet', strength: '15', tilt: '8' }">
+        Strong magnet
+      </aui-card>
+    description: Increased strength and tilt.

package/dist/docs/traits/mention.yaml

@@ -0,0 +1,40 @@
+name: mention
+type: trait
+category: state
+summary: Detects @mentions in text input and emits search events.
+description: >
+  Watches for a trigger character (default: @) in text input and emits
+  mention-search events as the user types a mention query. Listens for
+  mention-select events to insert the chosen mention text. Works with
+  both contenteditable elements and native input/textarea. Exposes an
+  active state while a mention is being typed.
+
+config:
+  - name: trigger
+    type: string
+    default: "@"
+    description: Character that triggers mention detection.
+  - name: min-length
+    type: string
+    default: "1"
+    description: Minimum query length before emitting search events.
+
+events:
+  - name: mention-search
+    description: Fires as the user types after the trigger, with query in detail.
+  - name: mention-select
+    description: Listened for externally to insert the chosen mention text.
+
+exposes:
+  - name: data-mention-active
+    description: Present while the user is actively typing a mention.
+
+examples:
+  - html: |
+      <aui-input traits="mention">Type @ to mention someone</aui-input>
+    description: Basic mention detection with @ trigger.
+  - html: |
+      <aui-input traits="{ trait: 'mention', trigger: '@', min-length: '2' }">
+        Mention with minimum 2 characters
+      </aui-input>
+    description: Require at least 2 characters before searching.

package/dist/docs/traits/modal.yaml

@@ -0,0 +1,28 @@
+name: modal
+type: trait
+category: present
+summary: Modal overlay using the Popover API with focus trap and backdrop.
+description: >
+  Promotes the host to the top layer as a modal overlay (popover="manual")
+  with backdrop click dismiss, focus trapping via inert siblings, and
+  CSS anchor positioning. Restores focus to the previously focused element
+  on close. Supports configurable animations and anchor placement.
+config:
+  - closable: Allow closing via Escape or backdrop click ('true' | 'false', default 'true')
+  - anchor: CSS selector for anchor element (empty = centered)
+  - placement: CSS position-area value (default 'block-end span-inline-end')
+  - type: Popover API mode (default 'manual')
+  - matchWidth: Match anchor inline size ('true' | 'false', default 'false')
+  - animation: Entry/exit animation ('scale' | 'fade' | 'hinge' | 'none', default 'scale')
+events:
+  - overlay-open: Fires when modal opens
+  - overlay-close: Fires when modal closes
+exposes:
+  - data-modal-open: Boolean indicating whether the modal is open
+examples:
+  - html: |
+      <aui-panel traits="modal">Modal content</aui-panel>
+    description: Basic centered modal.
+  - html: |
+      <aui-panel traits="{ trait: 'modal', anchor: '#btn' }">Anchored modal</aui-panel>
+    description: Modal anchored to a button element.

package/dist/docs/traits/noodle.yaml

@@ -0,0 +1,45 @@
+name: noodle
+type: trait
+category: effect
+summary: Draws an SVG curved line connecting the host to a target element.
+description: >
+  Creates an SVG overlay with a cubic bezier path connecting the center
+  of the host element to the center of a target element. Automatically
+  updates on scroll, resize, and size changes via ResizeObserver.
+  Configurable color, stroke width, and curvature.
+
+config:
+  - name: target
+    type: string
+    default: ""
+    description: CSS selector for the element to connect to (required).
+  - name: color
+    type: string
+    default: "currentColor"
+    description: Stroke color of the connecting line.
+  - name: width
+    type: string
+    default: "2"
+    description: Stroke width of the connecting line.
+  - name: curvature
+    type: string
+    default: "0.5"
+    description: Curvature factor for the bezier control points (0 = straight, 1 = very curved).
+
+events: []
+
+exposes:
+  - name: data-noodle-connected
+    description: Present and set to "true" when the target element is found and connected.
+
+examples:
+  - html: |
+      <aui-node traits="{ trait: 'noodle', target: '#other-node' }">
+        Source
+      </aui-node>
+    description: Basic connection line between two elements.
+  - html: |
+      <aui-node traits="{ trait: 'noodle', target: '.peer', color: '#ff6b6b', width: '3' }">
+        Styled connection
+      </aui-node>
+    description: Custom color and width for the connecting line.

package/dist/docs/traits/overlay.yaml

@@ -0,0 +1,58 @@
+name: overlay
+type: trait
+category: present
+summary: Popover and modal overlay traits built on the Popover API.
+description: >
+  Factory module that creates two presentation traits — popover and modal —
+  both built on the Popover API with CSS anchor positioning. Popover uses
+  auto mode with light dismiss; modal uses manual mode with backdrop click
+  handling and focus trapping via inert. Supports configurable anchor
+  positioning, animations, and width matching.
+
+config:
+  - name: closable
+    type: string
+    default: "true"
+    description: Whether the overlay can be dismissed.
+  - name: anchor
+    type: string
+    default: ""
+    description: CSS selector for the anchor element (empty for centered).
+  - name: placement
+    type: string
+    default: "block-end span-inline-end"
+    description: CSS position-area value for anchor positioning.
+  - name: type
+    type: string
+    default: "auto"
+    description: Popover API mode — "auto" (light dismiss) or "manual".
+  - name: matchWidth
+    type: string
+    default: "false"
+    description: Whether to match the anchor element's inline size.
+  - name: animation
+    type: string
+    default: "scale"
+    description: Animation style — "scale", "fade", "hinge", or "none".
+
+events:
+  - name: overlay-open
+    description: Fires when the overlay opens.
+  - name: overlay-close
+    description: Fires when the overlay closes.
+
+exposes:
+  - name: data-popover-open
+    description: Present on popover variant when open.
+  - name: data-modal-open
+    description: Present on modal variant when open.
+
+examples:
+  - html: |
+      <aui-panel traits="popover">Popover content</aui-panel>
+    description: Basic centered popover.
+  - html: |
+      <aui-panel traits="{ trait: 'modal', anchor: '#btn' }">
+        Modal content
+      </aui-panel>
+    description: Anchored modal overlay.

package/dist/docs/traits/pan-zoom.yaml

@@ -0,0 +1,47 @@
+name: pan-zoom
+type: trait
+category: gesture
+summary: Makes any element a pannable and zoomable canvas surface.
+description: >
+  Adds pan and zoom gestures to the host element. Supports middle-click
+  drag or Space+drag for panning, Ctrl+wheel for zooming toward the
+  pointer, and Ctrl+double-click to reset. Sets CSS custom properties
+  (--_pan-x, --_pan-y, --_pan-zoom) for transform application.
+
+config:
+  - name: min-zoom
+    type: string
+    default: "0.1"
+    description: Minimum zoom scale.
+  - name: max-zoom
+    type: string
+    default: "5"
+    description: Maximum zoom scale.
+  - name: zoom-step
+    type: string
+    default: "0.1"
+    description: Zoom increment per wheel tick.
+
+events:
+  - name: pan-zoom-change
+    description: Fires on pan or zoom change with x, y, and scale in detail.
+
+exposes:
+  - name: data-pan-zoom-scale
+    description: Current zoom scale value.
+  - name: data-pan-zoom-x
+    description: Current horizontal pan offset.
+  - name: data-pan-zoom-y
+    description: Current vertical pan offset.
+
+examples:
+  - html: |
+      <div traits="pan-zoom">
+        <img src="large-image.png" />
+      </div>
+    description: Basic pannable and zoomable container.
+  - html: |
+      <div traits="{ trait: 'pan-zoom', min-zoom: '0.25', max-zoom: '4' }">
+        Canvas content
+      </div>
+    description: Custom zoom range.

package/dist/docs/traits/parallax.yaml

@@ -0,0 +1,36 @@
+name: parallax
+type: trait
+category: effect
+summary: Scroll-based parallax shifting via CSS custom property.
+description: >
+  Shifts the host element at a fraction of the scroll speed to create
+  a depth-of-field parallax effect. Calculates offset based on the
+  host's position relative to the viewport center and applies it
+  through a CSS custom property. Uses requestAnimationFrame for
+  smooth, jank-free updates.
+
+config:
+  - name: speed
+    type: string
+    default: "0.5"
+    description: Parallax speed multiplier. 0 means no shift, 1 means full scroll speed.
+  - name: direction
+    type: string
+    default: "vertical"
+    description: Parallax direction — "vertical" or "horizontal".
+
+events: []
+
+exposes: []
+
+examples:
+  - html: |
+      <aui-section traits="parallax">
+        Background content
+      </aui-section>
+    description: Basic vertical parallax at half scroll speed.
+  - html: |
+      <aui-section traits="{ trait: 'parallax', speed: '0.3', direction: 'horizontal' }">
+        Side-scrolling content
+      </aui-section>
+    description: Slower horizontal parallax effect.

package/dist/docs/traits/persist.yaml

@@ -0,0 +1,42 @@
+name: persist
+type: trait
+category: state
+summary: Saves and restores arbitrary state to localStorage.
+description: >
+  Generic persistence primitive that saves and restores state via
+  localStorage. On attach, loads saved state and emits a persist-load
+  event. Listens for persist-save events from the host to debounce
+  saves to localStorage. Handles quota exceeded and private browsing
+  gracefully.
+
+config:
+  - name: key
+    type: string
+    default: ""
+    description: localStorage key for the persisted state (required).
+  - name: debounce
+    type: string
+    default: "300"
+    description: Milliseconds to debounce save operations.
+
+events:
+  - name: persist-load
+    description: Fires on attach with the restored state in detail.
+  - name: persist-save
+    description: Dispatched by the host to trigger a save with state in detail.
+
+exposes:
+  - name: data-persist-ready
+    description: Present after initial load is complete.
+
+examples:
+  - html: |
+      <aui-panes traits="{ trait: 'persist', key: 'my-layout' }">
+        Persisted content
+      </aui-panes>
+    description: Basic persistence with a localStorage key.
+  - html: |
+      <aui-panes traits="{ trait: 'persist', key: 'my-layout', debounce: '500' }">
+        Debounced saves
+      </aui-panes>
+    description: Custom debounce interval for save operations.

package/dist/docs/traits/popover.yaml

@@ -0,0 +1,28 @@
+name: popover
+type: trait
+category: present
+summary: Non-modal overlay using the Popover API with CSS anchor positioning.
+description: >
+  Promotes the host to the top layer as a non-modal popover (popover="auto")
+  with light dismiss. Supports anchor positioning via CSS position-anchor,
+  configurable placement, width matching, and entry/exit animations. Syncs
+  state with browser-initiated popover toggles.
+config:
+  - closable: Allow closing via Escape or light dismiss ('true' | 'false', default 'true')
+  - anchor: CSS selector for anchor element (empty = centered)
+  - placement: CSS position-area value (default 'block-end span-inline-end')
+  - type: Popover API mode (default 'auto')
+  - matchWidth: Match anchor inline size ('true' | 'false', default 'false')
+  - animation: Entry/exit animation ('scale' | 'fade' | 'hinge' | 'none', default 'scale')
+events:
+  - overlay-open: Fires when popover opens
+  - overlay-close: Fires when popover closes
+exposes:
+  - data-popover-open: Boolean indicating whether the popover is open
+examples:
+  - html: |
+      <aui-panel traits="popover">Popover content</aui-panel>
+    description: Basic centered popover.
+  - html: |
+      <div traits="{ trait: 'popover', anchor: '#trigger' }">Anchored content</div>
+    description: Popover anchored to a trigger element.

package/dist/docs/traits/present.yaml

@@ -0,0 +1,42 @@
+name: present
+type: trait
+category: present
+summary: Show/hide the host with CSS transition state attributes.
+description: >
+  Manages visibility of the host element through data attributes that
+  CSS can hook into for transitions. Sets data-present-entering during
+  show transitions, data-present-leaving during hide transitions, and
+  data-present-hidden when fully hidden. Responds to toggle, show,
+  and hide action events.
+
+config:
+  - name: visible
+    type: string
+    default: "true"
+    description: Initial visibility state.
+  - name: transition
+    type: string
+    default: "200"
+    description: Transition duration in milliseconds.
+
+events: []
+
+exposes:
+  - name: data-present-visible
+    description: Boolean indicating current visibility state.
+  - name: data-present-entering
+    description: Present during the show transition.
+  - name: data-present-leaving
+    description: Present during the hide transition.
+  - name: data-present-hidden
+    description: Present when the element is fully hidden.
+
+examples:
+  - html: |
+      <aui-toast traits="present">Visible by default</aui-toast>
+    description: Basic show/hide with default transition.
+  - html: |
+      <aui-toast traits="{ trait: 'present', visible: 'false', transition: '300' }">
+        Initially hidden
+      </aui-toast>
+    description: Initially hidden with 300ms transition duration.

package/dist/docs/traits/press-hold.yaml

@@ -0,0 +1,34 @@
+name: press-hold
+type: trait
+category: gesture
+summary: Emits a hold event after a long press on the host.
+description: >
+  Starts a timer on pointerdown and emits a hold event if the pointer
+  remains down for the configured delay. Cancels if the pointer is
+  released, leaves the host, or is cancelled before the threshold.
+  Useful for context menus, destructive action confirmations, or
+  secondary interactions.
+
+config:
+  - name: delay
+    type: string
+    default: "500"
+    description: Milliseconds the pointer must be held before firing the hold event.
+
+events:
+  - name: hold
+    description: Fires when the hold threshold is reached.
+
+exposes:
+  - name: data-press-hold-held
+    description: Present after a successful hold, removed on pointer release.
+
+examples:
+  - html: |
+      <aui-button traits="press-hold">Hold me</aui-button>
+    description: Basic press-and-hold with default 500ms delay.
+  - html: |
+      <aui-button traits="{ trait: 'press-hold', delay: '600' }">
+        Long press
+      </aui-button>
+    description: Custom 600ms hold threshold.

package/dist/docs/traits/range-select.yaml

@@ -0,0 +1,42 @@
+name: range-select
+type: trait
+category: state
+summary: Shift/Cmd-click range and multi-selection on host children.
+description: >
+  Adds range and multi-selection behavior to a list of child elements.
+  Shift-click selects a contiguous range, Cmd/Ctrl-click toggles
+  individual items, and plain click selects a single item. Manages
+  selection state via configurable attributes on children.
+
+config:
+  - name: selector
+    type: string
+    default: "> *"
+    description: CSS selector for selectable children.
+  - name: attr
+    type: string
+    default: "selected"
+    description: Attribute name set on selected children.
+
+events:
+  - name: selection-change
+    description: Fires on selection change with selected indices and count in detail.
+
+exposes:
+  - name: data-range-select-count
+    description: Number of currently selected items.
+
+examples:
+  - html: |
+      <aui-list traits="range-select">
+        <div>Item 1</div>
+        <div>Item 2</div>
+        <div>Item 3</div>
+      </aui-list>
+    description: Basic range selection on list items.
+  - html: |
+      <aui-list traits="{ trait: 'range-select', selector: '.item', attr: 'selected' }">
+        <div class="item">A</div>
+        <div class="item">B</div>
+      </aui-list>
+    description: Custom selector and attribute for selection.