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

package/dist/docs/components/dialog.yaml

@@ -0,0 +1,133 @@
+name: aui-dialog
+tag: aui-dialog
+type: component
+summary: Modal dialog with backdrop and focus trapping.
+description: >
+  Modal dialog using the native <dialog> element. Provides
+  showModal()/close() API. Native dialog handles focus trapping,
+  Escape key dismissal, and ::backdrop. Composes aui-header,
+  aui-content, aui-footer as children.
+
+base: AgentElement
+
+attributes:
+  open:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Whether the dialog is visible. Setting this attribute
+      calls showModal() or close() on the native dialog.
+
+  size:
+    syntax: key-value
+    type: enum
+    values: [sm, lg, xl, full]
+    default: ""
+    description: >
+      Dialog width. Default is 32rem. sm=24rem, lg=48rem,
+      xl=64rem, full=viewport.
+
+content:
+  model: block
+  accepts: [aui-header, aui-content, aui-footer, aui-inset, any]
+  required: true
+  description: >
+    Children are moved inside a stamped <dialog> element.
+    Use aui-header + aui-content + aui-footer for structured
+    dialogs with scrollable content.
+
+slots:
+  default:
+    accepts: [aui-header, aui-content, aui-footer, aui-inset, any]
+    required: true
+    description: Dialog content.
+
+composition:
+  parents: [body, div, aui-stack]
+  children:
+    typical: [aui-header, aui-content, aui-footer]
+    pattern: >
+      Header for title + close button, body for scrollable
+      content, footer for action buttons. The native <dialog>
+      is auto-stamped as a wrapper.
+  context: >
+    Use for confirmations, forms, detail views, alerts.
+    Place anywhere in the DOM — the native dialog is
+    position: fixed and overlays everything.
+
+a11y:
+  role: dialog (native)
+  keyboard:
+    Escape: Closes the dialog (native behavior).
+    Tab: Trapped within the dialog (native behavior).
+  aria:
+    aria-modal: Set automatically by showModal().
+
+events:
+  close:
+    description: Fires when the dialog closes (Escape, backdrop click, or API).
+
+tokens:
+  color:
+    - --aui-modal
+    - --aui-doc
+    - --aui-border-muted
+    - --aui-ink
+    - --aui-backdrop-color
+    - --aui-backdrop-opacity
+  shadow:
+    - --aui-shadow-lg
+  shape:
+    - --aui-radius
+
+examples:
+  - html: |
+      <aui-container bordered max-width="md">
+        <aui-header>
+          <span>Confirm</span>
+        </aui-header>
+        <aui-content>
+          <aui-inset>
+            <p>Are you sure you want to delete this item? This action cannot be undone.</p>
+          </aui-inset>
+        </aui-content>
+        <aui-footer>
+          <span slot="trailing">
+            <aui-stack direction="row" gap="2">
+              <aui-button ghost>Cancel</aui-button>
+              <aui-button primary danger>Delete</aui-button>
+            </aui-stack>
+          </span>
+        </aui-footer>
+      </aui-container>
+    description: >
+      Confirmation dialog structure (header / body / footer).
+      In use, wrap with aui-dialog and control via the open attribute.
+
+  - html: |
+      <aui-container bordered max-width="lg">
+        <aui-header>
+          <span>Edit Profile</span>
+        </aui-header>
+        <aui-content>
+          <aui-inset>
+            <aui-stack>
+              <aui-field label="Name">
+                <aui-input placeholder="Full name"></aui-input>
+              </aui-field>
+              <aui-field label="Bio">
+                <aui-textarea placeholder="About you..."></aui-textarea>
+              </aui-field>
+            </aui-stack>
+          </aui-inset>
+        </aui-content>
+        <aui-footer>
+          <span slot="trailing">
+            <aui-button primary accent>Save</aui-button>
+          </span>
+        </aui-footer>
+      </aui-container>
+    description: >
+      Form dialog structure. Uses aui-container for inline preview.
+      Wrap with aui-dialog size="lg" for modal usage.

package/dist/docs/components/drawer.yaml

