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

package/dist/docs/components/chip.yaml

@@ -0,0 +1,91 @@
+name: aui-chip
+tag: aui-chip
+type: component
+summary: Compact pill-shaped label for tags, filters, and selected items.
+description: >
+  Inline pill element for tags, filter tokens, and selected items.
+  Supports intent colors via boolean attributes and a removable
+  variant that stamps a close button and dispatches a remove event.
+
+base: AgentElement
+
+# -- Component attributes ------------------------------------------
+
+attributes:
+  removable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Stamps an X close button. Clicking it dispatches a "remove"
+      CustomEvent (bubbles) and removes the element from the DOM.
+
+# -- Presentational attributes -------------------------------------
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: default
+    values: [sm]
+    description: Compact variant with smaller padding and font.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: neutral
+    values: [accent, success, warning, danger]
+    description: Tinted background and text color.
+
+# -- Content model -------------------------------------------------
+
+content:
+  model: inline
+  accepts: [text, aui-icon]
+  required: true
+  description: >
+    Short label text. May include a leading aui-icon. Keep concise.
+
+# -- Slots ---------------------------------------------------------
+
+slots:
+  default:
+    accepts: [text, aui-icon]
+    required: true
+    description: Chip label. Icons allowed before text.
+
+# -- Composition ---------------------------------------------------
+
+composition:
+  parents: [aui-stack, aui-wrap, div, span]
+  children: [aui-icon]
+  context: >
+    Inline element. Group chips in aui-stack direction="row" or
+    aui-wrap. Used inside tag inputs, filter bars, member labels.
+
+# -- Examples ------------------------------------------------------
+
+examples:
+  - html: <aui-chip>TypeScript</aui-chip>
+    description: Default chip.
+
+  - html: <aui-chip accent>Active</aui-chip>
+    description: Accent intent chip.
+
+  - html: <aui-chip success>Deployed</aui-chip>
+    description: Success intent chip.
+
+  - html: <aui-chip removable>React</aui-chip>
+    description: Removable chip with close button.
+
+  - html: <aui-chip size="sm">Small</aui-chip>
+    description: Compact size variant.
+
+  - html: |
+      <aui-chip>
+        <aui-icon name="tag" size="xs"></aui-icon>
+        Label
+      </aui-chip>
+    description: Chip with leading icon.

package/dist/docs/components/code-block.yaml

@@ -0,0 +1,126 @@
+name: aui-code-block
+tag: aui-code-block
+type: component
+summary: Fenced code block with optional language header, filename, and copy button.
+description: >
+  Wraps an aui-code element with an optional header bar showing a language
+  label, filename, and copy-to-clipboard button. Text content placed
+  directly inside is automatically wrapped in an aui-code child. The header
+  is stamped by JS when language, filename, or copyable attributes are
+  present. The copy button writes the code text to the clipboard via the
+  Clipboard API.
+
+base: AgentElement
+
+# ── Component attributes ──────────────────────────────────
+
+attributes:
+  language:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Programming language label shown in the header bar.
+      Also useful for syntax-highlighting integrations.
+
+  filename:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Filename shown in the header bar. Takes precedence over
+      language for the displayed label.
+
+  copyable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      When present, shows a "Copy" button in the header bar.
+      Clicking copies the code content to the clipboard.
+
+  max-height:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      CSS max-height applied to the code body. When set, the code
+      area becomes scrollable if content overflows.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: text
+  accepts: [text, aui-code]
+  required: true
+  description: >
+    Code text content. Plain text is automatically wrapped in an
+    aui-code element by JS. An explicit aui-code child is also accepted.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  - name: --aui-code-block-background
+    default: var(--aui-control)
+    description: Header background color.
+  - name: --aui-code-block-border
+    default: var(--aui-border-muted)
+    description: Border color for the outer container and header divider.
+  - name: --aui-code-block-border-radius
+    default: var(--aui-radius)
+    description: Corner radius of the outer container.
+  - name: --aui-code-block-header-font-size
+    default: var(--aui-font-xs)
+    description: Font size of the header label text.
+  - name: --aui-code-block-header-color
+    default: var(--aui-ink-muted)
+    description: Text color of the header label.
+  - name: --aui-code-block-header-padding
+    default: calc(var(--aui-space) * 2) calc(var(--aui-space) * 3)
+    description: Padding inside the header bar.
+  - name: --aui-code-block-copy-color
+    default: var(--aui-ink-muted)
+    description: Copy button text color.
+  - name: --aui-code-block-copy-color-hover
+    default: var(--aui-ink)
+    description: Copy button text color on hover.
+
+# ── Accessibility ─────────────────────────────────────────
+
+a11y:
+  role: figure
+  aria:
+    aria-label: Set from language or filename when present.
+
+# ── Use cases ─────────────────────────────────────────────
+
+use-cases:
+  - Code snippets in documentation pages.
+  - Chat message code blocks in agent conversations.
+  - Copyable terminal commands.
+  - File previews with filename headers.
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: |
+      <aui-code-block language="typescript">
+      export function normalize(tokens: string[]) {
+        return tokens.map(t => t.trim())
+      }
+      </aui-code-block>
+    description: Code block with language header.
+
+  - html: |
+      <aui-code-block language="python" filename="main.py" copyable>
+      import pandas as pd
+      df = pd.read_csv("data.csv")
+      print(df.head())
+      </aui-code-block>
+    description: Code block with filename and copy button.
+
+  - html: |
+      <aui-code-block>
+      npm install @agent-ui-kit/web-components
+      </aui-code-block>
+    description: Plain code block without header.

