@zeyos/zx 4.4.0 → 5.0.0

package/src/components/select/select.js

@@ -3,8 +3,12 @@ import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
 import { typeahead } from '../../core/keyboard.js';
 import { position } from '../../core/position.js';
-import { isCssColor, uid } from '../../core/util.js';
+import { uid } from '../../core/util.js';
+import { itemColor } from './color.js';
 import { matchItems } from './filter.js';
+import {
+  DEFAULT_STATUSES, STATUS_INDICATORS, STATUS_TONES, normalizePriorityLevel, priorityIcon, statusIcon
+} from './glyphs.js';
 
 /** @typedef {string|number|boolean|symbol|bigint|null|undefined} Primitive */
 /** @typedef {Record<string, any>|Primitive} SelectItem */
@@ -49,7 +53,9 @@ import { matchItems } from './filter.js';
  * @property {string} [recentLabel='Recent'] Heading above recent choices.
  * @property {boolean|SelectAction} [create=false] Optional create command at the bottom.
  * @property {string|((item: SelectItem)=>unknown)} [iconKey='icon'] Item icon reader.
- * @property {string|((item: SelectItem)=>unknown)} [colorKey='color'] Optional icon colour reader.
+ * @property {string|((item: SelectItem)=>unknown)} [colorKey='color'] Optional icon colour reader: a CSS
+ * colour or a token reference such as `var(--zx-color-tone-blue-fg)`. Without one the glyph is a
+ * neutral tile in muted ink.
  * @property {string|((item: SelectItem)=>unknown)} [subtitleKey='description'] Secondary-text reader.
  * @property {((item: SelectItem, context:{selected:boolean})=>Node|string|null)|null} [renderIcon=null] Entity icon renderer.
  */
@@ -69,18 +75,6 @@ const PRIORITY_KEYS = [
 ];
 const PRIORITY_FALLBACKS = ['Lowest', 'Low', 'Medium', 'High', 'Highest'];
 
