@agent-ui-kit/web-components 0.0.8 → 0.0.14

package/dist/docs/components/dropdown-menu.yaml

@@ -0,0 +1,146 @@
+name: aui-dropdown-menu
+tag: aui-dropdown-menu
+type: component
+summary: Trigger button + popover menu for actions (not selection).
+description: >
+  A dropdown menu that stamps a trigger button and opens a popover with
+  action items. Unlike aui-select, does not track selection state — items
+  are fire-and-forget actions that emit a select event. Supports label,
+  icon-leading, hide-label for icon-only triggers, and grouped items
+  via aui-optgroup. Keyboard accessible with arrow navigation, Enter to
+  select, and Escape to close.
+
+base: AgentElement
+
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Text label for the trigger button.
+  icon-leading:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Icon name for leading position in trigger.
+  icon-trailing:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Icon name for trailing position in trigger.
+  hide-label:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Visually hide the label text (keeps aria-label).
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction.
+  open:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the menu popover is currently open.
+
+tokens:
+  - name: --aui-dropdown-menu-font-family
+    default: var(--aui-font-family)
+    description: Font family for the trigger and menu items.
+  - name: --aui-dropdown-menu-font-size
+    default: var(--aui-font-size)
+    description: Font size for the trigger and menu items.
+  - name: --aui-dropdown-menu-font-weight
+    default: var(--aui-control-font-weight)
+    description: Font weight for the trigger label.
+  - name: --aui-dropdown-menu-color
+    default: var(--aui-ink)
+    description: Default text color.
+  - name: --aui-dropdown-menu-background
+    default: var(--aui-control, var(--aui-fill))
+    description: Background color of the trigger button.
+  - name: --aui-dropdown-menu-border-color
+    default: var(--aui-stroke)
+    description: Border color of the trigger button.
+  - name: --aui-dropdown-menu-border-radius
+    default: var(--aui-radius)
+    description: Border radius for the trigger and dropdown.
+  - name: --aui-dropdown-menu-size
+    default: var(--aui-size)
+    description: Height of the trigger button.
+  - name: --aui-dropdown-menu-padding-inline
+    default: var(--aui-pad-control-inline)
+    description: Inline padding for the trigger.
+  - name: --aui-dropdown-menu-gap
+    default: var(--aui-pad-gap-control)
+    description: Gap between trigger icon, label, and chevron.
+  - name: --aui-dropdown-menu-icon-size
+    default: var(--aui-icon-size)
+    description: Size of the chevron icon.
+  - name: --aui-dropdown-menu-chevron-color
+    default: var(--aui-ink-muted)
+    description: Color of the dropdown chevron.
+  - name: --aui-dropdown-menu-dropdown-background
+    default: var(--aui-modal, var(--aui-doc))
+    description: Background of the dropdown popover.
+  - name: --aui-dropdown-menu-dropdown-border-color
+    default: var(--aui-border-muted)
+    description: Border color of the dropdown popover.
+  - name: --aui-dropdown-menu-dropdown-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the dropdown popover.
+  - name: --aui-dropdown-menu-dropdown-shadow
+    default: var(--aui-shadow-lg)
+    description: Box shadow of the dropdown popover.
+
+a11y:
+  role: button (trigger), menu (popover)
+  keyboard:
+    ArrowDown: Open menu or navigate to next item.
+    ArrowUp: Open menu or navigate to previous item.
+    Enter: Open menu or select active item.
+    Space: Open menu or select active item.
+    Escape: Close menu and return focus to trigger.
+    Home: First item.
+    End: Last item.
+
+events:
+  select:
+    description: Fired when a menu item is activated. Detail contains { value }.
+
+dependencies:
+  - aui-option
+  - aui-optgroup
+
+composition:
+  parents: [aui-header, aui-footer, aui-stack, any]
+  children: [aui-option, aui-optgroup]
+
+examples:
+  - html: |
+      <aui-dropdown-menu label="Actions">
+        <aui-option value="edit">Edit</aui-option>
+        <aui-option value="duplicate">Duplicate</aui-option>
+        <aui-option value="delete">Delete</aui-option>
+      </aui-dropdown-menu>
+    description: Basic dropdown menu with labeled trigger.
+
+  - html: |
+      <aui-dropdown-menu label="Actions" ghost>
+        <aui-optgroup label="Edit">
+          <aui-option value="cut">Cut</aui-option>
+          <aui-option value="copy">Copy</aui-option>
+          <aui-option value="paste">Paste</aui-option>
+        </aui-optgroup>
+        <aui-optgroup label="Danger" divider>
+          <aui-option value="delete">Delete</aui-option>
+        </aui-optgroup>
+      </aui-dropdown-menu>
+    description: Ghost-style dropdown with grouped options.
+
+  - html: |
+      <aui-dropdown-menu label="Actions" disabled>
+        <aui-option value="edit">Edit</aui-option>
+      </aui-dropdown-menu>
+    description: Disabled dropdown menu.

