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

package/dist/docs/components/button.yaml

@@ -0,0 +1,439 @@
+name: aui-button
+tag: aui-button
+type: component
+summary: Polymorphic action trigger with press semantics and resize-responsive collapse.
+description: >
+  The foundational interactive element. Uses inline-flex layout with a
+  CSS-generated label (::after { content: attr(label) }). Supports solid,
+  outline, ghost, and scrim variants across all intent families. Renders as
+  a button by default; set href to switch to link mode. Icon-only mode
+  available via the hide-label attribute. Icons are stamped as
+  <aui-icon slot="leading/trailing"> by JS from icon-leading / icon-trailing
+  attributes. Text adornments are stamped as <span slot="leading-text/trailing-text">
+  from text-leading / text-trailing attributes. The component auto-detects
+  icon-only state when no label attribute and no child text nodes are present.
+  Progressive collapse via the resize trait hides adornments as the
+  container shrinks.
+
+base: AgentElement
+
+# ── Layout ───────────────────────────────────────────────
+# Button uses inline-flex (not inline-grid).
+# Label text is rendered via CSS ::after { content: attr(label) } — no JS stamping.
+# Height is fixed at var(--aui-size), min-width at var(--aui-size).
+# Padding: padding-block var(--aui-pad-control-block), padding-inline calc(var(--aui-space) * 3).
+
+# ── Presentational attributes ─────────────────────────────
+# Boolean HTML attributes. Each group is mutually exclusive.
+# All cascade to descendants via CSS custom property inheritance.
+# Default appearance = absence of attribute (no "medium", no "neutral").
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: >
+      Controls dimensions, typography, icon size, and spacing
+      simultaneously. Swaps 7 tokens at once.
+
+  radius:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: medium
+    values: [sharp, round]
+    description: Controls border radius. Default is a medium radius.
+
+  density:
+    syntax: key-value
+    attribute: density
+    cascades: true
+    default: regular
+    values: [compact, spacious]
+    description: >
+      Controls padding and spacing compression. Unlike size (which
+      shifts the active step), density redefines the entire scale.
+
+  variant:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: default
+    values: [primary, outline, ghost, scrim]
+    description: >
+      Surface expression — how the component fills its space.
+      Default is a standard fill with role-appropriate background.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: true
+    default: neutral
+    values: [accent, info, success, warning, danger]
+    description: >
+      Color family. All color tokens remap to the selected palette.
+      Default is the neutral palette.
+
+  state:
+    syntax: boolean
+    exclusive: false
+    cascades: false
+    default: none
+    values: [active, selected, highlighted]
+    description: >
+      Visual state indicators. Unlike other presentational groups,
+      state values can combine (e.g. selected + highlighted).
+
+# ── Cross-product sections ────────────────────────────────
+
+cross:
+  - dimensions: [variant, intent]
+    label: Variant x Intent
+    description: >
+      Each variant with each intent color. The most common
+      composition pattern for buttons.
+
+# ── Component attributes ──────────────────────────────────
+# Signal-backed, observed. Key-value or boolean HTML attributes.
+
+attributes:
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents interaction. Dims visually.
+
+  loading:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Shows loading state. Blocks interaction but not focus.
+
+  type:
+    syntax: key-value
+    type: enum
+    values: [button, submit, reset]
+    default: button
+    description: >
+      Button behavior within a form. submit calls form.requestSubmit(),
+      reset calls form.reset().
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Primary button label. Rendered via CSS ::after { content: attr(label) }
+      — no JS stamping. Also maps to aria-label for accessibility.
+      When omitted and no child text nodes exist, the button auto-detects
+      icon-only mode.
+
+  icon-leading:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Icon registry name for the leading icon. JS stamps an
+      <aui-icon name="..." slot="leading"> element into the button.
+
+  icon-trailing:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Icon registry name for the trailing icon. JS stamps an
+      <aui-icon name="..." slot="trailing"> element into the button.
+
+  text-leading:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Text adornment before the label. JS stamps a
+      <span slot="leading-text"> element. Separate from the icon slot.
+
+  text-trailing:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Text adornment after the label. JS stamps a
+      <span slot="trailing-text"> element. Separate from the icon slot.
+
+  icon:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Shorthand icon name from the icon registry. Convenience for
+      hide-label buttons — equivalent to icon-leading.
+
+  href:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      When set, button acts as a navigation link. Clicking navigates
+      to the given URL.
+
+# ── Modifiers ─────────────────────────────────────────────
+
+modifiers:
+  hide-label:
+    syntax: boolean
+    description: >
+      Hides the label text and collapses the button to icon-only.
+      Square button sized to --aui-size. Removes inline padding.
+      Use with a slotted icon, icon-leading, or the icon attribute.
+
+  text:
+    syntax: key-value
+    values: [left, right]
+    description: >
+      Overrides the default centered text alignment.
+      Useful for wide buttons where left- or right-aligned labels
+      feel more natural.
+
+# ── Internal data attributes ─────────────────────────────
+
+data-attributes:
+  data-has-text:
+    set-by: JS
+    description: >
+      Set automatically by JS when the button has child text nodes.
+      Used in the auto icon-only detection selector:
+      :not([label]):not([data-has-text]):has(> [slot]):not(:has(> :not([slot])))
+
+# ── Resize-responsive collapse ───────────────────────────
+# These data attributes are set by the resize trait based on
+# the button's own measured width. CSS hides adornments accordingly.
+
+resize:
+  data-resize-small:
+    threshold: "< 128px"
+    description: >
+      Hides leading icon and leading-text adornment.
+
+  data-resize-xsmall:
+    threshold: "< 96px"
+    description: >
+      Hides trailing icon and trailing-text adornment.
+
+  data-resize-compact:
+    threshold: "< 72px"
+    description: >
+      Hides everything except the leading icon. Applies tight padding.
+      Button collapses to near icon-only appearance.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: inline
+  accepts: [text, span, svg, img, aui-icon]
+  required: false
+  description: >
+    Inline text label or icon content. The preferred API is to use
+    the label attribute (rendered via CSS ::after) and icon-leading /
+    icon-trailing attributes (stamped by JS as <aui-icon> children).
+    Manual slotting of <aui-icon slot="leading/trailing"> is also supported.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [text, inline elements]
+    required: false
+    description: >
+      Button label text content. Prefer using the label attribute instead,
+      which renders the label via CSS ::after without JS.
+
+  leading:
+    accepts: [aui-icon, span, svg, img]
+    required: false
+    description: >
+      Leading icon. Typically stamped by JS from icon-leading attribute
+      as <aui-icon slot="leading">. Manual slotting is also supported.
+
+  trailing:
+    accepts: [aui-icon, span, svg, img]
+    required: false
+    description: >
+      Trailing icon. Typically stamped by JS from icon-trailing attribute
+      as <aui-icon slot="trailing">. Manual slotting is also supported.
+
+  leading-text:
+    accepts: [span]
+    required: false
+    description: >
+      Text adornment before the label. Stamped by JS from text-leading
+      attribute as <span slot="leading-text">.
+
+  trailing-text:
+    accepts: [span]
+    required: false
+    description: >
+      Text adornment after the label. Stamped by JS from text-trailing
+      attribute as <span slot="trailing-text">.
+
+# ── Composition ───────────────────────────────────────────
+
+composition:
+  parents: [aui-stack, aui-grid, aui-header, aui-footer, aui-inset, form, div, section]
+  children: null
+  context: >
+    Buttons are leaf-level interactive elements. They appear in
+    action bars, forms, headers, toolbars. Use aui-stack direction="row"
+    to group multiple buttons.
+
+# ── Constraints ───────────────────────────────────────────
+
+constraints:
+  - when: hide-label
+    require: label
+    reason: >
+      Screen readers need accessible text when no visible label
+      is present. The label attribute maps to aria-label.
+
+  - when: href
+    conflicts-with: [type]
+    reason: >
+      Link-mode buttons navigate via href. Form type attributes
+      (submit/reset) are meaningless in link mode.
+
+# ── Deprecated / Removed ─────────────────────────────────
+
+deprecated:
+  aui-icon-button:
+    status: removed
+    replacement: >
+      Use <aui-button hide-label label="..." icon-leading="..."> instead.
+
+  icon-only:
+    status: removed
+    replacement: >
+      Renamed to hide-label attribute on <aui-button>.
+
+  name-on-aui-icon:
+    status: removed
+    replacement: >
+      The name attribute on <aui-icon> is renamed to registry.
+      Use <aui-icon name="..."> instead of <aui-icon name="...">.
+
+# ── Accessibility ─────────────────────────────────────────
+
+a11y:
+  role: button
+  keyboard:
+    Enter: Fires click.
+    Space: Fires click.
+  aria:
+    aria-disabled: Set automatically when disabled attribute is present.
+    aria-label: Set from label attribute when present.
+  focus:
+    default: tabindex="0"
+    disabled: tabindex="-1"
+
+# ── Form association ──────────────────────────────────────
+
+form:
+  associated: true
+  submit: Calls form.requestSubmit() when type="submit".
+  reset: Calls form.reset() when type="reset".
+
+# ── Events ────────────────────────────────────────────────
+
+events:
+  click:
+    description: >
+      Native click event. Blocked when disabled or loading.
+      Fires form submit/reset when type is set. Navigates when href is set.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-size
+    - --aui-font-size
+    - --aui-font-family
+    - --aui-icon-size
+  spacing:
+    - --aui-pad-control-block
+    - --aui-pad-control-inline
+    - --aui-pad-gap-control
+    - --aui-space
+  color:
+    - --aui-fill
+    - --aui-stroke
+    - --aui-indicator
+    - --aui-ink
+    - --aui-focus
+  shape:
+    - --aui-radius
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+# ── Use cases ─────────────────────────────────────────────
+
+use-cases:
+  - Primary call-to-action in forms and action bars.
+  - Ghost/outline secondary actions alongside primary buttons.
+  - Icon-only toolbar actions (hide-label + icon-leading).
+  - Navigation links styled as buttons (href mode).
+  - Form submit/reset triggers.
+  - Buttons with text adornments (e.g. "AI" badge via text-leading).
+  - Resize-responsive buttons that collapse adornments as space shrinks.
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-button label="Default Action"></aui-button>
+    description: Declarative label via attribute (rendered by CSS ::after).
+
+  - html: <aui-button label="Save" icon-leading="check" primary accent></aui-button>
+    description: Leading icon + label, primary accent.
+
+  - html: <aui-button label="Delete" icon-leading="warning" primary danger></aui-button>
+    description: Danger button with leading warning icon.
+
+  - html: <aui-button label="Cancel" outline></aui-button>
+    description: Outlined button.
+
+  - html: <aui-button label="Skip" ghost></aui-button>
+    description: Ghost button with no chrome.
+
+  - html: <aui-button label="Settings" icon-leading="gear" ghost hide-label></aui-button>
+    description: Icon-only ghost button with accessible label via hide-label.
+
+  - html: <aui-button label="Generate" icon-leading="robot" text-leading="AI" primary></aui-button>
+    description: Leading icon + text adornment + label.
+
+  - html: <aui-button label="Suggestions" icon-leading="lightbulb" icon-trailing="caret-right"></aui-button>
+    description: Leading + trailing icons with label.
+
+  - html: <aui-button href="/about" label="Learn More"></aui-button>
+    description: Link-mode button.
+
+  - html: <aui-button type="submit" label="Submit" primary accent></aui-button>
+    description: Form submit button.
+
+  - html: |
+      <aui-button outline>
+        <aui-icon name="robot" slot="leading"></aui-icon>
+        Ask AI
+        <aui-icon name="sparkle" slot="trailing"></aui-icon>
+      </aui-button>
+    description: Manual slot pattern with inline text and aui-icon children.
+
+  - html: |
+      <div responsive style="resize: horizontal; overflow: hidden; width: 24rem; min-width: 3rem; display: flex; gap: 0.5rem;">
+        <aui-button label="Toggle scheme" icon-leading="sun" icon-trailing="caret-right" outline></aui-button>
+        <aui-button label="Search" icon-leading="magnifying-glass" outline></aui-button>
+      </div>
+    description: >
+      Resize-responsive collapse demo. Drag to shrink — buttons progressively
+      hide leading icons/text (< 128px), trailing icons/text (< 96px),
+      then collapse to icon-only with tight padding (< 72px).

package/dist/docs/components/calendar.yaml

@@ -0,0 +1,74 @@
+name: aui-calendar
+tag: aui-calendar
+type: component
+summary: Date picker with day, month, and year views.
+description: >
+  An interactive calendar for selecting dates. Supports single selection
+  and range selection with hover preview. Click the title to drill up
+  from day → month → year views. Keyboard navigable with arrow keys,
+  Home/End, PageUp/PageDown. Min and max attributes constrain the
+  selectable date range.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Selected date in ISO format (YYYY-MM-DD).
+  min:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Minimum selectable date. Dates before this are disabled.
+  max:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Maximum selectable date. Dates after this are disabled.
+  range:
+    syntax: boolean
+    description: Enables range selection (click start, hover to preview, click to commit).
+
+modifiers:
+  disabled:
+    syntax: boolean
+    description: Disables all interaction.
+
+a11y:
+  role: group
+  keyboard:
+    ArrowLeft: Previous day.
+    ArrowRight: Next day.
+    ArrowUp: Same day previous week.
+    ArrowDown: Same day next week.
+    Home: First day of current week.
+    End: Last day of current week.
+    PageUp: Previous month (Shift previous year).
+    PageDown: Next month (Shift next year).
+    Enter: Select focused date.
+    Space: Select focused date.
+
+events:
+  aui:change:
+    description: Fired on single date selection. Detail contains { value }.
+  aui:range-select:
+    description: Fired on range commit. Detail contains { start, end }.
+
+examples:
+  - html: |
+      <aui-calendar></aui-calendar>
+    description: Default calendar — current month, no selection.
+
+  - html: |
+      <aui-calendar value="2026-03-17"></aui-calendar>
+    description: Calendar with a pre-selected date.
+
+  - html: |
+      <aui-calendar min="2026-03-10" max="2026-03-25"></aui-calendar>
+    description: Constrained date range — only March 10-25 selectable.
+
+  - html: |
+      <aui-calendar range></aui-calendar>
+    description: Range selection mode — click start, hover preview, click to commit.

