@adia-ai/web-components 0.6.50 → 0.7.0

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": []
     },

package/components/select/select.class.js

@@ -71,6 +71,7 @@ export class UISelect extends UIFormElement {
   static template = () => null;
 
   #options = [];
+  #ownTrigger = false; // true when WE stamped the trigger (vs a consumer-custom one)
   #listbox = null;
   #anchorCleanup = null;
   #query = '';
@@ -386,14 +387,18 @@ export class UISelect extends UIFormElement {
 
     // Stamp default trigger if none provided
     if (!this.querySelector('[slot="trigger"]')) {
+      this.#ownTrigger = true;
       // Detach listbox before innerHTML wipe so it isn't destroyed
       const lb = this.#listbox;
       if (lb?.parentNode === this) this.removeChild(lb);
 
+      // Initial leading reflects the host [avatar]/[icon]; #syncLeading() then
+      // reconciles it to the SELECTED option's icon/avatar on every render. The
+      // `data-select-leading` marker scopes that reconciliation to our element.
       const leading = this.avatar
-        ? `<img slot="leading" src="${this.avatar}" alt="" />`
+        ? `<img slot="leading" data-select-leading src="${escapeHTML(this.avatar)}" alt="" />`
         : this.icon
-          ? `<icon-ui slot="leading" name="${this.icon}"></icon-ui>`
+          ? `<icon-ui slot="leading" data-select-leading name="${escapeHTML(this.icon)}"></icon-ui>`
           : '';
       const displayMarkup = this.searchable
         ? `<input slot="display" type="text" role="combobox" aria-autocomplete="list" autocomplete="off" placeholder="${escapeHTML(this.placeholder || '')}" value="${escapeHTML(this.#displayText() === this.placeholder ? '' : this.#displayText())}" />`
@@ -470,6 +475,9 @@ export class UISelect extends UIFormElement {
       }
     }
 
+    // Reflect the selected option's icon/avatar in the trigger leading.
+    this.#syncLeading();
+
     // SPEC-040 — stamp / reconcile chips + "+N more" pill on every render.
     if (this.multiple) this.#stampChips();
     // Show clear-all only in multi-select mode when [clearable] + chips present.
@@ -548,12 +556,12 @@ export class UISelect extends UIFormElement {
       if (child.tagName === 'OPTGROUP') {
         const group = { label: child.label || child.getAttribute('label') || '', options: [] };
         for (const opt of child.querySelectorAll('option')) {
-          group.options.push({ value: opt.value, label: opt.textContent.trim(), disabled: opt.disabled });
+          group.options.push({ value: opt.value, label: opt.textContent.trim(), disabled: opt.disabled, icon: opt.getAttribute('icon') || '', avatar: opt.getAttribute('avatar') || '' });
           if (opt.hasAttribute('selected')) preSelectedArr.push(opt.value);
         }
         this.#options.push(group);
       } else if (child.tagName === 'OPTION') {
-        this.#options.push({ value: child.value, label: child.textContent.trim(), disabled: child.disabled });
+        this.#options.push({ value: child.value, label: child.textContent.trim(), disabled: child.disabled, icon: child.getAttribute('icon') || '', avatar: child.getAttribute('avatar') || '' });
         if (child.hasAttribute('selected')) preSelectedArr.push(child.value);
       } else if (
         // §225: skip [slot="display"] / [slot="listbox"] / [slot="action"] etc. — these are
@@ -614,6 +622,52 @@ export class UISelect extends UIFormElement {
 
   get options() { return this.#options; }
 
+  // Per-option leading markup: avatar (img) beats icon (icon-ui). Shared by
+  // the listbox rows AND the trigger (resolved against the selected option).
+  static #optionLeadHTML(opt) {
+    if (!opt) return '';
+    if (opt.avatar) return `<img data-option-avatar src="${escapeHTML(opt.avatar)}" alt="" />`;
+    if (opt.icon) return `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>`;
+    return '';
+  }
+
+  /**
+   * Reflect the SELECTED option's icon/avatar in the trigger's leading slot.
+   * Single-select only (multi-select shows chips). Falls back to the host
+   * [avatar]/[icon] when the selected option carries neither. Only manages the
+   * leading WE stamped (`[data-select-leading]`) — a consumer-custom trigger
+   * owns its own leading.
+   */
+  #syncLeading() {
+    if (this.multiple || !this.#ownTrigger) return;
+    const trigger = this.querySelector('[slot="trigger"]');
+    if (!trigger) return;
+    const flat = this.#options.flatMap((o) => o.options || [o]);
+    const sel = flat.find((o) => !o.header && !o.separator && o.value === this.value);
+    const avatar = (sel && sel.avatar) || this.avatar || '';
+    const icon = (sel && sel.icon) || this.icon || '';
+    const existing = trigger.querySelector(':scope > [data-select-leading]');
+    let html = '';
+    if (avatar) html = `<img slot="leading" data-select-leading src="${escapeHTML(avatar)}" alt="" />`;
+    else if (icon) html = `<icon-ui slot="leading" data-select-leading name="${escapeHTML(icon)}"></icon-ui>`;
+    if (!html) { existing?.remove(); return; }
+    const tmp = document.createElement('template');
+    tmp.innerHTML = html;
+    const next = tmp.content.firstElementChild;
+    if (!existing) {
+      trigger.insertBefore(next, trigger.firstChild);
+    } else if (existing.tagName === next.tagName) {
+      // Same element type — update the changing attribute in place.
+      if (next.tagName === 'IMG') {
+        if (existing.getAttribute('src') !== next.getAttribute('src')) existing.setAttribute('src', next.getAttribute('src'));
+      } else if (existing.getAttribute('name') !== next.getAttribute('name')) {
+        existing.setAttribute('name', next.getAttribute('name'));
+      }
+    } else {
+      existing.replaceWith(next); // icon ↔ avatar switch
+    }
+  }
+
   #renderOptions() {
     if (!this.#listbox) return;
     this.#listbox.innerHTML = '';
@@ -653,6 +707,8 @@ export class UISelect extends UIFormElement {
       // SPEC-040 — multi-select option rows render a leading checkbox
       // indicator (CSS-driven via [data-multi-option]); the `check` icon
       // shows when aria-selected="true".
+      // Per-option leading glyph — avatar (img) wins over icon (icon-ui).
+      const lead = UISelect.#optionLeadHTML(opt);
       if (this.multiple) {
         el.setAttribute('data-multi-option', '');
         const box = document.createElement('span');
@@ -661,11 +717,11 @@ export class UISelect extends UIFormElement {
         el.appendChild(box);
         const label = document.createElement('span');
         label.setAttribute('data-option-label', '');
-        if (opt.icon) label.innerHTML = `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>${escapeHTML(opt.label)}`;
+        if (lead) label.innerHTML = `${lead}${escapeHTML(opt.label)}`;
         else label.textContent = opt.label;
         el.appendChild(label);
-      } else if (opt.icon) {
-        el.innerHTML = `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>${escapeHTML(opt.label)}`;
+      } else if (lead) {
+        el.innerHTML = `${lead}${escapeHTML(opt.label)}`;
       } else {
         el.textContent = opt.label;
       }

package/components/select/select.css

@@ -191,6 +191,11 @@
   :scope[data-multi-chips] [slot="trigger"] {
     flex-wrap: wrap;
     align-items: center;
+    /* Pack chips left with a small gap — override the base trigger's
+       `space-between` (which is for the single-select content↔caret split),
+       otherwise the chips spread across the full trigger width. The display
+       slot flex-grows (below) to push the caret to the trailing edge. */
+    justify-content: flex-start;
     gap: var(--a-space-1);
     /* min-height tracks single-row height when empty; flex-wrap allows
        it to grow as chips overflow. */
@@ -290,6 +295,8 @@ select-ui [slot="listbox"]:popover-open {
 }
 
 select-ui [role="option"] {
+  display: flex;
+  align-items: center;
   padding: var(--a-space-1) var(--a-ui-px);
   border-radius: var(--a-radius-sm);
   white-space: nowrap;
@@ -325,6 +332,17 @@ select-ui [role="option"] icon-ui {
   vertical-align: -0.125em;
 }
 
+/* Option with avatar — small inline image (matches the trigger leading
+   avatar radius), sized to the option line-height. */
+select-ui [role="option"] img[data-option-avatar] {
+  width: var(--a-ui-size);
+  height: var(--a-ui-size);
+  border-radius: var(--select-leading-radius, var(--select-leading-radius-default));
+  object-fit: cover;
+  margin-inline-end: var(--a-space-1);
+  vertical-align: -0.2em;
+}
+
 /* Separator */
 select-ui [data-separator] {
   height: 1px;

package/components/select/select.yaml

@@ -23,7 +23,7 @@ description: |
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
-  - icon-ui   # chevron + option-row affixes (created in render)
+  - icon-ui   # caret + option-row affixes (created in render)
   - tag-ui    # multi-select chip per selected option in the trigger
 props:
   name:
@@ -151,7 +151,7 @@ props:
     default: false
     reflect: true
   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: []
   pattern:
@@ -249,6 +249,13 @@ a2ui:
       tag names are silently ignored (per §225 v0.5.9) and warned once
       at runtime. Or set `.options` programmatically as an array of
       `{value, label, disabled?}` (grouped form: `{label, options:[…]}`).
+    - >-
+      Per-option visuals: give each <option> an `icon` (Phosphor name) or
+      `avatar` (image URL) — `<option value="light" icon="sun">`. Each row
+      renders its glyph in the list AND the trigger reflects the SELECTED
+      option's icon/avatar (theme pickers, assignee/account switchers).
+      `avatar` wins over `icon`; a host-level [icon]/[avatar] is the
+      fallback when the selected option carries neither.
     - >-
       For dynamic option lists rendered inside <editor-shell>, set the
       JSON via the [data-options] attribute — <editor-shell>'s

package/components/stack/stack.a2ui.json

@@ -14,8 +14,19 @@
   ],
   "properties": {
     "align": {
-      "description": "Alignment of stacked items",
+      "description": "Alignment of the layered children within the shared cell (maps to grid place-items). `center` (default) plus eight directional keywords.",
       "type": "string",
+      "enum": [
+        "center",
+        "top-left",
+        "top",
+        "top-right",
+        "left",
+        "right",
+        "bottom-left",
+        "bottom",
+        "bottom-right"
+      ],
       "default": "center"
     },
     "component": {

package/components/stack/stack.d.ts

@@ -21,6 +21,6 @@ cell.
 import { UIElement } from '../../core/element.js';
 
 export class UIStack extends UIElement {
-  /** Alignment of stacked items */
-  align: string;
+  /** Alignment of the layered children within the shared cell (maps to grid place-items). `center` (default) plus eight directional keywords. */
+  align: 'center' | 'top-left' | 'top' | 'top-right' | 'left' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
 }

package/components/stack/stack.yaml

@@ -18,9 +18,21 @@ description: |
   cell.
 props:
   align:
-    description: Alignment of stacked items
+    description: >-
+      Alignment of the layered children within the shared cell (maps to
+      grid place-items). `center` (default) plus eight directional keywords.
     type: string
     default: center
+    enum:
+      - center
+      - top-left
+      - top
+      - top-right
+      - left
+      - right
+      - bottom-left
+      - bottom
+      - bottom-right
 events: {}
 slots:
   default:

package/components/stat/stat.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "bleed": {
+      "description": "Horizontal-bleed KPI layout. With a `slot=\"chart\"` child, the value / label / change stack on the left while the chart fills the right column at full height and bleeds to the card's top / right / bottom edges (the horizontal counterpart to a chart in a card `<section bleed>`). No effect without a chart slot.",
+      "type": "boolean",
+      "default": false
+    },
     "change": {
       "description": "Change indicator text (e.g. '+12%', '-3%')",
       "type": "string",

package/components/stat/stat.css

@@ -72,6 +72,61 @@
     grid-column: 1;
   }
 
+  /* ── Horizontal-bleed KPI tile ──
+     value / label / change stack on the LEFT; the chart fills the RIGHT
+     column at full height and bleeds to the card's top / right / bottom
+     edges (cancels the card-section inset via negative margins keyed to
+     the inherited --card-inset). The compact `slot="chart"` reflow above
+     keeps the chart resting on the value baseline; this opt-in spreads it
+     into a full-height trajectory panel. Compose inside a card section:
+       <card-ui><section>
+         <stat-ui bleed value=… label=… change=… trend=…>
+           <chart-ui slot="chart" type="area" …></chart-ui>
+         </stat-ui>
+       </section></card-ui>  */
+  :scope[bleed]:has([slot="chart"]) {
+    grid-template-columns: minmax(0, 1fr) minmax(0, var(--stat-bleed-col, 46%));
+    grid-template-areas:
+      "label  chart"
+      "value  chart"
+      "change chart";
+    align-items: start;
+  }
+  :scope[bleed] [slot="value"],
+  :scope[bleed] [slot="change"] {
+    grid-column: 1;
+  }
+  /* Icon shares the label row, pinned to the text column's inner edge. */
+  :scope[bleed] [slot="label"] {
+    padding-inline-end: var(--a-space-5);
+  }
+  :scope[bleed] [slot="icon"] {
+    grid-area: label;
+    justify-self: end;
+    align-self: start;
+  }
+  :scope[bleed] [slot="chart"] {
+    grid-area: chart;
+    /* VERTICAL bleed via stretch: a stretched grid item's height is
+       `track − margins`, so a negative margin-block overflows the track by
+       that amount top + bottom. `height:auto` overrides the base
+       chart-ui[slot="chart"]{height:100%} so the stretch governs. */
+    align-self: stretch;
+    height: auto;
+    margin-block: calc(-1 * var(--card-inset, var(--card-inset-default, 0px)));
+    /* HORIZONTAL bleed via explicit width: chart-ui pins its own
+       `width:100%` (chart.css), which beats justify-self:stretch and would
+       freeze the box to the track — so a negative margin-inline-end can't
+       widen it. Instead size the box to `track + inset` and left-anchor it,
+       so the right edge overflows to the card edge while the left keeps the
+       column gap. The percentage resolves against the grid track. */
+    justify-self: start;
+    width: calc(100% + var(--card-inset, var(--card-inset-default, 0px)));
+    min-width: 0;
+    /* override the inline-chart 4:3 — fill the row span instead */
+    aspect-ratio: auto;
+  }
+
   /* ── Label (eyebrow) ── */
   [slot="label"] {
     grid-area: label;

package/components/stat/stat.d.ts

@@ -13,6 +13,8 @@
 import { UIElement } from '../../core/element.js';
 
 export class UIStat extends UIElement {
+  /** Horizontal-bleed KPI layout. With a `slot="chart"` child, the value / label / change stack on the left while the chart fills the right column at full height and bleeds to the card's top / right / bottom edges (the horizontal counterpart to a chart in a card `<section bleed>`). No effect without a chart slot. */
+  bleed: boolean;
   /** Change indicator text (e.g. '+12%', '-3%') */
   change: string;
   /** Icon name displayed in the icon slot */