@adia-ai/web-components 0.7.9 → 0.7.11

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.11] — 2026-06-04
+
+### Added
+
+- **`<frame-ui>` slot-override regions.** Beyond the native `<header>` / `<section>` / `<footer>` tags, any element can take a region role via `slot="header|body|footer"` (a CSS `[slot]` match — the same role-slot pattern as `<drawer-ui>`), so e.g. `<section slot="header">` is a pinned rail rather than the scroll body. The native tag stays the 90% sugar; reach for the slot when the element you want differs from the region role. Rail-slotted elements are `:not()`-excluded from the scroll-body selector, so a `[slot="header"]` section never doubles as the body. Files: `components/frame/{frame.css,frame.yaml,frame.html}`.
+
+### Changed
+
+- **`button-ui` hover now intensifies to the family `-strong` step.** Filled buttons strengthen their fill on hover — neutral → `--a-bg-strong`, `variant="primary"` → `--a-accent-strong`, and `color="danger|success|info|warning"` → the matching `--a-{family}-strong`. Outline + ghost keep a transparent fill and instead move the **fg** from its rest color to `-strong` (per-color outline/ghost shift to `--a-{family}-strong` text). This corrects a latent bug where `variant="primary"` and `color="danger"` hovered to the neutral `--a-ui-bg-hover` scrim (dropping their color), while `success` / `info` / `warning` and the neutral/default button had no hover-bg feedback at all. Note `-strong` resolves to the same step as `-active`/pressed, so the `:active` scale transform is what distinguishes press from hover. Override surfaces preserved: ghost hover still reads `--button-fg-ghost-hover` (alert.css retints it) and `--button-bg/border-ghost-hover` (the `component-tokens` demo opts a fill back in); the orphaned `--button-bg-hover-danger` token was removed. Warning's mid-tone `-strong` under dark `--a-warning-fg` may read muddy — flagged to revisit the warning ramp upstream. Files: `components/button/{button.css,button.examples.html}`.
+- **`resizable` trait — corner handles + symmetric-from-center resize.** The trait gained 4 corner hit-zones (drag a corner to resize BOTH axes at once) on top of the 4 edges; each handle carries its axis signs (`dw`/`dh`) + cursor, and corners are layered last so they win the hit-test where they overlap an edge. Adds symmetric resize-from-center. Powers `<embed-shell traits="resizable">` and any resizable surface. Files: `traits/resizable/{resizable.js,resizable.examples.html}`.
+- **CDN bundles rebuilt** — `dist/web-components.min.css` + `dist/web-components.min.js` regenerated so the `<frame-ui>` slot-override, the `button-ui` hover `-strong` step, the `resizable` corner handles, and the `list-item-ui` / `<preview-ui>` fixes reach `@adia-ai/web-components@0.7` CDN consumers.
+
+### Fixed
+
+- **`list-item-ui` title vertical-centers with icon + action.** `[slot="text"]` lacked `align-self: center`, so when the action (e.g. a full-height `<button-ui>`) made row 1 taller than the title, the title top-aligned *above* the centered icon + action. All three row-1 cells now center together. Surfaced by `onboarding-checklist-ui` "Open" rows. File: `components/list/list.css`.
+- **`<preview-ui>` code pane shows JSON attributes cleanly.** A JSON-bearing attribute (e.g. `items='[{"id":"a"}]'`) serializes via `outerHTML` as `items="[{&quot;id&quot;…}]"` — the `&quot;` rendered literally in the code/copy pane, and `<code-ui>`’s Copy emitted entity-encoded source. `dedent()` now re-renders quote-bearing attribute values with single-quote delimiters (`items='[{"id":"a"}]'`) — the clean, valid, copy-paste-able form the author wrote (apostrophe-bearing values keep the escaped form, no safe single-char delimiter). File: `components/preview/preview.class.js`.
+- **`[verse]` register radius comment corrected.** `styles/verse.css`'s `--a-radius-max: 0.75rem` carried a stale `/* 16px */` comment — `0.75rem` is 12px. Comment-only; no behavior change (the `0.75rem` max itself shipped in the 0.7.10 `[verse]` type bump). File: `styles/verse.css`.
+
+## [0.7.10] — 2026-06-03
+
+### Added
+
+- **New `<frame-ui>` layout primitive — sticky-header / scroll-body / sticky-footer frame.** The chrome-less app-shell skeleton: a flex column that fills its parent; native `<header>` / `<footer>` children pin (`flex: 0 0 auto`), `<section>` scrolls (`flex: 1; min-block-size: 0; overflow: auto`) — the only overflow region. Regions are positioned by tag + DOM order (Light DOM, no slot projection — ADR-0033). CSS-only `category: layout` component (no props). Common shape `<frame-ui><section>…</section><footer>…</footer></frame-ui>`; add `<header>` only for a panel title/toolbar. Distinct from `<card-ui>` (border + elevation + rich header grid), `<drawer-ui>` / `<modal-ui>` (backdrop + dismiss), and the page shells — those layer chrome over the same region contract (a future cut extracts the shared frame `@layer` they compose). Requires a definite-height parent. Files: `components/frame/{frame.yaml,frame.css,frame.class.js,frame.js,frame.html}`.
+
+### Changed
+
+- **`[verse]` register: bare-verse prose type bumped one tier (`sm` → `md`).** A bare `[verse]` context now resolves its prose type to the `md` tier instead of `sm` — `--a-display-size` / `--a-title-size` / `--a-heading-size` / `--a-section-size` re-point `sm`→`md` (display 18→23, title 16→19, heading 13→14, section 13→14px). `--a-radius-max` tightened `1rem`→`0.75rem` (12px). **Behavior change** — prose-ish text in a compact `[verse]` surface renders one tier larger; controls + the `[verse][size]` sub-tiers are unaffected. File: `styles/verse.css`.
+- **CDN bundles rebuilt** — `dist/web-components.min.css` + `dist/web-components.min.js` regenerated so `<frame-ui>` (CSS + registration), the `list-item-ui` grid fix, and the `[verse]` type bump reach `@adia-ai/web-components@0.7` CDN consumers.
+
+### Fixed
+
+- **`list-item-ui` description now spans the full content width.** `[slot="description"]` was pinned to `grid-column: 2`, so when a `[slot="action"]` was present (the 3-column `icon | content | action` grid) a multi-line description was boxed into the content column — it wrapped early and left dead space under the action. The grid is now a **header-row model**: `[slot="icon"]` · `[slot="text"]` · `[slot="action"]` align on row 1, and `[slot="description"]` spans `grid-column: 2 / -1` on row 2 (flowing under the action). The icon + action `grid-row` changed `1 / -1` → `1`, which is identical for single-row items (icon + text only) — so nav menus / simple lists are unchanged; only rows carrying a description are affected (e.g. `onboarding-checklist-ui` rows gain full-width descriptions + title-aligned action buttons). File: `components/list/list.css`.
+
 ## [0.7.9] — 2026-06-03
 
 ### Changed

