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

package/dist/docs/components/agent-seeds.yaml

@@ -2,36 +2,30 @@ name: aui-agent-seeds
 tag: aui-agent-seeds
 type: component
 summary: Suggestion chips for pre-seeded quick responses.
-description: >
-  Renders a wrapped row of outline-styled chips from a JSON options array.
-  Each chip fires aui:seed-select on click with the option's value and label.
-
+description: |
+  Renders a wrapped row of outline-styled chips from a JSON options array. Each chip fires aui:seed-select on click with the option's value and label.
 base: AgentElement
-
 attributes:
   options:
     syntax: key-value
     type: string
     default: ""
-    description: >
+    description: |
       JSON array of { value, label, icon? } objects.
-
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Disables all chips.
-
 events:
   aui:seed-select:
-    description: >
-      Fired when a chip is clicked.
-      detail contains value and label.
-
+    description: |
+      Fired when a chip is clicked. detail contains value and label.
 composition:
-  parents: [aui-agent-message, aui-agent-feed]
+  parents:
+    - aui-agent-message
+    - aui-agent-feed
   children: []
-
 tokens:
   - name: --aui-agent-seeds-padding-block
     default: var(--aui-agent-seed-pad-block, var(--aui-space))
@@ -43,13 +37,13 @@ tokens:
     default: var(--aui-agent-seed-gap, var(--aui-space))
     description: Gap between chip rows.
   - name: --aui-agent-seeds-chip-gap
-    default: "calc(var(--aui-space) * 0.5)"
+    default: calc(var(--aui-space) * 0.5)
     description: Gap between icon and label within a chip.
   - name: --aui-agent-seeds-chip-padding-block
-    default: "calc(var(--aui-space) * 0.5)"
+    default: calc(var(--aui-space) * 0.5)
     description: Block padding of each chip.
   - name: --aui-agent-seeds-chip-padding-inline
-    default: "calc(var(--aui-space) * 1.5)"
+    default: calc(var(--aui-space) * 1.5)
     description: Inline padding of each chip.
   - name: --aui-agent-seeds-chip-font-family
     default: var(--aui-font-family)
@@ -84,14 +78,12 @@ tokens:
   - name: --aui-agent-seeds-chip-background-active
     default: var(--aui-fill-active, var(--aui-action-active))
     description: Background of chips when active/pressed.
-
 examples:
-  - html: |
+  - description: Quick action suggestions — common follow-up actions presented as selectable chips below the composer or a message
+    html: |-
       <aui-agent-seeds options='[{"value":"clarify","label":"Clarify user problem"},{"value":"context","label":"Define user context"},{"value":"deliverable","label":"Select deliverable"},{"value":"timeline","label":"Set timeline"}]'>
       </aui-agent-seeds>
-    description: Quick action suggestions — common follow-up actions presented as selectable chips below the composer or a message.
-
-  - html: |
-      <aui-agent-seeds options='[{"value":"write-email","label":"Draft an email","icon":"mail"},{"value":"summarize","label":"Summarize a document","icon":"file-text"},{"value":"brainstorm","label":"Brainstorm ideas","icon":"lightbulb"},{"value":"analyze-data","label":"Analyze data","icon":"chart-bar"}]'>
+  - description: Conversation starters with icons — used on an empty chat state to help users begin a session with common tasks
+    html: |-
+      <aui-agent-seeds options='[{"value":"write-email","label":"Draft an email","icon":"envelope"},{"value":"summarize","label":"Summarize a document","icon":"file-text"},{"value":"brainstorm","label":"Brainstorm ideas","icon":"lightbulb"},{"value":"analyze-data","label":"Analyze data","icon":"chart-bar"}]'>
       </aui-agent-seeds>
-    description: Conversation starters with icons — used on an empty chat state to help users begin a session with common tasks.

package/dist/docs/components/agent-text.yaml

