@tensor_1/react 2.45.1 → 2.47.0

package/README.md

@@ -217,6 +217,45 @@ Radial mode still shortens long labels to fit its ring, but every node carries i
 <TabPanel value="history" keepMounted>{history}</TabPanel>
 ```
 
+### State feedback: pending, result, refetch (motion standard §2.3, §2.5)
+
+The kit follows one latency ladder: nothing new for the first 300 ms of an action, then a pending
+indicator that stays at least 500 ms; an in-place result for 1.5 s. The waits are exported as
+`PENDING_DELAY_MS`, `PENDING_MIN_VISIBLE_MS` and `RESULT_HOLD_MS`.
+
+- **`Button loading`** blocks presses at once (`aria-disabled`, `aria-busy`) but looks the same for
+  300 ms; then the spinner shows, in the button's full colour, for at least 500 ms. A fast action
+  never flashes one. `loadingDelay={0}` shows it at once. Pass `loading`, never only
+  `disabled={isPending}`: a greyed-out button says nothing about work.
+- **`Button result`** (`'success' | 'error' | null`): when it changes, 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. Keep the
+  prop defined (`null` while there is no result). Say what failed and how to recover somewhere that
+  stays (a field error, a toast). Words also come from `UixLabelsProvider` `buttonResult`.
+- **`SaveStatus`** waits 300 ms before "Saving…" (`delay`); a fast save goes straight to "Saved".
+- **`Spinner delay` / `LoadingState delay`** (`true` = 300 ms) render nothing until the delay has
+  passed. To also hold a loader 500 ms once shown, mount it from `useDelayedPending(pending)`.
+- **`BusyRegion busy`** and **`TableWrap refreshing`** keep the rows on a refetch (filter, sort,
+  page, saved view): the content dims under an indeterminate bar and the region is `aria-busy`.
+  Skeletons are for a first load only; keep the previous data while fetching
+  (TanStack Query `placeholderData: keepPreviousData`).
+
+```tsx
+const assign = trpc.incident.assign.useMutation();
+<Button loading={assign.isPending} result={assign.isSuccess ? 'success' : assign.isError ? 'error' : null}
+  resultLabels={{ success: t('assigned'), error: t('notAssigned') }} onClick={() => assign.mutate(input)}>
+  {t('assignToMe')}
+</Button>
+
+const list = trpc.incident.list.useQuery(filters, { placeholderData: keepPreviousData });
+<TableWrap refreshing={list.isFetching && !list.isPending}>…</TableWrap>
+<BusyRegion busy={feed.isFetching && !feed.isPending}>{items}</BusyRegion>
+
+const showSpinner = useDelayedPending(upload.isPending);
+{showSpinner && <Spinner size="sm" label={t('uploading')} />}
+```
+
 ### Scrolling tabs, toned stat tiles and copying
 
 - **`Tabs overflow="scroll"`** keeps a long tab row on one line that scrolls sideways. The selected tab is always scrolled into view, and edge buttons appear only on the side that has hidden tabs. The buttons are pointer-only: keyboard users move with Arrow, Home and End. Combine it with `TabPanel keepMounted` on a record page with many sections.
@@ -256,6 +295,24 @@ Radial mode still shortens long labels to fit its ring, but every node carries i
 
 Ships **ESM + CJS + types**, with per-file `"use client"` so it's safe under React Server Components. Part of the **[UIx v2 styleguide](https://github.com/COx-ORG-H/UIx)**.
 
+### Motion: reduced motion, instant dialogs
+
+The motion contract lives on the docs Foundations → Motion page and is checked by `check-motion.mjs`. Under
+`prefers-reduced-motion: reduce` the stylesheets drop movement and keep fades, and the loading indicators pulse
+instead of freezing. Motion that your JavaScript drives (a swipe, a scripted scroll, a pan or zoom) reads the same
+preference with `useReducedMotion()` (or `prefersReducedMotion()` in an event handler) and lands on the end state.
+
+`Modal instant` opens and closes with no animation, for a keyboard-initiated or many-times-a-day dialog.
+`CommandPalette` marks the dialog or popover it sits in itself, so a palette in a plain `Modal` is instant without
+`data-uix-cmdk-dialog`. `Meter` and `Progress` move on `transform` (they set `--val`, 0–1).
+
+```tsx
+const reduce = useReducedMotion();
+graph.fitView({ animate: !reduce });
+
+<Modal open={open} onClose={close} aria-label="Command palette"><CommandPalette>…</CommandPalette></Modal>
+```
+
 ### Drawer closes on a backdrop click
 
 `Drawer` closes on a click on the dimmed backdrop, as well as on Escape and its close button, and calls the same

package/dist/components/BusyBar.d.ts

@@ -0,0 +1,13 @@
+import * as react from 'react';
+
+/**
+ * The top indeterminate bar of a `BusyRegion` or a refreshing `TableWrap` (HAR-2582). It
+ * appears after 300 ms of `busy` and stays at least 500 ms; the parent dims its content
+ * while the bar shows (`:has(> .uix-busy-bar[data-shown])`), so the parent itself stays a
+ * server component. Decorative: the parent carries `aria-busy`.
+ */
+declare function BusyBar({ busy }: {
+    busy: boolean;
+}): react.JSX.Element;
+
+export { BusyBar };

package/dist/components/BusyBar.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useDelayedPending } from "../hooks/useDelayedPending.js";
+function BusyBar({ busy }) {
+  const shown = useDelayedPending(busy);
+  return /* @__PURE__ */ jsx("span", { className: "uix-busy-bar", "aria-hidden": "true", "data-shown": shown || void 0 });
+}
+export {
+  BusyBar
+};

package/dist/components/BusyRegion.d.ts

@@ -0,0 +1,18 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+interface BusyRegionProps extends HTMLAttributes<HTMLDivElement> {
+    /** The content is being fetched again (a filter, sort, page or saved-view change). */
+    busy: boolean;
+    children?: ReactNode;
+}
+/**
+ * Keeps what is on screen while it is fetched again (HAR-2582, motion standard §2.5): the
+ * children stay, dim, and an indeterminate bar runs along the top; `aria-busy` is set at
+ * once. The bar and the dim wait 300 ms, so a quick refetch shows nothing, and then stay at
+ * least 500 ms. A skeleton is for a first load only: swapping rows for skeletons on every
+ * refetch hides what changed. For a table, `TableWrap refreshing` does the same.
+ */
+declare function BusyRegion({ busy, className, children, ...props }: BusyRegionProps): react.JSX.Element;
+
+export { BusyRegion, type BusyRegionProps };

package/dist/components/BusyRegion.js

@@ -0,0 +1,12 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "../cx.js";
+import { BusyBar } from "./BusyBar.js";
+function BusyRegion({ busy, className, children, ...props }) {
+  return /* @__PURE__ */ jsxs("div", { className: cx("uix-busy-region", className), "aria-busy": busy || void 0, ...props, children: [
+    /* @__PURE__ */ jsx(BusyBar, { busy }),
+    /* @__PURE__ */ jsx("div", { className: "uix-busy-region__content", children })
+  ] });
+}
+export {
+  BusyRegion
+};

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;

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,7 +38,7 @@ const Button = forwardRef(
         } : void 0,
         ...props,
         children: [
-          children,
+          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, ownsAria: props["aria-keyshortcuts"] === void 0 })
         ]
       }

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/CommandPalette.d.ts

@@ -18,6 +18,10 @@ interface CommandPaletteProps extends HTMLAttributes<HTMLDivElement> {
  * Modal/Popover and wire search + keyboard selection in the consumer. The input is
  * a combobox over the listbox of `CommandItem`s; spreads override every default, so
  * consumers already passing their own roles/labels keep working.
+ *
+ * ⌘K is keyboard-initiated and used many times a day, so the palette marks the dialog or
+ * popover it sits in `[data-uix-instant]`: it opens and closes with no animation, without the
+ * consumer knowing the attribute (or the older `data-uix-cmdk-dialog`).
  */
 declare function CommandPalette({ inputProps, children, inputLabel: inputLabelProp, resultsLabel, className, ...props }: CommandPaletteProps): react.JSX.Element;
 interface CommandGroupProps {

package/dist/components/CommandPalette.js

@@ -1,10 +1,11 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
+import { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { cx } from "../cx.js";
 import { fillLabel } from "../fill-label.js";
 import { useUixLabels } from "../labels-context.js";
 const CmdkContext = createContext(null);
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
 function CommandPalette({ inputProps, children, inputLabel: inputLabelProp, resultsLabel, className, ...props }) {
   const uixLabels = useUixLabels();
   const inputLabel = inputLabelProp ?? uixLabels.commandPalette?.input ?? "Command palette";
@@ -14,6 +15,13 @@ function CommandPalette({ inputProps, children, inputLabel: inputLabelProp, resu
   const resultsTextRef = useRef(resultsText);
   resultsTextRef.current = resultsText;
   const listId = useId();
+  const rootRef = useRef(null);
+  useIsomorphicLayoutEffect(() => {
+    const overlay = rootRef.current?.closest("dialog, [popover]");
+    if (!overlay || overlay.hasAttribute("data-uix-instant")) return;
+    overlay.setAttribute("data-uix-instant", "");
+    return () => overlay.removeAttribute("data-uix-instant");
+  }, []);
   const [activeId, setActiveId] = useState(null);
   const [count, setCount] = useState(0);
   const [announced, setAnnounced] = useState("");
@@ -29,7 +37,7 @@ function CommandPalette({ inputProps, children, inputLabel: inputLabelProp, resu
     return () => clearTimeout(t);
   }, [count]);
   const ctx = useMemo(() => ({ listId, setActive, registerItem }), [listId, setActive, registerItem]);
-  return /* @__PURE__ */ jsx(CmdkContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxs("div", { className: cx("uix-cmdk", className), ...props, children: [
+  return /* @__PURE__ */ jsx(CmdkContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxs("div", { ref: rootRef, className: cx("uix-cmdk", className), ...props, children: [
     /* @__PURE__ */ jsx(
       "input",
       {

package/dist/components/DelayedRender.d.ts

@@ -0,0 +1,15 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * Renders `children` only once they have been mounted for `delay` ms (HAR-2580). The client
+ * half of `Spinner delay` and `LoadingState delay`, so those stay server-renderable: a
+ * loader whose work ends inside the delay never appears. Inserting the loader after the
+ * delay is what announces it, as it always has.
+ */
+declare function DelayedRender({ delay, children }: {
+    delay: number;
+    children?: ReactNode;
+}): react.JSX.Element | null;
+
+export { DelayedRender };

package/dist/components/DelayedRender.js

@@ -0,0 +1,10 @@
+"use client";
+import { Fragment, jsx } from "react/jsx-runtime";
+import { useDelayedPending } from "../hooks/useDelayedPending.js";
+function DelayedRender({ delay, children }) {
+  const shown = useDelayedPending(true, { delay, minVisible: 0 });
+  return shown ? /* @__PURE__ */ jsx(Fragment, { children }) : null;
+}
+export {
+  DelayedRender
+};

package/dist/components/DiscardPrompt.d.ts

@@ -3,6 +3,7 @@ import { SyntheticEvent, RefObject, KeyboardEvent, ReactNode } from 'react';
 import { ButtonProps } from './Button.js';
 import '../link.js';
 import './Kbd.js';
+import './ButtonFeedback.js';
 
 /** The words of the "Discard changes?" step a `dirty` Drawer or Modal asks before it closes (HAR-2029). */
 interface DiscardPromptLabels {

package/dist/components/Drawer.d.ts

@@ -4,6 +4,7 @@ import { DialogCloseEvent, DiscardPromptLabels } from './DiscardPrompt.js';
 import './Button.js';
 import '../link.js';
 import './Kbd.js';
+import './ButtonFeedback.js';
 
 interface DrawerProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
     /** TENSOR RX-125 (UIX-04): translatable; English default. */

package/dist/components/Meter.js

@@ -25,7 +25,7 @@ function Meter({ value = 0, tone, label, toneLabels, className, ...props }) {
         "div",
         {
           className: "uix-meter__fill",
-          style: { width: `${pct}%` },
+          style: { "--val": pct / 100 },
           ...tone && tone !== "success" ? { "data-tone": tone } : {}
         }
       )

package/dist/components/Modal.d.ts

@@ -4,6 +4,7 @@ import { DialogCloseEvent, DiscardPromptLabels } from './DiscardPrompt.js';
 import './Button.js';
 import '../link.js';
 import './Kbd.js';
+import './ButtonFeedback.js';
 
 interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
     open: boolean;
@@ -28,7 +29,12 @@ interface ModalProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title'> {
     /** Accessible name for the close button (default "Close dialog"). */
     closeLabel?: string;
     role?: 'dialog' | 'alertdialog';
+    /**
+     * Open and close with no animation (`[data-uix-instant]`). For a keyboard-initiated or
+     * many-times-a-day dialog. A `CommandPalette` inside sets this on its own.
+     */
+    instant?: boolean;
 }
-declare function Modal({ open, onClose, dirty, pending, discardLabels, title, children, footer, className, closeLabel: closeLabelProp, role, onKeyDown, ...rest }: ModalProps): react.JSX.Element;
+declare function Modal({ open, onClose, dirty, pending, discardLabels, title, children, footer, className, closeLabel: closeLabelProp, role, instant, onKeyDown, ...rest }: ModalProps): react.JSX.Element;
 
 export { Modal, type ModalProps };

package/dist/components/Modal.js

@@ -17,6 +17,7 @@ function Modal({
   className,
   closeLabel: closeLabelProp,
   role = "dialog",
+  instant = false,
   onKeyDown,
   ...rest
 }) {
@@ -32,6 +33,7 @@ function Modal({
       className: cx("uix-dialog", className),
       role,
       "aria-labelledby": title != null ? titleId : void 0,
+      "data-uix-instant": instant ? "" : void 0,
       ...rest,
       onKeyDown: (event) => {
         onKeyDown?.(event);

package/dist/components/Progress.js

@@ -13,7 +13,7 @@ function Progress({ value = 0, max = 100, indeterminate, label, className, ...pr
       "aria-label": label,
       className: cx("uix-progress", indeterminate && "uix-progress--indeterminate", className),
       ...props,
-      children: /* @__PURE__ */ jsx("div", { className: "uix-progress__bar", style: indeterminate ? void 0 : { width: `${pct}%` } })
+      children: /* @__PURE__ */ jsx("div", { className: "uix-progress__bar", style: indeterminate ? void 0 : { "--val": pct / 100 } })
     }
   );
 }

package/dist/components/SaveStatus.d.ts

@@ -16,6 +16,12 @@ interface SaveStatusProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children
     labels?: Partial<SaveStatusLabels>;
     /** Offered as a button only while `state` is `failed`. */
     onRetry?: () => void;
+    /**
+     * Milliseconds before "Saving…" shows (default 300; HAR-2580). Until then the previous words
+     * stay, so a fast save goes straight to "Saved" without a flash; once "Saving…" shows it
+     * stays at least 500 ms. `0` shows every state at once and holds none.
+     */
+    delay?: number;
 }
 /**
  * Inline save feedback over `.uix-save-status`: saving → saved → failed, with a retry.
@@ -27,6 +33,6 @@ interface SaveStatusProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children
  * rendering null while idle would silence the first "Saving…". The retry button sits
  * outside the region so its label is not read out on every change.
  */
-declare function SaveStatus({ state, labels, onRetry, className, ...props }: SaveStatusProps): react.JSX.Element;
+declare function SaveStatus({ state, labels, onRetry, delay, className, ...props }: SaveStatusProps): react.JSX.Element;
 
 export { DEFAULT_SAVE_STATUS_LABELS, SaveStatus, type SaveStatusLabels, type SaveStatusProps, type SaveStatusState };

package/dist/components/SaveStatus.js

@@ -1,18 +1,27 @@
+"use client";
 import { jsx, jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
 import { cx } from "../cx.js";
+import { useDelayedPending } from "../hooks/useDelayedPending.js";
+import { PENDING_DELAY_MS } from "../motion-timing.js";
 const DEFAULT_SAVE_STATUS_LABELS = {
   saving: "Saving\u2026",
   saved: "Saved",
   failed: "Could not save",
   retry: "Try again"
 };
-function SaveStatus({ state, labels, onRetry, className, ...props }) {
+function SaveStatus({ state, labels, onRetry, delay = PENDING_DELAY_MS, className, ...props }) {
   const text = { ...DEFAULT_SAVE_STATUS_LABELS, ...labels };
-  const message = state === "idle" ? "" : text[state];
-  return /* @__PURE__ */ jsxs("div", { className: cx("uix-save-status", className), "data-state": state, ...props, children: [
+  const savingShown = useDelayedPending(state === "saving", { delay, minVisible: delay > 0 ? void 0 : 0 });
+  const settled = useRef(state === "saving" ? "idle" : state);
+  if (state !== "saving") settled.current = state;
+  const quiet = settled.current === "saved" ? "saved" : "idle";
+  const shown = savingShown ? "saving" : state === "saving" ? quiet : state;
+  const message = shown === "idle" ? "" : text[shown];
+  return /* @__PURE__ */ jsxs("div", { className: cx("uix-save-status", className), "data-state": shown, ...props, children: [
     /* @__PURE__ */ jsx("span", { className: "uix-save-status__icon", "aria-hidden": "true" }),
     /* @__PURE__ */ jsx("span", { className: "uix-save-status__text", role: "status", "aria-live": "polite", children: message }),
-    state === "failed" && onRetry && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-btn uix-btn--link uix-btn--sm uix-save-status__retry", onClick: onRetry, children: text.retry })
+    shown === "failed" && onRetry && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-btn uix-btn--link uix-btn--sm uix-save-status__retry", onClick: onRetry, children: text.retry })
   ] });
 }
 export {

package/dist/components/SearchBar.d.ts

@@ -3,6 +3,7 @@ import { HTMLAttributes, Ref } from 'react';
 import { ButtonVariant } from './Button.js';
 import '../link.js';
 import './Kbd.js';
+import './ButtonFeedback.js';
 
 /** The words of a `SearchBar` (HAR-2030); the field's own name is its `label`. */
 interface SearchBarLabels {

package/dist/components/Spinner.d.ts

@@ -7,7 +7,13 @@ interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
     accent?: boolean;
     /** Announced loading text (default "Loading…"). */
     label?: string;
+    /**
+     * Show the spinner only after it has been mounted this long: `true` is 300 ms, a number is
+     * milliseconds (HAR-2580). Work that ends sooner never flashes a spinner. To also hold it at
+     * least 500 ms once shown, mount it from `useDelayedPending(pending)` instead.
+     */
+    delay?: boolean | number;
 }
-declare function Spinner({ size, accent, label, className, ...props }: SpinnerProps): react.JSX.Element;
+declare function Spinner({ delay, ...props }: SpinnerProps): react.JSX.Element;
 
 export { Spinner, type SpinnerProps };

package/dist/components/Spinner.js

@@ -1,6 +1,12 @@
 import { jsx } from "react/jsx-runtime";
 import { cx } from "../cx.js";
-function Spinner({ size = "md", accent, label, className, ...props }) {
+import { DelayedRender } from "./DelayedRender.js";
+import { PENDING_DELAY_MS } from "../motion-timing.js";
+function Spinner({ delay, ...props }) {
+  if (delay === void 0 || delay === false || delay === 0) return /* @__PURE__ */ jsx(SpinnerRing, { ...props });
+  return /* @__PURE__ */ jsx(DelayedRender, { delay: delay === true ? PENDING_DELAY_MS : delay, children: /* @__PURE__ */ jsx(SpinnerRing, { ...props }) });
+}
+function SpinnerRing({ size = "md", accent, label, className, ...props }) {
   return /* @__PURE__ */ jsx(
     "span",
     {

package/dist/components/States.d.ts

@@ -51,8 +51,14 @@ interface LoadingStateProps extends HTMLAttributes<HTMLDivElement> {
     density?: 'compact' | 'comfortable';
     /** Announced loading text (default "Loading"). */
     label?: string;
+    /**
+     * Show the skeleton only after it has been mounted this long: `true` is 300 ms, a number is
+     * milliseconds (HAR-2580). A first load that answers sooner goes straight to the content.
+     * Skeletons are for a first load; a refetch keeps its rows in a `BusyRegion`.
+     */
+    delay?: boolean | number;
 }
 /** A stack of skeleton rows for list/section loading. `role="status"`. */
-declare function LoadingState({ rows, density, label, className, ...props }: LoadingStateProps): react.JSX.Element;
+declare function LoadingState({ delay, ...props }: LoadingStateProps): react.JSX.Element;
 
 export { type AccessStateProps, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, FilteredEmptyState, ForbiddenState, LoadingState, type LoadingStateProps, NotFoundState, Skeleton, type SkeletonProps, type StateVariant };

package/dist/components/States.js

@@ -1,5 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cx } from "../cx.js";
+import { DelayedRender } from "./DelayedRender.js";
+import { PENDING_DELAY_MS } from "../motion-timing.js";
 function EmptyState({ icon, title, children, action, variant = "section", className, ...props }) {
   return /* @__PURE__ */ jsxs("div", { className: cx("uix-empty", `uix-empty--${variant}`, className), ...props, children: [
     icon != null && /* @__PURE__ */ jsx("div", { className: "uix-empty__icon", children: icon }),
@@ -51,7 +53,11 @@ function Skeleton({ variant = "block", width, height, className, style, ...props
     }
   );
 }
-function LoadingState({ rows = 3, density = "comfortable", label, className, ...props }) {
+function LoadingState({ delay, ...props }) {
+  if (delay === void 0 || delay === false || delay === 0) return /* @__PURE__ */ jsx(SkeletonRows, { ...props });
+  return /* @__PURE__ */ jsx(DelayedRender, { delay: delay === true ? PENDING_DELAY_MS : delay, children: /* @__PURE__ */ jsx(SkeletonRows, { ...props }) });
+}
+function SkeletonRows({ rows = 3, density = "comfortable", label, className, ...props }) {
   return (
     // no aria-busy: busy=true tells AT the region isn't ready and suppresses the announcement (UIX-A11Y-4)
     /* @__PURE__ */ jsxs("div", { className: cx("uix-stack", density === "compact" && "uix-stack--compact", className), role: "status", ...props, children: [

package/dist/components/Table.d.ts

@@ -7,6 +7,13 @@ interface TableWrapProps extends HTMLAttributes<HTMLDivElement> {
      * "N selected". Pass `useTable().announcement` straight through (UIX-A11Y-2).
      */
     announcement?: string;
+    /**
+     * The rows are being fetched again (a filter, sort, page or saved-view change; HAR-2582). The
+     * current rows stay and dim under an indeterminate bar along the top, and the wrap is
+     * `aria-busy`; after 300 ms, held at least 500 ms. Keep the previous rows while fetching
+     * (TanStack Query `placeholderData: keepPreviousData`); skeleton rows are for a first load.
+     */
+    refreshing?: boolean;
     children?: ReactNode;
 }
 declare const TableWrap: react.ForwardRefExoticComponent<TableWrapProps & react.RefAttributes<HTMLDivElement>>;

package/dist/components/Table.js

@@ -2,8 +2,10 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { cx } from "../cx.js";
 import { highlightSegments } from "../table-engine.js";
-const TableWrap = forwardRef(function TableWrap2({ announcement, children, className, ...props }, ref) {
-  return /* @__PURE__ */ jsxs("div", { ref, className: cx("uix-table-wrap", className), ...props, children: [
+import { BusyBar } from "./BusyBar.js";
+const TableWrap = forwardRef(function TableWrap2({ announcement, refreshing, children, className, ...props }, ref) {
+  return /* @__PURE__ */ jsxs("div", { ref, className: cx("uix-table-wrap", className), "aria-busy": refreshing || void 0, ...props, children: [
+    refreshing !== void 0 && /* @__PURE__ */ jsx(BusyBar, { busy: refreshing }),
     announcement != null && /* @__PURE__ */ jsx("div", { role: "status", className: "uix-visually-hidden", children: announcement }),
     children
   ] });