@gusnips/react 0.1.0

package/dist/ui/tabs.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Tabs as Primitive } from "@base-ui/react/tabs";
+import { cn } from "../cn.js";
+import { mergeClassName } from "./class-name.js";
+// Root and Panel pass straight through: a wrapper around either would add a class string and
+// nothing else, and Base UI already owns arrow-key navigation, activation mode and the
+// tab/panel `aria-controls` wiring.
+export const Tabs = Primitive.Root;
+export const TabPanel = Primitive.Panel;
+/**
+ * The rail, and the reason this file exists.
+ *
+ * It scrolls sideways rather than wrapping, because a second row of tabs pushes the panel
+ * below the fold on a phone. But the scroll cannot live on the rail itself: `overflow-x: auto`
+ * makes the element a scroll container, a scroll container clips everything its children paint
+ * outside the padding box, and a computed `overflow-x` of `auto` forces `overflow-y` from
+ * `visible` to `auto` as well. A self-scrolling rail therefore crops the focus ring on all
+ * FOUR sides of whichever tab the keyboard is on — top and bottom always, the left of the
+ * first tab and the right of the last.
+ *
+ * So the scroll goes on a wrapper, and the wrapper's padding is the room the ring needs. The
+ * number is derived, not inherited: `@gusnips/tokens` draws `outline: 2px solid` at
+ * `outline-offset: 2px`, so the ring paints from 2px to 4px beyond a tab's border box, and
+ * `p-1` is exactly those 4px. An outline reaches FURTHER than the `ring-2` box-shadow the
+ * donor had here, so the wrapper matters more now than it did there, not less.
+ *
+ * Naming the rail is not optional and not a comment: pass `label`, or point
+ * `aria-labelledby` at a heading. A tablist with neither is announced as nothing at all.
+ */
+export function TabList({ label, className, wrapperClassName, children, ...rest }) {
+    return (_jsx("div", { className: cn("w-fit max-w-full overflow-x-auto p-1", wrapperClassName), children: _jsx(Primitive.List, { "aria-label": label, ...rest, 
+            // `relative`, because TabIndicator positions itself against the rail.
+            className: mergeClassName("relative flex w-fit", className), children: children }) }));
+}
+// Styled off `aria-selected`, never a parallel `data-active`: the primitive writes both from
+// one state, and styling the accessibility contract is what keeps what a screen reader
+// announces and what an eye sees from ever drifting apart.
+//
+// `shrink-0` and `whitespace-nowrap` are what make the rail scroll instead of squashing — a
+// tab that shrinks to fit is a tab nobody can read, and the scroll above exists precisely so
+// it does not have to.
+const tabClasses = "shrink-0 cursor-pointer px-3 py-1.5 whitespace-nowrap text-muted-foreground select-none aria-selected:text-foreground [@media(pointer:coarse)]:min-h-11";
+export function Tab({ className, ...rest }) {
+    return _jsx(Primitive.Tab, { ...rest, className: mergeClassName(tabClasses, className) });
+}
+/**
+ * The travelling marker under the active tab — a SEPARATE part, because the two donors
+ * disagreed about whether to have one at all and both were right about their own app. Render
+ * it or do not; the rail works either way.
+ *
+ * It must be a child of `TabList`: Base UI measures the active tab against the enclosing
+ * `[role="tablist"]` and writes `--active-tab-left` / `--active-tab-width` onto this element.
+ *
+ * `renderBeforeHydration` is on by default because this package's apps are prerendered — with
+ * it off, every prerendered page shows the rail with no marker until React arrives. It writes
+ * one inline script to do that; under a strict CSP without Base UI's `CspProvider` the script
+ * is blocked and the behaviour falls back to exactly what `false` would have done.
+ */
+export function TabIndicator({ className, ...rest }) {
+    return (_jsx(Primitive.Indicator, { "aria-hidden": "true", renderBeforeHydration: true, ...rest, className: mergeClassName("absolute bottom-0 left-0 h-0.5 w-[var(--active-tab-width)] translate-x-[var(--active-tab-left)] bg-foreground transition-[translate,width]", className) }));
+}
+//# sourceMappingURL=tabs.js.map

package/dist/ui/tabs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabs.js","sourceRoot":"","sources":["../../src/ui/tabs.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,6FAA6F;AAC7F,uFAAuF;AACvF,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;AACnC,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC;AAYxC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAgB;IAC7F,OAAO,CACL,cAAK,SAAS,EAAE,EAAE,CAAC,sCAAsC,EAAE,gBAAgB,CAAC,YAC1E,KAAC,SAAS,CAAC,IAAI,kBACD,KAAK,KACb,IAAI;YACR,sEAAsE;YACtE,SAAS,EAAE,cAAc,CAAC,qBAAqB,EAAE,SAAS,CAAC,YAE1D,QAAQ,GACM,GACb,CACP,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,uFAAuF;AACvF,2DAA2D;AAC3D,EAAE;AACF,4FAA4F;AAC5F,6FAA6F;AAC7F,uBAAuB;AACvB,MAAM,UAAU,GACd,yJAAyJ,CAAC;AAE5J,MAAM,UAAU,GAAG,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAuB;IAC7D,OAAO,KAAC,SAAS,CAAC,GAAG,OAAK,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,UAAU,EAAE,SAAS,CAAC,GAAI,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAA6B;IAC5E,OAAO,CACL,KAAC,SAAS,CAAC,SAAS,mBACN,MAAM,EAClB,qBAAqB,WACjB,IAAI,EACR,SAAS,EAAE,cAAc,CACvB,4IAA4I,EAC5I,SAAS,CACV,GACD,CACH,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@gusnips/react",
+  "version": "0.1.0",
+  "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, chunk-reload recovery, i18n bootstrap.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/frontkit/tree/main/react#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/frontkit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "default": "./dist/ui/index.js"
+    },
+    "./store": {
+      "types": "./dist/auth-store.d.ts",
+      "default": "./dist/auth-store.js"
+    },
+    "./guards": {
+      "types": "./dist/guards.d.ts",
+      "default": "./dist/guards.js"
+    },
+    "./contract": {
+      "types": "./dist/prerender-contract.d.ts",
+      "default": "./dist/prerender-contract.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "vite",
+    "spa",
+    "zustand",
+    "react-query",
+    "i18next",
+    "base-ui",
+    "headless"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "dependencies": {
+    "@gusnips/http": "0.1.0",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.6.0"
+  },
+  "peerDependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@tanstack/react-query": "^5",
+    "i18next": ">=25",
+    "react": "^19",
+    "react-dom": "^19",
+    "react-i18next": ">=16",
+    "react-router-dom": "^7",
+    "zustand": "^5"
+  },
+  "peerDependenciesMeta": {
+    "@base-ui/react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    },
+    "react-i18next": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    },
+    "zustand": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@tanstack/react-query": "^5.102.8",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "i18next": "^26.3.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-i18next": "^17.0.8",
+    "react-router-dom": "^7.18.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2",
+    "zustand": "^5.0.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/frontkit.git",
+    "directory": "react"
+  }
+}

package/src/api-client.test.ts