package/dist/docs/components/hover-card.yaml

@@ -0,0 +1,85 @@
+name: aui-hover-card
+tag: aui-hover-card
+type: component
+summary: Rich preview card shown on hover/focus with configurable delay.
+description: >
+  A popover card that appears after a hover delay on an anchor element.
+  Uses the Popover API with CSS anchor positioning. The card stays visible
+  when the pointer moves into it, and hides after a leave delay. Supports
+  side placement (top/bottom/left/right) and custom show/hide delays.
+
+base: AgentElement
+
+attributes:
+  anchor:
+    syntax: key-value
+    type: string
+    default: ""
+    description: CSS selector for the anchor element. Falls back to previous sibling or parent.
+  delay:
+    syntax: key-value
+    type: string
+    default: "300"
+    description: Show delay in milliseconds after hover starts.
+  hide-delay:
+    syntax: key-value
+    type: string
+    default: "200"
+    description: Hide delay in milliseconds after hover ends.
+  side:
+    syntax: key-value
+    type: string
+    default: "bottom"
+    description: Preferred placement side — top, bottom, left, or right.
+
+modifiers:
+  open:
+    syntax: boolean
+    description: Whether the hover card is currently visible.
+
+tokens:
+  - name: --aui-hover-card-background
+    default: var(--aui-modal, var(--aui-doc))
+    description: Background color of the card.
+  - name: --aui-hover-card-border-color
+    default: var(--aui-border-muted)
+    description: Border color of the card.
+  - name: --aui-hover-card-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the card.
+  - name: --aui-hover-card-shadow
+    default: var(--aui-shadow-lg)
+    description: Box shadow of the card.
+  - name: --aui-hover-card-padding
+    default: calc(var(--aui-space) * 3)
+    description: Padding inside the card.
+  - name: --aui-hover-card-max-width
+    default: 20rem
+    description: Maximum width of the card.
+
+a11y:
+  role: tooltip (popover)
+  keyboard:
+    Escape: Close the hover card.
+
+events: {}
+
+composition:
+  parents: [any]
+  children: [any]
+
+examples:
+  - html: |
+      <span id="hc-anchor" style="text-decoration: underline; cursor: pointer; color: var(--aui-ink);">Hover over me</span>
+      <aui-hover-card anchor="#hc-anchor">
+        <aui-heading size="sm">Preview Card</aui-heading>
+        <aui-text muted>This is a rich hover preview with any content.</aui-text>
+      </aui-hover-card>
+    description: Basic hover card — hover to show, move pointer away to hide.
+
+  - html: |
+      <span id="hc-top" style="text-decoration: underline; cursor: pointer; color: var(--aui-ink);">Hover (top side)</span>
+      <aui-hover-card anchor="#hc-top" side="top" delay="200">
+        <aui-text>This card appears above the anchor.</aui-text>
+      </aui-hover-card>
+    description: Hover card positioned above the anchor with shorter delay.

package/dist/docs/components/index.yaml

@@ -212,10 +212,34 @@ aui-calendar:
   summary: Date picker with day, month, and year views.
   uses: [appointment booking, date-of-birth selector, event scheduler, date range filter]
 
