@tensor_1/react 2.46.0 → 2.48.0

package/dist/components/Button.d.ts

@@ -2,6 +2,7 @@ import * as react from 'react';
 import { ButtonHTMLAttributes, ReactNode, AnchorHTMLAttributes } from 'react';
 import { UixRenderLink } from '../link.js';
 import { KeyShortcut } from './Kbd.js';
+import { ButtonResult, ButtonResultLabels } from './ButtonFeedback.js';
 
 type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger' | 'link';
 /** `xs` is 24 px: the smallest hit area WCAG 2.5.8 allows, for dense tool rows (HAR-1348). */
@@ -10,7 +11,27 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: ButtonVariant;
     size?: ButtonSize;
     icon?: boolean;
+    /**
+     * The button's action is running. The button stops taking presses at once and is announced
+     * busy; the spinner appears only after `loadingDelay` and then stays at least 500 ms, so a
+     * fast action never flashes one (HAR-2580, motion standard §2.3). The button keeps its full
+     * colour while it works: a spinner, not a greyed-out control.
+     */
     loading?: boolean;
+    /** Milliseconds before the spinner shows (default 300). `0` shows it at once. */
+    loadingDelay?: number;
+    /**
+     * How the button's last action ended (HAR-2581). When it changes to `success` or `error`,
+     * or an action ends with one, the label crossfades to a check and `resultLabels.success`
+     * ("Done") or an alert mark and `resultLabels.error` ("Failed") for 1.5 s, announced
+     * politely, then returns. Never on the first render. The button is always as wide as its
+     * widest wording, so nothing beside it moves. Pass `null` while there is no result (keep
+     * the prop defined); say what failed and how to recover somewhere that stays, such as a
+     * field error or a toast. e.g. `result={m.isSuccess ? 'success' : m.isError ? 'error' : null}`
+     */
+    result?: ButtonResult | null;
+    /** The result words, e.g. `{ success: 'Assigned', error: 'Not assigned' }`; or `UixLabelsProvider` `buttonResult`. */
+    resultLabels?: Partial<ButtonResultLabels>;
     /**
      * Let a long label wrap onto more lines: the size becomes a minimum height instead of a fixed
      * one (HAR-1813, WCAG 1.4.10 reflow). For human-language labels on public or narrow screens;
@@ -20,10 +41,11 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     /**
      * The button's keyboard shortcut, in `KbdCombo` key names: `['A']`, `['Mod', 'Enter']`
      * (HAR-2031). Hover or focus shows the keys in a hint above the button (an icon button's
-     * `aria-label` before them), and the button gets `aria-keyshortcuts` for the viewer's platform
-     * (⌘ / Meta on Apple, Ctrl / Control elsewhere), unless you pass `aria-keyshortcuts` yourself.
-     * Inside a `Tooltip` the Tooltip shows the keys in its own bubble. The kit only shows the
-     * shortcut: the product binds the key.
+     * `aria-label` before them; ⌘ on Apple, Ctrl elsewhere). Screen readers hear the keys once, as
+     * the button's description after any `aria-describedby` of yours ("Control+Enter"), the same
+     * rule as a `Tooltip` with a shortcut (HAR-2416). Inside a `Tooltip` the Tooltip shows and says
+     * the keys. An `aria-keyshortcuts` you pass is kept as it is. The kit only shows the shortcut:
+     * the product binds the key.
      */
     shortcut?: KeyShortcut;
     children?: ReactNode;
@@ -44,13 +66,19 @@ interface ButtonLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
     disabled?: boolean;
     /** Your router's link (`(p) => <NextLink {...p} />`); default a plain `<a>`. */
     renderLink?: UixRenderLink;
+    /**
+     * The link's keyboard shortcut, as on `Button` (HAR-2416): hover or keyboard focus shows the
+     * keys in a hint above it, and screen readers hear them once as its description. Not shown
+     * while `disabled`. The kit only shows the shortcut: the product binds the key.
+     */
+    shortcut?: KeyShortcut;
     children?: ReactNode;
 }
 /**
  * A link that looks like a `Button` (HAR-1348; TENSOR A4/B5, MOTUS C-3). Use it when the
  * action navigates; use `Button` when it acts in place.
  */
