@agent-ui-kit/web-components 0.0.3 → 0.0.5

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

@@ -0,0 +1,120 @@
+name: aui-agent-message
+tag: aui-agent-message
+type: component
+summary: Individual chat message bubble with action toolbar.
+description: >
+  Accepts slotted content: aui-agent-text, aui-agent-activity,
+  aui-agent-seeds, or any custom content. Provides a configurable
+  action toolbar (copy, retry, edit, feedback) that appears on hover
+  via CSS anchor positioning as a popover below the bubble.
+
+base: AgentElement
+
+attributes:
+  role:
+    syntax: key-value
+    type: string
+    default: assistant
+    description: Message role — user, assistant, or system.
+
+  message-id:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Unique message identifier.
+
+  timestamp:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Epoch milliseconds.
+
+  status:
+    syntax: key-value
+    type: string
+    default: sent
+    description: >
+      Message status — sending, sent, error, streaming, or partial.
+
+  actions:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Comma-separated action list, or "none" to suppress.
+      Defaults per role — assistant: copy,retry,feedback-up,feedback-down;
+      user: edit,retry.
+
+  actions-style:
+    syntax: key-value
+    type: string
+    default: icon
+    description: Action button style — icon, label, or icon-label.
+
+  actions-position:
+    syntax: key-value
+    type: string
+    default: below
+    description: Toolbar placement — below (popover) or inside (inline).
+
+a11y:
+  role: article
+
+events:
+  aui:message-action:
+    description: >
+      Fired when an action button is clicked.
+      detail contains action and messageId.
+
+  aui:continue-request:
+    description: >
+      Fired when continue is requested for a partial message.
+      detail contains messageId.
+
+composition:
+  parents: [aui-agent-thread]
+  children: [aui-agent-text, aui-agent-activity, aui-agent-seeds, any]
+
+examples:
+  - html: |
+      <aui-agent-message role="assistant" status="sent" message-id="msg-001">
+        <aui-agent-text>Based on your project structure, I recommend using a **monorepo** with the following layout:
+
+      - `packages/core` — shared utilities and types
+      - `packages/ui` — component library
+      - `apps/web` — main application
+
+      This keeps dependencies clean and enables independent versioning for each package.</aui-agent-text>
+      </aui-agent-message>
+    description: Assistant message with default actions (copy, retry, feedback). Hover reveals the action toolbar below.
+
+  - html: |
+      <aui-agent-message role="user" message-id="msg-002">
+        <aui-agent-text format="plain">How do I set up path aliases in TypeScript so imports like @/components work across all packages?</aui-agent-text>
+      </aui-agent-message>
+    description: User message with edit and retry actions.
+
+  - html: |
+      <aui-agent-message role="assistant" status="streaming" message-id="msg-003" actions="none">
+        <aui-agent-text>You'll need to configure `paths` in your root `tsconfig.json` and then extend it in each package. Here's the base config:
+
+      ```json
+      {
+        "compilerOptions": {
+          "baseUrl": ".",
+          "paths": {
+            "@/*": ["./src/*"]
+          }
+        }
+      }
+      ```
+
+      Each package tsconfig extends this and...</aui-agent-text>
+      </aui-agent-message>
+    description: Streaming message — content is still arriving. Actions are suppressed during streaming.
+
+  - html: |
+      <aui-agent-message role="assistant" status="error" message-id="msg-004">
+        <aui-agent-text format="plain">Something went wrong while generating the response. Please try again.</aui-agent-text>
+      </aui-agent-message>
+    description: Error message — status="error" applies error styling and surfaces a retry action.

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

@@ -0,0 +1,91 @@
+name: aui-agent-panel
+tag: aui-agent-panel
+type: component
+summary: Top-level chat shell that composes header, feed, and input.
+description: >
+  Layout coordinator for agent chat interfaces. Discovers child
+  aui-agent-feed and aui-agent-input elements and provides focus
+  delegation via focusComposer(). Sets role="region" with an
+  aria-label derived from the panel-title attribute. Does not stamp
+  DOM — just discovers and coordinates existing children.
+
+base: AgentElement
+
+attributes:
+  panel-title:
+    syntax: string
+    type: string
+    default: ''
+    description: Title for the panel, used as aria-label for the region.
+
+  auto-focus:
+    syntax: string
+    type: string
+    default: ready
+    description: >
+      When to auto-focus the composer. 'ready' focuses on activate,
+      'open-request' defers until an external signal, 'never' skips.
+
+a11y:
+  role: region
+  aria-label: Derived from panel-title attribute
+
+methods:
+  focusComposer:
+    description: Delegates focus to the child aui-agent-input composer.
+
+composition:
+  parents: [aui-content, aui-pane, aui-dialog, aui-drawer, div, any]
+  children: [aui-header, aui-agent-feed, aui-agent-input, aui-footer]
+
+examples:
+  - html: |
+      <aui-agent-panel panel-title="Design Assistant" max-width="xl" style="height: 32rem;">
+        <aui-header dividers>
+          <aui-stack direction="row" gap="2" align-items="center">
+            <aui-avatar square>AI</aui-avatar>
+            <aui-stack gap="0">
+              <aui-heading size="sm">Design Assistant</aui-heading>
+              <aui-text muted size="xs">Claude 3.5 Sonnet</aui-text>
+            </aui-stack>
+          </aui-stack>
+          <aui-badge accent slot="trailing">Online</aui-badge>
+        </aui-header>
+        <aui-agent-feed auto-scroll scrollable>
+          <aui-agent-thread role="user" sender="You">
+            <aui-agent-message role="user">
+              <aui-agent-text format="plain">How should I structure the color system?</aui-agent-text>
+            </aui-agent-message>
+          </aui-agent-thread>
+          <aui-agent-thread role="assistant" sender="Claude">
+            <aui-avatar>C</aui-avatar>
+            <aui-agent-message role="assistant">
+              <aui-agent-text>I recommend a **three-layer approach**: primitives, semantic tokens, and component tokens.</aui-agent-text>
+            </aui-agent-message>
+          </aui-agent-thread>
+        </aui-agent-feed>
+        <aui-agent-input>
+          <aui-agent-prompt>
+            <aui-textarea placeholder="Ask a follow-up question..."></aui-textarea>
+          </aui-agent-prompt>
+        </aui-agent-input>
+      </aui-agent-panel>
+    description: Full chat panel with header, message feed, and composer input.
+
+  - html: |
+      <aui-agent-panel panel-title="Quick Chat" max-width="xl" style="height: 24rem;">
+        <aui-agent-feed auto-scroll scrollable>
+          <aui-agent-thread role="assistant" sender="Claude">
+            <aui-avatar>C</aui-avatar>
+            <aui-agent-message role="assistant">
+              <aui-agent-text>Hello! How can I help you today?</aui-agent-text>
+            </aui-agent-message>
+          </aui-agent-thread>
+        </aui-agent-feed>
+        <aui-agent-input>
+          <aui-agent-prompt>
+            <aui-textarea placeholder="Type a message..."></aui-textarea>
+          </aui-agent-prompt>
+        </aui-agent-input>
+      </aui-agent-panel>
+    description: Minimal chat panel with just feed and input, no header.

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

@@ -0,0 +1,78 @@
+name: aui-agent-prompt
+tag: aui-agent-prompt
+type: component
+summary: Bordered prompt container for the chat composer textarea.
+description: >
+  Visual wrapper around the textarea inside aui-agent-input.
+  Provides bordered styling with focus ring when the inner
+  aui-textarea gains focus. Contains aui-textarea, optional
+  inline action buttons (ghost + hide-label), and a bottom
+  toolbar via aui-inset > aui-select mode="bar" transparent.
+
+base: AgentElement
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Disables interaction.
+  inline:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Single-line mode. Switches to row layout with textarea and send
+      button side-by-side. Textarea gets compact block padding and the
+      trailing button sits inline. Toolbar border is suppressed.
+
+composition:
+  parents: [aui-agent-input, aui-stack]
+  children: [aui-textarea, aui-button, aui-inset, any]
+
+examples:
+  - html: |
+      <aui-agent-prompt>
+        <aui-textarea placeholder="Describe what you need help with..."></aui-textarea>
+      </aui-agent-prompt>
+    description: Basic bordered prompt with textarea — focus ring activates when textarea is focused.
+
+  - html: |
+      <aui-agent-prompt>
+        <aui-textarea placeholder="Ask anything..."></aui-textarea>
+        <div data-role="leading">
+          <aui-button ghost size="sm">
+            <aui-icon name="sparkles"></aui-icon>
+          </aui-button>
+        </div>
+      </aui-agent-prompt>
+    description: Prompt with an inline action icon (sparkle) positioned beside the textarea for triggering AI features.
+
+  - html: |
+      <aui-agent-prompt>
+        <aui-textarea placeholder="What would you like to build today?"></aui-textarea>
+        <div data-role="actions">
+          <aui-button ghost size="sm">
+            <aui-icon name="paperclip"></aui-icon>
+          </aui-button>
+          <aui-button ghost size="sm">
+            <aui-icon name="image"></aui-icon>
+          </aui-button>
+          <aui-button ghost size="sm">
+            <aui-icon name="microphone"></aui-icon>
+          </aui-button>
+          <aui-button primary data-submit>Send</aui-button>
+        </div>
+      </aui-agent-prompt>
+    description: >
+      Prompt with action toolbar below textarea — attach files, upload images,
+      voice input, and send.
+
+  - html: |
+      <aui-agent-prompt inline>
+        <aui-textarea placeholder="Quick message..."></aui-textarea>
+        <aui-button round label="Send" data-submit hide-label><aui-icon name="arrow-up"></aui-icon></aui-button>
+      </aui-agent-prompt>
+    description: >
+      Inline single-line prompt with textarea and send button side-by-side.
+      Row layout with compact padding, no toolbar border.

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