package/dist/docs/components/color-picker.yaml

@@ -0,0 +1,78 @@
+name: aui-color-picker
+tag: aui-color-picker
+type: component
+summary: Compound color picker composing area, sliders, and field.
+description: >
+  A unified color picker that stamps and syncs aui-color-area,
+  aui-color-slider (hue + optional alpha), and aui-color-field
+  sub-components. All sub-components sync bidirectionally — changing
+  any part updates the others. Parses and serializes hex color values
+  internally, converting to/from HSL for the area and slider controls.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: "#000000"
+    description: Current color value in hex format.
+  format:
+    syntax: key-value
+    type: string
+    default: "hex"
+    description: Display format for the color field (hex, rgb, oklch).
+  show-alpha:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Show the alpha transparency slider.
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Disables all sub-components.
+
+tokens:
+  - name: --aui-color-picker-gap
+    default: calc(var(--aui-space) * 2)
+    description: Gap between sub-components.
+  - name: --aui-color-picker-area-height
+    default: 10rem
+    description: Height of the color area surface.
+  - name: --aui-color-picker-width
+    default: 14rem
+    description: Width of the entire picker.
+
+a11y:
+  role: group
+  keyboard:
+    ArrowKeys: Control the active sub-component (area, slider, or field).
+
+events:
+  change:
+    description: >
+      Fired when the color changes via any sub-component.
+      Detail contains { value, h, s, l, a }.
+
+dependencies:
+  - aui-color-area
+  - aui-color-slider
+  - aui-color-field
+
+composition:
+  parents: [aui-container, any]
+  children: []
+
+examples:
+  - html: |
+      <aui-color-picker value="#3b82f6"></aui-color-picker>
+    description: Basic color picker with initial blue value.
+
+  - html: |
+      <aui-color-picker value="#ef444480" show-alpha></aui-color-picker>
+    description: Color picker with alpha transparency slider.
+
+  - html: |
+      <aui-color-picker value="#10b981" disabled></aui-color-picker>
+    description: Disabled color picker.

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

@@ -0,0 +1,102 @@
+name: aui-context-menu
+tag: aui-context-menu
+type: component
+summary: Right-click triggered context menu using the Popover API.
+description: >
+  Declarative context menu that listens for contextmenu events on a target
+  element and positions a popover at the pointer location. Reuses aui-option
+  for menu items and aui-optgroup for grouped sections. Supports keyboard
+  navigation with arrow keys, Enter to select, and Escape to close.
+
+base: AgentElement
+
+attributes:
+  target:
+    syntax: key-value
+    type: string
+    default: ""
+    description: CSS selector for the element to attach the contextmenu listener to. Falls back to parent element.
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents the menu from opening.
+  open:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the menu is currently open.
+
+tokens:
+  - name: --aui-context-menu-font-family
+    default: var(--aui-font-family)
+    description: Font family for menu items.
+  - name: --aui-context-menu-font-size
+    default: var(--aui-font-size)
+    description: Font size for menu items.
+  - name: --aui-context-menu-color
+    default: var(--aui-ink)
+    description: Text color for menu items.
+  - name: --aui-context-menu-background
+    default: var(--aui-modal, var(--aui-doc))
+    description: Background color of the menu.
+  - name: --aui-context-menu-border-color
+    default: var(--aui-border-muted)
+    description: Border color of the menu.
+  - name: --aui-context-menu-border-radius
+    default: var(--aui-radius)
+    description: Border radius of the menu.
+  - name: --aui-context-menu-shadow
+    default: var(--aui-shadow-lg)
+    description: Box shadow of the menu.
+
+a11y:
+  role: menu
+  keyboard:
+    ArrowDown: Move to next menu item.
+    ArrowUp: Move to previous menu item.
+    Home: Move to first menu item.
+    End: Move to last menu item.
+    Enter: Select the active menu item.
+    Space: Select the active menu item.
+    Escape: Close the menu.
+
+events:
+  select:
+    description: Fired when a menu item is selected. Detail contains { value }.
+
+dependencies:
+  - aui-option
+  - aui-optgroup
+
+composition:
+  parents: [any]
+  children: [aui-option, aui-optgroup]
+
+examples:
+  - html: |
+      <div id="ctx-target" style="padding: 2rem; border: 1px dashed var(--aui-border-muted); border-radius: var(--aui-radius); text-align: center; color: var(--aui-ink-muted);">
+        Right-click here
+      </div>
+      <aui-context-menu target="#ctx-target">
+        <aui-option value="edit">Edit</aui-option>
+        <aui-option value="duplicate">Duplicate</aui-option>
+        <aui-option value="delete">Delete</aui-option>
+      </aui-context-menu>
+    description: Basic context menu — right-click the target area to open.
+
+  - html: |
+      <div id="ctx-grouped" style="padding: 2rem; border: 1px dashed var(--aui-border-muted); border-radius: var(--aui-radius); text-align: center; color: var(--aui-ink-muted);">
+        Right-click for grouped menu
+      </div>
+      <aui-context-menu target="#ctx-grouped">
+        <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-context-menu>
+    description: Context menu with grouped options.