@@ -0,0 +1,124 @@
+name: aui-drawer
+tag: aui-drawer
+type: component
+summary: Slide-out panel anchored to a viewport edge.
+description: >
+  Edge-anchored overlay panel using native <dialog>. Same
+  focus trapping and Escape dismissal as aui-dialog. Slides
+  in from right (default), left, top, or bottom.
+
+base: AgentElement
+
+attributes:
+  open:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the drawer is visible.
+
+  side:
+    syntax: key-value
+    type: enum
+    values: [left, right, top, bottom]
+    default: right
+    description: Which viewport edge the drawer anchors to.
+
+content:
+  model: block
+  accepts: [aui-header, aui-content, aui-footer, aui-inset, any]
+  required: true
+  description: >
+    Same child pattern as dialog. Children are moved inside
+    a stamped <dialog> element.
+
+slots:
+  default:
+    accepts: [aui-header, aui-content, aui-footer, aui-inset, any]
+    required: true
+    description: Drawer content.
+
+composition:
+  parents: [body, div, aui-stack]
+  children:
+    typical: [aui-header, aui-content, aui-footer]
+    pattern: >
+      Header for title + close, body for scrollable content,
+      footer for actions. The drawer fills the viewport edge.
+  context: >
+    Use for settings panels, filters, detail views, mobile
+    navigation. Right is the most common side.
+
+a11y:
+  role: dialog (native)
+  keyboard:
+    Escape: Closes the drawer.
+    Tab: Trapped within the drawer.
+
+events:
+  close:
+    description: Fires when the drawer closes.
+
+tokens:
+  color:
+    - --aui-modal
+    - --aui-doc
+    - --aui-border-muted
+    - --aui-ink
+    - --aui-backdrop-color
+    - --aui-backdrop-opacity
+  sizing:
+    - --aui-drawer-width
+    - --aui-drawer-height
+  motion:
+    - --aui-duration
+    - --aui-easing
+
+examples:
+  - html: |
+      <aui-container bordered max-width="sm">
+        <aui-header>
+          <span>Filters</span>
+        </aui-header>
+        <aui-content>
+          <aui-inset>
+            <aui-stack>
+              <aui-field label="Category">
+                <aui-input placeholder="All"></aui-input>
+              </aui-field>
+              <aui-field label="Status">
+                <aui-radio-group name="status">
+                  <aui-radio label="Active" value="active"></aui-radio>
+                  <aui-radio label="Archived" value="archived"></aui-radio>
+                </aui-radio-group>
+              </aui-field>
+            </aui-stack>
+          </aui-inset>
+        </aui-content>
+        <aui-footer>
+          <span slot="trailing">
+            <aui-button primary accent>Apply</aui-button>
+          </span>
+        </aui-footer>
+      </aui-container>
+    description: >
+      Filter drawer structure (header / body / footer).
+      In use, wrap with aui-drawer side="right" and control via open.
+
+  - html: |
+      <aui-container bordered max-width="xs">
+        <aui-header>
+          <span>Navigation</span>
+        </aui-header>
+        <aui-content>
+          <aui-inset>
+            <aui-stack>
+              <a href="/" style="color: var(--aui-ink); text-decoration: none;">Home</a>
+              <a href="/settings" style="color: var(--aui-ink); text-decoration: none;">Settings</a>
+              <a href="/help" style="color: var(--aui-ink); text-decoration: none;">Help</a>
+            </aui-stack>
+          </aui-inset>
+        </aui-content>
+      </aui-container>
+    description: >
+      Navigation drawer structure.
+      Wrap with aui-drawer side="left" for slide-out behavior.

package/dist/docs/components/editor-layer.yaml

@@ -0,0 +1,59 @@
+name: aui-editor-layer
+tag: aui-editor-layer
+type: component
+summary: Named stacking layer within aui-editor with guaranteed z-index.
+description: >
+  Full-size absolute layer inside the editor viewport. Well-known
+  layer names get guaranteed z-index positions forming the "sandwich"
+  that ensures noodles, content, and chrome never interfere. SVG
+  layers stamp an SVG element for vector rendering (noodles, paths).
+
+base: AgentElement
+
+attributes:
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Layer name. Well-known names and their z-index:
+      "under" (-1) — guides, grids, decorations below content.
+      "content" (0) — the DOM being edited. Gets pointer-events: auto.
+      "over" (1) — noodles, selection rects above content.
+      "chrome" (2) — menus, handles, toolbars. Gets pointer-events: auto.
+
+  type:
+    syntax: key-value
+    type: enum
+    values: [html, svg]
+    default: html
+    description: >
+      "html" for regular DOM content. "svg" stamps an SVG element
+      for vector rendering (noodle paths, connection lines).
+
+api:
+  properties:
+    - name: svg
+      type: SVGSVGElement | null
+      description: The stamped SVG element (only for type="svg" layers).
+
+composition:
+  parents: [aui-editor, aui-graph-ui]
+  children: [any, aui-graph-node, aui-graph-noodle]
+  context: >
+    Always place inside aui-editor or aui-graph-ui. Use name to
+    control stacking order. Multiple layers compose the z-index
+    sandwich that separates concerns (wires vs content vs chrome).
+
+examples:
+  - html: |
+      <aui-editor-layer name="content">
+        <aui-text>Layer content here</aui-text>
+      </aui-editor-layer>
+    description: Content layer — the main editing surface.
+
+  - html: |
+      <aui-editor-layer name="over" type="svg">
+        <!-- SVG noodle paths render here -->
+      </aui-editor-layer>
+    description: SVG layer for noodle connections above content.

package/dist/docs/components/editor.yaml

@@ -0,0 +1,168 @@
+name: aui-editor
+tag: aui-editor
+type: component
+summary: Pannable, zoomable editor stage with layered stacking context.
+description: >
+  Universal canvas for graph editors, preview tools, design surfaces,
+  and any context that needs pan/zoom with guaranteed z-index layering.
+  Provides coordinate conversion API and context to descendants.
+  Middle-click or space+left-click to pan. Scroll wheel zooms toward
+  cursor. Background patterns (dots, grid) track pan position.
+
+base: AgentElement
+
+attributes:
+  zoom:
+    syntax: key-value
+    type: string
+    default: "1"
+    description: Current zoom level. Clamped between min-zoom and max-zoom.
+
+  pan-x:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: Horizontal pan offset in pixels.
+
+  pan-y:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: Vertical pan offset in pixels.
+
+  min-zoom:
+    syntax: key-value
+    type: string
+    default: "0.1"
+    description: Minimum zoom level.
+
+  max-zoom:
+    syntax: key-value
+    type: string
+    default: "5"
+    description: Maximum zoom level.
+
+  background:
+    syntax: key-value
+    type: enum
+    values: [none, dots, grid]
+    default: none
+    description: >
+      Background pattern. "dots" renders a dot grid that tracks pan
+      position. "grid" renders a line grid. "none" is transparent.
+
+  grid-size:
+    syntax: key-value
+    type: string
+    default: "24"
+    description: Background pattern spacing in pixels.
+
+api:
+  methods:
+    - name: screenToEditor
+      signature: "(screenX: number, screenY: number) => { x, y }"
+      description: Convert screen coordinates to editor coordinates.
+
+    - name: editorToScreen
+      signature: "(editorX: number, editorY: number) => { x, y }"
+      description: Convert editor coordinates to screen coordinates.
+
+    - name: panTo
+      signature: "(x: number, y: number) => void"
+      description: Set pan position programmatically.
+
+    - name: zoomTo
+      signature: "(level: number) => void"
+      description: Set zoom level programmatically.
+
+    - name: reset
+      signature: "() => void"
+      description: Reset pan and zoom to defaults.
+
+  properties:
+    - name: zoomLevel
+      type: number
+      description: Clamped numeric zoom value.
+
+    - name: panXValue
+      type: number
+      description: Numeric pan-x value.
+
+    - name: panYValue
+      type: number
+      description: Numeric pan-y value.
+
+    - name: viewportElement
+      type: HTMLElement | null
+      description: The internal viewport wrapper element.
+
+context:
+  provides: editorContext
+  shape: >
+    { zoom, panX, panY, screenToEditor, editorToScreen, getViewport }
+  description: >
+    Provided to all descendants so layers, nodes, ports, noodles,
+    and traits can read zoom/pan state and convert coordinates
+    without DOM traversal via closest().
+
+events:
+  aui:editor-pan:
+    description: Fired when pan position changes. Detail { x, y }.
+    bubbles: true
+
+  aui:editor-zoom:
+    description: Fired when zoom level changes. Detail { zoom }.
+    bubbles: true
+
+a11y:
+  role: No implicit role. Focusable via tabindex.
+  keyboard:
+    Space+Drag: Pan the canvas.
+    "Middle-click+Drag": Pan the canvas.
+    "Scroll wheel": Zoom toward cursor.
+
+composition:
+  parents: [div, section, main, aui-stack, any]
+  children: [aui-editor-layer]
+  context: >
+    Use as the root canvas for any editor. Place aui-editor-layer
+    children inside for guaranteed z-index stacking. The editor
+    creates a viewport wrapper and moves all children into it.
+
+tokens:
+  color:
+    - --aui-doc
+    - --aui-border-muted
+    - --aui-accent
+    - --aui-focus
+  motion:
+    - --_editor-zoom
+    - --_editor-pan-x
+    - --_editor-pan-y
+    - --_editor-grid-size
+
+examples:
+  - html: |
+      <aui-editor background="dots" style="width: 100%; height: 20rem;">
+        <aui-editor-layer name="content">
+          <aui-text>Pannable content on a dot grid</aui-text>
+        </aui-editor-layer>
+      </aui-editor>
+    description: Basic editor with dot background and content layer.
+
+  - html: |
+      <aui-editor background="grid" style="width: 100%; height: 20rem;">
+        <aui-editor-layer name="under">
+          <!-- noodles / guides go here -->
+        </aui-editor-layer>
+        <aui-editor-layer name="content">
+          <!-- editable DOM goes here -->
+        </aui-editor-layer>
+        <aui-editor-layer name="over">
+          <!-- selection rects go here -->
+        </aui-editor-layer>
+        <aui-editor-layer name="chrome">
+          <!-- menus / handles go here -->
+        </aui-editor-layer>
+      </aui-editor>
+    description: Full 4-layer sandwich with grid background.

