@sheet-i18n/react-client 1.4.0 → 1.5.0-canary.0

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { MessageDescriptor, IntlShape } from 'react-intl';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { I18nStore } from '@sheet-i18n/react-core';
+import { ObserverManager } from '@sheet-i18n/shared-utils';
 
 type UseIntlParams<D = MessageDescriptor> = Parameters<IntlShape['$t']> extends [D, ...infer R] ? [...R, Omit<D, 'id'>] : never;
 type ExtendedUseIntlParams<D = MessageDescriptor> = UseIntlParams<D> extends [infer A, infer B, ...infer Rest] ? A extends Record<string, infer V> ? [Record<string, V | React.ReactNode>, B, ...Rest] : [A, B, ...Rest] : UseIntlParams<D>;
@@ -39,6 +40,33 @@ type IntlProviderProps<TSupportedLocales extends readonly string[], TLocaleSet e
     children: React.ReactNode;
 };
 
+interface IStorageService<V extends string> {
+    getItem(key: string): V;
+    setItem(key: string, value: V): boolean;
+    removeItem(key: string): boolean;
+    clear(): boolean;
+}
+/**
+ * locale storage manager
+ * implements ILocaleStorageManager (injected StorageService)
+ */
+interface ILocaleStorageManager<TSupportedLocales extends readonly string[]> {
+    getLocale(): TSupportedLocales[number];
+    setLocale(locale: TSupportedLocales[number]): void;
+}
+declare class LocaleStorageManager<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false> implements ILocaleStorageManager<TSupportedLocales> {
+    private readonly storageService;
+    private readonly i18nStore;
+    private readonly localeStorageKey;
+    observerManager: ObserverManager<TSupportedLocales[number]>;
+    constructor(storageService: IStorageService<TSupportedLocales[number]>, i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>, localeStorageKey?: string);
+    private initializeCurrentLocale;
+    getLocale: () => TSupportedLocales[number];
+    setLocale: (locale: TSupportedLocales[number]) => void;
+}
+
+declare function useLocaleStorage<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(localeStorageManager: LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>): TSupportedLocales[number];
+
 declare function createI18nContext<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>): {
     IntlProvider: ({ currentLocale, children, }: Omit<IntlProviderProps<TSupportedLocales, TLocaleSet>, "currentLocale" | "i18nStore"> & {
         currentLocale?: string;
@@ -46,6 +74,8 @@ declare function createI18nContext<TSupportedLocales extends readonly string[],
     }) => react_jsx_runtime.JSX.Element;
     useTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => UseTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
     getTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => GetTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
+    getLocaleStorageManager: (storage?: IStorageService<string>) => LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    useLocaleStorage: typeof useLocaleStorage;
 };
 
 export { createI18nContext };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { MessageDescriptor, IntlShape } from 'react-intl';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { I18nStore } from '@sheet-i18n/react-core';
+import { ObserverManager } from '@sheet-i18n/shared-utils';
 
 type UseIntlParams<D = MessageDescriptor> = Parameters<IntlShape['$t']> extends [D, ...infer R] ? [...R, Omit<D, 'id'>] : never;
 type ExtendedUseIntlParams<D = MessageDescriptor> = UseIntlParams<D> extends [infer A, infer B, ...infer Rest] ? A extends Record<string, infer V> ? [Record<string, V | React.ReactNode>, B, ...Rest] : [A, B, ...Rest] : UseIntlParams<D>;
@@ -39,6 +40,33 @@ type IntlProviderProps<TSupportedLocales extends readonly string[], TLocaleSet e
     children: React.ReactNode;
 };
 