package/dist/docs/components/date-field.yaml

@@ -0,0 +1,115 @@
+name: aui-date-field
+tag: aui-date-field
+type: component
+summary: Segmented date input with independently editable month, day, and year segments.
+description: >
+  An inline date entry control where month, day, and year are
+  separate focusable segments. Segment order and separator are
+  determined by the format attribute (MM/DD/YYYY, DD/MM/YYYY,
+  YYYY-MM-DD). Each segment supports arrow-key increment/decrement,
+  direct digit entry with auto-advance, and Tab/Arrow navigation.
+  Validates dates on commit (e.g. Feb 30 clamps to Feb 28/29).
+  Value is always stored as ISO YYYY-MM-DD. No native form elements.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Date value in ISO format (YYYY-MM-DD).
+
+  min:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Earliest allowed date (YYYY-MM-DD).
+
+  max:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Latest allowed date (YYYY-MM-DD).
+
+  format:
+    syntax: key-value
+    type: string
+    default: "MM/DD/YYYY"
+    description: Segment display order (MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD).
+
+  placeholder:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Placeholder shown in empty segments.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+
+a11y:
+  role: spinbutton (on each segment)
+  keyboard:
+    ArrowUp: Increment focused segment.
+    ArrowDown: Decrement focused segment.
+    ArrowLeft: Move to previous segment.
+    ArrowRight: Move to next segment.
+    Tab: Move between segments.
+    "0-9": Digit entry with auto-advance.
+    Backspace: Clear segment.
+  aria:
+    aria-label: Segment name (Month, Day, Year).
+    aria-valuemin: Segment minimum.
+    aria-valuemax: Segment maximum.
+
+tokens:
+  - name: --aui-date-field-background
+    default: var(--aui-control, var(--aui-fill))
+    description: Field background.
+  - name: --aui-date-field-border
+    default: var(--aui-stroke)
+    description: Field border color.
+  - name: --aui-date-field-border-radius
+    default: var(--aui-radius)
+    description: Field corner radius.
+  - name: --aui-date-field-border-hover
+    default: var(--aui-stroke-hover)
+    description: Border on hover.
+  - name: --aui-date-field-border-focus
+    default: var(--aui-focus)
+    description: Border when focused.
+  - name: --aui-date-field-font-size
+    default: var(--aui-font-sm)
+    description: Text size.
+  - name: --aui-date-field-color
+    default: var(--aui-ink)
+    description: Text color.
+  - name: --aui-date-field-segment-bg-focus
+    default: var(--aui-accent-100)
+    description: Focused segment background.
+  - name: --aui-date-field-segment-color-focus
+    default: var(--aui-accent-700)
+    description: Focused segment text color.
+
+composition:
+  parents: [aui-field, aui-stack, aui-container, div]
+  children: []
+  context: >
+    Standalone date entry for inline forms. Use inside aui-field
+    for labeled forms. For full calendar popup, use aui-calendar-picker.
+
+examples:
+  - html: <aui-date-field value="2026-03-21"></aui-date-field>
+    description: Default MM/DD/YYYY date field.
+
+  - html: <aui-date-field value="2026-03-21" format="DD/MM/YYYY"></aui-date-field>
+    description: European DD/MM/YYYY format.
+
+  - html: <aui-date-field value="2026-03-21" format="YYYY-MM-DD"></aui-date-field>
+    description: ISO format.
+
+  - html: <aui-date-field value="2026-03-21" disabled></aui-date-field>
+    description: Disabled date field.