package/components/button/button.css

@@ -4,26 +4,54 @@
    (0,1,1 / 0,2,1) is preserved. See docs/BROWSER-COMPAT.md §3a. */
 button-ui:active { transform: scale(0.97); }
 
-button-ui:not([disabled]):hover,
-button-ui[variant="primary"]:not([disabled]):hover {
-  --button-bg: var(--button-bg-hover);
+/* ── Hover (re-points the component tokens; lives outside @scope —
+   Safari 17.x ignores :scope:hover at the scope root, see note above) ──
+   Filled variants intensify the fill to the family `-strong` step (the
+   deeper, higher-contrast step — note it equals the `-active`/pressed
+   step, so the :active transform above is what distinguishes press from
+   hover). Outline + ghost keep a transparent fill and instead move the
+   FG from its rest color to the matching `-strong` color. */
+
+/* Neutral / default — fill → neutral `-strong` surface. Only --button-bg
+   moves: the rest fg (--a-fg-strong) and border (transparent) are already
+   the hover targets. The filled accent/semantic rules below re-point
+   --button-bg at higher specificity and leave each variant's rest fg
+   untouched (primary/danger/etc. keep their light label). */
+button-ui:not([disabled]):hover { --button-bg: var(--button-bg-hover); }
+
+button-ui[variant="primary"]:not([disabled]):hover { --button-bg: var(--a-accent-strong); }
+button-ui[color="danger"]:not([disabled]):hover     { --button-bg: var(--a-danger-strong); }
+button-ui[color="success"]:not([disabled]):hover    { --button-bg: var(--a-success-strong); }
+button-ui[color="info"]:not([disabled]):hover       { --button-bg: var(--a-info-strong); }
+/* warning fill → -strong like the rest; its mid-tone can read muddy under
+   the dark --a-warning-fg — revisit the warning ramp upstream if so. */
+button-ui[color="warning"]:not([disabled]):hover    { --button-bg: var(--a-warning-strong); }
+
+/* Outline / ghost — no fill on hover; fg goes rest-color → `-strong`.
+   Ghost reads --button-fg-ghost-hover (default --a-fg-strong) so consumers
+   like alert.css can retint the ghost-hover label, and --button-bg/border-
+   ghost-hover (default transparent) so the component-tokens demo can opt a
+   fill back in. */
+button-ui[variant="outline"]:not([disabled]):hover {
+  --button-bg: transparent;
   --button-fg: var(--button-fg-hover);
-  --button-border: var(--button-border-hover);
 }
 button-ui[variant="ghost"]:not([disabled]):hover {
   --button-bg: var(--button-bg-ghost-hover);
   --button-fg: var(--button-fg-ghost-hover);
   --button-border: var(--button-border-ghost-hover);
 }
-button-ui[variant="outline"]:not([disabled]):hover {
-  --button-fg: var(--button-fg-hover);
-  --button-border: var(--button-border-hover);
-}
-button-ui[color="danger"]:not([disabled]):hover {
-  --button-bg: var(--button-bg-hover);
-  --button-fg: var(--button-fg-hover);
-  --button-border: var(--button-border-hover);
-}
+
+/* Per-color outline/ghost — fg → family `-strong` (specificity 0,4,1
+   clears the 0,3,0 [variant][color] rest combos inside @scope). */
+button-ui[variant="outline"][color="danger"]:not([disabled]):hover,
+button-ui[variant="ghost"][color="danger"]:not([disabled]):hover    { --button-fg: var(--a-danger-strong); }
+button-ui[variant="outline"][color="success"]:not([disabled]):hover,
+button-ui[variant="ghost"][color="success"]:not([disabled]):hover   { --button-fg: var(--a-success-strong); }
+button-ui[variant="outline"][color="info"]:not([disabled]):hover,
+button-ui[variant="ghost"][color="info"]:not([disabled]):hover      { --button-fg: var(--a-info-strong); }
+button-ui[variant="outline"][color="warning"]:not([disabled]):hover,
+button-ui[variant="ghost"][color="warning"]:not([disabled]):hover   { --button-fg: var(--a-warning-strong); }
 
 @scope (button-ui) {
   :where(:scope) {
@@ -41,7 +69,7 @@ button-ui[color="danger"]:not([disabled]):hover {
     --button-font-weight:      var(--a-ui-weight);
     --button-font-family:      var(--a-font-family-ui);
     --button-gap:              var(--a-space-1);
-    --button-bg-hover:         var(--a-ui-bg-hover);
+    --button-bg-hover:         var(--a-bg-strong);   /* neutral fill → neutral -strong surface on hover */
     --button-fg-hover:         var(--a-ui-text-hover);
     --button-border-hover:     transparent;
     --button-bg-primary:       var(--a-primary);
@@ -52,12 +80,11 @@ button-ui[color="danger"]:not([disabled]):hover {
     --button-bg-ghost:         transparent;
     --button-fg-ghost:         var(--a-fg-subtle);
     --button-fg-ghost-hover:   var(--a-fg-strong);
-    --button-bg-ghost-hover:   var(--a-bg-hover);
+    --button-bg-ghost-hover:   transparent;   /* ghost hover is fg-only; consumers/demo may override to add a fill */
     --button-border-ghost:     transparent;
     --button-border-ghost-hover: transparent;
     --button-bg-danger:        var(--a-danger);
     --button-fg-danger:        var(--a-chrome-light);  /* white on the saturated fill — see color rules */
-    --button-bg-hover-danger:  var(--a-danger);
     --button-bg-disabled:      var(--a-ui-bg-disabled);
     --button-fg-disabled:      var(--a-ui-text-disabled);
     --button-border-disabled:  transparent;

package/components/frame/frame.a2ui.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Frame.json",
+  "title": "Frame",
+  "description": "Sticky-header / scrolling-body / sticky-footer layout frame — the\nchrome-less app-shell skeleton. A flex column that fills its parent's\nblock size: a native <header> child pins to the top, a <footer> child\npins to the bottom, and the <section> child scrolls between them (the\nonly region with overflow). Regions are positioned by tag + DOM order, OR any\nelement can take a region role via slot=\"header|body|footer\" (a CSS [slot] match,\nnot native projection — ADR-0033) — e.g. <section slot=\"header\"> as a pinned rail.\nAll three are OPTIONAL, so the common shape is just <section> + <footer>. Use for\ntab / panel content\nwhere actions stay visible while the body scrolls. Distinct from <card-ui>\n(adds border + elevation + a rich header grid), <drawer-ui> / <modal-ui>\n(add a backdrop + dismiss), and the page shells (<admin-page> / <page-ui>) —\nthose layer chrome over this same region contract. Requires a definite-height\nparent (a flex/grid chain rooted at a viewport height) for the section to\nscroll; in a content-sized parent it collapses to its content (no scroll,\nnot broken).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "Frame"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Scrolling body with a pinned footer action bar (no header).",
+        "a2ui": "[\n  { \"id\": \"root\", \"component\": \"Frame\", \"children\": [\"body\", \"actions\"] },\n  { \"id\": \"body\", \"component\": \"Section\", \"children\": [\"copy\"] },\n  { \"id\": \"copy\", \"component\": \"Text\", \"variant\": \"body\", \"textContent\": \"Scrollable panel content.\" },\n  { \"id\": \"actions\", \"component\": \"Footer\", \"children\": [\"save\"] },\n  { \"id\": \"save\", \"component\": \"Button\", \"text\": \"Save\", \"variant\": \"primary\" }\n]",
+        "name": "panel-with-footer"
+      }
+    ],
+    "keywords": [
+      "frame",
+      "panel",
+      "layout",
+      "scroll",
+      "sticky",
+      "footer",
+      "header",
+      "shell",
+      "app",
+      "sheet"
+    ],
+    "name": "UIFrame",
+    "related": [
+      "Card",
+      "Drawer",
+      "Modal",
+      "Col"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "panel": [
+        "panel",
+        "frame",
+        "sheet"
+      ],
+      "scroll": [
+        "scroll",
+        "frame",
+        "body"
+      ],
+      "shell": [
+        "shell",
+        "frame",
+        "app"
+      ]
+    },
+    "tag": "frame-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/frame/frame.class.js

@@ -0,0 +1,31 @@
+/**
+ * Non-side-effect class export for `<frame-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the tag.
+ * The auto-register path is `@adia-ai/web-components/components/frame`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { UIElement } from '../../core/element.js';
+
+/**
+ * <frame-ui> — sticky-header / scroll-body / sticky-footer layout frame.
+ *
+ *   <frame-ui>
+ *     <header>…</header>   <!-- optional: pinned top -->
+ *     <section>…</section> <!-- scrolling body (the only overflow region) -->
+ *     <footer>…</footer>   <!-- optional: pinned bottom (actions) -->
+ *   </frame-ui>
+ *
+ * Pure-CSS layout container — no props, no template. Regions are native
+ * <header>/<section>/<footer> children positioned by tag + DOM order (Light
+ * DOM, no slot projection). The class exists only to register the tag; all
+ * behaviour is in frame.css. See <card-ui>/<drawer-ui>/<modal-ui> for the
+ * chrome'd variants that compose the same region contract.
+ */
+export class UIFrame extends UIElement {
+  static properties = {};
+  static template = () => null;
+}

package/components/frame/frame.css

@@ -0,0 +1,42 @@
+/**
+ * <frame-ui> — sticky-header / scroll-body / sticky-footer layout frame.
+ *
+ * The chrome-less app-shell skeleton: a flex column that fills its parent's
+ * block size. A native <header> child pins to the top, a <footer> child pins
+ * to the bottom, and the <section> child scrolls between them (the only region
+ * with overflow). All three regions are OPTIONAL and positioned by tag + DOM
+ * order — Light DOM, no slot projection (ADR-0033). <card-ui> / <drawer-ui> /
+ * <modal-ui> layer chrome (border / elevation / backdrop) over this same
+ * region contract.
+ *
+ * Height: frame-ui fills its parent, so the parent must establish a definite
+ * block size (a flex/grid chain rooted at a viewport height, or an explicit
+ * height). In a content-sized parent it collapses to its content and the
+ * <section> simply doesn't scroll (graceful, not broken).
+ */
+@scope (frame-ui) {
+  :where(:scope) {
+    display: flex;
+    flex-direction: column;
+    block-size: 100%;
+    min-block-size: 0;
+  }
+
+  /* Pinned rails — native <header>/<footer>, OR any element that opts into the role
+     via slot="header"/"footer" (the drawer-ui pattern), so e.g. a <section slot="header">
+     becomes a pinned rail rather than the scroll body. Fixed height, never scroll. */
+  :scope > :is(header, footer, [slot="header"], [slot="footer"]) {
+    flex: 0 0 auto;
+    min-block-size: 0;
+  }
+
+  /* The single scroll region — native <section> OR slot="body", minus anything that
+     opted into a rail role above. `min-block-size: 0` lets the flex item shrink below
+     its content's intrinsic size — the flex-scroll gotcha that makes overflow:auto
+     actually scroll inside a column. */
+  :scope > :is(section, [slot="body"]):not([slot="header"]):not([slot="footer"]) {
+    flex: 1 1 auto;
+    min-block-size: 0;
+    overflow: auto;
+  }
+}

package/components/frame/frame.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `<frame-ui>` — Sticky-header / scrolling-body / sticky-footer layout frame — the
+chrome-less app-shell skeleton. A flex column that fills its parent's
+block size: a native <header> child pins to the top, a <footer> child
+pins to the bottom, and the <section> child scrolls between them (the
+only region with overflow). Regions are positioned by tag + DOM order, OR any
+element can take a region role via slot="header|body|footer" (a CSS [slot] match,
+not native projection — ADR-0033) — e.g. <section slot="header"> as a pinned rail.
+All three are OPTIONAL, so the common shape is just <section> + <footer>. Use for
+tab / panel content
+where actions stay visible while the body scrolls. Distinct from <card-ui>
+(adds border + elevation + a rich header grid), <drawer-ui> / <modal-ui>
+(add a backdrop + dismiss), and the page shells (<admin-page> / <page-ui>) —
+those layer chrome over this same region contract. Requires a definite-height
+parent (a flex/grid chain rooted at a viewport height) for the section to
+scroll; in a content-sized parent it collapses to its content (no scroll,
+not broken).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/frame
+ *
+ * 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 UIFrame extends UIElement {
+}

package/components/frame/frame.js

@@ -0,0 +1,17 @@
+/**
+ * `<frame-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIFrame } from '@adia-ai/web-components/components/frame/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIFrame } from './frame.class.js';
+
+defineIfFree('frame-ui', UIFrame);
+
+export { UIFrame };

package/components/frame/frame.yaml

@@ -0,0 +1,86 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIFrame
+tag: frame-ui
+status: stable
+component: Frame
+category: layout
+version: 1
+description: |
+  Sticky-header / scrolling-body / sticky-footer layout frame — the
+  chrome-less app-shell skeleton. A flex column that fills its parent's
+  block size: a native <header> child pins to the top, a <footer> child
+  pins to the bottom, and the <section> child scrolls between them (the
+  only region with overflow). Regions are positioned by tag + DOM order, OR any
+  element can take a region role via slot="header|body|footer" (a CSS [slot] match,
+  not native projection — ADR-0033) — e.g. <section slot="header"> as a pinned rail.
+  All three are OPTIONAL, so the common shape is just <section> + <footer>. Use for
+  tab / panel content
+  where actions stay visible while the body scrolls. Distinct from <card-ui>
+  (adds border + elevation + a rich header grid), <drawer-ui> / <modal-ui>
+  (add a backdrop + dismiss), and the page shells (<admin-page> / <page-ui>) —
+  those layer chrome over this same region contract. Requires a definite-height
+  parent (a flex/grid chain rooted at a viewport height) for the section to
+  scroll; in a content-sized parent it collapses to its content (no scroll,
+  not broken).
+props: {}
+events: {}
+slots: {}
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens: {}
+a2ui:
+  rules:
+    - rule: 'Use <frame-ui> for a scroll-body-with-pinned-footer panel — the <section> scrolls; <header> / <footer> stay fixed.'
+      reason: 'The chrome-less app-shell frame.'
+    - rule: 'Regions are positioned by tag + DOM order (native <header> / <section> / <footer>) OR by a role slot: slot="header"/"footer" pins ANY element as a rail, slot="body" makes it the scroll region (e.g. <section slot="header"> is a pinned rail). The native tag is the 90% sugar; reach for the slot when the element you want differs from the region role.'
+      reason: 'CSS matches [slot=…] in Light DOM (ADR-0033, no native projection) — the same role-slot pattern as drawer-ui.'
+    - rule: 'Most panels need only <section> + <footer>; add <header> only when the panel has its own title or toolbar.'
+      reason: 'Header is optional.'
+    - rule: 'For a bordered/elevated surface use <card-ui>; for an overlay use <drawer-ui> / <modal-ui>; for routed page layout use <admin-page> / <page-ui>. frame-ui is the bare layout only.'
+      reason: 'Decision rule vs chrome siblings.'
+    - rule: 'frame-ui fills its parent — give the parent a definite height (a flex/grid chain to a viewport height) or the section will not scroll.'
+      reason: 'Scroll requires a bounded height.'
+anti_patterns: []
+examples:
+  - name: panel-with-footer
+    description: Scrolling body with a pinned footer action bar (no header).
+    a2ui: >-
+      [
+        { "id": "root", "component": "Frame", "children": ["body", "actions"] },
+        { "id": "body", "component": "Section", "children": ["copy"] },
+        { "id": "copy", "component": "Text", "variant": "body", "textContent": "Scrollable panel content." },
+        { "id": "actions", "component": "Footer", "children": ["save"] },
+        { "id": "save", "component": "Button", "text": "Save", "variant": "primary" }
+      ]
+keywords:
+  - frame
+  - panel
+  - layout
+  - scroll
+  - sticky
+  - footer
+  - header
+  - shell
+  - app
+  - sheet
+synonyms:
+  panel:
+    - panel
+    - frame
+    - sheet
+  scroll:
+    - scroll
+    - frame
+    - body
+  shell:
+    - shell
+    - frame
+    - app
+related:
+  - Card
+  - Drawer
+  - Modal
+  - Col

package/components/index.js

@@ -74,6 +74,7 @@ export { UIFields } from './fields/fields.js';
 export { UIRow }   from './row/row.js';
 export { UIGrid }  from './grid/grid.js';
 export { UIStack } from './stack/stack.js';
+export { UIFrame } from './frame/frame.js';
 export { UIChart } from './chart/chart.js';
 export { UIChartLegend } from './chart-legend/chart-legend.js';
 export { UIPopover } from './popover/popover.js';

package/components/list/list.css

@@ -106,10 +106,12 @@
     --list-item-desc-font-size: var(--a-ui-sm);
   }
 
-  /* Anatomy:
-     col 1 = icon (auto width; collapses to 0 when no icon)
-     col 2 = content stack (text on row 1, description on row 2)
-     The icon spans both rows + centers vertically with the stack.
+  /* Anatomy (header-row model):
+     row 1 = icon (col 1) · text/title (col 2) · action (col 3), all aligned
+     on the title row. row 2 = description, spanning col 2 / -1 (under the
+     action) so multi-line supporting text uses the full content width rather
+     than being boxed into col 2 beside the action. For icon+text-only items
+     there is a single row, so `grid-row: 1` is identical to the old `1 / -1`.
      `[slot="content"]` (used when consumer provides custom rendering)
      spans all columns. */
   :scope {
@@ -136,7 +138,7 @@
      authored children + template-engine-wrapped conditionals). */
   :scope [slot="icon"] {
     grid-column: 1;
-    grid-row: 1 / -1;
+    grid-row: 1;
     align-self: center;
     color: var(--list-item-icon-color);
   }
@@ -144,10 +146,14 @@
   :scope [slot="text"] {
     grid-column: 2;
     grid-row: 1;
+    /* Center the title within row 1 so it aligns with the (also-centered) icon +
+       action. Without this, a full-height action button (e.g. onboarding's "Open")
+       makes row 1 taller than the title and the title top-aligns above the controls. */
+    align-self: center;
   }
 
   :scope [slot="description"] {
-    grid-column: 2;
+    grid-column: 2 / -1;
     grid-row: 2;
     color: var(--list-item-desc-color);
     font-size: var(--list-item-desc-font-size);
@@ -157,7 +163,8 @@
   /* When a [slot="action"] child is present, the grid becomes 3-column:
      icon | content | action. The :has() selector promotes the template
      only when an action exists, so 2-column layouts stay unaffected.
-     Action is right-aligned + vertically centered (spans both content rows).
+     Action is right-aligned on the title row (row 1) so a multi-line
+     description below can span the full width (col 2 / -1) beneath it.
      Used by onboarding-checklist-ui item rows + any consumer that needs an
      end-aligned action button on a list-item row.
      NOTE: NOT using `> [slot="action"]` (direct-child) — the template
@@ -171,7 +178,7 @@
   }
   :scope [slot="action"] {
     grid-column: 3;
-    grid-row: 1 / -1;
+    grid-row: 1;
     align-self: center;
     justify-self: end;
   }

package/components/preview/preview.class.js

@@ -41,6 +41,15 @@ import { UIElement } from '../../core/element.js';
 function dedent(src) {
   let lines = src
     .replace(/=""(?=[\s/>])/g, '') // boolean attr: truncate="" → truncate
+    // JSON / quote-bearing attribute values serialize as attr="…"…"…" —
+    // outerHTML escapes the inner " under the default double-quote delimiter. Re-render
+    // them single-quote-delimited (attr='…"…"…') — the clean, valid, copy-paste-able
+    // form the author actually wrote (e.g. items='[{"id":"a"}]'). Skipped when the value
+    // also contains a ' (no safe single-char delimiter — keep the escaped form).
+    .replace(/="([^"]*"[^"]*)"/g, (m, v) => {
+      const decoded = v.replace(/"/g, '"').replace(/&/g, '&');
+      return decoded.includes("'") ? m : `='${decoded}'`;
+    })
     .replace(/\t/g, '  ')
     .split('\n');
   while (lines.length && lines[0].trim() === '') lines.shift();