+aui-calendar-picker:
+  summary: Compound date picker with trigger input and calendar popover.
+  uses: [date form field, booking date selector, filter bar date input, event date picker]
+  children: [aui-calendar]
+
+aui-calendar-range-picker:
+  summary: Compound date range picker with trigger input and calendar popover.
+  uses: [analytics date range filter, booking date range, reporting period selector, leave request form]
+  children: [aui-calendar]
+
 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-hover-card:
+  summary: Rich preview card shown on hover/focus with configurable delay.
+  uses: [user profile previews, link preview cards, rich tooltips, repository hover previews]
+
+aui-dropdown-menu:
+  summary: Trigger button + popover menu for actions (not selection).
+  uses: [table row action menus, toolbar overflow menus, card header actions, user profile menus]
+  children: [aui-option, aui-optgroup]
+
+aui-context-menu:
+  summary: Right-click triggered context menu using the Popover API.
+  uses: [data table row actions, file browser context menus, canvas right-click, list item operations]
+  children: [aui-option, aui-optgroup]
+
 aui-container:
   summary: Unified card and panel surface.
   uses: [settings form card, dashboard stat widget, profile detail panel, pricing tier card, clickable nav tile]
@@ -318,3 +342,147 @@ aui-divider:
 aui-kbd:
   summary: Keyboard shortcut indicator styled as a key cap.
   uses: [shortcut hint in tooltip, command palette key combo, documentation hotkey reference]
