@gusnips/react 0.9.14 → 0.9.16

package/README.md

@@ -284,8 +284,10 @@ operator arriving while `/auth/me` is down gets told the page does not exist: th
 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. The URL
-survives reloads, OAuth and email links; router state does not. Read it through the main entry's
+`createRequireAuth` sends an anonymous visitor to `?next=`, carrying path, query and hash. A hash
+that carries a sign-in token (`#access_token=…`, as an OAuth callback does) is left off, so the
+token never lands in the address, the logs or the history. The URL survives reloads, OAuth and
+email links; router state does not. Read it through the main entry's
 validator before navigating yourself:
 
 ```ts
@@ -334,6 +336,26 @@ const { cause, fix, recover, reference } = describeError(error);
 // recover: "retry" | "signin" | "wait" | "none"
 ```
 
+Build it once. An app in one language writes its four sentences out:
+
+```ts
+const inTime = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+
+export const describeError = createErrorDescriber({
+  copy: {
+    network: "We could not reach the server.",
+    networkHint: "Check your connection, then try again.",
+    unexpected: "Something went wrong on our side.",
+    retrySoon: "Try again in a moment.",
+  },
+  formatWait: (secs) => inTime.format(secs, "second"),
+});
+```
+
+An app that translates passes `t`, `copyPrefix`, `messageKeyPrefix` and `knownMessageKeys`
+instead. Its catalog holds those four under `copyPrefix`, and when the server names a sentence
+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.
 
@@ -342,7 +364,7 @@ reader sees and the retry that actually happens cannot disagree. Give it the sam
 `durableLimitCodes` list you give `queryDefaults`, and a spent quota offers no button instead of
 one that cannot work.
 