@@ -0,0 +1,256 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ApiError, isAbortError } from "./api-error.ts";
+import { createApiClient, type RefreshResult, type SessionAdapter } from "./api-client.ts";
+
+function stubFetch(handler: (url: string, init: RequestInit) => Response | Promise<Response>) {
+  const spy = vi.fn(handler);
+  vi.stubGlobal("fetch", spy as unknown as typeof fetch);
+  return spy;
+}
+
+const ok = (data: unknown) =>
+  new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+
+const unauthorized = () =>
+  new Response(JSON.stringify({ error: { code: "UNAUTHORIZED", message: "no" } }), { status: 401 });
+
+function session(overrides: Partial<SessionAdapter> = {}): SessionAdapter {
+  return {
+    getToken: async () => "old-token",
+    refresh: async (): Promise<RefreshResult> => ({ token: "new-token", reachedAuth: true }),
+    signOut: async () => {},
+    ...overrides,
+  };
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("createApiClient", () => {
+  it("unwraps the success envelope", async () => {
+    stubFetch(() => ok({ id: 7 }));
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+    });
+    await expect(api.get<{ id: number }>("/me")).resolves.toEqual({ id: 7 });
+  });
+
+  it("throws an ApiError carrying the whole envelope and the request id", async () => {
+    stubFetch(
+      () =>
+        new Response(
+          JSON.stringify({
+            error: { code: "QUOTA_EXCEEDED", message: "spent", details: { retryAfterSecs: 60 } },
+          }),
+          { status: 429, headers: { "x-request-id": "req_1" } },
+        ),
+    );
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+    });
+
+    const error = await api.get("/x").catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error).toMatchObject({
+      status: 429,
+      code: "QUOTA_EXCEEDED",
+      details: { retryAfterSecs: 60 },
+      requestId: "req_1",
+    });
+  });
+
+  /**
+   * The single-flight rule, and the reason all three donors found it the hard way: the auth
+   * server rotates the refresh token on use, so six parallel 401s sending six refreshes means
+   * five of them invalidate the winner — and the person is signed out in the middle of a load
+   * that was working.
+   */
+  it("sends one refresh for six concurrent 401s", async () => {
+    let refreshes = 0;
+    let token = "old-token";
+    stubFetch((_url, init) => {
+      const auth = new Headers(init.headers).get("Authorization");
+      return auth === "Bearer new-token" ? ok({}) : unauthorized();
+    });
+
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session({
+        getToken: async () => token,
+        refresh: async () => {
+          refreshes++;
+          // A real rotation: the old token is dead the moment a refresh succeeds.
+          await new Promise((r) => setTimeout(r, 5));
+          token = "new-token";
+          return { token, reachedAuth: true };
+        },
+      }),
+      onSessionDead: () => {},
+    });
+
+    await Promise.all(Array.from({ length: 6 }, () => api.get("/me")));
+    expect(refreshes).toBe(1);
+  });
+
+  /**
+   * Invariant 3. Only one of three donors had this, and it is the difference between a Wi-Fi
+   * blip and losing your place: a refresh that never got an ANSWER out of auth says nothing
+   * about whether the session is good, so the 401 falls through as an ordinary error and the
+   * next request refreshes cleanly once the connection is back.
+   */
+  it("does not sign anyone out when the refresh never reached auth", async () => {
+    stubFetch(() => unauthorized());
+    const onSessionDead = vi.fn();
+    const signOut = vi.fn(async () => {});
+
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session({
+        refresh: async () => ({ token: null, reachedAuth: false }),
+        signOut,
+      }),
+      onSessionDead,
+      refreshRetryDelayMs: 0,
+    });
+
+    const error = await api.get("/me").catch((e: unknown) => e);
+    expect(onSessionDead).not.toHaveBeenCalled();
+    expect(signOut).not.toHaveBeenCalled();
+    // It surfaces as an ordinary 401 the caller can report, not as an expected sign-out.
+    expect(error).toBeInstanceOf(ApiError);
+    expect((error as ApiError).expected).toBe(false);
+  });
+
+  it("signs out once when auth actually says no", async () => {
+    stubFetch(() => unauthorized());
+    const onSessionDead = vi.fn();
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session({ refresh: async () => ({ token: null, reachedAuth: true }) }),
+      onSessionDead,
+      refreshRetryDelayMs: 0,
+    });
+
+    const first = await api.get("/a").catch((e: unknown) => e);
+    await api.get("/b").catch(() => {});
+
+    // Latched: whichever request got there first owns the sign-out.
+    expect(onSessionDead).toHaveBeenCalledTimes(1);
+    // Still throws, because location.replace() does not stop the current frame — a caller's
+    // own onError has to run or a half-finished screen keeps rendering against data that will
+    // never arrive. `expected` is what keeps it out of crash reporting.
+    expect((first as ApiError).expected).toBe(true);
+  });
+
+  /**
+   * providerkit's invariant 2, on the web side: a caller's Stop and our deadline must stay
+   * distinguishable. `AbortSignal.timeout` rejects with a **TimeoutError**, not an AbortError,
+   * so `isAbortError` stays false for it — which is what lets a timeout be retried and reported
+   * while a navigation-cancelled request is silently dropped.
+   */
+  it("distinguishes its own timeout from the caller's abort", async () => {
+    // Note the `aborted` check before the listener. A signal that fired before fetch was ever
+    // called never emits the event, so a listener alone hangs forever — real `fetch` checks the
+    // flag first, and so must anything standing in for it. That already-aborted race is exactly
+    // what `AbortSignal.any` in the client exists to cover.
+    stubFetch(
+      (_url, init) =>
+        new Promise<Response>((_resolve, reject) => {
+          const signal = init.signal as AbortSignal | null;
+          if (signal?.aborted) return reject(signal.reason as Error);
+          signal?.addEventListener("abort", () => reject(signal.reason as Error));
+        }),
+    );
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+      timeoutMs: 10,
+    });
+
+    const timedOut = await api.get("/slow").catch((e: unknown) => e);
+    expect((timedOut as DOMException).name).toBe("TimeoutError");
+    expect(isAbortError(timedOut)).toBe(false);
+
+    const controller = new AbortController();
+    const cancelled = api.get("/slow", { signal: controller.signal }).catch((e: unknown) => e);
+    controller.abort();
+    expect(isAbortError(await cancelled)).toBe(true);
+  });
+
+  // A 204 has no body, so `res.json()` on one throws `Unexpected end of JSON input` — which
+  // reads like a malformed response and is really a success nobody was allowed to parse. The
+  // donor's dashboard DELETEs all answer 204, so `del` must not go looking for data.
+  it("deletes without reading the body, and reads it only when asked", async () => {
+    const fetched = stubFetch((_url, init) =>
+      init.method === "DELETE" && !String(_url).endsWith("/queue/1")
+        ? new Response(null, { status: 204 })
+        : ok({ removed: true }),
+    );
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+    });
+
+    await expect(api.del("/keys/1")).resolves.toBeUndefined();
+    await expect(api.delJson<{ removed: boolean }>("/queue/1")).resolves.toEqual({ removed: true });
+    expect(fetched).toHaveBeenCalledTimes(2);
+  });
+
+  it("reports a failure to onError once, and still throws it", async () => {
+    stubFetch(
+      () =>
+        new Response(
+          JSON.stringify({
+            error: {
+              code: "FORBIDDEN",
+              message: "suspended",
+              messageKey: "serverErrors.suspended",
+            },
+          }),
+          { status: 403 },
+        ),
+    );
+    const seen: ApiError[] = [];
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+      onError: (error) => seen.push(error),
+    });
+
+    const thrown = await api.get("/numbers").catch((e: unknown) => e);
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.messageKey).toBe("serverErrors.suspended");
+    // The same object, not a copy: a listener that stashes it can compare identity later.
+    expect(thrown).toBe(seen[0]);
+  });
+
+  it("does not let a broken listener replace the API failure", async () => {
+    stubFetch(
+      () =>
+        new Response(JSON.stringify({ error: { code: "NOT_FOUND", message: "no" } }), {
+          status: 404,
+        }),
+    );
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+      onError: () => {
+        throw new Error("the listener is buggy");
+      },
+    });
+
+    const thrown = await api.get("/x").catch((e: unknown) => e);
+    expect(thrown).toBeInstanceOf(ApiError);
+    expect((thrown as ApiError).status).toBe(404);
+  });
+});