+
+aui-nav-item:
+  summary: Navigation list item with icon, label, badge, and active state.
+  uses: [sidebar navigation, app menu, settings nav, dashboard sidebar]
+
+aui-progress:
+  summary: Horizontal progress bar indicating completion or usage.
+  uses: [file upload progress, onboarding steps, storage usage, task completion]
+
+aui-stepper:
+  summary: Multi-step progress container with connector lines.
+  uses: [onboarding wizard, task timeline, workflow status, checkout steps]
+
+aui-step:
+  summary: Individual step within a stepper, with state-driven connector colors.
+  uses: [completed task, in-progress step, pending milestone]
+
+aui-sparkline:
+  summary: Compact inline bar chart for KPI widgets.
+  uses: [metric card trend, dashboard KPI, data table sparkline]
+
+aui-code-block:
+  summary: Code display with language header and copy button.
+  uses: [API documentation, code review, agent tool output, diff preview]
+
+aui-skeleton:
+  summary: Loading placeholder with shimmer animation.
+  uses: [avatar placeholder, text line placeholder, card loading state, list item skeleton]
+
+aui-alert:
+  summary: Contextual banner for status messages.
+  uses: [form validation error, save confirmation, system warning, inline notification]
+
+aui-link:
+  summary: Styled anchor for inline and standalone links.
+  uses: [navigation link, inline text reference, external site link, footer link]
+
+aui-spinner:
+  summary: Animated loading indicator.
+  uses: [button loading state, empty state loader, inline async feedback, page load indicator]
+
+aui-meter:
+  summary: Visual gauge for known-range scalar values.
+  uses: [disk usage bar, budget allocation, API rate limit, resource utilization]
+
+aui-chip:
+  summary: Compact pill-shaped label for tags, filters, and selected items.
+  uses: [tag input selected tags, filter bar tokens, member role labels, status indicators]
+
+aui-disclosure:
+  summary: Collapsible content section with animated expand/collapse.
+  uses: [FAQ sections, settings expandable groups, sidebar collapsible sections, form optional fields]
+
+aui-avatar-group:
+  summary: Overlapping avatar stack with automatic overflow counter.
+  uses: [contributor lists, team cards, member panels, PR reviewer display]
+
+aui-input-group:
+  summary: Wrapper that connects an input with prefix/suffix addons.
+  uses: [currency input, URL field, unit input, search with button suffix, domain configuration]
+
+aui-button-group:
+  summary: Groups buttons with shared or connected borders.
+  uses: [toolbar action groups, view mode toggles, split buttons, pagination controls, text alignment toggles]
+
+aui-fieldset:
+  summary: Groups form fields under a legend heading with consistent spacing.
+  uses: [multi-section forms, settings page groups, profile edit sections, admin config panels, wizard steps]
+
+aui-color-swatch:
+  summary: Color preview square with checkerboard transparency support.
+  uses: [color palette display, color field preview, swatch picker grid, theme color preview, saved color list]
+
+aui-progress-circle:
+  summary: Circular SVG ring progress indicator with value, size, and intent variants.
+  uses: [usage billing rings, dashboard KPI circles, upload progress, profile completion, plan limit indicators]
+
+aui-disclosure-group:
+  summary: Coordinates child disclosures with optional exclusive accordion mode.
+  uses: [FAQ accordion, settings expandable groups, sidebar collapsible sections, documentation sections]
+  children: [aui-disclosure]
+
+aui-tag-group:
+  summary: Keyboard-navigable container for aui-chip elements.
+  uses: [tag input fields, filter bars, multi-select displays, email recipient lists, category management]
+  children: [aui-chip]
+
+aui-color-area:
+  summary: 2D gradient surface for picking saturation and lightness at a given hue.
+  uses: [color picker compound, theme editor, design tool color selection, brand color configuration]
+
+aui-color-slider:
+  summary: Single-axis gradient slider for a color channel.
+  uses: [hue strip in color picker, individual channel adjustment, opacity/alpha control, HSL channel editors]
+
+aui-color-field:
+  summary: Text input for color values with inline swatch preview.
+  uses: [theme customization panels, design tool property inspectors, brand color forms, CSS variable editors]
+
+aui-color-picker:
+  summary: Compound color picker composing area, sliders, and field.
+  uses: [theme editor panels, design tool color selection, brand color configuration, settings with color customization]
+  children: [aui-color-area, aui-color-slider, aui-color-field]
+  uses: [theme customization panels, design tool property inspectors, brand color forms, CSS variable editors]
+
+aui-time-field:
+  summary: Segmented time input with independently editable hour and minute segments.
+  uses: [scheduling UIs, event creation forms, appointment booking, alarm settings, work hours configuration]
+
+aui-date-field:
+  summary: Segmented date input with independently editable month, day, and year segments.
+  uses: [inline date entry, birthdate fields, invoice date fields, expiration date entry, quick date filters]
+
+aui-file-upload:
+  summary: Drop zone with file list for drag-and-drop or click-to-browse file uploads.
+  uses: [profile image upload, document attachment, bulk CSV import, media library, message attachments]
+
+aui-copy-button:
+  summary: One-click copy button with visual check feedback.
+  uses: [code snippet copy, API key copy, URL sharing, terminal command copy, inline copy action]
+
+aui-stat:
+  summary: KPI display widget with label, value, trend arrow, and optional change text.
+  uses: [dashboard KPI card, analytics metric, revenue display, user count widget, performance indicator]
+
+aui-description-list:
+  summary: Key-value pair display using native dt/dd elements with grid layout.
+  uses: [profile detail panels, settings summaries, order detail pages, API response viewers, metadata displays]
+
+aui-image:
+  summary: Enhanced image with lazy loading, aspect ratio, fallback, and optional lightbox.
+  uses: [hero images, profile photos, gallery cards, content previews, product images]
+
+aui-carousel:
+  summary: Horizontal scrolling slides with CSS scroll-snap and navigation.
+  uses: [image galleries, feature tours, testimonial sliders, product showcases, onboarding steps]
+
+aui-notification-center:
+  summary: Persistent notification inbox with bell trigger, unread badge, and popover list.
+  uses: [app header toolbars, admin dashboard headers, SaaS app nav bars]
+
+aui-empty-state:
+  summary: Centered empty placeholder with icon, heading, description, and action slot.
+  uses: [empty tables, no-results search, first-use onboarding, empty inbox, zero-data dashboards]

package/dist/docs/components/input.yaml

@@ -130,6 +130,18 @@ attributes:
     default: ""
     description: Browser autocomplete hint. Forwarded to the native input.
 
+  debounce:
+    syntax: key-value
+    type: string
+    default: "200"
+    description: Debounce delay in ms for the search event. Only applies when type="search".
+
+  no-clear:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Hides the auto-stamped clear button. Only applies when type="search".
+
 # ── Modifiers ─────────────────────────────────────────────
 
 # None — clearable is a component attribute, not a modifier.
@@ -203,6 +215,10 @@ events:
     description: Fires on every keystroke. Value attribute syncs automatically.
   change:
     description: Fires on blur or enter. Bubbles from the native input.
