@adia-ai/web-components 0.6.50 → 0.7.1

package/components/menu/menu.test.js

@@ -0,0 +1,130 @@
+/**
+ * <menu-ui> behavioral tests.
+ *
+ * FEEDBACK-92 (2026-05-31): `#show()` collected items with a direct-child
+ * `:scope >` query, so items rendered through the template engine's
+ * `.map()` / `repeat()` (each wrapped in a `display:contents` <span>) were
+ * skipped → the popover opened empty. The fix uses a descendant query
+ * (mirroring `#hide()`). These tests pin the dynamic + static paths.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { html, stamp, repeat } from '../../core/template.js';
+
+beforeAll(async () => {
+  await import('../../core/element.js');
+  await import('./menu.js');
+  await import('../button/button.js');
+});
+
+const settle = () => new Promise((r) => setTimeout(r, 30));
+
+describe('<menu-ui> collects dynamically-rendered items (FEEDBACK-92)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+  afterEach(() => host.remove());
+
+  function popItems(menu) {
+    const pop = menu.querySelector('[data-menu-popover]');
+    return pop ? pop.querySelectorAll('menu-item-ui') : [];
+  }
+
+  it('populates the popover from `.map()`-rendered items (the bug)', async () => {
+    const ITEMS = [{ id: 'a', text: 'Alpha' }, { id: 'b', text: 'Beta' }];
+    // Render the menu (closed) the documented way — items via `.map()`. The
+    // consumer opens it later via interaction, after the template has rendered.
+    stamp(html`
+      <menu-ui>
+        <button-ui slot="trigger" text="Open"></button-ui>
+        ${ITEMS.map((i) => html`<menu-item-ui .text=${i.text} .value=${i.id}></menu-item-ui>`)}
+      </menu-ui>
+    `, host);
+    await settle();
+
+    const menu = host.querySelector('menu-ui');
+    // The exact bug condition: items exist under the host but are NOT direct
+    // children — the template engine nested them inside display:contents spans,
+    // which the old `:scope >` query in #show() could not see.
+    expect(menu.querySelectorAll('menu-item-ui').length).toBe(2);
+    expect(menu.querySelector(':scope > menu-item-ui')).toBeNull();
+
+    menu.open = true; // user opens the menu post-render
+    await settle();
+
+    const items = popItems(menu);
+    expect(items.length).toBe(2);
+    expect([...items].map((el) => el.value)).toEqual(['a', 'b']);
+  });
+
+  it('populates the popover from `repeat()`-rendered items', async () => {
+    const ITEMS = [{ id: 'x', text: 'Ex' }, { id: 'y', text: 'Why' }, { id: 'z', text: 'Zee' }];
+    stamp(html`
+      <menu-ui>
+        <button-ui slot="trigger" text="Open"></button-ui>
+        ${repeat(ITEMS, (i) => i.id, (i) => html`<menu-item-ui .text=${i.text} .value=${i.id}></menu-item-ui>`)}
+      </menu-ui>
+    `, host);
+    await settle();
+
+    const menu = host.querySelector('menu-ui');
+    expect(menu.querySelector(':scope > menu-item-ui')).toBeNull(); // behind wrappers
+    menu.open = true;
+    await settle();
+    expect(popItems(menu).length).toBe(3);
+  });
+
+  it('still populates from static literal children (no regression)', async () => {
+    const menu = document.createElement('menu-ui');
+    menu.innerHTML = `
+      <button-ui slot="trigger" text="Open"></button-ui>
+      <menu-item-ui text="Edit" value="edit"></menu-item-ui>
+      <menu-divider-ui></menu-divider-ui>
+      <menu-item-ui text="Delete" value="delete"></menu-item-ui>`;
+    host.appendChild(menu);
+    await settle();
+    menu.open = true;
+    await settle();
+
+    expect(popItems(menu).length).toBe(2);
+    const pop = menu.querySelector('[data-menu-popover]');
+    expect(pop.querySelectorAll('menu-divider-ui').length).toBe(1);
+  });
+
+  it('does not absorb the trigger into the popover', async () => {
+    const menu = document.createElement('menu-ui');
+    menu.innerHTML = `
+      <button-ui slot="trigger" text="Open"></button-ui>
+      <menu-item-ui text="Edit" value="edit"></menu-item-ui>`;
+    host.appendChild(menu);
+    await settle();
+    menu.open = true;
+    await settle();
+
+    const pop = menu.querySelector('[data-menu-popover]');
+    expect(pop.querySelector('[slot="trigger"]')).toBeNull();
+    expect(menu.querySelector(':scope > [slot="trigger"]')).not.toBeNull();
+  });
+
+  it('does not reorder items on a re-entrant #show() (open → re-render → still open)', async () => {
+    const menu = document.createElement('menu-ui');
+    menu.innerHTML = `
+      <button-ui slot="trigger" text="Open"></button-ui>
+      <menu-item-ui text="One" value="1"></menu-item-ui>
+      <menu-item-ui text="Two" value="2"></menu-item-ui>`;
+    host.appendChild(menu);
+    await settle();
+    menu.open = true;
+    await settle();
+    // Force another render() pass while still open (re-invokes #show()).
+    menu.placement = 'top-start';
+    await settle();
+
+    const pop = menu.querySelector('[data-menu-popover]');
+    const order = [...pop.querySelectorAll('menu-item-ui')].map((el) => el.value);
+    expect(order).toEqual(['1', '2']);
+  });
+});

package/components/modal/modal.class.js

@@ -122,7 +122,16 @@ export class UIModal extends UIElement {
   }
 
   #getDuration() {
-    const raw = getComputedStyle(this).getPropertyValue('--modal-duration').trim();
+    // Read the same fallback chain the CSS transitions use —
+    // var(--modal-duration, var(--modal-duration-default)). Reading only the
+    // public token (unset unless a consumer overrides) made this always fall
+    // back to 200ms while the CSS exit animation ran for --modal-duration-default
+    // (= --a-duration = 250ms), so the dialog closed 50ms early, clipping the
+    // animation. Same class as swiper bug-29 (the OD-5 -default token sweep left
+    // JS read-sites pointed at the now-unset public token).
+    const cs = getComputedStyle(this);
+    const raw = cs.getPropertyValue('--modal-duration').trim()
+             || cs.getPropertyValue('--modal-duration-default').trim();
     return parseFloat(raw) || 200;
   }
 

package/components/modal/modal.css

@@ -142,6 +142,12 @@
     flex: 1;
     overflow: auto;
   }
+  /* Form controls in the modal body fill the available width (a modal body is
+     a form column, not a content-width row) — matches the field/input family's
+     full-width behaviour in a real form. */
+  :scope [slot="body"] :is(field-ui, input-ui, select-ui, textarea-ui, combobox-ui, tags-input-ui, color-input-ui, slider-ui) {
+    width: 100%;
+  }
 
   /* ═══════ Footer ═══════ */
   :scope [slot="footer"] {
@@ -153,4 +159,7 @@
     border-top: 1px solid var(--modal-border, var(--modal-border-default));
     flex-shrink: 0;
   }
