@aceshooting/lyra-ui 1.2.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
@@ -29,7 +33,8 @@ export interface StatRow {
  * @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[];

package/dist/components/stat/stat.js

@@ -34,7 +34,8 @@ import { styles } from './stat.styles.js';
  * @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() {
@@ -147,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>

package/dist/components/stream-status/stream-status.d.ts

@@ -0,0 +1,110 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../live-region/live-region.js';
+export type StreamStatusPhase = 'idle' | 'connecting' | 'streaming' | 'stalled';
+/**
+ * `<lyra-stream-status>` — a compact status indicator for a single streaming
+ * connection (SSE, WebSocket, long-poll, …), with built-in heartbeat-aware
+ * stall detection.
+ *
+ * The host drives `phase` directly for `idle`/`connecting`/`streaming`, and
+ * calls `recordActivity()` on every *semantic* frame received while
+ * streaming — a real content chunk, never a transport-level keep-alive ping.
+ * This component has no payload-inspection logic of its own: "ignore
+ * heartbeats" is entirely a call-site discipline — the host simply never
+ * calls `recordActivity()` for a ping, so pings never reset the stall timer
+ * and a connection that's only sending keep-alives (no real content) for
+ * longer than `stall-threshold-ms` correctly reads as stalled.
+ *
+ * Internally, an inactivity timer runs only while `phase === 'streaming'`.
+ * It's (re)armed whenever the phase transitions to `'streaming'` (directly,
+ * or via `recordActivity()` recovering from `'stalled'`) and on every
+ * subsequent `recordActivity()` call while already streaming; it's disarmed
+ * the instant `phase` becomes anything else, including a host-driven
+ * reassignment away from `'streaming'` — so a stale timer can never fire a
+ * stall transition after the host has already moved on. If it ever fires,
+ * `phase` becomes `'stalled'` and `lyra-stall` is dispatched.
+ *
+ * `phase` remains a fully public, directly settable property at all times —
+ * a host can assign `'stalled'` (or any other phase) itself as a manual
+ * override, and this component never fights that assignment. `lyra-stall`/
+ * `lyra-recover` fire on *any* transition into/out of `'stalled'`
+ * respectively, whether timer-driven or host-driven, and never for a
+ * reassignment to the same value (Lit's default `hasChanged` already skips a
+ * no-op set, same as every other reflected `@property` in this library).
+ * Like `<lyra-chat-message>`'s `status`, whatever phase this element happens
+ * to *mount* with is never itself treated as an eventful transition — only a
+ * later change fires an event or an announcement.
+ *
+ * Accessibility: phase transitions into/out of `'stalled'` are announced
+ * through an internal `<lyra-live-region>` (see that component for the
+ * throttled/coalesced-announcement machinery this composes) rather than a
+ * hand-rolled `aria-live` region. `recordActivity()` itself never announces
+ * anything, no matter how often the host calls it — only the *transition*
+ * announces, exactly once per transition, which is the entire point of
+ * routing through the throttled announcer instead of writing to a live
+ * region on every call. Entering `'stalled'` announces with `mode="assertive"`
+ * (a stall can need the user's attention, e.g. before they give up and
+ * navigate away); recovering back out of `'stalled'` announces with
+ * `mode="polite"` (good news doesn't need to interrupt). The decorative
+ * indicator dot is `aria-hidden` — it's a color/motion cue only, never the
+ * sole carrier of state.
+ *
+ * Visual: `'stalled'` is styled as a warning, not a danger — a stall is
+ * usually recoverable (the stream may resume on its own, or the host's own
+ * retry logic may kick in), so treating it as an actionable warning rather
+ * than a hard failure keeps the tone proportionate. A host that wants to
+ * escalate to danger styling after N stalls can scope its own CSS off
+ * `[phase="stalled"]`, or simply stop rendering this component and show its
+ * own danger-styled error state instead.
+ *
+ * @customElement lyra-stream-status
+ * @slot - Custom copy shown only while `phase="stalled"` (e.g. "Taking longer than usual…"). A sensible built-in default is used when nothing is slotted.
+ * @slot actions - A stop/retry button row. Always present in the template regardless of `phase` — visibility is driven purely by whether anything is slotted, not by `phase`; what to put here, and when, is entirely the host's call.
+ * @event lyra-stall - Fired whenever `phase` transitions into `'stalled'` from anything else (timer-driven, or a direct host assignment).
+ * @event lyra-recover - Fired whenever `phase` transitions out of `'stalled'` to anything else (via `recordActivity()`, or a direct host assignment).
+ * @csspart base - The root layout container.
+ * @csspart indicator - The decorative (`aria-hidden`) status dot.
+ * @csspart message - Wrapper around the default slot; only rendered while `phase="stalled"`.
+ * @csspart actions - Wrapper around the `actions` slot.
+ */
+export declare class LyraStreamStatus extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Current connection phase. Settable directly by the host at any time —
+     *  see the class doc for how that interacts with the internal stall timer. */
+    phase: StreamStatusPhase;
+    /** How long `phase` may stay `'streaming'` with no `recordActivity()` call
+     *  before this component declares it stalled. */
+    stallThresholdMs: number;
+    private stallTimer?;
+    private hasActionsSlot;
+    private liveRegion?;
+    protected willUpdate(): void;
+    protected updated(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    /**
+     * Call on every semantic (non-heartbeat) frame received while streaming.
+     * - While `phase === 'streaming'`: (re)arms the stall timer, pushing the
+     *   stall deadline `stall-threshold-ms` further out.
+     * - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'`
+     *   again, `lyra-recover` fires, and the stall timer is armed fresh (same
+     *   as the bullet above), all via the same `updated()` transition handling
+     *   a direct host assignment would also go through.
+     * - While `phase` is `'idle'` or `'connecting'`: a no-op. A host may call
+     *   this defensively before formally flipping to `'streaming'`; it must
+     *   never throw or start a timer early.
+     */
+    recordActivity(): void;
+    private onPhaseChanged;
+    private armStallTimer;
+    private disarmStallTimer;
+    private announceTransition;
+    private hasSlotted;
+    private onActionsSlotChange;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-stream-status': LyraStreamStatus;
+    }
+}