@adia-ai/web-components 0.8.24 → 0.8.25

package/components/anchor-bar/anchor-bar.yaml

@@ -0,0 +1,167 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAnchorBar
+tag: anchor-bar-ui
+status: beta
+component: AnchorBar
+category: container
+version: 1
+description: >-
+  Persistent, anchored, elevated surface for chrome that must stay visible
+  while a condition holds — floating bulk-action toolbars, undo bars,
+  sticky wizard/commit footers. Distinct from <toast-ui> (auto-dismissing,
+  notification semantics) and <modal-ui>/<drawer-ui> (blocking overlays
+  with backdrop + focus-trap semantics). Default mode anchors [anchor] to
+  the nearest scroll container via `position: sticky` — the shape gh#494's
+  bulk-action-toolbar pattern hand-rolled with card-ui + position:sticky.
+  Opt into [viewport] for a surface that anchors to the browser viewport
+  instead, promoted to the top layer via the Popover API (`popover="manual"`)
+  so it wins stacking over shell chrome without a z-index war. Visibility
+  is [open] (default false, no auto-dismiss timer) — arbitrary content
+  (typically <toolbar-ui> or <text-ui> + <button-ui>) rides the default slot.
+props:
+  anchor:
+    description: Viewport/container edge the bar sticks to.
+    type: string
+    default: bottom
+    reflect: true
+    enum:
+      - bottom
+      - top
+  align:
+    description: Horizontal alignment along the anchored edge.
+    type: string
+    default: center
+    reflect: true
+    enum:
+      - start
+      - center
+      - end
+  viewport:
+    description: >-
+      false (default) anchors to the nearest scroll container via
+      `position: sticky` — safe for content with ResizeObserver-driven
+      children (e.g. <toolbar-ui>'s overflow measurement never sees a
+      display:none reset). true anchors to the browser viewport via
+      `position: fixed` + Popover API top-layer promotion — note the
+      native Popover UA stylesheet applies `display:none` while closed,
+      which DOES reset ResizeObserver-driven children on first open;
+      prefer the default for content wrapping <toolbar-ui>.
+    type: boolean
+    default: false
+    reflect: true
+  open:
+    description: Controls visibility. No auto-dismiss — caller toggles explicitly.
+    type: boolean
+    default: false
+    reflect: true
+events:
+  open:
+    description: Fired when [open] becomes true.
+  close:
+    description: Fired when [open] becomes false.
+slots:
+  default:
+    description: >-
+      Arbitrary bar content — typically <toolbar-ui> (bulk-action bars) or
+      <text-ui> + <button-ui> (undo bars, wizard footers). The bar owns
+      only the elevated surface chrome (bg/border/radius/shadow) and
+      positioning; content layout is the slotted children's own.
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens:
+  --anchor-bar-bg:
+    description: Override background color
+  --anchor-bar-fg:
+    description: Override text color
+  --anchor-bar-border:
+    description: Override border color
+  --anchor-bar-radius:
+    description: Override corner radius
+  --anchor-bar-shadow:
+    description: Override elevation shadow
+  --anchor-bar-offset:
+    description: Override distance from the anchored edge
+a2ui:
+  rules:
+    - rule: >-
+        Persistent, non-blocking anchored surface. Use for floating
+        bulk-action toolbars, undo bars, and wizard/commit footers — never
+        for transient notifications (use <toast-ui>) or blocking dialogs
+        (use <modal-ui> / <drawer-ui>).
+      reason: 'Lifecycle boundary vs adjacent overlay surfaces.'
+    - rule: >-
+        Default [viewport=false] anchors within the nearest scroll
+        container via position:sticky — the correct choice when the bar
+        sits over a bounded scroll region (e.g. a table's own scroll box).
+        Set [viewport] only when the surface must anchor to the browser
+        viewport regardless of ancestor scroll containers (e.g. an undo
+        bar over an arbitrary page layout).
+      reason: 'Mode selection.'
+    - rule: >-
+        Does NOT join the modal mutual-exclusion convention — it is not a
+        modal surface and coexists with page interaction and open popovers.
+      reason: 'Overlay coexistence contract (gh#495).'
+anti_patterns: []
+examples:
+  - name: anchor-bar-demo
+    description: >-
+      Bottom-anchored bar containing a toolbar with a selection count and
+      action buttons, shown persistently while open.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Card",
+          "children": [
+            "bar"
+          ]
+        },
+        {
+          "id": "bar",
+          "component": "AnchorBar",
+          "anchor": "bottom",
+          "open": true,
+          "children": [
+            "toolbar"
+          ]
+        },
+        {
+          "id": "toolbar",
+          "component": "Toolbar",
+          "children": [
+            "count"
+          ]
+        },
+        {
+          "id": "count",
+          "component": "Text",
+          "text": "3 selected"
+        }
+      ]
+keywords:
+  - anchor
+  - bar
+  - floating
+  - toolbar
+  - undo
+  - persistent
+  - sticky
+  - footer
+  - selection
+  - bulk action
+synonyms:
+  bar:
+    - toolbar
+    - anchor
+    - footer
+  floating:
+    - anchor
+    - sticky
+    - popover
+  undo:
+    - anchor
+    - toast
+    - alert

