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

package/dist/docs/components/preview-app.yaml

@@ -0,0 +1,170 @@
+name: aui-preview-app
+tag: aui-preview-app
+type: component
+summary: Full-screen preview shell with navigation, command palette, and pannable canvas.
+description: >
+  Top-level application shell for browsing block, component, and trait
+  previews. Fetches a preview.json manifest, renders a nav bar with
+  section select and color-scheme toggle, and loads each preview item
+  into an aui-editor pannable canvas. Includes a Cmd+K command palette
+  for fuzzy-finding items and Alt+Arrow keyboard navigation for
+  stepping through the item list. Each loaded preview's children are
+  absolutely positioned, given drag and resize traits, and centered
+  on the canvas automatically.
+
+base: AgentElement
+
+attributes:
+  src:
+    syntax: key-value
+    type: string
+    default: "./preview.json"
+    description: >
+      URL to the preview.json manifest file. Resolved relative to the
+      page. The directory containing this file becomes the base path
+      for resolving item HTML, CSS, and TS files.
+
+preview-json:
+  description: >
+    JSON manifest that drives the preview app. Must live at the URL
+    specified by the src attribute.
+  format: |
+    {
+      "section": "blocks",
+      "param": "block",
+      "items": [
+        {
+          "slug": "agent-chat",
+          "name": "agent-chat",
+          "file": "agent-chat/agent-chat.html",
+          "group": "Chat",
+          "summary": "Full chat interface block",
+          "category": "messaging"
+        }
+      ],
+      "links": [
+        { "label": "Components", "href": "../components/preview.html" }
+      ]
+    }
+  fields:
+    section:
+      type: string
+      description: >
+        Human-readable section name (e.g. "blocks", "components", "traits").
+        Used for the page select placeholder and document title.
+    param:
+      type: string
+      description: >
+        URL search parameter name used to track the current item
+        (e.g. "block" produces ?block=agent-chat).
+    items:
+      type: array
+      description: >
+        Ordered list of preview items. Each item has a slug (unique ID),
+        name (display label), and optional file (relative path to the
+        .html file, defaults to "{slug}/{slug}.html"). Optional group
+        for optgroup headings, summary for command palette search
+        keywords, and category for classification.
+    links:
+      type: array
+      description: >
+        Cross-section navigation links shown at the top of both the
+        page select dropdown and the command palette. Each entry has
+        a label and href.
+
+features:
+  - "Cmd/Ctrl+K command palette with fuzzy search across all items and section links"
+  - "Alt+ArrowLeft / Alt+ArrowRight navigates to previous/next item (wraps around)"
+  - "Color scheme toggle (light/dark) persisted to localStorage under aui-preview-scheme"
+  - "aui-editor canvas with dot background for pan/zoom of loaded previews"
+  - "Auto-centers content on the canvas after load"
+  - "Each preview child gets drag (free mode) and resize traits attached automatically"
+  - "Loads per-item CSS and TS modules dynamically alongside HTML content"
+  - "Section links for cross-navigation between blocks, components, and traits"
+  - "Grouped items via optgroup in both page select and command palette"
+  - "URL-driven state: current item stored as a query parameter"
+
+internal-structure:
+  navbar:
+    element: div[data-role="navbar"]
+    description: >
+      Absolutely positioned top bar containing an aui-select in bar
+      mode. Holds the logo link, color scheme toggle button, and the
+      page select dropdown. pointer-events: none on the wrapper with
+      pointer-events: auto on children so the canvas remains pannable
+      through empty nav space.
+
+  canvas:
+    element: aui-editor[data-role="canvas"]
+    description: >
+      Full-viewport aui-editor with background="dots". Contains a
+      single aui-editor-layer named "content" which holds a
+      div[data-role="content"] where preview HTML is injected.
+
+  command-palette:
+    element: aui-dialog > aui-command
+    description: >
+      A small aui-dialog (size="sm") positioned at 20% from top,
+      containing an aui-command with input, grouped list of all items
+      and section links, and an empty state. Opened/closed via Cmd+K.
+      Selecting an item navigates by updating the URL query parameter.
+
+  empty-state:
+    element: div[data-role="empty"]
+    description: >
+      Shown when no item is selected. Centered text prompting the
+      user to select from the section.
+
+item-loading:
+  description: >
+    When an item is selected, the component resolves three files
+    relative to the preview.json base path. The item's file field
+    (or default "{slug}/{slug}.html") provides the HTML. CSS is
+    loaded as "{dir}/{dir}.css" via a <link> appended to <head>.
+    TS is imported as "{dir}/{dir}.ts" via dynamic import. HTML
+    content children are measured, positioned absolutely with a
+    40px gap, and given drag and resize traits via attachTrait().
+
+a11y:
+  role: No implicit role. Acts as a full-screen application shell.
+  keyboard:
+    "Cmd/Ctrl+K": Toggle command palette open/closed.
+    "Alt+ArrowLeft": Navigate to previous item (wraps to last).
+    "Alt+ArrowRight": Navigate to next item (wraps to first).
+    Escape: Close command palette (delegated to aui-dialog native behavior).
+
+composition:
+  parents: [body, div]
+  children: [internal -- all DOM is stamped by the component]
+  context: >
+    Place as the sole child of <body> for a full-screen preview
+    experience. The component manages its own layout (position: fixed,
+    inset: 0) and stamps all internal structure on activation.
+
+tokens:
+  color:
+    - --aui-doc
+    - --aui-ink
+    - --aui-ink-muted
+    - --aui-ink-strong
+    - --aui-border-muted
+    - --aui-focus
+  typography:
+    - --aui-font-family
+    - --aui-font-size
+    - --aui-font-sm
+    - --aui-font-weight-semibold
+
+examples:
+  - html: |
+      <aui-preview-app src="./preview.json"></aui-preview-app>
+    description: >
+      Standard usage. Place in an HTML page alongside the preview.json
+      manifest. The component fetches the manifest and renders the full
+      preview shell.
+
+  - html: |
+      <aui-preview-app src="/blocks/preview.json"></aui-preview-app>
+    description: >
+      Absolute path to a manifest in a different directory. Useful
+      when the preview page is not co-located with the manifest.

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