-You also say how a stated wait becomes words:
+`formatWait` says how a stated wait becomes words:
 
 ```ts
 formatWait: (secs) => humanizeWait(t, secs, "errors."); // three ICU plural keys

package/dist/describe-error.d.ts

@@ -123,10 +123,8 @@ export interface ErrorContext {
      */
     recover: RecoveryKind;
 }
-export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix extends string, ServerName extends string> {
-    t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName | PluralBase<ServerName>}`>;
-    /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
-    copyPrefix: Prefix;
+/** What both forms share: everything but where the words come from. */
+interface DescriberRules {
     /**
      * How a stated wait becomes words, for the `wait` an arm reads off its context.
      *
@@ -137,6 +135,44 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
      * `(secs) => formatIn(secs, locale)` — and the catalog you need is the one you can see.
      */
     formatWait: (secs: number) => string;
+    /**
+     * Per-code copy. Everything not listed falls through to the default arm.
+     *
+     * The arms look up the app's own keys, so they close over the app's `t` rather than being
+     * handed one — this module has no names for that copy and no business typing it.
+     *
+     * Annotate your object `Partial<Record<YourErrorCode, ErrorArm>>` where you write it, and a
+     * code that does not exist is a compile error at the arm rather than a branch that never runs.
+     */
+    codes?: Partial<Record<string, ErrorArm>>;
+    /**
+     * What to say when nothing in `codes` matches: a code this build has no arm for, or an answer
+     * with no envelope at all.
+     *
+     * The built-in arm hands the reader the server's own `message`, and for one API in the fleet
+     * that is right — its message IS the sentence a person should read. For another it is exactly
+     * wrong: that repo's own i18n rules say `message` is "the English fallback for logs", and it
+     * ships three languages, so the built-in would put developer English in front of a reader who
+     * does not speak it. One default cannot be right for both, and the one baked in here was
+     * simply the first adopter's convention, mistaken for a fact.
+     *
+     * An arm here is also handed the stated wait, which the built-in spends on nothing: a refusal
+     * with no arm of its own could state its expiry and have that go unsaid.
+     */
+    fallback?: ErrorArm;
+    /**
+     * The codes that mean "this limit does not clear by waiting" — **the same list you hand
+     * `queryDefaults`**, because it answers the same question and a second copy is a second
+     * chance to disagree with the retry rule. Declare it once in the app and pass it twice.
+     */
+    durableLimitCodes?: readonly string[];
+    /** Longest stated wait still worth a retry rather than a countdown. Matches `queryDefaults`. */
+    maxRetryWaitSecs?: number;
+}
+export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix extends string, ServerName extends string> extends DescriberRules {
+    t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName | PluralBase<ServerName>}`>;
+    /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
+    copyPrefix: Prefix;
     /**
      * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
      * ignored — the server names a sentence, it does not get to name any key in the app.
@@ -176,42 +212,22 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
      * deliberately takes only the params — an arm that needs the error has `ctx` for that.
      */
     localizeParams?: (params: Record<string, string | number> | undefined) => Record<string, unknown> | undefined;
-    /**
-     * Per-code copy. Everything not listed falls through to the default arm.
-     *
-     * The arms look up the app's own keys, so they close over the app's `t` rather than being
-     * handed one — this module has no names for that copy and no business typing it.
-     *
-     * Annotate your object `Partial<Record<YourErrorCode, ErrorArm>>` where you write it, and a
-     * code that does not exist is a compile error at the arm rather than a branch that never runs.
-     */
-    codes?: Partial<Record<string, ErrorArm>>;
-    /**
-     * What to say when nothing in `codes` matches: a code this build has no arm for, or an answer
-     * with no envelope at all.
-     *
-     * The built-in arm hands the reader the server's own `message`, and for one API in the fleet
-     * that is right — its message IS the sentence a person should read. For another it is exactly
-     * wrong: that repo's own i18n rules say `message` is "the English fallback for logs", and it
-     * ships three languages, so the built-in would put developer English in front of a reader who
-     * does not speak it. One default cannot be right for both, and the one baked in here was
-     * simply the first adopter's convention, mistaken for a fact.
-     *
-     * An arm here is also handed the stated wait, which the built-in spends on nothing: a refusal
-     * with no arm of its own could state its expiry and have that go unsaid.
-     */
-    fallback?: ErrorArm;
-    /**
-     * The codes that mean "this limit does not clear by waiting" — **the same list you hand
-     * `queryDefaults`**, because it answers the same question and a second copy is a second
-     * chance to disagree with the retry rule. Declare it once in the app and pass it twice.
-     */
-    durableLimitCodes?: readonly string[];
-    /** Longest stated wait still worth a retry rather than a countdown. Matches `queryDefaults`. */
-    maxRetryWaitSecs?: number;
+}
+/**
+ * An app in one language writes its four sentences out, and needs no `t`, no prefixes and no
+ * catalog.
+ *
+ * With no catalog, the server cannot name a sentence the app carries, so a refusal with no arm of
+ * its own shows the server's `message`. In a one-language product that is the right sentence: the
+ * server writes in the same language the app does.
+ */
+export interface OneLanguageDescriberOptions extends DescriberRules {
+    copy: Record<CopyName, string>;
 }
 export type ErrorArm = (ctx: ErrorContext) => ErrorCopy;
-/** Build the describer. */
-export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, localizeParams, codes, fallback, durableLimitCodes, maxRetryWaitSecs, }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError;
+/** Build the describer for an app in one language. */
+export declare function createErrorDescriber(options: OneLanguageDescriberOptions): (error: unknown) => DescribedError;
+/** Build the describer for an app that translates. */
+export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>(options: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError;
 export {};
 //# sourceMappingURL=describe-error.d.ts.map

package/dist/describe-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY;AACtB,mDAAmD;AACjD,OAAO;AACT,gEAAgE;GAC9D,QAAQ;AACV,gFAAgF;GAC9E,MAAM;AACR,iFAAiF;GAC/E,MAAM,CAAC;AAEX,+FAA+F;AAC/F,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kGAAkG;IAClG,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,mFAAmF;IACnF,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,IAAI,CACnD,GAAG,EAAE,GAAG,EACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ,wFAAwF;AACxF,KAAK,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,WAAW,CAAC;AAE5D;;;;;;;;GAQG;AACH,KAAK,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,GAAG,WAAW,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,KAAK,YAAY,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AACtE,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,IAAI,YAAY,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC;AA4BzF;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,MAAM,EAChD,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAMR;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;OAKG;IACH,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB,CACpC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM;IAEzB,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,GAAG,GAAG,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC/F,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC;;;;;;;;;OASG;IACH,gBAAgB,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;;;;OAYG;IACH,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,KAChD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC1C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,SAAS,CAAC;AAExD,2BAA2B;AAC3B,wBAAgB,oBAAoB,CAClC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM,EACzB,EACA,CAAC,EACD,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,cAAmC,EACnC,KAAU,EACV,QAAQ,EACR,iBAAsB,EACtB,gBAAgB,GACjB,EAAE,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAyG9F"}
+{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}

package/dist/describe-error.js

@@ -24,8 +24,7 @@ export function humanizeWait(t, secs, prefix) {
         return t(`${prefix}waitMinutes`, { count: Math.ceil(secs / 60) });
     return t(`${prefix}waitHours`, { count: Math.ceil(secs / 3600) });
 }
-/** Build the describer. */
-export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, localizeParams = (params) => params, codes = {}, fallback, durableLimitCodes = [], maxRetryWaitSecs, }) {
+function translatedWords({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, localizeParams = (params) => params, }) {
     // Both spellings of every name: the one the catalog stores, and — for a plural — the one the
     // server sends. `Object.keys` and not `in`, which would have accepted "toString".
     const known = new Set();
@@ -36,19 +35,28 @@ export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPref
     // Still sound, and still the reason nothing here needs a cast: the set holds exactly the raw
     // keys and their plural bases, which is exactly what the predicate claims.
     const has = (name) => known.has(name);
-    function serverSentence(error) {
-        const lookup = (named) => {
-            if (named === undefined || !named.startsWith(messageKeyPrefix))
-                return null;
-            const name = named.slice(messageKeyPrefix.length);
-            return has(name) ? t(`${messageKeyPrefix}${name}`, localizeParams(error.params)) : null;
-        };
-        // `messageKey` first: an API that sends both means the key, and the code is what the UI
-        // switches on. The code is only consulted when there is no key to prefer, and it is spelled
-        // under the same prefix so the gate is identical.
-        return (lookup(error.messageKey) ??
-            (error.code === undefined ? null : lookup(`${messageKeyPrefix}${error.code}`)));
-    }
+    return {
+        copyOf: (name) => t(`${copyPrefix}${name}`),
+        serverSentence(error) {
+            const lookup = (named) => {
+                if (named === undefined || !named.startsWith(messageKeyPrefix))
+                    return null;
+                const name = named.slice(messageKeyPrefix.length);
+                return has(name) ? t(`${messageKeyPrefix}${name}`, localizeParams(error.params)) : null;
+            };
+            // `messageKey` first: an API that sends both means the key, and the code is what the UI
+            // switches on. The code is only consulted when there is no key to prefer, and it is spelled
+            // under the same prefix so the gate is identical.
+            return (lookup(error.messageKey) ??
+                (error.code === undefined ? null : lookup(`${messageKeyPrefix}${error.code}`)));
+        },
+    };
+}
+export function createErrorDescriber(options) {
+    const { formatWait, codes = {}, fallback, durableLimitCodes = [], maxRetryWaitSecs } = options;
+    const { copyOf, serverSentence } = "copy" in options
+        ? { copyOf: (name) => options.copy[name], serverSentence: () => null }
+        : translatedWords(options);
     /**
      * Which control to offer, decided once and never switched on separately.
      *
@@ -86,8 +94,8 @@ export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPref
      */
     const unmapped = fallback ??
         (({ error, says }) => ({
-            cause: says ?? ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
-            fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+            cause: says ?? ((error.code === undefined ? "" : error.message) || copyOf("unexpected")),
+            fix: error.status >= 500 ? copyOf("retrySoon") : undefined,
         }));
     return function describeError(error) {
         if (!(error instanceof ApiError)) {
@@ -95,10 +103,10 @@ export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPref
             // never worth showing a stack trace for. `shouldRetry` answers a non-response the same way,
             // so these two agree here without either being told about the other.
             return {
-                cause: t(`${copyPrefix}network`),
+                cause: copyOf("network"),
                 // The catalog KEY keeps its name while the field becomes `fix`: renaming it would cost
                 // every adopter a JSON edit in every language, for a string no caller ever types.
-                fix: t(`${copyPrefix}networkHint`),
+                fix: copyOf("networkHint"),
                 recover: "retry",
             };
         }

package/dist/describe-error.js.map

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

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { createApiClient, type ApiClient, type ApiClientOptions, type RefreshRes
 export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
 export { queryDefaults, queryView, retryDelayMs, shouldRetry, type QueryDefaultsOptions, type QueryView, } from "./query.ts";
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, } from "./error-boundary.tsx";
-export { createErrorDescriber, humanizeWait, type DescribedError, type ErrorArm, type ErrorContext, type ErrorCopy, type ErrorDescriberOptions, type RecoveryKind, type Translate, } from "./describe-error.ts";
+export { createErrorDescriber, humanizeWait, type DescribedError, type ErrorArm, type ErrorContext, type ErrorCopy, type ErrorDescriberOptions, type OneLanguageDescriberOptions, type RecoveryKind, type Translate, } from "./describe-error.ts";
 export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, isStaleBuild, RELOAD_GUARD_KEY, reloadOnce, } from "./deploy-recovery.ts";
 export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
 export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,4FAA4F;AAC5F,8FAA8F;AAC9F,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,GAGZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GAQb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,4FAA4F;AAC5F,8FAA8F;AAC9F,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,GAGZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GASb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/dist/states.d.ts

@@ -33,6 +33,11 @@ export interface EmptyStateProps {
      *
      * Only one donor had this, and it is the difference between a screen reader announcing a
      * page and announcing nothing.
+     *
+     * **The type cannot make your panel read it.** A panel that always renders an `<h3>` accepts
+     * `headingLevel={1}` and ignores it, and the page ships with no `h1`. The guide's own example
+     * app did exactly that on its 404 until a browser check found it. Render the heading from the
+     * prop: `` const Heading = `h${headingLevel}` as const ``.
      */
     headingLevel?: 1 | 2 | 3;
     className?: string;

package/dist/states.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"states.d.ts","sourceRoot":"","sources":["../src/states.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,WAAW,EAAE,SAAS,CAAC;IACvB,yDAAyD;IACzD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,iCAAiC;IACjC,GAAG,EAAE,SAAS,CAAC;IACf,8DAA8D;IAC9D,MAAM,EAAE,SAAS,CAAC;IAClB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gDAAgD;IAChD,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"states.d.ts","sourceRoot":"","sources":["../src/states.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,WAAW,EAAE,SAAS,CAAC;IACvB,yDAAyD;IACzD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,iCAAiC;IACjC,GAAG,EAAE,SAAS,CAAC;IACf,8DAA8D;IAC9D,MAAM,EAAE,SAAS,CAAC;IAClB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gDAAgD;IAChD,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.14",
+  "version": "0.9.16",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
@@ -80,7 +80,7 @@
     "release:major": "bun pm version major && bun publish --access public"
   },
   "dependencies": {
-    "@gusnips/http": "0.1.2",
+    "@gusnips/http": "0.1.3",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.6.0"
   },

package/src/describe-error.test.ts

@@ -386,3 +386,68 @@ describe("createErrorDescriber, when the code names the sentence", () => {
     expect(describeError(error).cause).toBe("errors.network");
   });
 });
+
+/**
+ * The form for an app in one language. It had to pass `copyPrefix`, `messageKeyPrefix` and an
+ * empty `knownMessageKeys` to say "I have no catalog", and typing `t`'s argument by hand broke the
+ * inference. It writes its four sentences out instead.
+ */
+describe("one language", () => {
+  const COPY = {
+    network: "We could not reach the server.",
+    networkHint: "Check your connection, then try again.",
+    unexpected: "Something went wrong on our side.",
+    retrySoon: "Try again in a moment.",
+  };
+  const describeError = createErrorDescriber({
+    copy: COPY,
+    formatWait: (secs) => `in ${secs}s`,
+    codes: {
+      RATE_LIMIT_EXCEEDED: ({ wait }) => ({ cause: "Too many at once.", fix: `Try ${wait}.` }),
+    },
+  });
+
+  it("takes its own sentences from `copy`", () => {
+    expect(describeError(new TypeError("Failed to fetch"))).toEqual({
+      cause: COPY.network,
+      fix: COPY.networkHint,
+      recover: "retry",
+    });
+    expect(describeError(new ApiError(502, null))).toMatchObject({
+      cause: COPY.unexpected,
+      fix: COPY.retrySoon,
+    });
+  });
+
+  // No catalog, so nothing the server names can reach the screen as a key. The server writes in
+  // the app's one language, so its own sentence is what an unmapped refusal shows.
+  it("shows the server's sentence and never a key the server named", () => {
+    const error = new ApiError(409, {
+      code: "SLUG_TAKEN",
+      message: "That address is taken.",
+      messageKey: "serverErrors.slugTaken",
+    });
+    expect(describeError(error).cause).toBe("That address is taken.");
+  });
+
+  it("still runs the arms and the stated wait", () => {
+    const error = new ApiError(
+      429,
+      { code: "RATE_LIMIT_EXCEEDED", message: "slow down" },
+      { retryAfterSecs: 30 },
+    );
+    expect(describeError(error)).toMatchObject({
+      cause: "Too many at once.",
+      fix: "Try in 30s.",
+      recover: "wait",
+    });
+  });
+
+  it("refuses `copy` with a sentence missing", () => {
+    // @ts-expect-error -- `retrySoon` is missing, and a 5xx would show `undefined` without it.
+    createErrorDescriber({
+      copy: { network: "", networkHint: "", unexpected: "" },
+      formatWait: String,
+    });
+  });
+});

package/src/describe-error.ts

@@ -175,14 +175,8 @@ export interface ErrorContext {
   recover: RecoveryKind;
 }
 
-export interface ErrorDescriberOptions<
-  Prefix extends string,
-  ServerPrefix extends string,
-  ServerName extends string,
-> {
-  t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName | PluralBase<ServerName>}`>;
-  /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
-  copyPrefix: Prefix;
+/** What both forms share: everything but where the words come from. */
+interface DescriberRules {
   /**
    * How a stated wait becomes words, for the `wait` an arm reads off its context.
    *
@@ -193,6 +187,49 @@ export interface ErrorDescriberOptions<
    * `(secs) => formatIn(secs, locale)` — and the catalog you need is the one you can see.
    */
   formatWait: (secs: number) => string;
+  /**
+   * Per-code copy. Everything not listed falls through to the default arm.
+   *
+   * The arms look up the app's own keys, so they close over the app's `t` rather than being
+   * handed one — this module has no names for that copy and no business typing it.
+   *
+   * Annotate your object `Partial<Record<YourErrorCode, ErrorArm>>` where you write it, and a
+   * code that does not exist is a compile error at the arm rather than a branch that never runs.
+   */
+  codes?: Partial<Record<string, ErrorArm>>;
+  /**
+   * What to say when nothing in `codes` matches: a code this build has no arm for, or an answer
+   * with no envelope at all.
+   *
+   * The built-in arm hands the reader the server's own `message`, and for one API in the fleet
+   * that is right — its message IS the sentence a person should read. For another it is exactly
+   * wrong: that repo's own i18n rules say `message` is "the English fallback for logs", and it
+   * ships three languages, so the built-in would put developer English in front of a reader who
+   * does not speak it. One default cannot be right for both, and the one baked in here was
+   * simply the first adopter's convention, mistaken for a fact.
+   *
+   * An arm here is also handed the stated wait, which the built-in spends on nothing: a refusal
+   * with no arm of its own could state its expiry and have that go unsaid.
+   */
+  fallback?: ErrorArm;
+  /**
+   * The codes that mean "this limit does not clear by waiting" — **the same list you hand
+   * `queryDefaults`**, because it answers the same question and a second copy is a second
+   * chance to disagree with the retry rule. Declare it once in the app and pass it twice.
+   */
+  durableLimitCodes?: readonly string[];
+  /** Longest stated wait still worth a retry rather than a countdown. Matches `queryDefaults`. */
+  maxRetryWaitSecs?: number;
+}
+
+export interface ErrorDescriberOptions<
+  Prefix extends string,
+  ServerPrefix extends string,
+  ServerName extends string,
+> extends DescriberRules {
+  t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName | PluralBase<ServerName>}`>;
+  /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
+  copyPrefix: Prefix;
   /**
    * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
    * ignored — the server names a sentence, it does not get to name any key in the app.
@@ -234,60 +271,39 @@ export interface ErrorDescriberOptions<
   localizeParams?: (
     params: Record<string, string | number> | undefined,
   ) => Record<string, unknown> | undefined;
-  /**
-   * Per-code copy. Everything not listed falls through to the default arm.
-   *
-   * The arms look up the app's own keys, so they close over the app's `t` rather than being
-   * handed one — this module has no names for that copy and no business typing it.
-   *
-   * Annotate your object `Partial<Record<YourErrorCode, ErrorArm>>` where you write it, and a
-   * code that does not exist is a compile error at the arm rather than a branch that never runs.
-   */
-  codes?: Partial<Record<string, ErrorArm>>;
-  /**
-   * What to say when nothing in `codes` matches: a code this build has no arm for, or an answer
-   * with no envelope at all.
-   *
-   * The built-in arm hands the reader the server's own `message`, and for one API in the fleet
-   * that is right — its message IS the sentence a person should read. For another it is exactly
-   * wrong: that repo's own i18n rules say `message` is "the English fallback for logs", and it
-   * ships three languages, so the built-in would put developer English in front of a reader who
-   * does not speak it. One default cannot be right for both, and the one baked in here was
-   * simply the first adopter's convention, mistaken for a fact.
-   *
-   * An arm here is also handed the stated wait, which the built-in spends on nothing: a refusal
-   * with no arm of its own could state its expiry and have that go unsaid.
-   */
-  fallback?: ErrorArm;
-  /**
-   * The codes that mean "this limit does not clear by waiting" — **the same list you hand
-   * `queryDefaults`**, because it answers the same question and a second copy is a second
-   * chance to disagree with the retry rule. Declare it once in the app and pass it twice.
-   */
-  durableLimitCodes?: readonly string[];
-  /** Longest stated wait still worth a retry rather than a countdown. Matches `queryDefaults`. */
-  maxRetryWaitSecs?: number;
+}
+
+/**
+ * An app in one language writes its four sentences out, and needs no `t`, no prefixes and no
+ * catalog.
+ *
+ * With no catalog, the server cannot name a sentence the app carries, so a refusal with no arm of
+ * its own shows the server's `message`. In a one-language product that is the right sentence: the
+ * server writes in the same language the app does.
+ */
+export interface OneLanguageDescriberOptions extends DescriberRules {
+  copy: Record<CopyName, string>;
 }
 
 export type ErrorArm = (ctx: ErrorContext) => ErrorCopy;
 
-/** Build the describer. */
-export function createErrorDescriber<
+/** Where the describer's words come from: its own four, and the server's when it named one. */
+interface Words {
+  copyOf: (name: CopyName) => string;
+  serverSentence: (error: ApiError) => string | null;
+}
+
+function translatedWords<
   Prefix extends string,
   ServerPrefix extends string,
   ServerName extends string,
 >({
   t,
   copyPrefix,
-  formatWait,
   messageKeyPrefix,
   knownMessageKeys,
   localizeParams = (params) => params,
-  codes = {},
-  fallback,
-  durableLimitCodes = [],
-  maxRetryWaitSecs,
-}: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError {
+}: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): Words {
   // Both spellings of every name: the one the catalog stores, and — for a plural — the one the
   // server sends. `Object.keys` and not `in`, which would have accepted "toString".
   const known = new Set<string>();
@@ -300,20 +316,49 @@ export function createErrorDescriber<
   // keys and their plural bases, which is exactly what the predicate claims.
   const has = (name: string): name is ServerName | PluralBase<ServerName> => known.has(name);
 
-  function serverSentence(error: ApiError): string | null {
-    const lookup = (named: string | undefined): string | null => {
-      if (named === undefined || !named.startsWith(messageKeyPrefix)) return null;
-      const name = named.slice(messageKeyPrefix.length);
-      return has(name) ? t(`${messageKeyPrefix}${name}`, localizeParams(error.params)) : null;
-    };
-    // `messageKey` first: an API that sends both means the key, and the code is what the UI
-    // switches on. The code is only consulted when there is no key to prefer, and it is spelled
-    // under the same prefix so the gate is identical.
-    return (
-      lookup(error.messageKey) ??
-      (error.code === undefined ? null : lookup(`${messageKeyPrefix}${error.code}`))
-    );
-  }
+  return {
+    copyOf: (name) => t(`${copyPrefix}${name}`),
+    serverSentence(error) {
+      const lookup = (named: string | undefined): string | null => {
+        if (named === undefined || !named.startsWith(messageKeyPrefix)) return null;
+        const name = named.slice(messageKeyPrefix.length);
+        return has(name) ? t(`${messageKeyPrefix}${name}`, localizeParams(error.params)) : null;
+      };
+      // `messageKey` first: an API that sends both means the key, and the code is what the UI
+      // switches on. The code is only consulted when there is no key to prefer, and it is spelled
+      // under the same prefix so the gate is identical.
+      return (
+        lookup(error.messageKey) ??
+        (error.code === undefined ? null : lookup(`${messageKeyPrefix}${error.code}`))
+      );
+    },
+  };
+}
+
+/** Build the describer for an app in one language. */
+export function createErrorDescriber(
+  options: OneLanguageDescriberOptions,
+): (error: unknown) => DescribedError;
+/** Build the describer for an app that translates. */
+export function createErrorDescriber<
+  Prefix extends string,
+  ServerPrefix extends string,
+  ServerName extends string,
+>(
+  options: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>,
+): (error: unknown) => DescribedError;
+export function createErrorDescriber<
+  Prefix extends string,
+  ServerPrefix extends string,
+  ServerName extends string,
+>(
+  options: OneLanguageDescriberOptions | ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>,
+): (error: unknown) => DescribedError {
+  const { formatWait, codes = {}, fallback, durableLimitCodes = [], maxRetryWaitSecs } = options;
+  const { copyOf, serverSentence }: Words =
+    "copy" in options
+      ? { copyOf: (name) => options.copy[name], serverSentence: () => null }
+      : translatedWords(options);
 
   /**
    * Which control to offer, decided once and never switched on separately.
@@ -351,9 +396,8 @@ export function createErrorDescriber<
   const unmapped: ErrorArm =
     fallback ??
     (({ error, says }) => ({
-      cause:
-        says ?? ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
-      fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+      cause: says ?? ((error.code === undefined ? "" : error.message) || copyOf("unexpected")),
+      fix: error.status >= 500 ? copyOf("retrySoon") : undefined,
     }));
 
   return function describeError(error: unknown): DescribedError {
@@ -362,10 +406,10 @@ export function createErrorDescriber<
       // never worth showing a stack trace for. `shouldRetry` answers a non-response the same way,
       // so these two agree here without either being told about the other.
       return {
-        cause: t(`${copyPrefix}network`),
+        cause: copyOf("network"),
         // The catalog KEY keeps its name while the field becomes `fix`: renaming it would cost
         // every adopter a JSON edit in every language, for a string no caller ever types.
-        fix: t(`${copyPrefix}networkHint`),
+        fix: copyOf("networkHint"),
         recover: "retry",
       };
     }

package/src/index.ts

@@ -68,6 +68,7 @@ export {
   type ErrorContext,
   type ErrorCopy,
   type ErrorDescriberOptions,
+  type OneLanguageDescriberOptions,
   type RecoveryKind,
   type Translate,
 } from "./describe-error.ts";

package/src/states.ts

@@ -35,6 +35,11 @@ export interface EmptyStateProps {
    *
    * Only one donor had this, and it is the difference between a screen reader announcing a
    * page and announcing nothing.
+   *
+   * **The type cannot make your panel read it.** A panel that always renders an `<h3>` accepts
+   * `headingLevel={1}` and ignores it, and the page ships with no `h1`. The guide's own example
+   * app did exactly that on its 404 until a browser check found it. Render the heading from the
+   * prop: `` const Heading = `h${headingLevel}` as const ``.
    */
   headingLevel?: 1 | 2 | 3;
   className?: string;