@xeplr/ui-utils 1.0.1 → 1.0.3

package/src/dateRange/designs/DateRangeSample.jsx

@@ -0,0 +1,138 @@
+import './dateRange.css';
+
+var TABS = [
+  ['quick', 'Quick date'],
+  ['range', 'Range'],
+  ['single', 'Single']
+];
+
+/**
+ * DateRange — design. Presentation only: everything arrives as props from
+ * useDateRangeController, so an app can swap this out without touching the
+ * behaviour.
+ *
+ * Three ways in, because they are genuinely different questions:
+ *   Quick   — "the current month", which stays current as time passes
+ *   Range   — two explicit dates
+ *   Single  — one date, month or year, typed
+ */
+export default function DateRangeSample(props) {
+  return (
+    <div className="xeplr-daterange">
+      <div className="xeplr-daterange-tabs">
+        {TABS.map(function(t) {
+          return (
+            <button
+              key={t[0]}
+              type="button"
+              data-xeplr-daterange-tab={t[0]}
+              className={props.tab === t[0] ? 'active' : ''}
+              onClick={function() { props.setTab(t[0]); }}
+            >
+              {t[1]}
+            </button>
+          );
+        })}
+      </div>
+
+      {props.tab === 'quick' && (
+        <div className="xeplr-daterange-list">
+          {props.presets.map(function(p) {
+            var on = props.value && props.value.kind === 'quick' && props.value.preset === p.key;
+            return (
+              <button
+                key={p.key}
+                type="button"
+                data-xeplr-daterange-preset={p.key}
+                className={'xeplr-daterange-item' + (on ? ' on' : '')}
+                onClick={function() { props.selectPreset(p.key); }}
+              >
+                {p.label}
+              </button>
+            );
+          })}
+        </div>
+      )}
+
+      {props.tab === 'range' && (
+        <div className="xeplr-daterange-body">
+          <label className="xeplr-daterange-field">
+            <span>From</span>
+            <input type="date" value={props.range.from || ''} onChange={function(e) { props.setRangeFrom(e.target.value); }} />
+          </label>
+          <label className="xeplr-daterange-field">
+            <span>To</span>
+            <input type="date" value={props.range.to || ''} onChange={function(e) { props.setRangeTo(e.target.value); }} />
+          </label>
+          {/* One-sided is legitimate — "everything since April" is a real
+              answer — so it is stated rather than blocked. */}
+          <div className="xeplr-daterange-note">Leave either side empty for an open-ended range.</div>
+        </div>
+      )}
+
+      {props.tab === 'single' && (
+        <div className="xeplr-daterange-body">
+          <input
+            className="xeplr-daterange-input"
+            value={props.single}
+            placeholder="1/1/2022, May 2022, or 2022"
+            onChange={function(e) { props.setSingle(e.target.value); }}
+            onBlur={function() { props.commitSingle(false); }}
+            onKeyDown={function(e) {
+              if (e.key !== 'Enter') return;
+              e.preventDefault();
+              props.commitSingle(true);
+            }}
+          />
+          {/* WHAT YOU PROBABLY MEAN, one click away. "j" is three months and
+              every month is several years — the list is shorter than typing
+              the rest, and it is ordered so the year already on screen comes
+              first. Months and years only; a day is quicker to finish typing
+              than to find among thirty. */}
+          {props.suggestions && props.suggestions.length > 0 && (
+            <ul className="xeplr-daterange-suggest">
+              {props.suggestions.map(function(s) {
+                return (
+                  <li key={s.value}>
+                    <button
+                      type="button"
+                      // MOUSEDOWN, not click: the input's onBlur commits what
+                      // is typed and would close this list before a click ever
+                      // landed on it.
+                      onMouseDown={function(e) { e.preventDefault(); props.applySuggestion(s.value); }}
+                    >
+                      <span>{s.label}</span>
+                      {s.note && <span className="xeplr-daterange-suggest-note">{s.note}</span>}
+                    </button>
+                  </li>
+                );
+              })}
+            </ul>
+          )}
+
+          {/* A month or a year IS a range, and showing the resolved span is the
+              quickest way to confirm "May 2022" was read as intended. */}
+          <div className="xeplr-daterange-note">
+            {props.single
+              ? (props.singleParsed ? props.singleParsed.from + ' → ' + props.singleParsed.to : 'Not a date yet')
+              : 'A day, a whole month, or a whole year.'}
+          </div>
+        </div>
+      )}
+
+      <div className="xeplr-daterange-foot">
+        {/* Absent, not disabled, where the host cannot accept an empty
+            selection — a control you can press that does nothing is worse
+            than one that was never offered. */}
+        {props.allowClear && (
+          <button type="button" className="xeplr-daterange-clear" onClick={props.clear}>Clear</button>
+        )}
+        {props.label && <span className="xeplr-daterange-current">{props.label}</span>}
+      </div>
+
+      {props.inheritedLabel && !props.value && (
+        <div className="xeplr-daterange-inherited">Using {props.inheritedLabel}</div>
+      )}
+    </div>
+  );
+}