package/components/chart/chart.a2ui.json

@@ -57,6 +57,17 @@
       "description": "JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x=\"month\" y=\"revenue\">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute.",
       "$ref": "common_types.json#/$defs/DynamicObjectList"
     },
+    "dots": {
+      "description": "Marker (dot) visibility for line and multi-line series. `all` draws a circle[data-dot] on every datum (default — matches pre-gh#561 behavior). `none` hides all dots so a dense series reads as a clean line. `hover` shows only the currently-hovered datum's dot. `last` shows only the terminal point per series (sparkline convention). Tooltip hit targets ([data-hit]) are a separate always-rendered layer — every mode keeps hover/click working along the whole line.",
+      "type": "string",
+      "enum": [
+        "all",
+        "none",
+        "hover",
+        "last"
+      ],
+      "default": "all"
+    },
     "format": {
       "description": "Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default \"$\"); `percent` multiplies × 100 and adds a % suffix.",
       "type": "string",
@@ -93,6 +104,11 @@
       "type": "number",
       "default": null
     },
+    "seriesEmphasis": {
+      "description": "Multi-line only. Names one series key (matching a `y` key) to render at full strength — area fill + full-opacity line. Every other series drops its area fill and renders line-only at --chart-deemphasized-opacity. Empty (default) applies full treatment to every series, unchanged from pre-gh#561 behavior.",
+      "type": "string",
+      "default": ""
+    },
     "size": {
       "description": "Chart size",
       "type": "string",

package/components/chart/chart.class.js

@@ -26,6 +26,8 @@
  *   hide-grid    — hide gridlines
  *   hide-values  — hide value labels
  *   radius       — bar corner radius (default: 4)
+ *   dots         — line/multi-line marker visibility: all|none|hover|last (default: all)
+ *   series-emphasis — multi-line: series key that keeps full area+line treatment; others render line-only, dimmed
  *
  * JS API:
  *   .data = [{...}, ...]  — array of data objects
@@ -222,6 +224,19 @@ export class UIChart extends UIElement {
     size:        { type: String,  default: '',       reflect: true },
     format:      { type: String,  default: 'abbr',   reflect: true },
     loading:     { type: Boolean, default: false,    reflect: true },
+    /* gh#561 — dot/marker visibility for line + multi-line. `all` is the
+       pre-561 default (every datum gets a circle[data-dot]); `none` /
+       `hover` / `last` exist because a 30-point small-integer series turns
+       into an unreadable bead string at `all`. Tooltip hit targets
+       ([data-hit]) are a separate always-rendered layer — every mode keeps
+       hover/click working along the whole line. */
+    dots:           { type: String, default: 'all', reflect: true },
+    /* gh#561 — names one multi-line series (a `y` key) to render at full
+       strength (area + full-opacity line); every other series drops its
+       area and renders line-only at --chart-deemphasized-opacity. Empty
+       (default) applies full treatment to every series — unchanged from
+       pre-561 behavior. */
+    seriesEmphasis: { type: String, default: '', reflect: true, attribute: 'series-emphasis' },
   };
 
   static template = () => null;
@@ -235,6 +250,10 @@ export class UIChart extends UIElement {
   /* Set of series keys hidden by external chart-legend-ui[for=self] toggles.
      Kept at render time; repopulated lookups rebuild with the new set. */
   #hiddenSeriesKeys = new Set();
+  /* gh#561 — dots="hover": the currently-shown dot element (a sibling of the
+     hovered [data-hit] circle), tracked so it can be cleared on leave /
+     re-render without a full DOM query. */
+  #activeDotEl = null;
 
   /** Resolves the corner radius: the `radius` prop if explicitly set,
    *  otherwise `--a-radius` from the host's computed style. Falls back
@@ -463,7 +482,11 @@ export class UIChart extends UIElement {
     }
     this.setAttribute('data-has-data', '');
 
-    this.#injectSeriesColors();
+    /* gh#561 — the DOM this pointed at is about to be wiped; drop the
+       reference so a stale node isn't held onto (its data-dot-active
+       attribute doesn't matter once detached, but nulling avoids leaking
+       the reference between renders). */
+    this.#activeDotEl = null;
 
     const svgWrap = document.createElement('div');
     if (this.type === 'sparkline') svgWrap.setAttribute('data-sparkline', '');
@@ -522,25 +545,26 @@ export class UIChart extends UIElement {
        tooltip-ui[follows=pointer] lands. */
   }
 
-  /* ── Per-series --color-{key} injection ──
-     For each declared series key (`y="revenue,users"`), emit an inline CSS
-     custom property on the host mapping the key to the categorical palette
-     slot it occupies. Consumers override `--color-revenue` at any ancestor
-     to recolor that series across chart + legend + (Phase 2) tooltip. */
-  #injectSeriesColors() {
-    const keys = this.#yKeys();
-    for (let i = 0; i < keys.length; i++) {
-      const slot = i % 10;
-      this.style.setProperty(`--color-${keys[i]}`, `var(--chart-${slot})`);
-    }
-  }
+  /* ── Per-series --color-{key} hook ──
+     gh#561 — previously this method wrote `--color-{key}: var(--chart-N)`
+     as an inline style on the HOST. Inline styles win the cascade over
+     everything except `!important`, so a consumer setting `--color-MAU` on
+     any ancestor lost to the chart's own inline default — the documented
+     "override --color-{key} to recolor a series" hook was unusable from
+     outside. The fix is to not set the host property at all: each
+     series-keyed element already carries its own inline
+     `var(--color-{key}, var(--chart-{slot}))` fallback chain (see
+     #seriesFill / #seriesStroke below), so an unset --color-{key} still
+     resolves to the right palette slot, and a consumer-set one now
+     actually wins. */
 
   /* Render-time helpers — emit data-slice + series-key + inline style that
-     references `--color-{key}` with fallback to `--chart-{slot}`. Inline
-     style beats the stylesheet's data-slice rule, so consumer overrides of
-     --color-{key} at any ancestor recolor that series. Non-series-keyed
-     elements (pie/donut/segments categorical slots) keep data-slice only
-     and are coloured by the stylesheet. */
+     references `--color-{key}` with fallback to `--chart-{slot}`. Because
+     nothing sets `--color-{key}` on the host anymore, an ancestor-set
+     value flows through the normal cascade into this var() and wins. Only
+     an unset `--color-{key}` falls through to `--chart-{slot}`.
+     Non-series-keyed elements (pie/donut/segments categorical slots) keep
+     data-slice only and are coloured by the stylesheet. */
   #seriesFill(slotIdx, seriesKey) {
     if (!seriesKey) return ` data-slice="${slotIdx}"`;
     return ` data-slice="${slotIdx}" data-series-key="${esc(seriesKey)}" style="fill: var(--color-${seriesKey}, var(--chart-${slotIdx}))"`;
@@ -813,6 +837,7 @@ export class UIChart extends UIElement {
 
   #emitHover(target, event) {
     this.#hoveredTarget = target;
+    if (this.dots === 'hover') this.#setActiveDot(target);
     this.dispatchEvent(new CustomEvent('chart-hover', {
       bubbles: true,
       detail: this.#tipPayload(target, event),
@@ -821,9 +846,32 @@ export class UIChart extends UIElement {
 
   #emitLeave() {
     this.#hoveredTarget = null;
+    if (this.dots === 'hover') this.#clearActiveDot();
     this.dispatchEvent(new CustomEvent('chart-leave', { bubbles: true }));
   }
 
+  /* gh#561 — dots="hover". The dot circle for a point is always the DOM
+     sibling immediately before its [data-hit] circle (both renderers push
+     them back-to-back: `<circle data-dot>` then `<circle data-hit>`), so
+     no separate index bookkeeping is needed to pair them. */
+  #setActiveDot(target) {
+    const dot = target?.previousElementSibling;
+    if (this.#activeDotEl && this.#activeDotEl !== dot) {
+      this.#activeDotEl.removeAttribute('data-dot-active');
+    }
+    if (dot && dot.hasAttribute('data-dot')) {
+      dot.setAttribute('data-dot-active', '');
+      this.#activeDotEl = dot;
+    } else {
+      this.#activeDotEl = null;
+    }
+  }
+
+  #clearActiveDot() {
+    if (this.#activeDotEl) this.#activeDotEl.removeAttribute('data-dot-active');
+    this.#activeDotEl = null;
+  }
+
   /* Build the standard event payload from a hovered/clicked datum element.
      OD-CHART-05 — per-X-column granularity. For multi-series renderers
      (stacked-bar, grouped-bar, multi-line, composed), the pointer is
@@ -959,6 +1007,20 @@ export class UIChart extends UIElement {
     return this.y ? this.y.split(',').map(k => k.trim()).filter(Boolean) : [];
   }
 
+  /* gh#561 — dots mode. `none`/`last` decide at render time (no dot markup
+     emitted for suppressed points); `hover` renders every dot but CSS
+     hides them by default (`[dots="hover"] [data-dot]`), and the pointer
+     handlers above toggle `data-dot-active` on the one under the cursor. */
+  #shouldRenderDot(i, total) {
+    switch (this.dots) {
+      case 'none': return false;
+      case 'last': return i === total - 1;
+      case 'hover':
+      case 'all':
+      default: return true;
+    }
+  }
+
   /* ── Grid + axes helper ───────────────────────────────────────── */
 
   #gridAndAxes(width, height, ticks, labels, pad, dims) {
@@ -1096,13 +1158,15 @@ export class UIChart extends UIElement {
     const showValues = !this.hideValues && !isSm;
     const showAverage = !this.hideAverage && vals.length > 1 && !isSm && !this.hideGrid;
 
-    for (const p of points) {
-      svg += `<circle data-dot cx="${p.x}" cy="${p.y}" r="${dotR}"/>`;
+    points.forEach((p, i) => {
+      if (this.#shouldRenderDot(i, points.length)) {
+        svg += `<circle data-dot cx="${p.x}" cy="${p.y}" r="${dotR}"/>`;
+      }
       svg += `<circle data-hit${tip({ label: p.label, value: p.v })} cx="${p.x}" cy="${p.y}" r="${hitR}" fill="transparent"/>`;
       if (showValues) {
         svg += `<text data-value x="${p.x}" y="${p.y - 8}" text-anchor="middle" font-size="${dims.valueSize}">${this.#fmtValue(p.v)}</text>`;
       }
-    }
+    });
 
     if (showAverage) {
       const avg = vals.reduce((a, b) => a + b, 0) / vals.length;
@@ -2082,18 +2146,32 @@ export class UIChart extends UIElement {
       const baseline = pad.top + plotH;
       const t = Math.max(0, Math.min(1, this.smooth));
 
-      /* Area fill */
-      svg += `<path data-area${this.#seriesFill(k % 10, keys[k])} d="${smoothAreaPath(points, baseline, t)}"/>`;
+      /* gh#561 — per-series emphasis. When `series-emphasis` names a key,
+         only that series keeps its area fill + full-strength line; every
+         other series drops the area and renders line-only at
+         --chart-deemphasized-opacity (data-deemphasized, CSS-driven — no
+         raw colors touched). Unset (default) emphasizes every series,
+         matching pre-561 behavior. */
+      const emphasisKey = this.seriesEmphasis;
+      const isEmphasized = !emphasisKey || keys[k] === emphasisKey;
+      const deemphAttr = isEmphasized ? '' : ' data-deemphasized';
+
+      /* Area fill — omitted entirely for deemphasized series. */
+      if (isEmphasized) {
+        svg += `<path data-area${this.#seriesFill(k % 10, keys[k])} d="${smoothAreaPath(points, baseline, t)}"/>`;
+      }
 
       /* Line */
-      svg += `<path data-line${this.#seriesStroke(k % 10, keys[k])} d="${smoothPath(points, t)}"/>`;
+      svg += `<path data-line${this.#seriesStroke(k % 10, keys[k])}${deemphAttr} d="${smoothPath(points, t)}"/>`;
 
       /* Dots + hit targets. Hit circles deliberately omit data-slice so
          they aren't caught by the circle[data-slice] fill rule in CSS. */
-      for (const p of points) {
-        svg += `<circle data-dot${this.#seriesFill(k % 10, keys[k])} cx="${p.x}" cy="${p.y}" r="3"/>`;
+      points.forEach((p, i) => {
+        if (this.#shouldRenderDot(i, points.length)) {
+          svg += `<circle data-dot${this.#seriesFill(k % 10, keys[k])}${deemphAttr} cx="${p.x}" cy="${p.y}" r="3"/>`;
+        }
         svg += `<circle data-hit${tip({ label: p.label, value: p.v, series: keys[k] })} cx="${p.x}" cy="${p.y}" r="10" fill="transparent"/>`;
-      }
+      });
     }
 
     this.#legendData = keys.map((k, i) => ({ label: k, key: k, slot: i % 10 }));

package/components/chart/chart.css

@@ -25,6 +25,9 @@
     --chart-area-opacity:   0.15;
     --chart-line-width:     2;
     --chart-radius:         4;
+    /* gh#561 — opacity applied to a multi-line series' line when
+       series-emphasis names a different series (data-deemphasized). */
+    --chart-deemphasized-opacity: 0.4;
 
     /* Layout */
     --chart-border:         var(--md-sys-color-neutral-outline-variant);
@@ -227,6 +230,30 @@
     r: 5;
   }
 
+  /* ── gh#561 — dots mode ──
+     `all` (default) leaves [data-dot] at full opacity, matching pre-561
+     behavior. `none`/`last` decide what to render in JS (no markup
+     emitted for suppressed points) so no CSS is needed for them. `hover`
+     renders every dot but hides them by default; the pointer handlers in
+     chart.js toggle [data-dot-active] on the one under the cursor. */
+  :scope[dots="hover"] [data-dot] {
+    opacity: 0;
+    transition: opacity var(--chart-duration) var(--chart-easing), r var(--chart-duration) var(--chart-easing);
+  }
+
+  :scope[dots="hover"] [data-dot][data-dot-active] {
+    opacity: 1;
+  }
+
+  /* ── gh#561 — multi-line per-series emphasis ──
+     `series-emphasis` names one series to keep full strength; every other
+     series' [data-line] (and its dots, if rendered) carry data-deemphasized
+     and dim to this token instead. Its [data-area] is never emitted at
+     all (see chart.js), so there's no fill to dim. */
+  [data-deemphasized] {
+    opacity: var(--chart-deemphasized-opacity);
+  }
+
   /* ── Average line ── */
 
   [data-avg] {

package/components/chart/chart.d.ts

@@ -24,6 +24,8 @@ export class UIChart extends UIElement {
   color: 'accent' | 'success' | 'warning' | 'danger' | 'info';
   /** JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x="month" y="revenue">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data="[…]"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute. */
   data: string;
+  /** Marker (dot) visibility for line and multi-line series. `all` draws a circle[data-dot] on every datum (default — matches pre-gh#561 behavior). `none` hides all dots so a dense series reads as a clean line. `hover` shows only the currently-hovered datum's dot. `last` shows only the terminal point per series (sparkline convention). Tooltip hit targets ([data-hit]) are a separate always-rendered layer — every mode keeps hover/click working along the whole line. */
+  dots: 'all' | 'none' | 'hover' | 'last';
   /** Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default "$"); `percent` multiplies × 100 and adds a % suffix. */
   format: 'abbr' | 'decimal' | 'currency' | 'percent';
   /** When true, suppress the overlaid average line */
@@ -36,6 +38,8 @@ export class UIChart extends UIElement {
   loading: boolean;
   /** Bar corner radius (null = let CSS tokens decide) */
   radius: number;
+  /** Multi-line only. Names one series key (matching a `y` key) to render at full strength — area fill + full-opacity line. Every other series drops its area fill and renders line-only at --chart-deemphasized-opacity. Empty (default) applies full treatment to every series, unchanged from pre-gh#561 behavior. */
+  seriesEmphasis: string;
   /** Chart size */
   size: 'sm' | 'md' | 'lg';
   /** Line smoothing factor */

package/components/chart/chart.yaml

@@ -92,6 +92,34 @@ props:
     description: Line smoothing factor
     type: number
     default: 0.4
+  dots:
+    description: >-
+      Marker (dot) visibility for line and multi-line series. `all` draws a
+      circle[data-dot] on every datum (default — matches pre-gh#561
+      behavior). `none` hides all dots so a dense series reads as a clean
+      line. `hover` shows only the currently-hovered datum's dot. `last`
+      shows only the terminal point per series (sparkline convention).
+      Tooltip hit targets ([data-hit]) are a separate always-rendered
+      layer — every mode keeps hover/click working along the whole line.
+    type: string
+    default: all
+    enum:
+      - all
+      - none
+      - hover
+      - last
+    reflect: true
+  seriesEmphasis:
+    description: >-
+      Multi-line only. Names one series key (matching a `y` key) to render
+      at full strength — area fill + full-opacity line. Every other series
+      drops its area fill and renders line-only at
+      --chart-deemphasized-opacity. Empty (default) applies full treatment
+      to every series, unchanged from pre-gh#561 behavior.
+    type: string
+    default: ""
+    attribute: series-emphasis
+    reflect: true
   loading:
     description: >-
       Show a skeleton placeholder instead of the chart body. Set to true

package/components/index.js

@@ -41,6 +41,7 @@ export { UIDrawer } from './drawer/drawer.js';
 export { UIModal } from './modal/modal.js';
 export { UIToast } from './toast/toast.js';
 export { UIFeedContainer, UIFeedItem, UIFeed } from './feed/feed.js';
+export { UIAnchorBar } from './anchor-bar/anchor-bar.js';
 export { UITabs } from './tabs/tabs.js';
 export { UITab } from './tabs/tab.js';
 export { UITooltip } from './tooltip/tooltip.js';

package/components/stat/stat.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "band": {
+      "description": "Chart-band KPI layout. With a `slot=\"chart\"` child, label / value / change stack full width top to bottom and the chart forms a short full-width band between the value and the change row (the Gmail/Vercel/shadcn stat-card shape). Composes with `icon` exactly as the base layout does. No effect without a chart slot.",
+      "type": "boolean",
+      "default": false
+    },
     "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",
@@ -233,6 +238,9 @@
       "--stat-change-size": {
         "description": "Font size for the change badge"
       },
+      "--stat-chart-band-height": {
+        "description": "Fixed height of the full-width chart band in `band` layout"
+      },
       "--stat-column-gap": {
         "description": "Horizontal gap between grid columns"
       },

package/components/stat/stat.css

@@ -16,6 +16,9 @@
     --stat-column-gap:   var(--a-gap-self, var(--a-gap));
     --stat-row-gap:      var(--a-gap-sm);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
+
+    /* ── Chart-band mode ── */
+    --stat-chart-band-height: 3rem;
 }
 
   :scope {
@@ -127,6 +130,42 @@
     aspect-ratio: auto;
   }
 
+  /* ── Chart-band KPI tile ──
+     label / value / chart-band / change stack full width, top to bottom —
+     the Gmail/Vercel/shadcn stat-card shape: a short full-width trend band
+     sits between the hero number and the delta footer, instead of the
+     inline chart resting beside the value (compact) or the bleed panel
+     replacing the text column (wide). Text rows stay baseline-aligned;
+     the band row stretches to its own fixed height. Compose inside a card
+     section:
+       <stat-ui band value=… label=… change=… trend=…>
+         <chart-ui slot="chart" type="sparkline" …></chart-ui>
+       </stat-ui>  */
+  :scope[band]:has([slot="chart"]) {
+    grid-template-columns: minmax(0, 1fr) auto;
+    grid-template-areas:
+      "label  icon"
+      "value  value"
+      "chart  chart"
+      "change change";
+    align-items: baseline;
+  }
+  /* Restore full-width value span — the inline-chart reflow above confines
+     value to column 1 to make room for the beside-value chart; band has no
+     such column, so the value spans both again. */
+  :scope[band] [slot="value"] {
+    grid-column: 1 / -1;
+  }
+  :scope[band] [slot="chart"] {
+    grid-area: chart;
+    /* Band row stretches to its own fixed short height rather than the
+       inline-chart's baseline-anchored 4:3 box — aspect-ratio released. */
+    align-self: stretch;
+    width: 100%;
+    height: var(--stat-chart-band-height);
+    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 {
+  /** Chart-band KPI layout. With a `slot="chart"` child, label / value / change stack full width top to bottom and the chart forms a short full-width band between the value and the change row (the Gmail/Vercel/shadcn stat-card shape). Composes with `icon` exactly as the base layout does. No effect without a chart slot. */
+  band: boolean;
   /** 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%') */

package/components/stat/stat.js

@@ -23,6 +23,11 @@ class UIStat extends UIElement {
     // slot="chart" child fills the right column and bleeds to the card edges.
     // Reflected so the [bleed] CSS selector gates the layout.
     bleed:   { type: Boolean, default: false, reflect: true },
+    // Chart-band layout: label/value/chart/change stack full width, top to
+    // bottom, with the slot="chart" child forming a short full-width band
+    // between the value and the change row. Reflected so the [band] CSS
+    // selector gates the layout.
+    band:    { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;

package/components/stat/stat.yaml

@@ -58,6 +58,15 @@ props:
       without a chart slot.
     type: boolean
     default: false
+  band:
+    description: >-
+      Chart-band KPI layout. With a `slot="chart"` child, label / value /
+      change stack full width top to bottom and the chart forms a short
+      full-width band between the value and the change row (the
+      Gmail/Vercel/shadcn stat-card shape). Composes with `icon` exactly as
+      the base layout does. No effect without a chart slot.
+    type: boolean
+    default: false
 events: {}
 slots:
   change:
@@ -81,6 +90,8 @@ traits: []
 tokens:
   --stat-change-size:
     description: Font size for the change badge
+  --stat-chart-band-height:
+    description: Fixed height of the full-width chart band in `band` layout
   --stat-column-gap:
     description: Horizontal gap between grid columns
   --stat-down-fg: