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

package/dist/docs/components/tooltip.yaml

@@ -0,0 +1,98 @@
+name: aui-tooltip
+tag: aui-tooltip
+type: component
+summary: Hover/focus tooltip with popover-based positioning.
+description: >
+  A lightweight tooltip that appears on hover or focus of its anchor
+  element. Uses the Popover API for top-layer rendering and CSS
+  anchor positioning for placement. The anchor is auto-discovered
+  as the previous sibling element.
+
+base: AgentElement
+
+# ── Component attributes ──────────────────────────────────
+
+attributes:
+  content:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      The text content displayed inside the tooltip.
+
+  position:
+    syntax: key-value
+    type: enum
+    values: [top, bottom, left, right]
+    default: top
+    description: >
+      Preferred placement relative to the anchor element.
+      Uses CSS anchor positioning for layout.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    Content is set via the content attribute. The tooltip
+    stamps its own popover surface internally.
+
+# ── Composition ───────────────────────────────────────────
+
+composition:
+  parents: [any]
+  children: null
+  context: >
+    Place as a sibling immediately after the element you want
+    to annotate. The tooltip auto-discovers the previous sibling
+    as its anchor. Works with any interactive element.
+
+# ── Accessibility ─────────────────────────────────────────
+
+a11y:
+  role: tooltip (on the popover surface)
+  aria:
+    aria-describedby: Set on the anchor element, pointing to the tooltip.
+  keyboard:
+    Escape: Dismisses the tooltip.
+  focus:
+    description: >
+      Tooltip appears on focusin and disappears on focusout
+      of the anchor element.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  color:
+    - --aui-tooltip-ink
+    - --aui-tooltip-fill
+  shape:
+    - --aui-radius
+  motion:
+    - --aui-easing
+  typography:
+    - --aui-font-family
+  shadow:
+    - --aui-shadow-sm
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: |
+      <aui-button hide-label ghost label="Settings">
+        <aui-icon name="gear" slot="leading"></aui-icon>
+      </aui-button>
+      <aui-tooltip content="Settings" position="bottom"></aui-tooltip>
+    description: Tooltip on an hide-label button.
+
+  - html: |
+      <aui-button primary accent>Save</aui-button>
+      <aui-tooltip content="Save your changes (⌘S)"></aui-tooltip>
+    description: Tooltip with keyboard shortcut hint.
+
+  - html: |
+      <aui-icon name="info" label="Info"></aui-icon>
+      <aui-tooltip content="More information" position="right"></aui-tooltip>
+    description: Tooltip positioned to the right of an icon.

package/dist/docs/components/tree-item.yaml

@@ -0,0 +1,46 @@
+name: aui-tree-item
+tag: aui-tree-item
+type: component
+summary: Tree node with expand/collapse and nesting
+base: AgentElement
+attributes:
+  expanded:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether children are visible.
+  selected:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether this item is selected.
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction.
+a11y:
+  role: treeitem
+  keyboard:
+    Enter: Select/toggle item.
+    ArrowRight: Expand (if collapsed).
+    ArrowLeft: Collapse (if expanded).
+composition:
+  parents: [aui-tree, aui-tree-item]
+  children: [aui-tree-item]
+description: >
+  A tree node that supports expand/collapse and arbitrary nesting.
+  The caret indicator uses aui-icon name="caret-right" (rotated when
+  expanded) and is automatically stamped by the component.
+
+examples:
+  - html: |
+      <aui-tree>
+        <aui-tree-item expanded>
+          <span data-trigger>Parent node</span>
+          <aui-tree-item><span data-trigger>Child A</span></aui-tree-item>
+          <aui-tree-item selected><span data-trigger>Child B (selected)</span></aui-tree-item>
+          <aui-tree-item disabled><span data-trigger>Child C (disabled)</span></aui-tree-item>
+        </aui-tree-item>
+      </aui-tree>
+    description: Tree with expanded parent and child items showing selected and disabled states.

package/dist/docs/components/tree.yaml

@@ -0,0 +1,27 @@
+name: aui-tree
+tag: aui-tree
+type: component
+summary: Hierarchical tree view with expand/collapse
+base: AgentElement
+a11y:
+  role: tree
+  keyboard:
+    ArrowDown: Focus next visible item.
+    ArrowUp: Focus previous visible item.
+composition:
+  parents: [any]
+  children: [aui-tree-item]
+examples:
+  - html: |
+      <aui-tree>
+        <aui-tree-item expanded>
+          <span data-trigger>Documents</span>
+          <aui-tree-item><span data-trigger>report.pdf</span></aui-tree-item>
+          <aui-tree-item><span data-trigger>notes.txt</span></aui-tree-item>
+        </aui-tree-item>
+        <aui-tree-item>
+          <span data-trigger>Images</span>
+          <aui-tree-item><span data-trigger>photo.jpg</span></aui-tree-item>
+        </aui-tree-item>
+      </aui-tree>
+    description: File tree with nested folders.