-declare function ButtonLink({ href, variant, size, icon, wrap, disabled, renderLink, className, children, onClick, ...props }: ButtonLinkProps): react.JSX.Element;
+declare function ButtonLink({ href, variant, size, icon, wrap, disabled, renderLink, shortcut, className, children, onClick, ...props }: ButtonLinkProps): react.JSX.Element;
 interface ButtonGroupProps {
     children?: ReactNode;
     className?: string;

package/dist/components/Button.js

@@ -3,6 +3,8 @@ import { forwardRef } from "react";
 import { cx } from "../cx.js";
 import { renderUixLink } from "../link.js";
 import { ShortcutHint } from "./ShortcutHint.js";
+import { ButtonFeedback } from "./ButtonFeedback.js";
+import { PENDING_DELAY_MS } from "../motion-timing.js";
 const buttonClasses = (variant, size, icon, wrap, className) => cx(
   "uix-btn",
   `uix-btn--${variant}`,
@@ -13,7 +15,7 @@ const buttonClasses = (variant, size, icon, wrap, className) => cx(
 );
 let warnedIconButton = false;
 const Button = forwardRef(
-  ({ variant = "secondary", size = "md", icon = false, loading = false, wrap = false, shortcut, className, children, disabled, onClick, ...props }, ref) => {
+  ({ variant = "secondary", size = "md", icon = false, loading, loadingDelay = PENDING_DELAY_MS, result, resultLabels, wrap = false, shortcut, className, children, disabled, onClick, ...props }, ref) => {
     if (!warnedIconButton && icon && children == null && !props["aria-label"] && !props["aria-labelledby"] && typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
       warnedIconButton = true;
       console.warn("uix: icon-only <Button> has no accessible name \u2014 pass aria-label or aria-labelledby.");
@@ -26,7 +28,7 @@ const Button = forwardRef(
         disabled,
         "aria-disabled": loading || void 0,
         "aria-busy": loading || void 0,
-        "data-loading": loading || void 0,
+        "data-pending": loading || void 0,
         onClick: loading || onClick ? (e) => {
           if (loading) {
             e.preventDefault();
@@ -36,20 +38,24 @@ const Button = forwardRef(
         } : void 0,
         ...props,
         children: [
-          children,
-          shortcut && shortcut.length > 0 && /* @__PURE__ */ jsx(ShortcutHint, { keys: shortcut, label: icon ? props["aria-label"] : void 0, ownsAria: props["aria-keyshortcuts"] === void 0 })
+          loading !== void 0 || result !== void 0 ? /* @__PURE__ */ jsx(ButtonFeedback, { loading: !!loading, loadingDelay, result, resultLabels, children }) : children,
+          shortcut && shortcut.length > 0 && /* @__PURE__ */ jsx(ShortcutHint, { keys: shortcut, label: icon ? props["aria-label"] : void 0, describedBy: props["aria-describedby"] })
         ]
       }
     );
   }
 );
 Button.displayName = "Button";
-function ButtonLink({ href, variant = "secondary", size = "md", icon = false, wrap = false, disabled = false, renderLink, className, children, onClick, ...props }) {
+function ButtonLink({ href, variant = "secondary", size = "md", icon = false, wrap = false, disabled = false, renderLink, shortcut, className, children, onClick, ...props }) {
   const classes = buttonClasses(variant, size, icon, wrap, className);
   if (disabled) {
     return /* @__PURE__ */ jsx("a", { ...props, className: classes, role: "link", "aria-disabled": "true", children });
   }
-  return /* @__PURE__ */ jsx(Fragment, { children: renderUixLink(renderLink, { ...props, href, onClick, className: classes, children }) });
+  const content = shortcut && shortcut.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+    children,
+    /* @__PURE__ */ jsx(ShortcutHint, { keys: shortcut, label: icon ? props["aria-label"] : void 0, describedBy: props["aria-describedby"] })
+  ] }) : children;
+  return /* @__PURE__ */ jsx(Fragment, { children: renderUixLink(renderLink, { ...props, href, onClick, className: classes, children: content }) });
 }
 function ButtonGroup({ children, className }) {
   return /* @__PURE__ */ jsx("div", { className: cx("uix-btn-group", className), children });

package/dist/components/ButtonFeedback.d.ts

@@ -0,0 +1,30 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type ButtonResult = 'success' | 'error';
+/** The words a `Button` shows and announces for a moment after its action ends. */
+interface ButtonResultLabels {
+    success: string;
+    error: string;
+}
+declare const DEFAULT_BUTTON_RESULT_LABELS: ButtonResultLabels;
+interface ButtonFeedbackProps {
+    loading: boolean;
+    loadingDelay: number;
+    result?: ButtonResult | null;
+    resultLabels?: Partial<ButtonResultLabels>;
+    children?: ReactNode;
+}
+/**
+ * The client half of `Button`'s `loading` and `result` (HAR-2580, HAR-2581). `Button` itself
+ * stays server-renderable; this child keeps the timers. It marks the button busy through a
+ * hidden marker (`[data-uix-btn-busy]`, read by `.uix-btn:has(…)`), so the button element is
+ * never re-created and keeps focus. With a `result` it also stacks the label and the result
+ * words in one grid cell, so the button is always as wide as the widest of them, and
+ * announces the result through a polite status region portalled to the body (inside the
+ * button it would become part of the button's name), or to the nearest dialog, since a modal
+ * dialog makes the body inert. An icon-only button shows the mark alone; the words are spoken.
+ */
+declare function ButtonFeedback({ loading, loadingDelay, result, resultLabels, children }: ButtonFeedbackProps): react.JSX.Element;
+
+export { ButtonFeedback, type ButtonFeedbackProps, type ButtonResult, type ButtonResultLabels, DEFAULT_BUTTON_RESULT_LABELS };

package/dist/components/ButtonFeedback.js

@@ -0,0 +1,78 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { useDelayedPending } from "../hooks/useDelayedPending.js";
+import { useUixLabels } from "../labels-context.js";
+import { RESULT_HOLD_MS } from "../motion-timing.js";
+const DEFAULT_BUTTON_RESULT_LABELS = {
+  success: "Done",
+  error: "Failed"
+};
+const SuccessGlyph = () => /* @__PURE__ */ jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("path", { d: "M20 6 9 17l-5-5" }) });
+const ErrorGlyph = () => /* @__PURE__ */ jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
+  /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "10" }),
+  /* @__PURE__ */ jsx("line", { x1: "12", x2: "12", y1: "8", y2: "12" }),
+  /* @__PURE__ */ jsx("line", { x1: "12", x2: "12.01", y1: "16", y2: "16" })
+] });
+function ButtonFeedback({ loading, loadingDelay, result, resultLabels, children }) {
+  const busy = useDelayedPending(loading, { delay: loadingDelay });
+  const fromProvider = useUixLabels().buttonResult;
+  const text = { ...DEFAULT_BUTTON_RESULT_LABELS, ...fromProvider, ...resultLabels };
+  const [queued, setQueued] = useState(null);
+  const [shown, setShown] = useState(null);
+  const previous = useRef({ result: result ?? null, loading });
+  useEffect(() => {
+    const before = previous.current;
+    previous.current = { result: result ?? null, loading };
+    if (loading) {
+      setQueued(null);
+      setShown(null);
+      return;
+    }
+    if (result && (result !== before.result || before.loading)) setQueued(result);
+  }, [result, loading]);
+  useEffect(() => {
+    if (!queued || busy || loading) return;
+    setShown((current) => ({ kind: queued, n: (current?.n ?? 0) + 1 }));
+    setQueued(null);
+  }, [queued, busy, loading]);
+  useEffect(() => {
+    if (!shown) return void 0;
+    const timer = setTimeout(() => setShown(null), RESULT_HOLD_MS);
+    return () => clearTimeout(timer);
+  }, [shown]);
+  const markerRef = useRef(null);
+  const [portalTarget, setPortalTarget] = useState(null);
+  const withResult = result !== void 0;
+  useEffect(() => {
+    if (withResult) setPortalTarget(markerRef.current?.closest("dialog") ?? document.body);
+  }, [withResult]);
+  const marker = /* @__PURE__ */ jsx("span", { ref: markerRef, hidden: true, "data-uix-btn-busy": busy || void 0 });
+  if (!withResult) return /* @__PURE__ */ jsxs(Fragment, { children: [
+    marker,
+    children
+  ] });
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    marker,
+    /* @__PURE__ */ jsxs("span", { className: "uix-btn__face", "data-result": shown?.kind, children: [
+      /* @__PURE__ */ jsx("span", { className: "uix-btn__label", children }),
+      /* @__PURE__ */ jsxs("span", { className: "uix-btn__result", "data-kind": "success", "aria-hidden": "true", children: [
+        /* @__PURE__ */ jsx(SuccessGlyph, {}),
+        /* @__PURE__ */ jsx("span", { className: "uix-btn__result-text", children: text.success })
+      ] }),
+      /* @__PURE__ */ jsxs("span", { className: "uix-btn__result", "data-kind": "error", "aria-hidden": "true", children: [
+        /* @__PURE__ */ jsx(ErrorGlyph, {}),
+        /* @__PURE__ */ jsx("span", { className: "uix-btn__result-text", children: text.error })
+      ] })
+    ] }),
+    portalTarget && createPortal(
+      /* @__PURE__ */ jsx("span", { role: "status", className: "uix-visually-hidden", children: shown ? text[shown.kind] : "" }),
+      portalTarget
+    )
+  ] });
+}
+export {
+  ButtonFeedback,
+  DEFAULT_BUTTON_RESULT_LABELS
+};

