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

package/dist/docs/components/chip.yaml

@@ -0,0 +1,125 @@
+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.
+base: AgentElement
+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:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: default
+    values:
+      - sm
+    description: Compact variant with smaller padding and font.
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: neutral
+    values:
+      - accent
+      - success
+      - warning
+      - danger
+    description: Tinted background and text color.
+content:
+  model: inline
+  accepts:
+    - text
+    - aui-icon
+  required: true
+  description: |
+    Short label text. May include a leading aui-icon. Keep concise.
+slots:
+  default:
+    accepts:
+      - text
+      - aui-icon
+    required: true
+    description: Chip label. Icons allowed before text.
+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:
+  - 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>
+        Label
+      </aui-chip>
+
+      <!-- ===============================================================
+           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

@@ -0,0 +1,127 @@
+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.
+base: AgentElement
+attributes:
+  language:
+    syntax: key-value
+    type: string
+    default: ""
+    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.
+  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.
+  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: text
+  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.
+tokens:
+  - name: --aui-code-block-background
+    default: var(--aui-control)
+    description: Header background color.
+  - name: --aui-code-block-border
+    default: var(--aui-border-muted)
+    description: Border color for the outer container and header divider.
+  - name: --aui-code-block-border-radius
+    default: var(--aui-radius)
+    description: Corner radius of the outer container.
+  - name: --aui-code-block-header-font-size
+    default: var(--aui-font-xs)
+    description: Font size of the header label text.
+  - name: --aui-code-block-header-color
+    default: var(--aui-ink-muted)
+    description: Text color of the header label.
+  - name: --aui-code-block-header-padding
+    default: calc(var(--aui-space) * 2) calc(var(--aui-space) * 3)
+    description: Padding inside the header bar.
+  - name: --aui-code-block-copy-color
+    default: var(--aui-ink-muted)
+    description: Copy button text color.
+  - name: --aui-code-block-copy-color-hover
+    default: var(--aui-ink)
+    description: Copy button text color on hover.
+a11y:
+  role: figure
+  aria:
+    aria-label: Set from language or filename when present.
+use-cases:
+  - Code snippets in documentation pages.
+  - Chat message code blocks in agent conversations.
+  - Copyable terminal commands.
+  - File previews with filename headers.
+examples:
+  - 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: 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: 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: 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>

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

@@ -0,0 +1,104 @@
+name: aui-color-picker
+tag: aui-color-picker
+type: component
+summary: Compound OKLCH color picker composing area, labeled slider rows, and output copy buttons.
+description: |
+  A unified color picker using OKLCH as the native internal color model. Stamps and syncs:
+  - aui-color-area (2D chroma+lightness surface)
+  - Four labeled slider rows (H/C/L/A) each showing [label][slider][value]
+  - Two output rows with OKLCH string + hex string and aui-copy-button for each
+
+  All sub-components sync bidirectionally — changing any part updates the others. Parses both oklch() and hex color values as input, converting internally to OKLCH. The alpha slider row is hidden unless the `alpha` attribute is set.
+base: AgentElement
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: "#000000"
+    description: Current color value. Accepts oklch() string or hex format.
+  format:
+    syntax: key-value
+    type: string
+    default: oklch
+    description: Primary output format (oklch or hex). Controls the value attribute serialization.
+  alpha:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Show the alpha transparency slider row.
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Disables all sub-components.
+tokens:
+  - name: --aui-color-picker-gap
+    default: calc(var(--aui-space) * 2)
+    description: Gap between the area, slider block, and output block.
+  - name: --aui-color-picker-area-height
+    default: 10rem
+    description: Height of the color area surface.
+  - name: --aui-color-picker-width
+    default: 16rem
+    description: Width of the entire picker.
+  - name: --aui-color-picker-slider-height
+    default: 16px
+    description: Height of the slider tracks.
+  - name: --aui-color-picker-border-radius
+    default: var(--aui-radius)
+    description: Border radius for area, slider tracks, and output rows.
+internal-structure:
+  - element: aui-color-area
+    attr: data-color-picker-area
+    description: 2D chroma+lightness picking surface.
+  - element: div
+    attr: data-color-picker-sliders
+    description: Container for the four slider rows.
+  - element: div
+    attr: data-color-picker-slider-row
+    description: Single row containing [label][slider][value].
+  - element: span
+    attr: data-color-picker-slider-label
+    description: Single-character channel label (H, C, L, A). Mono font.
+  - element: span
+    attr: data-color-picker-slider-value
+    description: Numeric readout for the slider value. Mono font.
+  - element: div
+    attr: data-color-picker-output
+    description: Container for OKLCH and hex output rows.
+  - element: div
+    attr: data-color-picker-output-group
+    description: Single output row with value text and copy button.
+  - element: span
+    attr: data-color-picker-value
+    description: Formatted color string (OKLCH or hex).
+  - element: aui-copy-button
+    description: Copy button for the adjacent color string (size="sm").
+a11y:
+  role: group
+  keyboard:
+    ArrowKeys: Control the active sub-component (area or slider).
+events:
+  change:
+    description: |
+      Fired when the color changes via any sub-component. Detail contains { value, l, c, h, a }.
+dependencies:
+  - aui-color-area
+  - aui-color-slider
+  - aui-copy-button
+composition:
+  parents:
+    - aui-container
+    - any
+  children: []
+examples:
+  - description: Basic color picker with initial blue value (hex input)
+    html: <aui-color-picker value="#3b82f6"></aui-color-picker>
+  - description: Color picker with OKLCH input
+    html: <aui-color-picker value="oklch(0.65 0.2 250)"></aui-color-picker>
+  - description: Color picker with alpha transparency slider
+    html: <aui-color-picker value="oklch(0.65 0.2 15 / 0.8)" alpha></aui-color-picker>
+  - description: Color picker with hex format output
+    html: <aui-color-picker value="#10b981" format="hex"></aui-color-picker>
+  - description: Disabled color picker
+    html: <aui-color-picker value="#10b981" disabled></aui-color-picker>