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

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

@@ -1,78 +1,130 @@
 name: aui-color-picker
 tag: aui-color-picker
 type: component
-summary: Compound color picker composing area, sliders, and field.
-description: >
-  A unified color picker that stamps and syncs aui-color-area,
-  aui-color-slider (hue + optional alpha), and aui-color-field
-  sub-components. All sub-components sync bidirectionally — changing
-  any part updates the others. Parses and serializes hex color values
-  internally, converting to/from HSL for the area and slider controls.
+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 in hex format.
+    description: Current color value. Accepts oklch() string or hex format.
   format:
     syntax: key-value
     type: string
-    default: "hex"
-    description: Display format for the color field (hex, rgb, oklch).
-  show-alpha:
+    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.
+    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 sub-components.
+    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: 14rem
+    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, slider, or field).
-
+    ArrowKeys: Control the active sub-component (area or slider).
 events:
   change:
-    description: >
-      Fired when the color changes via any sub-component.
-      Detail contains { value, h, s, l, a }.
-
+    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-color-field
-
+  - aui-copy-button
 composition:
-  parents: [aui-container, any]
+  parents:
+    - aui-container
+    - any
   children: []
-
 examples:
-  - html: |
-      <aui-color-picker value="#3b82f6"></aui-color-picker>
-    description: Basic color picker with initial blue value.
+  - description: Basic color picker with hex input (blue)
+    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>
 
-  - html: |
-      <aui-color-picker value="#ef444480" show-alpha></aui-color-picker>
-    description: Color picker with alpha transparency slider.
+      <!-- ===============================================================
+           ALPHA
+           =============================================================== -->
+  - description: Color picker with alpha slider row visible
+    html: |-
+      <aui-color-picker value="oklch(0.65 0.2 15 / 0.8)" alpha></aui-color-picker>
 
-  - html: |
+      <!-- ===============================================================
+           HEX OUTPUT FORMAT
+           =============================================================== -->
+  - description: Color picker serializing value as hex
+    html: |-
+      <aui-color-picker value="#10b981" format="hex"></aui-color-picker>
+
+      <!-- ===============================================================
+           DISABLED
+           =============================================================== -->
+  - description: Disabled color picker
+    html: |-
       <aui-color-picker value="#10b981" disabled></aui-color-picker>
-    description: Disabled color picker.
+
+      <!-- ===============================================================
+           MULTIPLE PICKERS
+           =============================================================== -->
+  - description: Two pickers side by side for comparison
+    html: |-
+      <div style="display: flex; gap: 2rem;">
+        <aui-color-picker value="oklch(0.7 0.25 145)"></aui-color-picker>
+        <aui-color-picker value="oklch(0.55 0.22 300)" alpha></aui-color-picker>
+      </div>

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

