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

package/dist/docs/components/index.yaml

@@ -0,0 +1,320 @@
+# ── Components ──────────────────────────────────
+
+aui-button:
+  summary: Polymorphic action trigger (button) with press semantics.
+  uses: [form submit, toolbar action, hide-label close button, link-mode nav, CTA in pricing card]
+  children: [aui-icon]
+
+aui-icon:
+  summary: SVG icon rendered from a global registry.
+  uses: [button leading icon, nav menu item, status indicator in toast, toolbar glyph, decorative illustration]
+
+aui-input:
+  summary: Text input with type variants, slots, and clearable mode.
+  uses: [email login field, search bar with clear, password entry, inline cell editor, URL input]
+
+aui-textarea:
+  summary: Multi-line text input with autogrow support.
+  uses: [comment box, chat message composer, bio field in profile, feedback form, code snippet editor]
+
+aui-select:
+  summary: Universal collection surface — dropdown, toolbar, listbox, and combobox in one element.
+  uses: [country picker dropdown, toolbar overflow menu, sidebar nav list, combobox search filter, multi-select tag picker]
+  children: [aui-option, aui-optgroup, aui-select]
+  modes: [bar, list, combobox]
+
+aui-option:
+  summary: Selectable item within aui-select.
+  uses: [dropdown menu entry, toolbar action, listbox row, combobox suggestion]
+
+aui-optgroup:
+  summary: Groups related options with an optional label and divider.
+  uses: [categorized dropdown sections, grouped combobox results, toolbar divider groups]
+  children: [aui-option]
+
+aui-checkbox:
+  summary: Checkbox with custom check and indeterminate indicators.
+  uses: [terms acceptance toggle, bulk-select all in table, survey multi-choice, todo item, filter panel option]
+
+aui-switch:
+  summary: Toggle switch with track and sliding thumb.
+  uses: [dark mode toggle, notification preference, feature flag in settings, auto-save toggle]
+
+aui-radio:
+  summary: Radio button with custom circle indicator.
+  uses: [shipping method choice, plan tier selection, sort order option]
+
+aui-radio-group:
+  summary: Container that coordinates radio button selection.
+  uses: [plan selection in pricing, payment method chooser, frequency toggle in settings]
+  children: [aui-radio]
+
+aui-field:
+  summary: Form field wrapper with label, description, and error.
+  uses: [labeled login input, settings form row, registration field with validation, inline error display]
+  children: [aui-input, aui-textarea, aui-select, aui-checkbox, aui-switch, aui-radio-group]
+
+aui-tooltip:
+  summary: Hover/focus tooltip with popover-based positioning.
+  uses: [hide-label button hint, keyboard shortcut callout, truncated text reveal, toolbar action label]
+
+aui-range:
+  summary: Slider control with custom track and thumb.
+  uses: [volume control, price range filter, opacity adjuster, font size slider]
+
+aui-input-otp:
+  summary: Segmented one-time password input.
+  uses: [two-factor auth code, phone verification, invite code entry, PIN confirmation]
+
+aui-gripper:
+  summary: Resize handle for panes and resizable containers.
+  uses: [IDE panel divider, split-view separator, resizable sidebar edge, code/preview splitter]
+
+aui-tabs:
+  summary: Tabbed interface with roving keyboard navigation.
+  uses: [settings page sections, dashboard view switcher, product detail tabs, code/preview toggle]
+  children: [aui-tab, aui-tab-panel]
+
+aui-tab:
+  summary: Individual tab trigger within a tabbed interface.
+  uses: [settings section label, dashboard tab header, detail view selector]
+
+aui-tab-panel:
+  summary: Content panel associated with a tab.
+  uses: [settings section body, dashboard tab content, detail view pane]
+
+aui-accordion:
+  summary: Collapsible section group with optional single-open mode.
+  uses: [FAQ page, settings category groups, sidebar filter sections, changelog entries]
+  children: [aui-accordion-item]
+
+aui-accordion-item:
+  summary: Collapsible section with trigger and content panel.
+  uses: [FAQ answer reveal, filter group collapse, advanced settings toggle, sidebar section]
+
+aui-segmented-control:
+  summary: Toggle between mutually exclusive options.
+  uses: [list/grid/board view switcher, billing period toggle, codespaces/local tab bar]
+  children: [aui-segment]
+
+aui-segment:
+  summary: Individual toggle within a segmented control.
+  uses: [view mode option, billing period choice, tab-like segment]
+
+aui-pagination:
+  summary: Page navigation with numbered buttons and prev/next.
+  uses: [table page controls, search results paging, blog post navigation, gallery pagination]
+
+aui-toast:
+  summary: Toast notification with auto-dismiss and stacking.
+  uses: [save confirmation, error alert after failed request, new message notification, copy-to-clipboard feedback]
+
+aui-breadcrumb:
+  summary: Breadcrumb navigation trail.
+  uses: [file manager path, settings hierarchy, e-commerce category trail, documentation breadcrumb]
+  children: [aui-breadcrumb-item]
+
+aui-breadcrumb-item:
+  summary: Individual breadcrumb link or current-page indicator.
+  uses: [parent folder link, category link, current page marker]
+
+aui-command:
+  summary: Command palette with search, keyboard navigation, and grouping.
+  uses: [app-wide quick actions, file search overlay, admin action launcher, keyboard-driven navigation]
+  children: [aui-command-input, aui-command-list, aui-command-empty]
+
+aui-command-input:
+  summary: Search input for the command palette.
+  uses: [command search box, action filter field]
+
+aui-command-list:
+  summary: Scrollable container for command items.
+  uses: [command results panel, action list viewport]
+  children: [aui-command-item, aui-command-group]
+
+aui-command-group:
+  summary: Groups command items under a heading.
+  uses: [categorized actions section, navigation group in palette]
+  children: [aui-command-item]
+
+aui-command-item:
+  summary: Selectable item within a command palette.
+  uses: [quick action entry, search result row, keyboard-navigable option]
+
+aui-command-empty:
+  summary: Empty state shown when no command items match the query.
+  uses: [no-results feedback in command palette, search miss message]
+
+aui-panes:
+  summary: Resizable split layout with draggable grippers.
+  uses: [IDE editor/preview split, email list/detail pane, file browser/content split]
+  children: [aui-pane, aui-gripper]
+
+aui-pane:
+  summary: Individual pane within a resizable split layout.
+  uses: [sidebar panel, main content region, detail inspector pane]
+
+aui-table:
+  summary: CSS grid table with subgrid rows.
+  uses: [user admin list, invoice line items, API key management, data export preview]
+  children: [aui-table-head, aui-table-body]
+
+aui-table-head:
+  summary: Table head section using display contents.
+  children: [aui-table-row]
+
+aui-table-body:
+  summary: Table body section using display contents.
+  children: [aui-table-row]
+
+aui-table-row:
+  summary: Table row using CSS subgrid.
+  children: [aui-table-header, aui-table-cell]
+
+aui-table-header:
+  summary: Column header cell with bold label.
+  uses: [sortable column title, fixed header cell]
+
+aui-table-cell:
+  summary: Data cell within a table row.
+  uses: [user name cell, status badge cell, action button cell]
+
+aui-tree:
+  summary: Hierarchical tree view with expand/collapse.
+  uses: [file explorer sidebar, org chart, nested settings menu, category taxonomy browser]
+  children: [aui-tree-item]
+
+aui-tree-item:
+  summary: Tree node with expand/collapse and nesting.
+  uses: [folder node, file leaf, nested category item]
+  children: [aui-tree-item]
+
+aui-feed:
+  summary: Scrollable feed for messages and activity streams.
+  uses: [chat message thread, activity log, notification feed, comment stream]
+
+aui-drawer:
+  summary: Slide-out panel anchored to a viewport edge.
+  uses: [mobile nav menu, filter sidebar, detail inspector, notification tray]
+  children: [aui-header, aui-content, aui-footer]
+
+aui-dialog:
+  summary: Modal dialog with backdrop and focus trapping.
+  uses: [delete confirmation prompt, edit profile form, command palette host, session expired alert]
+  children: [aui-header, aui-content, aui-footer]
+
+aui-root:
+  summary: App shell root container.
+  uses: [top-level app wrapper, theme provider boundary, full-page layout host]
+  children: [aui-header, aui-content, aui-footer, aui-panes]
+
+aui-calendar:
+  summary: Date picker with day, month, and year views.
+  uses: [appointment booking, date-of-birth selector, event scheduler, date range filter]
+
+aui-noodles:
+  summary: Declarative SVG noodle canvas for node-based flow editors.
+  uses: [data pipeline diagram, CI/CD workflow builder, state machine editor, API integration mapper]
+
+aui-container:
+  summary: Unified card and panel surface.
+  uses: [settings form card, dashboard stat widget, profile detail panel, pricing tier card, clickable nav tile]
+  children: [aui-header, aui-content, aui-footer, aui-inset]
+
+aui-canvas:
+  summary: Versatile preview surface with pan/zoom, backgrounds, and editor layout slots.
+  uses: [component preview renderer, infinite whiteboard, flow editor viewport, design tool workspace]
+
+# ── Agent Chat Components ──────────────────────
+
+aui-agent-panel:
+  summary: Top-level chat shell that composes header, feed, and input.
+  uses: [full chat interface, conversational AI panel, support chat window, agent workspace shell]
+  children: [aui-header, aui-agent-feed, aui-agent-input, aui-footer]
+
+aui-agent-feed:
+  summary: Scrollable chat thread coordinator with auto-scroll and token definitions.
+  uses: [chat message thread, conversational AI interface, support chat window, agent conversation log]
+  children: [aui-agent-thread]
+
+aui-agent-thread:
+  summary: Message group with 2x2 grid layout for avatar, context, and bubbles.
+  uses: [message cluster from one sender, assistant response group, user message group]
+  children: [aui-avatar, aui-agent-message]
+
+aui-agent-message:
+  summary: Individual chat message bubble with action toolbar.
+  uses: [assistant response bubble, user message bubble, system notification bubble]
+  children: [aui-agent-text, aui-agent-activity, aui-agent-seeds]
+
+aui-agent-text:
+  summary: Markdown renderer for chat message content.
+  uses: [rich text assistant response, plain text user message, formatted code explanation]
+
+aui-agent-activity:
+  summary: Streaming activity indicator with typing dots and elapsed timer.
+  uses: [thinking indicator, typing animation, tool-use status, reasoning trace display]
+
+aui-agent-seeds:
+  summary: Suggestion chips for pre-seeded quick responses.
+  uses: [conversation starters, quick reply options, follow-up suggestions]
+
+aui-agent-input:
+  summary: Chat composer surface with textarea, submit button, and keyboard shortcuts.
+  uses: [chat message input, agent prompt composer, conversation reply box]
+  children: [aui-textarea, aui-agent-prompt, aui-button]
+
+aui-agent-prompt:
+  summary: Bordered prompt container for the chat composer textarea.
+  uses: [advanced composer layout, bordered textarea wrapper, rich input surface]
+  children: [aui-textarea, aui-button]
+
+# ── Elements (CSS-only, no JS) ──────────────────
+
+aui-stack:
+  summary: Flex column or row layout container.
+  uses: [vertical form layout, horizontal button group, card content stacking, wrapping tag row]
+
+aui-grid:
+  summary: CSS grid container with column shorthand.
+  uses: [dashboard card grid, two-column form fields, image gallery, pricing tier row]
+
+aui-inset:
+  summary: Density-aware padding wrapper.
+  uses: [card content padding, dialog body spacing, scrollable area inset, section content margin]
+
+aui-header:
+  summary: Adaptive grid container for top bars.
+  uses: [page title bar, card header with actions, dialog title row, drawer top bar]
+
+aui-footer:
+  summary: Adaptive grid container for bottom bars.
+  uses: [dialog action buttons, card save/cancel row, page copyright line, pagination bar]
+
+aui-content:
+  summary: Scrollable content region that fills available space.
+  uses: [dialog scrollable body, drawer main content, card middle section, sidebar scrollable list]
+
+aui-heading:
+  summary: Block-level heading text with size and weight attributes.
+  uses: [page title, card heading, stat value label, section title, profile name]
+
+aui-text:
+  summary: Block-level text element with muted and size attributes.
+  uses: [card subtitle, form field description, timestamp label, secondary metadata, empty state message]
+
+aui-badge:
+  summary: Status indicator with intent colors and dot mode.
+  uses: [notification count, plan tier label, online presence dot, PR status tag, version label]
+
+aui-avatar:
+  summary: Avatar circle or square showing initials or image.
+  uses: [user profile photo, team member row, comment author, workspace icon, nav brand mark]
+
+aui-divider:
+  summary: Semantic separator line.
+  uses: [section break in settings, toolbar group separator, form section divider, list item border]
+
+aui-kbd:
+  summary: Keyboard shortcut indicator styled as a key cap.
+  uses: [shortcut hint in tooltip, command palette key combo, documentation hotkey reference]

