@agent-ui-kit/web-components 0.0.8 → 0.0.14

package/dist/docs/components/nav-item.yaml

@@ -0,0 +1,93 @@
+name: aui-nav-item
+tag: aui-nav-item
+type: component
+summary: Navigation list item with icon, label, badge, and active state.
+description: >
+  Flex row navigation item with hover, active, and disabled states.
+  Supports icons and inline text. Use [active] to indicate the current
+  page. CSS-only element with no JS behavior beyond extending AgentElement.
+
+base: AgentElement
+
+# ── Modifiers ────────────────────────────────────────────
+
+modifiers:
+  active:
+    syntax: boolean
+    description: >
+      Marks the item as the current/active page. Applies stronger
+      text color, medium font weight, and a subtle background fill.
+
+  disabled:
+    syntax: boolean
+    description: >
+      Disables the item. Dims color and prevents pointer interaction.
+
+  muted:
+    syntax: boolean
+    description: >
+      Reduces opacity for de-emphasized items.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: inline
+  accepts: [text, aui-icon, aui-badge]
+  required: true
+  description: >
+    Label text and optional leading icon or trailing badge.
+    Icons and text are laid out in a flex row.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [text, aui-icon, aui-badge]
+    required: true
+    description: Nav item content — icon, label text, optional badge.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-nav-item-gap
+    - --aui-nav-item-padding-block
+    - --aui-nav-item-padding-inline
+    - --aui-nav-item-border-radius
+  typography:
+    - --aui-nav-item-font-size
+    - --aui-nav-item-font-weight
+    - --aui-nav-item-font-weight-active
+  color:
+    - --aui-nav-item-color
+    - --aui-nav-item-color-hover
+    - --aui-nav-item-color-active
+    - --aui-nav-item-color-disabled
+    - --aui-nav-item-background-hover
+    - --aui-nav-item-background-active
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-nav-item>Dashboard</aui-nav-item>
+    description: Default nav item.
+
+  - html: <aui-nav-item active>Dashboard</aui-nav-item>
+    description: Active nav item (current page).
+
+  - html: |
+      <aui-stack gap="1">
+        <aui-nav-item active>
+          <aui-icon name="home"></aui-icon>
+          Dashboard
+        </aui-nav-item>
+        <aui-nav-item>
+          <aui-icon name="settings"></aui-icon>
+          Settings
+        </aui-nav-item>
+        <aui-nav-item disabled>
+          <aui-icon name="lock"></aui-icon>
+          Admin
+        </aui-nav-item>
+      </aui-stack>
+    description: Nav list with active, default, and disabled items.

package/dist/docs/components/progress-circle.yaml

@@ -0,0 +1,105 @@
+name: aui-progress-circle
+tag: aui-progress-circle
+type: component
+summary: Circular SVG ring progress indicator with value, size, and intent variants.
+description: >
+  Circular progress ring rendered as an SVG arc. The value attribute
+  (0-100) is clamped by JS and mapped to stroke-dasharray via the
+  --aui-progress-circle-value custom property. Supports optional
+  center label text, size variants, and intent colors.
+
+base: AgentElement
+
+# -- Presentational attributes -----------------------------------------
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: default
+    values: [sm, lg]
+    description: >
+      Controls the ring diameter. Default is 48px. sm = 32px, lg = 64px.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: accent
+    values: [success, warning, danger]
+    description: >
+      Color family for the fill stroke. Default uses the accent color.
+
+# -- Component attributes ---------------------------------------------
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: >
+      Progress percentage (0-100). Clamped by JS and set as
+      --aui-progress-circle-value for the CSS stroke-dasharray calculation.
+
+  label:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Center text displayed over the ring (e.g. "75%").
+
+# -- Content model -----------------------------------------------------
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    No child content. The SVG ring and label are stamped by JS.
+
+# -- CSS tokens consumed -----------------------------------------------
+
+tokens:
+  - name: --aui-progress-circle-value
+    default: "0"
+    description: Fill percentage set by JS. Drives stroke-dasharray.
+
+# -- Accessibility -----------------------------------------------------
+
+a11y:
+  role: progressbar
+  aria:
+    aria-valuenow: Set from value attribute.
+    aria-valuemin: "0"
+    aria-valuemax: "100"
+
+# -- Use cases ---------------------------------------------------------
+
+use-cases:
+  - Usage/billing panels (storage, API quota rings).
+  - Dashboard KPI cards with circular metrics.
+  - Upload progress indicators.
+  - Profile completion rings.
+  - Plan limit indicators.
+
+# -- Examples ----------------------------------------------------------
+
+examples:
+  - html: <aui-progress-circle value="75"></aui-progress-circle>
+    description: Default progress circle at 75%.
+
+  - html: <aui-progress-circle value="75" label="75%"></aui-progress-circle>
+    description: Circle with center label.
+
+  - html: <aui-progress-circle value="90" warning></aui-progress-circle>
+    description: Warning intent at 90%.
+
+  - html: <aui-progress-circle value="100" success></aui-progress-circle>
+    description: Complete with success color.
+
+  - html: <aui-progress-circle value="60" size="sm"></aui-progress-circle>
+    description: Small size variant.
+
+  - html: <aui-progress-circle value="60" size="lg" label="60%"></aui-progress-circle>
+    description: Large size with label.

