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

package/dist/docs/components/noodles.yaml

@@ -0,0 +1,184 @@
+name: aui-noodles
+tag: aui-noodles
+type: component
+summary: Declarative SVG noodle canvas for node-based flow editors.
+description: >
+  Renders SVG bezier/step/straight connections between child elements.
+  Children declare ports via `data-noodle-port="left right"` and the
+  element handles the SVG overlay, coordinate system, path computation,
+  and interactive drag-to-connect when editable. Supports reconnect
+  (grab an existing noodle to move it), proximity-based port snapping,
+  and animated dash patterns.
+
+base: AgentElement
+
+attributes:
+  editable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Allow interactive creation and deletion of connections via
+      drag-to-connect from port indicators.
+
+  color:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Noodle stroke color. Defaults to var(--aui-accent-500).
+      Individual connections can override via the color property.
+
+  stroke-width:
+    syntax: key-value
+    type: string
+    default: "2"
+    description: Stroke width in px.
+
+  tension:
+    syntax: key-value
+    type: string
+    default: "0.5"
+    description: >
+      Bezier control point distance as a fraction of the distance
+      between endpoints. 0 = flat, 1 = dramatic curves.
+
+  show-ports:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Show port indicator dots on connectable elements. Defaults to
+      true when editable is set.
+
+  port-size:
+    syntax: key-value
+    type: string
+    default: "10"
+    description: Port indicator dot diameter in px.
+
+  curve:
+    syntax: key-value
+    type: enum
+    values: [bezier, step, straight]
+    default: bezier
+    description: >
+      Curve style for noodle paths. bezier = smooth cubic bezier,
+      step = right-angle step, straight = direct line.
+
+  animated:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Animate noodles with a flowing dash pattern.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: >
+      Disable the controller. Paths render as muted dashed lines
+      and interaction is prevented.
+
+content:
+  model: block
+  accepts: [div, section, any]
+  required: true
+  description: >
+    Child elements that participate in the noodle graph. Each connectable
+    element must have an `id` and a `data-noodle-port` attribute listing
+    which sides accept connections (e.g. "left right top bottom").
+
+slots:
+  default:
+    accepts: [any]
+    required: true
+    description: Node elements with data-noodle-port attributes.
+
+composition:
+  parents: [aui-container, div, section, main]
+  children:
+    typical: [div, aui-container]
+    pattern: >
+      Absolutely positioned child elements with id and data-noodle-port
+      attributes. The noodles element establishes a positioning context.
+  context: >
+    Use for flow editors, pipeline visualizations, node-based UIs,
+    and any diagram where elements need visible connections.
+
+a11y:
+  role: No implicit role. The SVG overlay is pointer-events:none.
+  keyboard:
+    Tab: Port indicators are not in tab order (crosshair cursor).
+  focus:
+    default: Not focusable.
+
+events:
+  aui:noodle-connect:
+    description: >
+      Fired when a connection is created (programmatic or drag).
+      Detail: { id, from, to, fromPort, toPort }
+    bubbles: true
+
+  aui:noodle-disconnect:
+    description: >
+      Fired when a connection is removed.
+      Detail: { id, from, to, fromPort, toPort }
+    bubbles: true
+
+  aui:noodle-drag:
+    description: >
+      Fired during drag-to-connect pointer movement.
+      Detail: { from, fromPort, x, y, reconnect? }
+    bubbles: true
+
+tokens:
+  color:
+    - --aui-accent-500
+    - --aui-ink-muted
+  motion:
+    - noodle-flow (keyframe animation)
+
+examples:
+  - html: |
+      <aui-noodles style="width: 600px; height: 300px;">
+        <aui-container id="a" data-noodle-port="right" kind="card" bordered padding="3" style="position: absolute; left: 40px; top: 120px;">
+          <aui-text weight="medium">Source</aui-text>
+        </aui-container>
+        <aui-container id="b" data-noodle-port="left" kind="card" bordered padding="3" style="position: absolute; left: 400px; top: 120px;">
+          <aui-text weight="medium">Target</aui-text>
+        </aui-container>
+      </aui-noodles>
+    description: Two connected nodes with a bezier noodle.
+    script: |
+      const noodles = document.querySelector('aui-noodles');
+      noodles.connect('a', 'b', 'right', 'left');
+
+  - html: |
+      <aui-noodles editable show-ports style="width: 600px; height: 300px;">
+        <aui-container id="n1" data-noodle-port="right bottom" kind="card" bordered padding="3" style="position: absolute; left: 40px; top: 40px;">
+          <aui-text weight="medium">Node 1</aui-text>
+        </aui-container>
+        <aui-container id="n2" data-noodle-port="left right" kind="card" bordered padding="3" style="position: absolute; left: 240px; top: 120px;">
+          <aui-text weight="medium">Node 2</aui-text>
+        </aui-container>
+        <aui-container id="n3" data-noodle-port="left top" kind="card" bordered padding="3" style="position: absolute; left: 440px; top: 40px;">
+          <aui-text weight="medium">Node 3</aui-text>
+        </aui-container>
+      </aui-noodles>
+    description: Editable canvas with port indicators. Drag between ports to connect.
+
+  - html: |
+      <aui-noodles curve="step" stroke-width="3" animated style="width: 500px; height: 200px;">
+        <aui-container id="s1" data-noodle-port="right" kind="card" bordered padding="3" style="position: absolute; left: 20px; top: 80px;">
+          <aui-text weight="medium">Step A</aui-text>
+        </aui-container>
+        <aui-container id="s2" data-noodle-port="left" kind="card" bordered padding="3" style="position: absolute; left: 340px; top: 80px;">
+          <aui-text weight="medium">Step B</aui-text>
+        </aui-container>
+      </aui-noodles>
+    description: Step curve style with animated dash pattern.
+    script: |
+      const noodles = document.querySelector('aui-noodles');
+      noodles.connect('s1', 's2', 'right', 'left');

