@aceshooting/lyra-ui 1.1.0 → 2.0.0

package/dist/components/split/split.js

@@ -4,8 +4,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { html } from 'lit';
-import { property, state } from 'lit/decorators.js';
+import { html, nothing } from 'lit';
+import { property, state, query } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { isRtl } from '../../internal/rtl.js';
@@ -20,11 +20,28 @@ const NO_MAX_PX = 1_000_000;
  * `<lyra-split>` — resizable panels for dashboard layouts. Direct light-DOM
  * children are the panels; a divider is auto-inserted between each pair.
  *
+ * Optionally, one pane can opt in to responsive collapse via `collapse`
+ * (`"start"`/`"end"`, default `"none"` — no behavior change when unset): as
+ * the split's own container narrows past `railBreakpoint` that pane clamps
+ * to a fixed `railWidth`, and past the narrower `floatBreakpoint` it instead
+ * becomes an absolutely-positioned overlay "floating card" above the other
+ * pane. This component only handles the width-collapse mechanics and
+ * signals the current state — via the `collapseState`-derived
+ * `data-collapse-state` attribute (set on both the host and the collapsing
+ * panel itself) and the `lyra-split-collapse-change` event — it renders no
+ * icon-only/collapsed UI of its own; slotted content is expected to adapt to
+ * its own clamped width (e.g. via its own container query).
+ *
  * @customElement lyra-split
  * @event lyra-resize - `detail: { sizes }`, fired on every drag step/release
  *   and every keyboard step.
+ * @event lyra-split-collapse-change - `detail: { state }` (`SplitCollapseChangeDetail`),
+ *   fired whenever the responsive `collapseState` actually transitions between
+ *   `'wide'`/`'rail'`/`'floating'`. Only relevant when `collapse` isn't `"none"`;
+ *   never fires otherwise.
  * @slot - Panels to arrange side by side (or stacked, when `orientation="vertical"`); each direct child becomes one resizable panel.