@@ -0,0 +1,108 @@
+name: aui-radio-group
+tag: aui-radio-group
+type: component
+summary: Container that coordinates radio button selection.
+description: >
+  Wraps aui-radio children and manages single-selection, name
+  propagation, and arrow-key navigation. Set value to pre-select
+  an option.
+
+base: AgentElement
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: Cascades size to all child radios.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values: [accent, info, success, warning, danger]
+    description: Cascades color family to all child radios.
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Disables all child radios.
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Form group name. Propagated to all child aui-radio elements.
+
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Currently selected value. Setting this checks the matching
+      child radio and unchecks others.
+
+content:
+  model: block
+  accepts: [aui-radio]
+  required: true
+  min-children: 2
+  description: Two or more aui-radio children.
+
+composition:
+  parents: [aui-field, aui-stack, form, div]
+  children: [aui-radio]
+  context: >
+    Use inside aui-field for labeled radio groups. The group
+    handles keyboard navigation (arrow keys cycle through options)
+    and single-selection enforcement.
+
+a11y:
+  role: radiogroup
+  keyboard:
+    ArrowDown: Select next radio.
+    ArrowRight: Select next radio.
+    ArrowUp: Select previous radio.
+    ArrowLeft: Select previous radio.
+
+events:
+  change:
+    description: >
+      Bubbles from the selected child radio. Read the group's
+      value attribute for the current selection.
+
+tokens:
+  spacing:
+    - --aui-space
+
+examples:
+  - html: |
+      <aui-radio-group name="size" value="md">
+        <aui-radio label="Small" value="sm"></aui-radio>
+        <aui-radio label="Medium" value="md"></aui-radio>
+        <aui-radio label="Large" value="lg"></aui-radio>
+      </aui-radio-group>
+    description: Radio group with pre-selected value.
+
+  - html: |
+      <aui-field label="Plan">
+        <aui-radio-group name="plan">
+          <aui-radio label="Free" value="free"></aui-radio>
+          <aui-radio label="Pro" value="pro"></aui-radio>
+          <aui-radio label="Enterprise" value="enterprise"></aui-radio>
+        </aui-radio-group>
+      </aui-field>
+    description: Radio group inside a labeled field.
+
+  - html: |
+      <aui-radio-group name="status" disabled>
+        <aui-radio label="Active" value="active"></aui-radio>
+        <aui-radio label="Inactive" value="inactive"></aui-radio>
+      </aui-radio-group>
+    description: Disabled radio group.