package/dist/docs/components/optgroup.yaml

@@ -0,0 +1,38 @@
+name: aui-optgroup
+tag: aui-optgroup
+type: component
+summary: Groups related options with an optional label and divider.
+description: >
+  Wraps aui-option elements into a labeled section within aui-select.
+  In dropdown/list/combobox modes, renders an uppercase heading above
+  the group. Use divider attribute to add a visual separator before the
+  group. In bar mode, groups are layout-transparent (display: contents)
+  with labels hidden — adjacent groups are separated by auto-stamped
+  vertical dividers. When a group overflows, all its items move to the
+  overflow menu together, rendered under a divider + uppercase header.
+
+attributes:
+  label:
+    type: string
+    default: ""
+    description: Group heading text displayed above the options.
+  divider:
+    type: boolean
+    default: false
+    description: Adds a visual separator (border-top) before the group.
+
+examples:
+  - html: |
+      <aui-select placeholder="Choose a color">
+        <aui-optgroup label="Warm">
+          <aui-option value="red">Red</aui-option>
+          <aui-option value="orange">Orange</aui-option>
+          <aui-option value="yellow">Yellow</aui-option>
+        </aui-optgroup>
+        <aui-optgroup label="Cool" divider>
+          <aui-option value="blue">Blue</aui-option>
+          <aui-option value="green">Green</aui-option>
+          <aui-option value="purple">Purple</aui-option>
+        </aui-optgroup>
+      </aui-select>
+    description: Two option groups with a divider between them.

package/dist/docs/components/option.yaml

@@ -0,0 +1,56 @@
+name: aui-option
+tag: aui-option
+type: component
+summary: Selectable item within aui-select.
+description: >
+  A single option within aui-select.
+  Most behavior is coordinated by the parent listbox. Visual states
+  driven by selected, disabled, and data-navigate-active attributes.
+
+base: AgentElement
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: ""
+    description: The option's value for form submission.
+
+  disabled:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Prevents selection.
+
+  selected:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Whether this option is currently selected.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Display label override. When empty, textContent is used.
+
+a11y:
+  role: option
+  aria:
+    aria-selected: Reflects selected attribute.
+    aria-disabled: Reflects disabled attribute.
+
+composition:
+  parents: [aui-select, aui-optgroup]
+  children: null
+
+examples:
+  - html: <aui-option value="apple">Apple</aui-option>
+    description: Simple option.
+
+  - html: <aui-option value="banana" selected>Banana</aui-option>
+    description: Pre-selected option.
+
+  - html: <aui-option value="cherry" disabled>Cherry</aui-option>
+    description: Disabled option.

