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

package/dist/docs/components/chip.yaml

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

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

@@ -2,63 +2,42 @@ name: aui-code-block
 tag: aui-code-block
 type: component
 summary: Fenced code block with optional language header, filename, and copy button.
-description: >
-  Wraps an aui-code element with an optional header bar showing a language
-  label, filename, and copy-to-clipboard button. Text content placed
-  directly inside is automatically wrapped in an aui-code child. The header
-  is stamped by JS when language, filename, or copyable attributes are
-  present. The copy button writes the code text to the clipboard via the
-  Clipboard API.
-
+description: |
+  Wraps an aui-code element with an optional header bar showing a language label, filename, and copy-to-clipboard button. Text content placed directly inside is automatically wrapped in an aui-code child. The header is stamped by JS when language, filename, or copyable attributes are present. The copy button writes the code text to the clipboard via the Clipboard API.
 base: AgentElement
-
-# ── Component attributes ──────────────────────────────────
-
 attributes:
   language:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Programming language label shown in the header bar.
-      Also useful for syntax-highlighting integrations.
-
+    description: |
+      Programming language label shown in the header bar. Also useful for syntax-highlighting integrations.
   filename:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Filename shown in the header bar. Takes precedence over
-      language for the displayed label.
-
+    description: |
+      Filename shown in the header bar. Takes precedence over language for the displayed label.
   copyable:
     syntax: boolean
     type: boolean
     default: false
-    description: >
-      When present, shows a "Copy" button in the header bar.
-      Clicking copies the code content to the clipboard.
-
+    description: |
+      When present, shows a "Copy" button in the header bar. Clicking copies the code content to the clipboard.
   max-height:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      CSS max-height applied to the code body. When set, the code
-      area becomes scrollable if content overflows.
-
-# ── Content model ─────────────────────────────────────────
-
+    description: |
+      CSS max-height applied to the code body. When set, the code area becomes scrollable if content overflows.
 content:
   model: text
-  accepts: [text, aui-code]
+  accepts:
+    - text
+    - aui-code
   required: true
-  description: >
-    Code text content. Plain text is automatically wrapped in an
-    aui-code element by JS. An explicit aui-code child is also accepted.
-
-# ── CSS tokens consumed ──────────────────────────────────
-
+  description: |
+    Code text content. Plain text is automatically wrapped in an aui-code element by JS. An explicit aui-code child is also accepted.
 tokens:
   - name: --aui-code-block-background
     default: var(--aui-control)
@@ -84,43 +63,65 @@ tokens:
   - name: --aui-code-block-copy-color-hover
     default: var(--aui-ink)
     description: Copy button text color on hover.
-
-# ── Accessibility ─────────────────────────────────────────
-
 a11y:
   role: figure
   aria:
     aria-label: Set from language or filename when present.
-
-# ── Use cases ─────────────────────────────────────────────
-
 use-cases:
   - Code snippets in documentation pages.
   - Chat message code blocks in agent conversations.
   - Copyable terminal commands.
   - File previews with filename headers.
-
-# ── Examples ──────────────────────────────────────────────
-
 examples:
-  - html: |
+  - description: Code block with language header
+    html: |-
       <aui-code-block language="typescript">
       export function normalize(tokens: string[]) {
         return tokens.map(t => t.trim())
       }
       </aui-code-block>
-    description: Code block with language header.
-
-  - html: |
+  - description: JavaScript with language label
+    html: |-
+      <aui-code-block language="javascript">
+      const greet = (name) => `Hello, ${name}!`
+      console.log(greet('world'))
+      </aui-code-block>
+  - description: Code block with filename and copy button
+    html: |-
       <aui-code-block language="python" filename="main.py" copyable>
       import pandas as pd
       df = pd.read_csv("data.csv")
       print(df.head())
       </aui-code-block>
