@adia-ai/web-components 0.6.47 → 0.6.48

package/components/preview/preview.css

@@ -0,0 +1,176 @@
+/* ============================================================
+   <preview-ui> — live code + render, single source of truth.
+
+   A framed demo surface: a "stage" holding the live components on top
+   (or beside) the same markup shown as escaped, highlighted, copyable
+   HTML via a nested <code-ui>. The frame owns the chrome; the inner
+   code-ui's own border/radius are flattened so the two panes read as
+   one card.
+
+   Two-block @scope per docs/specs/component-token-contract.md.
+   ============================================================ */
+
+@scope (preview-ui) {
+  /* ── Block 1 — TOKENS ── */
+  :where(:scope) {
+    --preview-border-default:       1px solid var(--a-border-subtle);
+    --preview-radius-default:       var(--a-radius-lg);
+    --preview-render-bg-default:    var(--a-canvas-1);
+    --preview-render-pad-default:   var(--a-space-6);
+    --preview-render-gap-default:   var(--a-space-3);
+    /* split column floor — below this the grid wraps to a single column
+       (responsive without container-type; see ADR note in css-patterns). */
+    --preview-split-min-default:    20rem;
+  }
+
+  /* ── Block 2 — BASE ── */
+  :scope {
+    display: block;
+    border: var(--preview-border, var(--preview-border-default));
+    border-radius: var(--preview-radius, var(--preview-radius-default));
+    overflow: hidden;
+    background: var(--preview-render-bg, var(--preview-render-bg-default));
+  }
+
+  /* Render stage — wraps live demo nodes; flex row so multiple sibling
+     samples (e.g. button variants) sit on one line and wrap. overflow-x:auto is
+     the last-resort affordance: a single unwrappable sample wider than even the
+     full-width stage (a page-scale composite) scrolls instead of being clipped
+     by the frame's overflow:hidden. Most demos fit (the component's overflow
+     check stacks split→full-width first), so the scrollbar only appears when a
+     demo is genuinely wider than the docs column. */
+  [data-preview-render] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--preview-render-gap, var(--preview-render-gap-default));
+    padding: var(--preview-render-pad, var(--preview-render-pad-default));
+    background: var(--preview-render-bg, var(--preview-render-bg-default));
+    overflow-x: auto;
+  }
+
+  /* Code pane — divider line between panes; flatten the nested code-ui
+     chrome so the preview frame owns the outer border + radius. */
+  [data-preview-code] {
+    border-block-start: var(--preview-border, var(--preview-border-default));
+    min-width: 0; /* allow the code-ui to shrink in split grid */
+  }
+  [data-preview-code] code-ui {
+    display: block;
+    --code-border: transparent;
+    --code-radius: 0;
+    --code-bg: var(--a-bg);
+  }
+
+  /* code-first — divider moves to the bottom of the (now-leading) code pane */
+  :scope[code-first] [data-preview-code] {
+    border-block-start: none;
+    border-block-end: var(--preview-border, var(--preview-border-default));
+  }
+
+  /* Stacked layout — render above code. This is the BASE behaviour (above), so
+     [layout="stack"] just names it explicitly: it's the opt-out from the
+     side-by-side default that a bare <preview-ui> stamps on connect, and the
+     value the docs pin onto wide self-framing demos (card / shell / table). */
+  :scope[layout="stack"] {
+    display: block;
+  }
+
+  /* ── Split layout — render + code side-by-side ──
+     auto-fit grid collapses to one column under --preview-split-min with
+     NO container-type (avoids the flex-child-collapse trap; see memory
+     `container_name_convention`). When wrapped, the inter-pane divider
+     reverts to the stacked top-border via the base rule above. */
+  :scope[layout="split"] {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--preview-split-min, var(--preview-split-min-default))), 1fr));
+  }
+  :scope[layout="split"] [data-preview-code] {
+    border-block-start: none;
+    border-inline-start: var(--preview-border, var(--preview-border-default));
+    /* Stretch code-ui to the grid row height — the render side is often
+       taller, so a short snippet would otherwise leave an empty code surface
+       below it (same fill as rows mode). */
+    display: grid;
+  }
+  :scope[layout="split"] [data-preview-code] code-ui {
+    height: 100%;
+  }
+  /* Single-column fallback (grid wrapped): restore the horizontal divider.
+     :scope[layout="split"] with one effective column → the code pane is on
+     its own row, so the inline-start border reads as a stray left edge.
+     Guard with a width media as a pragmatic floor. */
+  @media (max-width: 32rem) {
+    :scope[layout="split"] [data-preview-code] {
+      border-inline-start: none;
+      border-block-start: var(--preview-border, var(--preview-border-default));
+    }
+  }
+
+  /* ══════════ rows mode — a gallery of [render | code] rows ══════════
+     Each example is its own row: live render on the left, its source on the
+     right, paired side-by-side (no all-renders-then-one-code-dump). Rows
+     stack with a divider between them; each row is a 2-col grid that
+     collapses to stacked on narrow widths. */
+  :scope[rows] {
+    display: block;
+  }
+  :scope[rows] [data-preview-row] {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    align-items: stretch;
+  }
+  :scope[rows] [data-preview-row] + [data-preview-row] {
+    border-block-start: var(--preview-border, var(--preview-border-default));
+  }
+  /* In rows mode the render/code panes butt horizontally — divider is the
+     inline-start border on the code cell, not the stacked top-border. The
+     cell is a grid so the nested code-ui STRETCHES to the row height (the
+     render side is often taller), filling the dark code surface instead of
+     leaving empty space below a short snippet. */
+  :scope[rows] [data-preview-row] > [data-preview-code] {
+    border-block-start: none;
+    border-inline-start: var(--preview-border, var(--preview-border-default));
+    display: grid;
+  }
+  :scope[rows] [data-preview-row] > [data-preview-code] code-ui {
+    height: 100%;
+  }
+  /* Optional per-row caption pill (from [data-preview-label] on the render
+     cell — attr() reads the element's OWN attribute). The render cell becomes
+     a column so the pill sits above the live sample. */
+  :scope[rows] [data-preview-render][data-preview-label] {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+  :scope[rows] [data-preview-render][data-preview-label]::before {
+    content: attr(data-preview-label);
+    align-self: start;
+    font-family: var(--a-font-family-mono);
+    font-size: var(--a-ui-sm);
+    color: var(--a-fg-muted);
+    background: var(--a-bg-muted);
+    padding: 0.125rem 0.375rem;
+    border-radius: var(--a-radius-sm);
+  }
+  /* Narrow: collapse each row to stacked render-over-code. */
+  @media (max-width: 40rem) {
+    :scope[rows] [data-preview-row] {
+      grid-template-columns: 1fr;
+    }
+    :scope[rows] [data-preview-row] > [data-preview-code] {
+      border-inline-start: none;
+      border-block-start: var(--preview-border, var(--preview-border-default));
+    }
+  }
+  /* Content-driven fallback — a single row whose live sample is wider than the
+     half-width cell gets [data-stack] from the component's overflow check, so it
+     lays out render-over-code at full width (wide controls / composites). */
+  :scope[rows] [data-preview-row][data-stack] {
+    grid-template-columns: 1fr;
+  }
+  :scope[rows] [data-preview-row][data-stack] > [data-preview-code] {
+    border-inline-start: none;
+    border-block-start: var(--preview-border, var(--preview-border-default));
+  }
+}

