@gusnips/react 0.5.1 → 0.5.2

package/README.md

@@ -159,6 +159,11 @@ hurry cannot skip.
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
 `i18nInitOptions`, and `cn`.
 
+Pass `storageWriter: "app"` to `i18nInitOptions` when your own language control writes the stored
+locale. Leave it out and the detector writes it, which is right until you offer "follow the
+browser": going back to that means clearing the key and detecting again, and a detector that
+writes on every change puts the language it just detected straight back in. One writer per key.
+
 `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

package/dist/i18n.d.ts

@@ -35,8 +35,22 @@ export interface I18nInitOptions {
      * Only one donor had this. The other has the same split-origin layout and the same problem.
      */
     queryKey?: string;
+    /**
+     * Who WRITES {@link storageKey}. The detector, by default.
+     *
+     * Pass `"app"` when your own language control writes it. That is not a preference — it is what
+     * a "follow the browser" option costs. Going back to following the browser means clearing the
+     * key and calling `changeLanguage(undefined)`, which re-runs detection; a detector that caches
+     * then writes the language it just detected straight back into the key it was told to clear.
+     * The choice re-pins itself and nothing can reach that state again.
+     *
+     * Three repos on this stack, three answers: one lets the detector write, one writes it from its
+     * own control, and one does both — harmless there only because it offers no "follow the
+     * browser" state. So the rule, rather than the default: one writer per key.
+     */
+    storageWriter?: "detector" | "app";
 }
-export declare function i18nInitOptions({ fallbackLng, supportedLngs, storageKey, queryKey, }: I18nInitOptions): {
+export declare function i18nInitOptions({ fallbackLng, supportedLngs, storageKey, queryKey, storageWriter, }: I18nInitOptions): {
     fallbackLng: string;
     supportedLngs: string[];
     load: "currentOnly";

package/dist/i18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,EAC9B,WAAW,EACX,aAAa,EACb,UAAU,EACV,QAAQ,GACT,EAAE,eAAe;;;;;;;;;;;;;;;;EAuBjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAmB/E"}
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC;CACpC;AAED,wBAAgB,eAAe,CAAC,EAC9B,WAAW,EACX,aAAa,EACb,UAAU,EACV,QAAQ,EACR,aAA0B,GAC3B,EAAE,eAAe;;;;;;;;;;;;;;;;EAwBjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAmB/E"}

package/dist/i18n.js

@@ -11,7 +11,7 @@
  * product from drifting apart on the details below — each of which is a bug somebody already
  * shipped.
  */
-export function i18nInitOptions({ fallbackLng, supportedLngs, storageKey, queryKey, }) {
+export function i18nInitOptions({ fallbackLng, supportedLngs, storageKey, queryKey, storageWriter = "detector", }) {
     return {
         fallbackLng,
         supportedLngs: [...supportedLngs],
@@ -21,7 +21,8 @@ export function i18nInitOptions({ fallbackLng, supportedLngs, storageKey, queryK
             order: queryKey
                 ? ["querystring", "localStorage", "navigator"]
                 : ["localStorage", "navigator"],
-            caches: ["localStorage"],
+            // Read from always, written to only by whoever owns it — see `storageWriter`.
+            caches: storageWriter === "detector" ? ["localStorage"] : [],
             ...(queryKey ? { lookupQuerystring: queryKey } : {}),
             lookupLocalStorage: storageKey,
         },

package/dist/i18n.js.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4BH,MAAM,UAAU,eAAe,CAAC,EAC9B,WAAW,EACX,aAAa,EACb,UAAU,EACV,QAAQ,GACQ;IAChB,OAAO;QACL,WAAW;QACX,aAAa,EAAE,CAAC,GAAG,aAAa,CAAC;QACjC,IAAI,EAAE,aAAsB;QAC5B,aAAa,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,yBAAyB;QAChE,SAAS,EAAE;YACT,KAAK,EAAE,QAAQ;gBACb,CAAC,CAAC,CAAC,aAAa,EAAE,cAAc,EAAE,WAAW,CAAC;gBAC9C,CAAC,CAAC,CAAC,cAAc,EAAE,WAAW,CAAC;YACjC,MAAM,EAAE,CAAC,cAAc,CAAC;YACxB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,kBAAkB,EAAE,UAAU;SAC/B;QACD,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;QAC7B,gGAAgG;QAChG,4FAA4F;QAC5F,4FAA4F;QAC5F,sFAAsF;QACtF,wFAAwF;QACxF,2FAA2F;QAC3F,8FAA8F;KAC/F,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAI,SAAY,EAAE,IAA4B;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,MAAM,CACxB,UAAU,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EACvF,GAAG,CACJ,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAE9F,MAAM,IAAI,GAAG,CAAC,KAAc,EAAW,EAAE;QACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YACpC,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO,IAAI,CAAC,SAAS,CAAM,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA0CH,MAAM,UAAU,eAAe,CAAC,EAC9B,WAAW,EACX,aAAa,EACb,UAAU,EACV,QAAQ,EACR,aAAa,GAAG,UAAU,GACV;IAChB,OAAO;QACL,WAAW;QACX,aAAa,EAAE,CAAC,GAAG,aAAa,CAAC;QACjC,IAAI,EAAE,aAAsB;QAC5B,aAAa,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,yBAAyB;QAChE,SAAS,EAAE;YACT,KAAK,EAAE,QAAQ;gBACb,CAAC,CAAC,CAAC,aAAa,EAAE,cAAc,EAAE,WAAW,CAAC;gBAC9C,CAAC,CAAC,CAAC,cAAc,EAAE,WAAW,CAAC;YACjC,8EAA8E;YAC9E,MAAM,EAAE,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE;YAC5D,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,kBAAkB,EAAE,UAAU;SAC/B;QACD,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;QAC7B,gGAAgG;QAChG,4FAA4F;QAC5F,4FAA4F;QAC5F,sFAAsF;QACtF,wFAAwF;QACxF,2FAA2F;QAC3F,8FAA8F;KAC/F,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAI,SAAY,EAAE,IAA4B;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,MAAM,CACxB,UAAU,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EACvF,GAAG,CACJ,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAE9F,MAAM,IAAI,GAAG,CAAC,KAAc,EAAW,EAAE;QACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;YACpC,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO,IAAI,CAAC,SAAS,CAAM,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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",

package/src/i18n.test.ts

@@ -83,4 +83,19 @@ describe("i18nInitOptions", () => {
     expect(detection.order).toEqual(["localStorage", "navigator"]);
     expect(detection).not.toHaveProperty("lookupQuerystring");
   });
+
+  // An app with a "follow the browser" option has to own the key. Getting back to that state
+  // means clearing it and re-running detection — and a caching detector writes the language it
+  // just detected back into the key it was told to clear, so the choice re-pins itself and the
+  // option can never be reached again. The fourth adopter found this; the package had the write
+  // hardcoded on.
+  it("leaves the key alone when the app is the one writing it", () => {
+    const base = { fallbackLng: "en", supportedLngs: ["en"], storageKey: "app.locale" } as const;
+    const app = i18nInitOptions({ ...base, storageWriter: "app" });
+
+    expect(app.detection.caches).toEqual([]);
+    // Still READ: the app writes the key, the detector is what notices it.
+    expect(app.detection.lookupLocalStorage).toBe("app.locale");
+    expect(i18nInitOptions(base).detection.caches).toEqual(["localStorage"]);
+  });
 });

package/src/i18n.ts

@@ -36,6 +36,20 @@ export interface I18nInitOptions {
    * Only one donor had this. The other has the same split-origin layout and the same problem.
    */
   queryKey?: string;
+  /**
+   * Who WRITES {@link storageKey}. The detector, by default.
+   *
+   * Pass `"app"` when your own language control writes it. That is not a preference — it is what
+   * a "follow the browser" option costs. Going back to following the browser means clearing the
+   * key and calling `changeLanguage(undefined)`, which re-runs detection; a detector that caches
+   * then writes the language it just detected straight back into the key it was told to clear.
+   * The choice re-pins itself and nothing can reach that state again.
+   *
+   * Three repos on this stack, three answers: one lets the detector write, one writes it from its
+   * own control, and one does both — harmless there only because it offers no "follow the
+   * browser" state. So the rule, rather than the default: one writer per key.
+   */
+  storageWriter?: "detector" | "app";
 }
 
 export function i18nInitOptions({
@@ -43,6 +57,7 @@ export function i18nInitOptions({
   supportedLngs,
   storageKey,
   queryKey,
+  storageWriter = "detector",
 }: I18nInitOptions) {
   return {
     fallbackLng,
@@ -53,7 +68,8 @@ export function i18nInitOptions({
       order: queryKey
         ? ["querystring", "localStorage", "navigator"]
         : ["localStorage", "navigator"],
-      caches: ["localStorage"],
+      // Read from always, written to only by whoever owns it — see `storageWriter`.
+      caches: storageWriter === "detector" ? ["localStorage"] : [],
       ...(queryKey ? { lookupQuerystring: queryKey } : {}),
       lookupLocalStorage: storageKey,
     },