- * @csspart base, divider
+ * @csspart base - The flex layout wrapper (`position: relative`, so the `'floating'` collapse state can anchor to it).
+ * @csspart divider - Each divider between two panels; carries `aria-disabled="true"` and is drag/keyboard-inert while its adjacent panel is collapsed (`'rail'`/`'floating'`).
  */
 export class LyraSplit extends LyraElement {
     constructor() {
@@ -38,21 +55,55 @@ export class LyraSplit extends LyraElement {
          *  localStorage persistence stay percent-based regardless — only the
          *  effective clamp bounds change for a constrained panel. */
         this.panelConstraints = [];
+        /** Opts a pane in to responsive collapse: `'start'` is the first light-DOM
+         *  panel (index 0), `'end'` is the last. Both are LOGICAL positions, same
+         *  as CSS `inset-inline-start`/`-end` — see the `collapsingIndex` getter
+         *  for why that already resolves to the same physical index under RTL for
+         *  this component (panels are never re-`order`ed for RTL, only the drag
+         *  delta sign mirrors). Default `'none'`: none of the collapse behavior
+         *  below applies, and rendering/behavior is identical to before this
+         *  property existed. */
+        this.collapse = 'none';
+        /** Fixed CSS length the collapsing pane clamps to in the `'rail'` state. */
+        this.railWidth = '3.5rem';
+        /** Container width (px, measured on `[part="base"]`) below which the
+         *  collapsing pane switches from its normal percent width to the fixed
+         *  `railWidth` (`'rail'` state). Must stay above `floatBreakpoint`. */
+        this.railBreakpoint = 640;
+        /** Container width (px) below which the collapsing pane instead becomes an
+         *  absolutely-positioned overlay above the other pane (`'floating'` state). */
+        this.floatBreakpoint = 400;
         this.panelCount = 0;
+        /** The collapsing pane's current responsive state; always `'wide'` (a
+         *  no-op) while `collapse === 'none'`. */
+        this.collapseState = 'wide';
         // Keyed by pointerId so an interrupted or concurrent (multi-touch) drag on
         // one divider never reads or clobbers another pointer's drag state.
         this.drags = new Map();
+        // Panels `updated()` last applied inline flex/order (and, while collapsing,
+        // position/inset/inline-size) styles to — tracked so a panel removed from
+        // the slot (e.g. a DOM node later reused elsewhere) gets those
+        // lyra-split-authored styles cleared instead of carrying them around stale
+        // forever.
+        this.stylizedPanels = new Set();
         this.onSlotChange = () => {
             this.panelCount = this.children.length;
             this.ensureSizes();
         };
         this.onPointerDown = (e, index) => {
+            // The divider adjacent to a currently rail/floating-collapsed pane isn't
+            // draggable — mirrors the `[part="divider"][aria-disabled="true"]`
+            // `pointer-events: none` in split.styles.ts (belt-and-suspenders: this
+            // guard also covers a synthetic/programmatic pointerdown that CSS
+            // wouldn't stop).
+            if (this.isDividerDisabled(index))
+                return;
             const base = this.renderRoot.querySelector('[part="base"]');
             this.drags.set(e.pointerId, {
                 index,
                 startPos: this.orientation === 'vertical' ? e.clientY : e.clientX,
-                startSizes: [...this.sizes],
                 base,
+                appliedDelta: 0,
             });
             e.target.setPointerCapture(e.pointerId);
             window.addEventListener('pointermove', this.onPointerMove);
@@ -70,14 +121,40 @@ export class LyraSplit extends LyraElement {
                 return;
             const total = this.orientation === 'vertical' ? drag.base.clientHeight : drag.base.clientWidth;
             const pos = this.orientation === 'vertical' ? e.clientY : e.clientX;
-            let deltaPercent = ((pos - drag.startPos) / total) * 100;
+            let cumulativeDelta = ((pos - drag.startPos) / total) * 100;
             // Panels are ordered along the inline axis via CSS `order`, so under RTL
             // `flex-direction: row` already renders panel[i] to the *right* of
             // panel[i+1] — a physically-rightward drag has to shrink index instead
             // of growing it to keep matching the visible panel under the pointer.
             if (this.orientation === 'horizontal' && isRtl(this))
-                deltaPercent = -deltaPercent;
-            const paired = this.clampPair(drag.startSizes, drag.index, deltaPercent, total);
+                cumulativeDelta = -cumulativeDelta;
+            // Clamp against the *current* live sizes, not this pointer's own drag-start
+            // snapshot -- two adjacent dividers dragged concurrently share one panel
+            // between them, and each clamp pass must see whatever the other pointer's
+            // move has *just* written, or the two independently-clamped pairs can each
+            // stay individually valid while their shared panel drifts past what either
+            // pair alone would allow, letting the total exceed 100%. Since the clamp
+            // basis is now the live, already-partially-applied `this.sizes` instead of
+            // a fixed drag-start snapshot, only the *incremental* delta since the last
+            // move may be applied here (not the cumulative-since-drag-start delta a
+            // snapshot-based clamp would use).
+            const incremental = cumulativeDelta - drag.appliedDelta;
+            const priorValue = this.sizes[drag.index];
+            const paired = this.clampPair(this.sizes, drag.index, incremental, total);
+            // Accumulate this move's own *realized* increment (post-clamp) onto the
+            // running total, rather than recomputing an absolute "total since
+            // drag-start" diff against a fixed startSizes snapshot. clampPair can
+            // cap the actual move short of what was requested (e.g. a drag
+            // saturating a panel's min/panelConstraints bound), so the realized
+            // portion still has to be tracked instead of the raw request -- that
+            // part of round 1's fix stands. But an absolute since-start diff also
+            // silently absorbs any change a DIFFERENT concurrent pointer's drag
+            // makes to this same shared panel between this pointer's own moves
+            // (adjacent dividers share one panel: divider i's index+1 panel is
+            // divider i+1's index panel), corrupting this pointer's next incremental
+            // calculation. Summing only this move's own delta (paired vs. the value
+            // immediately prior to *this* clamp) avoids both bugs at once.
+            drag.appliedDelta += paired[drag.index] - priorValue;
             // Merge only this drag's pair into the live sizes so a concurrent drag
             // on another divider (different pointerId) isn't clobbered.
             const next = [...this.sizes];
@@ -99,6 +176,9 @@ export class LyraSplit extends LyraElement {
             }
         };
         this.onDividerKeyDown = (e, index) => {
+            // Same rail/floating-adjacent guard as onPointerDown.
+            if (this.isDividerDisabled(index))
+                return;
             // Mirror the same swap as onPointerMove for horizontal+RTL.
             const rtl = this.orientation === 'horizontal' && isRtl(this);
             const forwardKey = this.orientation === 'vertical' ? 'ArrowDown' : rtl ? 'ArrowLeft' : 'ArrowRight';
@@ -119,6 +199,13 @@ export class LyraSplit extends LyraElement {
         this.panelCount = this.children.length;
         this.ensureSizes();
         this.loadPersisted();
+        // No-op on first mount (`baseEl` doesn't exist until the first render —
+        // `firstUpdated()` below arms it then) but does the real work on a
+        // reconnect, whose shadow DOM content survives disconnect. Mirrors
+        // lite-chart.ts's identical connectedCallback/firstUpdated split for its
+        // own ResizeObserver.
+        if (this.collapse !== 'none')
+            this.armCollapseObserver();
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -128,6 +215,11 @@ export class LyraSplit extends LyraElement {
         window.removeEventListener('pointerup', this.onPointerUp);
         window.removeEventListener('pointercancel', this.onPointerUp);
         window.removeEventListener('lostpointercapture', this.onPointerUp);
+        this.collapseResizeObserver?.disconnect();
+    }
+    firstUpdated() {
+        if (this.collapse !== 'none')
+            this.armCollapseObserver();
     }
     get storageFullKey() {
         return this.storageKey ? `lyra-split:${this.storageKey}:${this.panelCount}` : undefined;
@@ -211,6 +303,84 @@ export class LyraSplit extends LyraElement {
             return 0;
         return this.orientation === 'vertical' ? base.clientHeight : base.clientWidth;
     }
+    /** The physical panel index `collapse: 'start' | 'end'` resolves to, or
+     *  `-1` when collapse is off (`'none'`) or there are fewer than 2 panels
+     *  to collapse one of. Panels are laid out via ascending inline `order`
+     *  (see `updated()`) and that ordering is never re-swapped for RTL — only
+     *  the drag/keyboard *delta sign* mirrors for RTL, exactly like
+     *  `onPointerMove`/`onDividerKeyDown` — so panel index 0 already renders
+     *  at the logical inline-start edge under both LTR and RTL (confirmed by
+     *  the pointer-drag RTL test elsewhere in this file: panel 0 renders on
+     *  the visual *right*, i.e. the RTL inline-start side). `'start'` therefore
+     *  always resolves to index 0 and `'end'` to `panelCount - 1`, regardless
+     *  of `isRtl(this)` — consulting it here would swap collapse onto the
+     *  panel that visually sits at the *other* logical edge, which would be a
+     *  bug against this component's own RTL rendering, not a fix for one.
+     */
+    get collapsingIndex() {
+        if (this.collapse === 'none' || this.panelCount < 2)
+            return -1;
+        return this.collapse === 'start' ? 0 : this.panelCount - 1;
+    }
+    /** Whether a pane is actually collapsed (rail or floating) right now —
+     *  `false` whenever `collapse === 'none'`, since `collapseState` then
+     *  never leaves its `'wide'` default. */
+    get collapseActive() {
+        return this.collapsingIndex !== -1 && this.collapseState !== 'wide';
+    }
+    /** Dragging/keyboard-resizing is disabled on the one divider immediately
+     *  adjacent to the currently-collapsed pane (its other side has nothing
+     *  meaningful to resize against while the pane is rail/floating-width). */
+    isDividerDisabled(index) {
+        if (!this.collapseActive)
+            return false;
+        const adjacent = this.collapsingIndex === 0 ? 0 : this.panelCount - 2;
+        return index === adjacent;
+    }
+    /** Classifies a measured container width into the collapsing pane's
+     *  responsive state and, only on an actual transition, updates
+     *  `collapseState` and fires `lyra-split-collapse-change`. */
+    updateCollapseState(width) {
+        if (this.collapse === 'none')
+            return;
+        const next = width < this.floatBreakpoint ? 'floating' : width < this.railBreakpoint ? 'rail' : 'wide';
+        if (next === this.collapseState)
+            return;
+        this.collapseState = next;
+        this.emit('lyra-split-collapse-change', { state: next });
+    }
+    /** Creates (idempotently) and (re-)observes `[part="base"]` with the
+     *  collapse-state `ResizeObserver` — a no-op until `baseEl` exists (see
+     *  `firstUpdated()`/`connectedCallback()`). Mirrors lite-chart.ts's own
+     *  ResizeObserver setup, including reading the box size synchronously
+     *  once so the very first render doesn't sit at the stale `'wide'` default
+     *  until the (async) first callback fires — same rationale as
+     *  lyra-virtual-list's `containerResizeObserver` synchronous initial read. */
+    armCollapseObserver() {
+        if (!this.collapseResizeObserver) {
+            this.collapseResizeObserver = new ResizeObserver((entries) => {
+                const box = entries[0]?.contentBoxSize?.[0];
+                const width = box ? box.inlineSize : (this.baseEl?.getBoundingClientRect().width ?? 0);
+                this.updateCollapseState(width);
+            });
+        }
+        if (this.baseEl) {
+            this.collapseResizeObserver.observe(this.baseEl);
+            this.updateCollapseState(this.baseEl.clientWidth);
+        }
+    }
+    /** Reacts to a live `collapse` property change (as opposed to the
+     *  connect/first-render arming above): turns the observer on/off, and
+     *  resets `collapseState` back to its `'wide'` default when collapse is
+     *  switched off so no stale rail/floating styling survives it. */
+    syncCollapseObserver() {
+        if (this.collapse === 'none') {
+            this.collapseResizeObserver?.disconnect();
+            this.collapseState = 'wide';
+            return;
+        }
+        this.armCollapseObserver();
+    }
     /** Resolves panel `index`'s effective percent min/max for this clamp pass:
      *  a `panelConstraints` entry's px bound converted against the live
      *  `containerSize`, or the component's plain percent `min` (no upper
@@ -257,19 +427,98 @@ export class LyraSplit extends LyraElement {
     updated(changed) {
         if (changed.has('sizes') || this.sizes.length === 0)
             this.ensureSizes();
+        if (changed.has('collapse'))
+            this.syncCollapseObserver();
         const panels = [...this.children];
+        const current = new Set(panels);
+        // A panel that dropped out of the slot (removed from the light DOM)
+        // still carries whatever inline flex/order (and, while collapsing,
+        // position/inset/inline-size) this method last applied to it — clear
+        // those before that DOM node potentially gets reused elsewhere (e.g.
+        // re-slotted into another split/container).
+        for (const stale of this.stylizedPanels) {
+            if (!current.has(stale)) {
+                stale.style.removeProperty('flex');
+                stale.style.removeProperty('order');
+                stale.style.removeProperty('position');
+                stale.style.removeProperty('inset-block');
+                stale.style.removeProperty('inset-inline-start');
+                stale.style.removeProperty('inset-inline-end');
+                stale.style.removeProperty('inline-size');
+                delete stale.dataset.collapseState;
+            }
+        }
+        // Resolved once per pass rather than per panel: which physical index (if
+        // any) is actually collapsed right now — `-1` covers both `collapse ===
+        // 'none'` (the default) and a `collapse !== 'none'` pane that's still in
+        // its normal `'wide'` state, so every panel below falls straight through
+        // to the exact pre-existing (non-collapse) styling in either case.
+        const collapsingIndex = this.collapseActive ? this.collapsingIndex : -1;
         panels.forEach((panel, i) => {
             const percent = this.sizes[i] ?? 0;
             const constraint = this.panelConstraints[i];
-            // clamp() mixes units natively, so a constrained panel stays pinned
-            // between its px bounds across container resizes with no extra
-            // ResizeObserver — the browser re-evaluates it on every layout pass.
-            panel.style.flex =
-                constraint && (constraint.minPx != null || constraint.maxPx != null)
-                    ? `0 0 clamp(${constraint.minPx ?? NO_MIN_PX}px, ${percent}%, ${constraint.maxPx ?? NO_MAX_PX}px)`
-                    : `0 0 ${percent}%`;
+            // Collapse-only inline styles are always cleared first, then
+            // re-applied below only for the panel(s) that need them this pass —
+            // simpler than diffing which of the 5 properties changed.
+            panel.style.removeProperty('position');
+            panel.style.removeProperty('inset-block');
+            panel.style.removeProperty('inset-inline-start');
+            panel.style.removeProperty('inset-inline-end');
+            panel.style.removeProperty('inline-size');
+            if (collapsingIndex === i && this.collapseState === 'rail') {
+                // Fixed rail width instead of the normal clamp()/percent flex-basis.
+                panel.style.flex = `0 0 ${this.railWidth}`;
+            }
+            else if (collapsingIndex === i && this.collapseState === 'floating') {
+                // Lifted out of the flex flow entirely as an overlay card, anchored
+                // to its own logical start/end edge, spanning the full cross-axis
+                // extent — [part="base"] carries `position: relative` for this to
+                // anchor against (see split.styles.ts). Sized at its own normal
+                // percent width (i.e. what it would render at in the `'wide'`
+                // state), so there's no visual size jump the moment it un-floats.
+                panel.style.flex = 'none';
+                panel.style.position = 'absolute';
+                panel.style.setProperty('inset-block', '0');
+                panel.style.setProperty(collapsingIndex === 0 ? 'inset-inline-start' : 'inset-inline-end', '0');
+                panel.style.setProperty('inline-size', `${percent}%`);
+            }
+            else if (collapsingIndex !== -1 && i !== collapsingIndex) {
+                // The pane(s) sharing the split with a currently rail/floating
+                // collapsed pane: grow to fill whatever space that pane no longer
+                // occupies (its full percent-basis space while floating, or
+                // percent-basis-minus-railWidth while railed), proportionally to
+                // their own relative `sizes` share for a 3+-panel split.
+                panel.style.flex = `${percent} 1 0%`;
+            }
+            else {
+                // clamp() mixes units natively, so a constrained panel stays pinned
+                // between its px bounds across container resizes with no extra
+                // ResizeObserver — the browser re-evaluates it on every layout pass.
+                panel.style.flex =
+                    constraint && (constraint.minPx != null || constraint.maxPx != null)
+                        ? `0 0 clamp(${constraint.minPx ?? NO_MIN_PX}px, ${percent}%, ${constraint.maxPx ?? NO_MAX_PX}px)`
+                        : `0 0 ${percent}%`;
+            }
             panel.style.order = String(i * 2);
+            if (collapsingIndex === i) {
+                panel.dataset.collapseState = this.collapseState;
+            }
+            else {
+                delete panel.dataset.collapseState;
+            }
         });
+        this.stylizedPanels = current;
+        // Host-level marker (mirrors the per-panel `dataset.collapseState`
+        // above) for simple external CSS targeting of the whole component's
+        // current state, e.g. `lyra-split[data-collapse-state="rail"] + aside`.
+        // Absent whenever there's nothing collapsed to report (`collapse ===
+        // 'none'` or still `'wide'`), same as the per-panel marker.
+        if (collapsingIndex !== -1) {
+            this.setAttribute('data-collapse-state', this.collapseState);
+        }
+        else {
+            this.removeAttribute('data-collapse-state');
+        }
     }
     render() {
         const dividers = [];
@@ -278,6 +527,7 @@ export class LyraSplit extends LyraElement {
             // panels, not the whole track — pushing past it would starve a panel
             // further down the line even though this pair still has room.
             const valueMax = (this.sizes[i] ?? 0) + (this.sizes[i + 1] ?? 0) - this.min;
+            const disabled = this.isDividerDisabled(i);
             dividers.push(html `<div
         part="divider"
         role="separator"
@@ -286,7 +536,8 @@ export class LyraSplit extends LyraElement {
         aria-valuenow=${Math.round(this.sizes[i] ?? 0)}
         aria-valuemin=${this.min}
         aria-valuemax=${Math.round(valueMax)}
-        tabindex="0"
+        aria-disabled=${disabled ? 'true' : nothing}
+        tabindex=${disabled ? '-1' : '0'}
         style=${`order:${i * 2 + 1}`}
         @pointerdown=${(e) => this.onPointerDown(e, i)}
         @keydown=${(e) => this.onDividerKeyDown(e, i)}
@@ -310,7 +561,25 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], LyraSplit.prototype, "panelConstraints", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraSplit.prototype, "collapse", void 0);
+__decorate([
+    property({ attribute: 'rail-width' })
+], LyraSplit.prototype, "railWidth", void 0);
+__decorate([
+    property({ type: Number, attribute: 'rail-breakpoint' })
+], LyraSplit.prototype, "railBreakpoint", void 0);
+__decorate([
+    property({ type: Number, attribute: 'float-breakpoint' })
+], LyraSplit.prototype, "floatBreakpoint", void 0);
 __decorate([
     state()
 ], LyraSplit.prototype, "panelCount", void 0);
+__decorate([
+    state()
+], LyraSplit.prototype, "collapseState", void 0);
+__decorate([
+    query('[part="base"]')
+], LyraSplit.prototype, "baseEl", void 0);
 defineElement('split', LyraSplit);

package/dist/components/split/split.styles.js

@@ -7,6 +7,9 @@ export const styles = css `
   }
   [part='base'] {
     display: flex;
+    /* Anchor for the 'floating' collapse state's absolutely-positioned
+       overlay panel (set inline by split.ts's updated()). */
+    position: relative;
     inline-size: 100%;
     block-size: 100%;
   }
@@ -48,4 +51,31 @@ export const styles = css `
     outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
     outline-offset: var(--lyra-focus-ring-offset);
   }
+  /* The divider adjacent to a rail/floating-collapsed pane (see split.ts's
+     isDividerDisabled()) — geometry (position/inset/inline-size) for the
+     collapsing panel itself is set inline by updated(), same as the
+     pre-existing flex/order styling; this only covers the divider's own
+     drag/hover affordance and the floating panel's elevation, which read
+     more naturally as stylesheet rules than one-off inline styles. */
+  [part='divider'][aria-disabled='true'] {
+    cursor: default;
+    pointer-events: none;
+  }
+  /* The 'floating' collapse state's overlay "card" look -- geometry
+     (position/inset-*/inline-size) is set inline by split.ts's updated(),
+     matching how the ordinary flex/order styling is applied; only the
+     visual/stacking treatment lives here. */
+  ::slotted([data-collapse-state='floating']) {
+    z-index: 1;
+    background: var(--lyra-color-surface);
+    border-radius: var(--lyra-radius);
+    box-shadow: var(--lyra-shadow);
+  }
+  /* Rail-clamped content can easily overflow the fixed rail-width — clip it
+     rather than letting it blow out the layout; the panel's own content is
+     expected to adapt to the narrower width itself (e.g. via a container
+     query), this is just a safety net. */
+  ::slotted([data-collapse-state='rail']) {
+    overflow: hidden;
+  }
 `;

package/dist/components/stat/stat.d.ts

@@ -5,6 +5,10 @@ export type StatGoodDirection = 'up' | 'down';
 export interface StatRow {
     label: string;
     value: string;
+    /** Exact value shown as a hover/focus tooltip on this row's `row-value` (mirrors the headline
+     *  `exactValue`/`exact-value` behavior). Also makes this row's `[part='row-value']`
+     *  keyboard-focusable so the tooltip is reachable without a pointer. */
+    exactValue?: string;
 }
 /**
  * `<lyra-stat>` — a KPI/stat card. First-party invention consolidating the
@@ -15,6 +19,7 @@ export interface StatRow {
  * @slot caption - Rich caption content (overrides the `caption` attribute).
  * @slot spark - A sparkline (e.g. `<lyra-sparkline>`) or other compact trend
  *   visual. `lyra-stat` only reserves the slot; it doesn't render one itself.
+ * @slot sub - Rich sub-line content (overrides the `sub` attribute).
  * @csspart base - The component's root wrapper.
  * @csspart icon - Container for the leading icon slot.
  * @csspart label - The label text.
@@ -22,12 +27,14 @@ export interface StatRow {
  * @csspart value - The value text.
  * @csspart unit - The unit text.
  * @csspart trend - The trend pill.
+ * @csspart sub - Container for the `sub` attribute/slot.
  * @csspart spark - Container for the `spark` slot.
  * @csspart caption - Container for the caption attribute/slot.
  * @csspart rows - Container for the `rows` breakdown list.
  * @csspart row - A single breakdown row (one per `rows` entry).
  * @csspart row-label - The label text of a breakdown row.
- * @csspart row-value - The value text of a breakdown row.
+ * @csspart row-value - The value text of a breakdown row. Shows the row's `exactValue` (if any) as
+ *   a hover/focus tooltip, same as the headline `value`.
  */
 export declare class LyraStat extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -46,13 +53,27 @@ export declare class LyraStat extends LyraElement {
      *  the status `variant`; see the `[part='value']` selector below for how
      *  the two combine. */
     emphasis: boolean;
+    /** Exact value shown as a hover/focus tooltip on the headline `value` (e.g. `value="$1.2K"
+     *  exact-value="$1,204.37"`). Also makes `[part='value']` keyboard-focusable so the tooltip is
+     *  reachable without a pointer. */
+    exactValue: string;
+    /** A secondary line distinct from `caption` (e.g. a comparison-period label), rendered between the
+     *  trend pill and the caption. */
+    sub: string;
+    /** Renders `value` as smaller/lighter prose (e.g. a loading/status message) instead of the bold
+     *  numeric headline style, and hides `unit`. */
+    prose: boolean;
+    /** Tighter padding for constrained spaces — same convention as `lyra-empty`'s `compact`. */
+    compact: boolean;
     private hasIcon;
     private hasCaptionSlot;
     private hasSparkSlot;
+    private hasSubSlot;
     protected willUpdate(): void;
     private onIconSlotChange;
     private onCaptionSlotChange;
     private onSparkSlotChange;
+    private onSubSlotChange;
     render(): TemplateResult;
 }
 declare global {

package/dist/components/stat/stat.js

@@ -20,6 +20,7 @@ import { styles } from './stat.styles.js';
  * @slot caption - Rich caption content (overrides the `caption` attribute).
  * @slot spark - A sparkline (e.g. `<lyra-sparkline>`) or other compact trend
  *   visual. `lyra-stat` only reserves the slot; it doesn't render one itself.
+ * @slot sub - Rich sub-line content (overrides the `sub` attribute).
  * @csspart base - The component's root wrapper.
  * @csspart icon - Container for the leading icon slot.
  * @csspart label - The label text.
@@ -27,12 +28,14 @@ import { styles } from './stat.styles.js';
  * @csspart value - The value text.
  * @csspart unit - The unit text.
  * @csspart trend - The trend pill.
+ * @csspart sub - Container for the `sub` attribute/slot.
  * @csspart spark - Container for the `spark` slot.
  * @csspart caption - Container for the caption attribute/slot.
  * @csspart rows - Container for the `rows` breakdown list.
  * @csspart row - A single breakdown row (one per `rows` entry).
  * @csspart row-label - The label text of a breakdown row.
- * @csspart row-value - The value text of a breakdown row.
+ * @csspart row-value - The value text of a breakdown row. Shows the row's `exactValue` (if any) as
+ *   a hover/focus tooltip, same as the headline `value`.
  */
 export class LyraStat extends LyraElement {
     constructor() {
@@ -52,12 +55,25 @@ export class LyraStat extends LyraElement {
          *  the status `variant`; see the `[part='value']` selector below for how
          *  the two combine. */
         this.emphasis = false;
+        /** Exact value shown as a hover/focus tooltip on the headline `value` (e.g. `value="$1.2K"
+         *  exact-value="$1,204.37"`). Also makes `[part='value']` keyboard-focusable so the tooltip is
+         *  reachable without a pointer. */
+        this.exactValue = '';
+        /** A secondary line distinct from `caption` (e.g. a comparison-period label), rendered between the
+         *  trend pill and the caption. */
+        this.sub = '';
+        /** Renders `value` as smaller/lighter prose (e.g. a loading/status message) instead of the bold
+         *  numeric headline style, and hides `unit`. */
+        this.prose = false;
+        /** Tighter padding for constrained spaces — same convention as `lyra-empty`'s `compact`. */
+        this.compact = false;
         // Same fix `lyra-empty` already established: `[part]:empty` never matches
         // because the part always contains a literal `<slot>` child. Track real
         // slot assignment in JS instead.
         this.hasIcon = false;
         this.hasCaptionSlot = false;
         this.hasSparkSlot = false;
+        this.hasSubSlot = false;
         this.onIconSlotChange = (e) => {
             this.hasIcon = e.target.assignedElements({ flatten: true }).length > 0;
         };
@@ -67,6 +83,9 @@ export class LyraStat extends LyraElement {
         this.onSparkSlotChange = (e) => {
             this.hasSparkSlot = e.target.assignedElements({ flatten: true }).length > 0;
         };
+        this.onSubSlotChange = (e) => {
+            this.hasSubSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
     }
     static { this.styles = [LyraElement.styles, styles, srOnly]; }
     willUpdate() {
@@ -74,6 +93,7 @@ export class LyraStat extends LyraElement {
             this.hasIcon = Array.from(this.children).some((el) => !el.hasAttribute('slot'));
             this.hasCaptionSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'caption');
             this.hasSparkSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'spark');
+            this.hasSubSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'sub');
         }
     }
     render() {
@@ -86,6 +106,7 @@ export class LyraStat extends LyraElement {
         // [part='trend'].
         const arrow = rawDirection === 'flat' ? '–' : chevronIcon();
         const hasCaption = this.hasCaptionSlot || this.caption.length > 0;
+        const hasSub = this.hasSubSlot || this.sub.length > 0;
         // The visible pill only ever shows the icon rotation + color to convey
         // direction and good/bad polarity; both are invisible to screen readers,
         // so mirror them into a plain-language sr-only announcement.
@@ -99,7 +120,9 @@ export class LyraStat extends LyraElement {
         ></span>
         <span part="label">${this.label}</span>
         <div part="value-row">
-          <span part="value">${this.value}</span>
+          <span part="value" title=${this.exactValue || nothing} tabindex=${this.exactValue ? '0' : nothing}
+            >${this.value}</span
+          >
           <span part="unit">${this.unit}</span>
         </div>
         ${hasTrend
@@ -112,6 +135,9 @@ export class LyraStat extends LyraElement {
               <span class="sr-only">${trendAnnouncement}</span>
             </span>`
             : nothing}
+        <div part="sub" ?hidden=${!hasSub}>
+          ${this.sub}<slot name="sub" @slotchange=${this.onSubSlotChange}></slot>
+        </div>
         <div part="spark" ?hidden=${!this.hasSparkSlot}>
           <slot name="spark" @slotchange=${this.onSparkSlotChange}></slot>
         </div>
@@ -122,7 +148,12 @@ export class LyraStat extends LyraElement {
           ${this.rows.map((row) => html `
               <div part="row">
                 <span part="row-label">${row.label}</span>
-                <span part="row-value">${row.value}</span>
+                <span
+                  part="row-value"
+                  title=${row.exactValue || nothing}
+                  tabindex=${row.exactValue ? '0' : nothing}
+                  >${row.value}</span
+                >
               </div>
             `)}
         </div>
@@ -157,6 +188,18 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraStat.prototype, "emphasis", void 0);
+__decorate([
+    property({ attribute: 'exact-value' })
+], LyraStat.prototype, "exactValue", void 0);
+__decorate([
+    property()
+], LyraStat.prototype, "sub", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraStat.prototype, "prose", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraStat.prototype, "compact", void 0);
 __decorate([
     state()
 ], LyraStat.prototype, "hasIcon", void 0);
@@ -166,4 +209,7 @@ __decorate([
 __decorate([
     state()
 ], LyraStat.prototype, "hasSparkSlot", void 0);
+__decorate([
+    state()
+], LyraStat.prototype, "hasSubSlot", void 0);
 defineElement('stat', LyraStat);