package/dist/docs/components/page-context.yaml

@@ -0,0 +1,55 @@
+name: aui-page-context
+tag: aui-page-context
+type: component
+summary: Page context bar with leading, center, and trailing sections.
+description: >
+  Adaptive 3-column grid bar at the top of aui-page. Automatically
+  adjusts grid layout via :has() selectors based on which child
+  slots are present (leading, center breadcrumb, trailing aside).
+
+base: AgentElement
+
+a11y:
+  role: navigation
+  aria:
+    aria-label: Breadcrumb
+
+composition:
+  parents: [aui-page]
+  children:
+    typical: [div, aui-breadcrumb, aside]
+    pattern: >
+      First child is the leading section (e.g. back button),
+      center child is typically aui-breadcrumb, trailing aside
+      holds action buttons. Grid adapts from 1 to 3 columns
+      based on which children are present.
+
+tokens:
+  sizing:
+    - --aui-pad-control-block
+    - --aui-size
+    - --aui-space
+
+examples:
+  - html: |
+      <aui-page-context>
+        <div>
+          <aui-button icon="arrow-left" hide-label label="Back"></aui-button>
+        </div>
+        <aui-breadcrumb>
+          <aui-breadcrumb-item label="Home"></aui-breadcrumb-item>
+          <aui-breadcrumb-item label="Projects"></aui-breadcrumb-item>
+        </aui-breadcrumb>
+        <aside>
+          <aui-button icon="plus" label="New"></aui-button>
+        </aside>
+      </aui-page-context>
+    description: Full 3-column context bar with leading, breadcrumb, and trailing actions.
+
+  - html: |
+      <aui-page-context>
+        <aui-breadcrumb>
+          <aui-breadcrumb-item label="Dashboard"></aui-breadcrumb-item>
+        </aui-breadcrumb>
+      </aui-page-context>
+    description: Minimal context bar with breadcrumb only.

package/dist/docs/components/page-main.yaml

@@ -0,0 +1,39 @@
+name: aui-page-main
+tag: aui-page-main
+type: component
+summary: Canvas area below the page context bar.
+description: >
+  Contains a <main> element with a scrollable, rounded content panel.
+  Supports sticky header and footer inside the main panel. Provides
+  the primary content surface with panel background and border radius.
+
+base: AgentElement
+
+composition:
+  parents: [aui-page]
+  children:
+    typical: [main]
+    pattern: >
+      Direct child should be a <main> element containing the page
+      content. The main element gets panel styling with rounded
+      corners, hidden scrollbar, and supports sticky header/footer
+      children.
+
+tokens:
+  color:
+    - --aui-panel
+    - --aui-border
+  sizing:
+    - --aui-space
+    - --aui-radius
+
+examples:
+  - html: |
+      <aui-page-main>
+        <main>
+          <header>Sticky page header</header>
+          <section>Scrollable content</section>
+          <footer>Sticky page footer</footer>
+        </main>
+      </aui-page-main>
+    description: Main content area with sticky header and footer inside the panel.

package/dist/docs/components/page.yaml