package/dist/docs/components/radio.yaml

@@ -0,0 +1,132 @@
+name: aui-radio
+tag: aui-radio
+type: component
+summary: Radio button with custom circle indicator.
+description: >
+  Custom radio button. Hidden native input for form participation.
+  Visual circle with dot indicator via ::before. Label rendered via
+  CSS ::after { content: attr(label) } — JS only sets aria-label
+  for accessibility, no DOM stamping for the visible label. Use
+  inside aui-radio-group for coordinated single-selection.
+
+base: AgentElement
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: Controls radio and label size.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values: [accent, info, success, warning, danger]
+    description: Color family for the selected state.
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction.
+
+  checked:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether this radio is selected.
+
+  required:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Marks as required for form validation.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Label text next to the radio.
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form group name. Usually set by parent aui-radio-group.
+
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form submission value for this option.
+
+content:
+  model: inline
+  accepts: [input]
+  required: false
+  description: >
+    Auto-stamps hidden input for form participation. Label is
+    rendered purely via CSS ::after on :scope — no stamped span.
+
+composition:
+  parents: [aui-radio-group, aui-field, aui-stack, form, div]
+  children: null
+  context: >
+    Almost always used inside aui-radio-group which handles
+    name propagation, single-selection, and keyboard navigation.
+
+constraints:
+  - when: standalone (no aui-radio-group parent)
+    require: name attribute
+    reason: Radios need a shared name for browser grouping.
+
+a11y:
+  role: radio
+  keyboard:
+    Space: Selects this radio.
+    Enter: Selects this radio.
+  aria:
+    aria-checked: Mirrors checked attribute.
+    aria-disabled: Mirrors disabled attribute.
+
+events:
+  change:
+    description: Fires when this radio becomes selected.
+
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-widget-size
+    - --aui-font-size
+  color:
+    - --aui-ink
+    - --aui-control
+    - --aui-fill
+    - --aui-stroke
+    - --aui-solid
+    - --aui-focus
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+css-notes:
+  attr-audit:
+    - "AB1: [checked], [disabled] — visual state via attributes"
+    - "CG2: ::before on [data-circle] for dot indicator"
+    - "CG3: ::after { content: attr(label) } — label rendered in CSS, overflow: hidden on ::after only"
+    - "CG4: gap uses 2 * space (tightened from 3 * space)"
+
+examples:
+  - html: <aui-radio label="Option A" value="a"></aui-radio>
+    description: Default unchecked radio.
+
+  - html: <aui-radio label="Option B" value="b" checked></aui-radio>
+    description: Pre-selected radio.
+
+  - html: <aui-radio label="Unavailable" disabled></aui-radio>
+    description: Disabled radio.

package/dist/docs/components/range.yaml