@@ -0,0 +1,153 @@
+name: aui-color-slider
+tag: aui-color-slider
+type: component
+summary: Single-axis gradient slider for an OKLCH color channel (hue, chroma, lightness, or alpha).
+description: |
+  A one-dimensional slider that controls a specific OKLCH color channel. The track renders a computed gradient using hex color stops for the selected channel:
+  - **hue** — perceptual rainbow at current lightness and chroma (0-360, step 1)
+  - **chroma** — saturation range at current L and H (0-0.4, step 0.004)
+  - **lightness** — luminance range at current C and H (0-1, step 0.01)
+  - **alpha** — transparency gradient over checkerboard at current color (0-1, step 0.01)
+
+  Pointer drag and keyboard arrow navigation with Shift for 10x step. Values are snapped to the channel step size.
+base: AgentElement
+attributes:
+  channel:
+    syntax: key-value
+    type: string
+    default: hue
+    description: Which color channel to control (hue, chroma, lightness, alpha).
+  value:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: Current channel value.
+  min:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Minimum value. Defaults to channel minimum (0).
+  max:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Maximum value. Defaults to channel maximum (360 for hue, 0.4 for chroma, 1 for lightness/alpha).
+  hue:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: Reference hue for gradient rendering (used by chroma/lightness/alpha channels).
+  chroma:
+    syntax: key-value
+    type: string
+    default: "0.15"
+    description: Reference chroma for gradient rendering (used by hue/lightness/alpha channels).
+  lightness:
+    syntax: key-value
+    type: string
+    default: "0.65"
+    description: Reference lightness for gradient rendering (used by hue/chroma/alpha channels).
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+a11y:
+  role: slider (on thumb element)
+  keyboard:
+    ArrowRight: "Increase by step (Shift: 10x)."
+    ArrowLeft: "Decrease by step (Shift: 10x)."
+    Home: Set to minimum.
+    End: Set to maximum.
+  aria:
+    aria-valuenow: Current value.
+    aria-valuemin: Channel minimum.
+    aria-valuemax: Channel maximum.
+    aria-label: Channel name (capitalized).
+tokens:
+  - name: --aui-color-slider-height
+    default: var(--aui-color-picker-slider-height, 16px)
+    description: Total height of the slider.
+  - name: --aui-color-slider-track-radius
+    default: var(--aui-color-picker-border-radius, var(--aui-radius-sm, 4px))
+    description: Track corner radius.
+  - name: --aui-color-slider-thumb-size
+    default: 16px
+    description: Thumb diameter.
+  - name: --aui-color-slider-thumb-border
+    default: 2px solid white
+    description: Thumb border.
+  - name: --aui-color-slider-thumb-shadow
+    default: 0 0 0 1px rgba(0,0,0,0.3), 0 1px 3px rgba(0,0,0,0.2)
+    description: Thumb drop shadow.
+internal-structure:
+  - element: div
+    attr: data-color-slider-track
+    description: Gradient track element. Background set dynamically via computed hex stops.
+  - element: div
+    attr: data-color-slider-thumb
+    description: Draggable thumb positioned via --_pct custom property.
+composition:
+  parents:
+    - aui-color-picker
+    - aui-stack
+    - aui-container
+    - div
+  children: []
+  context: |
+    Used inside aui-color-picker in labeled rows (H/C/L/A). Multiple sliders can also be stacked independently for individual channel editing.
+examples:
+  - description: Hue slider (0-360 at L=0.65 C=0.15)
+    html: <aui-color-slider channel="hue" value="250" lightness="0.65" chroma="0.15"></aui-color-slider>
+  - description: Hue slider at 0 (red)
+    html: |-
+      <aui-color-slider channel="hue" value="0" lightness="0.65" chroma="0.2"></aui-color-slider>
+
+      <!-- ===============================================================
+           CHROMA CHANNEL
+           =============================================================== -->
+  - description: Chroma slider at hue 250
+    html: <aui-color-slider channel="chroma" value="0.2" hue="250" lightness="0.65"></aui-color-slider>
+  - description: Chroma slider at hue 145 (green)
+    html: |-
+      <aui-color-slider channel="chroma" value="0.18" hue="145" lightness="0.7"></aui-color-slider>
+
+      <!-- ===============================================================
+           LIGHTNESS CHANNEL
+           =============================================================== -->
+  - description: Lightness slider at hue 250
+    html: |-
+      <aui-color-slider channel="lightness" value="0.65" hue="250" chroma="0.2"></aui-color-slider>
+
+      <!-- ===============================================================
+           ALPHA CHANNEL
+           =============================================================== -->
+  - description: Alpha slider with checkerboard
+    html: |-
+      <aui-color-slider channel="alpha" value="0.8" hue="250" chroma="0.2" lightness="0.65"></aui-color-slider>
+
+      <!-- ===============================================================
+           CUSTOM WIDTH
+           =============================================================== -->
+  - description: Full-width hue slider
+    html: |-
+      <aui-color-slider channel="hue" value="200" lightness="0.65" chroma="0.15" width="full"></aui-color-slider>
+
+      <!-- ===============================================================
+           DISABLED
+           =============================================================== -->
+  - description: Disabled hue slider
+    html: |-
+      <aui-color-slider channel="hue" value="250" lightness="0.65" chroma="0.15" disabled></aui-color-slider>
+
+      <!-- ===============================================================
+           GROUP -- all channels together
+           =============================================================== -->
+  - description: All four OKLCH channel sliders together
+    html: |-
+      <aui-stack gap="3" style="min-width: 20rem;">
+        <aui-color-slider channel="hue" value="250" lightness="0.65" chroma="0.2" width="full"></aui-color-slider>
+        <aui-color-slider channel="chroma" value="0.2" hue="250" lightness="0.65" width="full"></aui-color-slider>
+        <aui-color-slider channel="lightness" value="0.65" hue="250" chroma="0.2" width="full"></aui-color-slider>
+        <aui-color-slider channel="alpha" value="1" hue="250" chroma="0.2" lightness="0.65" width="full"></aui-color-slider>
+      </aui-stack>

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

