@gusnips/react 0.9.24 → 0.9.26

package/README.md

@@ -11,7 +11,7 @@ bun add @gusnips/react
 const user = await api.get<User>("/me");
 ```
 
-That is the whole call. `user` is a `User` — not a `Response`, not `res.json()`, not a null
+That is the whole call. `user` is a `User`: not a `Response`, not `res.json()`, not a null
 check. The client attached the token, unwrapped the envelope, and threw a typed `ApiError`
 carrying the code and the request id if the server refused.
 
@@ -30,18 +30,18 @@ const api = createApiClient({
 ## The client knows three things people learn the hard way
 
 **Six queries firing at once send one refresh, not six.** The auth server rotates the refresh
-token when you use it, so the losers of that race each invalidate the winner — and the person is
+token when you use it, so the losers of that race each invalidate the winner, and the person is
 signed out in the middle of a load that was working. Three separate codebases arrived at
 single-flight refresh independently. This is that.
 
 **Only auth ANSWERING is a "no".** Dropping a packet tells you nothing about whether a session is
-good, and neither does a 500 — that is auth failing, not auth answering. So `refresh()` answers
+good, and neither does a 500. That is auth failing, not auth answering. So `refresh()` answers
 `{ token, reachedAuth }`, and only a real refusal signs anyone out. Before that split, a Wi-Fi
 blip logged people out mid-load; without the second half, one bad minute at the auth server signs
 out everybody whose token happened to need refreshing.
 
 **A sign-out has a fail-safe timer.** Awaiting `signOut()` before redirecting covers a rejection,
-not a hang — and a hang leaves someone signed out in name only: every request 401ing, nothing
+not a hang, and a hang leaves someone signed out in name only: every request 401ing, nothing
 left that could redirect it.
 
 ### Supabase sessions
@@ -65,14 +65,14 @@ import { isAuthOutage } from "@gusnips/react/supabase";
 
 // A callback that just failed to trade its one-use link.
 if (isAuthOutage(error))
-  showRetry(); // the link was never spent — the same one still works
+  showRetry(); // the link was never spent: the same one still works
 else showLinkSpent(); // auth said no: only a new link helps
 ```
 
-`isAuthOutage` is true when auth FAILED rather than answered — a request that never landed, or a
+`isAuthOutage` is true when auth FAILED rather than answered: a request that never landed, or a
 5xx. Only a real refusal is an answer, and only an answer may end a session or a link. Use it
-anywhere that decision is made; the sentence you show is a separate question, and a narrower one
-— "check your connection" is true of a request that never landed and false of a 502, which is
+anywhere that decision is made; the sentence you show is a separate question, and a narrower one:
+"check your connection" is true of a request that never landed and false of a 502, which is
 ours. auth-js marks "nothing came back", and only that, with status 0.
 
 It is safe to hand it the `error` from a `{ data, error }` result without checking it first:
@@ -120,7 +120,7 @@ Supabase email links have two complete patterns. Keep either one, never half of
 - A link carrying `ConfirmationURL` needs `detectSessionInUrl` enabled. That reader consumes an
   implicit `#access_token` or a PKCE `?code`; it does not consume `token_hash`.
 
-Either pattern can carry a destination — the `token_hash` one has to be asked. GoTrue hands every
+Either pattern can carry a destination: the `token_hash` one has to be asked. GoTrue hands every
 template a `{{ .RedirectTo }}`: the `redirectTo` the app passed, already checked against the
 allowlist, falling back to the Site URL when it was absent or not on it. A `{{ .ConfirmationURL }}`
 link carries it for you. A template that writes its own landing drops it unless it asks:
