@gusnips/react 0.9.23 → 0.9.25

package/src/auth-email.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { forgetAuthEmail, recallAuthEmail, rememberAuthEmail } from "./auth-email.ts";
+
+const KEY = "frontkit.auth-email";
+const MINUTE = 60 * 1000;
+
+/**
+ * `localStorage` stubbed rather than run under a DOM, the same call as `theme.test.ts`. What
+ * matters is what a browser does at the edges: site data blocked (every method throws), a quota
+ * that refuses new writes while old ones stay readable, and a page with no storage at all.
+ */
+function storage({ blocked = false }: { blocked?: boolean } = {}) {
+  const store = new Map<string, string>();
+  const state = { blocked, full: false };
+  vi.stubGlobal("localStorage", {
+    getItem: (key: string) => {
+      if (state.blocked) throw new Error("site data blocked");
+      return store.get(key) ?? null;
+    },
+    setItem: (key: string, value: string) => {
+      if (state.blocked || state.full) throw new Error("site data blocked");
+      store.set(key, value);
+    },
+    removeItem: (key: string) => {
+      if (state.blocked) throw new Error("site data blocked");
+      store.delete(key);
+    },
+  });
+  return { store, state };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date("2026-10-08T10:00:00Z"));
+});
+
+afterEach(() => {
+  forgetAuthEmail();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("remember and recall", () => {
+  it("starts empty", () => {
+    storage();
+    expect(recallAuthEmail()).toBe("");
+  });
+
+  it("hands back what was typed, as typed", () => {
+    storage();
+    rememberAuthEmail(" Ana@Example.com ");
+    expect(recallAuthEmail()).toBe(" Ana@Example.com ");
+  });
+
+  it("writes to localStorage, so a new tab opened from a mail finds it", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    expect(JSON.parse(store.get(KEY) ?? "null")).toMatchObject({ email: "ana@example.com" });
+  });
+
+  it("empties when the field is cleared", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    rememberAuthEmail("");
+    expect(recallAuthEmail()).toBe("");
+    expect(store.has(KEY)).toBe(false);
+  });
+
+  it("keeps the last good value when handed something longer than an address can be", () => {
+    storage();
+    rememberAuthEmail("ana@example.com");
+    rememberAuthEmail("a".repeat(255));
+    expect(recallAuthEmail()).toBe("ana@example.com");
+  });
+
+  it("forgets on request", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    forgetAuthEmail();
+    expect(recallAuthEmail()).toBe("");
+    expect(store.has(KEY)).toBe(false);
+  });
+});
+
+describe("the thirty minutes", () => {
+  it("lets go after thirty minutes of nothing, and deletes what it found", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    vi.advanceTimersByTime(30 * MINUTE);
+    expect(recallAuthEmail()).toBe("ana@example.com");
+    vi.advanceTimersByTime(1);
+    expect(recallAuthEmail()).toBe("");
+    expect(store.has(KEY)).toBe(false);
+  });
+
+  it("renews on every keystroke", () => {
+    storage();
+    rememberAuthEmail("ana@example.com");
+    vi.advanceTimersByTime(25 * MINUTE);
+    rememberAuthEmail("ana@example.com.br");
+    vi.advanceTimersByTime(25 * MINUTE);
+    expect(recallAuthEmail()).toBe("ana@example.com.br");
+  });
+});
+
+describe("when the browser will not store it", () => {
+  it("falls back to memory when site data is blocked", () => {
+    storage({ blocked: true });
+    rememberAuthEmail("ana@example.com");
+    expect(recallAuthEmail()).toBe("ana@example.com");
+    forgetAuthEmail();
+    expect(recallAuthEmail()).toBe("");
+  });
+
+  it("falls back to memory when there is no localStorage at all", () => {
+    vi.stubGlobal("localStorage", undefined);
+    rememberAuthEmail("ana@example.com");
+    expect(recallAuthEmail()).toBe("ana@example.com");
+  });
+
+  it("prefers the newer address when a full quota left an older one in storage", () => {
+    const { state } = storage();
+    rememberAuthEmail("old@example.com");
+    state.full = true;
+    vi.advanceTimersByTime(MINUTE);
+    rememberAuthEmail("new@example.com");
+    expect(recallAuthEmail()).toBe("new@example.com");
+  });
+
+  it("prefers what another tab wrote after this tab's memory went stale", () => {
+    const { store } = storage();
+    rememberAuthEmail("old@example.com");
+    vi.advanceTimersByTime(MINUTE);
+    store.set(KEY, JSON.stringify({ email: "new@example.com", at: Date.now() }));
+    expect(recallAuthEmail()).toBe("new@example.com");
+  });
+
+  it("ignores a stored value that is not ours", () => {
+    const { store } = storage();
+    store.set(KEY, "{not json");
+    expect(recallAuthEmail()).toBe("");
+    store.set(KEY, JSON.stringify({ email: 42, at: "now" }));
+    expect(recallAuthEmail()).toBe("");
+  });
+});