@@ -0,0 +1,36 @@
+name: aui-page
+tag: aui-page
+type: component
+summary: Content column within the app shell.
+description: >
+  Flex column that fills the remaining space beside the sidebar.
+  Contains a page context bar and a main content area. Acts as
+  the primary content region of the application layout.
+
+base: AgentElement
+
+a11y:
+  role: main
+
+composition:
+  parents: [aui-app-shell]
+  children:
+    typical: [aui-page-context, aui-page-main]
+    pattern: >
+      Context bar at top for breadcrumbs and actions, page-main
+      below for the scrollable content panel.
+
+examples:
+  - html: |
+      <aui-page>
+        <aui-page-context>
+          <aui-breadcrumb>
+            <aui-breadcrumb-item label="Home"></aui-breadcrumb-item>
+            <aui-breadcrumb-item label="Settings"></aui-breadcrumb-item>
+          </aui-breadcrumb>
+        </aui-page-context>
+        <aui-page-main>
+          <main>Page content here</main>
+        </aui-page-main>
+      </aui-page>
+    description: Page with breadcrumb context bar and main content area.

package/dist/docs/components/pagination.yaml

@@ -0,0 +1,46 @@
+name: aui-pagination
+tag: aui-pagination
+type: component
+summary: Page navigation with numbered buttons and prev/next.
+description: >
+  Stamps page buttons, prev/next arrows, and ellipsis from the
+  page and total attributes. Handles large page counts with
+  configurable sibling count.
+
+base: AgentElement
+
+attributes:
+  page:
+    syntax: key-value
+    type: string
+    default: "1"
+    description: Current page number.
+
+  total:
+    syntax: key-value
+    type: string
+    default: "1"
+    description: Total number of pages.
+
+  siblings:
+    syntax: key-value
+    type: string
+    default: "1"
+    description: Number of sibling pages to show around the current page.
+
+a11y:
+  role: navigation
+  aria:
+    aria-label: Pagination
+    aria-current: page (on the current page button).
+
+events:
+  change:
+    description: Fired when page changes. detail.page is the new page number.
+
+examples:
+  - html: <aui-pagination page="3" total="10"></aui-pagination>
+    description: Pagination on page 3 of 10.
+
+  - html: <aui-pagination page="1" total="5" siblings="2"></aui-pagination>
+    description: Small pagination with 2 siblings.

package/dist/docs/components/pane.yaml

@@ -0,0 +1,102 @@
+name: aui-pane
+tag: aui-pane
+type: component
+summary: Individual pane within a resizable split layout.
+description: >
+  A flexible panel within aui-panes. Supports auto-stamped headers with
+  label, icon, close and minimize buttons. Can be minimized to header-only,
+  collapsed to a thin strip, or hidden. Resize priority (high/normal/low)
+  controls how cascade resizing distributes space.
+
+base: AgentElement
+
+attributes:
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Pane header label. When set, auto-stamps an aui-header with the label
+      text and optional action buttons.
+
+  icon:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Icon name shown before the label in the stamped header.
+
+  closeable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Adds a close button to the stamped header.
+
+  minimizable:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Adds a minimize/restore button to the stamped header.
+
+  minimized:
+    syntax: boolean
+    type: boolean
+    default: false
+    description: Collapses pane to header-only.
+
+  fixed-size:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Fixed flex value (e.g. "300px"). Sets flex to 0 1 {fixed-size}.
+
+  basis:
+    syntax: key-value
+    type: string
+    default: ""
+    description: Preferred size (e.g. "14rem"). Sets flex to 1 1 {basis}.
+
+  priority:
+    syntax: key-value
+    type: enum
+    values: [high, low]
+    default: ""
+    description: >
+      Resize priority. High-priority panes absorb delta first during
+      cascade resize. Low-priority panes resize last.
+
+composition:
+  parents: [aui-panes]
+  children: [any]
+
+examples:
+  - html: |
+      <aui-panes style="height: 20rem; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-pane label="Explorer" size="xs" density="compact">
+          <aui-stack gap="1" padding="2">
+            <aui-text muted size="xs">src/</aui-text>
+            <aui-text size="xs">components/</aui-text>
+            <aui-text size="xs">utils/</aui-text>
+          </aui-stack>
+        </aui-pane>
+        <aui-pane label="Editor" size="xs" density="compact">
+          <aui-stack gap="1" padding="2">
+            <aui-text muted size="xs">main.ts</aui-text>
+          </aui-stack>
+        </aui-pane>
+      </aui-panes>
+    description: Two-pane split with labeled headers and resizable boundary.
+
+  - html: |
+      <aui-panes direction="vertical" style="height: 20rem; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-pane label="Output" minimizable size="xs" density="compact">
+          <aui-stack padding="2">
+            <aui-text muted size="xs">Build succeeded in 1.2s</aui-text>
+          </aui-stack>
+        </aui-pane>
+        <aui-pane label="Terminal" minimizable size="xs" density="compact">
+          <aui-stack padding="2">
+            <aui-text size="xs" style="font-family: var(--aui-font-family-mono);">$ npm run dev</aui-text>
+          </aui-stack>
+        </aui-pane>
+      </aui-panes>
+    description: Vertical split with minimizable panes.