+  /* No content → no footer chrome: an empty footer slot otherwise renders a
+     dead band (border-top + padding) under the body. */
+  :scope [slot="footer"]:empty { display: none; }
 }

package/components/option-card/option-card.a2ui.json

@@ -114,6 +114,9 @@
       "default": {
         "description": "Spillover content revealed only when the card is checked — typically a follow-up form field (e.g. a textarea on an \"Other\" option, conditional inputs that depend on the selection). Aligns with the heading/description column; hidden via `display: none` when not checked."
       },
+      "action": {
+        "description": "CTA slot for `layout=\"tile\"` — a button-ui anchored to the card's bottom edge and stretched full-width, so a row of tile cards keeps their CTAs aligned regardless of body length (plan-picker-style pickers)."
+      },
       "heading": {
         "description": "Rich heading content. Overrides the `heading` attribute when present."
       },

package/components/option-card/option-card.css

@@ -173,34 +173,59 @@ option-card-ui[checked] [slot="icon"] {
        description below, all left-aligned. Used for hero pickers
        (data source, role, plan tiles) where the icon is a primary
        brand cue rather than secondary chrome. ── */
+  /* Tile layout — a vertical content stack (icon → heading → description →
+     body → action) with the radio indicator pinned top-right OUT of flow.
+     Flex (not grid) so content flows in DOM order with no reserved/empty
+     tracks: a no-icon plan card has no dead left column, and a slotted CTA
+     (slot="action") anchors to the card bottom regardless of how much body
+     content (price / feature list) precedes it. (Plan Picker option-card grid) */
   :scope[layout="tile"] {
-    grid-template-columns: minmax(0, 1fr) auto;
-    grid-template-areas:
-      "icon       indicator"
-      "heading    heading"
-      "description description";
-    column-gap: var(--option-card-gap-x, var(--option-card-gap-x-default));
-    row-gap: var(--option-card-gap-y, var(--option-card-gap-y-default));
-    padding: var(--a-space-4);
-    align-items: start;
+    display: flex;
+    flex-direction: column;
+    gap: var(--option-card-gap-y, var(--option-card-gap-y-default));
+    position: relative;
+    /* padding inherited from base :scope (token-driven, --option-card-padding-*) */
+  }
+  /* Radio pinned to the card's top-right corner, OUT of flow. Clear the
+     base grid-area:indicator so the absolute containing block is the card
+     itself (position:relative) rather than a collapsed grid cell — otherwise
+     a grid-forcing host (plan-picker-ui) strands the indicator in an 8px
+     gutter and inset-inline-end resolves negative. Inset by the active
+     padding token so the dot aligns with the content edge. */
+  :scope[layout="tile"]::before {
+    position: absolute;
+    grid-area: auto;
+    inset-block-start: var(--option-card-padding-block, var(--option-card-padding-block-default));
+    inset-inline-end: var(--option-card-padding-inline, var(--option-card-padding-inline-default));
+    margin-block-start: 0;
   }
+  /* Visual order is fixed via `order`, NOT DOM order: composites
+     (plan-picker-ui) append default-slot body content BEFORE option-card
+     stamps the heading/description spans on connect, so a flex stack that
+     trusted DOM order would render the body above the title. */
   :scope[layout="tile"] [slot="icon"] {
-    grid-area: icon;
-    justify-self: start;
+    order: 1;
     align-self: start;
     --option-card-icon-size-default: 1.75rem;
   }
-  :scope[layout="tile"]::before {
-    grid-area: indicator;
-    align-self: start;
-    justify-self: end;
-    margin-block-start: 0;
-  }
   :scope[layout="tile"] [slot="heading"] {
-    margin-block-start: var(--a-space-2);
+    order: 2;
+    /* Reserve the top-right radio's footprint so a long heading doesn't run
+       under it. */
+    padding-inline-end: var(--a-space-6);
+  }
+  :scope[layout="tile"] [slot="description"] {
+    order: 3;
   }
   :scope[layout="tile"] > :not([slot]) {
-    grid-column: 1 / -1;
+    order: 4;
+  }
+  /* CTA anchors to the card bottom (auto top-margin) + full-width, so a row of
+     plan cards with different body lengths keeps their buttons aligned. */
+  :scope[layout="tile"] [slot="action"] {
+    order: 5;
+    width: 100%;
+    margin-block-start: auto;
   }
 
   /* ── State: disabled ── */

package/components/option-card/option-card.yaml

@@ -76,6 +76,11 @@ slots:
     description: Rich description content. Overrides the `description` attribute when present.
   icon:
     description: Custom icon element. Overrides the `icon` attribute when present.
+  action:
+    description: >-
+      CTA slot for `layout="tile"` — a button-ui anchored to the card's bottom
+      edge and stretched full-width, so a row of tile cards keeps their CTAs
+      aligned regardless of body length (plan-picker-style pickers).
   default:
     description: >-
       Spillover content revealed only when the card is checked — typically a

package/components/otp-input/otp-input.css

@@ -1,9 +1,13 @@
 @scope (otp-input-ui) {
   :where(:scope) {
     /* ── Tokens ── */
-    --otp-input-size-default:         var(--a-size);
+    /* Digit boxes grow to fill the row, capped at ~1.75× the base control size
+       (~52px) so they read as comfortable single-digit boxes. Radius is the
+       plain --a-radius-lg token (no min()/clamp expression — radius patterns
+       stay simple). Scales with [size] + density (relative to --a-size). */
+    --otp-input-size-default:         calc(var(--a-size) * 1.75);
     --otp-input-gap-default:          var(--a-space-2);
-    --otp-input-radius-default:       var(--a-radius-md);
+    --otp-input-radius-default:       var(--a-radius-lg);
     --otp-input-border-default:       var(--a-ui-border);
     --otp-input-border-hover-default: var(--a-ui-border-hover);
     --otp-input-border-focus-default: var(--a-accent);
@@ -24,15 +28,27 @@
     /* ── Base ── */
     box-sizing: border-box;
     display: flex;
-    justify-content: space-around;
+    justify-content: center;
     gap: var(--otp-input-gap, var(--otp-input-gap-default));
+    /* Fill the container (a block-level control per ADR-0037) so the digit
+       boxes grow to use the available width instead of sitting content-width
+       on the left. Boxes flex to fill up to their cap; once capped (very wide
+       container) the group centers rather than packing left. (bug-37 follow-up) */
+    width: 100%;
   }
 
   /* ── Digit inputs ── */
+  /* Boxes grow equally to fill the row (flex), staying square (aspect-ratio)
+     and capped at --otp-input-size so they read as digit boxes — not huge on a
+     wide container, not cramped on a narrow one. The cap keeps --a-radius-md
+     proportional (a rounded square, ~25-30%), which is the whole point of the
+     bug-37 sizing. */
   [slot="digit"] {
     box-sizing: border-box;
-    width: var(--otp-input-size, var(--otp-input-size-default));
-    height: var(--otp-input-size, var(--otp-input-size-default));
+    flex: 1 1 0;
+    min-width: 0;
+    max-width: var(--otp-input-size, var(--otp-input-size-default));
+    aspect-ratio: 1;
     text-align: center;
     border: 1px solid var(--otp-input-border, var(--otp-input-border-default));
     border-radius: var(--otp-input-radius, var(--otp-input-radius-default));
@@ -67,12 +83,11 @@
   :scope[disabled] [slot="digit"] {
     background: var(--otp-input-bg-disabled, var(--otp-input-bg-disabled-default));
     color: var(--otp-input-fg-disabled, var(--otp-input-fg-disabled-default));
-    /* Dashed border rendered via SVG border-image for consistent ~8px
-       dashes across browsers (native `border-style: dashed` is too short
-       and varies by engine). The border-color fallback is used when
-       border-image isn't supported. */
+    /* Native dashed border — it follows the box's border-radius (a rounded
+       dashed square, matching the enabled state). An SVG border-image would
+       give more uniform dashes but is clipped to a SQUARE — it ignores
+       border-radius — so the disabled corners wouldn't round. */
     border: 1px dashed var(--otp-input-border-disabled, var(--otp-input-border-disabled-default));
-    border-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='28' height='28' preserveAspectRatio='none'><rect x='0.5' y='0.5' width='27' height='27' fill='none' stroke='%23999' stroke-width='1' stroke-dasharray='8 6'/></svg>") 1 repeat;
     cursor: not-allowed;
   }
 }

package/components/page/page.css

@@ -9,6 +9,15 @@
     /* ── Padding default (when [padding] is set without a value) ── */
     --page-padding-default:  var(--a-space-6);
 
+    /* ── Region rhythm — vertical gap between header / section / footer,
+       mirroring card-ui's section inset. The page [padding] supplies the
+       outer frame; this is the inter-region spacing. ── */
+    --page-inset-default:    var(--a-space-5);
+
+    /* ── Padded-region sub-surface (a section[padding] inside the page) ── */
+    --page-region-bg-default:     var(--a-bg-subtle);
+    --page-region-radius-default: var(--a-radius-md);
+
     /* ── Surfaces ── */
     --page-bg-default:               var(--a-canvas-0);
     --page-fg-default:               var(--a-fg);
@@ -23,6 +32,9 @@
     box-sizing: border-box;
     display: block;
     width: 100%;
+    /* --page-pad carries the resolved [padding] value so the sticky header can
+       bleed back over it (card-ui pattern) — see the sticky-header rule. */
+    padding: var(--page-pad, 0);
     background: var(--page-bg, var(--page-bg-default));
     color: var(--page-fg, var(--page-fg-default));
   }
@@ -33,17 +45,47 @@
   :scope[max-width="wide"]   { max-width: var(--page-max-width-wide, var(--page-max-width-wide-default));   margin-inline: auto; }
   :scope[max-width="full"]   { max-width: var(--page-max-width-full, var(--page-max-width-full-default)); }
 
-  /* ── Padding scale (mirrors --a-space-N) ── */
-  :scope[padding=""]  { padding: var(--page-padding-default); }
-  :scope[padding="0"] { padding: 0; }
-  :scope[padding="1"] { padding: var(--a-space-1); }
-  :scope[padding="2"] { padding: var(--a-space-2); }
-  :scope[padding="3"] { padding: var(--a-space-3); }
-  :scope[padding="4"] { padding: var(--a-space-4); }
-  :scope[padding="5"] { padding: var(--a-space-5); }
-  :scope[padding="6"] { padding: var(--a-space-6); }
-  :scope[padding="7"] { padding: var(--a-space-7); }
-  :scope[padding="8"] { padding: var(--a-space-8); }
+  /* ── Padding scale (mirrors --a-space-N) — sets --page-pad, applied above ── */
+  :scope[padding=""]  { --page-pad: var(--page-padding-default); }
+  :scope[padding="0"] { --page-pad: 0; }
+  :scope[padding="1"] { --page-pad: var(--a-space-1); }
+  :scope[padding="2"] { --page-pad: var(--a-space-2); }
+  :scope[padding="3"] { --page-pad: var(--a-space-3); }
+  :scope[padding="4"] { --page-pad: var(--a-space-4); }
+  :scope[padding="5"] { --page-pad: var(--a-space-5); }
+  :scope[padding="6"] { --page-pad: var(--a-space-6); }
+  :scope[padding="7"] { --page-pad: var(--a-space-7); }
+  :scope[padding="8"] { --page-pad: var(--a-space-8); }
+
+  /* ═══════ Region model — header / section / footer ═══════
+     Mirrors card-ui's section model, adapted to the page's [padding] frame:
+     the page [padding] is the OUTER inset; these rules add the vertical
+     rhythm BETWEEN regions plus the [bleed] / [padding] modifiers. The
+     page's own @scope styling the slot primitives is what the docs promise
+     ([<header>] / [<section>] / [<footer>] and their -ui variants). */
+
+  /* Vertical rhythm: every region after the first picks up a top margin so
+     header → body → footer breathe consistently (the first region hugs the
+     padding edge). */
+  :scope > :where(header, header-ui, section, section-ui, footer, footer-ui)
+    ~ :where(header, header-ui, section, section-ui, footer, footer-ui) {
+    margin-block-start: var(--page-inset, var(--page-inset-default));
+  }
+
+  /* [bleed] — edge-to-edge region: cancel the page's inline [padding] so
+     full-width content (hero, banner, table, chart) reaches the page edges.
+     Resolves to 0 (no-op) when the page has no padding. */
+  :scope > :where(header, header-ui, section, section-ui, footer, footer-ui)[bleed] {
+    margin-inline: calc(-1 * var(--page-pad, 0));
+  }
+
+  /* [padding] on a region — a padded sub-surface with its own background +
+     radius, like card-ui's section[padding]. */
+  :scope > :where(section, section-ui)[padding] {
+    padding: var(--page-inset, var(--page-inset-default));
+    background: var(--page-region-bg, var(--page-region-bg-default));
+    border-radius: var(--page-region-radius, var(--page-region-radius-default));
+  }
 
   /* ── Scroll container ── */
   :scope[scroll] {
@@ -53,11 +95,22 @@
   }
 
   /* ── Sticky-header support ── */
+  /* Drop the page's TOP padding when the header is sticky — that gap is where
+     scrolling content used to peek ABOVE the pinned header. The header then
+     sits flush at the scroll-container top and supplies its own top spacing
+     (padding-block below). */
+  :scope[sticky-header] { padding-top: 0; }
   :scope[sticky-header] > :where(header, header-ui) {
     position: sticky;
     top: 0;
     z-index: 1;
     background: var(--page-sticky-bg, var(--page-sticky-bg-default));
+    /* Bleed horizontally over the page's inline [padding] so the opaque band
+       spans the full scroll width, then re-inset the content so it stays
+       aligned with the body. Vertical = its own breathing room. Card-ui
+       header pattern. (No negative margin-top — that breaks position:sticky.) */
+    margin-inline: calc(-1 * var(--page-pad, 0));
+    padding: var(--a-space-3) var(--page-pad, 0);
     transition: border-color var(--a-duration-fast) var(--a-easing), box-shadow var(--a-duration-fast) var(--a-easing);
   }
 

package/components/pagination/pagination.class.js

@@ -37,7 +37,7 @@ export class UIPagination extends UIElement {
     size:     { type: String, default: 'md', reflect: true },
   };
 
-  // Phosphor icons stamped by this primitive (prev/next chevrons inside
+  // Phosphor icons stamped by this primitive (prev/next carets inside
   // the nested <button-ui>). Audited by check-required-icons.mjs.
   static requiredIcons = ['caret-left', 'caret-right'];
 

package/components/pagination/pagination.css

@@ -23,9 +23,12 @@
   :scope {
     /* ── Base ── */
     box-sizing: border-box;
-    display: inline-flex;
+    display: flex;
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-flex; }
+
   /* ── Nav container ── */
   [slot="nav"] {
     display: flex;
@@ -66,5 +69,10 @@
      aspect-ratio 1 here for the bordered-cell look). */
   :scope[variant="button"] [slot="nav"] button-ui {
     aspect-ratio: 1;
+    /* 1:1 cells inherit button-ui's --a-radius-md (~13px), which on a square
+       cell is ~37% of the side → a circle, not the "square 1:1 bordered button"
+       the variant promises. Tighten to -sm so the bordered cells read as rounded
+       squares. Same square+large-radius trap as otp-input (bug-37 / bug-39). */
+    --button-radius: var(--a-radius-sm);
   }
 }