package/components/preview/preview.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `<preview-ui>` — Live code + render in one frame, from a single source. Wrap any authored AdiaUI markup: the same HTML renders LIVE in a stage and appears beside (or below) it as escaped, syntax-highlighted, copyable source via a nested <code-ui>. The code can never drift from the render — it IS the render's source. Batteries-included + HTML-first by construction: write one block of HTML, no inline styles, no JS wiring, and both panes appear. Use it for every component/recipe example so the primary snippet is always real, copyable HTML shown next to the working component.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/preview
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIPreview extends UIElement {
+  /** Show the code pane before (above / left of) the render pane. Default is render-first. */
+  codeFirst: boolean;
+  /** Language hint forwarded to the nested <code-ui> for syntax highlighting. Demos are HTML, so this defaults to `html`. */
+  language: string;
+  /** Pane arrangement. Defaults to `split` — render and code side-by-side in a responsive 2-column grid that collapses to stacked on narrow widths (a bare `<preview-ui>` stamps `layout="split"` on connect). Use `stack` to force the render stacked above the code; the docs auto-apply `stack` to wide self-framing demos (card / shell / table) that read cramped at half width. The `rows` attribute is a separate gallery mode and overrides this. */
+  layout: 'split' | 'stack';
+  /** Gallery mode — treat each direct child as a SEPARATE example and lay each out as its own `[render | code]` row (live sample left, its own source right), stacked with dividers. Without `rows`, the whole slotted markup is one render + one code block. An optional `data-preview-label` on a child surfaces a caption above that row's sample. */
+  rows: boolean;
+}