-    description: Code block with filename and copy button.
-
-  - html: |
+  - description: CSS file with copy
+    html: |-
+      <aui-code-block language="css" filename="tokens.css" copyable>
+      :root {
+        --color-primary: oklch(0.65 0.24 265);
+        --color-surface: oklch(0.98 0 0);
+      }
+      </aui-code-block>
+  - description: Plain code block without header
+    html: |-
       <aui-code-block>
       npm install @agent-ui-kit/web-components
       </aui-code-block>
-    description: Plain code block without header.
+  - description: Scrollable code block with max-height
+    html: |-
+      <aui-code-block language="json" filename="package.json" copyable max-height="8rem">
+      {
+        "name": "@agent-ui-kit/web-components",
+        "version": "0.1.0",
+        "type": "module",
+        "main": "dist/index.js",
+        "exports": {
+          ".": "./dist/index.js",
+          "./styles": "./dist/styles.css"
+        },
+        "dependencies": {},
+        "devDependencies": {
+          "typescript": "^5.4.0",
+          "vite": "^5.2.0"
+        }
+      }
+      </aui-code-block>

package/dist/docs/components/code.yaml

@@ -0,0 +1,37 @@
+name: aui-code
+tag: aui-code
+type: element
+summary: Preformatted code block with monospace font on a recessed surface.
+description: |
+  A CSS-only element for displaying code snippets, terminal output, or configuration text. Renders with monospace font, pre-wrapped whitespace, and a recessed background. Scrolls vertically when content exceeds max-height. Drops border-radius when nested inside aui-container. No JavaScript required.
+tokens:
+  typography:
+    - --aui-font-family-mono
+    - --aui-font-xs
+  color:
+    - --aui-ink-muted
+    - --aui-control
+  sizing:
+    - --aui-radius
+    - --aui-space
+examples:
+  - description: JSON config output
+    html: |-
+      <aui-code>{
+        "source": ["src/tokens/**/*.json"],
+        "platforms": {
+          "css": {
+            "transformGroup": "css",
+            "buildPath": "dist/css/"
+          }
+        }
+      }</aui-code>
+  - description: Terminal log output
+    html: |-
+      <aui-code>Step 1/5 : FROM node:20-alpine
+      Step 2/5 : COPY package*.json ./
+      Step 3/5 : RUN npm ci --production
+      Step 4/5 : COPY . .
+      Step 5/5 : CMD ["node", "server.js"]</aui-code>
+  - description: Single-line command
+    html: <aui-code>npm install @agent-ui/kit</aui-code>

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