package/dist/components/Card.d.ts

@@ -33,5 +33,22 @@ interface CardLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 't
 }
 /** A whole-card anchor with visible hover and keyboard focus affordances. */
 declare function CardLink({ title, subtitle, headerAction, footer, children, className, ...props }: CardLinkProps): react.JSX.Element;
+interface InsetProps extends HTMLAttributes<HTMLDivElement> {
+    /** `md` (default) pads with `--uix-space-4`; `sm` with `--uix-space-3`, for a dense card. */
+    padding?: 'sm' | 'md';
+    /**
+     * `sunken` (default) is `--uix-bg-subtle` on the card's surface; `surface` is for a well on a
+     * panel that is already subtle.
+     */
+    tone?: 'sunken' | 'surface';
+    children?: ReactNode;
+}
+/**
+ * A bordered, sunken well inside a card body (HAR-1818), over `.uix-inset`: for a preview or a
+ * specimen (a rendered header, an image crop, a code sample). Use it instead of a `Card` in a
+ * `Card`, which brings a second shadow, card padding and card semantics. It lays out nothing:
+ * the content is yours. Give it `role="group"` and an `aria-label` when the preview needs a name.
+ */
+declare function Inset({ padding, tone, children, className, ...props }: InsetProps): react.JSX.Element;
 