+interface IStorageService<V extends string> {
+    getItem(key: string): V;
+    setItem(key: string, value: V): boolean;
+    removeItem(key: string): boolean;
+    clear(): boolean;
+}
+/**
+ * locale storage manager
+ * implements ILocaleStorageManager (injected StorageService)
+ */
+interface ILocaleStorageManager<TSupportedLocales extends readonly string[]> {
+    getLocale(): TSupportedLocales[number];
+    setLocale(locale: TSupportedLocales[number]): void;
+}
+declare class LocaleStorageManager<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false> implements ILocaleStorageManager<TSupportedLocales> {
+    private readonly storageService;
+    private readonly i18nStore;
+    private readonly localeStorageKey;
+    observerManager: ObserverManager<TSupportedLocales[number]>;
+    constructor(storageService: IStorageService<TSupportedLocales[number]>, i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>, localeStorageKey?: string);
+    private initializeCurrentLocale;
+    getLocale: () => TSupportedLocales[number];
+    setLocale: (locale: TSupportedLocales[number]) => void;
+}
+
+declare function useLocaleStorage<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(localeStorageManager: LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>): TSupportedLocales[number];
+
 declare function createI18nContext<TSupportedLocales extends readonly string[], TLocaleSet extends Partial<Record<TSupportedLocales[number], Record<string, any>>>, TTypeSafe extends boolean = false>(i18nStore: I18nStore<TSupportedLocales, TLocaleSet, TTypeSafe>): {
     IntlProvider: ({ currentLocale, children, }: Omit<IntlProviderProps<TSupportedLocales, TLocaleSet>, "currentLocale" | "i18nStore"> & {
         currentLocale?: string;
@@ -46,6 +74,8 @@ declare function createI18nContext<TSupportedLocales extends readonly string[],
     }) => react_jsx_runtime.JSX.Element;
     useTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => UseTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
     getTranslation: <TSheetTitle extends TTypeSafe extends true ? keyof TLocaleSet[TSupportedLocales[number]] extends never ? string : keyof TLocaleSet[TSupportedLocales[number]] : string>(sheetTitle: TSheetTitle) => GetTranslationReturn<TSupportedLocales, TLocaleSet, TTypeSafe, TSheetTitle>;
+    getLocaleStorageManager: (storage?: IStorageService<string>) => LocaleStorageManager<TSupportedLocales, TLocaleSet, TTypeSafe>;
+    useLocaleStorage: typeof useLocaleStorage;
 };
 
 export { createI18nContext };

package/dist/index.js

@@ -43,7 +43,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/createI18nContext.tsx
-var import_shared_utils4 = require("@sheet-i18n/shared-utils");
+var import_shared_utils5 = require("@sheet-i18n/shared-utils");
 var import_react_core = require("@sheet-i18n/react-core");
 
 // src/IntlProvider.tsx
