@gusnips/react 0.9.26 → 0.9.27

package/README.md

@@ -529,6 +529,47 @@ toast needs no `catch`. Outside a component, `copyText(text)` does the write on
 The words are yours, and so is the live region: a label that changes needs `aria-live` to be
 heard.
 
+## A busy button a person can see
+
+```tsx
+import { BusyRing, useHeldPending } from "@gusnips/react";
+
+function SaveButton({ saving, ...props }: { saving: boolean } & ButtonProps) {
+  const busy = useHeldPending(saving);
+  return (
+    <button {...props} disabled={busy} aria-busy={busy} className="relative rounded-md ...">
+      Save
+      {busy && <BusyRing />}
+    </button>
+  );
+}
+```
+
+```css
+@import "@gusnips/tokens/busy-ring.css";
+```
+
+A refresh that answers in 80 ms turns its pending flag on and off inside a frame. Nothing was
+painted, so the reader pressed "Reload", saw nothing change, and decided the press was ignored.
+A louder spinner cannot fix that, because the spinner never shows. `useHeldPending(pending)`
+keeps the flag on for at least 400 ms once it turns on. It is `true` on the very render
+`pending` turns true, so the busy look is there on the press and not a frame later, and a slow
+request is not made slower. Pass a second argument to change the 400.
+
+`<BusyRing />` is a ring that runs round the button's edge. It paints in `currentColor`, so it
+contrasts with every variant in both themes and adds nothing to your palette. The button needs
+`position: relative` and a disabled style that does not dim it (`disabled:opacity-100`), or the
+ring shows at half strength. It copies the button's `border-radius`.
+
+Tune it in your own CSS: `--busy-ring-width` (2px), `--busy-ring-duration` (900ms) and
+`--busy-ring-duration-reduced` (2400ms). Under reduced motion the ring turns slower and does not
+stop, because a frozen ring reads as a hang. The `@gusnips/tokens` base rules clamp every
+animation to one pass under reduced motion, and the ring wins that fight on purpose.
+
+There is no shared `Button`, so the two lines above live in your button once. That is also the
+place to change the look later: swap the ring for an icon or a label there, or edit the CSS for a
+different ring everywhere.
+
 ## Slash commands in a text field
 
 A slash command is text like `/help` that picks an action instead of sending a message.
@@ -636,7 +677,7 @@ or scheduler: offer a repeat command only when your app has real scheduling behi
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
-`i18nInitOptions`, and `cn`.
+`i18nInitOptions`, `useHeldPending` and `BusyRing` (above), and `cn`.
 
 Pass `storageWriter: "app"` to `i18nInitOptions` when your own language control writes the stored
 locale. Leave it out and the detector writes it, which is right until you offer "follow the

package/dist/busy-ring.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The ring that runs round a busy control's edge. Put it inside the control while it is busy.
+ *
+ * It draws nothing by itself: the look lives in `@gusnips/tokens/busy-ring.css`, which you import
+ * once. The control needs `position: relative` and the radius it already has (the ring copies it),
+ * and its disabled style must not dim it, or the ring is drawn at half strength and nobody sees it.
+ *
+ * Why a component for one `span`: the class name and the markup are one contract. Changing how
+ * busy looks, a second element or another shape, is then one edit here and one release, not one
+ * edit in every product's button.
+ */
+export declare function BusyRing(): import("react").JSX.Element;
+//# sourceMappingURL=busy-ring.d.ts.map

package/dist/busy-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"busy-ring.d.ts","sourceRoot":"","sources":["../src/busy-ring.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,gCAEvB"}

package/dist/busy-ring.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The ring that runs round a busy control's edge. Put it inside the control while it is busy.
+ *
+ * It draws nothing by itself: the look lives in `@gusnips/tokens/busy-ring.css`, which you import
+ * once. The control needs `position: relative` and the radius it already has (the ring copies it),
+ * and its disabled style must not dim it, or the ring is drawn at half strength and nobody sees it.
+ *
+ * Why a component for one `span`: the class name and the markup are one contract. Changing how
+ * busy looks, a second element or another shape, is then one edit here and one release, not one
+ * edit in every product's button.
+ */
+export function BusyRing() {
+    return _jsx("span", { "aria-hidden": "true", className: "busy-ring" });
+}
+//# sourceMappingURL=busy-ring.js.map

package/dist/busy-ring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"busy-ring.js","sourceRoot":"","sources":["../src/busy-ring.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,8BAAkB,MAAM,EAAC,SAAS,EAAC,WAAW,GAAG,CAAC;AAC3D,CAAC"}

package/dist/held-pending.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `pending`, kept on for at least `minMs` once it turns on.
+ *
+ * It answers `true` on the very render `pending` turns true, with no wait for an effect, so the
+ * busy state shows on the press and not a frame later. A slow request is not made slower: the
+ * hold only fills the gap when the request ended early, and ends within one timer tick of it
+ * otherwise.
+ *
+ * 400 ms is the floor for a busy state a person can read as "it ran". Use it for a button's busy
+ * look, a refresh icon, a save that returns at once. Do not use it to gate real work: it changes
+ * what is shown, never what the request does.
+ */
+export declare function useHeldPending(pending: boolean, minMs?: number): boolean;
+//# sourceMappingURL=held-pending.d.ts.map