package/dist/docs/components/feed.yaml

@@ -0,0 +1,72 @@
+name: aui-feed
+tag: aui-feed
+type: component
+summary: Scrollable feed for messages and activity streams
+base: AgentElement
+attributes:
+  align:
+    syntax: key-value
+    type: enum
+    values: [end]
+    default: ""
+    description: Bottom-anchor content (chat-style).
+  scrollable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Enable scrolling with smooth behavior.
+  autoscroll:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Auto-scroll to bottom on new children (when pinned).
+description: >
+  Scrollable feed for messages and activity streams. Uses block layout
+  (not flex) so aui-feed-item margins collapse, giving natural vertical
+  rhythm without explicit gap management.
+
+a11y:
+  role: feed
+composition:
+  parents: [any]
+  children: [aui-feed-item, any]
+
+# ── Child element ──────────────────────────────────────────
+children:
+  aui-feed-item:
+    tag: aui-feed-item
+    summary: Individual item in a feed with margin-based vertical rhythm.
+    description: >
+      Uses margin-block for spacing that collapses between siblings.
+      Consecutive items with the same role attribute (e.g. role="user",
+      role="assistant") receive tighter spacing via adjacent-sibling
+      selectors, producing compact clusters of same-sender messages.
+    attributes:
+      role:
+        syntax: key-value
+        type: string
+        default: ""
+        description: >
+          Semantic role of the feed item (e.g. "user", "assistant", "system").
+          Consecutive items sharing the same role get tighter margin-block-start
+          (50% of normal spacing).
+
+examples:
+  - html: |
+      <aui-feed scrollable style="height: 16rem; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-feed-item role="user">
+          <aui-inset><aui-text>Hey, how's the project going?</aui-text></aui-inset>
+        </aui-feed-item>
+        <aui-feed-item role="assistant">
+          <aui-inset><aui-text>Good progress — the token system refactor is done.</aui-text></aui-inset>
+        </aui-feed-item>
+        <aui-feed-item role="assistant">
+          <aui-inset><aui-text>Still need to do a visual QA pass though.</aui-text></aui-inset>
+        </aui-feed-item>
+        <aui-feed-item role="user">
+          <aui-inset><aui-text>Nice, let's review it together.</aui-text></aui-inset>
+        </aui-feed-item>
+      </aui-feed>
+    description: >
+      Scrollable message feed with aui-feed-item elements. Consecutive
+      assistant items get tighter spacing via same-role margin collapsing.