package/dist/docs/components/progress.yaml

@@ -0,0 +1,104 @@
+name: aui-progress
+tag: aui-progress
+type: component
+summary: Horizontal progress bar with value, size, and intent variants.
+description: >
+  A simple horizontal progress indicator. The fill width is driven by the
+  value attribute (0–100), which JS clamps and maps to the
+  --aui-progress-value custom property. The bar itself is rendered via a
+  CSS ::after pseudo-element — no inner DOM required. Size and intent
+  variants control height and fill color respectively.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: default
+    values: [sm, lg]
+    description: >
+      Controls the bar height. Default is 4px. sm = 2px, lg = 6px.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: neutral
+    values: [success, warning, danger, info]
+    description: >
+      Color family for the fill bar. Default uses the accent color.
+
+# ── Component attributes ──────────────────────────────────
+
+attributes:
+  value:
+    syntax: key-value
+    type: string
+    default: "0"
+    description: >
+      Progress percentage (0–100). Clamped by JS and set as
+      --aui-progress-value for the CSS width calculation.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    No child content. The bar is rendered entirely via CSS ::after.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  - name: --aui-progress-height
+    default: 4px
+    description: Bar height. Overridden by size attribute.
+  - name: --aui-progress-border-radius
+    default: 2px
+    description: Corner radius for both track and fill.
+  - name: --aui-progress-background
+    default: var(--aui-control)
+    description: Track background color.
+  - name: --aui-progress-fill
+    default: var(--aui-accent)
+    description: Fill bar color. Overridden by intent attributes.
+
+# ── Accessibility ─────────────────────────────────────────
+
+a11y:
+  role: progressbar
+  aria:
+    aria-valuenow: Set from value attribute.
+    aria-valuemin: "0"
+    aria-valuemax: "100"
+
+# ── Use cases ─────────────────────────────────────────────
+
+use-cases:
+  - Upload or download progress indicator.
+  - Step completion percentage in onboarding flows.
+  - Resource usage bar (storage, quota, CPU).
+  - Form completion meter.
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-progress value="40"></aui-progress>
+    description: Default progress bar at 40%.
+
+  - html: <aui-progress value="90" size="sm" success></aui-progress>
+    description: Small bar with success intent.
+
+  - html: <aui-progress value="60" size="lg" warning></aui-progress>
+    description: Large bar with warning intent.
+
+  - html: <aui-progress value="95" danger></aui-progress>
+    description: Danger intent at high usage.
+
+  - html: <aui-progress value="100" success></aui-progress>
+    description: Completed progress with success color.

package/dist/docs/components/skeleton.yaml