package/components/preview/preview.js

@@ -0,0 +1,22 @@
+/**
+ * `<preview-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIPreview } from '@adia-ai/web-components/components/preview/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIPreview } from './preview.class.js';
+
+// preview-ui composes <code-ui> for the source pane — pull it in so a bare
+// `import '.../preview'` is batteries-included (the code pane works without
+// the consumer separately importing code-ui).
+import '../code/code.js';
+
+defineIfFree('preview-ui', UIPreview);
+
+export { UIPreview };

package/components/preview/preview.yaml

@@ -0,0 +1,100 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIPreview
+tag: preview-ui
+status: stable
+component: Preview
+category: display
+version: 1
+description: >-
+  Live code + render in one frame, from a single source. Wrap any authored
+  AdiaUI markup: the same HTML renders LIVE in a stage and appears beside (or
+  below) it as escaped, syntax-highlighted, copyable source via a nested
+  <code-ui>. The code can never drift from the render — it IS the render's
+  source. Batteries-included + HTML-first by construction: write one block of
+  HTML, no inline styles, no JS wiring, and both panes appear. Use it for
+  every component/recipe example so the primary snippet is always real,
+  copyable HTML shown next to the working component.
+props:
+  layout:
+    description: >-
+      Pane arrangement. Defaults to `split` — render and code side-by-side in a
+      responsive 2-column grid that collapses to stacked on narrow widths (a bare
+      `<preview-ui>` stamps `layout="split"` on connect). Use `stack` to force the
+      render stacked above the code; the docs auto-apply `stack` to wide
+      self-framing demos (card / shell / table) that read cramped at half width.
+      The `rows` attribute is a separate gallery mode and overrides this.
+    type: string
+    default: ""
+    reflect: true
+    enum:
+      - split
+      - stack
+  codeFirst:
+    description: >-
+      Show the code pane before (above / left of) the render pane. Default is
+      render-first.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: code-first
+  language:
+    description: >-
+      Language hint forwarded to the nested <code-ui> for syntax highlighting.
+      Demos are HTML, so this defaults to `html`.
+    type: string
+    default: html
+    reflect: true
+  rows:
+    description: >-
+      Gallery mode — treat each direct child as a SEPARATE example and lay
+      each out as its own `[render | code]` row (live sample left, its own
+      source right), stacked with dividers. Without `rows`, the whole slotted
+      markup is one render + one code block. An optional `data-preview-label`
+      on a child surfaces a caption above that row's sample.
+    type: boolean
+    default: false
+    reflect: true
+slots:
+  default:
+    description: >-
+      The authored markup to preview. Captured verbatim on connect: re-parsed
+      into the live render stage AND shown literally in the code pane. Any
+      valid AdiaUI HTML — one element or many siblings.
+states:
+  - name: idle
+    description: Default, the only state.
+keywords:
+  - preview
+  - example
+  - demo
+  - code-preview
+  - live-preview
+  - playground
+  - codepen
+synonyms:
+  preview: [example, demo, sandbox, live-preview]
+related:
+  - Code
+  - Card
+a2ui:
+  rules:
+    - rule: >-
+        Use <preview-ui> to demonstrate ANY component or recipe — wrap the
+        example markup once; it shows the live component and its copyable HTML
+        source together. Prefer it over a bare <code-ui> snippet (which shows
+        code but no render) or a bare rendered sample (which shows output but
+        no copyable HTML).
+      reason: 'Single source of truth — code and render cannot drift.'
+    - rule: >-
+        Author the slotted markup as plain AdiaUI HTML with attributes only —
+        no inline `style=`, no `<script>` wiring. If a sample needs inline
+        styles to look right, the component is missing an attribute; fix the
+        component, not the demo.
+      reason: 'Demos are the reference the next author copies; keep them honest.'
+    - rule: >-
+        Side-by-side ([layout="split"]) is the default. Set [layout="stack"] for
+        wide self-framing examples (a full card / shell / table reads cramped at
+        half width). Use [code-first] when the code is the teaching point and the
+        render is confirmation.
+      reason: 'Layout matches the reading order of the lesson.'

package/components/progress/progress.a2ui.json

@@ -22,16 +22,11 @@
       "default": null
     },
     "variant": {
-      "description": "Display variant. Structural values (bar, spinner) set the render mode; semantic values (primary/success/warning/danger/info) set the fill color. Prefer the `color` global attribute for color; variant-as-color accepted for back-compat with older exemplars.",
+      "description": "Render mode — `bar` (default) or `spinner`. For fill color set the `--progress-fill` token (defaults to `--a-accent`); there is no variant-as-color (use the token).",
       "type": "string",
       "enum": [
         "bar",
-        "spinner",
-        "primary",
-        "success",
-        "warning",
-        "danger",
-        "info"
+        "spinner"
       ],
       "default": "bar"
     }

package/components/progress/progress.d.ts

@@ -15,6 +15,6 @@ import { UIElement } from '../../core/element.js';
 export class UIProgress extends UIElement {
   /** Current progress. 0..max (or 0..1 when max omitted). null = indeterminate (legacy -1 accepted for back-compat). */
   value: number;
-  /** Display variant. Structural values (bar, spinner) set the render mode; semantic values (primary/success/warning/danger/info) set the fill color. Prefer the `color` global attribute for color; variant-as-color accepted for back-compat with older exemplars. */
-  variant: 'bar' | 'spinner' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+  /** Render mode — `bar` (default) or `spinner`. For fill color set the `--progress-fill` token (defaults to `--a-accent`); there is no variant-as-color (use the token). */
+  variant: 'bar' | 'spinner';
 }

package/components/progress/progress.yaml

@@ -17,19 +17,14 @@ props:
     type: number
     default: null
   variant:
-    description: Display variant. Structural values (bar, spinner) set the render mode; semantic values (primary/success/warning/danger/info)
-      set the fill color. Prefer the `color` global attribute for color; variant-as-color accepted for back-compat with older
-      exemplars.
+    description: Render mode — `bar` (default) or `spinner`. For fill color set
+      the `--progress-fill` token (defaults to `--a-accent`); there is no
+      variant-as-color (use the token).
     type: string
     default: bar
     enum:
     - bar
     - spinner
-    - primary
-    - success
-    - warning
-    - danger
-    - info
 events: {}
 slots:
   fill:

package/components/progress-row/progress-row.a2ui.json

@@ -36,11 +36,9 @@
       "type": "string",
       "enum": [
         "default",
-        "accent",
         "success",
         "warning",
-        "danger",
-        "info"
+        "danger"
       ],
       "default": "default"
     }