-export { Card, CardLink, type CardLinkProps, type CardProps };
+export { Card, CardLink, type CardLinkProps, type CardProps, Inset, type InsetProps };

package/dist/components/Card.js

@@ -34,7 +34,11 @@ function CardLink({ title, subtitle, headerAction, footer, children, className,
     footer != null && /* @__PURE__ */ jsx("div", { className: "uix-card__footer", children: footer })
   ] });
 }
+function Inset({ padding = "md", tone = "sunken", children, className, ...props }) {
+  return /* @__PURE__ */ jsx("div", { className: cx("uix-inset", padding === "sm" && "uix-inset--sm", tone === "surface" && "uix-inset--surface", className), ...props, children });
+}
 export {
   Card,
-  CardLink
+  CardLink,
+  Inset
 };

package/dist/components/ChangeHighlight.d.ts

@@ -0,0 +1,30 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+interface ChangeHighlightProps extends HTMLAttributes<HTMLElement> {
+    /** The value shown inside. When it changes after mount the element flashes; never on the first render. */
+    value: unknown;
+    /** The element to render (default `span`): `td`, `tr`, `div`, `li`… A `tr` tints its cells. */
+    as?: keyof HTMLElementTagNameMap;
+    /**
+     * `tint` (default) fades a background tint, for a row, a cell or a field; `ring` fades an
+     * outline instead, for something with a colour of its own, such as a status pill.
+     */
+    variant?: 'tint' | 'ring';
+    /** Said politely when the value changes, e.g. "Status changed to Resolved by A. Novak". */
+    announce?: string;
+    /** No highlight, e.g. while the person is editing this value themselves. */
+    disabled?: boolean;
+    children?: ReactNode;
+}
+/**
+ * Shows that a value changed in place (HAR-2585, motion standard §2.5): a live update, the
+ * result of a transition, a rolled-back optimistic change. The element is tinted at once and
+ * the tint fades; under reduced motion or forced colours it is outlined for the same time
+ * instead. The flash is the signal and its place the location; pass `announce` for the
+ * description. For an element you render yourself, use `useChangeHighlight`; on plain markup,
+ * add `.uix-changed` (remove it, force a reflow and add it again to replay).
+ */
+declare const ChangeHighlight: react.ForwardRefExoticComponent<ChangeHighlightProps & react.RefAttributes<HTMLElement | null>>;
+
+export { ChangeHighlight, type ChangeHighlightProps };

