@adia-ai/web-components 0.6.47 → 0.6.48

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.48] — 2026-05-29
+
+### Demos — library-wide consolidation sweep (HTML-first)
+
+- **`components/**/*.examples.html` + `traits/**/*.examples.html`** — Usage-section consolidation across 83 components + 45 traits: every example now shows its own auto-stamped HTML, so the standalone Usage cheat-sheet was redundant. Per-page consolidations (text, card, drawer) + implemented-matrix depth fills. See the root CHANGELOG for the full campaign.
+
+### Changed — foundation styles reorganized by dimension × layer (ADR-0035)
+
+- **`styles/`** — the foundation token surface is now organized by **dimension × layer**. `tokens.css`, `typography.css`, and `colors/semantics.css` remain as **compat barrels** at their published paths (the `@adia-ai/web-components/styles/*` export map and the `<link>` surface are unchanged); their content moved to single-responsibility files — `foundation/{space,size,radius,motion,elevation}.css`, `type/{scale,roles,elements}.css`, `colors/semantics/{core,buckets,features,data-viz,aliases}.css` — and the global attribute API to `api/{sizing,text,layout}.css`. New `styles/index.css` is the real barrel; the package-root `index.css` re-exports it. **Behavior-neutral** — identical custom-property declaration multiset in the minified bundle (see ADR-0035). Fixed in passing: the dead `--ui-focus` reference in the global `:focus-visible` fallback, and element-typography defaults consolidated into `type/elements.css`.
+- **`scripts/release/check-foundation-layer-placement.mjs`** — new audit (wired into `npm run check`) enforcing the layout: header tags present, primitives free of attribute selectors, the global attribute API confined to `api/`, no orphan files.
+- **`dist/web-components.min.css`** — bundle rebuild reflecting the reorg (no behavioral change).
+
+### Fixed — `<date-range-picker>` popover clipped its second month
+
+- **`core/anchor.js`** — the anchored-popover viewport-safety cap was a hard
+  `max-width: min(100vw - 1rem, 32rem)`. It's now `min(100vw - 1rem,
+  var(--popover-max-width, 32rem))`, so a wide-content popover can raise the
+  32rem cap by setting `--popover-max-width` on the popover element (default
+  unchanged → ordinary popovers like `popover-ui` / `menu-ui` / `select-ui` keep
+  the 512px cap). Viewport safety still wins.
+- **`components/date-range-picker/date-range-picker.css`** — the preset rail plus
+  two side-by-side month panes need ~656px, but the 32rem (512px) cap clipped the
+  second month inside the popover. The popover now opts into
+  `--popover-max-width: 48rem` (new `--date-range-picker-popover-max-width` token),
+  and `[data-calendar-area]` gains `flex-wrap: wrap` so the second pane wraps below
+  the first when the viewport clamps the popover narrower than two months (instead
+  of clipping). Fixes `<date-range-selector>` too (it embeds the picker). 32/32
+  picker tests pass; no regression on other popovers.
+
+### Changed — `<preview-ui>` (docs primitive)
+
+- **Side-by-side is the default + self-correcting.** A bare `<preview-ui>` stamps
+  `layout="split"` (render | code); a render cell wider than its half-width cell
+  downgrades to stacked after layout (rAF + `ResizeObserver`: `split`→`layout="stack"`,
+  or a row gains `[data-stack]`), and `overflow-x:auto` lets a page-scale composite
+  scroll rather than clip. New `layout="stack"` enum value + CSS.
+- **`dedent` indentation fix** — measures the common indent from the body (lines
+  after the first) so markup captured with the opening tag at column 0 no longer
+  renders its children deeply over-indented.
+- **`[data-preview-unwrap]`** — multi-element rows show their children's markup, not
+  the throwaway layout wrapper, in the code pane.
+
 ## [0.6.47] — 2026-05-29
 
 ### Added — `<card-ui>` `[grow]` section attribute

package/components/badge/badge.d.ts

@@ -29,6 +29,20 @@ export class UIBadge extends UIElement {
   text: string;
   /** Badge display text. Renderer routes this to the `text` attribute via CSS attr(text) on ::after. */
   textContent: string;
+  /** Fill style — orthogonal to [variant]. Badge defaults to `muted`
+(quiet metadata is the primitive's identity — counts, IDs, status
+pills in dense rows). Three values:
+  - `muted` (default) — tinted bg + scheme-paired text. Same as
+    the existing family-variant rules.
+  - `solid` — saturated bg + on-strong text. Use for hero badges
+    where the badge IS the state (e.g. a single inline error). The
+    existing `primary` variant is a shortcut for accent + solid.
+  - `outline` — transparent bg + family-colored border + family-
+    colored text. Lightest visual weight; good in dense data rows.
+Vocabulary mirrors `<tag-ui>` (which defaults to solid, given its
+different role as filter / autocomplete chip).
+ */
+  tone: 'muted' | 'solid' | 'outline';
   /** Semantic color variant. */
   variant: 'default' | 'accent' | 'info' | 'success' | 'warning' | 'danger' | 'primary' | 'muted' | 'neutral';
 }

package/components/button/button.a2ui.json

@@ -88,10 +88,7 @@
         "solid",
         "outline",
         "ghost",
-        "primary",
-        "secondary",
-        "soft",
-        "current"
+        "primary"
       ],
       "default": "solid"
     }

package/components/button/button.d.ts

@@ -33,7 +33,7 @@ export class UIButton extends UIElement {
   textContent: string;
   /** Visual style — `solid` (default fill), `outline`, `ghost`. `default` / `primary` are aliases of `solid`. Style is independent of semantic intent — to express destructive / success / info / warning intent, set [color="…"] alongside.
 For **inline navigation** (Terms of Service, Privacy Policy, footer links, "Sign in" / "Sign up" cross-page affordances) use `<link-ui>` instead — it carries proper `<a href>` semantics, keyboard handling (Enter only, no Space), middle-click open-new-tab, and screen-reader announces "link" instead of "button". Mixing navigation and action affordances under the same primitive is a category error fixed at this junction. */
-  variant: 'default' | 'solid' | 'outline' | 'ghost' | 'primary' | 'secondary' | 'soft' | 'current';
+  variant: 'default' | 'solid' | 'outline' | 'ghost' | 'primary';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/button/button.yaml

@@ -80,9 +80,6 @@ props:
       - outline
       - ghost
       - primary
-      - secondary
-      - soft
-      - current
   color:
     description: >-
       Semantic intent — composes with [variant]. `<button-ui variant="solid" color="danger">`

package/components/calendar-grid/calendar-grid.css

@@ -15,9 +15,12 @@
 @scope (calendar-grid-ui) {
   /* ── Block 1 — TOKENS ── */
   :where(:scope) {
-    /* Layout */
+    /* Layout
+       Width derives from the day-cell size so the grid scales with the
+       universal [size] system (sm/md/lg) exactly like select/input/button:
+       7 columns at --a-size + 6 inter-cell gaps' worth of breathing room. */
     --calendar-grid-gap-default:                var(--a-space-1);
-    --calendar-grid-width-default:              16rem;
+    --calendar-grid-width-default:              calc(7 * var(--a-size) + 6 * var(--a-space-1));
 
     /* Header */
     --calendar-grid-header-gap-default:         var(--a-space-1);
@@ -26,26 +29,32 @@
     --calendar-grid-title-size-default:         var(--a-ui-size);
     --calendar-grid-title-weight-default:       var(--a-weight-medium);
 
-    /* Nav buttons (prev/next) */
-    --calendar-grid-nav-size-default:           1.5rem;
+    /* Nav buttons (prev/next) — secondary chrome at one notch below the
+       control height (mirrors select's `calc(height - gap)` idiom); icon
+       is a directional chevron sized from the universal --a-caret-size. */
+    --calendar-grid-nav-size-default:           calc(var(--a-size) - var(--a-space-2));
     --calendar-grid-nav-radius-default:         var(--a-radius-sm);
     --calendar-grid-nav-bg-default:             transparent;
     --calendar-grid-nav-bg-hover-default:       var(--a-bg-muted);
     --calendar-grid-nav-fg-default:             var(--a-fg-muted);
     --calendar-grid-nav-fg-hover-default:       var(--a-fg);
-    --calendar-grid-nav-icon-size-default:      0.75rem;
+    --calendar-grid-nav-icon-size-default:      var(--a-caret-size);
 
-    /* Weekday header */
+    /* Weekday header — row height tracks the control height (one notch
+       below, like nav); label font scales with the tier via --a-ui-size
+       (de-emphasis comes from color + weight, not a frozen small size). */
     --calendar-grid-weekday-fg-default:         var(--a-fg-muted);
-    --calendar-grid-weekday-size-default:       var(--a-ui-sm);
+    --calendar-grid-weekday-size-default:       var(--a-ui-size);
     --calendar-grid-weekday-weight-default:     var(--a-weight-medium);
-    --calendar-grid-weekday-height-default:     1.5rem;
+    --calendar-grid-weekday-height-default:     calc(var(--a-size) - var(--a-space-2));
     --calendar-grid-weekday-mb-default:         var(--a-space-1);
 
-    /* Day cells */
-    --calendar-grid-day-size-default:           2rem;
+    /* Day cells — the interactive targets size from --a-size (control
+       height) and scale their digits with --a-ui-size, exactly like a
+       button/select row. */
+    --calendar-grid-day-size-default:           var(--a-size);
     --calendar-grid-day-radius-default:         var(--a-radius);
-    --calendar-grid-day-font-size-default:      var(--a-ui-sm);
+    --calendar-grid-day-font-size-default:      var(--a-ui-size);
     --calendar-grid-day-bg-default:             transparent;
     --calendar-grid-day-fg-default:             var(--a-fg-subtle);
     --calendar-grid-day-bg-hover-default:       var(--a-bg-hover);

package/components/calendar-picker/calendar-picker.css

@@ -30,7 +30,10 @@
     --calendar-picker-popover-radius-default:         var(--a-radius-lg);
     --calendar-picker-popover-shadow-default:         var(--a-shadow-lg);
     --calendar-picker-popover-padding-default:        var(--a-space-2);
-    --calendar-picker-popover-width-default:          16rem;
+    /* Width derives from the day-grid so the popover scales with [size]:
+       7 columns at --a-size + inter-cell breathing + popover padding both
+       sides (border-box). Matches calendar-grid-ui's width formula. */
+    --calendar-picker-popover-width-default:          calc(7 * var(--a-size) + 6 * var(--a-space-1) + 2 * var(--a-space-2));
     --calendar-picker-popover-fg-default:             var(--a-fg);
 
     /* Header */
@@ -40,26 +43,32 @@
     --calendar-picker-title-size-default:             var(--a-ui-size);
     --calendar-picker-title-weight-default:           var(--a-weight-medium);
 
-    /* Nav buttons (prev/next) */
-    --calendar-picker-nav-size-default:               1.5rem;
+    /* Nav buttons (prev/next) — secondary chrome at one notch below the
+       control height (mirrors select's `calc(height - gap)` idiom); icon
+       is a directional chevron sized from the universal --a-caret-size. */
+    --calendar-picker-nav-size-default:               calc(var(--a-size) - var(--a-space-2));
     --calendar-picker-nav-radius-default:             var(--a-radius-sm);
     --calendar-picker-nav-bg-default:                 transparent;
     --calendar-picker-nav-bg-hover-default:           var(--a-bg-muted);
     --calendar-picker-nav-fg-default:                 var(--a-fg-muted);
     --calendar-picker-nav-fg-hover-default:           var(--a-fg);
-    --calendar-picker-nav-icon-size-default:          0.75rem;
+    --calendar-picker-nav-icon-size-default:          var(--a-caret-size);
 
-    /* Weekday header */
+    /* Weekday header — row height tracks the control height (one notch
+       below, like nav); label font scales with the tier via --a-ui-size
+       (de-emphasis comes from color + weight, not a frozen small size). */
     --calendar-picker-weekday-fg-default:             var(--a-fg-muted);
-    --calendar-picker-weekday-size-default:           var(--a-ui-sm);
+    --calendar-picker-weekday-size-default:           var(--a-ui-size);
     --calendar-picker-weekday-weight-default:         var(--a-weight-medium);
-    --calendar-picker-weekday-height-default:         1.5rem;
+    --calendar-picker-weekday-height-default:         calc(var(--a-size) - var(--a-space-2));
     --calendar-picker-weekday-mb-default:             var(--a-space-1);
 
-    /* Day cells */
-    --calendar-picker-day-size-default:               2rem;
+    /* Day cells — the interactive targets size from --a-size (control
+       height) and scale their digits with --a-ui-size, exactly like a
+       button/select row. */
+    --calendar-picker-day-size-default:               var(--a-size);
     --calendar-picker-day-radius-default:             var(--a-radius);
-    --calendar-picker-day-font-size-default:          var(--a-ui-sm);
+    --calendar-picker-day-font-size-default:          var(--a-ui-size);
     --calendar-picker-day-bg-default:                 transparent;
     --calendar-picker-day-fg-default:                 var(--a-fg-subtle);
     --calendar-picker-day-bg-hover-default:           var(--a-bg-hover);

package/components/card/card.a2ui.json

@@ -53,17 +53,14 @@
       "default": ""
     },
     "variant": {
-      "description": "Visual style. `outline` is an alias for `outlined`; `flat` removes shadow; `soft`/`primary` apply tinted surfaces.",
+      "description": "Visual style. `outlined` (alias `outline`) draws a border with no shadow; `filled` uses a tinted canvas surface; `ghost` drops border + shadow.",
       "type": "string",
       "enum": [
         "default",
         "outlined",
         "outline",
         "filled",
-        "ghost",
-        "flat",
-        "soft",
-        "primary"
+        "ghost"
       ],
       "default": "default"
     }

package/components/card/card.css

@@ -66,7 +66,9 @@
 
   /* ═══════ Variants — token-only overrides ═══════ */
 
-  :scope[variant="outlined"] {
+  /* `outline` is a documented alias for `outlined` (yaml). */
+  :scope[variant="outlined"],
+  :scope[variant="outline"] {
     --card-bg-default: transparent;
     --card-shadow-default: none;
     --card-border-default: 1px solid var(--a-border);

package/components/card/card.d.ts

@@ -23,6 +23,6 @@ export class UICard extends UIElement {
   raw: boolean;
   /** Card scale. Controls inset, radius, gap, and font sizes. Default (empty) = md. */
   size: 'sm' | 'md' | 'lg';
-  /** Visual style. `outline` is an alias for `outlined`; `flat` removes shadow; `soft`/`primary` apply tinted surfaces. */
-  variant: 'default' | 'outlined' | 'outline' | 'filled' | 'ghost' | 'flat' | 'soft' | 'primary';
+  /** Visual style. `outlined` (alias `outline`) draws a border with no shadow; `filled` uses a tinted canvas surface; `ghost` drops border + shadow. */
+  variant: 'default' | 'outlined' | 'outline' | 'filled' | 'ghost';
 }

package/components/card/card.yaml

@@ -44,8 +44,8 @@ props:
     - md
     - lg
   variant:
-    description: Visual style. `outline` is an alias for `outlined`; `flat` removes shadow; `soft`/`primary` apply tinted
-      surfaces.
+    description: Visual style. `outlined` (alias `outline`) draws a border with no
+      shadow; `filled` uses a tinted canvas surface; `ghost` drops border + shadow.
     type: string
     default: default
     enum:
@@ -54,9 +54,6 @@ props:
     - outline
     - filled
     - ghost
-    - flat
-    - soft
-    - primary
 events: {}
 slots:
   icon:

package/components/date-range-picker/date-range-picker.css

@@ -21,6 +21,9 @@
     --date-range-picker-popover-shadow-default:   var(--a-shadow-lg);
     --date-range-picker-popover-padding-default:  var(--a-space-3);
     --date-range-picker-popover-gap-default:      var(--a-space-3);
+    /* Wide enough for the preset rail + two side-by-side month panes; raises
+       anchor.js's default 32rem cap (which clipped the second month). */
+    --date-range-picker-popover-max-width-default: 48rem;
 
     /* Preset rail */
     --date-range-picker-preset-bg-default:        transparent;
@@ -132,6 +135,9 @@
    the popover-ui pattern that uses `:not(:popover-open) { display: none }`. */
 date-range-picker-ui [slot="popover"] {
   margin: 0;
+  /* Opt into a wider anchor.js max-width cap so both month panes fit side-by-side
+     (the 32rem default clipped the second month). Viewport safety still applies. */
+  --popover-max-width: var(--date-range-picker-popover-max-width, var(--date-range-picker-popover-max-width-default));
   padding: var(--date-range-picker-py, var(--date-range-picker-py-default)) var(--date-range-picker-px, var(--date-range-picker-px-default));
   border: 1px solid var(--date-range-picker-popover-border, var(--date-range-picker-popover-border-default));
   border-radius: var(--date-range-picker-popover-radius, var(--date-range-picker-popover-radius-default));
@@ -188,10 +194,13 @@ date-range-picker-ui [data-preset-rail] button-ui {
   justify-content: flex-start;
 }
 
-/* Calendar area — horizontal layout of two calendar panes. */
+/* Calendar area — horizontal layout of two calendar panes. Wraps the second
+   pane below the first when the popover is viewport-clamped narrower than two
+   months (instead of clipping it past the popover's right edge). */
 date-range-picker-ui [data-calendar-area] {
   grid-column: 2;
   display: flex;
+  flex-wrap: wrap;
   gap: var(--a-space-3);
   align-items: flex-start;
 }

package/components/heatmap/heatmap.a2ui.json

@@ -39,6 +39,8 @@
         "accent",
         "success",
         "warning",
+        "danger",
+        "info",
         "data-ramp"
       ],
       "default": "data-ramp"

package/components/heatmap/heatmap.d.ts

@@ -24,7 +24,7 @@ export class UIHeatmap extends UIElement {
   /** Aspect ratio */
   aspect: 'square' | 'wide';
   /** Color ramp */
-  colorScheme: 'accent' | 'success' | 'warning' | 'data-ramp';
+  colorScheme: 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'data-ramp';
   /** Column count */
   cols: number;
   /** Hide the Less/More legend strip */

package/components/heatmap/heatmap.yaml

@@ -33,6 +33,8 @@ props:
       - accent
       - success
       - warning
+      - danger
+      - info
       - data-ramp
     attribute: color-scheme
   cols:

package/components/index.js

@@ -87,6 +87,7 @@ export { UITableOfContents } from './toc/toc.js';
 export { UIQRCode } from './qr-code/qr-code.js';
 export { UIPagination } from './pagination/pagination.js';
 export { UICode } from './code/code.js';
+export { UIPreview } from './preview/preview.js';
 export { UIList, UIListItem } from './list/list.js';
 export { UIListWindow } from './list-window/list-window.js';
 export { UIMenu, UIMenuItem, UIMenuDivider } from './menu/menu.js';

package/components/preview/preview.a2ui.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Preview.json",
+  "title": "Preview",
+  "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.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "codeFirst": {
+      "description": "Show the code pane before (above / left of) the render pane. Default is render-first.",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "Preview"
+    },
+    "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"
+    },
+    "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",
+      "enum": [
+        "split",
+        "stack"
+      ],
+      "default": ""
+    },
+    "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
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "display",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "preview",
+      "example",
+      "demo",
+      "code-preview",
+      "live-preview",
+      "playground",
+      "codepen"
+    ],
+    "name": "UIPreview",
+    "related": [
+      "Code",
+      "Card"
+    ],
+    "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": [
+      {
+        "description": "Default, the only state.",
+        "name": "idle"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "preview": [
+        "example",
+        "demo",
+        "sandbox",
+        "live-preview"
+      ]
+    },
+    "tag": "preview-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/preview/preview.class.js

@@ -0,0 +1,178 @@
+/**
+ * Non-side-effect class export for `<preview-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the tag.
+ * The auto-register path is `@adia-ai/web-components/components/preview`.
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <preview-ui> — live code + render, single source of truth.
+ *
+ * Wrap any authored AdiaUI markup; the component keeps it LIVE in a render
+ * stage and shows the SAME markup as escaped, syntax-highlighted, copyable
+ * HTML beside it — so a demo's code and its rendered output can never drift
+ * (the code IS the render's source).
+ *
+ *   <preview-ui>
+ *     <button-ui text="Save" variant="primary"></button-ui>
+ *   </preview-ui>
+ *
+ * Batteries-included + HTML-first by construction: the author writes one
+ * block of HTML, no inline styles, no JS wiring — both panes appear.
+ *
+ * Attributes:
+ *   [layout="split"]  — render + code side-by-side (default: stacked)
+ *   [code-first]      — show the code pane above/before the render
+ *   [language="…"]    — code-ui language hint (default: html)
+ *
+ * Light-DOM (ADR-0033): the render pane holds real, live custom elements
+ * (re-parsed from the captured source on connect), so interactive demos
+ * actually work. `slot=` here is decorative; positioning is by CSS.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+/** Prepare captured markup for display: strip shared indentation + surrounding
+ *  blank lines, and collapse `attr=""` → `attr` (the DOM serializes boolean
+ *  attributes like `truncate` / `disabled` with an empty value — show the
+ *  cleaner boolean form a consumer would actually type). */
+function dedent(src) {
+  let lines = src
+    .replace(/=""(?=[\s/>])/g, '') // boolean attr: truncate="" → truncate
+    .replace(/\t/g, '  ')
+    .split('\n');
+  while (lines.length && lines[0].trim() === '') lines.shift();
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+  const indentOf = (l) => l.match(/^ */)[0].length;
+  // Measure the common indent from the BODY (everything after the first line),
+  // not from every line: markup captured via outerHTML/innerHTML puts the
+  // opening tag at column 0 while its children + closing tag carry the source
+  // file's nesting depth. Including that 0-indent first line would make min=0
+  // and leave the whole body deeply indented (the original bug). Clamp each
+  // slice to the line's own indent so the 0-indent opener is never truncated.
+  const body = lines.slice(1).filter((l) => l.trim());
+  const measured = (body.length ? body : lines.filter((l) => l.trim())).map(indentOf);
+  const min = measured.length ? Math.min(...measured) : 0;
+  return lines.map((l) => l.slice(Math.min(min, indentOf(l)))).join('\n');
+}
+
+export class UIPreview extends UIElement {
+  static properties = {
+    layout:    { type: String,  default: '',     reflect: true },
+    codeFirst: { type: Boolean, default: false,  reflect: true, attribute: 'code-first' },
+    language:  { type: String,  default: 'html', reflect: true },
+    rows:      { type: Boolean, default: false,  reflect: true },
+  };
+
+  static template = () => null;
+
+  #fitObserver = null;
+
+  /** A [render-cell | code-cell] pair from one source string. */
+  #pane(source, lang, codeFirst) {
+    const render = document.createElement('div');
+    render.setAttribute('data-preview-render', '');
+    render.innerHTML = source; // re-parse → fresh, live custom elements (keeps
+                               // any data-chunk corpus markers for harvest)
+    const codeWrap = document.createElement('div');
+    codeWrap.setAttribute('data-preview-code', '');
+    const code = document.createElement('code-ui');
+    code.setAttribute('language', lang);
+    // The CODE pane shows the clean consumer-facing HTML — strip doc-only
+    // corpus markers (data-chunk / -kind / -slot) that the render keeps.
+    code.textContent = source.replace(/\s+data-chunk(?:-[a-z]+)?="[^"]*"/g, '');
+    codeWrap.appendChild(code);
+    return codeFirst ? [codeWrap, render] : [render, codeWrap];
+  }
+
+  connected() {
+    // Idempotent — never re-stamp (peer mutation / re-connect safe).
+    if (this.querySelector(':scope > [data-preview-render], :scope > [data-preview-row]')) return;
+
+    // Side-by-side (render | code) is the default presentation. `rows` mode lays
+    // out its own per-example grid, and an explicit layout="…" (e.g. "stack")
+    // opts back into the stacked render-over-code form — so only default when
+    // neither is set. Setting the attribute (not the property default) keeps
+    // rows-mode previews free of a conflicting layout="split".
+    if (!this.hasAttribute('rows') && !this.hasAttribute('layout')) {
+      this.setAttribute('layout', 'split');
+    }
+
+    const lang = this.getAttribute('language') || 'html';
+    const codeFirst = this.hasAttribute('code-first');
+
+    // ── rows mode ── each direct child is one example; lay each out as its
+    // own [render | code] row so a multi-example gallery reads as paired
+    // side-by-side rows instead of all-renders-then-one-code-dump. The code
+    // shown is the child's OWN markup (zero drift). An optional
+    // [data-preview-label] surfaces a caption per row.
+    if (this.hasAttribute('rows')) {
+      const children = [...this.children];
+      const out = [];
+      for (const child of children) {
+        const label = child.getAttribute('data-preview-label');
+        if (label != null) child.removeAttribute('data-preview-label');
+        // A synthetic wrapper (multi-element row grouped by the host) marks
+        // itself [data-preview-unwrap] so we show its children's markup, not the
+        // throwaway wrapper tag — the copied code stays exactly what the author
+        // would paste.
+        const unwrap = child.hasAttribute('data-preview-unwrap');
+        if (unwrap) child.removeAttribute('data-preview-unwrap');
+        const source = dedent(unwrap ? child.innerHTML : child.outerHTML);
+        const row = document.createElement('div');
+        row.setAttribute('data-preview-row', '');
+        const panes = this.#pane(source, lang, codeFirst);
+        // The caption pill renders via [data-preview-render]::before, whose
+        // attr() can only read its OWN element — so the label goes on the
+        // render cell, not the row.
+        if (label) {
+          const renderEl = panes.find((el) => el.hasAttribute('data-preview-render'));
+          renderEl?.setAttribute('data-preview-label', label);
+        }
+        row.append(...panes);
+        out.push(row);
+      }
+      if (out.length) { this.replaceChildren(...out); this.#observeFit(); return; }
+    }
+
+    // ── single-block mode ── the whole slotted markup → one render + one code.
+    const source = dedent(this.innerHTML);
+    this.replaceChildren(...this.#pane(source, lang, codeFirst));
+    this.#observeFit();
+  }
+
+  // Side-by-side clips content wider than its half-width cell (a full dashboard
+  // composite, a wide control). After layout, if a render cell overflows, fall
+  // back to the stacked full-width form so the demo is never cut off. Monotonic
+  // (split → stack, never back; a row gains [data-stack] once), so it settles in
+  // one pass and never oscillates. Runs on a rAF + a ResizeObserver so it also
+  // adapts when the viewport narrows. Self-correcting — no per-component "wide"
+  // list to maintain.
+  #fit = () => {
+    if (this.hasAttribute('rows')) {
+      for (const row of this.querySelectorAll(':scope > [data-preview-row]')) {
+        const r = row.querySelector(':scope > [data-preview-render]');
+        if (r && r.scrollWidth > r.clientWidth + 4) row.setAttribute('data-stack', '');
+      }
+    } else if (this.getAttribute('layout') === 'split') {
+      const r = this.querySelector(':scope > [data-preview-render]');
+      if (r && r.scrollWidth > r.clientWidth + 4) this.setAttribute('layout', 'stack');
+    }
+  };
+
+  #scheduleFit = () => requestAnimationFrame(this.#fit);
+
+  #observeFit() {
+    this.#scheduleFit();
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#fitObserver = new ResizeObserver(this.#scheduleFit);
+      this.#fitObserver.observe(this);
+    }
+  }
+
+  disconnected() {
+    this.#fitObserver?.disconnect();
+  }
+}