package/dist/docs/traits/auto-dismiss.yaml

@@ -0,0 +1,23 @@
+name: auto-dismiss
+type: trait
+category: present
+summary: Automatically hides the host after a configurable timeout.
+description: >
+  Sets a countdown timer that hides the host element after the specified
+  delay. Exposes the remaining time as a data attribute updated each second.
+  Pauses the timer on pointer hover. Useful for toasts, notifications,
+  and transient alerts.
+config:
+  - delay: Time in milliseconds before auto-dismiss (default '3000')
+events:
+  - dismiss: Fires when the element is auto-dismissed
+exposes:
+  - data-auto-dismiss-remaining: Countdown in milliseconds, updated each second
+  - data-auto-dismiss-dismissed: Present after the element has been dismissed
+examples:
+  - html: |
+      <aui-badge traits="auto-dismiss">Notification</aui-badge>
+    description: Basic auto-dismiss after 3 seconds.
+  - html: |
+      <aui-badge traits="{ trait: 'auto-dismiss', delay: '5000' }">Slower toast</aui-badge>
+    description: Auto-dismiss after 5 seconds.

package/dist/docs/traits/backtick-wrap.yaml

@@ -0,0 +1,22 @@
+name: backtick-wrap
+type: trait
+category: state
+summary: Auto-wraps selected text in backticks on backtick keypress.
+description: >
+  Listens for the backtick key on the host element. When text is selected,
+  wraps it in single backticks for inline selections or triple backticks
+  for multi-line selections. Works with both contenteditable and native
+  input/textarea elements.
+
+config: []
+
+events:
+  - name: backtick-wrap
+    description: Fires after wrapping, with detail containing the original text and wrapped result.
+
+exposes: []
+
+examples:
+  - html: |
+      <aui-editor traits="backtick-wrap">Select text and press backtick</aui-editor>
+    description: Basic usage on an editor element.

package/dist/docs/traits/clipboard.yaml