package/src/auth-email.ts

@@ -0,0 +1,112 @@
+/**
+ * The email a person has typed during sign-in, kept so the next auth screen opens with it filled.
+ *
+ * Sign-in, "use a code instead", "forgot password" and "create account" are separate screens, and
+ * each one used to start with an empty email field. Someone who typed their address, then chose
+ * another way in, typed it again. The fix is the same everywhere, so it lives here once.
+ *
+ * ```tsx
+ * <input name="email" type="email" defaultValue={recallAuthEmail()}
+ *   onChange={(event) => rememberAuthEmail(event.currentTarget.value)} />
+ * ```
+ *
+ * - **Not in the URL.** A query string rides in `Referer`, in access logs, in history and in every
+ *   analytics tool that records page addresses. An email is personal data and has no business there.
+ * - **`localStorage`, not `sessionStorage`.** An emailed link opens in a new tab, and a new tab
+ *   does not inherit `sessionStorage`. The person who confirms their account from the mail lands
+ *   on sign-in in that new tab, which is the screen that most needs the address.
+ * - **Thirty minutes, sliding.** Long enough to read a code in a mail client and come back; short
+ *   enough that a shared computer forgets. Every keystroke renews it, and a value found expired is
+ *   deleted when it is read, so it does not sit on disk afterwards.
+ * - **Memory behind it.** A browser that blocks site data throws on `localStorage` itself, and
+ *   React Native has none. The value then lasts until the page (or the app) is left, which still
+ *   covers moving between screens.
+ *
+ * Read it once when a screen opens, as a default value. It is not a live store: nothing re-renders
+ * when it changes, and a prerendered page must read it after hydration, never while rendering.
+ * Never put a password, a code or a token here. Call `forgetAuthEmail()` once a session exists, so
+ * the next person at this browser starts empty.
+ */
+
+const KEY = "frontkit.auth-email";
+const TTL_MS = 30 * 60 * 1000;
+/** The longest an address can be (RFC 5321). A longer value is not one, and is not kept. */
+const MAX_LENGTH = 254;
+
+interface Saved {
+  email: string;
+  at: number;
+}
+
+let memory: Saved | null = null;
+
+function isSaved(value: unknown): value is Saved {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "email" in value &&
+    typeof value.email === "string" &&
+    "at" in value &&
+    typeof value.at === "number"
+  );
+}
+
+function readStored(): Saved | null {
+  try {
+    const raw = globalThis.localStorage?.getItem(KEY);
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    return isSaved(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Storage and memory are written together, so they only differ when one of them missed a write:
+ * storage that is full keeps an older address while memory holds the new one, and a second tab
+ * writes storage while this tab's memory goes stale. The newer of the two is the one the person
+ * typed last.
+ */
+function newest(): Saved | null {
+  const stored = readStored();
+  if (!stored || !memory) return stored ?? memory;
+  return stored.at >= memory.at ? stored : memory;
+}
+
+/** The address typed earlier in this sign-in, or an empty string when there is none. */
+export function recallAuthEmail(): string {
+  const saved = newest();
+  if (!saved) return "";
+  if (Date.now() - saved.at > TTL_MS) {
+    forgetAuthEmail();
+    return "";
+  }
+  return saved.email;
+}
+
+/**
+ * Keep what the person has typed. Call it from the email field's change handler, so every screen
+ * they reach next can open with it. The value is stored as typed: trim it where you submit it.
+ * An empty value forgets.
+ */
+export function rememberAuthEmail(value: string): void {
+  if (value === "") return forgetAuthEmail();
+  if (value.length > MAX_LENGTH) return;
+  memory = { email: value, at: Date.now() };
+  try {
+    globalThis.localStorage?.setItem(KEY, JSON.stringify(memory));
+  } catch {
+    // Blocked or full: the memory copy above carries it until the page is left.
+  }
+}
+
+/** Drop it. Call this once a session exists, so the next person at this browser starts empty. */
+export function forgetAuthEmail(): void {
+  memory = null;
+  try {
+    globalThis.localStorage?.removeItem(KEY);
+  } catch {
+    // Blocked: nothing was stored, so there is nothing to drop.
+  }
+}

package/src/auth-store.ts

@@ -3,14 +3,14 @@ import { create, type StoreApi, type UseBoundStore } from "zustand";
 /**
  * Session FLAGS only.
  *
- * Who the person is — their plan, their staff bit, whether they are suspended — comes from
- * `GET /auth/me` through react-query, never from here. Mirroring server state in a client store
- * is how two sources of truth start disagreeing, and the one that is wrong is always the one on
- * screen. Three repos wrote this same store; two of them wrote that same warning in a comment.
+ * Who the person is, including their plan, staff bit and suspension status, comes from `GET
+ * /auth/me` through react-query, never from here. Mirroring server state in a client store is how
+ * two sources of truth start disagreeing, and the one that is wrong is always the one on screen.
+ * Three repos wrote this same store; two of them wrote that same warning in a comment.
  *
  * `TUser` stays generic because it is the one part that differs: one product carries an
- * anonymous-browsing flag, another does not. Keep it to what a GUARD needs — an id and an
- * email is what all three donors had.
+ * anonymous-browsing flag, another does not. Keep it to what a GUARD needs. All three donors had an
+ * id and an email.
  */
 export interface AuthState<TUser> {
   user: TUser | null;
@@ -21,10 +21,10 @@ export interface AuthState<TUser> {
    */
   isLoading: boolean;
   /**
-   * Set (or clear) the signed-in user. This ENDS the loading state — knowing who they are is
-   * what the bootstrap was waiting for. Two of the three donors left `isLoading` alone here and
-   * relied on a separate `setLoading(false)`; forgetting that call leaves every guard spinning,
-   * so the safe default is to do it in one write.
+   * Set (or clear) the signed-in user. This ENDS the loading state, because the bootstrap was
+   * waiting to learn who they are. Two of the three donors left `isLoading` alone here and relied
+   * on a separate `setLoading(false)`; forgetting that call leaves every guard spinning, so the
+   * safe default is to do it in one write.
    */
   setUser: (user: TUser | null) => void;
   setLoading: (isLoading: boolean) => void;
@@ -38,12 +38,12 @@ export interface AuthState<TUser> {
  * The whole reason this is a factory and not a store: `isLoading` must start FALSE where there
  * is no window, and only a factory can decide that at the call site rather than at import.
  *
- * A session bootstrap can only be in flight in a browser. The BUILD renders this app to files
- * with no window at all, so `true` there is a wait that never ends — one donor shipped a route
- * guard holding its loading screen forever, and prerendered a public page as 1,174 bytes of
- * `role="status"`: a spinner as the indexable body of a page whose entire purpose was to be
- * found. With no browser there is no session and never will be, which is exactly the state a
- * first-time visitor arrives in, so that is what the page should render.
+ * A session bootstrap can only be in flight in a browser. The BUILD renders this app to files with
+ * no window at all, so `true` there is a wait that never ends. One donor shipped a route guard
+ * holding its loading screen forever, and prerendered a public page as 1,174 bytes of
+ * `role="status"`: a spinner as the indexable body of a page whose entire purpose was to be found.
+ * With no browser there is no session and never will be, which is exactly the state a first-time
+ * visitor arrives in, so that is what the page should render.
  *
  * Only one of the three donors knew this. It is invariant 7.
  */
@@ -70,13 +70,13 @@ type AuthSet<TUser, TExtra> = (
 /**
  * The session flags as a plain object, for a product whose store needs more than them.
  *
- * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product
- * cannot wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that
- * met it had a superset and neither could use it. One holds a remember-me choice, a profile row
- * and the sign-in methods themselves, under `persist`. The other adds `isAnonymous` — and that
- * one is the reason this takes a `derive` function rather than just letting the caller spread
- * extra keys in: `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and
- * `clear`, which are exactly the two writes the product does not own.
+ * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product cannot
+ * wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that met it had
+ * a superset and neither could use it. One holds a remember-me choice, a profile row and the
+ * sign-in methods themselves, under `persist`. The other adds `isAnonymous`, which is the reason
+ * this takes a `derive` function rather than just letting the caller spread extra keys in:
+ * `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and `clear`, which are
+ * exactly the two writes the product does not own.
  *
  * The caller keeps `create`, so middleware, extra actions and the store's own name stay theirs:
  *

package/src/copy.ts

@@ -29,9 +29,9 @@ export interface CopyOptions {
 }
 
 /**
- * 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.
+ * A copy with an outcome the reader can see. You choose what it says, such as "Copied" or "Select
+ * it and copy it yourself", in a label or a toast. You also choose how to announce 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.

package/src/deploy-recovery.ts

@@ -5,26 +5,26 @@
  * every hashed asset underneath whatever tabs are already open, and those tabs go on running
  * yesterday's bundle. It surfaces two ways, and only one of them looks like a missing file:
  *
- *   1. The next navigation asks for a chunk whose hashed name is gone. React's lazy boundary
- *      throws, and the person gets a white screen on a click that worked a minute ago.
- *   2. The old bundle reads a field the API has since renamed, and throws. That one arrives as a
- *      plain `TypeError` with nothing in it about a deploy — no file, no hash, no signal.
+ * 1. The next navigation asks for a chunk whose hashed name is gone. React's lazy boundary throws,
+ * and the person gets a white screen on a click that worked a minute ago. 2. The old bundle reads a
+ * field the API has since renamed, and throws. That one arrives as a plain `TypeError` with nothing
+ * in it about a deploy: no file, no hash, no signal.
  *
  * So there are two detectors here and they are not interchangeable. {@link isChunkLoadError}
- * matches the message, which is all you have for a failure that never reaches a boundary.
- * {@link isStaleBuild} asks the server, which is evidence rather than a guess — and it is the
- * only one that catches case 2 at all.
+ * matches the message, which is all you have for a failure that never reaches a boundary. {@link
+ * isStaleBuild} asks the server for evidence rather than a guess. It is the only one that catches
+ * case 2 at all.
  *
  * **The deepest fix is not in this file, and it is worth more than everything in it.** A static
- * host answers a missing `/assets/x.js` with the SPA fallback — `index.html`, at a 200, as
- * `text/html` — which is what the browser's "MIME type text/html" module-script refusal actually
- * is. Hosts then match cache rules against the REQUEST PATH rather than the outcome, so the
- * `immutable, max-age=31536000` rule written for hashed assets gets applied to that HTML body:
- * one poisoned asset URL, at the edge and in every browser that touched it, for a year. One
- * adopter removed the cause instead of recovering from it — no blanket fallback over `/assets/`,
- * and an edge function that refuses to answer an asset path with `text/html` — which turns a
- * dead chunk into a real, uncacheable 404 and lets everything below be recovery rather than the
- * plan. A package cannot ship that; it can refuse to let it go unwritten.
+ * host answers a missing `/assets/x.js` with the SPA fallback, `index.html`, at a 200, as
+ * `text/html`. That is what the browser's "MIME type text/html" module-script refusal actually is.
+ * Hosts then match cache rules against the REQUEST PATH rather than the outcome, so the `immutable,
+ * max-age=31536000` rule written for hashed assets gets applied to that HTML body: one poisoned
+ * asset URL, at the edge and in every browser that touched it, for a year. One adopter removed the
+ * cause instead of recovering from it: no blanket fallback over `/assets/`, and an edge function
+ * that refuses to answer an asset path with `text/html`. That turns a dead chunk into a real,
+ * uncacheable 404 and lets everything below be recovery rather than the plan. A package cannot ship
+ * that; it can refuse to let it go unwritten.
  */
 
 /**
@@ -48,14 +48,14 @@ const RELOAD_WINDOW_MS = 60_000;
 const PROBE_TIMEOUT_MS = 4_000;
 
 /**
- * A lazy-chunk fetch failure — recoverable by reloading.
+ * A lazy-chunk fetch failure that a reload can fix.
  *
- * Matched by message because no browser gives it a shared type. Every phrasing in the wild is
- * here: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading
- * dynamically imported module", Safari "Importing a module script failed", webpack's
- * ChunkLoadError and "Loading chunk N failed", and the SPA-fallback "MIME type" refusal —
- * which is the one that fires on a static host that has not fixed the cause above, because the
- * missing `.js` is answered with `index.html`.
+ * Matched by message because no browser gives it a shared type. Every phrasing in the wild is here:
+ * Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading dynamically
+ * imported module", Safari "Importing a module script failed", webpack's ChunkLoadError and
+ * "Loading chunk N failed", and the SPA-fallback "MIME type" refusal. The last one that fires on a
+ * static host that has not fixed the cause above, because the missing `.js` is answered with
+ * `index.html`.
  *
  * A standalone predicate rather than a method on the boundary, so a global `unhandledrejection`
  * handler can classify the same failure without importing a component.
@@ -93,13 +93,13 @@ function runningEntry(): string {
 /**
  * Is the build this tab is running still the one being served?
  *
- * Asked of the server, so the answer is evidence rather than a guess. Everything ambiguous —
- * offline, a non-200, a captive portal, a probe that times out — resolves to `false`: dressing a
- * genuine bug up as an update hides it from the user and from us.
+ * Asked of the server, so the answer is evidence rather than a guess. An offline request, a non-200
+ * response, a captive portal or a timed-out probe resolves to `false`: dressing a genuine bug up as
+ * an update hides it from the user and from us.
  *
  * It asks for the PAGE, not for the asset, and that is not the obvious choice. A missing asset
  * looks like the direct question, but a CDN commonly serves assets with a long `s-maxage`, so a
- * bundle a deploy retired an hour ago still answers 200 from the edge — it would report "current"
+ * bundle a deploy retired an hour ago still answers 200 from the edge. It would report "current"
  * during exactly the window when skew is most likely. The page is the one URL that cannot lie: it
  * ships `max-age=0, must-revalidate` and never enters the edge cache.
  */
@@ -124,9 +124,9 @@ export async function isStaleBuild(): Promise<boolean> {
  * rather than watching the same attempt loop.
  *
  * The guard is the part that matters. Reloading on a failure is obvious; reloading on a failure
- * that the reload does not fix is an infinite loop with the user inside it. At most one reload
- * per minute, so a genuinely broken deploy degrades to the error screen — which can at least say
- * something — instead of flickering forever.
+ * that the reload does not fix is an infinite loop with the user inside it. At most one reload per
+ * minute, so a genuinely broken deploy shows the error screen instead of flickering forever. That
+ * screen can at least say something.
  *
  * `sessionStorage` and not `localStorage`: the guard is about this tab's current predicament, and
  * a stale stamp in another tab must not suppress a reload this one needs. Wrapped because storage
@@ -149,11 +149,11 @@ export function reloadOnce(): boolean {
 /**
  * Vite's *hint* failure, which is not the same thing and must not be treated as one.
  *
- * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it.
- * When that link fails, the import itself still runs right after and usually succeeds — so this
- * one is worth swallowing, where a failure of the import is the real thing
- * {@link isChunkLoadError} matches. Vite builds this message in exactly one place and only ever
- * for a stylesheet link; script hints never reject.
+ * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it. When
+ * that link fails, the import itself still runs right after and usually succeeds, so this one is
+ * worth swallowing, where a failure of the import is the real thing {@link isChunkLoadError}
+ * matches. Vite builds this message in exactly one place and only ever for a stylesheet link;
+ * script hints never reject.
  */
 export function isPreloadHintFailure(error: unknown): boolean {
   return error instanceof Error && error.message.startsWith("Unable to preload CSS for");
@@ -162,12 +162,12 @@ export function isPreloadHintFailure(error: unknown): boolean {
 /**
  * Install the `vite:preloadError` listener. Call once, from the browser entry.
  *
- * Vite offers `preventDefault()` here so an app can own a failed asset itself — but taking that
- * deal unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
+ * Vite offers `preventDefault()` here so an app can own a failed asset itself, but taking that deal
+ * unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
  * `baseModule().catch(handlePreloadError)`), and `React.lazy` then reads `.default` off nothing.
- * The user gets the crash screen and the developer gets a TypeError with only React frames in
- * it, naming no chunk. So it is taken ONLY for a failed preload hint, where the import still
- * runs. A real module failure is left to throw, where the error boundary can recognise it.
+ * The user gets the crash screen and the developer gets a TypeError with only React frames in it,
+ * naming no chunk. So it is taken ONLY for a failed preload hint, where the import still runs. A
+ * real module failure is left to throw, where the error boundary can recognise it.
  */
 export function installPreloadErrorHandler(): void {
   window.addEventListener("vite:preloadError", (event) => {