package/dist/held-pending.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"held-pending.d.ts","sourceRoot":"","sources":["../src/held-pending.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,SAAM,GAAG,OAAO,CAmBrE"}

package/dist/held-pending.js

@@ -0,0 +1,36 @@
+import { useEffect, useRef, useState } from "react";
+// A refresh that answers in 80 ms flips its `pending` flag on and off inside a frame or two. The
+// reader pressed the button, nothing on screen changed, and the page looks like it ignored them.
+// A louder spinner does not fix that, because the spinner is never painted. The flag itself has
+// to stay on long enough to be seen.
+/**
+ * `pending`, kept on for at least `minMs` once it turns on.
+ *
+ * It answers `true` on the very render `pending` turns true, with no wait for an effect, so the
+ * busy state shows on the press and not a frame later. A slow request is not made slower: the
+ * hold only fills the gap when the request ended early, and ends within one timer tick of it
+ * otherwise.
+ *
+ * 400 ms is the floor for a busy state a person can read as "it ran". Use it for a button's busy
+ * look, a refresh icon, a save that returns at once. Do not use it to gate real work: it changes
+ * what is shown, never what the request does.
+ */
+export function useHeldPending(pending, minMs = 400) {
+    const [held, setHeld] = useState(false);
+    const startedAt = useRef(0);
+    // Raised while rendering, not in an effect, so there is no frame where `pending` is true and the
+    // hold is not. It only ever turns on here. The timer below is the one place it turns off.
+    if (pending && !held)
+        setHeld(true);
+    useEffect(() => {
+        if (pending) {
+            startedAt.current = Date.now();
+            return;
+        }
+        const remaining = Math.max(0, startedAt.current + minMs - Date.now());
+        const timer = setTimeout(() => setHeld(false), remaining);
+        return () => clearTimeout(timer);
+    }, [pending, minMs]);
+    return pending || held;
+}
+//# sourceMappingURL=held-pending.js.map

