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

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

@@ -0,0 +1,41 @@
+name: aui-graph-layer
+tag: aui-graph-layer
+type: component
+summary: Stacking layer for graph editors. Extends aui-editor-layer.
+description: >
+  Named layer inside aui-graph-ui. Extends aui-editor-layer with
+  the same API. Supports graph-conventional names: "wires" (z:-1),
+  "content" (z:0), "chrome" (z:2), plus the standard editor names
+  (under, content, over, chrome). SVG layers stamp an SVG element
+  for noodle path rendering.
+
+base: AuiEditorLayer
+
+attributes:
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Layer name. "wires" = z-index -1 (noodle paths).
+      "content" = z-index 0 (nodes). "over" = z-index 1.
+      "chrome" = z-index 2 (menus, handles).
+
+  type:
+    syntax: key-value
+    type: enum
+    values: [html, svg]
+    default: html
+    description: >
+      "svg" stamps an SVG element for noodle rendering.
+
+composition:
+  parents: [aui-graph-ui]
+  children: [aui-graph-node, aui-graph-noodle, any]
+
+examples:
+  - html: |
+      <aui-graph-layer name="wires" type="svg">
+        <aui-graph-noodle from="a:out" to="b:in" color="accent" weight="2"></aui-graph-noodle>
+      </aui-graph-layer>
+    description: SVG wire layer with a noodle connection.

package/dist/docs/components/graph-node.yaml

@@ -0,0 +1,58 @@
+name: aui-graph-node
+tag: aui-graph-node
+type: component
+summary: Positioned draggable node inside a graph editor.
+description: >
+  Renders at (x, y) in graph coordinates via CSS transform.
+  Draggable with pointer. Contains any content — typically
+  aui-container with aui-graph-port children for connections.
+
+base: AgentElement
+
+attributes:
+  x:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: X position in graph coordinates.
+
+  y:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: Y position in graph coordinates.
+
+  node-id:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Unique node identifier. Used by noodle port selectors.
+
+  selected:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether the node is selected.
+
+events:
+  aui:node-move:
+    description: Fired when node is dragged. Detail { id, x, y }.
+    bubbles: true
+
+composition:
+  parents: [aui-graph-layer, aui-editor-layer]
+  children: [aui-container, aui-graph-port, any]
+  context: >
+    Place inside a content-type layer. The node-id is referenced
+    by aui-graph-noodle port selectors ("nodeId:portId").
+
+examples:
+  - html: |
+      <aui-graph-node x="100" y="50" node-id="my-node">
+        <aui-container kind="card" bordered padding="3">
+          <aui-text weight="medium">My Node</aui-text>
+          <aui-graph-port port-id="in" side="left" type="input"></aui-graph-port>
+          <aui-graph-port port-id="out" side="right" type="output"></aui-graph-port>
+        </aui-container>
+      </aui-graph-node>
+    description: Draggable node with input and output ports.

package/dist/docs/components/graph-noodle.yaml

@@ -0,0 +1,103 @@
+name: aui-graph-noodle
+tag: aui-graph-noodle
+type: component
+summary: SVG bezier connection between two points or ports.
+description: >
+  Renders a cubic bezier path inside a parent SVG layer. Supports
+  port selectors ("nodeId:portId") for live tracking of port
+  positions, or literal "x,y" coordinates. Direction-aware control
+  points extend perpendicular to each port's side attribute.
+  Optional label at bezier midpoint, stream/blob animations.
+
+base: AgentElement
+
+attributes:
+  from:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Start point. "nodeId:portId" resolves from live port position.
+      "x,y" uses literal coordinates.
+
+  to:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      End point. Same format as from.
+
+  color:
+    syntax: key-value
+    type: string
+    default: "var(--aui-border)"
+    description: >
+      Stroke color. Named presets: accent, success, warning, danger,
+      muted, scrim. Or any CSS color value.
+
+  weight:
+    syntax: key-value
+    type: string
+    default: "2"
+    description: Stroke width in pixels.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Text shown at the bezier midpoint (t=0.5).
+
+  label-bg:
+    syntax: key-value
+    type: string
+    default: "var(--aui-doc)"
+    description: Background fill for the label rect.
+
+  animation:
+    syntax: key-value
+    type: enum
+    values: [none, stream, blob]
+    default: none
+    description: >
+      "stream" animates a flowing dash pattern. "blob" sends a
+      circle traveling along the path.
+
+  animate-direction:
+    syntax: key-value
+    type: enum
+    values: [forward, reverse]
+    default: forward
+    description: Direction of stream/blob animation.
+
+  animate-speed:
+    syntax: key-value
+    type: string
+    default: "1500"
+    description: Animation duration in milliseconds.
+
+  dashed:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Render as dashed stroke.
+
+events:
+  aui:noodle-click:
+    description: Fired when the noodle path is clicked. Detail { from, to }.
+    bubbles: true
+
+composition:
+  parents: [aui-graph-layer, aui-editor-layer]
+  children: none
+  context: >
+    Place inside an SVG-type layer. Uses closest aui-graph-ui or
+    aui-editor for coordinate conversion when resolving port selectors.
+
+examples:
+  - html: |
+      <aui-graph-noodle from="source:out" to="target:in" color="accent" weight="2" label="data"></aui-graph-noodle>
+    description: Labeled noodle connecting two ports by selector.
+
+  - html: |
+      <aui-graph-noodle from="100,50" to="400,150" color="success" weight="2" animation="stream"></aui-graph-noodle>
+    description: Animated stream noodle with literal coordinates.

package/dist/docs/components/graph-port.yaml

@@ -0,0 +1,71 @@
+name: aui-graph-port
+tag: aui-graph-port
+type: component
+summary: Connection endpoint on a graph node edge.
+description: >
+  Small dot positioned at a node's edge. Reports its center
+  position in editor coordinates via getPosition(). Used by
+  aui-graph-noodle port selectors to resolve connection endpoints.
+  Type coloring: input (green), output (accent), bidirectional (border).
+
+base: AgentElement
+
+attributes:
+  port-id:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Unique identifier within the parent node.
+
+  side:
+    syntax: key-value
+    type: enum
+    values: [top, right, bottom, left]
+    default: right
+    description: Which edge of the parent node the port sits on.
+
+  type:
+    syntax: key-value
+    type: enum
+    values: [input, output, bidirectional]
+    default: bidirectional
+    description: Connection direction. Controls dot color.
+
+  data-type:
+    syntax: key-value
+    type: string
+    default: any
+    description: Data type for connection compatibility checking.
+
+  connected:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether a noodle is connected. Fills the dot.
+
+api:
+  methods:
+    - name: getPosition
+      signature: "() => { x: number, y: number }"
+      description: >
+        Center position in editor coordinates. Uses nearest
+        aui-graph-ui or aui-editor's screenToEditor() for conversion.
+
+events:
+  aui:port-drag-start:
+    description: >
+      Fired on pointerdown for drag-to-connect.
+      Detail { portId, side, type, dataType, position }.
+    bubbles: true
+
+composition:
+  parents: [aui-graph-node, aui-container]
+  children: none
+  context: >
+    Place inside aui-graph-node. The port-id is referenced by
+    noodle selectors as "nodeId:portId".
+
+examples:
+  - html: |
+      <aui-graph-port port-id="out" side="right" type="output"></aui-graph-port>
+    description: Output port on the right edge.

package/dist/docs/components/graph-ui.yaml

@@ -0,0 +1,64 @@
+name: aui-graph-ui
+tag: aui-graph-ui
+type: component
+summary: Graph editor canvas with dot grid and snap-to-grid.
+description: >
+  Extends aui-editor with graph-specific features. Defaults to
+  background="dots". Adds snap-to-grid for node positioning.
+  All pan/zoom, coordinate conversion, context provision, and
+  layer stacking are inherited from aui-editor.
+
+base: AuiEditor
+
+attributes:
+  snap-to-grid:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Snap node positions to the grid when dragged.
+
+  connectable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Enable interactive drag-to-connect between ports. Drag from
+      a port to create a rubber-band noodle, release near another
+      port to fire aui:noodle-connect with from/to selectors.
+
+inherits:
+  from: aui-editor
+  attributes: [zoom, pan-x, pan-y, min-zoom, max-zoom, background, grid-size]
+  methods: [screenToEditor, editorToScreen, panTo, zoomTo, reset]
+  events: [aui:editor-pan, aui:editor-zoom]
+  context: editorContext
+
+composition:
+  parents: [div, section, main, aui-stack, any]
+  children: [aui-graph-layer, aui-editor-layer]
+  context: >
+    Root canvas for node-graph editors. Place aui-graph-layer
+    children inside for wires and content separation.
+
+examples:
+  - html: |
+      <aui-graph-ui style="width: 100%; height: 20rem;">
+        <aui-graph-layer name="wires" type="svg">
+          <aui-graph-noodle from="source:out" to="target:in" color="accent" weight="2"></aui-graph-noodle>
+        </aui-graph-layer>
+        <aui-graph-layer name="content">
+          <aui-graph-node x="50" y="50" node-id="source">
+            <aui-container kind="card" bordered padding="3">
+              <aui-text weight="medium">Source</aui-text>
+              <aui-graph-port port-id="out" side="right" type="output"></aui-graph-port>
+            </aui-container>
+          </aui-graph-node>
+          <aui-graph-node x="350" y="50" node-id="target">
+            <aui-container kind="card" bordered padding="3">
+              <aui-text weight="medium">Target</aui-text>
+              <aui-graph-port port-id="in" side="left" type="input"></aui-graph-port>
+            </aui-container>
+          </aui-graph-node>
+        </aui-graph-layer>
+      </aui-graph-ui>
+    description: Simple two-node graph with a noodle connection.

package/dist/docs/components/gripper.yaml

@@ -0,0 +1,55 @@
+name: aui-gripper
+tag: aui-gripper
+type: component
+summary: Resize handle for panes and resizable containers.
+description: >
+  A draggable separator that emits resize events with delta values.
+  Supports both horizontal (col-resize) and vertical (row-resize)
+  orientations. Keyboard resizing via arrow keys. Has a 10px hit area
+  with a 2px feedback line at rest (border-muted) that expands to a
+  6px accent bar on click. Width/height transition is animated between
+  rest and active states.
+
+base: AgentElement
+
+attributes:
+  orientation:
+    syntax: key-value
+    type: enum
+    values: [horizontal, vertical]
+    default: horizontal
+    description: >
+      Drag axis. Horizontal = vertical divider (drag left/right).
+      Vertical = horizontal divider (drag up/down).
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents drag interaction.
+
+a11y:
+  role: separator
+  keyboard:
+    ArrowLeft: Resize left (horizontal).
+    ArrowRight: Resize right (horizontal).
+    ArrowUp: Resize up (vertical).
+    ArrowDown: Resize down (vertical).
+    Shift+Arrow: Resize by 10px instead of 1px.
+  aria:
+    aria-orientation: Set from orientation attribute.
+
+events:
+  aui:resize-start:
+    description: Fired when drag begins.
+  aui:resize-move:
+    description: Fired on drag movement. detail contains dx, dy, delta.
+  aui:resize-end:
+    description: Fired when drag ends. detail contains final dx, dy, delta.
+
+examples:
+  - html: <aui-gripper></aui-gripper>
+    description: Default horizontal gripper (drag left/right).
+
+  - html: <aui-gripper orientation="vertical"></aui-gripper>
+    description: Vertical gripper (drag up/down).

package/dist/docs/components/icon.yaml

@@ -0,0 +1,133 @@
+name: aui-icon
+tag: aui-icon
+type: component
+summary: SVG icon rendered from a global registry.
+description: >
+  Displays an icon by name from the global icon registry. Icons are
+  registered via registerIcon() or registerIcons() — the component
+  itself is icon-set agnostic. Inherits color from its parent via
+  currentColor. Size follows --aui-icon-size or explicit size attribute.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  size:
+    syntax: key-value
+    cascades: false
+    default: medium
+    values: [xs, sm, lg, xl]
+    description: >
+      Overrides the inherited --aui-icon-size token.
+      Default (no attribute) uses the token value from context.
+
+# ── Component attributes ──────────────────────────────────
+
+attributes:
+  name:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Icon name matching a key in the global registry.
+      When the name changes, the SVG is re-rendered.
+      Registered names: arrow-up, caret-down, caret-left, caret-right,
+      caret-up, chat-dots, check, check-circle, circle, clock, crosshair,
+      dots-three, envelope, file-text, flask, gear, globe-simple, house,
+      image, lightbulb, list-checks, magnifying-glass, microphone, minus,
+      paperclip, pencil, plus, robot, sliders, sparkle, star, stop, user,
+      warning, warning-circle, x, chart-bar, sun, moon, heart, trash,
+      info, copy, thumbs-up, thumbs-down, arrow-clockwise.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Accessible label for meaningful icons. When set, the element
+      gets role="img" and aria-label. When absent, it is treated
+      as decorative (role="presentation", aria-hidden="true").
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    Content is auto-rendered from the registry. Do not place
+    children inside aui-icon.
+
+# ── Composition ───────────────────────────────────────────
+
+composition:
+  parents: [aui-button, aui-input, aui-select, aui-header, aui-footer, any]
+  children: null
+  context: >
+    Icons appear inside button slots, input leading/trailing,
+    toolbar items, or standalone. Inherits color and size from
+    the parent context.
+
+# ── Accessibility ─────────────────────────────────────────
+
+a11y:
+  role: img (when label set) / presentation (decorative)
+  aria:
+    aria-label: Set from label attribute when present.
+    aria-hidden: Set to "true" when no label (decorative icon).
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-icon-size
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: |
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-icon name="house"></aui-icon>
+        <aui-icon name="gear"></aui-icon>
+        <aui-icon name="magnifying-glass"></aui-icon>
+        <aui-icon name="heart"></aui-icon>
+        <aui-icon name="star"></aui-icon>
+        <aui-icon name="user"></aui-icon>
+        <aui-icon name="pencil"></aui-icon>
+        <aui-icon name="trash"></aui-icon>
+        <aui-icon name="plus"></aui-icon>
+        <aui-icon name="check"></aui-icon>
+        <aui-icon name="warning"></aui-icon>
+        <aui-icon name="info"></aui-icon>
+      </aui-stack>
+    description: Icon gallery from the Phosphor icon set.
+
+  - html: |
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-icon name="star" size="xs"></aui-icon>
+        <aui-icon name="star" size="sm"></aui-icon>
+        <aui-icon name="star"></aui-icon>
+        <aui-icon name="star" size="lg"></aui-icon>
+        <aui-icon name="star" size="xl"></aui-icon>
+      </aui-stack>
+    description: Size scale from xs to xl.
+
+  - html: |
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-button outline accent>
+          <aui-icon name="pencil" slot="leading"></aui-icon>
+          Edit
+        </aui-button>
+        <aui-button primary danger>
+          <aui-icon name="trash" slot="leading"></aui-icon>
+          Delete
+        </aui-button>
+        <aui-button ghost hide-label label="Search">
+          <aui-icon name="magnifying-glass" slot="leading"></aui-icon>
+        </aui-button>
+      </aui-stack>
+    description: Icons inside button slots.
+
+  - html: <aui-icon name="warning" label="Warning" size="xl"></aui-icon>
+    description: Meaningful icon with accessible label.