package/dist/components/ChangeHighlight.js

@@ -0,0 +1,21 @@
+"use client";
+import { createElement, forwardRef, useCallback } from "react";
+import { cx } from "../cx.js";
+import { useChangeHighlight } from "../hooks/useChangeHighlight.js";
+const ChangeHighlight = forwardRef(function ChangeHighlight2({ value, as = "span", variant = "tint", announce, disabled, className, children, ...props }, forwarded) {
+  const ref = useChangeHighlight(value, { announce, disabled });
+  const setRef = useCallback((node) => {
+    ref.current = node;
+    if (typeof forwarded === "function") forwarded(node);
+    else if (forwarded) forwarded.current = node;
+  }, [ref, forwarded]);
+  return createElement(as, {
+    ...props,
+    ref: setRef,
+    className: cx("uix-change-highlight", variant === "ring" && "uix-change-highlight--ring", className)
+  }, children);
+});
+ChangeHighlight.displayName = "ChangeHighlight";
+export {
+  ChangeHighlight
+};

package/dist/components/ChartCore.js

@@ -3,6 +3,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useRef } from "react";
 import { cx } from "../cx.js";
 import { mergeChartTheme, uixChartTheme, uixChartTokens } from "../chart-theme.js";
+import { prefersReducedMotion } from "../hooks/useReducedMotion.js";
 function readToken(name) {
   if (typeof getComputedStyle === "undefined") return "";
   return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
@@ -15,7 +16,7 @@ function themed(option, theme, element) {
   return theme === "none" ? resolved : mergeChartTheme(uixChartTheme(element), resolved);
 }
 function motionSafe(option) {
-  if (typeof matchMedia !== "undefined" && matchMedia("(prefers-reduced-motion: reduce)").matches) {
+  if (prefersReducedMotion()) {
     return { ...option, animation: false };
   }
   return option;

package/dist/components/Checkbox.d.ts

@@ -6,5 +6,31 @@ interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'typ
     indeterminate?: boolean;
 }
 declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
+interface CheckboxGroupProps {
+    children: ReactNode;
+    /** The group's name, rendered as the `<legend>`: announced with each checkbox (HAR-1799). */
+    label: ReactNode;
+    /** Help under the boxes, tied to the group with `aria-describedby`. */
+    hint?: ReactNode;
+    /** Shown instead of the hint and announced (`role="alert"`). */
+    error?: ReactNode;
+    /** Draws the required marker after the legend. Which boxes must be ticked is your rule to check. */
+    required?: boolean;
+    /** Disables every checkbox in the group (a disabled `<fieldset>`). */
+    disabled?: boolean;
+    /**
+     * The most columns the boxes form. Default 1. A column is never narrower than 10rem: on a phone,
+     * or in a narrow card, the boxes fall back to fewer columns.
+     */
+    columns?: number;
+    id?: string;
+    className?: string;
+}
+/**
+ * Checkboxes under one name (HAR-1799; MOTUS UXR-05): a `<fieldset>` whose `<legend>` names the
+ * group, so a screen reader says "Tags, group" before each box, with the field's hint and error
+ * slot below. The checkbox counterpart of `<RadioGroup label>`. Put `Checkbox`es inside.
+ */
+declare function CheckboxGroup({ children, label, hint, error, required, disabled, columns, id, className }: CheckboxGroupProps): react.JSX.Element;
 
-export { Checkbox, type CheckboxProps };
+export { Checkbox, CheckboxGroup, type CheckboxGroupProps, type CheckboxProps };

package/dist/components/Checkbox.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { forwardRef, useEffect, useRef } from "react";
+import { forwardRef, useEffect, useId, useRef } from "react";
 import { cx } from "../cx.js";
 const CheckIcon = () => /* @__PURE__ */ jsx("svg", { viewBox: "0 0 12 12", fill: "none", stroke: "currentColor", strokeWidth: 2.5, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: /* @__PURE__ */ jsx("polyline", { points: "1.5,6 4.5,9 10.5,3" }) });
 const IndeterminateIcon = () => /* @__PURE__ */ jsx("svg", { viewBox: "0 0 12 12", "aria-hidden": "true", children: /* @__PURE__ */ jsx("rect", { x: "2", y: "5", width: "8", height: "2", rx: "1", fill: "currentColor" }) });
@@ -30,6 +30,35 @@ const Checkbox = forwardRef(
   }
 );
 Checkbox.displayName = "Checkbox";
+function CheckboxGroup({ children, label, hint, error, required, disabled, columns = 1, id, className }) {
+  const uid = useId();
+  const msgId = `${id ?? uid}-msg`;
+  const message = error != null && error !== false ? error : hint;
+  const cols = Math.max(1, Math.floor(columns));
+  return /* @__PURE__ */ jsxs(
+    "fieldset",
+    {
+      id,
+      className: cx("uix-checkbox-group", className),
+      disabled,
+      "aria-describedby": message != null && message !== false ? msgId : void 0,
+      "data-invalid": error != null && error !== false || void 0,
+      children: [
+        /* @__PURE__ */ jsx("legend", { className: "uix-checkbox-group__legend", "data-required": required || void 0, children: label }),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: "uix-checkbox-group__options",
+            style: cols > 1 ? { "--uix-checkbox-group-columns": cols } : void 0,
+            children
+          }
+        ),
+        /* @__PURE__ */ jsx("div", { className: "uix-field__msg", id: msgId, children: error != null && error !== false ? /* @__PURE__ */ jsx("span", { className: "uix-field__error", role: "alert", children: error }) : hint != null && hint !== false ? /* @__PURE__ */ jsx("span", { className: "uix-field__hint", children: hint }) : null })
+      ]
+    }
+  );
+}
 export {
-  Checkbox
+  Checkbox,
+  CheckboxGroup
 };

