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

package/dist/docs/components/container.yaml

@@ -2,126 +2,144 @@ name: aui-container
 tag: aui-container
 type: component
 summary: Unified card and panel surface.
-description: >
-  The standard surface element for cards, panels, and sections.
-  Replaces separate Card and Panel components — a single element
-  with bordered, elevation, shadow, and interactive modifiers. Composes
-  aui-header, aui-content, aui-footer as children.
-
+description: |
+  The standard surface element for cards, panels, and sections. Replaces separate Card and Panel components — a single element with bordered, elevation, shadow, and interactive modifiers. Composes aui-header, aui-content, aui-footer as children.
 base: AgentElement
-
 presentational:
   size:
     syntax: key-value
     attribute: size
     cascades: true
     default: medium
-    values: [xs, sm, md, lg, xl]
+    values:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
     description: Cascades size to all children (header, body, footer).
-
   density:
     syntax: key-value
     attribute: density
     cascades: true
     default: regular
-    values: [compact, spacious]
+    values:
+      - compact
+      - spacious
     description: Cascades density to all children.
-
   intent:
     syntax: boolean
     exclusive: true
     cascades: true
     default: neutral
-    values: [accent, info, success, warning, danger]
+    values:
+      - accent
+      - info
+      - success
+      - warning
+      - danger
     description: Cascades color family to all children.
-
   radius:
     syntax: boolean
     exclusive: true
     cascades: true
     default: medium
-    values: [sharp, round]
+    values:
+      - sharp
+      - round
     description: Controls corner radius of the container.
-
 attributes:
   kind:
     syntax: key-value
     type: enum
-    values: [widget, card, panel]
+    values:
+      - widget
+      - card
+      - panel
+      - popover
     default: card
-    description: >
-      Sets the padding and gap scale for all children.
-      widget: 0.75rem (compact, 1/6–1/4 page).
-      card: 1rem (default, 1/4–1/3 page).
-      panel: 1.75rem (spacious, 1/3–3/4 page, modals).
-
+    description: |
+      Sets the padding and gap scale for all children. widget: 0.75rem (compact). card: 1rem (default). panel: 1.25rem (spacious). popover: 0.75rem with modal background, shadow, border, and auto-computed border-radius (radius + padding) so inner content corners don't clip.
   href:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Navigation target when interactive. Clicking the container
-      navigates to this URL.
-
+    description: |
+      Navigation target when interactive. Clicking the container navigates to this URL.
   elevation:
     syntax: key-value
     type: enum
-    values: ["1", "2", "3", "4", "5", "6", "7"]
+    values:
+      - "1"
+      - "2"
+      - "3"
+      - "4"
+      - "5"
+      - "6"
+      - "7"
     default: ""
-    description: >
-      Surface brightness level. 1=doc (dimmest) through
-      7=modal (brightest). Controls background color.
-
+    description: |
+      Surface brightness level. 1=doc (dimmest) through 7=modal (brightest). Controls background color.
   shadow:
     syntax: key-value
     type: enum
-    values: ["1", "2", "3"]
+    values:
+      - "1"
+      - "2"
+      - "3"
     default: ""
-    description: >
+    description: |
       Shadow depth. 1=subtle, 2=medium, 3=prominent.
-
 modifiers:
   bordered:
     syntax: boolean
     description: Adds a visible border around the container.
-
   interactive:
     syntax: boolean
-    description: >
+    description: |
       Makes the container clickable with hover/active states.
-
 content:
   model: block
-  accepts: [aui-header, aui-content, aui-footer, aui-inset, aui-stack, aui-grid, div, p, any]
+  accepts:
+    - aui-header
+    - aui-content
+    - aui-footer
+    - aui-inset
+    - aui-stack
+    - aui-grid
+    - div
+    - p
+    - any
   required: true
-  description: >
-    Typically aui-header + aui-content + aui-footer for structured
-    cards. Or aui-inset for simple content cards. Child headers
-    and footers automatically get separator borders.
-
+  description: |
+    Typically aui-header + aui-content + aui-footer for structured cards. Or aui-inset for simple content cards. Child headers and footers automatically get separator borders.
 slots:
   default:
-    accepts: [any]
+    accepts:
+      - any
     required: true
     description: Container content.
-
 composition:
-  parents: [aui-stack, aui-grid, div, section, main]
+  parents:
+    - aui-stack
+    - aui-grid
+    - div
+    - section
+    - main
   children:
-    typical: [aui-header, aui-content, aui-footer, aui-inset]
-    pattern: >
-      The standard card pattern is header + body + footer.
-      For simple content, use aui-inset directly.
-  context: >
-    Use for cards in grids, settings panels, dashboard tiles,
-    detail panes. The bordered modifier is the most common —
-    shadow/elevation is for floating/overlay surfaces.
-
+    typical:
+      - aui-header
+      - aui-content
+      - aui-footer
+      - aui-inset
+    pattern: |
+      The standard card pattern is header + body + footer. For simple content, use aui-inset directly.
+  context: |
+    Use for cards in grids, settings panels, dashboard tiles, detail panes. The bordered modifier is the most common — shadow/elevation is for floating/overlay surfaces.
 constraints:
   - when: interactive
     require: href or click handler
     reason: Interactive containers need a destination or action.