@@ -0,0 +1,31 @@
+name: clipboard
+type: trait
+category: state
+summary: Handles paste events, parsing clipboard data into structured components.
+description: >
+  Listens for paste events on the host and extracts text, HTML, and file
+  data from the clipboard. Filters content by configurable MIME type
+  accept patterns (supports wildcards like image/*). Emits a paste event
+  with the structured data and exposes a has-data state after paste.
+config:
+  - name: accept
+    type: string
+    default: "text/plain,text/html,image/*"
+    description: Comma-separated MIME types to accept.
+  - name: prevent
+    type: string
+    default: "true"
+    description: Prevent default paste behavior ('true' | 'false').
+events:
+  - name: paste
+    description: Fires on paste, detail contains text, html, files, and types.
+exposes:
+  - name: data-clipboard-has-data
+    description: Present after a paste event has been processed.
+examples:
+  - html: |
+      <aui-editor traits="clipboard">Paste here</aui-editor>
+    description: Basic clipboard paste handler.
+  - html: |
+      <aui-editor traits="{ trait: 'clipboard', accept: 'text/plain' }">Plain text only</aui-editor>
+    description: Only accepts plain text pastes.

package/dist/docs/traits/collapsible.yaml

@@ -0,0 +1,23 @@
+name: collapsible
+type: trait
+category: present
+summary: Toggles host height between collapsed and expanded states with CSS transitions.
+description: >
+  Animates the host element between a collapsed (max-height: 0) and expanded state
+  using CSS transitions on max-height. Responds to press events to toggle, and
+  exposes the collapsed boolean as a data attribute. Configurable initial state
+  and transition duration.
+config:
+  - collapsed: Initial collapsed state ('true' | 'false', default 'false')
+  - duration: Transition duration in milliseconds (default '200')
+events:
+  - press: Triggers toggle between collapsed and expanded
+exposes:
+  - data-collapsible-collapsed: Boolean indicating whether the element is collapsed
+examples:
+  - html: |
+      <aui-panel traits="collapsible">Content here</aui-panel>
+    description: Basic collapsible panel, starts expanded.
+  - html: |
+      <aui-panel traits="{ trait: 'collapsible', collapsed: 'true', duration: '300' }">Content here</aui-panel>
+    description: Starts collapsed with a 300ms transition.

package/dist/docs/traits/confetti.yaml

@@ -0,0 +1,37 @@
+name: confetti
+type: trait
+category: effect
+summary: Bursts confetti particles from the host on press.
+description: >
+  Spawns colorful confetti particles that fly outward from the center
+  of the host element when a press event fires. Uses CSS animations
+  for particle movement and rotation with no JS animation frames.
+  Particles auto-remove on animationend.
+
+config:
+  - name: count
+    type: string
+    default: "30"
+    description: Number of confetti particles to spawn per burst.
+  - name: spread
+    type: string
+    default: "60"
+    description: Angular spread in degrees for the particle cone.
+  - name: duration
+    type: string
+    default: "800"
+    description: Animation duration in milliseconds for each particle.
+
+events: []
+
+exposes: []
+
+examples:
+  - html: |
+      <aui-button traits="confetti">Celebrate</aui-button>
+    description: Basic confetti burst on press.
+  - html: |
+      <aui-button traits="{ trait: 'confetti', count: '50', spread: '90' }">
+        Big celebration
+      </aui-button>
+    description: Dense confetti with wider spread.

package/dist/docs/traits/copy.yaml

@@ -0,0 +1,27 @@
+name: copy
+type: trait
+category: state
+summary: Copies text to clipboard on press with visual feedback.
+description: >
+  On press, copies the configured text (or the host's textContent) to
+  the clipboard using the Clipboard API. Shows a brief feedback state
+  then restores after a duration.
+config:
+  - name: text
+    type: string
+    default: ""
+    description: Text to copy (default uses host's textContent).
+  - name: feedback
+    type: string
+    default: "1500"
+    description: Duration of feedback window in milliseconds.
+events:
+  - name: copy-success
+    description: Fires after successful copy with { text } detail.
+exposes:
+  - name: data-copy-copied
+    description: Present during the feedback window after a copy.
+examples:
+  - html: |
+      <aui-button traits="copy">Copy this text</aui-button>
+    description: Basic copy button using textContent.

package/dist/docs/traits/css-inspect.yaml

@@ -0,0 +1,46 @@
+name: css-inspect
+type: trait
+category: effect
+summary: 3D exploded view of the DOM tree for visual debugging.
+description: >
+  Toggles on press to create a 3D exploded view of the host's DOM tree.
+  Each level of children is pushed along the Z axis with perspective
+  transforms. Configurable depth, spread distance, and tilt angles.
+  Visual styles like outlines and transitions are handled via CSS.
+
+config:
+  - name: depth
+    type: string
+    default: "3"
+    description: Maximum depth of children to transform.
+  - name: spread
+    type: string
+    default: "40"
+    description: Pixels between each depth level along the Z axis.
+  - name: tilt-x
+    type: string
+    default: "15"
+    description: Degrees of X-axis rotation when active.
+  - name: tilt-y
+    type: string
+    default: "30"
+    description: Degrees of Y-axis rotation when active.
+
+events: []
+
+exposes:
+  - name: data-css-inspect-active
+    description: Present and set to "true" while the inspect view is active.
+
+examples:
+  - html: |
+      <aui-panel traits="css-inspect">
+        <div>Child 1</div>
+        <div>Child 2</div>
+      </aui-panel>
+    description: Basic usage toggled via press event.
+  - html: |
+      <aui-panel traits="{ trait: 'css-inspect', depth: '5', spread: '60' }">
+        <div>Deep inspect</div>
+      </aui-panel>
+    description: Custom depth and spread configuration.

package/dist/docs/traits/dismiss.yaml

@@ -0,0 +1,23 @@
+name: dismiss
+type: trait
+category: present
+summary: Closes the host on Escape key or outside click.
+description: >
+  Listens for Escape keydown and pointer events outside the host element,
+  emitting a configurable dismiss event when triggered. Both triggers can
+  be independently enabled or disabled. Useful for popover, dropdown, and
+  overlay dismiss patterns.
+config:
+  - escape: Enable Escape key dismiss ('true' | 'false', default 'true')
+  - outside: Enable outside click dismiss ('true' | 'false', default 'true')
+  - event: Custom event name to emit on dismiss (default 'dismiss')
+events:
+  - dismiss: Fires when dismiss is triggered (configurable name)
+exposes: []
+examples:
+  - html: |
+      <aui-popover traits="dismiss">Dismissible content</aui-popover>
+    description: Basic usage with both Escape and outside click.
+  - html: |
+      <aui-popover traits="{ trait: 'dismiss', outside: 'false' }">Escape only</aui-popover>
+    description: Dismiss only on Escape key.

package/dist/docs/traits/drag.yaml

@@ -0,0 +1,88 @@
+name: drag
+type: trait
+category: gesture
+summary: Composable pointer-driven drag-and-drop with drop, slot, and preview modes.
+description: >
+  Three modes: drop (outlines the target element), slot (shows a gap indicator
+  between items for insertion), and preview (live DOM reordering). Set zoneSelector
+  to enable cross-zone dragging (e.g., kanban boards). Ghost renders in the top
+  layer via popover. Press Escape to cancel.
+
+config:
+  - name: selector
+    type: string
+    default: ""
+    description: CSS selector for draggable items within the host. Required.
+  - name: drop-zone-selector
+    type: string
+    default: ""
+    description: CSS selector for drop zones. Defaults to selector items if empty.
+  - name: zone-selector
+    type: string
+    default: ""
+    description: CSS selector for zone containers (e.g., kanban columns). Enables cross-zone dragging.
+  - name: axis
+    type: string
+    default: "both"
+    description: Constrains hit-testing to 'vertical', 'horizontal', or 'both'. Ghost always moves freely.
+  - name: mode
+    type: string
+    default: "drop"
+    description: >
+      'drop' outlines hovered target. 'slot' shows gap indicator.
+      'preview' moves the real item in real time (no consumer reordering needed).
+  - name: animate
+    type: string
+    default: "true"
+    description: Enable view-transition animation for preview mode grid reordering.
+
+events:
+  - name: drag-start
+    description: Fired on first pointer move. Detail { item, index }.
+  - name: drag-move
+    description: Fired on every pointer move during drag. Detail { item, x, y }.
+  - name: drag-over
+    description: Fired when the target or insertion position changes.
+  - name: drop
+    description: Fired on pointer up. Detail includes item, fromIndex, toIndex, insertBefore (slot), target (drop), sourceZone, targetZone.
+  - name: drag-cancel
+    description: Fired when Escape is pressed or pointer is cancelled. Detail { item }.
+
+exposes:
+  - name: "[dragging]"
+    description: Present on the dragged item while dragging.
+  - name: "[drag-over]"
+    description: Present on drop target (drop mode).
+  - name: "[drag-slot-before]"
+    description: Item immediately after insertion gap (slot mode).
+  - name: "[drag-slot-after]"
+    description: Item immediately before insertion gap (slot mode).
+  - name: "[drag-zone-active]"
+    description: Zone the ghost is currently over (cross-zone mode).
+
+examples:
+  - html: |
+      <div traits="{ trait: 'drag', selector: '.drag-item', axis: 'vertical', mode: 'drop' }">
+        <div class="drag-item">Design mockups</div>
+        <div class="drag-item">Write component API</div>
+        <div class="drag-item">Implement CSS</div>
+      </div>
+    description: Drop mode — outlines hovered target for swap.
+  - html: |
+      <div traits="{ trait: 'drag', selector: '.drag-item', axis: 'vertical', mode: 'slot' }">
+        <div class="drag-item">Research</div>
+        <div class="drag-item">Prototype</div>
+        <div class="drag-item">Build</div>
+        <div class="drag-item">Test</div>
+        <div class="drag-item">Ship</div>
+      </div>
+    description: Slot mode — shows gap indicator between items.
+  - html: |
+      <div traits="{ trait: 'drag', selector: '.grid-cell', axis: 'both', mode: 'preview' }">
+        <div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 0.5rem;">
+          <div class="grid-cell">1</div>
+          <div class="grid-cell">2</div>
+          <div class="grid-cell">3</div>
+        </div>
+      </div>
+    description: Preview mode — live DOM reordering with view transitions.

package/dist/docs/traits/drop-zone.yaml

@@ -0,0 +1,37 @@
+name: drop-zone
+type: trait
+category: state
+summary: Makes the host a drag-and-drop target for files and data.
+description: >
+  Handles dragover, dragenter, dragleave, and drop events on the host
+  element. Validates dropped content against configurable accepted MIME
+  type patterns. Exposes an over state while dragging over the host and
+  emits a drop event with files, items, and text on successful drop.
+
+config:
+  - name: accept
+    type: string
+    default: "*"
+    description: Comma-separated MIME type patterns to accept (e.g., "image/*,text/plain").
+  - name: overlay
+    type: string
+    default: "true"
+    description: Whether to show a visual overlay during drag-over.
+
+events:
+  - name: drop
+    description: Fires on successful drop with detail containing files, items, and text.
+
+exposes:
+  - name: data-drop-zone-over
+    description: Present and set to "true" while dragging over the host.
+
+examples:
+  - html: |
+      <aui-panel traits="drop-zone">Drop files here</aui-panel>
+    description: Basic drop zone accepting all file types.
+  - html: |
+      <aui-panel traits="{ trait: 'drop-zone', accept: 'image/*,text/plain' }">
+        Drop images or text
+      </aui-panel>
+    description: Drop zone restricted to images and plain text.

package/dist/docs/traits/edit.yaml

@@ -0,0 +1,39 @@
+name: edit
+type: trait
+category: state
+summary: Inline edit mode with commit and cancel support.
+description: >
+  Makes the host content-editable on a configurable activation event
+  (default: dblclick). Commits the edit on blur or Enter depending on
+  configuration, and cancels on Escape restoring original text. Emits
+  edit-commit and edit-cancel events with value details.
+
+config:
+  - name: event
+    type: string
+    default: "dblclick"
+    description: DOM event that activates edit mode.
+  - name: commit
+    type: string
+    default: "blur"
+    description: Trigger for committing the edit ("blur" or "enter").
+
+events:
+  - name: edit-commit
+    description: Fires on commit with detail containing value and previous text.
+  - name: edit-cancel
+    description: Fires when the edit is cancelled via Escape.
+
+exposes:
+  - name: data-edit-editing
+    description: Present while the host is in edit mode.
+
+examples:
+  - html: |
+      <aui-label traits="edit">Double-click to edit</aui-label>
+    description: Basic inline editing with double-click activation.
+  - html: |
+      <aui-label traits="{ trait: 'edit', event: 'dblclick', commit: 'enter' }">
+        Edit me
+      </aui-label>
+    description: Edit mode that commits on Enter instead of blur.

package/dist/docs/traits/flip.yaml

@@ -0,0 +1,40 @@
+name: flip
+type: trait
+category: effect
+summary: 3D card flip animation toggled on press.
+description: >
+  Toggles a 3D flip state on the host element when a press event fires.
+  The host should contain two children representing the front and back
+  faces. All visual styling (perspective, transforms, backface-visibility,
+  transitions) is handled in companion CSS. The JS only toggles the
+  data-flip-flipped attribute.
+
+config:
+  - name: duration
+    type: string
+    default: "600"
+    description: Flip animation duration in milliseconds.
+  - name: direction
+    type: string
+    default: "horizontal"
+    description: Flip axis — "horizontal" rotates around Y, "vertical" rotates around X.
+
+events: []
+
+exposes:
+  - name: data-flip-flipped
+    description: Set to "true" when the card is flipped, "false" when showing the front face.
+
+examples:
+  - html: |
+      <aui-card traits="flip">
+        <div class="front">Front</div>
+        <div class="back">Back</div>
+      </aui-card>
+    description: Basic horizontal flip card.
+  - html: |
+      <aui-card traits="{ trait: 'flip', direction: 'vertical', duration: '400' }">
+        <div class="front">Front</div>
+        <div class="back">Back</div>
+      </aui-card>
+    description: Vertical flip with a faster animation.

package/dist/docs/traits/gateway.yaml

@@ -0,0 +1,33 @@
+name: gateway
+type: trait
+category: present
+summary: DOM portal that moves host children to a target container.
+description: >
+  Moves the host element's children to a target container elsewhere in
+  the DOM (default: body). Restores children to their original position
+  on detach. Useful for overlays, modals, and tooltips that need to
+  escape stacking context or overflow constraints.
+
+config:
+  - name: target
+    type: string
+    default: "body"
+    description: CSS selector for the destination container.
+
+events: []
+
+exposes:
+  - name: data-gateway-active
+    description: Present and set to "true" while children are portaled.
+
+examples:
+  - html: |
+      <aui-overlay traits="gateway">
+        <div>Portaled content</div>
+      </aui-overlay>
+    description: Basic usage portaling children to body.
+  - html: |
+      <aui-overlay traits="{ trait: 'gateway', target: '#portal-root' }">
+        <div>Custom target</div>
+      </aui-overlay>
+    description: Portal to a specific container element.