@@ -2,25 +2,19 @@ name: aui-agent-text
 tag: aui-agent-text
 type: component
 summary: Markdown renderer for chat message content.
-description: >
-  Renders a markdown subset (paragraphs, headings, lists, code fences,
-  inline code, bold, italic, links, blockquotes) to sanitized HTML.
-  Content can come from text content or the content property.
-  Debounced rendering during streaming updates.
-
+description: |
+  Renders a markdown subset (paragraphs, headings, lists, code fences, inline code, bold, italic, links, blockquotes) to sanitized HTML. Content can come from text content or the content property. Debounced rendering during streaming updates.
 base: AgentElement
-
 attributes:
   format:
     syntax: key-value
     type: string
     default: markdown
     description: Render format — markdown (default) or plain.
-
 composition:
-  parents: [aui-agent-message]
+  parents:
+    - aui-agent-message
   children: []
-
 tokens:
   - name: --aui-agent-text-padding-block
     default: var(--aui-agent-bubble-pad-block, 0.625rem)
@@ -29,7 +23,7 @@ tokens:
     default: var(--aui-agent-bubble-pad-inline, 0.875rem)
     description: Inline padding of the text container.
   - name: --aui-agent-text-prose-gap
-    default: "var(--aui-agent-prose-gap, calc(var(--aui-space) * 2))"
+    default: var(--aui-agent-prose-gap, calc(var(--aui-space) * 2))
     description: Vertical gap between prose elements (paragraphs, headings, etc.).
   - name: --aui-agent-text-heading-font-weight
     default: var(--aui-font-weight-bold, 600)
@@ -47,16 +41,16 @@ tokens:
     default: var(--aui-control, var(--aui-fill))
     description: Background of inline code spans.
   - name: --aui-agent-text-code-border-radius
-    default: "calc(var(--aui-radius) * 0.5)"
+    default: calc(var(--aui-radius) * 0.5)
     description: Border radius of inline code spans.
   - name: --aui-agent-text-pre-background
     default: var(--aui-control, var(--aui-fill))
     description: Background of code blocks.
   - name: --aui-agent-text-pre-border-radius
-    default: "calc(var(--aui-radius) * 0.5)"
+    default: calc(var(--aui-radius) * 0.5)
     description: Border radius of code blocks.
   - name: --aui-agent-text-pre-padding
-    default: "calc(var(--aui-space) * 2)"
+    default: calc(var(--aui-space) * 2)
     description: Padding inside code blocks.
   - name: --aui-agent-text-link-color
     default: var(--aui-ink-accent, var(--aui-accent-solid))
@@ -67,9 +61,9 @@ tokens:
   - name: --aui-agent-text-hr-border
     default: var(--aui-border-muted)
     description: Border color of horizontal rules.
-
 examples:
-  - html: |
+  - description: Rich markdown rendering with headings, code fences, bullet lists, blockquotes, bold text, and links
+    html: |-
       <aui-agent-text>## Getting Started
 
       To install the package, run:
@@ -87,13 +81,10 @@ examples:
       > Note: Requires a modern browser with custom element support.
 
       See the [documentation](https://example.com/docs) for the full API reference.</aui-agent-text>
-    description: Rich markdown rendering with headings, code fences, bullet lists, blockquotes, bold text, and links.
-
-  - html: |
-      <aui-agent-text format="plain">The deployment completed successfully. All 47 tests passed and the build artifact was uploaded to s3://releases/v2.1.0/bundle.tar.gz. No breaking changes detected.</aui-agent-text>
-    description: Plain text mode — no markdown processing, rendered as-is.
-
-  - html: |
+  - description: Plain text mode — no markdown processing, rendered as-is
+    html: <aui-agent-text format="plain">The deployment completed successfully. All 47 tests passed and the build artifact was uploaded to s3://releases/v2.1.0/bundle.tar.gz. No breaking changes detected.</aui-agent-text>
+  - description: Streaming content — text cuts off mid-sentence while the response is still being generated. The renderer handles partial markdown gracefully
+    html: |-
       <aui-agent-text>Here are the three main approaches to state management:
 
       1. **Local component state** — simplest, works for isolated UI
@@ -101,4 +92,3 @@ examples:
       3. **External store** — best for complex, cross-cutting state
 
       For your use case, I'd recommend starting with option 2 and migrating to an external store only if you hit performance issues with deeply nested...</aui-agent-text>
-    description: Streaming content — text cuts off mid-sentence while the response is still being generated. The renderer handles partial markdown gracefully.

package/dist/docs/components/agent-thread.yaml

@@ -2,44 +2,38 @@ name: aui-agent-thread
 tag: aui-agent-thread
 type: component
 summary: Message group with 2x2 grid layout for avatar, context, and bubbles.
-description: >
-  Cluster of messages from the same sender. Provides a 2x2 grid layout:
-  col 1 = avatar (bottom-aligned), col 2 row 1 = context area (metadata),
-  col 2 row 2 = bubbles area (message flex column). A MutationObserver
-  routes dynamically added children into the correct wrapper.
-
+description: |
+  Cluster of messages from the same sender. Provides a 2x2 grid layout: col 1 = avatar (bottom-aligned), col 2 row 1 = context area (metadata), col 2 row 2 = bubbles area (message flex column). A MutationObserver routes dynamically added children into the correct wrapper.
 base: AgentElement
-
 attributes:
   role:
     syntax: key-value
     type: string
     default: ""
     description: Message role — user, assistant, or system.
-
   sender:
     syntax: key-value
     type: string
     default: ""
     description: Display name of the sender.
-
   avatar-align:
     syntax: key-value
     type: string
     default: ""
     description: Avatar vertical alignment — top, center, or bottom (default).
-
 a11y:
   role: group
   aria-label: Messages from {sender}
-
 composition:
-  parents: [aui-agent-feed]
-  children: [aui-avatar, aui-agent-message, any]
-
+  parents:
+    - aui-agent-feed
+  children:
+    - aui-avatar
+    - aui-agent-message
+    - any
 tokens:
   - name: --aui-agent-thread-column-gap
-    default: "var(--aui-agent-message-gap, calc(var(--aui-space) * 2))"
+    default: var(--aui-agent-message-gap, calc(var(--aui-space) * 2))
     description: Gap between avatar column and message column.
   - name: --aui-agent-thread-max-width
     default: var(--aui-agent-bubble-max-width, 85%)
@@ -56,26 +50,24 @@ tokens:
   - name: --aui-agent-thread-user-avatar-color
     default: var(--aui-agent-bubble-user-ink)
     description: Text/icon color of the user avatar.
-
 examples:
-  - html: |
+  - description: Assistant thread with avatar and a single message bubble
+    html: |-
       <aui-agent-thread role="assistant" sender="Claude">
         <aui-avatar>C</aui-avatar>
         <aui-agent-message role="assistant">
           <aui-agent-text>I've analyzed your codebase and found three potential performance bottlenecks in the data processing pipeline. Let me walk through each one.</aui-agent-text>
         </aui-agent-message>
       </aui-agent-thread>
-    description: Assistant thread with avatar and a single message bubble.
-
-  - html: |
+  - description: User thread — right-aligned with no avatar
+    html: |-
       <aui-agent-thread role="user" sender="Sarah">
         <aui-agent-message role="user">
           <aui-agent-text format="plain">Can you refactor the authentication module to use JWT instead of session cookies?</aui-agent-text>
         </aui-agent-message>
       </aui-agent-thread>
-    description: User thread — right-aligned with no avatar.
-
-  - html: |
+  - description: Multi-message thread with context metadata (model, latency, token count) and top-aligned avatar
+    html: |-
       <aui-agent-thread role="assistant" sender="Claude" avatar-align="top">
         <aui-avatar>C</aui-avatar>
         <div data-role="context">
@@ -99,4 +91,3 @@ examples:
           <aui-agent-text>I've split the token generation and verification into separate functions for better testability. The refresh token rotation is handled in the middleware layer.</aui-agent-text>
         </aui-agent-message>
       </aui-agent-thread>
-    description: Multi-message thread with context metadata (model, latency, token count) and top-aligned avatar.

package/dist/docs/components/alert.yaml

@@ -2,53 +2,48 @@ name: aui-alert
 tag: aui-alert
 type: component
 summary: Contextual banner for status messages.
-description: >
-  Inline alert banner with intent-based coloring via boolean
-  attributes (info, success, warning, danger). Left border accent
-  stripe signals severity. Supports rich content including
-  headings and paragraphs. Optional dismissable behavior via JS.
-
+description: |
+  Inline alert banner with intent-based coloring via boolean attributes (info, success, warning, danger). Left border accent stripe signals severity. Supports rich content including headings and paragraphs. Optional dismissable behavior via JS.
 base: AgentElement
-
-# ── Presentational attributes ─────────────────────────────
-
 presentational:
   intent:
     syntax: boolean
     exclusive: true
     cascades: false
     default: info
-    values: [accent, info, success, warning, danger]
+    values:
+      - accent
+      - info
+      - success
+      - warning
+      - danger
     description: Visual intent controlling background tint and border accent color.
-
-# ── Modifiers ─────────────────────────────────────────────
-
 modifiers:
   dismissable:
     syntax: boolean
-    description: >
+    description: |
       Shows a close button area. JS removes the element on click.
-
-# ── Content model ─────────────────────────────────────────
-
 content:
   model: flow
-  accepts: [text, strong, p, aui-text, aui-link]
+  accepts:
+    - text
+    - strong
+    - p
+    - aui-text
+    - aui-link
   required: true
-  description: >
-    Message content. Can be plain text or rich HTML with
-    headings and paragraphs for multi-line alerts.
-
-# ── Slots ─────────────────────────────────────────────────
-
+  description: |
+    Message content. Can be plain text or rich HTML with headings and paragraphs for multi-line alerts.
 slots:
   default:
-    accepts: [text, strong, p, aui-text, aui-link]
+    accepts:
+      - text
+      - strong
+      - p
+      - aui-text
+      - aui-link
     required: true
     description: Alert message content.
-
-# ── CSS tokens consumed ──────────────────────────────────
-
 tokens:
   spacing:
     - --aui-alert-gap
@@ -61,19 +56,26 @@ tokens:
     - --aui-alert-font-size
   shape:
     - --aui-alert-radius
-
-# ── Examples ──────────────────────────────────────────────
-
 examples:
-  - html: <aui-alert>Your session will expire in 5 minutes.</aui-alert>
-    description: Default info alert.
-
-  - html: <aui-alert success>Operation completed successfully.</aui-alert>
-    description: Success alert.
-
-  - html: |
+  - description: Default info alert
+    html: <aui-alert>Your session will expire in 5 minutes.</aui-alert>
+  - description: Success alert
+    html: <aui-alert success>Operation completed successfully.</aui-alert>
+  - description: Warning alert
+    html: <aui-alert warning>This action cannot be undone.</aui-alert>
+  - description: Danger alert
+    html: <aui-alert danger>Failed to save changes. Please try again.</aui-alert>
+  - description: Rich content danger alert
+    html: |-
       <aui-alert danger>
         <strong>Deployment failed</strong>
         <p>Build step 3 returned exit code 1. Check logs for details.</p>
       </aui-alert>
-    description: Rich content danger alert.
+  - description: All four intent variants stacked
+    html: |-
+      <aui-stack gap="3">
+        <aui-alert>Informational message.</aui-alert>
+        <aui-alert success>Success message.</aui-alert>
+        <aui-alert warning>Warning message.</aui-alert>
+        <aui-alert danger>Danger message.</aui-alert>
+      </aui-stack>

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

@@ -2,73 +2,64 @@ name: aui-avatar-group
 tag: aui-avatar-group
 type: component
 summary: Overlapping avatar stack with automatic overflow counter.
-description: >
-  Displays child aui-avatar elements in an overlapping row with
-  descending z-index. When the max attribute is set and children
-  exceed that count, excess avatars are hidden and a +N counter
-  is stamped. Size attribute propagates to child avatars.
-
+description: |
+  Displays child aui-avatar elements in an overlapping row with descending z-index. When the max attribute is set and children exceed that count, excess avatars are hidden and a +N counter is stamped. Size attribute propagates to child avatars.
 base: AgentElement
-
-# -- Component attributes ------------------------------------------
-
 attributes:
   max:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Maximum visible avatars. Remaining are hidden and a +N
-      overflow counter is shown.
-
+    description: |
+      Maximum visible avatars. Remaining are hidden and a +N overflow counter is shown.
   size:
     syntax: key-value
     type: string
     default: ""
-    values: [xs, sm, lg]
-    description: >
-      Passed through to child aui-avatar elements for consistent
-      sizing across the group.
-
-# -- Content model -------------------------------------------------
-
+    values:
+      - xs
+      - sm
+      - lg
+    description: |
+      Passed through to child aui-avatar elements for consistent sizing across the group.
 content:
   model: block
-  accepts: [aui-avatar]
+  accepts:
+    - aui-avatar
   required: true
-  description: >
-    One or more aui-avatar children. Order determines stacking
-    (first avatar on top, highest z-index).
-
-# -- Slots ---------------------------------------------------------
-
+  description: |
+    One or more aui-avatar children. Order determines stacking (first avatar on top, highest z-index).
 slots:
   default:
-    accepts: [aui-avatar]
+    accepts:
+      - aui-avatar
     required: true
     description: Avatar children to display in the overlapping stack.
-
-# -- Composition ---------------------------------------------------
-
 composition:
-  parents: [aui-stack, aui-header, aui-footer, div, span]
-  children: [aui-avatar]
-  context: >
-    Inline-flex element. Use inside headers, cards, list items,
-    or stacks. Commonly paired with team/contributor displays.
-
-# -- Examples ------------------------------------------------------
-
+  parents:
+    - aui-stack
+    - aui-header
+    - aui-footer
+    - div
+    - span
+  children:
+    - aui-avatar
+  context: |
+    Inline-flex element. Use inside headers, cards, list items, or stacks. Commonly paired with team/contributor displays.
 examples:
-  - html: |
+  - description: Three overlapping avatars
+    html: |-
       <aui-avatar-group>
         <aui-avatar>A</aui-avatar>
         <aui-avatar>B</aui-avatar>
         <aui-avatar>C</aui-avatar>
       </aui-avatar-group>
-    description: Basic avatar group showing all avatars.
 
-  - html: |
+      <!-- ===============================================================
+           MAX OVERFLOW
+           =============================================================== -->
+  - description: Max 3, showing +2 overflow counter
+    html: |-
       <aui-avatar-group max="3">
         <aui-avatar>A</aui-avatar>
         <aui-avatar>B</aui-avatar>
@@ -76,11 +67,47 @@ examples:
         <aui-avatar>D</aui-avatar>
         <aui-avatar>E</aui-avatar>
       </aui-avatar-group>
-    description: Avatar group with max=3 showing +2 overflow.
+  - description: Max 2, showing +4 overflow counter
+    html: |-
+      <aui-avatar-group max="2">
+        <aui-avatar>A</aui-avatar>
+        <aui-avatar>B</aui-avatar>
+        <aui-avatar>C</aui-avatar>
+        <aui-avatar>D</aui-avatar>
+        <aui-avatar>E</aui-avatar>
+        <aui-avatar>F</aui-avatar>
+      </aui-avatar-group>
 
-  - html: |
+      <!-- ===============================================================
+           SIZE VARIANTS
+           =============================================================== -->
+  - description: Small size avatar group
+    html: |-
       <aui-avatar-group size="sm">
         <aui-avatar>A</aui-avatar>
         <aui-avatar>B</aui-avatar>
+        <aui-avatar>C</aui-avatar>
+      </aui-avatar-group>
+  - description: Large size avatar group
+    html: |-
+      <aui-avatar-group size="lg">
+        <aui-avatar>A</aui-avatar>
+        <aui-avatar>B</aui-avatar>
+        <aui-avatar>C</aui-avatar>
+      </aui-avatar-group>
+
+      <!-- ===============================================================
+           MANY AVATARS
+           =============================================================== -->
+  - description: Team display with max 4
+    html: |-
+      <aui-avatar-group max="4">
+        <aui-avatar>AL</aui-avatar>
+        <aui-avatar>BK</aui-avatar>
+        <aui-avatar>CJ</aui-avatar>
+        <aui-avatar>DM</aui-avatar>
+        <aui-avatar>EP</aui-avatar>
+        <aui-avatar>FR</aui-avatar>
+        <aui-avatar>GS</aui-avatar>
+        <aui-avatar>HT</aui-avatar>
       </aui-avatar-group>
-    description: Small size avatars.

package/dist/docs/components/avatar.yaml

@@ -0,0 +1,99 @@
+name: aui-avatar
+tag: aui-avatar
+type: element
+summary: Avatar circle or square showing initials or image.
+description: |
+  Displays user initials or a profile image. Circle by default, square with the square modifier. Sized by --aui-size token. Use for user profiles, contact lists, comment threads.
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: medium
+    values:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
+    description: Controls avatar dimensions.
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: neutral
+    values:
+      - accent
+      - info
+      - success
+      - warning
+      - danger
+    description: Color family for the avatar background.
+modifiers:
+  square:
+    syntax: boolean
+    description: |
+      Uses border-radius (from --aui-radius) instead of circle. Use for workspace/team/app icons rather than people.
+content:
+  model: inline
+  accepts:
+    - text
+    - img
+  required: true
+  description: |
+    1-2 character initials as text, or an img element for photos. When using img, the image fills the avatar and clips to the circle/square shape via object-fit: cover.
+slots:
+  default:
+    accepts:
+      - text
+      - img
+    required: true
+    description: |
+      Initials text (1-2 uppercase letters) or an img element.
+composition:
+  parents:
+    - aui-stack
+    - aui-header
+    - span
+    - div
+    - td
+  children: null
+  context: |
+    Inline element. Use in headers, comment threads, user lists. Group with aui-stack direction="row" for avatar stacks. Pair with text for "avatar + name" patterns.
+constraints:
+  - when: img child
+    require: alt attribute on img
+    reason: |
+      Avatar images need alt text for screen readers. Set alt to the person's name or a descriptive label.
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-font-size
+  color:
+    - --aui-control
+    - --aui-ink-muted
+  shape:
+    - --aui-radius
+examples:
+  - description: Default avatar with initials
+    html: <aui-avatar>KG</aui-avatar>
+  - description: Accent-colored avatar
+    html: <aui-avatar accent>AI</aui-avatar>
+  - description: Square avatar for non-person entities
+    html: <aui-avatar square>SQ</aui-avatar>
+  - description: Avatar size comparison
+    html: |-
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-avatar size="sm">KG</aui-avatar>
+        <aui-avatar>KG</aui-avatar>
+        <aui-avatar size="lg">KG</aui-avatar>
+      </aui-stack>
+  - description: Avatars with intent colors
+    html: |-
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-avatar accent>A</aui-avatar>
+        <aui-avatar info>B</aui-avatar>
+        <aui-avatar success>C</aui-avatar>
+        <aui-avatar warning>D</aui-avatar>
+        <aui-avatar danger>E</aui-avatar>
+      </aui-stack>