package/src/dateRange/designs/dateRange.css

@@ -0,0 +1,69 @@
+/* Namespaced xeplr-daterange-* so a host's own styles can't collide with it. */
+.xeplr-daterange {
+  display: flex;
+  flex-direction: column;
+  width: 260px;
+  background: var(--xeplr-surface, #fff);
+  border: 1px solid var(--xeplr-border-strong, #c9cdd6);
+  border-radius: 9px;
+  overflow: hidden;
+  color: inherit;
+}
+.xeplr-daterange-tabs { display: flex; border-bottom: 1px solid var(--xeplr-border, #e2e5eb); }
+.xeplr-daterange-tabs button {
+  flex: 1; padding: 7px 4px; border: none; background: none; cursor: pointer;
+  font-size: 11.5px; font-weight: 600; color: var(--xeplr-muted, #6b7280);
+  border-bottom: 2px solid transparent;
+}
+.xeplr-daterange-tabs button.active {
+  color: var(--xeplr-accent, #4f5fd6);
+  border-bottom-color: var(--xeplr-accent, #4f5fd6);
+}
+.xeplr-daterange-list { max-height: 240px; overflow-y: auto; padding: 4px; }
+.xeplr-daterange-item {
+  display: block; width: 100%; text-align: left;
+  padding: 5px 7px; border: none; border-radius: 5px; background: none;
+  font-size: 12.5px; color: inherit; cursor: pointer;
+}
+.xeplr-daterange-item:hover { background: var(--xeplr-hover, #f4f5f8); }
+.xeplr-daterange-item.on { color: var(--xeplr-accent, #4f5fd6); font-weight: 600; }
+.xeplr-daterange-body { padding: 10px; }
+.xeplr-daterange-field { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+.xeplr-daterange-field span { width: 42px; flex-shrink: 0; font-size: 11.5px; color: var(--xeplr-muted, #6b7280); }
+.xeplr-daterange-field input,
+.xeplr-daterange-input {
+  flex: 1; min-width: 0; width: 100%; padding: 5px 8px;
+  border: 1px solid var(--xeplr-border, #e2e5eb); border-radius: 6px;
+  background: var(--xeplr-surface-2, #fafbfc); color: inherit; font-size: 12.5px;
+}
+.xeplr-daterange-note { font-size: 11px; color: var(--xeplr-muted-2, #9aa1ad); margin-top: 6px; line-height: 1.4; }
+.xeplr-daterange-foot {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 6px 10px; border-top: 1px solid var(--xeplr-border, #e2e5eb);
+}
+.xeplr-daterange-clear {
+  border: none; background: none; cursor: pointer;
+  font-size: 11.5px; font-weight: 600; color: var(--xeplr-accent, #4f5fd6);
+}
+.xeplr-daterange-current { font-size: 11px; color: var(--xeplr-muted-2, #9aa1ad); }
+.xeplr-daterange-inherited {
+  padding: 6px 10px; font-size: 10.5px; line-height: 1.4;
+  color: var(--xeplr-muted-2, #9aa1ad);
+  border-top: 1px solid var(--xeplr-border, #e2e5eb);
+}
+
+/* ── Suggestions, under the Single box ──────────────────────────────────── */
+.xeplr-daterange-suggest {
+  list-style: none; margin: 6px 0 0; padding: 0;
+  max-height: 190px; overflow: auto;
+  border: 1px solid var(--xeplr-border, #e2e5eb); border-radius: 8px;
+}
+.xeplr-daterange-suggest li + li { border-top: 1px solid var(--xeplr-border-secondary, #eef0f4); }
+.xeplr-daterange-suggest button {
+  display: flex; justify-content: space-between; align-items: baseline; gap: 10px;
+  width: 100%; padding: 7px 10px; border: 0; background: none;
+  font: inherit; font-size: 13px; color: var(--xeplr-text, #1c2029);
+  text-align: left; cursor: pointer;
+}
+.xeplr-daterange-suggest button:hover { background: var(--xeplr-hover, #f4f5f8); }
+.xeplr-daterange-suggest-note { font-size: 11px; color: var(--xeplr-muted, #6b7280); }

package/src/dateRange/designs/index.js

@@ -0,0 +1 @@
+export { default as DateRangeSample } from './DateRangeSample.jsx';

package/src/dateRange/pages.jsx

@@ -0,0 +1,10 @@
+import { useDateRangeController } from './useDateRangeController.js';
+import DateRangeSample from './designs/DateRangeSample.jsx';
+import { useDesignValidator } from '../fileUpload/validateDesign.js';
+import { DATE_RANGE_RULES } from './validateDesign.js';
+
+export function DateRangePage(props) {
+  var controller = useDateRangeController(props);
+  var ref = useDesignValidator('DateRangePage', DATE_RANGE_RULES);
+  return <div ref={ref}><DateRangeSample {...controller} /></div>;
+}

package/src/dateRange/useDateRangeController.js

@@ -0,0 +1,118 @@
+import { useEffect, useState } from 'react';
+import { QUICK_PRESETS, parseSingleDate, dateValueLabel, singleDateSuggestions } from './dateRange.js';
+
+/**
+ * DateRange — controller. Owns which tab is open and the half-typed text; the
+ * design draws it. No JSX here.
+ *
+ * @param {object} props
+ * @param {object|null} props.value      - the current selection, or null
+ * @param {Function} props.onChange      - (selection|null) => void
+ * @param {Function} [props.onClose]     - called after a choice that ends the interaction
+ * @param {Array} [props.presets]        - override the quick list
+ * @param {boolean} [props.allowClear]   - default true. Set false where an
+ *   empty selection is not a state the host can accept — a report bounded by
+ *   a date, say, for which "no date" means scanning all of history.
+ */
+export function useDateRangeController(props) {
+  var value = props.value || null;
+  var onChange = props.onChange || function() {};
+  var onClose = props.onClose;
+  var presets = props.presets || QUICK_PRESETS;
+  // Opt-OUT, so every existing caller keeps the button it already had.
+  var allowClear = props.allowClear !== false;
+
+  var initial = value && value.kind ? value.kind : 'quick';
+  var tabState = useState(initial);
+  var tab = tabState[0];
+  var setTab = tabState[1];
+
+  var singleState = useState(value && value.kind === 'single' ? value.value : '');
+  var single = singleState[0];
+  var setSingle = singleState[1];
+
+  // A selection made elsewhere (a reset, a different record) has to show up
+  // here, or the box keeps displaying what the user last typed into it.
+  useEffect(function() {
+    if (value && value.kind === 'single') setSingle(value.value || '');
+  }, [value]);
+
+  var range = value && value.kind === 'range' ? value : { from: '', to: '' };
+  // Parsed as you type, so "May 202" reads as not-a-date-yet rather than
+  // silently saving as nothing.
+  var singleParsed = single ? parseSingleDate(single) : null;
+
+  // WHAT YEAR TO OFFER FIRST — the one already on screen.
+  //
+  // Somebody typing "j" after looking at Feb 2025 is almost certainly after a
+  // month of 2025. Read from what is COMMITTED rather than from what is being
+  // typed, or the anchor would move as soon as a suggestion resolved to a
+  // different year and the list would reorder under the cursor.
+  var committed = value && value.kind === 'single' ? parseSingleDate(value.value) : null;
+  var anchorYear = committed && committed.from
+    ? Number(String(committed.from).slice(0, 4))
+    : new Date().getFullYear();
+
+  var suggestions = singleDateSuggestions(single, anchorYear);
+
+  function applySuggestion(text) {
+    setSingle(text);
+    // COMMITTED IMMEDIATELY. Picking from a list is a decision — leaving it in
+    // the box for the user to then press Enter on would be asking twice.
+    if (parseSingleDate(text)) {
+      onChange({ kind: 'single', value: text });
+      if (onClose) onClose();
+    }
+  }
+
+  function selectPreset(key) {
+    onChange({ kind: 'quick', preset: key });
+    if (onClose) onClose();
+  }
+
+  function setRangeFrom(from) {
+    onChange({ kind: 'range', from: from, to: range.to || '' });
+  }
+
+  function setRangeTo(to) {
+    onChange({ kind: 'range', from: range.from || '', to: to });
+  }
+
+  // Only committed once it parses — a partial entry must not overwrite a good
+  // selection with nothing.
+  function commitSingle(close) {
+    if (!singleParsed) return;
+    onChange({ kind: 'single', value: single.trim() });
+    if (close && onClose) onClose();
+  }
+
+  function clear() {
+    // Enforced here, not only by hiding the button: a custom design that
+    // renders its own clear must not be able to produce a state the host
+    // said it cannot accept.
+    if (!allowClear) return;
+    onChange(null);
+    if (onClose) onClose();
+  }
+
+  return {
+    tab: tab,
+    setTab: setTab,
+    presets: presets,
+    value: value,
+    label: dateValueLabel(value),
+    range: range,
+    single: single,
+    setSingle: setSingle,
+    singleParsed: singleParsed,
+    suggestions: suggestions,
+    applySuggestion: applySuggestion,
+    selectPreset: selectPreset,
+    setRangeFrom: setRangeFrom,
+    setRangeTo: setRangeTo,
+    commitSingle: commitSingle,
+    clear: clear,
+    allowClear: allowClear,
+    inheritedLabel: props.inheritedLabel || null
+  };
+}

package/src/dateRange/validateDesign.js

@@ -0,0 +1,20 @@
+// A design that omits any of these can't collect a date, so the page reports
+// loudly at mount rather than rendering a control nobody can use.
+//
+// The tabs are the one thing always on screen. Everything else belongs to a
+// tab — the quick list to "Quick", the date inputs to "Range"/"Single" — so
+// requiring a preset list AND a date input at the same time is a rule no
+// tabbed design can satisfy on any tab. It failed every time it was mounted.
+// `anyOf` asks what is actually meant: is there some way to enter a date?
+export var DATE_RANGE_RULES = [
+  { selector: '.xeplr-daterange-tabs button, [data-xeplr-daterange-tab]', label: 'Tab buttons (quick / range / single)' },
+  {
+    anyOf: [
+      '.xeplr-daterange-list button',
+      '[data-xeplr-daterange-preset]',
+      'input[type="date"]',
+      '.xeplr-daterange-input'
+    ],
+    label: 'A way to pick a date — a quick preset list, or a date input'
+  }
+];

package/src/fileUpload/validateDesign.js

@@ -1,11 +1,17 @@
 import { useEffect, useRef } from 'react';
 
 /**
- * Validates that required elements exist in the rendered design.
- * Throws a visible error if any required element is missing.
+ * Validates that required elements exist in the rendered design, and reports
+ * loudly when they don't — console.error plus a data-xeplr-design-invalid
+ * marker on the container.
+ *
+ * A rule matches by id, role or selector. `anyOf` takes a list of selectors
+ * and passes when ANY one is present — which is what a design with tabs or
+ * steps needs, since only the current one is mounted and demanding all of
+ * them at once can never pass.
  *
  * @param {string} componentName - Name of the page (for error messages)
- * @param {Array<{id?: string, role?: string, selector?: string, label: string}>} requiredElements
+ * @param {Array<{id?: string, role?: string, selector?: string, anyOf?: string[], label: string}>} requiredElements
  */
 export function useDesignValidator(componentName, requiredElements) {
   var containerRef = useRef(null);
@@ -22,20 +28,33 @@ export function useDesignValidator(componentName, requiredElements) {
         found = !!containerRef.current.querySelector('#' + rule.id);
       } else if (rule.role) {
         found = !!containerRef.current.querySelector('[role="' + rule.role + '"]');
+      } else if (rule.anyOf) {
+        for (var j = 0; j < rule.anyOf.length && !found; j++) {
+          found = !!containerRef.current.querySelector(rule.anyOf[j]);
+        }
       } else if (rule.selector) {
         found = !!containerRef.current.querySelector(rule.selector);
       }
 
       if (!found) {
-        missing.push(rule.label + (rule.id ? ' (id="' + rule.id + '")' : '') + (rule.selector ? ' (' + rule.selector + ')' : ''));
+        var where = rule.id ? ' (id="' + rule.id + '")'
+          : rule.anyOf ? ' (one of: ' + rule.anyOf.join(', ') + ')'
+          : rule.selector ? ' (' + rule.selector + ')' : '';
+        missing.push(rule.label + where);
       }
     }
 
     if (missing.length > 0) {
-      throw new Error(
-        '[xeplr-ui-utils] ' + componentName + ' design is missing required elements:\n' +
-        missing.map(function(m) { return '  - ' + m; }).join('\n')
-      );
+      // Reported, not thrown. Throwing from an effect gives React nothing to
+      // catch, so a design rule — a development-time check — took the whole
+      // application down with it. The container is marked so the failure is
+      // visible on the page as well as in the console, which is what "fail
+      // loudly" was ever meant to buy.
+      var message = '[xeplr-ui-utils] ' + componentName + ' design is missing required elements:\n' +
+        missing.map(function(m) { return '  - ' + m; }).join('\n');
+      console.error(message);
+      containerRef.current.setAttribute('data-xeplr-design-invalid', componentName);
+      containerRef.current.setAttribute('title', message);
     }
   }, []);
 

package/src/index.js

@@ -84,6 +84,47 @@ export { DateFieldSample } from './dateField/designs/index.js';
 // DateField — ready-made page
 export { DateFieldPage } from './dateField/pages.jsx';
 
+// DateRange — model. One selection covering a quick preset, an explicit
+// range, or a single day/month/year; everything resolves to {from, to}.
+export {
+  QUICK_PRESETS,
+  parseSingleDate,
+  resolveQuickPreset,
+  resolveDateValue,
+  dateValueLabel,
+  dateValueIsSet
+} from './dateRange/dateRange.js';
+
+// DateRange — controller
+export { useDateRangeController } from './dateRange/useDateRangeController.js';
+
+// DateRange — design validation
+export { DATE_RANGE_RULES } from './dateRange/validateDesign.js';
+
+// DateRange — sample design
+export { DateRangeSample } from './dateRange/designs/index.js';
+
+// DateRange — ready-made page
+export { DateRangePage } from './dateRange/pages.jsx';
+
+// RangeField — model. Not DateRange (below) — that's a full quick/range/
+// single POPOVER picker; this is just a From+To pair rendered as one field,
+// for a caller that already knows it wants an explicit range and has
+// nowhere to put a popover.
+export { RANGE_TYPES, emptyRange, normalizeRange, rangeIsSet } from './rangeField/rangeField.js';
+
+// RangeField — controller
+export { useRangeFieldController } from './rangeField/useRangeFieldController.js';
+
+// RangeField — design validation
+export { RANGE_FIELD_RULES } from './rangeField/validateDesign.js';
+
+// RangeField — sample design
+export { RangeFieldSample } from './rangeField/designs/index.js';
+
+// RangeField — ready-made page
+export { RangeFieldPage } from './rangeField/pages.jsx';
+
 // Dropdown — model
 export {
   DROPDOWN_MODES,
@@ -124,14 +165,35 @@ export { GridDisplayerPage } from './gridDisplayer/pages.jsx';
 export { raiseSnackbar } from './snackbar/snackbar.js';
 
 // Confirm
-export { raiseConfirm } from './confirm/confirm.js';
+export { raiseConfirm, raiseChoice } from './confirm/confirm.js';
 
 // Theme — brand-neutral DEFAULT design tokens (chart + table), override-friendly.
 // Consumers pass overrides to resolveTheme(); overrides win, rest falls through.
-export { default as DEFAULT_THEME, resolveTheme, getThemeVariant, getChartOptions, deepMerge } from './theme/index.js';
+export { default as DEFAULT_THEME, resolveTheme, getThemeVariant, getChartOptions, inputStyleVars, deepMerge } from './theme/index.js';
 
 // Static data
 export { default as COUNTRIES } from './data/countries.json';
 import _statesData from './data/states.json';
 export var STATES = _statesData.STATES;
 export var STATES_IN = _statesData.STATES_IN;
+
+// TextField — the plain text input, its multiline and search shapes.
+export { TEXT_TYPES, toValue, normalise, validate, remaining } from './textField/textField.js';
+export { useTextFieldController } from './textField/useTextFieldController.js';
+export { TEXT_FIELD_RULES } from './textField/validateDesign.js';
+export { TextFieldSample } from './textField/designs/index.js';
+export { TextFieldPage } from './textField/pages.jsx';
+
+// ── Progress notifier ────────────────────────────────────────────────────
+//
+// A small moving bar and a line of text, driven by an event KEY the back end
+// chooses. Hidden until an event for that key arrives, so it is safe to mount
+// on anything; visible while the work says it is continuing.
+//
+// An app attaches its own stream ONCE with attachProgressSource, adapting
+// whatever it publishes into { key, continue, status?, data }. This package
+// knows nothing about SSE — see progressSource.js for why the sentence is
+// built on the client rather than sent as prose.
+export { attachProgressSource, progressSourceAttached, subscribeToProgress,
+         describeProgress, describeComplete } from './progress/progressSource.js';
+export { default as ProgressNotifier } from './progress/ProgressNotifier.jsx';

package/src/progress/ProgressNotifier.jsx

@@ -0,0 +1,118 @@
+import { useEffect, useRef, useState } from 'react';
+import { subscribeToProgress, describeProgress, describeComplete } from './progressSource.js';
+import './designs/progressNotifier.css';
+
+// PROGRESS NOTIFIER — a small moving bar and a line of text, driven by an
+// event key. Mount it next to anything that starts long-running work.
+//
+// ── A NOTIFIER, NOT A PROGRESS BAR ───────────────────────────────────────
+//
+// The bar is INDETERMINATE and always will be. Almost nothing this reports on
+// can honestly say how far through it is: a GROUP BY over twenty million rows
+// knows it is running and nothing else, and a bar creeping to 60% would be a
+// number invented to look reassuring. What moves says "this is alive"; what is
+// TRUE is in the text beside it, which is the count the server actually has.
+//
+// So it is not measuring the work. It is telling you the work exists, and
+// repeating what it last said about itself.
+//
+// ── IT LISTENS, IT DOES NOT ASK ──────────────────────────────────────────
+//
+// No polling and no fetching. The app attaches its stream once with
+// attachProgressSource, and this subscribes to one key on it. A screen shows a
+// notifier for a job it did not start — one already running when the page
+// loaded, or started by somebody else — with no extra wiring, because the key
+// is the thing it is about rather than a handle handed back to whoever
+// launched it.
+
+export default function ProgressNotifier({
+  eventKey,
+  noun,
+  // Shown before anything has been heard. Usually nothing — a notifier for
+  // work that is not running should take up no room at all.
+  idle = null,
+  // Keep the finished line on screen instead of clearing it. Worth it where
+  // there is nothing else to show the result (a card with no numbers on it);
+  // not worth it where the result itself is about to appear underneath.
+  keepFinal = false,
+  // How long the finished line stays before it clears, when it does.
+  finalMs = 4000,
+  onComplete,
+  onError,
+  className = ''
+}) {
+  const [state, setState] = useState(null);   // { status, message }
+
+  // THE CALLBACKS LIVE IN A REF, AND THE SUBSCRIPTION DEPENDS ONLY ON THE KEY.
+  //
+  // They arrive as inline arrows — `onComplete={() => refresh()}` — which are
+  // a new function identity on every render of the host. With them in the
+  // effect's dependency list, every render tore the subscription down and
+  // rebuilt it; and because a stream with no listeners left is CLOSED, and its
+  // ticket is single-use, each rebuild opened a new connection and spent a new
+  // ticket. Pressing Build produced three of each: one for the busy state, one
+  // for the completion, one for the refresh that followed it.
+  //
+  // A ref keeps the latest callbacks reachable without making the subscription
+  // depend on their identity — so the stream is opened once and stays open
+  // while the key is unchanged, which is the entire point of sharing it.
+  const handlers = useRef({ onComplete: onComplete, onError: onError });
+  handlers.current = { onComplete: onComplete, onError: onError };
+
+  useEffect(() => {
+    if (!eventKey) return undefined;
+    let alive = true;
+    let timer = null;
+
+    const stop = subscribeToProgress(eventKey, (evt) => {
+      if (!alive) return;
+
+      if (evt.state === 'complete') {
+        setState({ status: 'complete', message: describeComplete(evt.data, noun) });
+        handlers.current.onComplete?.(evt.data);
+        // Cleared after a moment unless asked to stay: a finished line that
+        // never goes reads, an hour later, as if it were still happening.
+        if (!keepFinal) timer = setTimeout(() => { if (alive) setState(null); }, finalMs);
+        return;
+      }
+
+      if (evt.state === 'error') {
+        // The REASON, kept on screen. An error that clears itself is one the
+        // user is told about only if they happened to be looking.
+        setState({
+          status: 'error',
+          message: (evt.data && (evt.data.error || evt.data.message)) ||
+                   ('The ' + (noun || 'task') + ' could not be finished')
+        });
+        handlers.current.onError?.(evt.data);
+        return;
+      }
+
+      setState({ status: 'running', message: describeProgress(evt.data, noun) });
+    });
+
+    return () => {
+      alive = false;
+      if (timer) clearTimeout(timer);
+      stop();
+    };
+  // ONLY the key and the presentation options. Not the callbacks — see above.
+  }, [eventKey, noun, keepFinal, finalMs]);
+
+  if (!state) return idle;
+
+  return (
+    <div
+      className={`xpn xpn--${state.status} ${className}`.trim()}
+      // Announced to a screen reader as it changes, but politely — this is
+      // status, not an alert, and it must not interrupt what is being read.
+      role="status"
+      aria-live="polite"
+    >
+      {state.status === 'running' && (
+        <div className="xpn-bar" aria-hidden="true"><span /></div>
+      )}
+      <p className="xpn-text">{state.message}</p>
+    </div>
+  );
+}