-
 a11y:
   role: When interactive, role="button" is set automatically.
   keyboard:
@@ -130,11 +148,9 @@ a11y:
   focus:
     default: Not focusable unless interactive.
     interactive: tabindex="0".
-
 events:
   click:
     description: Fires on interactive containers. Navigates to href if set.
-
 tokens:
   - name: --aui-container-background
     default: var(--aui-card, var(--aui-doc))
@@ -145,9 +161,9 @@ tokens:
   - name: --aui-container-font-size
     default: var(--aui-font-lg)
     description: Base font size for the container.
-
 examples:
-  - html: |
+  - description: Card kind — Settings form (1.25rem padding)
+    html: |-
       <aui-container kind="card" bordered max-width="prose">
         <aui-header>
           <aui-stack gap="1">
@@ -176,9 +192,8 @@ examples:
           </span>
         </aui-footer>
       </aui-container>
-    description: Card kind — Settings form (1.25rem padding).
-
-  - html: |
+  - description: Widget kind — Compact dashboard stat cards (0.75rem padding)
+    html: |-
       <aui-stack direction="row" gap="3" style="flex-wrap: wrap;">
         <aui-container kind="widget" bordered style="flex: 1; min-width: 12rem;">
           <aui-inset>
@@ -214,9 +229,8 @@ examples:
           </aui-inset>
         </aui-container>
       </aui-stack>
-    description: Widget kind — Compact dashboard stat cards (0.75rem padding).
-
-  - html: |
+  - description: Panel kind — Spacious member list (1.75rem padding)
+    html: |-
       <aui-container kind="panel" bordered max-width="xl">
         <aui-header>
           <span slot="leading">
@@ -261,9 +275,8 @@ examples:
           </aui-inset>
         </aui-content>
       </aui-container>
-    description: Panel kind — Spacious member list (1.75rem padding).
-
-  - html: |
+  - description: Elevated success card with centered content
+    html: |-
       <aui-container kind="card" bordered shadow="2" success max-width="md">
         <aui-inset>
           <aui-stack gap="4" align-items="center" style="text-align: center;">
@@ -274,9 +287,8 @@ examples:
           </aui-stack>
         </aui-inset>
       </aui-container>
-    description: Elevated success card with centered content.
-
-  - html: |
+  - description: Widget kind — Compact clickable navigation card
+    html: |-
       <aui-container kind="widget" bordered interactive href="#" max-width="sm">
         <aui-inset>
           <aui-stack direction="row" gap="2" align-items="center">
@@ -289,4 +301,3 @@ examples:
           </aui-stack>
         </aui-inset>
       </aui-container>
-    description: Widget kind — Compact clickable navigation card.

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

@@ -2,14 +2,9 @@ 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.
-
+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
@@ -26,7 +21,6 @@ attributes:
     type: boolean
     default: false
     description: Whether the menu is currently open.
-
 tokens:
   - name: --aui-context-menu-font-family
     default: var(--aui-font-family)
@@ -49,7 +43,6 @@ tokens:
   - name: --aui-context-menu-shadow
     default: var(--aui-shadow-lg)
     description: Box shadow of the menu.
-
 a11y:
   role: menu
   keyboard:
@@ -60,21 +53,21 @@ a11y:
     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]
-
+  parents:
+    - any
+  children:
+    - aui-option
+    - aui-optgroup
 examples:
-  - html: |
+  - 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>
@@ -83,9 +76,8 @@ examples:
         <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: |
+  - 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>
@@ -99,4 +91,3 @@ examples:
           <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

@@ -2,54 +2,40 @@ 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.
-
+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"
+    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:
@@ -58,13 +44,12 @@ a11y:
     ArrowLeft: Move to previous segment.
     ArrowRight: Move to next segment.
     Tab: Move between segments.
-    "0-9": Digit entry with auto-advance.
+    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))
@@ -93,23 +78,86 @@ tokens:
   - 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]
+  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.
-
+  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.
+  - 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>
 
-  - html: <aui-date-field value="2026-03-21" format="DD/MM/YYYY"></aui-date-field>
-    description: European DD/MM/YYYY format.
+      <!-- ===============================================================
+           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>
 
-  - html: <aui-date-field value="2026-03-21" format="YYYY-MM-DD"></aui-date-field>
-    description: ISO format.
+      <!-- ===============================================================
+           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>
 
-  - html: <aui-date-field value="2026-03-21" disabled></aui-date-field>
-    description: Disabled date field.
+      <!-- ===============================================================
+           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>