package/components/pipeline-status/pipeline-status.css

@@ -96,11 +96,17 @@
     transition:          background var(--pipeline-status-duration, var(--pipeline-status-duration-default)) var(--pipeline-status-easing, var(--pipeline-status-easing-default));
   }
 
+  /* State colors: the -active (accent) / -complete (success) dot-bg tokens were
+     defined but never applied — these rules only set animation, so every dot
+     stayed the default gray (--a-border). Now active dots read accent + pulse,
+     complete dots read success. (bug-40 — "use color more") */
   [data-pipeline-dot="active"] {
+    background:           var(--pipeline-status-dot-bg-active, var(--pipeline-status-dot-bg-active-default));
     animation:           pipeline-pulse var(--pipeline-status-pulse-duration, var(--pipeline-status-pulse-duration-default)) var(--pipeline-status-pulse-easing, var(--pipeline-status-pulse-easing-default)) infinite;
   }
 
   [data-pipeline-dot="complete"] {
+    background:           var(--pipeline-status-dot-bg-complete, var(--pipeline-status-dot-bg-complete-default));
     animation:           none;
   }
 

package/components/popover/popover.css

@@ -14,10 +14,13 @@
 
   :scope {
     box-sizing: border-box;
-    display: inline-flex;
+    display: flex;
     position: relative;
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-flex; }
+
   [slot="trigger"] {
     display: inline-flex;
   }