@@ -0,0 +1,119 @@
+name: aui-color-area
+tag: aui-color-area
+type: component
+summary: 2D OKLCH gradient surface for picking chroma and lightness at a given hue.
+description: |
+  A rectangular color picking surface using OKLCH as the native color model. X axis controls chroma (0 to 0.4), Y axis controls lightness (1 at top to 0 at bottom). A <canvas> element renders the 2D gradient programmatically since CSS cannot produce OKLCH 2D gradients. Out-of-gamut regions are gamut-mapped via binary search to the nearest in-gamut chroma, ensuring smooth visual continuity. A draggable thumb indicator tracks the current position. Supports pointer drag and keyboard arrow navigation with Shift for 10x step. Dispatches input (continuous) and change (on release) events with { l, c, h } detail.
+base: AgentElement
+attributes:
+  hue:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: Hue angle (0-360) for the gradient.
+  chroma:
+    syntax: key-value
+    type: string
+    default: "0.15"
+    description: Current chroma value (0-0.4, X axis).
+  lightness:
+    syntax: key-value
+    type: string
+    default: "0.65"
+    description: Current lightness value (0-1, Y axis).
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+rendering:
+  description: |
+    Canvas renders at half device-pixel resolution for performance. Each pixel computes an OKLCH color at the given hue; out-of-sRGB-gamut pixels are gamut-mapped by binary-searching chroma downward (8 iterations) to the nearest in-gamut value. A ResizeObserver triggers redraw on size change.
+a11y:
+  role: slider (on thumb element)
+  keyboard:
+    ArrowRight: "Increase chroma by 0.004 (Shift: 0.04)."
+    ArrowLeft: "Decrease chroma by 0.004 (Shift: 0.04)."
+    ArrowUp: "Increase lightness by 0.01 (Shift: 0.1)."
+    ArrowDown: "Decrease lightness by 0.01 (Shift: 0.1)."
+  aria:
+    aria-valuetext: '"oklch(L C H)" on thumb.'
+tokens:
+  - name: --aui-color-area-border-radius
+    default: var(--aui-color-picker-border-radius, var(--aui-radius))
+    description: Corner radius of the gradient surface.
+  - name: --aui-color-area-thumb-size
+    default: 16px
+    description: Width and height of the circular thumb.
+  - name: --aui-color-area-thumb-border
+    default: 2px solid white
+    description: Thumb border for contrast against the gradient.
+  - name: --aui-color-area-thumb-shadow
+    default: 0 0 0 1px rgba(0,0,0,0.3), 0 2px 4px rgba(0,0,0,0.2)
+    description: Thumb drop shadow.
+internal-structure:
+  - element: canvas
+    attr: data-color-area-canvas
+    description: Programmatic 2D OKLCH gradient surface.
+  - element: div
+    attr: data-color-area-thumb
+    description: Draggable thumb positioned via --_x and --_y custom properties.
+composition:
+  parents:
+    - aui-color-picker
+    - aui-stack
+    - aui-container
+    - div
+  children: []
+  context: |
+    Typically used inside aui-color-picker alongside aui-color-slider rows and aui-copy-button output.
+examples:
+  - description: Default color area (hue 0)
+    html: |-
+      <aui-color-area hue="0" chroma="0.15" lightness="0.65"></aui-color-area>
+
+      <!-- ===============================================================
+           DIFFERENT HUES
+           =============================================================== -->
+  - description: Blue hue color area
+    html: <aui-color-area hue="250" chroma="0.2" lightness="0.6"></aui-color-area>
+  - description: Green hue color area
+    html: <aui-color-area hue="145" chroma="0.18" lightness="0.7"></aui-color-area>
+  - description: Purple hue color area
+    html: |-
+      <aui-color-area hue="300" chroma="0.15" lightness="0.5"></aui-color-area>
+
+      <!-- ===============================================================
+           SIZES
+           =============================================================== -->
+  - description: Compact color area (150x150)
+    html: '<aui-color-area hue="30" style="width: 150px; height: 150px;"></aui-color-area>'
+  - description: Large color area (300x200)
+    html: |-
+      <aui-color-area hue="200" style="width: 300px; height: 200px;"></aui-color-area>
+
+      <!-- ===============================================================
+           DISABLED
+           =============================================================== -->
+  - description: Disabled color area
+    html: |-
+      <aui-color-area hue="250" chroma="0.2" lightness="0.6" disabled></aui-color-area>
+
+      <!-- ===============================================================
+           INTERACTIVE -- with live output
+           =============================================================== -->
+  - description: Interactive color area with change events
+    html: |-
+      <aui-stack gap="3">
+        <aui-color-area id="demo-area" hue="200" chroma="0.18" lightness="0.65"></aui-color-area>
+        <aui-text size="sm" muted id="demo-area-output">Drag the thumb to see values</aui-text>
+      </aui-stack>
+
+      <script type="module">
+        const area = document.getElementById('demo-area')
+        const output = document.getElementById('demo-area-output')
+        area?.addEventListener('input', (e) => {
+          const { l, c, h } = e.detail
+          output.textContent = `oklch(${l} ${c} ${h})`
+        })
+      </script>

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

