@gusnips/react 0.9.12 → 0.9.13

package/README.md

@@ -417,6 +417,27 @@ In jsdom tests, mock `window.matchMedia`, which jsdom does not have, and run
 `delete window.__frontkitTheme` between tests. There is one controller per page, and a jsdom
 window lasts the whole file.
 
+## A copy button that says when it failed
+
+```tsx
+import { useCopy } from "@gusnips/react";
+
+const { state, copy } = useCopy();
+
+<button onClick={() => void copy(apiKey)} aria-live="polite">
+  {state === "copied" ? "Copied" : state === "failed" ? "Select it and copy it yourself" : "Copy"}
+</button>;
+```
+
+Of eight copy buttons we read, five failed without a word, so the reader pasted whatever was
+already on the clipboard. Two more threw on a page served without https, where there is no
+clipboard API. `useCopy` shows `"copied"` for 2 seconds or `"failed"` for 6, then goes back to
+`"idle"`, and a second copy restarts the clock. `copy` resolves `false` instead of throwing, so a
+toast needs no `catch`. Outside a component, `copyText(text)` does the write on its own.
+
+The words are yours, and so is the live region: a label that changes needs `aria-live` to be
+heard.
+
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
@@ -459,6 +480,8 @@ writes you no longer own.
 The main entry works in React Native. It imports `react` and nothing else you would have to go
 find — no `react-dom`, no router, no store — so the fetch client, the retry rule and the SSE
 parser all come along, and the four things that need a browser stay behind the subpaths above.
+`useCopy` imports fine there but has no `navigator.clipboard` to write to, so every copy answers
+`"failed"`: use the platform's clipboard on a phone.
 
 ## The Base UI wrappers
 

package/dist/copy.d.ts

@@ -0,0 +1,23 @@
+/** Write `text` to the clipboard. `false` when the browser refused or has no clipboard API. */
+export declare function copyText(text: string): Promise<boolean>;
+export type CopyState = "idle" | "copied" | "failed";
+export interface CopyOptions {
+    /** How long `"copied"` shows. Default 2000 ms. */
+    copiedMs?: number;
+    /** How long `"failed"` shows. Default 6000 ms: a failure is a sentence the reader has to act on. */
+    failedMs?: number;
+}
+/**
+ * A copy with an outcome the reader can see. What it says stays yours — "Copied", or "Select it
+ * and copy it yourself", in a label or a toast — and so does announcing it: a label that changes
+ * needs `aria-live="polite"` to be heard.
+ *
+ * The outcome goes back to `"idle"` on its own. A "Copied" that never clears makes the second copy
+ * look like it did not take.
+ */
+export declare function useCopy({ copiedMs, failedMs }?: CopyOptions): {
+    state: CopyState;
+    /** Resolves `false` instead of throwing, so a caller can toast without a `catch`. */
+    copy: (text: string) => Promise<boolean>;
+};
+//# sourceMappingURL=copy.d.ts.map

package/dist/copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.d.ts","sourceRoot":"","sources":["../src/copy.ts"],"names":[],"mappings":"AAWA,+FAA+F;AAC/F,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7D;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,EAAE,QAAe,EAAE,QAAe,EAAE,GAAE,WAAgB,GAAG;IAC/E,KAAK,EAAE,SAAS,CAAC;IACjB,qFAAqF;IACrF,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C,CAmBA"}

package/dist/copy.js