@@ -81,6 +84,14 @@
     box-shadow: var(--popover-shadow, var(--popover-shadow-default));
   }
 
+  /* Prose margin reset on the content's edge children — a slotted <p> / <h*>
+     carries the UA stylesheet's margin-block (~1em), which lands inside the
+     panel padding and adds asymmetric top/bottom space (a single-line <p> looked
+     like it had a stray bottom margin). Zero the leading/trailing margins so the
+     panel padding alone frames the content. (bug — Popover single-line space) */
+  [slot="content"] > :first-child { margin-block-start: 0; }
+  [slot="content"] > :last-child  { margin-block-end: 0; }
+
   [slot="content"]:popover-open {
     @starting-style {
       opacity: 0;

package/components/preview/preview.css

@@ -39,16 +39,42 @@
      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. */
+  /* Column flow is the default: each example stacks in DOM order and fills the
+     stage width (align-items: stretch), so block-level demos (progress / bars /
+     accordion / cards / pages …) read at full width without a per-component
+     list. Text-flow atoms (button / badge / tag / …) opt back to content-width
+     via align-self below. (bug-46 — replaces the old flex-row + :only-child
+     block-flow hack, which only filled single-child demos.) */
   [data-preview-render] {
     display: flex;
-    flex-wrap: wrap;
-    align-items: center;
+    flex-direction: column;
+    align-items: stretch;
     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;
   }
-
+  /* Lone text-flow atoms shouldn't span the whole stage — keep them
+     content-width + leading-aligned (the ADR-0037 inline-display set). */
+  [data-preview-render] > :is(button-ui, badge-ui, tag-ui, chip-ui, kbd-ui, icon-ui, swatch-ui, spinner-ui, switch-ui, avatar-ui) {
+    align-self: start;
+  }
+  /* Form-field demos collapse to content-width as flex items in the render
+     cell — a placeholder-only combobox shrank to a ~52px "Sel…" stub — so
+     stretch form controls to the cell width with width:100%.
+       • <field-ui> is a full-width form ROW: let it fill the whole stage,
+         NO measure cap. The prior 28rem cap read as "not using available
+         space" on wide single-block demos (bug-55 follow-up).
+       • Bare atomic controls (input/select/…) keep the 28rem measure cap so
+         a lone control doesn't sprawl into an unrealistic bar on a wide stage.
+     Non-form demos (buttons, badges, etc.) are untouched — content-width. */
+  [data-preview-render] field-ui {
+    width: 100%;
+  }
+  [data-preview-render] > :is(input-ui, select-ui, combobox-ui, textarea-ui, tags-input-ui, color-input-ui) {
+    width: 100%;
+    max-width: 28rem;
+  }
   /* Code pane — divider line between panes; flatten the nested code-ui
      chrome so the preview frame owns the outer border + radius. */
   [data-preview-code] {
@@ -151,6 +177,7 @@
     color: var(--a-fg-muted);
     background: var(--a-bg-muted);
     padding: 0.125rem 0.375rem;
+    margin-bottom: 0.5rem;
     border-radius: var(--a-radius-sm);
   }
   /* Narrow: collapse each row to stacked render-over-code. */

package/components/progress-row/progress-row.css

@@ -1,7 +1,9 @@
 @scope (progress-row-ui) {
   :where(:scope) {
     /* ── Tokens ── */
-    --progress-row-gap-default:           var(--a-space-1);
+    /* Row-gap between the label/meta row and the bar. Bumped --a-space-1 →
+       --a-space-2 so the bar isn't crammed under the label. (bug-42) */
+    --progress-row-gap-default:           var(--a-space-2);
     --progress-row-column-gap-default:    var(--a-space-2);
     --progress-row-label-size-default:    var(--a-ui-size);
     --progress-row-label-fg-default:      var(--a-fg);

package/components/qr-code/qr-code.css

@@ -10,7 +10,7 @@
 
   :scope {
     box-sizing: border-box;
-    display: inline-block;
+    display: block;
     /* The SVG itself carries explicit width/height; this is a fallback
        for cases where the SVG hasn't stamped yet (empty value/matrix). */
     line-height: 0;
@@ -18,6 +18,9 @@
     background: var(--qr-code-bg, var(--qr-code-bg-default));
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-block; }
+
   :scope svg {
     display: block;
     /* Width / height come from the explicit SVG attributes set by JS

package/components/segmented/segmented.css

@@ -28,7 +28,7 @@
   :scope {
     /* ── Base ── */
     box-sizing: border-box;
-    display: inline-grid;
+    display: grid;
     grid-auto-flow: column;
     grid-auto-columns: 1fr;
     align-items: stretch;
@@ -55,6 +55,9 @@
     border-radius: var(--segmented-radius, var(--segmented-radius-default));
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-grid; }
+
   /* -- Indicator (hidden until first selection) -- */
   :scope > [data-indicator] {
     display: none;

package/components/select/select.a2ui.json

@@ -107,7 +107,7 @@
       "default": false
     },
     "options": {
-      "description": "Option list. Array of {value, label, disabled?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children.",
+      "description": "Option list. Array of {value, label, disabled?, icon?, avatar?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children. Per-option icon/avatar render in the list AND reflect in the trigger's selected state.",
       "type": "array",
       "default": []
     },