package/dist/docs/components/field.yaml

@@ -0,0 +1,145 @@
+name: aui-field
+tag: aui-field
+type: element
+summary: Form field wrapper with label, description, and error.
+description: >
+  Wraps a form control with a label, optional description, and
+  error message. All text is rendered CSS-first via content: attr()
+  from HTML attributes — zero JavaScript stamping required. Uses
+  display: flex with column direction, so child controls (aui-input,
+  aui-textarea, aui-select) stretch to full width automatically —
+  no width="full" needed on the child.
+
+# ── Component attributes ──────────────────────────────────
+
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Field label text. Rendered via ::before { content: attr(label) }.
+      No JS needed — CSS reads the attribute directly.
+
+  description:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Help text below the control. Rendered via ::after.
+      Replaced by error text when error attribute is set.
+
+  error:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Error message. When set, replaces description text and
+      cascades danger intent to child controls via CSS custom
+      properties.
+
+  required:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Appends " *" to the label text via CSS content concatenation.
+      Also sets the required constraint on the wrapped control.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Dims the field and disables pointer events.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: block
+  accepts: [aui-input, aui-textarea, aui-checkbox, aui-switch, aui-select, aui-radio-group]
+  required: true
+  description: >
+    Exactly one form control as the direct child. The field wrapper
+    provides the label and messages; the control provides the input.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [aui-input, aui-textarea, aui-checkbox, aui-switch, aui-select]
+    required: true
+    description: The form control.
+
+# ── Composition ───────────────────────────────────────────
+
+composition:
+  parents: [aui-stack, aui-grid, form, div, section]
+  children: [aui-input, aui-textarea, aui-checkbox, aui-switch, aui-select, aui-radio-group]
+  context: >
+    Use inside forms, settings panels, registration/login pages.
+    Stack multiple aui-field elements vertically in an aui-stack.
+    The field handles layout (label above, description below);
+    the control handles input behavior.
+
+# ── CSS implementation notes ──────────────────────────────
+
+css-notes:
+  attr-bindings:
+    - "::before { content: attr(label) } — AB2: label from attribute"
+    - "::before { content: attr(label) ' *' } — CG1: required indicator"
+    - "::after { content: attr(description) } — AB2: description from attribute"
+    - "::after { content: attr(error) } — AB1: error replaces description"
+  state-attributes:
+    - "[error] cascades --aui-stroke to danger color"
+    - "[disabled] dims with opacity"
+    - "[required] appends asterisk to label"
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  spacing:
+    - --aui-space
+  typography:
+    - --aui-font-family
+    - --aui-font-size
+    - --aui-text-line-height
+    - --aui-control-line-height-relaxed
+  color:
+    - --aui-ink
+    - --aui-ink-muted
+    - --aui-ink-disabled
+    - --aui-border-danger
+    - --aui-danger
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: |
+      <aui-field label="Email">
+        <aui-input type="email" placeholder="you@example.com"></aui-input>
+      </aui-field>
+    description: Basic field with label and input.
+
+  - html: |
+      <aui-field label="Password" description="Must be at least 8 characters.">
+        <aui-input type="password" placeholder="Enter password"></aui-input>
+      </aui-field>
+    description: Field with description text.
+
+  - html: |
+      <aui-field label="Username" required>
+        <aui-input placeholder="Choose a username"></aui-input>
+      </aui-field>
+    description: Required field — label shows asterisk.
+
+  - html: |
+      <aui-field label="Email" error="This email is already registered.">
+        <aui-input type="email" value="taken@example.com"></aui-input>
+      </aui-field>
+    description: Field with error state.
+
+  - html: |
+      <aui-field label="Name" disabled>
+        <aui-input value="Read only" disabled></aui-input>
+      </aui-field>
+    description: Disabled field.