@@ -0,0 +1,121 @@
+name: aui-color-field
+tag: aui-color-field
+type: component
+summary: Text input for color values with inline swatch preview.
+description: |
+  A compact color entry field that combines a color swatch preview with a text editing surface. Supports hex, rgb, oklch, and hsl formats. The swatch updates live as valid colors are typed. Invalid values show an error state. Uses contenteditable span (no native input element) with CSS.supports() for broad format validation.
+base: AgentElement
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Color value string in the specified format.
+  format:
+    syntax: key-value
+    type: string
+    default: hex
+    description: Expected color format (hex, rgb, oklch).
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+a11y:
+  role: textbox (on input surface)
+  keyboard:
+    Enter: Commits value and blurs.
+  aria:
+    aria-label: '"Color value" on input surface.'
+tokens:
+  - name: --aui-color-field-background
+    default: var(--aui-control, var(--aui-fill))
+    description: Field background color.
+  - name: --aui-color-field-border
+    default: var(--aui-stroke)
+    description: Field border color.
+  - name: --aui-color-field-border-radius
+    default: var(--aui-radius)
+    description: Field corner radius.
+  - name: --aui-color-field-border-hover
+    default: var(--aui-stroke-hover)
+    description: Border color on hover.
+  - name: --aui-color-field-border-focus
+    default: var(--aui-focus)
+    description: Border color when focused.
+  - name: --aui-color-field-font-size
+    default: var(--aui-font-sm)
+    description: Text font size.
+  - name: --aui-color-field-font-family
+    default: var(--aui-font-mono, monospace)
+    description: Text font family.
+  - name: --aui-color-field-color
+    default: var(--aui-ink)
+    description: Text color.
+  - name: --aui-color-field-swatch-size
+    default: 20px
+    description: Swatch width and height.
+  - name: --aui-color-field-swatch-radius
+    default: 4px
+    description: Swatch corner radius.
+composition:
+  parents:
+    - aui-field
+    - aui-stack
+    - aui-container
+    - div
+  children: []
+  context: |
+    Typically used inside aui-field for labeled color entry. Pairs with aui-color-area and aui-color-slider in color pickers.
+examples:
+  - description: Hex color value
+    html: <aui-color-field value="#3b82f6"></aui-color-field>
+  - description: Another hex color
+    html: |-
+      <aui-color-field value="#10b981"></aui-color-field>
+
+      <!-- ===============================================================
+           FORMATS
+           =============================================================== -->
+  - description: RGB format
+    html: <aui-color-field value="rgb(59, 130, 246)" format="rgb"></aui-color-field>
+  - description: OKLCH format
+    html: <aui-color-field value="oklch(0.65 0.2 250)" format="oklch"></aui-color-field>
+  - description: HSL format
+    html: |-
+      <aui-color-field value="hsl(220, 90%, 60%)"></aui-color-field>
+
+      <!-- ===============================================================
+           EMPTY STATE
+           =============================================================== -->
+  - description: Empty color field (shows placeholder)
+    html: |-
+      <aui-color-field></aui-color-field>
+
+      <!-- ===============================================================
+           DISABLED
+           =============================================================== -->
+  - description: Disabled color field
+    html: |-
+      <aui-color-field value="#ef4444" disabled></aui-color-field>
+
+      <!-- ===============================================================
+           GROUP -- multiple color fields
+           =============================================================== -->
+  - description: Row of color fields for a palette
+    html: |-
+      <aui-stack direction="row" gap="3">
+        <aui-color-field value="#ef4444"></aui-color-field>
+        <aui-color-field value="#f59e0b"></aui-color-field>
+        <aui-color-field value="#10b981"></aui-color-field>
+        <aui-color-field value="#3b82f6"></aui-color-field>
+      </aui-stack>
+
+      <!-- ===============================================================
+           IN FORM FIELD
+           =============================================================== -->
+  - description: Color field inside aui-field with label
+    html: |-
+      <aui-field label="Brand Color">
+        <aui-color-field value="#6366f1"></aui-color-field>
+      </aui-field>