@@ -0,0 +1,46 @@
+import { useCallback, useEffect, useState } from "react";
+// Eight products wrote a copy button, and five of them failed silently, one under a comment
+// saying it must not. Silent is worse than it looks: the reader pastes whatever was already on
+// the clipboard, and for a key shown once that is pasting something else over the only copy.
+// Two more called `writeText` outside a `try`, and on a page not served over https there is no
+// `navigator.clipboard` at all, so the click threw a TypeError instead of rejecting.
+//
+// No `execCommand` fallback, and none of the eight had one: it is deprecated, the async API is
+// there in every browser over https, and a copy that says it failed beats a shim that pretends.
+/** Write `text` to the clipboard. `false` when the browser refused or has no clipboard API. */
+export async function copyText(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A copy with an outcome the reader can see. What it says stays yours — "Copied", or "Select it
+ * and copy it yourself", in a label or a toast — and so does announcing it: a label that changes
+ * needs `aria-live="polite"` to be heard.
+ *
+ * The outcome goes back to `"idle"` on its own. A "Copied" that never clears makes the second copy
+ * look like it did not take.
+ */
+export function useCopy({ copiedMs = 2000, failedMs = 6000 } = {}) {
+    // A new object on every copy, so copying again restarts the clock even when the state is the
+    // same: two copies a second apart read "Copied" for two seconds after the second one.
+    const [outcome, setOutcome] = useState({ state: "idle" });
+    useEffect(() => {
+        if (outcome.state === "idle")
+            return;
+        const ms = outcome.state === "copied" ? copiedMs : failedMs;
+        const timer = setTimeout(() => setOutcome({ state: "idle" }), ms);
+        return () => clearTimeout(timer);
+    }, [outcome, copiedMs, failedMs]);
+    const copy = useCallback(async (text) => {
+        const copied = await copyText(text);
+        setOutcome({ state: copied ? "copied" : "failed" });
+        return copied;
+    }, []);
+    return { state: outcome.state, copy };
+}
+//# sourceMappingURL=copy.js.map

package/dist/copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.js","sourceRoot":"","sources":["../src/copy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEzD,4FAA4F;AAC5F,+FAA+F;AAC/F,6FAA6F;AAC7F,+FAA+F;AAC/F,qFAAqF;AACrF,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAEhG,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,IAAI,KAAkB,EAAE;IAK5E,6FAA6F;IAC7F,sFAAsF;IACtF,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAuB,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAEhF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,CAAC,KAAK,KAAK,MAAM;YAAE,OAAO;QACrC,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAClE,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IAElC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;QAC9C,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QACpD,OAAO,MAAM,CAAC;IAChB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { cn } from "./cn.ts";
+export { copyText, useCopy, type CopyOptions, type CopyState } from "./copy.ts";
 export { returnPathFromLocation, safeInternalPath, type PathParts } from "./internal-path.ts";
 export { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";
 export { createApiClient, type ApiClient, type ApiClientOptions, type RefreshResult, type RequestOptions, type SessionAdapter, } from "./api-client.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,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,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,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,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,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,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

@@ -30,6 +30,7 @@
 // Check that claim against `dist/`, never against this file: a type-only re-export looks
 // identical in source.
 export { cn } from "./cn.js";
+export { copyText, useCopy } from "./copy.js";
 export { returnPathFromLocation, safeInternalPath } from "./internal-path.js";
 export { ApiError, isAbortError, retryAfterSecs } from "./api-error.js";
 export { createApiClient, } from "./api-client.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,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,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,GAQb,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,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,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,GAQb,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.12",
+  "version": "0.9.13",
   "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",
@@ -80,7 +80,7 @@
     "release:major": "bun pm version major && bun publish --access public"
   },
   "dependencies": {
-    "@gusnips/http": "0.1.0",
+    "@gusnips/http": "0.1.1",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.6.0"
   },

package/src/copy.test.ts

@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { copyText } from "./copy.ts";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("copyText", () => {
+  it("answers true once the clipboard has the text", async () => {
+    const writeText = vi.fn(() => Promise.resolve());
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+    await expect(copyText("sk_live_1")).resolves.toBe(true);
+    expect(writeText).toHaveBeenCalledWith("sk_live_1");
+  });
+
+  it("answers false when the browser refuses the write", async () => {
+    vi.stubGlobal("navigator", {
+      clipboard: { writeText: () => Promise.reject(new DOMException("denied", "NotAllowedError")) },
+    });
+    await expect(copyText("sk_live_1")).resolves.toBe(false);
+  });
+
+  // Over plain http there is no `navigator.clipboard`, so `writeText` is read off `undefined` and
+  // throws before any promise exists. Two copies in the fleet let that escape the click handler.
+  it("answers false, and does not throw, where there is no clipboard API", async () => {
+    vi.stubGlobal("navigator", {});
+    await expect(copyText("sk_live_1")).resolves.toBe(false);
+  });
+});

package/src/copy.ts

@@ -0,0 +1,62 @@
+import { useCallback, useEffect, useState } from "react";
+
+// Eight products wrote a copy button, and five of them failed silently, one under a comment
+// saying it must not. Silent is worse than it looks: the reader pastes whatever was already on
+// the clipboard, and for a key shown once that is pasting something else over the only copy.
+// Two more called `writeText` outside a `try`, and on a page not served over https there is no
+// `navigator.clipboard` at all, so the click threw a TypeError instead of rejecting.
+//
+// No `execCommand` fallback, and none of the eight had one: it is deprecated, the async API is
+// there in every browser over https, and a copy that says it failed beats a shim that pretends.
+
+/** Write `text` to the clipboard. `false` when the browser refused or has no clipboard API. */
+export async function copyText(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type CopyState = "idle" | "copied" | "failed";
+
+export interface CopyOptions {
+  /** How long `"copied"` shows. Default 2000 ms. */
+  copiedMs?: number;
+  /** How long `"failed"` shows. Default 6000 ms: a failure is a sentence the reader has to act on. */
+  failedMs?: number;
+}
+
+/**
+ * A copy with an outcome the reader can see. What it says stays yours — "Copied", or "Select it
+ * and copy it yourself", in a label or a toast — and so does announcing it: a label that changes
+ * needs `aria-live="polite"` to be heard.
+ *
+ * The outcome goes back to `"idle"` on its own. A "Copied" that never clears makes the second copy
+ * look like it did not take.
+ */
+export function useCopy({ copiedMs = 2000, failedMs = 6000 }: CopyOptions = {}): {
+  state: CopyState;
+  /** Resolves `false` instead of throwing, so a caller can toast without a `catch`. */
+  copy: (text: string) => Promise<boolean>;
+} {
+  // A new object on every copy, so copying again restarts the clock even when the state is the
+  // same: two copies a second apart read "Copied" for two seconds after the second one.
+  const [outcome, setOutcome] = useState<{ state: CopyState }>({ state: "idle" });
+
+  useEffect(() => {
+    if (outcome.state === "idle") return;
+    const ms = outcome.state === "copied" ? copiedMs : failedMs;
+    const timer = setTimeout(() => setOutcome({ state: "idle" }), ms);
+    return () => clearTimeout(timer);
+  }, [outcome, copiedMs, failedMs]);
+
+  const copy = useCallback(async (text: string) => {
+    const copied = await copyText(text);
+    setOutcome({ state: copied ? "copied" : "failed" });
+    return copied;
+  }, []);
+
+  return { state: outcome.state, copy };
+}

package/src/index.ts

@@ -31,6 +31,7 @@
 // identical in source.
 
 export { cn } from "./cn.ts";
+export { copyText, useCopy, type CopyOptions, type CopyState } from "./copy.ts";
 export { returnPathFromLocation, safeInternalPath, type PathParts } from "./internal-path.ts";
 
 export { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";