@@ -130,7 +130,7 @@ link carries it for you. A template that writes its own landing drops it unless
 ```
 
 Leave that parameter off and `redirectTo` and `emailRedirectTo` do nothing on every e-mail flow,
-however carefully the app sets them — four of the codebases this came from pass one that the
+however carefully the app sets them: four of the codebases this came from pass one that the
 template throws away, so a person bounced off a protected page signs in and lands on the front
 door. Nothing reports it: the app's call is correct, the link works, and the destination was
 dropped in an HTML file hosted somewhere else.
@@ -147,7 +147,7 @@ Validate it on arrival even though GoTrue already did: that check is against a l
 so it says the link may come back here, not which page it may open.
 
 Recovery and invite links continue to the new-password screen after the session opens. A callback
-must also tell a used or expired link apart from a request that never landed — or one that landed
+must also tell a used or expired link apart from a request that never landed, or one that landed
 and came back 5xx: the first needs a new link, and the other two can retry the same one, because
 the hash was never spent.
 
@@ -165,7 +165,7 @@ implicit-flow tokens; in a browser the client has already taken it, so wait for
 React Native hand `credential` to `exchangeCodeForSession` or `setSession`. `error` is a failure
 GoTrue wrote into the address. `invalid` is a link that was cut short or edited.
 
-Pass the fragment too — `parseAuthCallback(location.search, location.hash)`. GoTrue writes a
+Pass the fragment too: `parseAuthCallback(location.search, location.hash)`. GoTrue writes a
 failure into the fragment every time and into the query only sometimes: after an implicit-flow
 email link it is in the fragment alone, so a query-only reader shows nothing to somebody whose
 link expired.
@@ -197,7 +197,7 @@ new QueryClient({
 });
 ```
 