@@ -0,0 +1,98 @@
+name: aui-color-swatch
+tag: aui-color-swatch
+type: element
+summary: Color preview square with checkerboard transparency support.
+description: |
+  CSS-only element that renders a small color preview with a checkerboard background for transparency support. Use in color palettes, swatch pickers, and color field previews. Color is set via --aui-color-swatch-value custom property.
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: md
+    values:
+      - sm
+      - md
+      - lg
+    description: |
+      Swatch dimensions. sm = 16px, md = 24px (default), lg = 32px.
+modifiers:
+  round:
+    syntax: boolean
+    description: |
+      Renders as a circle instead of a rounded square.
+  selected:
+    syntax: boolean
+    description: |
+      Shows a selection ring around the swatch using box-shadow with accent color.
+custom_properties:
+  --aui-color-swatch-value:
+    default: transparent
+    description: The color to display in the swatch.
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: |
+    No content — swatch is a visual indicator only. Color is set via the --aui-color-swatch-value custom property.
+composition:
+  parents:
+    - aui-stack
+    - aui-wrap
+    - aui-grid
+    - div
+  children: null
+  context: |
+    Use in color palette grids, inline color previews, and swatch picker rows. Group multiple swatches in aui-wrap for wrapping palette layouts.
+tokens:
+  sizing:
+    - width / height (16px, 24px, 32px)
+  color:
+    - --aui-border
+    - --aui-control
+    - --aui-surface
+    - --aui-accent-500
+    - --aui-color-swatch-value
+  shape:
+    - --aui-radius-sm
+examples:
+  - description: Basic blue swatch
+    html: '<aui-color-swatch style="--aui-color-swatch-value: #3b82f6"></aui-color-swatch>'
+  - description: Color palette row
+    html: |-
+      <aui-wrap gap="2">
+        <aui-color-swatch style="--aui-color-swatch-value: #ef4444"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #f97316"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #eab308"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #22c55e"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #3b82f6"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #a855f7"></aui-color-swatch>
+      </aui-wrap>
+  - description: Round swatches
+    html: |-
+      <aui-wrap gap="2">
+        <aui-color-swatch round style="--aui-color-swatch-value: #ef4444"></aui-color-swatch>
+        <aui-color-swatch round style="--aui-color-swatch-value: #3b82f6"></aui-color-swatch>
+        <aui-color-swatch round style="--aui-color-swatch-value: #22c55e"></aui-color-swatch>
+      </aui-wrap>
+  - description: All three sizes
+    html: |-
+      <aui-wrap gap="2">
+        <aui-color-swatch size="sm" style="--aui-color-swatch-value: #3b82f6"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #3b82f6"></aui-color-swatch>
+        <aui-color-swatch size="lg" style="--aui-color-swatch-value: #3b82f6"></aui-color-swatch>
+      </aui-wrap>
+  - description: Transparent colors showing checkerboard
+    html: |-
+      <aui-wrap gap="2">
+        <aui-color-swatch style="--aui-color-swatch-value: rgba(59, 130, 246, 0.5)"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: rgba(239, 68, 68, 0.3)"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: transparent"></aui-color-swatch>
+      </aui-wrap>
+  - description: Selected state with accent ring
+    html: |-
+      <aui-wrap gap="2">
+        <aui-color-swatch selected style="--aui-color-swatch-value: #3b82f6"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #ef4444"></aui-color-swatch>
+        <aui-color-swatch style="--aui-color-swatch-value: #22c55e"></aui-color-swatch>
+      </aui-wrap>

package/dist/docs/components/command.yaml

@@ -2,14 +2,9 @@ name: aui-command
 tag: aui-command
 type: component
 summary: Command palette with search, keyboard navigation, and grouping.
-description: >
-  Root component for the command palette. Composes aui-command-input
-  (search), aui-command-list (scrollable results), aui-command-item
-  (actions), aui-command-group (grouping), and aui-command-empty
-  (no results). Place inside aui-dialog for modal usage.
-
+description: |
+  Root component for the command palette. Composes aui-command-input (search), aui-command-list (scrollable results), aui-command-item (actions), aui-command-group (grouping), and aui-command-empty (no results). Place inside aui-dialog for modal usage.
 base: AgentElement
-
 a11y:
   role: search
   keyboard:
@@ -19,13 +14,11 @@ a11y:
     End: Highlight last item.
     Enter: Select highlighted item.
     Escape: Dismiss (fires dismiss event).
-
 events:
   select:
     description: Fired when an item is selected. detail contains value, label, item.
   dismiss:
     description: Fired on Escape key. Parent dialog can listen to close.
-
 tokens:
   - name: --aui-command-background
     default: var(--aui-modal, var(--aui-doc))
@@ -42,13 +35,17 @@ tokens:
   - name: --aui-command-gap
     default: var(--aui-space)
     description: Gap between command palette sections.
-
 composition:
-  parents: [aui-dialog, any]
-  children: [aui-command-input, aui-command-list, aui-command-empty]
-
+  parents:
+    - aui-dialog
+    - any
+  children:
+    - aui-command-input
+    - aui-command-list
+    - aui-command-empty
 examples:
-  - html: |
+  - description: Command palette with grouped items and search
+    html: |-
       <aui-command max-width="prose">
         <aui-command-input placeholder="Type a command…"></aui-command-input>
         <aui-command-list>
@@ -65,9 +62,8 @@ examples:
         </aui-command-list>
         <aui-command-empty>No results found.</aui-command-empty>
       </aui-command>
-    description: Command palette with grouped items and search.
-
-  - html: |
+  - description: Simple flat command palette
+    html: |-
       <aui-command max-width="md">
         <aui-command-input placeholder="Search actions…"></aui-command-input>
         <aui-command-list>
@@ -78,4 +74,3 @@ examples:
         </aui-command-list>
         <aui-command-empty>No matching commands.</aui-command-empty>
       </aui-command>
-    description: Simple flat command palette.