package/dist/docs/components/panes.yaml

@@ -0,0 +1,82 @@
+name: aui-panes
+tag: aui-panes
+type: component
+summary: Resizable split layout with pointer-proximity resize.
+description: >
+  Split-pane container with VS Code-style cascade resize. No handle elements —
+  resize boundaries are detected by pointer proximity (8px threshold) and
+  visualized with an accent bar. Supports priority-based size distribution,
+  min/max constraints, and proportional container resize.
+
+base: AgentElement
+
+attributes:
+  direction:
+    syntax: key-value
+    type: enum
+    values: [vertical]
+    default: ""
+    description: >
+      Layout direction. Default is horizontal (row). Set to "vertical"
+      for top/bottom stacking.
+
+composition:
+  parents: [any]
+  children: [aui-pane, aui-panes]
+  context: >
+    Direct children should be aui-pane elements. Nested aui-panes are
+    supported for complex layouts. No gripper elements needed — resize
+    is handled by pointer proximity detection.
+
+examples:
+  - html: |
+      <aui-panes style="height: 16rem; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-pane label="Sidebar" basis="12rem" size="xs" density="compact">
+          <aui-stack gap="1" padding="2">
+            <aui-text size="xs">Navigation</aui-text>
+            <aui-text muted size="xs">Drag the boundary to resize</aui-text>
+          </aui-stack>
+        </aui-pane>
+        <aui-pane label="Content" size="xs" density="compact">
+          <aui-stack gap="1" padding="2">
+            <aui-text size="xs">Main content area</aui-text>
+          </aui-stack>
+        </aui-pane>
+      </aui-panes>
+    description: Horizontal split — hover between panes to see resize handle.
+
+  - html: |
+      <aui-panes direction="vertical" style="height: 20rem; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-pane label="Editor" size="xs" density="compact">
+          <aui-stack padding="2">
+            <aui-text size="xs" style="font-family: var(--aui-font-family-mono);">const x = 42;</aui-text>
+          </aui-stack>
+        </aui-pane>
+        <aui-pane label="Terminal" basis="8rem" minimizable size="xs" density="compact">
+          <aui-stack padding="2">
+            <aui-text muted size="xs">$ npm run build</aui-text>
+          </aui-stack>
+        </aui-pane>
+      </aui-panes>
+    description: Vertical split with minimizable bottom pane.
+
+  - html: |
+      <aui-panes style="height: 18rem; border: 1px solid var(--aui-border-muted); border-radius: var(--aui-radius);">
+        <aui-pane label="Files" basis="10rem" priority="low" size="xs" density="compact">
+          <aui-stack gap="1" padding="2">
+            <aui-text size="xs">src/</aui-text>
+            <aui-text size="xs">tests/</aui-text>
+          </aui-stack>
+        </aui-pane>
+        <aui-pane label="Editor" priority="high" size="xs" density="compact">
+          <aui-stack padding="2">
+            <aui-text size="xs">Editor gets priority during resize</aui-text>
+          </aui-stack>
+        </aui-pane>
+        <aui-pane label="Preview" basis="12rem" size="xs" density="compact">
+          <aui-stack padding="2">
+            <aui-text muted size="xs">Live preview</aui-text>
+          </aui-stack>
+        </aui-pane>
+      </aui-panes>
+    description: Three-pane layout with resize priority.