package/dist/docs/components/disclosure-group.yaml

@@ -0,0 +1,69 @@
+name: aui-disclosure-group
+tag: aui-disclosure-group
+type: component
+summary: Coordinates child aui-disclosure elements with optional exclusive (accordion) mode.
+description: >
+  Groups multiple aui-disclosure children. When the exclusive attribute
+  is present, opening one disclosure automatically closes all siblings,
+  creating accordion behavior. Without exclusive, all disclosures can
+  be open independently. Uses a MutationObserver to detect open
+  attribute changes on child disclosures.
+
+base: AgentElement
+
+# -- Component attributes ---------------------------------------------
+
+attributes:
+  exclusive:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      When set, only one child disclosure can be open at a time.
+      Opening a disclosure closes all siblings.
+
+# -- Content model -----------------------------------------------------
+
+content:
+  model: block
+  accepts: [aui-disclosure]
+  required: true
+  description: >
+    One or more aui-disclosure children. The group coordinates
+    their open/close state.
+
+# -- Composition -------------------------------------------------------
+
+composition:
+  parents: [aui-stack, aui-content, aui-inset, div]
+  children: [aui-disclosure]
+  context: >
+    Block-level element. Contains aui-disclosure children.
+    Use inside stacks, content areas, or sidebars.
+
+# -- Examples ----------------------------------------------------------
+
+examples:
+  - html: |
+      <aui-disclosure-group>
+        <aui-disclosure summary="Section 1"><p>Content 1</p></aui-disclosure>
+        <aui-disclosure summary="Section 2"><p>Content 2</p></aui-disclosure>
+      </aui-disclosure-group>
+    description: Independent disclosure group (all can be open).
+
+  - html: |
+      <aui-disclosure-group exclusive>
+        <aui-disclosure summary="General" open><p>General settings...</p></aui-disclosure>
+        <aui-disclosure summary="Security"><p>Security settings...</p></aui-disclosure>
+        <aui-disclosure summary="Notifications"><p>Notification prefs...</p></aui-disclosure>
+      </aui-disclosure-group>
+    description: Exclusive accordion mode.
+
+# -- Use cases ---------------------------------------------------------
+
+use-cases:
+  - FAQ pages with accordion behavior.
+  - Settings panels with grouped expandable sections.
+  - Sidebar navigation with collapsible groups.
+  - Documentation with expandable sections.
+  - Form sections with progressive disclosure.

package/dist/docs/components/disclosure.yaml

@@ -0,0 +1,81 @@
+name: aui-disclosure
+tag: aui-disclosure
+type: component
+summary: Collapsible content section with animated expand/collapse.
+description: >
+  Standalone collapsible section with a clickable trigger row.
+  Stamps a button with the summary text and a chevron icon. Content
+  height animates via CSS grid-template-rows transition. Toggle the
+  open attribute to expand or collapse programmatically.
+
+base: AgentElement
+
+# -- Component attributes ------------------------------------------
+
+attributes:
+  summary:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Text displayed in the trigger row header.
+
+  open:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Whether the content is expanded. Toggle to open/close.
+
+# -- Content model -------------------------------------------------
+
+content:
+  model: block
+  accepts: [any]
+  required: true
+  description: >
+    The collapsible content. Can contain any elements — forms,
+    stacks, text, nested disclosures, etc.
+
+# -- Slots ---------------------------------------------------------
+
+slots:
+  default:
+    accepts: [any]
+    required: true
+    description: Content revealed when open.
+
+# -- Composition ---------------------------------------------------
+
+composition:
+  parents: [aui-stack, aui-content, aui-inset, div]
+  children: [any]
+  context: >
+    Block-level element. Nest inside stacks, content areas, or
+    sidebars. Supports nesting (disclosure inside disclosure).
+
+# -- Examples ------------------------------------------------------
+
+examples:
+  - html: |
+      <aui-disclosure summary="More details">
+        <p>Hidden content revealed on click.</p>
+      </aui-disclosure>
+    description: Basic collapsed disclosure.
+
+  - html: |
+      <aui-disclosure summary="Advanced Settings" open>
+        <aui-stack gap="3">
+          <p>Setting A</p>
+          <p>Setting B</p>
+        </aui-stack>
+      </aui-disclosure>
+    description: Initially open disclosure.
+
+  - html: |
+      <aui-disclosure summary="Section A">
+        <aui-disclosure summary="Sub-section A.1">
+          Nested content.
+        </aui-disclosure>
+      </aui-disclosure>
+    description: Nested disclosures.