@@ -0,0 +1,97 @@
+name: aui-range
+tag: aui-range
+type: component
+summary: Slider control with custom track and thumb.
+description: >
+  A range slider that wraps a native input[type="range"] for form
+  participation and full keyboard/ARIA support. The wrapper renders
+  a custom track, fill, and wide iOS-style thumb contained within the
+  track — the native input is visually hidden. The thumb uses a scaleX
+  animation on press (:active) with transform-origin: center for
+  centered scaling.
+
+base: AgentElement
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+
+  min:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: Minimum value.
+
+  max:
+    syntax: key-value
+    type: string
+    default: "100"
+    description: Maximum value.
+
+  step:
+    syntax: key-value
+    type: string
+    default: "1"
+    description: Step increment.
+
+  value:
+    syntax: key-value
+    type: string
+    default: "50"
+    description: Current value.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Accessible label (maps to aria-label on the native input).
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form field name.
+
+a11y:
+  role: slider (via native input)
+  keyboard:
+    ArrowLeft: Decrease by step.
+    ArrowRight: Increase by step.
+    Home: Set to min.
+    End: Set to max.
+  aria:
+    aria-label: Set from label attribute.
+
+form:
+  associated: true
+  value: Current slider value.
+
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-widget-size
+  spacing:
+    - --aui-pad-control-block
+  color:
+    - --aui-control
+    - --aui-fill
+    - --aui-stroke
+    - --aui-solid
+    - --aui-focus
+  shape:
+    - --aui-radius-round
+  motion:
+    - --aui-easing
+
+examples:
+  - html: <aui-range></aui-range>
+    description: Default slider (0–100, value 50).
+
+  - html: <aui-range min="0" max="10" step="1" value="3" label="Volume"></aui-range>
+    description: Slider with custom range and label.
+
+  - html: <aui-range disabled value="75"></aui-range>
+    description: Disabled slider.

package/dist/docs/components/root.yaml

@@ -0,0 +1,18 @@
+name: aui-root
+tag: aui-root
+type: component
+summary: App shell root container
+base: AgentElement
+composition:
+  parents: [body]
+  children: [aui-header, aui-content, aui-footer, aui-panes, any]
+examples:
+  - html: |
+      <aui-container bordered style="min-height: 12rem;">
+        <aui-header><span>App Title</span></aui-header>
+        <aui-content><aui-inset><p>Main content area</p></aui-inset></aui-content>
+        <aui-footer><span slot="leading">v0.1</span></aui-footer>
+      </aui-container>
+    description: >
+      App shell structure (shown via aui-container for inline preview).
+      In use, wrap with aui-root at the document body level.

package/dist/docs/components/segment.yaml

@@ -0,0 +1,41 @@
+name: aui-segment
+tag: aui-segment
+type: component
+summary: Individual toggle within a segmented control.
+description: >
+  A single option within aui-segmented-control. Uses radio role
+  for accessibility. Selection coordinated by parent.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Segment identifier.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents selection.
+
+  selected:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether this segment is active.
+
+a11y:
+  role: radio
+  aria:
+    aria-checked: Reflects selected state.
+
+composition:
+  parents: [aui-segmented-control]
+  children: null
+
+examples:
+  - html: <aui-segment value="list">List</aui-segment>
+    description: Simple segment.

package/dist/docs/components/segmented-control.yaml

@@ -0,0 +1,52 @@
+name: aui-segmented-control
+tag: aui-segmented-control
+type: component
+summary: Toggle between mutually exclusive options.
+description: >
+  A radiogroup-style control for switching between views or values.
+  Contains aui-segment children. Selected segment gets a raised
+  pill appearance.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Currently selected segment value.
+
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Form field name.
+
+a11y:
+  role: radiogroup
+  keyboard:
+    ArrowRight: Select next segment.
+    ArrowLeft: Select previous segment.
+    Home: Select first segment.
+    End: Select last segment.
+
+events:
+  change:
+    description: Fired when selection changes. detail.value is the new value.
+
+form:
+  associated: true
+  value: Selected segment value.
+
+composition:
+  parents: [any]
+  children: [aui-segment]
+
+examples:
+  - html: |
+      <aui-segmented-control value="list">
+        <aui-segment value="list" selected>List</aui-segment>
+        <aui-segment value="grid">Grid</aui-segment>
+        <aui-segment value="board">Board</aui-segment>
+      </aui-segmented-control>
+    description: View mode toggle.