@gusnips/react 0.1.0

package/src/index.ts

@@ -0,0 +1,63 @@
+// @gusnips/react — the headless runtime under a Vite + React SPA.
+//
+// No styling, no brand, no Node built-ins.
+//
+// Three things live behind their own subpath, and the rule picking them is invariant 15 stated
+// as a test rather than a judgement: **a peer marked `optional` must not be reachable from this
+// barrel.** An optional peer the barrel imports anyway is not optional — it is a required peer
+// with the error moved from install time to the adopter's first build, which is the worse of the
+// two places to find out.
+//
+//   @gusnips/react/ui       the Base UI wrappers   → @base-ui/react
+//   @gusnips/react/store    createAuthStore        → zustand
+//   @gusnips/react/guards   the route guards       → react-router-dom
+//
+// So what is left here imports `react`, `react-dom` and `@gusnips/http` and nothing else, and an
+// app on TanStack Router or on Redux takes the fetch client without installing a router or a
+// store it will never call. `@tanstack/react-query`, `i18next` and `react-i18next` stay optional
+// AND stay here, because `query.ts`, `i18n.ts` and `states.ts` import only their TYPES — which
+// erase, so the built barrel does not reference them at runtime. Check that claim against
+// `dist/`, never against this file: a type-only re-export looks identical in source.
+
+export { cn } from "./cn.ts";
+
+export { ApiError, isAbortError } from "./api-error.ts";
+export {
+  createApiClient,
+  type ApiClient,
+  type ApiClientOptions,
+  type RefreshResult,
+  type RequestOptions,
+  type SessionAdapter,
+} from "./api-client.ts";
+export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
+
+export { queryDefaults, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
+
+export {
+  ErrorBoundary,
+  type ErrorBoundaryFallbackProps,
+  type ErrorBoundaryProps,
+} from "./error-boundary.tsx";
+export {
+  createErrorDescriber,
+  humanizeWait,
+  retryAfterSecs,
+  type DescribedError,
+  type ErrorContext,
+  type ErrorDescriberOptions,
+  type Translate,
+} from "./describe-error.ts";
+
+export {
+  installPreloadErrorHandler,
+  isChunkLoadError,
+  isPreloadHintFailure,
+  reloadOnceForChunkError,
+} from "./chunk-reload.ts";
+
+export { hydrateOrMount, PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./hydrate.ts";
+
+export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";
+
+export type { EmptyStateProps, ErrorStateProps } from "./states.ts";

package/src/prerender-contract.ts

@@ -0,0 +1,31 @@
+/**
+ * The two constants the build and the browser both need — and **nothing else in this file**.
+ *
+ * It is separate from `hydrate.ts` for one reason: that module imports `react-dom/client`, and
+ * `@gusnips/vite` needs these constants to WRITE the attribute at build time. If the constants
+ * lived beside the hydration helper, a build script asking for a string would pull the browser
+ * renderer into a Node process, and every `entry-server.tsx` that touched this package would do
+ * the same. Zero imports here is the whole point; keep it that way.
+ *
+ * The contract itself was invented three times independently, with the same name and the same
+ * string value each time. See `hydrate.ts` for why it exists at all.
+ */
+
+/**
+ * The attribute a prerendered file names its own route in — written by the build, read by the
+ * browser entry.
+ *
+ * One constant because the writer and the reader are in different builds, and a typo between
+ * them would show up only as a silent full re-render: a page that works, and a bug nobody sees.
+ */
+export const PRERENDERED_ROUTE_ATTR = "data-prerendered-route";
+
+/**
+ * What a 404 shell writes instead of a route.
+ *
+ * It is the pattern that actually matched — the catch-all — and it can never equal an address,
+ * which is the property that matters: every route a static host answers from the shell mounts
+ * fresh rather than hydrating the not-found page over itself. A real 404 pays one redundant
+ * client render for that, and keeps the markup a crawler reads.
+ */
+export const SHELL_ROUTE = "*";

package/src/query.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { ApiError } from "./api-error.ts";
+import { shouldRetry } from "./query.ts";
+
+const refusal = (status: number, code?: string) =>
+  new ApiError(status, code ? { code, message: code } : null);
+
+// Invariant 8, and the reason this module exists: three donors wrote three retry rules and
+// each was right about something the other two got wrong. Every case below is one of those.
+describe("shouldRetry", () => {
+  it("retries a request that never landed", () => {
+    // Offline, DNS, a dropped connection. Nothing about it is an answer.
+    expect(shouldRetry(new TypeError("Failed to fetch"))).toBe(true);
+  });
+
+  it("retries 5xx", () => {
+    expect(shouldRetry(refusal(500))).toBe(true);
+    expect(shouldRetry(refusal(503))).toBe(true);
+  });
+
+  it("does not retry a 4xx that is an answer", () => {
+    // A 402, a 403 and a 404 say exactly the same thing three times.
+    for (const status of [400, 401, 402, 403, 404, 409, 422, 451]) {
+      expect(shouldRetry(refusal(status))).toBe(false);
+    }
+  });
+
+  // Only one donor allowed this through, and it is the one 4xx a second attempt genuinely fixes.
+  it("retries 408", () => {
+    expect(shouldRetry(refusal(408))).toBe(true);
+  });
+
+  it("retries a burst 429", () => {
+    expect(shouldRetry(refusal(429, "RATE_LIMIT_EXCEEDED"))).toBe(true);
+  });
+
+  // The sharpest rule of the three, and only one donor had it. A spent monthly quota and an
+  // empty balance both arrive as 429 or 402, and neither clears by waiting — retrying burns
+  // another request against the limiter and cannot succeed. The status alone cannot tell them
+  // apart from a burst limit, which is why the caller names the codes.
+  it("does not retry a limit the code says is durable", () => {
+    const durable = ["QUOTA_EXCEEDED", "PAYMENT_REQUIRED"];
+    expect(shouldRetry(refusal(429, "QUOTA_EXCEEDED"), durable)).toBe(false);
+    expect(shouldRetry(refusal(402, "PAYMENT_REQUIRED"), durable)).toBe(false);
+    // …and the burst limit still retries, which is the distinction the whole rule is for.
+    expect(shouldRetry(refusal(429, "RATE_LIMIT_EXCEEDED"), durable)).toBe(true);
+  });
+
+  // A durable code wins even over a 5xx: if the server says the limit does not clear by
+  // waiting, its status code is not the more specific claim.
+  it("lets a durable code override the status", () => {
+    expect(shouldRetry(refusal(503, "QUOTA_EXCEEDED"), ["QUOTA_EXCEEDED"])).toBe(false);
+  });
+});

package/src/query.ts

@@ -0,0 +1,79 @@
+import type { DefaultOptions } from "@tanstack/react-query";
+import { ApiError } from "./api-error.ts";
+
+/**
+ * react-query defaults — the merge of three repos that each got part of this right.
+ *
+ * The default is three blind retries, which is wrong for an API that answers refusals
+ * precisely: a 402, a 403 or a 451 says exactly the same thing three times, and a 429 we hammer
+ * is a 429 we deserve. All three donors knew that much. What each knew alone:
+ *
+ * - one allowed **408** through, the only 4xx that a second attempt genuinely fixes;
+ * - one refused to retry a 429 whose CODE says the limit is durable — a monthly quota or a
+ *   spent balance clears by buying, not by waiting, so retrying burns another request against
+ *   the limiter and cannot succeed;
+ * - one set **`refetchOnReconnect`**, which none of the others had, and which is the single
+ *   most useful refetch there is: coming back from a tunnel is exactly when the screen is stale.
+ *
+ * This is invariant 8.
+ */
+
+/** 4xx statuses a second attempt can fix. Everything else in the 4xx family is an answer. */
+const RETRYABLE_CLIENT_STATUS = new Set([408, 429]);
+
+export interface QueryDefaultsOptions {
+  /**
+   * Error codes that mean "this limit does not clear by waiting" — a spent monthly quota, a
+   * balance that needs topping up. They usually arrive as 402 or 429; the status alone cannot
+   * tell them apart from a burst limit, which is why the caller names them.
+   */
+  durableLimitCodes?: readonly string[];
+  /** How many times to retry a transient failure. Two donors used 2, one used 1. */
+  maxRetries?: number;
+  staleTime?: number;
+  gcTime?: number;
+  /**
+   * Left to the caller on purpose. A dashboard someone leaves open wants it on; a console
+   * whose data changes only when the operator changes it wants it off, and one donor turned it
+   * off deliberately. There is no right answer to inherit.
+   */
+  refetchOnWindowFocus?: boolean;
+}
+
+/**
+ * Should this failure be retried?
+ *
+ * Exported on its own because an app with its own QueryClient config still wants this rule, and
+ * because it is the part worth testing.
+ */
+export function shouldRetry(error: unknown, durableLimitCodes: readonly string[] = []): boolean {
+  // No response at all — offline, DNS, a dropped connection. The request never landed, so
+  // nothing about it is an answer, and a second attempt is exactly right.
+  if (!(error instanceof ApiError)) return true;
+
+  if (error.code !== undefined && durableLimitCodes.includes(error.code)) return false;
+  if (error.status >= 500) return true;
+  return RETRYABLE_CLIENT_STATUS.has(error.status);
+}
+
+export function queryDefaults({
+  durableLimitCodes = [],
+  maxRetries = 2,
+  staleTime = 2 * 60 * 1000,
+  gcTime = 10 * 60 * 1000,
+  refetchOnWindowFocus = false,
+}: QueryDefaultsOptions = {}): DefaultOptions {
+  return {
+    queries: {
+      staleTime,
+      gcTime,
+      retry: (failureCount, error) =>
+        failureCount < maxRetries && shouldRetry(error, durableLimitCodes),
+      refetchOnWindowFocus,
+      refetchOnReconnect: true,
+    },
+    // A mutation is not idempotent by default. Retrying one that already reached the server is
+    // how a customer gets charged twice; all three donors agreed on this without discussion.
+    mutations: { retry: false },
+  };
+}

package/src/sse.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { createSseParser, type SseFrame } from "./sse.ts";
+
+function collect(...chunks: string[]): SseFrame[] {
+  const frames: SseFrame[] = [];
+  const parser = createSseParser((f) => frames.push(f));
+  for (const chunk of chunks) parser.feed(chunk);
+  return frames;
+}
+
+describe("createSseParser", () => {
+  // The bug one donor shipped: assigning `data` instead of appending, so a multi-line
+  // payload arrived as its last line only. Silent — no error, no warning, a truncated message.
+  it("joins repeated data lines instead of overwriting them", () => {
+    expect(collect("data: one\ndata: two\ndata: three\n\n")[0]?.data).toBe("one\ntwo\nthree");
+  });
+
+  it("holds a frame split across reads until it completes", () => {
+    expect(collect("data: hel", "lo\n", "\n")).toEqual([
+      { event: "message", data: "hello", id: undefined },
+    ]);
+  });
+
+  // The spec strips exactly one space after the colon. `.trim()` is the obvious wrong thing:
+  // it eats leading and trailing whitespace a payload may actually mean.
+  it("strips one leading space, not all whitespace", () => {
+    expect(collect("data:  padded \n\n")[0]?.data).toBe(" padded ");
+  });
+
+  it("defaults an unnamed frame to `message`, and carries event and id", () => {
+    expect(collect("event: tick\nid: 42\ndata: x\n\n")[0]).toEqual({
+      event: "tick",
+      data: "x",
+      id: "42",
+    });
+  });
+
+  // What lets a server keep the connection warm without waking the consumer on every beat.
+  it("does not dispatch a frame with no data", () => {
+    expect(collect("event: heartbeat\n\n", ": just a comment\n\n")).toEqual([]);
+  });
+
+  it("handles CRLF line endings", () => {
+    expect(collect("event: tick\r\ndata: x\r\n\r\n")[0]?.event).toBe("tick");
+  });
+
+  it("does not parse the payload", () => {
+    expect(collect('data: {"n":1}\n\n')[0]?.data).toBe('{"n":1}');
+  });
+});

package/src/sse.ts

@@ -0,0 +1,117 @@
+/**
+ * Server-sent events: the framing and the transport, kept apart.
+ *
+ * Three donors had three readers and each had half the answer. One was spec-correct about the
+ * wire but welded to `TextDecoderStream`, so the React Native app — whose fetch has no body
+ * reader — could not use a line of it. One was a platform-free `feed(text)` that three
+ * transports shared, and it silently dropped data. One was a whole second transport with its
+ * own fetch and its own 401 handling, bypassing the app's only API client.
+ *
+ * So: {@link createSseParser} is the state machine and knows about no platform at all;
+ * {@link readSseStream} is fifteen lines of `ReadableStream` on top of it. A caller on a
+ * platform without body readers keeps its own fifteen lines and shares the machine underneath.
+ * (providerkit reached this exact split from the other direction and for the same reason.)
+ *
+ * And streams ride the ordinary API client — `client.request(path, {headers: {Accept:
+ * "text/event-stream"}, timeoutMs: null})`. Not `EventSource`, which cannot carry an
+ * Authorization header, and not a second fetch, which would need its own copy of the refresh
+ * logic and would drift from it.
+ */
+
+/** One frame off the wire. `data` is raw text; see {@link createSseParser} on why. */
+export interface SseFrame {
+  /** The `event:` field, or `"message"` — which is what the spec says an unnamed frame is. */
+  event: string;
+  /** Every `data:` line in the frame, joined with newlines. Never parsed here. */
+  data: string;
+  /** The `id:` field, if the server sent one. Feed it back as `Last-Event-ID` to resume. */
+  id: string | undefined;
+}
+
+/**
+ * An incremental parser. Feed it text in whatever sizes the transport delivers.
+ *
+ * Frames split across reads are held until they complete, so a payload cut mid-line is never
+ * lost or truncated — which is the failure this shape exists to prevent, and the one that only
+ * shows up under a slow network.
+ *
+ * Three rules that are easy to get wrong, and one donor got each of them wrong:
+ *
+ * - **`data:` repeats.** A frame may carry several `data:` lines and they are JOINED with
+ *   newlines. One donor assigned instead of appending, so a multi-line payload arrived as its
+ *   last line only — no error, no warning, just a truncated message.
+ * - **Strip ONE leading space after the colon**, not all whitespace. `.trim()` is the obvious
+ *   thing and it corrupts any payload whose own content begins or ends with a space.
+ * - **A frame with no `data:` is not dispatched.** That is what lets a server send bare
+ *   `event: heartbeat` keepalives, or `:` comment lines, without waking a consumer.
+ *
+ * `data` is handed back as a raw string and deliberately NOT JSON-parsed. One donor parsed here
+ * and its three consumers wanted three different things — one wraps non-JSON, one uses a
+ * tolerant parser, one parses directly. Parsing in the parser picks a policy for all of them.
+ */
+export function createSseParser(onFrame: (frame: SseFrame) => void): {
+  feed: (text: string) => void;
+} {
+  let buffer = "";
+
+  return {
+    feed(text: string) {
+      // A server may send CRLF; the frame boundary is a blank line either way.
+      buffer += text.replace(/\r\n/g, "\n");
+      let end = buffer.indexOf("\n\n");
+      while (end !== -1) {
+        const frame = parseFrame(buffer.slice(0, end));
+        buffer = buffer.slice(end + 2);
+        if (frame) onFrame(frame);
+        end = buffer.indexOf("\n\n");
+      }
+    },
+  };
+}
+
+/** The SSE wire format: `field: value` lines, `data` repeatable, a leading `:` is a comment. */
+function parseFrame(raw: string): SseFrame | null {
+  let event = "message";
+  let id: string | undefined;
+  const data: string[] = [];
+
+  for (const line of raw.split("\n")) {
+    if (line === "" || line.startsWith(":")) continue;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+    if (field === "event") event = value;
+    else if (field === "id") id = value;
+    else if (field === "data") data.push(value);
+  }
+
+  return data.length === 0 ? null : { event, data: data.join("\n"), id };
+}
+
+/**
+ * Read a `Response` body as SSE. Resolves when the server closes the stream.
+ *
+ * Pass the response from the ordinary API client, so the stream inherits the token, the
+ * single-flight refresh, and a 402 or a 404 arriving as an `ApiError` the page can explain
+ * rather than an `onerror` event with nothing in it.
+ *
+ * Cancels the reader on the way out however it leaves — a stream abandoned without cancelling
+ * holds the connection open until the server gives up on it.
+ */
+export async function readSseStream(
+  response: Response,
+  onFrame: (frame: SseFrame) => void,
+): Promise<void> {
+  if (!response.body) return;
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+  const parser = createSseParser(onFrame);
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      parser.feed(value);
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+}

package/src/states.ts

@@ -0,0 +1,71 @@
+import type { ReactNode } from "react";
+
+/**
+ * The two contracts that make "never dead-end the user" a compile error instead of a rule
+ * somebody remembers.
+ *
+ * **No component ships here, on purpose.** Seven repos have an `EmptyState.tsx` and an
+ * `ErrorState.tsx`, and read side by side they overlap 9–37%: one draws a tinted icon badge,
+ * one a branded illustration set, one a mascot. What they genuinely share is the PROP SHAPE —
+ * which is the rule itself, and the only part a package can hold without deciding how eight
+ * brands look. Same reasoning as the styled Button: share behaviour, skin per product.
+ *
+ * Import the type, write your own component against it, and the compiler enforces the rest.
+ */
+
+/**
+ * A panel with nothing in it yet.
+ *
+ * The prop shape IS the rule: somebody who lands here must learn what this panel is FOR
+ * (`title`), what belongs IN it (`description`), and how to FILL it (`action`). The first two
+ * are required because two of the three are what make it an orientation rather than a shrug.
+ * `action` is optional only because some panels fill themselves once a job upstream finishes.
+ */
+export interface EmptyStateProps {
+  /** What this panel is for. "No lookups yet" — not "No results". */
+  title: string;
+  /** What belongs here, and what it will show once it does. */
+  description: ReactNode;
+  /** The way forward, as a control. Usually one button. */
+  action?: ReactNode;
+  /**
+   * `3` inside a panel that already sits under a page heading — the default and the common
+   * case. `1` when this composer IS the page (a 404, a suspended account), which otherwise
+   * ships a document with no `h1` in it at all.
+   *
+   * Only one donor had this, and it is the difference between a screen reader announcing a
+   * page and announcing nothing.
+   */
+  headingLevel?: 1 | 2 | 3;
+  className?: string;
+}
+
+/**
+ * Something did not work.
+ *
+ * `problem` names what failed, `cause` says why it most likely happened, `fix` says what to do
+ * about it, and `action` is that fix as a control. **`fix` and `action` are both required** — a
+ * required prop is the only version of "never dead-end" that a caller in a hurry cannot skip,
+ * and the donor that made them required is the one whose error screens all have a way out.
+ *
+ * Not a place for a stack trace. `cause` is what a person can act on ("the site answered too
+ * slowly"), with the request id, if there is one, alongside it in `reference`.
+ *
+ * {@link DescribedError} from `describe-error.ts` produces `cause` and `fix` from a thrown
+ * `ApiError`, which is the seam these two were designed against.
+ */
+export interface ErrorStateProps {
+  /** What failed, in the reader's words. "Couldn't load your numbers". */
+  problem: string;
+  /** Why it most likely happened. */
+  cause?: ReactNode;
+  /** The way forward, in words. */
+  fix: ReactNode;
+  /** The way forward, as a control — usually a retry button. */
+  action: ReactNode;
+  /** A request id or code, for a support thread. Set in mono, never shouted. */
+  reference?: ReactNode;
+  /** See {@link EmptyStateProps.headingLevel}. */
+  headingLevel?: 1 | 2 | 3;
+  className?: string;
+}

package/src/ui/class-name.ts

@@ -0,0 +1,23 @@
+import type { ClassValue } from "clsx";
+import { cn } from "../cn.ts";
+
+/**
+ * A Base UI part's `className`: a plain string, or a function of that part's own state
+ * (`open`, `transitionStatus`, `highlighted`, …).
+ */
+export type StateClassName<State> = string | ((state: State) => string | undefined) | undefined;
+
+/**
+ * Merge a wrapper's own classes with the caller's, keeping BOTH forms working.
+ *
+ * `cn()` on its own silently DROPS the function form — clsx walks strings, arrays and plain
+ * objects, and a function is none of the three — so a caller styling by `open` or
+ * `transitionStatus` would get an empty class and no warning. Always returning a function
+ * keeps one code path for both.
+ */
+export function mergeClassName<State>(
+  base: ClassValue,
+  extra: StateClassName<State>,
+): (state: State) => string {
+  return (state) => cn(base, typeof extra === "function" ? extra(state) : extra);
+}

package/src/ui/combobox.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { comboboxInputValue } from "./combobox.tsx";
+
+interface City {
+  id: string;
+  name: string;
+}
+
+const recife: City = { id: "rec", name: "Recife" };
+const label = (city: City) => city.name;
+
+describe("comboboxInputValue", () => {
+  // Show the label while the list is open and every keystroke is overwritten by the old
+  // selection — the field types backwards.
+  it("shows what the user is typing while the list is open", () => {
+    expect(comboboxInputValue(true, "rec", recife, label)).toBe("rec");
+  });
+
+  // Show the query while the list is closed and the field goes blank the moment focus
+  // leaves, even though a value is set.
+  it("shows the selected item once the list closes", () => {
+    expect(comboboxInputValue(false, "rec", recife, label)).toBe("Recife");
+  });
+
+  it("is empty with nothing selected", () => {
+    expect(comboboxInputValue(false, "rec", null, label)).toBe("");
+  });
+
+  it("still shows an open query when nothing is selected yet", () => {
+    expect(comboboxInputValue(true, "rec", null, label)).toBe("rec");
+  });
+});