package/dist/docs/components/input-otp.yaml

@@ -0,0 +1,59 @@
+name: aui-input-otp
+tag: aui-input-otp
+type: component
+summary: Segmented one-time password input.
+description: >
+  A multi-cell input for one-time codes. Auto-advances on entry,
+  navigates on backspace/arrows, and distributes pasted values
+  across cells. A hidden input holds the combined value for forms.
+
+base: AgentElement
+
+attributes:
+  length:
+    syntax: key-value
+    type: string
+    default: "6"
+    description: Number of digit cells to render.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Current combined value.
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form field name.
+
+a11y:
+  role: group
+  aria:
+    aria-label: '"One-time code" on the container.'
+  keyboard:
+    ArrowLeft: Move to previous cell.
+    ArrowRight: Move to next cell.
+    Backspace: Clear current cell and move to previous.
+
+events:
+  aui:complete:
+    description: Fired when all cells are filled. detail.value contains the code.
+
+form:
+  associated: true
+  value: Combined string of all cells.
+
+examples:
+  - html: <aui-input-otp length="6"></aui-input-otp>
+    description: Default 6-digit OTP input.
+
+  - html: <aui-input-otp length="4" name="code"></aui-input-otp>
+    description: 4-digit OTP with form name.

package/dist/docs/components/input.yaml