-Retries 408, 425, a transient 429, 5xx, and no-response-at-all. Nothing else — every other 4xx is
+Retries 408, 425, a transient 429, 5xx, and no-response-at-all. Nothing else: every other 4xx is
 an answer, and a second attempt just says it again. The rule itself is
 [`@gusnips/http/retry`](../http#should-this-request-be-tried-again), so an SDK with no React in it
 can retry the same way.
@@ -210,7 +210,7 @@ those codes and they are never retried.
 You only need that list where your API stays quiet. If it answers `Retry-After: 2`, the wait is
 sat out; past `maxRetryWaitSecs` (10 seconds by default) the wait is the answer and the screen
 says so instead of holding a spinner. And if it sends `details.retryAfterSecs: null`, it is
-saying waiting will never fix this — a cap that frees only when somebody deletes something, a
+saying waiting will never fix this: a cap that frees only when somebody deletes something, a
 slot that frees when another job ends. That `null` is read as the claim it is, not as a field
 somebody forgot, so the code never reaches your list.
 
@@ -244,14 +244,14 @@ offer comes from `describeError(view.error).recover`, below.
 ## Survives your deploys
 
 An app with `lazy()` routes serves chunks by hashed filename. Deploy while someone has a tab
-open, and their next click asks for a file that no longer exists — a white screen on a button
+open, and their next click asks for a file that no longer exists: a white screen on a button
 that worked a minute ago. The same deploy breaks a second way that looks nothing like the first:
 the old bundle reads a field your API just renamed, and throws a plain `TypeError` with nothing
 in it about a deploy.
 
 **Fix the cause in your host config first.** This package cannot do it for you and it is worth
 more than everything below. A static host answers a missing `/assets/x.js` with your SPA
-fallback — `index.html`, at a 200, as `text/html` — and that is what the browser's "MIME type
+fallback (`index.html`, at a 200, as `text/html`), and 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 you wrote for hashed
 assets lands on that HTML body: one poisoned asset URL, at the edge and in every browser that
@@ -264,12 +264,12 @@ Then two detectors, for the two failures:
 if (await isStaleBuild()) reloadOnce();
 ```
 
-`isStaleBuild` asks the server instead of reading the error — it compares the entry script this
+`isStaleBuild` asks the server instead of reading the error: it compares the entry script this
 document loaded against the one the live page names. That is the only thing that catches the
 renamed-field crash, where the message carries no signal at all. It asks for the page, not for
 the asset: a CDN serves assets with a long `s-maxage`, so a bundle retired an hour ago still
 answers 200 from the edge and would report "current" during exactly the window when skew is most
-likely. Anything ambiguous — offline, a non-200, a timeout — answers `false`, because dressing a
+likely. Anything ambiguous (offline, a non-200, a timeout) answers `false`, because dressing a
 real bug up as an update hides it from you too.
 
 ```ts
@@ -277,12 +277,12 @@ if (isChunkLoadError(error) && reloadOnce()) return null;
 ```
 
 `isChunkLoadError` matches the message, which is all you have for a failure that never reaches a
-boundary — an `unhandledrejection`, or a listener. Every browser's phrasing is in there.
+boundary: an `unhandledrejection`, or a listener. Every browser's phrasing is in there.
 
 `reloadOnce` reloads at most once a minute, and there is **one** stamp for every reason to
 reload. A tab can reload because a chunk 404'd, because the server says it is behind, or from a
-guard inlined in `index.html` that runs before any module does. Three detectors, one predicament
-— give each its own key and a broken deploy gets three reloads a minute to take turns with. That
+guard inlined in `index.html` that runs before any module does. Three detectors, one predicament:
+give each its own key and a broken deploy gets three reloads a minute to take turns with. That
 inline guard cannot import anything, so the key it has to copy is exported as `RELOAD_GUARD_KEY`.
 
 And in your browser entry:
@@ -294,7 +294,7 @@ installPreloadErrorHandler();
 ```
 
 It is narrower than it looks: it swallows Vite's CSS _preload hint_ failure and nothing else. A
-hint that fails is harmless — the import runs straight after and usually works. Taking Vite's
+hint that fails is harmless: the import runs straight after and usually works. Taking Vite's
 `preventDefault()` for every preload error instead resolves the dynamic import with `undefined`,
 `React.lazy` reads `.default` off nothing, and you get a crash screen plus a TypeError with only
 React frames in it, naming no chunk.
@@ -315,7 +315,7 @@ const RequireStaff = requireProfile(
 
 `onDenied` and `onError` are separate because `!me?.isStaff` reads a 500 as "not staff". An
 operator arriving while `/auth/me` is down gets told the page does not exist: the wrong cause, no
-retry, and no request id to quote. A guard has three answers — wait, fail, refuse — and only a
+retry, and no request id to quote. A guard has three answers (wait, fail, refuse) and only a
 real `false` reaches the refusal.
 
 `createRequireAuth` sends an anonymous visitor to `?next=`, carrying path, query and hash. A hash
@@ -333,7 +333,7 @@ const next = safeInternalPath(new URLSearchParams(location.search).get("next"))
 `createRequireAnonymous` already performs that check and falls back to the home path you gave it.
 
 Writing a return target down is the other direction, and it has its own hazard. A Supabase client
-with no `flowType` is on the **implicit** flow — the default — so a callback comes back as
+with no `flowType` is on the **implicit** flow (the default), so a callback comes back as
 `#access_token=…&refresh_token=…`. A guard renders exactly when there is no session yet, which is
 that callback's own state while the client parses the fragment: point an OAuth `redirectTo` at a
 guarded route and a concatenated `pathname + search + hash` puts a refresh token into a query
@@ -347,8 +347,40 @@ const returnTo = returnPathFromLocation(window.location);
 ```
 
 It keeps the page and drops only a fragment carrying a credential, because the page is the part
-worth returning to. `createRequireAuth` uses it; use it anywhere else you record where someone was
-— a dead-session redirect is the common one.
+worth returning to. `createRequireAuth` uses it; use it anywhere else you record where someone was:
+a dead-session redirect is the common one.
+
+## Keep the email between sign-in screens
+
+```tsx
+import { recallAuthEmail, rememberAuthEmail } from "@gusnips/react";
+
+<input
+  name="email"
+  type="email"
+  defaultValue={recallAuthEmail()}
+  onChange={(event) => rememberAuthEmail(event.currentTarget.value)}
+/>;
+```
+
+Sign in, "use a code instead", forgot password and create account are separate screens, and each
+one used to open with an empty email field. Put those two props on every one of them and the
+address follows the person. Call `forgetAuthEmail()` where your app learns a session exists, so the
+next person at this browser starts empty.
+
+It is kept in `localStorage` for 30 minutes after the last keystroke, and never in a URL, where it
+would reach `Referer`, access logs, history and analytics. It is `localStorage` and not
+`sessionStorage` because an emailed link opens in a new tab, and a new tab does not inherit
+`sessionStorage`. That tab is where a person lands on sign-in after confirming an account. Where
+the browser blocks site data, or on React Native, the address lasts in memory until the page or the
+app is left.
+
+- Read it once, when the screen opens. It is not a store: nothing re-renders when it changes. On a
+  prerendered page, read it after hydration, never while rendering.
+- Leave the field uncontrolled. A `defaultValue` and a change handler are enough. Also call
+  `rememberAuthEmail(value)` where you read the field at submit, because some password managers fill
+  a form without firing events.
+- Never put a password, a code or a token here.
 
 ## Never dead-end anyone
 
@@ -356,13 +388,13 @@ worth returning to. `createRequireAuth` uses it; use it anywhere else you record
 import type { ErrorStateProps } from "@gusnips/react";
 ```
 
-No component ships — seven codebases have an `ErrorState.tsx` and they overlap 9–37%, because one
+No component ships: seven codebases have an `ErrorState.tsx` and they overlap 9–37%, because one
 draws a tinted icon, one an illustration, one a mascot. What they share is the prop shape, and
 the prop shape _is_ the rule: `problem`, `cause`, `fix`, and `action`. **`fix` and `action` are
 required.** A required prop is the only version of "always offer a way out" that a caller in a
 hurry cannot skip.
 
-`createErrorDescriber` turns a thrown `ApiError` into the `cause` and `fix` to put in it — plus
+`createErrorDescriber` turns a thrown `ApiError` into the `cause` and `fix` to put in it, plus
 which control to offer, and the request id to print under it:
 
 ```ts
@@ -393,7 +425,7 @@ the catalog has, the reader gets it in their own language.
 The field is `fix`, the same word as the prop above. It was `hint` until 0.6.0, which left every
 adopter writing `fix={hint}` at every error surface.
 
-`recover` is derived from `shouldRetry` — the same rule react-query retries on — so the button a
+`recover` is derived from `shouldRetry` (the same rule react-query retries on), so the button a
 reader sees and the retry that actually happens cannot disagree. Give it the same
 `durableLimitCodes` list you give `queryDefaults`, and a spent quota offers no button instead of
 one that cannot work. The words follow it too: "try again in a moment" appears only on a 5xx that
@@ -420,7 +452,7 @@ fallback: ({ says, wait }) => ({
 });
 ```
 
-Some APIs write `message` for whoever reads the screen. Some write it for whoever reads the log —
+Some APIs write `message` for whoever reads the screen. Some write it for whoever reads the log,
 in English, in an app that ships three languages. Your arm also gets the stated wait, which the
 default has nowhere to put.
 
@@ -497,6 +529,110 @@ 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.
 
+## Slash commands in a text field
+
+A slash command is text like `/help` that picks an action instead of sending a message.
+
+```ts
+import { parseCommand } from "@gusnips/react/commands";
+
+parseCommand("/help");
+// { name: "help" }
+```
+
+Names have no leading slash. Give each command other names (`aliases`) and search words (`tags`):
+
+```ts
+const commands = [
+  {
+    name: "help",
+    description: "See commands",
+    aliases: ["commands", "shortcuts"],
+    tags: ["keyboard", "guide"],
+  },
+];
+```
+
+`/commands` runs `/help`. Searching for `keyboard` finds its menu row, but `/keyboard` is not an
+executable name. `matchCommands(commands, query)` searches names, aliases, tags and descriptions,
+ignoring case and accents. Exact names rank first, then aliases, name prefixes, alias prefixes,
+tags and descriptions. Equal ranks keep registry order; each name gets one row.
+
+`resolveCommand(commands, name)` answers `matched`, `unknown` or `ambiguous`. An exact name wins
+over an alias. Two commands sharing an alias are ambiguous, not a reason to run the first one.
+
+For a controlled text field, use the hook:
+
+```tsx
+import { useSlashCommands } from "@gusnips/react/commands";
+
+const slash = useSlashCommands({
+  text,
+  commands,
+  onChange: setText,
+  onExecute: runCommand,
+  onError: showCommandError,
+});
+
+function submit() {
+  if (slash.submit()) return;
+  sendMessage(text);
+}
+```
+
+The functions in that example belong to your app. `runCommand(command, arg, altKey)` gets the
+original command object, the argument and whether Alt was held. It owns permissions and action
+errors. Supply only commands allowed in this field, with descriptions and tags in the current
+language. Changing those commands or the language refreshes the menu even if `text` stays the same.
+
+Call `slash.handleKeyDown(event)` first in the field's key handler. If it returns `true`, stop
+your own handler. Arrows move the selection; Enter picks it. Tab completes the name without
+running it. Escape hides the menu until the query changes. Shift+Enter stays yours. During IME
+composition (when a keyboard combines keystrokes into a character), the hook lets the browser
+finish that character without running or sending anything.
+
+Render the rows in your own menu. Keep focus in the field with the browser's `preventDefault`
+on mouse down; use click for the action so keyboard and screen-reader clicks work too:
+
+```tsx
+return slash.open ? (
+  <div id={slash.listId} role="listbox" aria-label="Commands">
+    {slash.items.map((command, index) => (
+      <button
+        key={command.name}
+        id={slash.itemId(command)}
+        type="button"
+        role="option"
+        tabIndex={-1}
+        aria-selected={slash.index === index}
+        onMouseEnter={() => slash.highlight(index)}
+        onMouseDown={(event) => event.preventDefault()}
+        onClick={(event) => slash.pick(command, event.altKey)}
+      >
+        /{command.name}: {command.description}
+      </button>
+    ))}
+  </div>
+) : null;
+```
+
+Give the field `role="combobox"`, `aria-autocomplete="list"`, `aria-expanded={slash.open}`,
+`aria-controls={slash.open ? slash.listId : undefined}` and `aria-activedescendant={slash.activeId}`.
+Translate the menu label too. If there are no rows, explain how to find commands and offer a
+"See commands" button that calls `slash.showAll()`. It opens the full list, even after Escape.
+`onError` is required: show what was not recognized, or which names share an alias, with the
+same way back to the list.
+
+Set `takesArg: true` when a command accepts an argument. Selecting it, or submitting its bare
+alias, completes `/name ` without running it. Completion keeps arguments already typed.
+`parseCommand` leaves multiline text as a normal message.
+
+Call `submit()` before every normal send, queue or quota check, including button and imperative
+paths. It returns `true` for commands it ran, completed or rejected, so unknown commands never
+silently become model messages. It returns `false` for ordinary text. The hook never sends a
+message, clears a draft or changes attached files; those stay with the app. It also has no timer
+or scheduler: offer a repeat command only when your app has real scheduling behind it.
+
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
@@ -511,13 +647,13 @@ Detection walks the browser's language list in the reader's order, exact tag fir
 subtag: `[pt-PT, en]` gets `pt-BR` when that is what you ship, and `[en-GB, pt-BR]` gets `en`.
 `localeGateScript` uses the same rule, so the gate and the app agree about a reader.
 
-`createAuthStore` is at `@gusnips/react/store` — a zustand store whose `isLoading` starts `false`
+`createAuthStore` is at `@gusnips/react/store`: a zustand store whose `isLoading` starts `false`
 where there is no window. A session bootstrap can only be in flight in a browser, and `true`
 during a build is a wait that never ends: it once shipped a spinner as the indexable body of a
 page whose whole job was to be found.
 
 When your store needs more than those flags, `authSlice` in the same place gives you them as a
-plain object to spread, so `create` stays yours — and with it `persist`, your own actions, and
+plain object to spread, so `create` stays yours, and with it `persist`, your own actions, and
 fields of your own:
 
 ```ts
@@ -537,7 +673,7 @@ writes you no longer own.
 ## On a phone
 
 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
+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.
@@ -555,8 +691,8 @@ no wrapper added scroll lock, focus trap, ESC, outside-dismiss, focus return, ro
 typeahead. Base UI already does all of that, and a wrapper "adding" them is a second
 implementation of something that works. Twenty were dropped.
 
-What the remaining seven buy is composition you cannot skip — no caller can ship a scrimless
-dialog — required a11y props expressed as types, and a handful of facts that each cost somebody
+What the remaining seven buy is composition you cannot skip (no caller can ship a scrimless
+dialog), required a11y props expressed as types, and a handful of facts that each cost somebody
 an afternoon. z-index goes on the Viewport, not the Popup, because `position: fixed` makes a
 stacking context. A drawer _ties_ with dialog rather than beating it, or a modal opened from
 inside a drawer never paints. A wrapper earns its place by knowing something, not by styling
@@ -577,9 +713,10 @@ lives behind a subpath, so you install a dependency only if you import the thing
 | `@gusnips/react/ui`       | the seven wrappers                       | @base-ui/react        |
 | `@gusnips/react/contract` | two prerender names                      | nothing               |
 | `@gusnips/react/theme`    | `createTheme`, `startTheme`              | react                 |
+| `@gusnips/react/commands` | slash matching and `useSlashCommands`    | react                 |
 
 The rule behind that table: **a peer marked optional must not be reachable from the main entry
-point.** An optional peer the barrel imports anyway is not optional — it is a required one whose
+point.** An optional peer the barrel imports anyway is not optional: it is a required one whose
 error moved from install time to your first build, which is the worse of the two places to learn
 about it.
 

package/dist/api-client.d.ts

@@ -3,10 +3,10 @@ import { ApiError } from "./api-error.ts";
 /**
  * The app's one door to the API. Nothing else should call `fetch`.
  *
- * Every route answers the same envelope, so unwrapping and error-shaping belong here once
- * rather than in every hook. Three donors built this independently and all three arrived at
- * single-flight token refresh — see {@link SessionAdapter.refresh} for the reason, which is
- * the sharpest thing in this file.
+ * Every route answers the same envelope, so unwrapping and error-shaping belong here once rather
+ * than in every hook. Three donors built this independently and all three arrived at single-flight
+ * token refresh. See {@link SessionAdapter.refresh} for the reason, which is the sharpest thing in
+ * this file.
  *
  * Four things deliberately did NOT come across from the donors, because they belong to a
  * product and not to a client:
@@ -14,7 +14,7 @@ import { ApiError } from "./api-error.ts";
  * - **Toasts.** Whether a failure is spoken aloud is a design decision that differs per surface.
  *   Throw, and let the caller decide.
  * - **In-flight GET deduplication.** react-query already dedups by key, so the client's copy is
- *   redundant — and one donor's version returned a `clone()` of a body already being consumed,
+ *   redundant. One donor's version also returned a `clone()` of a body already being consumed,
  *   which is a race with no symptom until it has one.
  * - **Service-status tracking and impersonation.** One donor's, and firmly its own.
  * - **Analytics correlation headers.** Injected through {@link ApiClientOptions.headers}.
@@ -23,8 +23,8 @@ import { ApiError } from "./api-error.ts";
 export interface RefreshResult {
     token: string | null;
     /**
-     * False when the refresh never got an ANSWER out of the auth server — a dropped connection,
-     * a 5xx, a captive portal.
+     * False when the refresh never got an ANSWER out of the auth server because of a dropped
+     * connection, a 5xx or a captive portal.
      *
      * This flag is invariant 3, and only one of three donors had it. Losing a packet says nothing
      * about whether a session is still good, so a client that collapses "auth said no" into
@@ -35,8 +35,8 @@ export interface RefreshResult {
     reachedAuth: boolean;
 }
 /**
- * The seam onto whatever holds the session. Supabase in every donor so far, but nothing here
- * knows that — an adapter is four lines and keeps the auth vendor out of this package.
+ * The seam onto whatever holds the session. Supabase in every donor so far, but nothing here knows
+ * that. An adapter is four lines and keeps the auth vendor out of this package.
  */
 export interface SessionAdapter {
     getToken(): Promise<string | null>;
@@ -44,9 +44,9 @@ export interface SessionAdapter {
     signOut(): Promise<void>;
 }
 /**
- * How long anything here waits on a sign-out: the default for
- * {@link ApiClientOptions.signOutTimeoutMs}, and the deadline of `signOutEvenOffline` in
- * `@gusnips/react/supabase`. Shared so the two give up together — a redirect that gave up sooner
+ * How long anything here waits on a sign-out: the default for {@link
+ * ApiClientOptions.signOutTimeoutMs}, and the deadline of `signOutEvenOffline` in
+ * `@gusnips/react/supabase`. Shared so the two give up together. A redirect that gave up sooner
  * would navigate away while the session was still in storage.
  */
 export declare const SIGN_OUT_TIMEOUT_MS = 3000;
@@ -64,54 +64,54 @@ export interface ApiClientOptions {
      */
     headers?: () => Record<string, string>;
     /**
-     * The session is gone and cannot be renewed — send them to sign in.
+     * The session is gone and cannot be renewed. Send them to sign in.
      *
      * The client does not know the route, and it deliberately still THROWS after calling this:
      * `location.replace()` does not stop the current frame, so a caller's own `onError` must
      * still run or a half-finished screen keeps rendering against data that will never arrive.
      * The error it throws carries `expected: true`.
      *
-     * Ending the session IN PLACE is equally supported — routing to the sign-in screen without a
-     * reload — and it is the case that keeps this client alive across the next sign-in. The
-     * sign-out latch is keyed on the refused token for exactly that reason; see `refusedToken`.
+     * Routing to the sign-in screen without a reload is equally supported. It is the case that keeps
+     * this client alive across the next sign-in. The sign-out latch is keyed on the refused token for
+     * exactly that reason; see `refusedToken`.
      */
     onSessionDead: () => void;
     /**
      * Every failed response, seen once, just before it is thrown.
      *
-     * For a reaction that belongs to the whole app rather than to one call site. The donor's case
-     * is the sharp one: a mid-session account suspension 403s every authed route except
-     * `GET /auth/me`, so the moment one arrives the app has to refresh `me` and route to the
-     * screen that explains it — otherwise every query on the page fails at once and the shell
-     * half-renders behind an error storm until `me` goes stale on its own.
+     * For a reaction that belongs to the whole app rather than to one call site. The donor's case is
+     * the sharp one: a mid-session account suspension 403s every authed route except `GET /auth/me`,
+     * so the moment one arrives the app has to refresh `me` and route to the screen that explains it.
+     * Otherwise every query on the page fails at once and the shell half-renders behind an error
+     * storm until `me` goes stale on its own.
      *
-     * It cannot live at a call site, because the point is that it fires from whichever call
-     * happened to be first. It went in the donor's client directly, which made the client import
-     * its query cache and its query keys — a cycle that this hook removes.
+     * It cannot live at a call site, because the point is that it fires from whichever call happened
+     * to be first. It went in the donor's client directly, which made the client import its query
+     * cache and its query keys, creating a cycle that this hook removes.
      *
      * Observation only: the error is thrown either way, and throwing from here would replace a
      * real API failure with whatever the listener hit.
      *
      * **The response comes with it, because a refusal's headers are otherwise unreachable.**
-     * `request` throws before the `Response` escapes, so an adopter whose API states something on
-     * the error path had no way to read it at all — one reports what every call cost, refusals
-     * included, which is how "a blocked page costs nothing" becomes a thing a customer can check
-     * rather than a thing we assert. That is the distinction worth keeping: field-error flattening
-     * and a per-call meter callback both stayed in their products, because a product can write
-     * those itself. This one it cannot, at any price, and a capability the kit makes unreachable
-     * is a regression the kit has to undo.
+     * `request` throws before the `Response` escapes, so an adopter whose API states something on the
+     * error path had no way to read it at all. One reports what every call cost, refusals included,
+     * which is how "a blocked page costs nothing" becomes a thing a customer can check rather than a
+     * thing we assert. That is the distinction worth keeping: field-error flattening and a per-call
+     * meter callback both stayed in their products, because a product can write those itself. This
+     * one it cannot, at any price, and a capability the kit makes unreachable is a regression the kit
+     * has to undo.
      *
-     * The BODY has already been read by the time this runs — the envelope was needed to build the
-     * error — so `response.json()` here throws. The headers are what is left, and what this is for.
+     * The BODY has already been read by the time this runs to build the error from the envelope, so
+     * `response.json()` here throws. The headers are what is left, and what this is for.
      */
     onError?: (error: ApiError, response: Response) => void;
     /**
      * Abort a request that has not answered. Default 30s.
      *
-     * Neither donor bounded its authenticated requests at all — both bounded only their keyless
-     * clients — so a stalled connection was a spinner with no end. providerkit learned the same
-     * lesson about streams: a request with no deadline is a bug that only shows up on a bad
-     * network, which is exactly when nobody can reproduce it.
+     * Neither donor bounded its authenticated requests. Both bounded only their keyless clients, so a
+     * stalled connection was a spinner with no end. providerkit learned the same lesson about
+     * streams: a request with no deadline is a bug that only shows up on a bad network, which is
+     * exactly when nobody can reproduce it.
      */
     timeoutMs?: number;
     /** How many times to refresh-and-retry a 401. Default 2. */
@@ -121,9 +121,9 @@ export interface ApiClientOptions {
     /**
      * How long to wait for `signOut()` before redirecting anyway. Default 3s.
      *
-     * A fail-safe, and one donor added it after the failure it prevents: awaiting `signOut()`
-     * covers a rejection but not a HANG, and a hang leaves the tab signed out in name only —
-     * still on the page, every request 401ing, nothing left that could redirect it.
+     * A fail-safe, and one donor added it after the failure it prevents: awaiting `signOut()` covers
+     * a rejection but not a HANG, and a hang leaves the tab signed out in name only: still on the
+     * page, every request 401ing, nothing left that could redirect it.
      */
     signOutTimeoutMs?: number;
     /** Header carrying the server's request id, echoed onto {@link ApiError.requestId}. */
@@ -143,9 +143,9 @@ export interface ApiClient {
     put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     /**
-     * DELETE, discarding whatever comes back. Returns `void` because 204 is the usual answer and
-     * a 204 has NO BODY — `res.json()` on one throws `Unexpected end of JSON input`, which reads
-     * like a malformed response and is really just a success nobody was allowed to parse.
+     * DELETE, discarding whatever comes back. Returns `void` because 204 is the usual answer and a
+     * 204 has NO BODY. `res.json()` on one throws `Unexpected end of JSON input`, which reads like a
+     * malformed response and is really just a success nobody was allowed to parse.
      *
      * Split from {@link ApiClient.delJson} rather than guessing per response, because the guess is
      * the part that hides a bug: a route that was supposed to answer with data and returned
@@ -153,21 +153,21 @@ export interface ApiClient {
      * layers away. The donor that hit this had written exactly these two functions.
      */
     del(path: string, options?: RequestOptions): Promise<void>;
-    /** The DELETE that answers with something worth reading — a queue entry it handed back. */
+    /** The DELETE that answers with something worth reading, such as a queue entry it handed back. */
     delJson<T>(path: string, options?: RequestOptions): Promise<T>;
     /**
-     * The whole envelope rather than just `data`, for a route whose `meta` is half the answer —
-     * a list's `total`, or a metered call's receipt.
+     * The whole envelope rather than just `data`, for a route whose `meta` is half the answer, such
+     * as a list's `total` or a metered call's receipt.
      */
     page<T, M>(path: string, options?: RequestOptions): Promise<ApiSuccess<T, M>>;
     /**
      * The same, off a POST.
      *
-     * Two adopters needed this and both wrote the same workaround: `client.request(…)` followed by
-     * a hand-rolled `res.json()`, stepping around the client's own envelope reader and its one
-     * assertion about the success shape. One of them left the reason sitting in a comment — "the
-     * whole envelope is reachable off a GET and not off a POST, so this one reads the body itself"
-     * — which is this package describing its own gap in somebody else's file.
+     * Two adopters needed this and both wrote the same workaround: `client.request(…)` followed by a
+     * hand-rolled `res.json()`, stepping around the client's own envelope reader and its one
+     * assertion about the success shape. One of them left the reason sitting in a comment: "the whole
+     * envelope is reachable off a GET and not off a POST, so this one reads the body itself". This
+     * package's gap was described in somebody else's file.
      *
      * A metered route takes a body whenever its input is too long or too punctuated to be a path
      * segment (a URL, a search query), and then the receipt has to survive the POST too. When the

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/api-client.js

@@ -2,9 +2,9 @@ import { isApiError } from "@gusnips/http";
 import { parseRetryAfter } from "@gusnips/http/retry";
 import { ApiError } from "./api-error.js";
 /**
- * How long anything here waits on a sign-out: the default for
- * {@link ApiClientOptions.signOutTimeoutMs}, and the deadline of `signOutEvenOffline` in
- * `@gusnips/react/supabase`. Shared so the two give up together — a redirect that gave up sooner
+ * How long anything here waits on a sign-out: the default for {@link
+ * ApiClientOptions.signOutTimeoutMs}, and the deadline of `signOutEvenOffline` in
+ * `@gusnips/react/supabase`. Shared so the two give up together. A redirect that gave up sooner
  * would navigate away while the session was still in storage.
  */
 export const SIGN_OUT_TIMEOUT_MS = 3_000;