package/dist/held-pending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"held-pending.js","sourceRoot":"","sources":["../src/held-pending.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEpD,iGAAiG;AACjG,iGAAiG;AACjG,gGAAgG;AAChG,qCAAqC;AAErC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,KAAK,GAAG,GAAG;IAC1D,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAE5B,iGAAiG;IACjG,0FAA0F;IAC1F,IAAI,OAAO,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,EAAE,CAAC;YACZ,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC/B,OAAO;QACT,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACtE,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;QAC1D,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IAErB,OAAO,OAAO,IAAI,IAAI,CAAC;AACzB,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { cn } from "./cn.ts";
 export { copyText, useCopy, type CopyOptions, type CopyState } from "./copy.ts";
+export { BusyRing } from "./busy-ring.tsx";
+export { useHeldPending } from "./held-pending.ts";
 export { returnPathFromLocation, safeInternalPath, type PathParts } from "./internal-path.ts";
 export { forgetAuthEmail, recallAuthEmail, rememberAuthEmail } from "./auth-email.ts";
 export { ApiError, isAbortError } from "./api-error.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -31,6 +31,8 @@
 // identical in source.
 export { cn } from "./cn.js";
 export { copyText, useCopy } from "./copy.js";
+export { BusyRing } from "./busy-ring.js";
+export { useHeldPending } from "./held-pending.js";
 export { returnPathFromLocation, safeInternalPath } from "./internal-path.js";
 export { forgetAuthEmail, recallAuthEmail, rememberAuthEmail } from "./auth-email.js";
 export { ApiError, isAbortError } from "./api-error.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,4FAA4F;AAC5F,8FAA8F;AAC9F,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,GAGZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GASb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,4FAA4F;AAC5F,8FAA8F;AAC9F,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,GAGZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GASb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.26",
+  "version": "0.9.27",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",

package/src/busy-ring.tsx

@@ -0,0 +1,14 @@
+/**
+ * The ring that runs round a busy control's edge. Put it inside the control while it is busy.
+ *
+ * It draws nothing by itself: the look lives in `@gusnips/tokens/busy-ring.css`, which you import
+ * once. The control needs `position: relative` and the radius it already has (the ring copies it),
+ * and its disabled style must not dim it, or the ring is drawn at half strength and nobody sees it.
+ *
+ * Why a component for one `span`: the class name and the markup are one contract. Changing how
+ * busy looks, a second element or another shape, is then one edit here and one release, not one
+ * edit in every product's button.
+ */
+export function BusyRing() {
+  return <span aria-hidden="true" className="busy-ring" />;
+}

package/src/held-pending.test.ts

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useHeldPending } from "./held-pending.ts";
+
+// A refresh that answers in 80 ms flipped `pending` on and off inside a frame, so the button never
+// visibly changed and the reader thought the press was ignored. The flag has to stay on for the
+// minimum once it turns on, and a slow request must not be made to wait any longer.
+
+vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+
+const roots = new Set<Root>();
+
+beforeEach(() => vi.useFakeTimers());
+
+afterEach(() => {
+  for (const root of roots) act(() => root.unmount());
+  roots.clear();
+  document.body.replaceChildren();
+  vi.useRealTimers();
+});
+
+function mount(initial: boolean, minMs?: number) {
+  const element = document.createElement("div");
+  document.body.append(element);
+  const root = createRoot(element);
+  roots.add(root);
+  const seen: boolean[] = [];
+
+  function Probe({ pending }: { pending: boolean }) {
+    const held = useHeldPending(pending, minMs);
+    seen.push(held);
+    return null;
+  }
+
+  const render = (pending: boolean) => act(() => root.render(createElement(Probe, { pending })));
+  render(initial);
+  return { render, current: () => seen.at(-1) };
+}
+
+describe("useHeldPending", () => {
+  it("is false while nothing is pending", () => {
+    expect(mount(false).current()).toBe(false);
+  });
+
+  it("is true on the very render pending starts true, with no wait for an effect", () => {
+    const { render, current } = mount(false);
+    render(true);
+    expect(current()).toBe(true);
+  });
+
+  it("holds a request that ended early until the minimum has passed", () => {
+    const { render, current } = mount(false, 400);
+    render(true);
+    act(() => void vi.advanceTimersByTime(80));
+    render(false);
+    expect(current()).toBe(true);
+    act(() => void vi.advanceTimersByTime(319));
+    expect(current()).toBe(true);
+    act(() => void vi.advanceTimersByTime(1));
+    expect(current()).toBe(false);
+  });
+
+  it("does not make a slow request wait longer than one timer tick", () => {
+    const { render, current } = mount(false, 400);
+    render(true);
+    act(() => void vi.advanceTimersByTime(900));
+    render(false);
+    act(() => void vi.advanceTimersByTime(0));
+    expect(current()).toBe(false);
+  });
+
+  it("starts the clock again when it turns on a second time", () => {
+    const { render, current } = mount(false, 400);
+    render(true);
+    act(() => void vi.advanceTimersByTime(100));
+    render(false);
+    act(() => void vi.advanceTimersByTime(300));
+    expect(current()).toBe(false);
+    render(true);
+    act(() => void vi.advanceTimersByTime(50));
+    render(false);
+    expect(current()).toBe(true);
+    act(() => void vi.advanceTimersByTime(350));
+    expect(current()).toBe(false);
+  });
+});

package/src/held-pending.ts

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "react";
+
+// A refresh that answers in 80 ms flips its `pending` flag on and off inside a frame or two. The
+// reader pressed the button, nothing on screen changed, and the page looks like it ignored them.
+// A louder spinner does not fix that, because the spinner is never painted. The flag itself has
+// to stay on long enough to be seen.
+
+/**
+ * `pending`, kept on for at least `minMs` once it turns on.
+ *
+ * It answers `true` on the very render `pending` turns true, with no wait for an effect, so the
+ * busy state shows on the press and not a frame later. A slow request is not made slower: the
+ * hold only fills the gap when the request ended early, and ends within one timer tick of it
+ * otherwise.
+ *
+ * 400 ms is the floor for a busy state a person can read as "it ran". Use it for a button's busy
+ * look, a refresh icon, a save that returns at once. Do not use it to gate real work: it changes
+ * what is shown, never what the request does.
+ */
+export function useHeldPending(pending: boolean, minMs = 400): boolean {
+  const [held, setHeld] = useState(false);
+  const startedAt = useRef(0);
+
+  // Raised while rendering, not in an effect, so there is no frame where `pending` is true and the
+  // hold is not. It only ever turns on here. The timer below is the one place it turns off.
+  if (pending && !held) setHeld(true);
+
+  useEffect(() => {
+    if (pending) {
+      startedAt.current = Date.now();
+      return;
+    }
+    const remaining = Math.max(0, startedAt.current + minMs - Date.now());
+    const timer = setTimeout(() => setHeld(false), remaining);
+    return () => clearTimeout(timer);
+  }, [pending, minMs]);
+
+  return pending || held;
+}

package/src/index.ts

@@ -32,6 +32,8 @@
 
 export { cn } from "./cn.ts";
 export { copyText, useCopy, type CopyOptions, type CopyState } from "./copy.ts";
+export { BusyRing } from "./busy-ring.tsx";
+export { useHeldPending } from "./held-pending.ts";
 export { returnPathFromLocation, safeInternalPath, type PathParts } from "./internal-path.ts";
 
 export { forgetAuthEmail, recallAuthEmail, rememberAuthEmail } from "./auth-email.ts";