@@ -0,0 +1,81 @@
+name: aui-skeleton
+tag: aui-skeleton
+type: component
+summary: Loading placeholder with shimmer animation.
+description: >
+  Animated placeholder element for content that has not yet loaded.
+  Uses a gradient shimmer animation. Shape variants for text lines,
+  circles, and rectangles. Width and height set via inline style
+  bridging to CSS custom properties.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: md
+    values: [xs, sm, md, lg]
+    description: Controls placeholder height. xs=0.5rem, sm=0.75rem, md=1rem, lg=1.5rem.
+
+  type:
+    syntax: key-value
+    attribute: type
+    cascades: false
+    default: text
+    values: [text, circle, rect]
+    description: Shape variant — text line, avatar circle, or image rectangle.
+
+# ── Modifiers ─────────────────────────────────────────────
+
+modifiers:
+  round:
+    syntax: boolean
+    description: >
+      Fully rounded corners (pill shape). Applies radius-full
+      regardless of type.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    No content — skeleton is a visual placeholder only.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots: {}
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-skeleton-width
+    - --aui-skeleton-height
+  color:
+    - --aui-skeleton-base
+    - --aui-skeleton-highlight
+  shape:
+    - --aui-skeleton-radius
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-skeleton></aui-skeleton>
+    description: Default text line placeholder.
+
+  - html: <aui-skeleton type="circle"></aui-skeleton>
+    description: Circle placeholder for avatars.
+
+  - html: |
+      <aui-stack gap="2">
+        <aui-skeleton></aui-skeleton>
+        <aui-skeleton style="--aui-skeleton-width: 80%"></aui-skeleton>
+        <aui-skeleton style="--aui-skeleton-width: 60%"></aui-skeleton>
+      </aui-stack>
+    description: Multiple text lines with decreasing widths.

package/dist/docs/components/sparkline.yaml

@@ -0,0 +1,88 @@
+name: aui-sparkline
+tag: aui-sparkline
+type: component
+summary: Inline bar sparkline with configurable highlight and color.
+description: >
+  A compact bar chart rendered as a row of flex-aligned divs. Values
+  are passed as a comma-separated string and normalized against the
+  maximum. Each bar is stamped by JS with a percentage height and
+  chart color. The highlight attribute controls which bar is shown
+  at full opacity — "last" (default), "max", or "none".
+
+base: AgentElement
+
+# ── Component attributes ──────────────────────────────────
+
+attributes:
+  values:
+    syntax: key-value
+    type: string
+    default: ""
+    description: >
+      Comma-separated numeric values. Each value becomes one bar
+      whose height is proportional to the maximum value.
+
+  color:
+    syntax: key-value
+    type: string
+    default: "1"
+    description: >
+      Chart color index (1–8). Maps to --aui-chart-{n} token.
+
+  highlight:
+    syntax: key-value
+    type: string
+    default: last
+    values: [last, max, none]
+    description: >
+      Which bar to render at full opacity. "last" highlights the
+      final bar, "max" highlights the tallest bar, "none" shows
+      all bars at full opacity.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    No child content. Bars are stamped by JS from the values attribute.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  - name: --aui-sparkline-height
+    default: 2rem
+    description: Overall height of the sparkline container.
+  - name: --aui-sparkline-gap
+    default: calc(var(--aui-space) * 1)
+    description: Gap between adjacent bars.
+  - name: --aui-sparkline-bar-radius
+    default: var(--aui-radius)
+    description: Corner radius of each bar.
+
+# ── Accessibility ─────────────────────────────────────────
+
+a11y:
+  role: img
+  aria:
+    aria-label: Derived from values attribute for screen readers.
+
+# ── Use cases ─────────────────────────────────────────────
+
+use-cases:
+  - Inline trend indicator in table cells.
+  - Dashboard metric sparkline beside a stat card.
+  - Activity or usage micro-chart.
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-sparkline values="40,55,35,70,60,80,95"></aui-sparkline>
+    description: Default sparkline with last bar highlighted.
+
+  - html: <aui-sparkline values="60,45,55,50,70,65,85" highlight="max" color="2"></aui-sparkline>
+    description: Sparkline with max bar highlighted, color 2.
+
+  - html: <aui-sparkline values="30,50,40,60,55,45,50" highlight="none" color="3"></aui-sparkline>
+    description: All bars at full opacity, color 3.

package/dist/docs/components/spinner.yaml