@@ -0,0 +1,289 @@
+name: aui-input
+tag: aui-input
+type: component
+summary: Text input with type variants, slots, and clearable mode.
+description: >
+  Single-line text input. The wrapper element owns the visual chrome
+  (border, radius, padding, focus ring). A native <input> lives
+  inside as a light DOM child with all browser chrome stripped.
+  Supports leading/trailing icon slots and a clearable button.
+  Defaults to width: 20ch for standalone use. Automatically stretches
+  to full width when placed inside aui-field. Use width="full" on the
+  element to override the default width in other contexts.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: Controls height, font size, and icon size.
+
+  radius:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: medium
+    values: [sharp, round]
+    description: Controls border radius.
+
+  density:
+    syntax: key-value
+    attribute: density
+    cascades: true
+    default: regular
+    values: [compact, spacious]
+    description: Controls padding compression.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values: [accent, info, success, warning, danger]
+    description: Color family for the input border and focus ring.
+
+# ── Component attributes ──────────────────────────────────
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+
+  readonly:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Allows selection but prevents editing. Dashed border.
+
+  required:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Marks the input as required for form validation.
+
+  clearable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Shows a clear button when the input has a value.
+
+  autofocus:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Focuses the input on mount.
+
+  type:
+    syntax: key-value
+    type: enum
+    values: [text, email, password, search, url, tel, number]
+    default: text
+    description: HTML input type. Forwarded to the native input.
+
+  placeholder:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Placeholder text. Forwarded to the native input.
+
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Current input value. Two-way synced with the native input.
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form submission name. Forwarded to the native input.
+
+  pattern:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Regex validation pattern. Forwarded to the native input.
+
+  minlength:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Minimum character count.
+
+  maxlength:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Maximum character count.
+
+  autocomplete:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Browser autocomplete hint. Forwarded to the native input.
+
+# ── Modifiers ─────────────────────────────────────────────
+
+# None — clearable is a component attribute, not a modifier.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: mixed
+  accepts: [input, span, svg, button]
+  required: false
+  description: >
+    The component auto-stamps a native <input> if none exists.
+    Slot elements (leading/trailing) are optional. Do not place
+    block elements inside.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [input]
+    required: false
+    description: >
+      The native input element. Auto-stamped if not provided.
+
+  leading:
+    accepts: [span, svg, img]
+    required: false
+    description: Leading icon. Adapts grid to auto 1fr.
+
+  trailing:
+    accepts: [span, svg, img]
+    required: false
+    description: Trailing icon. Adapts grid to 1fr auto.
+
+# ── Composition ───────────────────────────────────────────
+
+composition:
+  parents: [aui-field, aui-stack, aui-grid, form, div]
+  children: null
+  context: >
+    Use inside aui-field for labeled form inputs. Can also be
+    used standalone in search bars, inline editors, or compact
+    toolbars. The wrapper is the styling surface — the inner
+    input is a plain native element.
+
+# ── Constraints ───────────────────────────────────────────
+
+constraints:
+  - when: inside aui-field
+    require: aui-field[label]
+    reason: >
+      Inputs need an accessible label. When used inside aui-field,
+      the field provides the label. When standalone, add aria-label.
+
+# ── Accessibility ─────────────────────────────────────────
+
+a11y:
+  role: implicit (native input)
+  keyboard:
+    Tab: Focuses the native input.
+    Escape: Clears the input (when clearable and focused).
+  aria:
+    aria-disabled: Reflected from disabled attribute.
+    aria-readonly: Reflected from readonly attribute.
+    aria-required: Reflected from required attribute.
+
+# ── Events ────────────────────────────────────────────────
+
+events:
+  input:
+    description: Fires on every keystroke. Value attribute syncs automatically.
+  change:
+    description: Fires on blur or enter. Bubbles from the native input.
+
+# ── CSS implementation notes ──────────────────────────────
+
+css-notes:
+  attr-audit:
+    - "AB1: [disabled], [readonly], [clearable] — all visual states via attributes"
+    - "AB5: No classes used — all state is attribute-driven"
+    - ":focus-within on wrapper — delegates focus ring to the container"
+    - ":has(> [slot='leading']) — slot-adaptive grid, same pattern as button"
+    - ":not(:has(> input:not(:placeholder-shown))) — hides clear button when empty"
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-font-size
+    - --aui-icon-size
+  spacing:
+    - --aui-pad-control-block
+    - --aui-pad-control-inline
+  color:
+    - --aui-ink
+    - --aui-ink-muted
+    - --aui-ink-placeholder
+    - --aui-ink-disabled
+    - --aui-control
+    - --aui-fill
+    - --aui-fill-disabled
+    - --aui-stroke
+    - --aui-stroke-hover
+    - --aui-stroke-disabled
+    - --aui-focus
+  shape:
+    - --aui-radius
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-input placeholder="Enter text"></aui-input>
+    description: Basic text input.
+
+  - html: <aui-input type="email" placeholder="you@example.com"></aui-input>
+    description: Email input.
+
+  - html: <aui-input type="password" placeholder="Password"></aui-input>
+    description: Password input.
+
+  - html: <aui-input placeholder="Search" clearable></aui-input>
+    description: Clearable input with clear button.
+
+  - html: <aui-input placeholder="Disabled" disabled></aui-input>
+    description: Disabled input.
+
+  - html: <aui-input value="Read only" readonly></aui-input>
+    description: Read-only input with dashed border.
+
+  - html: |
+      <aui-input placeholder="Search">
+        <span slot="leading">🔍</span>
+      </aui-input>
+    description: Input with leading icon.
+
+  - html: |
+      <aui-input type="email" placeholder="Email">
+        <span slot="leading">✉</span>
+        <span slot="trailing">✓</span>
+      </aui-input>
+    description: Input with leading and trailing icons.
+
+  - html: |
+      <aui-field label="Email" required>
+        <aui-input type="email" placeholder="you@example.com"></aui-input>
+      </aui-field>
+    description: Input inside a labeled field.
+
+  - html: |
+      <aui-field label="Username" error="Already taken.">
+        <aui-input value="admin"></aui-input>
+      </aui-field>
+    description: Input with error state via parent field.