@@ -0,0 +1,44 @@
+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.
+
+base: AgentElement
+
+attributes:
+  options:
+    syntax: key-value
+    type: string
+    default: ""
+    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.
+
+composition:
+  parents: [aui-agent-message, aui-agent-feed]
+  children: []
+
+examples:
+  - 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"}]'>
+      </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

@@ -0,0 +1,57 @@
+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.
+
+base: AgentElement
+
+attributes:
+  format:
+    syntax: key-value
+    type: string
+    default: markdown
+    description: Render format — markdown (default) or plain.
+
+composition:
+  parents: [aui-agent-message]
+  children: []
+
+examples:
+  - html: |
+      <aui-agent-text>## Getting Started
+
+      To install the package, run:
+
+      ```bash
+      npm install @agent-ui/kit
+      ```
+
+      ### Key features
+
+      - **Zero dependencies** — no runtime bloat
+      - **Web standards** — built on custom elements
+      - **Accessible** — ARIA roles and keyboard nav built in
+
+      > 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: |
+      <aui-agent-text>Here are the three main approaches to state management:
+
+      1. **Local component state** — simplest, works for isolated UI
+      2. **Context/Provider pattern** — good for shared state within a subtree
+      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

@@ -0,0 +1,82 @@
+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.
+
+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]
+
+examples:
+  - 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: |
+      <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: |
+      <aui-agent-thread role="assistant" sender="Claude" avatar-align="top">
+        <aui-avatar>C</aui-avatar>
+        <div data-role="context">
+          <aui-text muted size="xs">Claude 3.5 Sonnet · 2.4s · 347 tokens</aui-text>
+        </div>
+        <aui-agent-message role="assistant">
+          <aui-agent-text>Here's the refactored auth module using JWT:</aui-agent-text>
+        </aui-agent-message>
+        <aui-agent-message role="assistant">
+          <aui-agent-text>```typescript
+          import jwt from 'jsonwebtoken';
+
+          export function generateToken(userId: string): string {
+            return jwt.sign({ sub: userId }, process.env.JWT_SECRET!, {
+              expiresIn: '7d',
+            });
+          }
+          ```</aui-agent-text>
+        </aui-agent-message>
+        <aui-agent-message role="assistant">
+          <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/app-shell.yaml