-const DEFAULT_STATUSES = Object.freeze([
-  ['backlog', 'status.backlog', 'Backlog', 'dotted', 'muted'],
-  ['todo', 'status.todo', 'Todo', 'ring', 'neutral'],
-  ['in-progress', 'status.inProgress', 'In Progress', 'progress', 'warning'],
-  ['in-review', 'status.inReview', 'In Review', 'review', 'info'],
-  ['ready', 'status.ready', 'Ready to Merge', 'ready', 'accent'],
-  ['waiting', 'status.waiting', 'Waiting for feedback', 'waiting', 'warning'],
-  ['done', 'status.done', 'Done', 'done', 'info'],
-  ['canceled', 'status.canceled', 'Canceled', 'canceled', 'muted'],
-  ['duplicate', 'status.duplicate', 'Duplicate', 'duplicate', 'muted']
-]);
-
 /**
  * APG editable combobox with optional local or asynchronous filtering.
  *
@@ -125,7 +119,7 @@ export class Select extends Component {
   render() {
     // Instance state initialized here because render() runs inside the base
     // constructor, before class-field initializers would run (and clobber it).
-    this._items = []; this._visibleItems = []; this._fixedItems = []; this._visibleFixed = []; this._actions = []; this._selected = null; this._optionEntries = []; this._activeIndex = -1; this._open = false; this._disabled = false; this._loading = false; this._requestSequence = 0; this._queryTimer = null; this._position = null; this._createdRoot = false; this._root = null; this._snapshot = null;
+    this._items = []; this._visibleItems = []; this._fixedItems = []; this._visibleFixed = []; this._actions = []; this._selected = null; this._optionEntries = []; this._activeIndex = -1; this._open = false; this._disabled = false; this._loading = false; this._requestSequence = 0; this._queryTimer = null; this._position = null; this._createdRoot = false; this._root = null; this._snapshot = null; this._pointerModality = false;
     this._createdRoot = this.el === null;
     const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
     this.el = root;
@@ -209,7 +203,22 @@ export class Select extends Component {
 
     this.listen(input, 'click', () => this.open());
     this.listen(input, 'input', () => this._onInput());
-    this.listen(input, 'keydown', (event) => this._onKeydown(/** @type {KeyboardEvent} */ (event)));
+    this.listen(input, 'keydown', (event) => {
+      if (!isModifierKey(/** @type {KeyboardEvent} */ (event))) root.removeAttribute('data-focus-origin');
+      this._onKeydown(/** @type {KeyboardEvent} */ (event));
+    });
+    // A text input matches :focus-visible however it was focused, read-only or not, so a click on
+    // a read-only Select would draw the keyboard ring. Track how the user last interacted and mark
+    // a pointer focus; the ring then follows keyboard focus only, and returns on the first key.
+    this.listen(input, 'focus', () => {
+      if (this._pointerModality && /** @type {HTMLInputElement} */ (input).readOnly) {
+        root.setAttribute('data-focus-origin', 'pointer');
+      } else root.removeAttribute('data-focus-origin');
+    });
+    this.listen(input, 'blur', () => root.removeAttribute('data-focus-origin'));
+    this.listen(document, 'keydown', (event) => {
+      if (!isModifierKey(/** @type {KeyboardEvent} */ (event))) this._pointerModality = false;
+    }, { capture: true });
     this.listen(toggle, 'click', () => {
       this.focus();
       if (this._open) this.close();
@@ -222,6 +231,7 @@ export class Select extends Component {
     this.listen(panel, 'pointerdown', (event) => event.preventDefault());
     this.listen(panel, 'click', (event) => this._onOptionClick(event));
     this.listen(document, 'pointerdown', (event) => {
+      this._pointerModality = true;
       if (this._open && !root.contains(/** @type {Node} */ (event.target))) this.close();
     }, { capture: true });
 
@@ -381,26 +391,44 @@ export class Select extends Component {
   }
 
   /**
-   * Creates the five-level priority preset.
+   * Creates the five-level priority preset: values 0 (lowest) to 4 (highest), each drawn as grey
+   * signal bars filled to its level, except the highest, which is the one coloured level — a
+   * danger square with an exclamation mark. A "No priority" row (value null, a row of dashes)
+   * heads the list and labels the empty control; `clearable: false` removes it.
    * @param {Element|string|null} target Component target.
-   * @param {SelectOptions} [options={}] Select overrides other than fixed items and renderer.
+   * @param {SelectOptions} [options={}] Select overrides other than items and renderers.
+   *   `clearable` defaults to true here; `noneLabel` and `placeholder` default to the
+   *   `priority.none` message ("No priority").
    * @returns {Select}
    */
   static priority(target, options = {}) {
     const requestedValue = options.value ?? null;
-    const select = new Select(target, {
+    const clearable = options.clearable ?? true;
+    /** @type {Select|null} */
+    let select = null;
+    // The constructor renders the list once before `select` is assigned; the label is settled by
+    // the setItems() below, which renders it again.
+    const noneLabel = () => options.noneLabel
+      ?? (select ? select._message('priority.none', 'No priority') : 'No priority');
+    select = new Select(target, {
       ...options,
+      clearable,
       value: null,
       items: [],
       renderItem(item) {
         return priorityContent(item, true);
       },
+      renderNone: options.renderNone ?? (() => priorityContent({ level: null, name: noneLabel() }, true)),
       renderValueAdornment(item) { return priorityIndicator(item.level); }
     });
+    if (clearable && !options.placeholder) {
+      /** @type {HTMLInputElement} */ (select.refs.input).placeholder = noneLabel();
+    }
+    const preset = select;
     select.setItems(PRIORITY_KEYS.map((key, level) => {
-      let name = level === 2 ? select.msg('priority.medium') : key;
-      if (name === 'priority.medium') name = select._message(key, PRIORITY_FALLBACKS[level]);
-      else if (level !== 2) name = select._message(key, PRIORITY_FALLBACKS[level]);
+      let name = level === 2 ? preset.msg('priority.medium') : key;
+      if (name === 'priority.medium') name = preset._message(key, PRIORITY_FALLBACKS[level]);
+      else if (level !== 2) name = preset._message(key, PRIORITY_FALLBACKS[level]);
       return { ID: level, name, level };
     }));
     select.set(requestedValue, { silent: true });
@@ -453,10 +481,10 @@ export class Select extends Component {
       const value = readSelectItem(item, iconKey);
       if (value && typeof value === 'object' && typeof value.nodeType === 'number') return value.cloneNode(true);
       if (typeof value !== 'string' || !value) return null;
-      const color = readSelectItem(item, colorKey);
+      const color = itemColor(readSelectItem(item, colorKey));
       return h('span', {
         class: 'zx-select__entity-glyph',
-        style: isCssColor(color) ? { '--zx-select-entity-color': String(color) } : null,
+        style: color ? { '--zx-select-entity-color': color } : null,
         ariaHidden: 'true'
       }, icon(value, { size: 14 }));
     };
@@ -992,28 +1020,26 @@ function priorityContent(item, label) {
     label ? h('span', {}, String(item.name)) : null);
 }
 
-/** @param {unknown} level @returns {Node} */
+/**
+ * The priority glyph `priorityIcon()` draws, carrying the Select's own class as well so styles
+ * written against it keep applying.
+ * @param {unknown} level Priority level 0–4, or null for none.
+ * @returns {Node}
+ */
 function priorityIndicator(level) {
-  const normalized = Math.max(0, Math.min(4, Math.trunc(Number(level) || 0)));
-  return h('span', {
-    class: 'zx-select__priority-icon',
-    dataset: { level: normalized },
-    ariaHidden: 'true'
-  }, Array.from({ length: 5 }, (_, index) => h('span', {
-    dataset: { filled: String(index <= normalized) }
-  })));
+  const glyph = priorityIcon(/** @type {number|null} */ (normalizePriorityLevel(level)));
+  glyph.classList.add('zx-select__priority-icon');
+  return glyph;
 }
 
 /** @param {unknown} input @returns {Record<string, any>|null} */
 function normalizeStatusItem(input) {
   if (!input || typeof input !== 'object' || input.ID == null || input.name == null) return null;
-  const indicators = ['dotted', 'ring', 'progress', 'review', 'ready', 'waiting', 'done', 'canceled', 'duplicate'];
-  const tones = ['muted', 'neutral', 'warning', 'info', 'accent', 'success', 'danger'];
   return {
     ...input,
     name: String(input.name),
-    indicator: indicators.includes(String(input.indicator)) ? String(input.indicator) : 'ring',
-    tone: tones.includes(String(input.tone)) ? String(input.tone) : 'muted',
+    indicator: STATUS_INDICATORS.includes(String(input.indicator)) ? String(input.indicator) : 'ring',
+    tone: STATUS_TONES.includes(String(input.tone)) ? String(input.tone) : 'muted',
     description: input.description == null ? '' : String(input.description),
     shortcut: input.shortcut == null ? '' : String(input.shortcut)
   };
@@ -1029,17 +1055,16 @@ function statusContent(item) {
     item.shortcut ? h('kbd', { class: 'zx-select__status-shortcut' }, item.shortcut) : null);
 }
 
-/** @param {Record<string, any>} item @returns {Node} */
+/**
+ * The status glyph `statusIcon()` draws for a settled status item, carrying the Select's own class
+ * as well so styles written against it keep applying.
+ * @param {Record<string, any>} item Normalized status item.
+ * @returns {Node}
+ */
 function statusIndicator(item) {
-  const indicator = String(item.indicator ?? 'ring');
-  const marker = h('span', {
-    class: 'zx-select__status-indicator',
-    dataset: { indicator, tone: String(item.tone ?? 'muted') },
-    ariaHidden: 'true'
-  });
-  if (indicator === 'done') marker.append(icon('check', { size: 8 }));
-  if (indicator === 'canceled') marker.append(icon('x', { size: 7 }));
-  return marker;
+  const glyph = statusIcon({ indicator: item.indicator ?? 'ring', tone: item.tone ?? 'muted' });
+  glyph.classList.add('zx-select__status-indicator');
+  return glyph;
 }
 
 /** Change emitted when the selected value changes. @event Select#change @type {CustomEvent<SelectChangeDetail>} */
@@ -1061,6 +1086,17 @@ function readItem(item, reader) {
   return item[reader];
 }
 
+/**
+ * Reports a key press that says nothing about how the user is moving focus: a lone modifier, or a
+ * shortcut chord the page or the browser handles.
+ * @param {KeyboardEvent} event Key event.
+ * @returns {boolean}
+ */
+function isModifierKey(event) {
+  return ['Shift', 'Control', 'Alt', 'Meta', 'CapsLock'].includes(event.key)
+    || event.ctrlKey || event.metaKey;
+}
+
 /** @param {KeyboardEvent} event @returns {boolean} */
 function isPrintable(event) {
   return event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;

package/src/components/sheet/sheet.css

@@ -57,8 +57,8 @@
   inset-block-start: 0;
   inset-block-end: auto;
   border-block-end: 1px solid var(--zx-color-overlay-border);
-  border-end-start-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
-  border-end-end-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  border-end-start-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
+  border-end-end-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
   --zx-sheet-enter: 0 -100%;
 }
 
@@ -66,8 +66,8 @@
   inset-block-start: auto;
   inset-block-end: 0;
   border-block-start: 1px solid var(--zx-color-overlay-border);
-  border-start-start-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
-  border-start-end-radius: var(--zx-sheet-radius, var(--zx-radius-xl));
+  border-start-start-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
+  border-start-end-radius: var(--zx-sheet-radius, var(--zx-radius-lg));
   --zx-sheet-enter: 0 100%;
 }
 
@@ -105,11 +105,14 @@
  * `display: none` immediately — so `display` and `overlay` transition with `allow-discrete`, which
  * defers the discrete jump until the rest of the transition has finished. `@starting-style` gives
  * the entry its from-state. Where either is unsupported the sheet simply appears and disappears.
+ *
+ * The slide runs on the drawer curve — most of the distance at once, then a settle — while the
+ * fade keeps the ordinary ease, so the panel arrives decisively without flashing in.
  */
 @media (prefers-reduced-motion: no-preference) {
   .zx-sheet {
     transition:
-      translate var(--zx-dur-base) var(--zx-ease),
+      translate var(--zx-dur-base) var(--zx-ease-drawer),
       opacity var(--zx-dur-base) var(--zx-ease),
       display var(--zx-dur-base) allow-discrete,
       overlay var(--zx-dur-base) allow-discrete;
@@ -193,7 +196,7 @@
 @media (prefers-reduced-motion: no-preference) {
   .zx-sheet[data-docked] {
     transition:
-      flex-basis var(--zx-dur-base) var(--zx-ease),
+      flex-basis var(--zx-dur-base) var(--zx-ease-drawer),
       opacity var(--zx-dur-base) var(--zx-ease),
       display var(--zx-dur-base) allow-discrete,
       overlay var(--zx-dur-base) allow-discrete;
@@ -363,8 +366,8 @@
 @media (prefers-reduced-motion: no-preference) {
   .zx-sheet[data-stack] {
     transition:
-      transform var(--zx-dur-base) var(--zx-ease),
-      translate var(--zx-dur-base) var(--zx-ease),
+      transform var(--zx-dur-base) var(--zx-ease-drawer),
+      translate var(--zx-dur-base) var(--zx-ease-drawer),
       opacity var(--zx-dur-base) var(--zx-ease),
       display var(--zx-dur-base) allow-discrete,
       overlay var(--zx-dur-base) allow-discrete;

package/src/components/slider/slider.css

@@ -147,17 +147,31 @@
   font-variant-numeric: tabular-nums;
 }
 
+/*
+ * A mark sits under the thumb's centre at its value — half a thumb in from either end of the rail
+ * — and centres its label there, except that a label is never pushed past either end of the
+ * track: the outermost ones end flush with it instead of spilling out of the component.
+ * `--zx-slider-mark` is the value's position on the scale, from 0 to 1.
+ */
 .zx-slider__marks {
   position: relative;
+  inline-size: 100%;
   block-size: var(--zx-space-5);
   margin-block-start: var(--zx-space-1);
+  container-type: inline-size;
 }
 
 .zx-slider__mark {
+  --zx-slider-mark-at: calc(var(--zx-slider-thumb) / 2
+    + (100cqi - var(--zx-slider-thumb)) * var(--zx-slider-mark, 0));
   position: absolute;
   inset-block-start: 0;
-  inset-inline-start: var(--zx-slider-mark, 0%);
-  transform: translateX(-50%);
+  inset-inline-start: var(--zx-slider-mark-at);
+  transform: translateX(clamp(
+    -1 * var(--zx-slider-mark-at),
+    -50%,
+    100cqi - var(--zx-slider-mark-at) - 100%
+  ));
   color: var(--zx-color-text-muted);
   font-size: var(--zx-text-xs);
   white-space: nowrap;

package/src/components/slider/slider.js

@@ -279,7 +279,7 @@ export class Slider extends Component {
       const label = typeof mark === 'number' ? this._format(value) : String(mark.label ?? this._format(value));
       element.append(h('span', {
         class: 'zx-slider__mark',
-        style: { '--zx-slider-mark': `${this._ratio(value) * 100}%` }
+        style: { '--zx-slider-mark': String(this._ratio(value)) }
       }, label));
     }
     return element;

package/src/components/sort-control/sort-control.css

@@ -10,8 +10,11 @@
 .zx-sort-control__direction {
   inline-size: var(--zx-control-height);
   padding: 0;
-  border-radius: var(--zx-radius-full);
+  border-radius: var(--zx-control-radius);
 }
 
 .zx-sort-control__direction:focus-visible { box-shadow: var(--zx-focus-ring); }
+/* The arrow is the current direction, not decoration, so it keeps the text colour a ghost glyph
+   would otherwise give up. */
+.zx-sort-control .zx-sort-control__direction > .zx-icon { color: var(--zx-color-text); }
 .zx-sort-control .zx-select__control { background: var(--zx-color-bg-control); }

package/src/components/stat-tile/stat-tile.css

@@ -1,14 +1,17 @@
 /*
- * The tile is a size ladder, not a colour: the value is the loudest thing on it, the label is
- * small above it, and the delta and sparkline are quieter than both. `kind` tints the icon and
- * the sparkline only — never the value, which has to stay at full text contrast whatever intent
- * a server assigns the metric.
+ * The tile is a size ladder, not a colour: the value is the loudest thing on it, the label is a
+ * quiet sentence-case line above it, and the caption, delta and sparkline are quieter than both.
+ * The icon is a muted glyph, not a coloured chip. `kind` tints the sparkline only — never the
+ * value, which has to stay at full text contrast whatever intent a server assigns the metric.
+ *
+ * A column, with the sparkline pushed to the foot: tiles in one row are as tall as the tallest,
+ * so their labels, values and sparklines line up whether or not each tile has every part.
  */
 .zx-stat-tile {
   --zx-stat-tile-value-size: var(--zx-text-2xl);
-  display: grid;
-  gap: var(--zx-space-2);
-  align-content: start;
+  display: flex;
+  flex-direction: column;
+  gap: var(--zx-space-1);
   min-inline-size: 0;
   padding: var(--zx-space-4);
   border: 1px solid var(--zx-color-border);
@@ -60,25 +63,19 @@ button.zx-stat-tile:focus-visible {
 .zx-stat-tile__label {
   min-inline-size: 0;
   overflow: hidden;
-  font-size: var(--zx-text-xs);
-  font-weight: 600;
-  letter-spacing: 0.04em;
+  font-size: var(--zx-text-sm);
+  font-weight: var(--zx-weight-medium);
   line-height: 1.4;
-  text-transform: uppercase;
   text-overflow: ellipsis;
   white-space: nowrap;
   color: var(--zx-color-text-muted);
 }
 
 .zx-stat-tile__icon {
-  display: grid;
+  display: inline-grid;
   flex: none;
   place-items: center;
-  inline-size: 1.75rem;
-  block-size: 1.75rem;
-  border-radius: var(--zx-radius-full);
-  background: var(--zx-color-bg-muted);
-  color: var(--zx-color-text-muted);
+  color: var(--zx-color-text-subtle);
 }
 
 /*
@@ -87,21 +84,35 @@ button.zx-stat-tile:focus-visible {
  */
 .zx-stat-tile__value {
   min-inline-size: 0;
+  margin-block-start: var(--zx-space-1);
   font-size: var(--zx-stat-tile-value-size);
-  font-weight: 600;
+  font-weight: 650;
   font-variant-numeric: tabular-nums;
+  letter-spacing: var(--zx-tracking-title);
   line-height: 1.15;
   overflow-wrap: break-word;
   color: var(--zx-color-text);
 }
 
+/* What the value is out of, or measured in: one muted line, read with the value. */
+.zx-stat-tile__caption {
+  min-inline-size: 0;
+  overflow: hidden;
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+  font-variant-numeric: tabular-nums;
+  line-height: 1.4;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .zx-stat-tile__delta {
   display: flex;
   gap: var(--zx-space-1);
   align-items: baseline;
   min-inline-size: 0;
   font-size: var(--zx-text-xs);
-  font-weight: 600;
+  font-weight: var(--zx-weight-medium);
   font-variant-numeric: tabular-nums;
   line-height: 1.4;
   color: var(--zx-color-text-muted);
@@ -124,6 +135,12 @@ button.zx-stat-tile:focus-visible {
   align-self: center;
 }
 
+.zx-stat-tile__delta-value {
+  /* A figure never breaks ("+23" over "pcs"); the comparison beside it gives way first. */
+  flex: none;
+  white-space: nowrap;
+}
+
 .zx-stat-tile__delta-label {
   min-inline-size: 0;
   overflow: hidden;
@@ -136,9 +153,12 @@ button.zx-stat-tile:focus-visible {
 
 .zx-stat-tile__trend {
   display: block;
+  flex: none;
+  box-sizing: content-box;
   inline-size: 100%;
   block-size: 2rem;
-  margin-block-start: var(--zx-space-1);
+  margin-block-start: auto;
+  padding-block-start: var(--zx-space-2);
   color: var(--zx-color-text-placeholder);
 }
 
@@ -147,32 +167,7 @@ button.zx-stat-tile:focus-visible {
   gap: var(--zx-space-2);
 }
 
-/* Intent. The icon carries it as a tint, the sparkline as its stroke. */
-.zx-stat-tile[data-kind="accent"] .zx-stat-tile__icon {
-  background: var(--zx-color-accent-subtle);
-  color: var(--zx-color-accent);
-}
-
-.zx-stat-tile[data-kind="success"] .zx-stat-tile__icon {
-  background: var(--zx-color-success-bg);
-  color: var(--zx-color-success);
-}
-
-.zx-stat-tile[data-kind="warning"] .zx-stat-tile__icon {
-  background: var(--zx-color-warning-bg);
-  color: var(--zx-color-warning);
-}
-
-.zx-stat-tile[data-kind="danger"] .zx-stat-tile__icon {
-  background: var(--zx-color-danger-bg);
-  color: var(--zx-color-danger);
-}
-
-.zx-stat-tile[data-kind="info"] .zx-stat-tile__icon {
-  background: var(--zx-color-info-bg);
-  color: var(--zx-color-info);
-}
-
+/* Intent. The sparkline carries it as its stroke; the icon stays a muted glyph. */
 .zx-stat-tile[data-kind="accent"] .zx-stat-tile__trend {
   color: var(--zx-color-accent);
 }

package/src/components/stat-tile/stat-tile.js

@@ -25,6 +25,7 @@ import { skeleton } from '../skeleton/skeleton.js';
  * @typedef {Object} StatTileNameParts
  * @property {string} [label] The metric's name.
  * @property {string} [value] The formatted value.
+ * @property {string} [caption] The context line under the value, e.g. `'of 13,184'`.
  * @property {string} [delta] The change, already worded for speech (`'up 2'`, not `'+2'`).
  * @property {string} [deltaLabel] What the change is measured against.
  */
@@ -36,6 +37,8 @@ import { skeleton } from '../skeleton/skeleton.js';
  * @property {StatTileFormat} [format='number'] How a numeric value is rendered: a named mode, a
  *   callback receiving the raw value, or null to print the value unformatted.
  * @property {string|null} [currency=null] ISO 4217 code used by `format: 'currency'`.
+ * @property {string} [caption=''] A muted context line under the value — what the number is out
+ *   of or measured in, e.g. `'of 13,184'` or `'open tickets'`. Part of the accessible name.
  * @property {string} [locale] BCP 47 tag for every formatter; defaults to the active language.
  * @property {number|string|null} [delta=null] Change against the previous period. Rendered with
  *   its own sign and an arrow, never with colour alone.
@@ -46,9 +49,10 @@ import { skeleton } from '../skeleton/skeleton.js';
  * @property {string} [deltaLabel=''] What the change is measured against, e.g. `'vs. last week'`.
  * @property {number[]} [trend=[]] Values for a decorative sparkline. Fewer than two usable numbers
  *   render nothing.
- * @property {string|null} [icon=null] Icon name from `icons.js`, shown beside the label.
- * @property {StatTileKind} [kind='neutral'] Semantic intent. It tints the icon and the sparkline
- *   and never the value, which stays at full text contrast whatever intent a record carries.
+ * @property {string|null} [icon=null] Icon name from `icons.js`, shown muted beside the label —
+ *   a glyph, not a coloured chip.
+ * @property {StatTileKind} [kind='neutral'] Semantic intent. It tints the sparkline and never the
+ *   value, which stays at full text contrast whatever intent a record carries.
  * @property {string|null} [href=null] Destination. A tile with an href is an `<a>`.
  * @property {boolean} [clickable=false] Renders a `<button>` without an href. Passing `onclick`
  *   sets this implicitly; set it directly to subscribe with `on('click', …)` instead.
@@ -93,6 +97,7 @@ const defaults = Object.freeze({
   value: null,
   format: 'number',
   currency: null,
+  caption: '',
   delta: null,
   deltaKind: 'neutral',
   deltaLabel: '',
@@ -306,17 +311,19 @@ export function statTileTag(options = {}) {
 }
 
 /**
- * Composes the tile's accessible name: label, then value, then how it changed.
+ * Composes the tile's accessible name: label, then value with its caption, then how it changed.
  *
  * The sparkline is decoration and contributes nothing, and the delta arrives already worded —
- * `'up 2'` rather than `'+2'` — because a screen reader should not have to interpret a glyph.
+ * `'up 2'` rather than `'+2'` — because a screen reader should not have to interpret a glyph. The
+ * caption is read with the value it qualifies (`'2,184 of 13,184'`), not as a separate clause.
  *
  * @param {StatTileNameParts} [parts={}] The pieces, already formatted and translated.
  * @returns {string} The name, with empty pieces dropped rather than left as stray punctuation.
  */
 export function statTileName(parts = {}) {
+  const value = [parts.value, parts.caption].map(trimmed).filter(Boolean).join(' ');
   const change = [parts.delta, parts.deltaLabel].map(trimmed).filter(Boolean).join(' ');
-  return [trimmed(parts.label), trimmed(parts.value), change].filter(Boolean).join(', ');
+  return [trimmed(parts.label), value, change].filter(Boolean).join(', ');
 }
 
 /**
@@ -391,10 +398,12 @@ function fillStatTile(root, options, message) {
     currency: options.currency
   });
   const deltaLabel = asText(options.deltaLabel);
+  const caption = asText(options.caption).trim();
 
   applyName(root, statTileName({
     label,
     value,
+    caption,
     delta: delta === null ? '' : spokenDelta(delta, message),
     deltaLabel
   }));
@@ -407,6 +416,7 @@ function fillStatTile(root, options, message) {
   // `Element`, not `HTMLElement`: the sparkline is an SVG element and belongs in the same list.
   /** @type {Element[]} */
   const children = [header, h('div', { class: 'zx-stat-tile__value' }, value)];
+  if (caption) children.push(h('div', { class: 'zx-stat-tile__caption' }, caption));
   if (delta !== null) children.push(deltaBody(delta, deltaLabel, options.deltaKind));
   const trend = trendBody(options.trend);
   if (trend) children.push(trend);
@@ -481,6 +491,7 @@ function loadingBody(options) {
     h('div', { class: 'zx-stat-tile__header' }, skeleton({ width: '55%', height: '0.75rem' })),
     skeleton({ width: '70%', height: '1.75rem', radius: 'md' })
   ];
+  if (asText(options.caption).trim()) blocks.push(skeleton({ width: '35%', height: '0.75rem' }));
   if (options.delta !== null && options.delta !== undefined) {
     blocks.push(skeleton({ width: '40%', height: '0.75rem' }));
   }