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

package/dist/docs/components/content.yaml

@@ -0,0 +1,100 @@
+name: aui-content
+tag: aui-content
+type: element
+summary: Scrollable content region that fills available space.
+description: >
+  Flex child that grows to fill remaining space in a flex column
+  container. Clips vertical overflow with scroll. Typically used
+  between aui-header and aui-footer to create a scrollable content
+  area within a fixed-height layout.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: block
+  accepts: [aui-inset, aui-stack, aui-grid, div, section, p, any]
+  required: true
+  description: >
+    Block-level content. Wrap in aui-inset for consistent padding.
+    Content that exceeds the available height will scroll vertically.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [any]
+    required: true
+    description: Scrollable body content.
+
+# ── Composition ───────────────────────────────────────────
+
+composition:
+  parents: [aui-stack, div, section]
+  siblings:
+    typical: [aui-header, aui-footer]
+    pattern: >
+      aui-content sits between aui-header and aui-footer in a
+      vertical flex container. The parent must have a constrained
+      height (explicit height or flex layout) for scrolling
+      to work — aui-content grows to fill remaining space.
+  children:
+    typical: [aui-inset, aui-stack, aui-grid]
+    pattern: >
+      Wrap content in aui-inset for consistent padding. Direct
+      children are laid out in a flex column.
+  context: >
+    The key structural element for scrollable layouts. Without
+    a constrained parent, aui-content simply grows without scrolling.
+
+# ── Attributes ────────────────────────────────────────────
+
+attributes:
+  scroll-shadow:
+    type: boolean
+    default: absent
+    description: >
+      Enables gradient mask at scroll edges to hint that more content
+      exists above or below. Only takes effect when `scrollable` is also
+      present. Uses CSS mask-image — no JS required. Horizontal variant
+      activates when `scrollable="x"` is set alongside `scroll-shadow`.
+
+# ── Constraints ───────────────────────────────────────────
+
+constraints:
+  - when: always
+    require: parent with constrained height
+    reason: >
+      aui-content uses flex-grow: 1 and overflow-y: auto. Without a
+      height constraint on the parent, it will grow indefinitely
+      and never scroll.
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: |
+      <div style="height: 150px; display: flex; flex-direction: column; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-header>
+          <span>Title</span>
+        </aui-header>
+        <aui-content>
+          <aui-inset>
+            <p>Line 1</p><p>Line 2</p><p>Line 3</p>
+            <p>Line 4</p><p>Line 5</p><p>Line 6</p>
+          </aui-inset>
+        </aui-content>
+      </div>
+    description: Scrollable body below a header in a fixed-height container.
+
+  - html: |
+      <div style="height: 150px; display: flex; flex-direction: column; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-header>
+          <span>Title</span>
+        </aui-header>
+        <aui-content scrollable scroll-shadow>
+          <aui-inset>
+            <p>Line 1</p><p>Line 2</p><p>Line 3</p>
+            <p>Line 4</p><p>Line 5</p><p>Line 6</p>
+          </aui-inset>
+        </aui-content>
+      </div>
+    description: Scroll shadow fades top and bottom edges to indicate overflow.

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

@@ -0,0 +1,93 @@
+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:
+  - description: Basic context menu — right-click the target area to open
+    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: Context menu with grouped options
+    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>

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

@@ -0,0 +1,163 @@
+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:
+  - description: Default date field (MM/DD/YYYY)
+    html: <aui-date-field value="2026-03-21"></aui-date-field>
+  - description: Another date
+    html: |-
+      <aui-date-field value="2026-12-25"></aui-date-field>
+
+      <!-- ===============================================================
+           FORMATS
+           =============================================================== -->
+  - description: DD/MM/YYYY format
+    html: <aui-date-field value="2026-03-21" format="DD/MM/YYYY"></aui-date-field>
+  - description: ISO format (YYYY-MM-DD)
+    html: |-
+      <aui-date-field value="2026-03-21" format="YYYY-MM-DD"></aui-date-field>
+
+      <!-- ===============================================================
+           EMPTY STATE
+           =============================================================== -->
+  - description: Empty date field (segments show --/----)
+    html: |-
+      <aui-date-field></aui-date-field>
+
+      <!-- ===============================================================
+           DISABLED
+           =============================================================== -->
+  - description: Disabled date field
+    html: |-
+      <aui-date-field value="2026-03-21" disabled></aui-date-field>
+
+      <!-- ===============================================================
+           IN FORM FIELD
+           =============================================================== -->
+  - description: Date field inside aui-field with label
+    html: |-
+      <aui-field label="Date of Birth">
+        <aui-date-field></aui-date-field>
+      </aui-field>
+  - description: Date field with min/max constraints
+    html: |-
+      <aui-field label="Appointment Date">
+        <aui-date-field value="2026-03-21" min="2026-01-01" max="2026-12-31"></aui-date-field>
+      </aui-field>
+
+      <!-- ===============================================================
+           ROW -- multiple date fields
+           =============================================================== -->
+  - description: Start and end date fields
+    html: |-
+      <aui-stack direction="row" gap="3">
+        <aui-field label="Check-in">
+          <aui-date-field value="2026-06-15"></aui-date-field>
+        </aui-field>
+        <aui-field label="Check-out">
+          <aui-date-field value="2026-06-20"></aui-date-field>
+        </aui-field>
+      </aui-stack>
+
+      <!-- ===============================================================
+           ALL FORMATS SIDE BY SIDE
+           =============================================================== -->
+  - description: All three format variants
+    html: |-
+      <aui-stack gap="3">
+        <aui-field label="US Format (MM/DD/YYYY)">
+          <aui-date-field value="2026-03-21" format="MM/DD/YYYY"></aui-date-field>
+        </aui-field>
+        <aui-field label="EU Format (DD/MM/YYYY)">
+          <aui-date-field value="2026-03-21" format="DD/MM/YYYY"></aui-date-field>
+        </aui-field>
+        <aui-field label="ISO Format (YYYY-MM-DD)">
+          <aui-date-field value="2026-03-21" format="YYYY-MM-DD"></aui-date-field>
+        </aui-field>
+      </aui-stack>

package/dist/docs/components/description-list.yaml

@@ -0,0 +1,81 @@
+name: Description List
+tag: aui-description-list
+type: css-only
+summary: Key-value pair display using native dt/dd elements with grid layout.
+attributes:
+  direction:
+    type: enum
+    values:
+      - row
+      - column
+    default: row
+    description: Layout direction of term/description pairs
+  striped:
+    type: boolean
+    description: Alternating background on pairs
+usage: |
+  <aui-description-list>
+    <dt>Name</dt>
+    <dd>Jane Doe</dd>
+    <dt>Role</dt>
+    <dd>Engineer</dd>
+  </aui-description-list>
+examples:
+  - description: Basic key-value description list
+    html: |-
+      <aui-description-list>
+        <dt>Name</dt>
+        <dd>Jane Doe</dd>
+        <dt>Role</dt>
+        <dd>Engineer</dd>
+        <dt>Email</dt>
+        <dd>jane@example.com</dd>
+        <dt>Location</dt>
+        <dd>San Francisco, CA</dd>
+      </aui-description-list>
+
+      <!-- ===============================================================
+           COLUMN DIRECTION
+           =============================================================== -->
+  - description: Column direction (stacked term above description)
+    html: |-
+      <aui-description-list direction="column">
+        <dt>Status</dt>
+        <dd>Active</dd>
+        <dt>Plan</dt>
+        <dd>Professional</dd>
+        <dt>Billing</dt>
+        <dd>Monthly</dd>
+      </aui-description-list>
+
+      <!-- ===============================================================
+           STRIPED
+           =============================================================== -->
+  - description: Striped rows for easier scanning
+    html: |-
+      <aui-description-list striped>
+        <dt>Created</dt>
+        <dd>2024-01-15</dd>
+        <dt>Updated</dt>
+        <dd>2024-03-21</dd>
+        <dt>Owner</dt>
+        <dd>Kim Granlund</dd>
+        <dt>Version</dt>
+        <dd>2.1.0</dd>
+      </aui-description-list>
+
+      <!-- ===============================================================
+           STRIPED + ROW
+           =============================================================== -->
+  - description: Striped row layout (default direction)
+    html: |-
+      <aui-description-list striped>
+        <dt>API Key</dt>
+        <dd>sk_live_abc123def456</dd>
+        <dt>Endpoint</dt>
+        <dd>https://api.example.com/v2</dd>
+        <dt>Rate Limit</dt>
+        <dd>1,000 requests/min</dd>
+        <dt>Last Used</dt>
+        <dd>2 hours ago</dd>
+      </aui-description-list>

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

@@ -0,0 +1,88 @@
+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
+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: block
+  accepts:
+    - aui-disclosure
+  required: true
+  description: |
+    One or more aui-disclosure children. The group coordinates their open/close state.
+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:
+  - description: Independent disclosure group
+    html: |-
+      <aui-disclosure-group>
+        <aui-disclosure summary="Section 1">
+          <p>Content for section 1. All sections can be open simultaneously.</p>
+        </aui-disclosure>
+        <aui-disclosure summary="Section 2">
+          <p>Content for section 2. Independent of other sections.</p>
+        </aui-disclosure>
+        <aui-disclosure summary="Section 3">
+          <p>Content for section 3. Toggle freely.</p>
+        </aui-disclosure>
+      </aui-disclosure-group>
+
+      <!-- ===============================================================
+           EXCLUSIVE -- accordion mode
+           =============================================================== -->
+  - description: Exclusive accordion mode
+    html: |-
+      <aui-disclosure-group exclusive>
+        <aui-disclosure summary="General" open>
+          <p>General settings content. Opening another section will close this one.</p>
+        </aui-disclosure>
+        <aui-disclosure summary="Security">
+          <p>Security settings content. Only one section open at a time.</p>
+        </aui-disclosure>
+        <aui-disclosure summary="Notifications">
+          <p>Notification preferences. Accordion enforces single-open.</p>
+        </aui-disclosure>
+      </aui-disclosure-group>
+
+      <!-- ===============================================================
+           FAQ STYLE -- exclusive with more sections
+           =============================================================== -->
+  - description: FAQ-style accordion
+    html: |-
+      <aui-disclosure-group exclusive>
+        <aui-disclosure summary="What is agent-ui?">
+          <p>A design system for building agent interfaces with web components.</p>
+        </aui-disclosure>
+        <aui-disclosure summary="How do I install it?">
+          <p>Install via npm: npm install @agent-ui/kit</p>
+        </aui-disclosure>
+        <aui-disclosure summary="Is it open source?">
+          <p>Yes, agent-ui is released under the MIT license.</p>
+        </aui-disclosure>
+        <aui-disclosure summary="Can I use it with React?">
+          <p>Yes, web components work with any framework including React, Vue, and Svelte.</p>
+        </aui-disclosure>
+      </aui-disclosure-group>
+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,95 @@
+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
+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: block
+  accepts:
+    - any
+  required: true
+  description: |
+    The collapsible content. Can contain any elements — forms, stacks, text, nested disclosures, etc.
+slots:
+  default:
+    accepts:
+      - any
+    required: true
+    description: Content revealed when open.
+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:
+  - description: Basic collapsed disclosure
+    html: |-
+      <aui-disclosure summary="More details">
+        <p>Hidden content revealed on click. Click the trigger row to expand.</p>
+      </aui-disclosure>
+
+      <!-- ===============================================================
+           INITIALLY OPEN
+           =============================================================== -->
+  - description: Initially open disclosure
+    html: |-
+      <aui-disclosure summary="Advanced Settings" open>
+        <aui-stack gap="3">
+          <p>Setting A: Timeout configuration</p>
+          <p>Setting B: Retry policy</p>
+        </aui-stack>
+      </aui-disclosure>
+
+      <!-- ===============================================================
+           NESTED
+           =============================================================== -->
+  - description: Nested disclosures
+    html: |-
+      <aui-disclosure summary="Section A">
+        <aui-stack gap="2">
+          <p>Top-level content for Section A.</p>
+          <aui-disclosure summary="Sub-section A.1">
+            <p>Nested content inside sub-section A.1.</p>
+          </aui-disclosure>
+          <aui-disclosure summary="Sub-section A.2">
+            <p>Nested content inside sub-section A.2.</p>
+          </aui-disclosure>
+        </aui-stack>
+      </aui-disclosure>
+
+      <!-- ===============================================================
+           MULTIPLE -- stacked disclosures
+           =============================================================== -->
+  - description: Stacked disclosures (FAQ style)
+    html: |-
+      <aui-stack gap="0">
+        <aui-disclosure summary="What is agent-ui?">
+          <p>A design system for building agent interfaces with web components.</p>
+        </aui-disclosure>
+        <aui-disclosure summary="How do I install it?">
+          <p>Install via npm: npm install @agent-ui/kit</p>
+        </aui-disclosure>
+        <aui-disclosure summary="Is it open source?">
+          <p>Yes, agent-ui is released under the MIT license.</p>
+        </aui-disclosure>
+      </aui-stack>

package/dist/docs/components/divider.yaml

@@ -0,0 +1,63 @@
+name: aui-divider
+tag: aui-divider
+type: element
+summary: Semantic separator line.
+description: |
+  Visual separator between content sections. Horizontal by default. Set orientation="vertical" for vertical dividers inside flex rows. Self-closing — no children.
+attributes:
+  orientation:
+    syntax: key-value
+    type: enum
+    values:
+      - vertical
+    default: null
+    description: |
+      Divider orientation. Horizontal is the default — no attribute needed. Set orientation="vertical" inside direction="row" containers.
+modifiers:
+  label:
+    syntax: boolean
+    description: |
+      Enables labeled divider mode. The element switches to flex layout with ::before and ::after lines flanking the text content. Place label text as the element's inner content. Example: <aui-divider label>or continue with</aui-divider>
+content:
+  model: conditional
+  accepts:
+    - text
+  required: false
+  description: |
+    Empty by default — renders as a 1px line. When the [label] attribute is set, accepts inline text content displayed between two horizontal lines.
+composition:
+  parents:
+    - aui-stack
+    - aui-grid
+    - div
+    - section
+    - main
+  children: null
+  context: |
+    Use between sections, list items, or grouped content. Horizontal by default in column stacks. Use orientation="vertical" in row stacks. The divider stretches to fill available width (horizontal) or height (vertical, via align-self: stretch).
+tokens:
+  color:
+    - --aui-border-muted
+  typography:
+    - --aui-font-family
+    - --aui-font-xs
+    - --aui-ink-muted
+examples:
+  - description: Horizontal divider between content
+    html: |-
+      <aui-stack>
+        <span>Above</span>
+        <aui-divider></aui-divider>
+        <span>Below</span>
+      </aui-stack>
+  - description: Vertical divider in a row
+    html: |-
+      <aui-stack direction="row" align-items="center" style="height: 2rem;">
+        <span>Left</span>
+        <aui-divider orientation="vertical"></aui-divider>
+        <span>Right</span>
+      </aui-stack>
+  - description: Labeled divider with text between lines
+    html: <aui-divider label>or continue with</aui-divider>
+  - description: Labeled divider as section header
+    html: <aui-divider label>Settings</aui-divider>