package/dist/components/CodeDisplay.d.ts

@@ -0,0 +1,65 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+/** The words of a `CodeDisplay` (HAR-1253). */
+interface CodeDisplayLabels {
+    /** The live countdown; `{time}` is `m:ss` (or `h:mm:ss`). */
+    expiresIn: string;
+    /** Announced once when `warnBefore` seconds are left; `{time}` is that time as `m:ss`. */
+    expiresSoon: string;
+    /** Shown, and announced once, when the code has expired. Text, so the state never rests on colour. */
+    expired: string;
+    /** The copy button's accessible name. */
+    copy: string;
+    /** Announced after a copy. */
+    copied: string;
+    /** Announced when the copy failed. */
+    copyFailed: string;
+}
+declare const DEFAULT_CODE_DISPLAY_LABELS: CodeDisplayLabels;
+interface CodeDisplayProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * The code, e.g. `"K7Q4PX9MW"` or `"K7Q-4PX-9MW"`. A code that already contains spaces or
+     * hyphens is shown in those groups; otherwise it is cut into groups of `groupSize`.
+     */
+    code: string;
+    /** The visible name above the code, e.g. "Pairing code"; it also names the group. */
+    label: ReactNode;
+    /** Characters per group, or the length of each group in turn (`[4, 4, 4]`). Default 3. */
+    groupSize?: number | readonly number[];
+    /** Drawn between groups, never read out. Default `-`. */
+    separator?: string;
+    /** `md` (default) for a panel; `lg` for a code read across a counter. */
+    size?: 'md' | 'lg';
+    /** When the code stops working (an ISO instant, epoch milliseconds or a Date): shows a countdown, then the expired state. */
+    expiresAt?: string | number | Date;
+    /**
+     * Seconds before expiry when the countdown turns to a warning and a screen reader hears it
+     * once (`labels.expiresSoon`). Default 60; 0 turns the warning off.
+     */
+    warnBefore?: number;
+    /** Called once when the countdown reaches zero while the component is on screen. */
+    onExpire?: () => void;
+    /** Adds a copy button while the code is live. */
+    copyable?: boolean;
+    /**
+     * What a screen reader says for one character. Default: the character itself, so "K7Q" is
+     * read "K, 7, Q". Use it for a spelling alphabet or to tell O from 0.
+     */
+    spell?: (character: string) => string;
+    /** The words. Default: `UixLabelsProvider` `codeDisplay`, then English. */
+    labels?: Partial<CodeDisplayLabels>;
+}
+/** The code in its display groups. */
+declare function codeGroups(code: string, groupSize?: number | readonly number[]): string[];
+/** `m:ss`, or `h:mm:ss` from an hour up, for a number of whole seconds. */
+declare function formatCountdown(seconds: number): string;
+/**
+ * A one-time code shown large (HAR-1253; SHOPx PRE-08 till pairing, the shopper's voucher):
+ * monospace characters in groups, spelled character by character to a screen reader, an
+ * optional countdown that ends in an expired state said in words, and an optional copy button.
+ * The consumer makes the code and enforces its expiry; this only shows it.
+ */
+declare function CodeDisplay({ code, label, groupSize, separator, size, expiresAt, warnBefore, onExpire, copyable, spell, labels: labelsProp, className, ...props }: CodeDisplayProps): react.JSX.Element;
+
+export { CodeDisplay, type CodeDisplayLabels, type CodeDisplayProps, DEFAULT_CODE_DISPLAY_LABELS, codeGroups, formatCountdown };