@@ -0,0 +1,64 @@
+name: aui-app-shell
+tag: aui-app-shell
+type: component
+summary: Full-page application shell with sidebar and content column.
+description: >
+  Top-level layout component. Horizontal flex layout spanning the full
+  viewport height. Contains a collapsible sidebar and a page column
+  with context bar and main content area.
+
+base: AgentElement
+
+a11y:
+  role: application
+
+composition:
+  parents: [body]
+  children:
+    typical: [aui-sidebar, aui-page]
+    pattern: >
+      Sidebar on one side (left by default) and aui-page filling
+      the remaining space. The shell scopes layout styles for all
+      nested page and sidebar descendants.
+  context: >
+    The root layout for full-page applications. Manages the
+    relationship between sidebar width and content column flex.
+
+tokens:
+  color:
+    - --aui-doc
+    - --aui-ink
+    - --aui-panel
+    - --aui-border
+  typography:
+    - --aui-font-family
+  sizing:
+    - --aui-space
+    - --aui-radius
+    - --aui-pad-control-block
+    - --aui-size
+
+examples:
+  - html: |
+      <aui-app-shell>
+        <aui-sidebar width="240" collapsible>
+          <aui-sidebar-header>
+            <aui-nav-item label="App" icon="grid"></aui-nav-item>
+          </aui-sidebar-header>
+          <aui-sidebar-content>
+            <aui-nav-item label="Home" icon="home"></aui-nav-item>
+            <aui-nav-item label="Settings" icon="settings"></aui-nav-item>
+          </aui-sidebar-content>
+        </aui-sidebar>
+        <aui-page>
+          <aui-page-context>
+            <aui-breadcrumb>
+              <aui-breadcrumb-item label="Home"></aui-breadcrumb-item>
+            </aui-breadcrumb>
+          </aui-page-context>
+          <aui-page-main>
+            <main>Page content</main>
+          </aui-page-main>
+        </aui-page>
+      </aui-app-shell>
+    description: Complete app shell with sidebar navigation and page content.

package/dist/docs/components/breadcrumb-item.yaml

@@ -0,0 +1,49 @@
+name: aui-breadcrumb-item
+tag: aui-breadcrumb-item
+type: component
+summary: Individual breadcrumb link or current-page indicator.
+description: >
+  A single entry in a breadcrumb trail. Set href for a link,
+  or current for the active page (no link, bold text).
+  Always used inside aui-breadcrumb.
+
+base: AgentElement
+
+attributes:
+  href:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Navigation URL. Stamps an anchor element when set.
+
+  current:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Marks this item as the current page (aria-current="page").
+
+a11y:
+  aria:
+    aria-current: page (when current is set).
+
+composition:
+  parents: [aui-breadcrumb]
+  children: null
+
+examples:
+  - html: |
+      <aui-breadcrumb>
+        <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/settings">Settings</aui-breadcrumb-item>
+        <aui-breadcrumb-item current>Profile</aui-breadcrumb-item>
+      </aui-breadcrumb>
+    description: Full breadcrumb trail with link items and current page.
+
+  - html: |
+      <aui-breadcrumb>
+        <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/products">Products</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/products/widgets">Widgets</aui-breadcrumb-item>
+        <aui-breadcrumb-item current>Deluxe Widget</aui-breadcrumb-item>
+      </aui-breadcrumb>
+    description: Deep breadcrumb trail with four levels.

package/dist/docs/components/breadcrumb.yaml

@@ -0,0 +1,59 @@
+name: aui-breadcrumb
+tag: aui-breadcrumb
+type: component
+summary: Breadcrumb navigation trail.
+description: >
+  Container for aui-breadcrumb-item children. Sets role="navigation"
+  and aria-label. Separators are rendered via CSS between items.
+
+base: AgentElement
+
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: Breadcrumb
+    description: Accessible label for the navigation landmark.
+
+  joiner:
+    syntax: key-value
+    type: string
+    default: "/"
+    description: >
+      Separator character between breadcrumb items.
+      Common values: "/" "›" "→" "·"
+
+a11y:
+  role: navigation
+  aria:
+    aria-label: Set from label attribute.
+
+composition:
+  parents: [any]
+  children: [aui-breadcrumb-item]
+
+examples:
+  - html: |
+      <aui-breadcrumb>
+        <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/settings">Settings</aui-breadcrumb-item>
+        <aui-breadcrumb-item current>Profile</aui-breadcrumb-item>
+      </aui-breadcrumb>
+    description: Typical three-level breadcrumb trail.
+
+  - html: |
+      <aui-breadcrumb>
+        <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/products">Products</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/products/widgets">Widgets</aui-breadcrumb-item>
+        <aui-breadcrumb-item current>Deluxe Widget</aui-breadcrumb-item>
+      </aui-breadcrumb>
+    description: Deep breadcrumb trail with four levels.
+
+  - html: |
+      <aui-breadcrumb joiner="›">
+        <aui-breadcrumb-item href="/">Home</aui-breadcrumb-item>
+        <aui-breadcrumb-item href="/docs">Docs</aui-breadcrumb-item>
+        <aui-breadcrumb-item current>API</aui-breadcrumb-item>
+      </aui-breadcrumb>
+    description: Custom joiner character (›).