@tensor_1/react 2.46.0 → 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.

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/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/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;

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
   ] });

package/dist/hooks/useDelayedPending.d.ts

@@ -0,0 +1,22 @@
+interface DelayedPendingOptions {
+    /** Wait this long before showing anything (default 300 ms). `0` shows at once. */
+    delay?: number;
+    /** Once shown, keep showing at least this long (default 500 ms). */
+    minVisible?: number;
+}
+/**
+ * Whether to show a pending indicator for `pending` (motion standard §2.3): nothing for the
+ * first 300 ms, so a fast action never flashes a spinner; once shown, held at least 500 ms
+ * after it appeared, so it never flickers off the moment the work ends.
+ *
+ * ```tsx
+ * const showSpinner = useDelayedPending(query.isFetching);
+ * {showSpinner && <Spinner />}
+ * ```
+ *
+ * Use the raw `pending` for behaviour (blocking a second submit); use the result for what
+ * people see. Returns `false` on the server and on the first client render unless `delay` is 0.
+ */
+declare function useDelayedPending(pending: boolean, { delay, minVisible }?: DelayedPendingOptions): boolean;
+
+export { type DelayedPendingOptions, useDelayedPending };

package/dist/hooks/useDelayedPending.js

@@ -0,0 +1,35 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { PENDING_DELAY_MS, PENDING_MIN_VISIBLE_MS } from "../motion-timing.js";
+function useDelayedPending(pending, { delay = PENDING_DELAY_MS, minVisible = PENDING_MIN_VISIBLE_MS } = {}) {
+  const [shown, setShown] = useState(() => pending && delay <= 0);
+  const shownAt = useRef(shown ? now() : 0);
+  useEffect(() => {
+    if (pending) {
+      if (shown) return void 0;
+      const show = () => {
+        shownAt.current = now();
+        setShown(true);
+      };
+      if (delay <= 0) {
+        show();
+        return void 0;
+      }
+      const timer2 = setTimeout(show, delay);
+      return () => clearTimeout(timer2);
+    }
+    if (!shown) return void 0;
+    const remaining = minVisible - (now() - shownAt.current);
+    if (remaining <= 0) {
+      setShown(false);
+      return void 0;
+    }
+    const timer = setTimeout(() => setShown(false), remaining);
+    return () => clearTimeout(timer);
+  }, [pending, shown, delay, minVisible]);
+  return shown;
+}
+const now = () => Date.now();
+export {
+  useDelayedPending
+};