package/dist/components/CodeDisplay.js

@@ -0,0 +1,124 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+import { cx } from "../cx.js";
+import { fillLabel } from "../fill-label.js";
+import { useUixLabels } from "../labels-context.js";
+import { CopyButton } from "./CopyButton.js";
+const DEFAULT_CODE_DISPLAY_LABELS = {
+  expiresIn: "Expires in {time}",
+  expiresSoon: "{time} left before the code expires",
+  expired: "Expired. Ask for a new code.",
+  copy: "Copy code",
+  copied: "Copied",
+  copyFailed: "Could not copy. Select the code instead."
+};
+function codeGroups(code, groupSize = 3) {
+  const trimmed = code.trim();
+  if (/[\s-]/.test(trimmed)) return trimmed.split(/[\s-]+/).filter(Boolean);
+  const sizes = typeof groupSize === "number" ? [groupSize] : groupSize;
+  const groups = [];
+  for (let i = 0, at = 0; at < trimmed.length; i += 1) {
+    const size = Math.max(1, Math.floor(sizes[Math.min(i, sizes.length - 1)] ?? trimmed.length));
+    groups.push(trimmed.slice(at, at + size));
+    at += size;
+  }
+  return groups;
+}
+function formatCountdown(seconds) {
+  const s = Math.max(0, Math.ceil(seconds));
+  const hours = Math.floor(s / 3600);
+  const minutes = Math.floor(s % 3600 / 60);
+  const rest = String(s % 60).padStart(2, "0");
+  return hours > 0 ? `${hours}:${String(minutes).padStart(2, "0")}:${rest}` : `${minutes}:${rest}`;
+}
+const instant = (value) => value === void 0 ? void 0 : new Date(value).getTime();
+function CodeDisplay({
+  code,
+  label,
+  groupSize = 3,
+  separator = "-",
+  size = "md",
+  expiresAt,
+  warnBefore = 60,
+  onExpire,
+  copyable = false,
+  spell,
+  labels: labelsProp,
+  className,
+  ...props
+}) {
+  const uixLabels = useUixLabels();
+  const labels = { ...DEFAULT_CODE_DISPLAY_LABELS, ...uixLabels.codeDisplay, ...labelsProp };
+  const labelId = useId();
+  const deadline = instant(expiresAt);
+  const [now, setNow] = useState(() => Date.now());
+  const remaining = deadline === void 0 || Number.isNaN(deadline) ? void 0 : deadline - now;
+  const expired = remaining !== void 0 && remaining <= 0;
+  const warnAt = Math.max(0, warnBefore) * 1e3;
+  const phase = remaining === void 0 ? "live" : remaining <= 0 ? "expired" : remaining <= warnAt ? "soon" : "live";
+  const [announcement, setAnnouncement] = useState("");
+  const shownPhase = useRef(phase);
+  const onExpireRef = useRef(onExpire);
+  onExpireRef.current = onExpire;
+  const labelsRef = useRef(labels);
+  labelsRef.current = labels;
+  useEffect(() => {
+    if (deadline === void 0 || Number.isNaN(deadline)) return void 0;
+    let timer;
+    const tick = () => {
+      const current = Date.now();
+      setNow(current);
+      const left = deadline - current;
+      if (left > 0) timer = setTimeout(tick, left % 1e3 || 1e3);
+    };
+    tick();
+    return () => clearTimeout(timer);
+  }, [deadline]);
+  useEffect(() => {
+    const before = shownPhase.current;
+    shownPhase.current = phase;
+    if (phase === before) return;
+    if (phase === "live") setAnnouncement("");
+    else if (phase === "soon" && before === "live") setAnnouncement(fillLabel(labelsRef.current.expiresSoon, { time: formatCountdown(warnAt / 1e3) }));
+    else if (phase === "expired") {
+      setAnnouncement(labelsRef.current.expired);
+      onExpireRef.current?.();
+    }
+  }, [phase, warnAt]);
+  const groups = codeGroups(code, groupSize);
+  const say = spell ?? ((character) => character);
+  const spoken = groups.map((group) => Array.from(group).map(say).join(" ")).join(", ");
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx("uix-code-display", size === "lg" && "uix-code-display--lg", className),
+      role: "group",
+      "aria-labelledby": labelId,
+      "data-state": phase,
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "uix-code-display__label", id: labelId, children: label }),
+        /* @__PURE__ */ jsxs("div", { className: "uix-code-display__row", children: [
+          /* @__PURE__ */ jsx("span", { className: "uix-code-display__code", "aria-hidden": "true", translate: "no", children: groups.map((group, index) => (
+            // The separator ends its group, so a wrapped line never starts with one.
+            /* @__PURE__ */ jsxs("span", { className: "uix-code-display__group", children: [
+              group,
+              index < groups.length - 1 && /* @__PURE__ */ jsx("span", { className: "uix-code-display__sep", children: separator })
+            ] }, index)
+          )) }),
+          /* @__PURE__ */ jsx("span", { className: "uix-code-display__spoken uix-visually-hidden", children: spoken }),
+          copyable && !expired && /* @__PURE__ */ jsx(CopyButton, { value: groups.join(""), label: labels.copy, copiedLabel: labels.copied, failedLabel: labels.copyFailed })
+        ] }),
+        remaining !== void 0 && /* @__PURE__ */ jsx("div", { className: "uix-code-display__meta", suppressHydrationWarning: true, children: expired ? labels.expired : fillLabel(labels.expiresIn, { time: formatCountdown(remaining / 1e3) }) }),
+        /* @__PURE__ */ jsx("span", { role: "status", className: "uix-visually-hidden", children: announcement })
+      ]
+    }
+  );
+}
+export {
+  CodeDisplay,
+  DEFAULT_CODE_DISPLAY_LABELS,
+  codeGroups,
+  formatCountdown
+};