package/dist/docs/components/canvas.yaml

@@ -0,0 +1,161 @@
+name: aui-canvas
+tag: aui-canvas
+type: component
+summary: Versatile preview surface with pan/zoom, backgrounds, and editor layout slots.
+description: >
+  A composable canvas surface that serves three roles:
+  1. Simple preview container with background patterns (replaces .block-render)
+  2. Infinite canvas with pan and zoom for visual editors
+  3. Full editor layout with leading/trailing panels and floating toolbars
+
+  The canvas uses a slot-based architecture. Content goes in the default
+  slot. Panels attach via leading/trailing slots. Floating UI (toolbars,
+  indicators) uses float-top/bottom/left/right slots positioned absolutely
+  within the canvas viewport.
+
+  Pan uses pointer-captured drag on the background. Zoom uses wheel events.
+  Both expose CSS custom properties (--_canvas-x, --_canvas-y, --_canvas-zoom)
+  so content transforms are CSS-driven.
+
+base: AgentElement
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: true
+    default: medium
+    values: [xs, sm, md, lg, xl]
+    description: Cascades size to all children.
+
+attributes:
+  background:
+    syntax: key-value
+    type: enum
+    values: [none, grid, dots]
+    default: none
+    description: >
+      Background pattern. grid = checkerboard squares.
+      dots = dot matrix. none = transparent.
+
+  orientation:
+    syntax: key-value
+    type: enum
+    values: [horizontal, vertical]
+    default: horizontal
+    description: >
+      Layout direction. horizontal = [leading][content][trailing].
+      vertical = [content] over [leading][trailing].
+
+modifiers:
+  pan-enabled:
+    syntax: boolean
+    description: Enable click-and-drag panning of the canvas content.
+
+  zoom-enabled:
+    syntax: boolean
+    description: Enable scroll-to-zoom on the canvas content.
+
+  infinite:
+    syntax: boolean
+    description: >
+      Infinite canvas mode. Content is not constrained to the
+      viewport bounds. Combines pan-enabled + zoom-enabled.
+
+  bordered:
+    syntax: boolean
+    description: Adds a visible border around the canvas.
+
+slots:
+  default:
+    accepts: [any]
+    required: true
+    description: Main canvas content.
+
+  leading:
+    accepts: [any]
+    description: Left panel (horizontal) or top panel (vertical).
+
+  trailing:
+    accepts: [any]
+    description: Right panel (horizontal) or bottom panel (vertical).
+
+  float-top:
+    accepts: [any]
+    description: Floating toolbar at top center of the viewport.
+
+  float-bottom:
+    accepts: [any]
+    description: Floating toolbar at bottom center of the viewport.
+
+  float-left:
+    accepts: [any]
+    description: Floating indicator at left center of the viewport.
+
+  float-right:
+    accepts: [any]
+    description: Floating indicator at right center of the viewport.
+
+tokens:
+  custom:
+    - --_canvas-x — Current pan X offset in px
+    - --_canvas-y — Current pan Y offset in px
+    - --_canvas-zoom — Current zoom level (1 = 100%)
+
+events:
+  aui:canvas-pan:
+    description: Fires on pan change. Detail contains { x, y }.
+  aui:canvas-zoom:
+    description: Fires on zoom change. Detail contains { zoom }.
+
+a11y:
+  role: region
+  keyboard:
+    "0": Reset zoom to 100%.
+    "+": Zoom in.
+    "-": Zoom out.
+    Escape: Reset pan and zoom.
+
+examples:
+  - html: |
+      <aui-canvas bordered background="grid" style="height: 12rem;">
+        <aui-container kind="card" bordered max-width="xs">
+          <aui-inset>
+            <aui-heading size="md">Preview</aui-heading>
+            <aui-text muted size="sm">Component rendered on a grid canvas.</aui-text>
+          </aui-inset>
+        </aui-container>
+      </aui-canvas>
+    description: Simple preview with grid background.
+
+  - html: |
+      <aui-canvas bordered background="dots" infinite style="height: 20rem;">
+        <div style="position: absolute; top: 5rem; left: 5rem;">
+          <aui-container kind="widget" bordered accent>
+            <aui-inset><aui-text size="sm">Node A</aui-text></aui-inset>
+          </aui-container>
+        </div>
+        <div style="position: absolute; top: 5rem; left: 20rem;">
+          <aui-container kind="widget" bordered>
+            <aui-inset><aui-text size="sm">Node B</aui-text></aui-inset>
+          </aui-container>
+        </div>
+      </aui-canvas>
+    description: Infinite canvas with pan and zoom.
+
+  - html: |
+      <aui-canvas bordered background="dots" style="height: 24rem;">
+        <div slot="leading" style="width: 14rem; background: var(--aui-panel); border-right: 1px solid var(--aui-border-muted); padding: 1rem;">
+          <aui-heading size="sm">Sidebar</aui-heading>
+        </div>
+        <div slot="float-top">
+          <aui-container kind="widget" bordered shadow="1">
+            <aui-inset><aui-text size="xs">Toolbar</aui-text></aui-inset>
+          </aui-container>
+        </div>
+        Main content area
+        <div slot="trailing" style="width: 14rem; background: var(--aui-panel); border-left: 1px solid var(--aui-border-muted); padding: 1rem;">
+          <aui-heading size="sm">Properties</aui-heading>
+        </div>
+      </aui-canvas>
+    description: Full editor layout with panels and floating toolbar.