@@ -183,8 +183,7 @@ function useIntlLocale({
   i18nStore,
   currentLocale
 }) {
-  var _a;
-  const locale = (_a = currentLocale != null ? currentLocale : detectClientLanguage(i18nStore)) != null ? _a : i18nStore.defaultLocale;
+  const locale = currentLocale || detectClientLanguage(i18nStore) || i18nStore.defaultLocale;
   i18nStore.setCurrentLocale(locale);
   (0, import_react2.useEffect)(() => {
     i18nStore.setCurrentLocale(locale);
@@ -319,10 +318,157 @@ function getTranslation({
   return { t };
 }
 
+// src/Service/LocalStorageService.ts
+var import_shared_utils4 = require("@sheet-i18n/shared-utils");
+var LocalStorageService = class {
+  constructor(storage) {
+    this.storage = null;
+    this.isClientSide = typeof window !== "undefined";
+    if (storage) {
+      this.storage = this.validateStorage(storage);
+    } else if (this.isClientSide) {
+      this.storage = this.initializeWindowLocalStorage();
+    }
+  }
+  validateStorage(storage) {
+    const requiredMethods = [
+      "getItem",
+      "setItem",
+      "removeItem",
+      "clear"
+    ];
+    try {
+      for (const method of requiredMethods) {
+        if (typeof storage[method] !== "function") {
+          throw new Error(
+            `Invalid storage object: missing required method '${method}'`
+          );
+        }
+      }
+      return storage;
+    } catch (error) {
+      console.error(error);
+      return null;
+    }
+  }
+  initializeWindowLocalStorage() {
+    try {
+      const testKey = "__storage_test__";
+      localStorage.setItem(testKey, "test");
+      localStorage.removeItem(testKey);
+      return localStorage;
+    } catch (error) {
+      console.warn("Window LocalStorage is not available:", error);
+      return null;
+    }
+  }
+  getItem(key) {
+    if (!this.storage || !key) {
+      return "";
+    }
+    try {
+      return this.storage.getItem(key);
+    } catch (error) {
+      console.error(`Failed to get item with key "${key}":`, error);
+      return "";
+    }
+  }
+  setItem(key, value) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.setItem(key, value);
+      return true;
+    } catch (error) {
+      console.error(`Failed to set item with key "${key}":`, error);
+      return false;
+    }
+  }
+  removeItem(key) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.removeItem(key);
+      return true;
+    } catch (error) {
+      console.error(`Failed to remove item with key "${key}":`, error);
+      return false;
+    }
+  }
+  clear() {
+    if (!this.storage) {
+      return false;
+    }
+    try {
+      this.storage.clear();
+      return true;
+    } catch (error) {
+      console.error("Failed to clear storage:", error);
+      return false;
+    }
+  }
+};
+var LocaleStorageManager = class {
+  constructor(storageService, i18nStore, localeStorageKey = "sheet-i18n-locale") {
+    this.storageService = storageService;
+    this.i18nStore = i18nStore;
+    this.localeStorageKey = localeStorageKey;
+    this.observerManager = new import_shared_utils4.ObserverManager();
+    this.initializeCurrentLocale = () => {
+      var _a, _b;
+      if (this.storageService && this.i18nStore.currentLocale) {
+        this.storageService.setItem(
+          this.localeStorageKey,
+          this.i18nStore.currentLocale
+        );
+      }
+      (_b = (_a = this.i18nStore) == null ? void 0 : _a.observerManager) == null ? void 0 : _b.addListener({
+        listenerId: this.localeStorageKey,
+        listener: (newLocale) => {
+          this.storageService.setItem(this.localeStorageKey, newLocale);
+        }
+      });
+    };
+    this.getLocale = () => {
+      const stored = this.storageService.getItem(this.localeStorageKey);
+      return stored != null ? stored : "";
+    };
+    this.setLocale = (locale) => {
+      this.storageService.setItem(this.localeStorageKey, locale);
+      this.observerManager.notify(locale);
+    };
+    this.initializeCurrentLocale();
+  }
+};
+
+// src/useLocaleStorage.ts
+var import_react3 = require("react");
+var LISTENER_ID = "LOCALE_STORAGE_LISTENER_ID";
+function useLocaleStorage(localeStorageManager) {
+  var _a;
+  const [locale, setLocale] = (0, import_react3.useState)((_a = localeStorageManager == null ? void 0 : localeStorageManager.getLocale) == null ? void 0 : _a.call(localeStorageManager));
+  (0, import_react3.useEffect)(() => {
+    var _a2;
+    (_a2 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a2.addListener({
+      listenerId: LISTENER_ID,
+      listener: (newLocale) => {
+        setLocale(newLocale);
+      }
+    });
+    return () => {
+      var _a3;
+      (_a3 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a3.removeListener(LISTENER_ID);
+    };
+  }, []);
+  return locale;
+}
+
 // src/createI18nContext.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 function createI18nContext(i18nStore) {
-  if (import_shared_utils4.validator.isNullish(i18nStore)) {
+  if (import_shared_utils5.validator.isNullish(i18nStore)) {
     throw new InvalidI18nContextStateError(
       "\u26A0\uFE0F no i18nStore provided. To use createI18nContext, you must provide an i18nStore as a parameter"
     );
@@ -345,10 +491,20 @@ function createI18nContext(i18nStore) {
   );
   const useTranslationImpl = (sheetTitle) => useTranslation({ sheetTitle, i18nStore });
   const getTranslationImpl = (sheetTitle) => getTranslation({ sheetTitle, i18nStore });
+  const getLocaleStorageManager = (storage) => {
+    const localStorageService = new LocalStorageService(storage);
+    const localeStorageManager = new LocaleStorageManager(
+      localStorageService,
+      i18nStore
+    );
+    return localeStorageManager;
+  };
   return {
     IntlProvider: IntlProviderImpl,
     useTranslation: useTranslationImpl,
-    getTranslation: getTranslationImpl
+    getTranslation: getTranslationImpl,
+    getLocaleStorageManager,
+    useLocaleStorage
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -160,8 +160,7 @@ function useIntlLocale({
   i18nStore,
   currentLocale
 }) {
-  var _a;
-  const locale = (_a = currentLocale != null ? currentLocale : detectClientLanguage(i18nStore)) != null ? _a : i18nStore.defaultLocale;
+  const locale = currentLocale || detectClientLanguage(i18nStore) || i18nStore.defaultLocale;
   i18nStore.setCurrentLocale(locale);
   useEffect(() => {
     i18nStore.setCurrentLocale(locale);
@@ -296,6 +295,153 @@ function getTranslation({
   return { t };
 }
 
+// src/Service/LocalStorageService.ts
+import { ObserverManager } from "@sheet-i18n/shared-utils";
+var LocalStorageService = class {
+  constructor(storage) {
+    this.storage = null;
+    this.isClientSide = typeof window !== "undefined";
+    if (storage) {
+      this.storage = this.validateStorage(storage);
+    } else if (this.isClientSide) {
+      this.storage = this.initializeWindowLocalStorage();
+    }
+  }
+  validateStorage(storage) {
+    const requiredMethods = [
+      "getItem",
+      "setItem",
+      "removeItem",
+      "clear"
+    ];
+    try {
+      for (const method of requiredMethods) {
+        if (typeof storage[method] !== "function") {
+          throw new Error(
+            `Invalid storage object: missing required method '${method}'`
+          );
+        }
+      }
+      return storage;
+    } catch (error) {
+      console.error(error);
+      return null;
+    }
+  }
+  initializeWindowLocalStorage() {
+    try {
+      const testKey = "__storage_test__";
+      localStorage.setItem(testKey, "test");
+      localStorage.removeItem(testKey);
+      return localStorage;
+    } catch (error) {
+      console.warn("Window LocalStorage is not available:", error);
+      return null;
+    }
+  }
+  getItem(key) {
+    if (!this.storage || !key) {
+      return "";
+    }
+    try {
+      return this.storage.getItem(key);
+    } catch (error) {
+      console.error(`Failed to get item with key "${key}":`, error);
+      return "";
+    }
+  }
+  setItem(key, value) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.setItem(key, value);
+      return true;
+    } catch (error) {
+      console.error(`Failed to set item with key "${key}":`, error);
+      return false;
+    }
+  }
+  removeItem(key) {
+    if (!this.storage || !key) {
+      return false;
+    }
+    try {
+      this.storage.removeItem(key);
+      return true;
+    } catch (error) {
+      console.error(`Failed to remove item with key "${key}":`, error);
+      return false;
+    }
+  }
+  clear() {
+    if (!this.storage) {
+      return false;
+    }
+    try {
+      this.storage.clear();
+      return true;
+    } catch (error) {
+      console.error("Failed to clear storage:", error);
+      return false;
+    }
+  }
+};
+var LocaleStorageManager = class {
+  constructor(storageService, i18nStore, localeStorageKey = "sheet-i18n-locale") {
+    this.storageService = storageService;
+    this.i18nStore = i18nStore;
+    this.localeStorageKey = localeStorageKey;
+    this.observerManager = new ObserverManager();
+    this.initializeCurrentLocale = () => {
+      var _a, _b;
+      if (this.storageService && this.i18nStore.currentLocale) {
+        this.storageService.setItem(
+          this.localeStorageKey,
+          this.i18nStore.currentLocale
+        );
+      }
+      (_b = (_a = this.i18nStore) == null ? void 0 : _a.observerManager) == null ? void 0 : _b.addListener({
+        listenerId: this.localeStorageKey,
+        listener: (newLocale) => {
+          this.storageService.setItem(this.localeStorageKey, newLocale);
+        }
+      });
+    };
+    this.getLocale = () => {
+      const stored = this.storageService.getItem(this.localeStorageKey);
+      return stored != null ? stored : "";
+    };
+    this.setLocale = (locale) => {
+      this.storageService.setItem(this.localeStorageKey, locale);
+      this.observerManager.notify(locale);
+    };
+    this.initializeCurrentLocale();
+  }
+};
+
+// src/useLocaleStorage.ts
+import { useEffect as useEffect2, useState as useState2 } from "react";
+var LISTENER_ID = "LOCALE_STORAGE_LISTENER_ID";
+function useLocaleStorage(localeStorageManager) {
+  var _a;
+  const [locale, setLocale] = useState2((_a = localeStorageManager == null ? void 0 : localeStorageManager.getLocale) == null ? void 0 : _a.call(localeStorageManager));
+  useEffect2(() => {
+    var _a2;
+    (_a2 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a2.addListener({
+      listenerId: LISTENER_ID,
+      listener: (newLocale) => {
+        setLocale(newLocale);
+      }
+    });
+    return () => {
+      var _a3;
+      (_a3 = localeStorageManager == null ? void 0 : localeStorageManager.observerManager) == null ? void 0 : _a3.removeListener(LISTENER_ID);
+    };
+  }, []);
+  return locale;
+}
+
 // src/createI18nContext.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
 function createI18nContext(i18nStore) {
@@ -322,10 +468,20 @@ function createI18nContext(i18nStore) {
   );
   const useTranslationImpl = (sheetTitle) => useTranslation({ sheetTitle, i18nStore });
   const getTranslationImpl = (sheetTitle) => getTranslation({ sheetTitle, i18nStore });
+  const getLocaleStorageManager = (storage) => {
+    const localStorageService = new LocalStorageService(storage);
+    const localeStorageManager = new LocaleStorageManager(
+      localStorageService,
+      i18nStore
+    );
+    return localeStorageManager;
+  };
   return {
     IntlProvider: IntlProviderImpl,
     useTranslation: useTranslationImpl,
-    getTranslation: getTranslationImpl
+    getTranslation: getTranslationImpl,
+    getLocaleStorageManager,
+    useLocaleStorage
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet-i18n/react-client",
-  "version": "1.4.0",
+  "version": "1.5.0-canary.0",
   "description": "a client package for react modules used by sheet-i18n",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -25,20 +25,20 @@
   },
   "license": "ISC",
   "dependencies": {
-    "@sheet-i18n/react-core": "1.4.0",
-    "@sheet-i18n/errors": "1.7.0",
-    "@sheet-i18n/shared-utils": "1.7.0"
+    "@sheet-i18n/shared-utils": "1.8.0-canary.0",
+    "@sheet-i18n/errors": "1.8.0-canary.0",
+    "@sheet-i18n/react-core": "1.5.0-canary.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.2",
     "react": "^18.2.0",
     "react-intl": "^7.0.4",
-    "@sheet-i18n/typescript-config": "1.7.0"
+    "@sheet-i18n/typescript-config": "1.8.0-canary.0"
   },
   "peerDependencies": {
-    "react": "^18 || ^19",
-    "react-dom": "^18 || ^19",
+    "react": "^18 || ^19 || ^20 || ^21",
+    "react-dom": "^18 || ^19 || ^20 || ^21",
     "react-intl": "^7.0.4"
   },
   "scripts": {