@@ -0,0 +1,75 @@
+name: aui-spinner
+tag: aui-spinner
+type: component
+summary: Animated loading indicator.
+description: >
+  CSS-only spinning ring indicator for inline and block-level
+  loading states. Border-based animation with configurable
+  size and intent coloring. Uses currentColor by default so it
+  inherits text color from its parent.
+
+base: AgentElement
+
+# ── Presentational attributes ─────────────────────────────
+
+presentational:
+  size:
+    syntax: key-value
+    attribute: size
+    cascades: false
+    default: md
+    values: [xs, sm, md, lg]
+    description: Diameter of the spinner ring. xs=1rem, sm=1.25rem, md=1.5rem, lg=2rem.
+
+  intent:
+    syntax: boolean
+    exclusive: true
+    cascades: false
+    default: null
+    values: [accent, success, warning, danger]
+    description: Color of the spinning ring segment.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: empty
+  accepts: []
+  required: false
+  description: >
+    No content — spinner is a visual indicator only.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots: {}
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-spinner-size
+    - --aui-spinner-border-width
+  color:
+    - --aui-spinner-track
+    - --aui-spinner-fill
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: <aui-spinner></aui-spinner>
+    description: Default medium spinner.
+
+  - html: |
+      <aui-stack direction="row" gap="3" align-items="center">
+        <aui-spinner size="xs"></aui-spinner>
+        <aui-spinner size="sm"></aui-spinner>
+        <aui-spinner></aui-spinner>
+        <aui-spinner size="lg"></aui-spinner>
+      </aui-stack>
+    description: All four sizes side by side.
+
+  - html: |
+      <aui-stack direction="row" gap="2" align-items="center">
+        <aui-spinner size="xs"></aui-spinner>
+        <aui-text size="sm">Loading...</aui-text>
+      </aui-stack>
+    description: Inline spinner with loading text.

package/dist/docs/components/step.yaml

@@ -0,0 +1,91 @@
+name: aui-step
+tag: aui-step
+type: component
+summary: Individual step within a stepper, with state-driven connector colors.
+description: >
+  A single step inside an aui-stepper. Renders as a flex row with a
+  connector line drawn via ::before to the next sibling. State attributes
+  control the connector color.
+
+base: AgentElement
+
+# ── Modifiers ────────────────────────────────────────────
+
+modifiers:
+  completed:
+    syntax: boolean
+    description: >
+      Step is completed. Colors the connector green (success).
+
+  active:
+    syntax: boolean
+    description: >
+      Step is currently active. Colors the connector with accent.
+
+  error:
+    syntax: boolean
+    description: >
+      Step has an error. Colors the connector red (danger).
+
+# ── Attributes ───────────────────────────────────────────
+
+attributes:
+  state:
+    syntax: key-value
+    type: enum
+    values: [done, running]
+    default: null
+    description: >
+      Legacy step state. "done" maps to completed, "running" maps to active.
+
+# ── Content model ─────────────────────────────────────────
+
+content:
+  model: block
+  accepts: [aui-badge, aui-icon, aui-text, aui-heading, aui-stack]
+  required: true
+  description: >
+    Step content. Typically starts with a visual indicator (badge
+    or icon) followed by a label or description.
+
+# ── Slots ─────────────────────────────────────────────────
+
+slots:
+  default:
+    accepts: [aui-badge, aui-icon, aui-text, aui-heading, aui-stack]
+    required: true
+    description: Step indicator and content.
+
+# ── CSS tokens consumed ──────────────────────────────────
+
+tokens:
+  sizing:
+    - --aui-step-gap
+    - --aui-step-connector-width
+    - --aui-step-connector-offset
+  color:
+    - --aui-step-connector-color
+
+# ── Examples ──────────────────────────────────────────────
+
+examples:
+  - html: |
+      <aui-step completed>
+        <aui-badge success>1</aui-badge>
+        <aui-text>Account created</aui-text>
+      </aui-step>
+    description: Completed step with success badge.
+
+  - html: |
+      <aui-step active>
+        <aui-badge accent>2</aui-badge>
+        <aui-text>In progress</aui-text>
+      </aui-step>
+    description: Active step with accent badge.
+
+  - html: |
+      <aui-step>
+        <aui-badge>3</aui-badge>
+        <aui-text>Pending</aui-text>
+      </aui-step>
+    description: Pending step with neutral badge.