+  search:
+    description: >
+      Debounced event fired after typing stops (type="search" only).
+      Detail contains { value: string }.
 
 # ── CSS implementation notes ──────────────────────────────
 
@@ -314,3 +330,12 @@ examples:
         <aui-input value="admin"></aui-input>
       </aui-field>
     description: Input with error state via parent field.
+
+  - html: <aui-input type="search" placeholder="Search..."></aui-input>
+    description: Search input with automatic leading icon and clear button.
+
+  - html: <aui-input type="search" placeholder="Search..." debounce="500"></aui-input>
+    description: Search input with custom 500ms debounce.
+
+  - html: <aui-input type="search" placeholder="Search..." no-clear></aui-input>
+    description: Search input without the clear button.

package/dist/docs/components/link.yaml

@@ -0,0 +1,85 @@
+name: aui-link
+tag: aui-link
+type: component
+summary: Styled anchor for inline and standalone links.
+description: >
+  Inline link element with consistent styling, hover underline,
+  and focus ring. Supports muted and intent coloring. External
+  attribute appends an arrow icon via CSS ::after pseudo-element.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: accent
+    values: [accent, success, warning, danger]
+    description: Link color family.
+
+# ── Modifiers ─────────────────────────────────────────────
+
+modifiers:
+  muted:
+    syntax: boolean
+    description: >
+      Uses muted text color instead of accent. Hover restores
+      full text color.
+
+  external:
+    syntax: boolean
+    description: >
+      Appends an external-link arrow icon via CSS ::after.
+      Indicates the link opens an external destination.
+
+# ── Attributes ────────────────────────────────────────────
+
+attributes:
+  href:
+    type: URL
+    required: false
+    description: Link destination URL.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: inline
+  accepts: [text, aui-icon]
+  required: true
+  description: >
+    Link label text. Keep concise — one to a few words.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [text, aui-icon]
+    required: true
+    description: Link label text.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  color:
+    - --aui-link-color
+    - --aui-link-color-hover
+  shape:
+    - --aui-link-radius
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-link href="/about">Learn more</aui-link>
+    description: Basic accent link.
+
+  - html: <aui-link href="https://example.com" external>Visit site</aui-link>
+    description: External link with arrow icon.
+
+  - html: |
+      <aui-text>
+        Read the <aui-link href="/terms">terms of service</aui-link> before continuing.
+      </aui-text>
+    description: Inline link within text flow.

package/dist/docs/components/meter.yaml

@@ -0,0 +1,89 @@
+name: aui-meter
+tag: aui-meter
+type: component
+summary: Visual gauge for known-range scalar values.
+description: >
+  Static measurement gauge within a known range. Fill width
+  driven by --aui-meter-pct CSS custom property computed from
+  value, min, and max attributes. Semantically distinct from
+  aui-progress — meters represent a static measurement (disk
+  usage, budget), not task completion. Intent colors indicate
+  threshold states.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: md
+    values: [sm, md, lg]
+    description: Track height — sm (4px), md (6px), lg (10px).
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: accent
+    values: [accent, success, warning, danger]
+    description: Fill color reflecting threshold state.
+
+# ── Attributes ────────────────────────────────────────────
+
+attributes:
+  value:
+    type: number
+    default: "0"
+    description: Current measurement value.
+  min:
+    type: number
+    default: "0"
+    description: Range minimum.
+  max:
+    type: number
+    default: "100"
+    description: Range maximum.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    No content — meter is a visual gauge only.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots: {}
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-meter-height
+  color:
+    - --aui-meter-background
+    - --aui-meter-fill
+  shape:
+    - --aui-meter-radius
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-meter value="45"></aui-meter>
+    description: Default accent meter at 45%.
+
+  - html: <aui-meter value="75" warning></aui-meter>
+    description: Warning meter at 75%.
+
+  - html: |
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-text size="xs" muted>Disk usage</aui-text>
+        <aui-meter value="82" warning style="flex: 1"></aui-meter>
+        <aui-text size="xs" muted>82%</aui-text>
+      </aui-stack>
+    description: Meter with context labels in a row.