package/components/progress-row/progress-row.d.ts

@@ -20,5 +20,5 @@ export class UIProgressRow extends UIElement {
   /** Progress value 0-100 (null = indeterminate; legacy -1 accepted for back-compat) */
   value: number;
   /** Color variant for the progress fill */
-  variant: 'default' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+  variant: 'default' | 'success' | 'warning' | 'danger';
 }

package/components/progress-row/progress-row.yaml

@@ -32,11 +32,9 @@ props:
     default: default
     enum:
       - default
-      - accent
       - success
       - warning
       - danger
-      - info
 events: {}
 slots:
   label:

package/components/select/select.a2ui.json

@@ -152,13 +152,11 @@
       "default": ""
     },
     "variant": {
-      "description": "Visual variant — default chrome, `outline` for bordered, `ghost` for inline.",
+      "description": "Visual variant — `default` chrome or `ghost` for inline.",
       "type": "string",
       "enum": [
         "default",
-        "outline",
-        "ghost",
-        "soft"
+        "ghost"
       ],
       "default": "default"
     }

package/components/select/select.yaml

@@ -31,10 +31,10 @@ props:
     type: string
     default: ""
   variant:
-    description: Visual variant — default chrome, `outline` for bordered, `ghost` for inline.
+    description: Visual variant — `default` chrome or `ghost` for inline.
     type: string
     default: default
-    enum: [default, outline, ghost, soft]
+    enum: [default, ghost]
   size:
     description: >-
       Sizing scale via universal `[size]` attribute system

package/components/tabs/tabs.a2ui.json

@@ -27,13 +27,10 @@
       "default": ""
     },
     "variant": {
-      "description": "Visual variant — default underline strip, `pills` for filled pill tabs, `underline` (explicit).",
+      "description": "Visual variant — `default` (underline strip) or `bordered`.",
       "type": "string",
       "enum": [
         "default",
-        "pills",
-        "underline",
-        "segmented",
         "bordered"
       ],
       "default": "default"

package/components/tabs/tabs.d.ts

@@ -24,8 +24,8 @@ export class UITabs extends UIElement {
   orientation: string;
   /** Value of the currently active tab. Set programmatically or auto-assigned to the first non-disabled tab on connect. */
   value: string;
-  /** Visual variant — default underline strip, `pills` for filled pill tabs, `underline` (explicit). */
-  variant: 'default' | 'pills' | 'underline' | 'segmented' | 'bordered';
+  /** Visual variant — `default` (underline strip) or `bordered`. */
+  variant: 'default' | 'bordered';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/tabs/tabs.yaml

@@ -22,10 +22,10 @@ props:
     type: string
     default: ""
   variant:
-    description: Visual variant — default underline strip, `pills` for filled pill tabs, `underline` (explicit).
+    description: Visual variant — `default` (underline strip) or `bordered`.
     type: string
     default: default
-    enum: [default, pills, underline, segmented, bordered]
+    enum: [default, bordered]
   value:
     description: Value of the currently active tab. Set programmatically or auto-assigned to the first
       non-disabled tab on connect.

package/core/anchor.js

@@ -75,7 +75,11 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
   //     past the cap is silently hidden).
   // Consumers can override per-instance via --popover-* tokens / inline style.
   popover.style.width = matchWidth ? `anchor-size(${name} width)` : 'max-content';
-  popover.style.maxWidth = 'min(calc(100vw - 1rem), 32rem)';
+  // 32rem default cap keeps ordinary popovers from sprawling; wide-content
+  // popovers (e.g. a dual-month date-range picker) opt into a larger cap by
+  // setting --popover-max-width on the popover element. Viewport safety
+  // (100vw - 1rem) still wins so nothing escapes the screen.
+  popover.style.maxWidth = 'min(calc(100vw - 1rem), var(--popover-max-width, 32rem))';
   popover.style.maxHeight = 'calc(100vh - 3rem)';
   popover.style.overflowY = 'auto';