pref: Add more convenience functions (#11)

* bump deps and update pref package

* fix dep

* fix dep again

* fixup deps

deno.jsonc

@@ -1,6 +1,6 @@
 {
     "name": "@pistonite/pure",
-    "version": "0.0.10",
+    "version": "0.0.11",
     "exports": {
         "./fs": "./fs/index.ts",
         "./log": "./log/index.ts",

package.json

@@ -1,13 +1,13 @@
 {
     "dependencies": {
-        "denque": "^2.1.0",
-        "file-saver": "^2.0.5"
+        "denque": "2.1.0",
+        "file-saver": "2.0.5"
     },
     "devDependencies": {
         "@types/file-saver": "^2.0.7",
-        "jsr": "^0.12.4",
+        "jsr": "^0.13.2",
         "prettier": "^3.3.3",
-        "typescript": "^5.5.4"
+        "typescript": "^5.7.2"
     },
     "prettier": {
         "tabWidth": 4,

pref/dark.ts

@@ -120,6 +120,20 @@ export const initDark = (options: DarkOptions = {}): void => {
     }
 };
 
+/**
+ * Clears the persisted dark mode preference
+ *
+ * If you are doing this, you should probably call `setDark`
+ * with `prefersDarkMode()` or some initial value immediately before this,
+ * so the current dark mode is set to user's preferred mode.
+ *
+ * Note if `persist` is `true` when initializing,
+ * subsequence `setDark` calls will still persist the value.
+ */
+export const clearPersistedDarkPerference = (): void => {
+    localStorage.removeItem(KEY);
+};
+
 /**
  * Gets the current value of dark mode
  */

pref/locale.ts

@@ -10,7 +10,7 @@
  *
  * initLocale({
  *     // required
- *     supported: ["en", "zh-CN", "zh-TW"],
+ *     supported: ["en", "zh-CN", "zh-TW"] as const,
  *     default: "en",
  *
  *     // optional
@@ -56,8 +56,9 @@
 
 const KEY = "Pure.Locale";
 
-let supportedLocales: string[] = [];
+let supportedLocales: readonly string[] = [];
 let locale: string = "";
+let defaultLocale: string = "";
 const subscribers: ((locale: string) => void)[] = [];
 
 /**
@@ -82,15 +83,17 @@ export type LocaleOptions<TLocale extends string> = {
      * List of supported locale or languages.
      * These can be full locale strings like "en-US" or just languages like "en"
      */
-    supported: TLocale[];
+    supported: readonly TLocale[];
     /**
-     * The default locale if the user's preferred locale is not supported
+     * The default locale if the user's preferred locale is not supported.
+     * This must be one of the items in `supported`.
      */
     default: TLocale;
     /**
      * Initial value for locale
      *
-     * If not set, it will default to calling `getPreferredLocale()`.
+     * If not set, it will default to calling `getPreferredLocale()`,
+     * which is based on the browser's language settings.
      *
      * If `persist` is `true`, it will also check the value from localStorage
      *
@@ -116,6 +119,7 @@ export const initLocale = <TLocale extends string>(
         _locale =
             convertToSupportedLocale(getPreferredLocale()) || options.default;
     }
+    defaultLocale = options.default;
     if (options.persist) {
         const value = localStorage.getItem(KEY);
         if (value !== null) {
@@ -134,11 +138,31 @@ export const initLocale = <TLocale extends string>(
     setLocale(_locale);
 };
 
+/**
+ * Clear the locale preference previously presisted to localStorage
+ *
+ * If you are doing this, you should probably call `setLocale`
+ * or `i18next.changeLanguage` (depending on your setup) immediately
+ * before this with `convertToSupportedLocaleOrDefault(getPreferredLocale())`
+ * so the current locale is set to user's preferred locale.
+ *
+ * Note if `persist` is `true` when initializing,
+ * subsequence `setLocale` calls will still persist the value.
+ */
+export const clearPersistedLocalePreference = (): void => {
+    localStorage.removeItem(KEY);
+};
+
 /** Get the current selected locale */
 export const getLocale = (): string => {
     return locale;
 };
 
+/** Get the default locale when initialized */
+export const getDefaultLocale = (): string => {
+    return defaultLocale;
+};
+
 /**
  * Set the selected locale
  *
@@ -181,7 +205,6 @@ export const setLocale = (newLocale: string): boolean => {
  * console.log(convertToSupportedLocale("zh-TW")); // "zh"
  * console.log(convertToSupportedLocale("es"));    // undefined
  * ```
- *
  */
 export const convertToSupportedLocale = (
     newLocale: string,
@@ -199,6 +222,19 @@ export const convertToSupportedLocale = (
     return undefined;
 };
 
+/**
+ * Convert a locale/language to a supported locale/language,
+ * or return the default locale if not found.
+ *
+ * This is a thin wrapper for `convertToSupportedLocale`.
+ * See that function for more details.
+ */
+export const convertToSupportedLocaleOrDefault = (
+    newLocale: string,
+): string => {
+    return convertToSupportedLocale(newLocale) || defaultLocale;
+};
+
 /**
  * Add a subscriber to be notified when the locale changes
  *

react/deno.jsonc

@@ -1,14 +1,14 @@
 {
     "name": "@pistonite/pure-react",
-    "version": "0.0.2",
+    "version": "0.0.3",
     "exports": {
         ".": "./src/index.ts",
     },
     "publish": {
         "exclude": ["package-lock.json", "node_modules/**", "Taskfile.yml"],
     },
     "imports": {
-        "@pistonite/pure": "jsr:@pistonite/pure@^0.0.10",
+        "@pistonite/pure": "jsr:@pistonite/pure@^0.0.11",
     },
     "lint": {
         "rules": {

react/package.json

@@ -1,11 +1,11 @@
 {
     "peerDependencies": {
-        "@pistonite/pure": "npm:@jsr/pistonite__pure@^0.0.10",
+        "@pistonite/pure": "npm:@jsr/pistonite__pure@^0.0.11",
         "react": "^18"
     },
     "devDependencies": {
         "@types/react": "^18.3.12",
         "react": "^18",
-        "typescript": "^5.5.4"
+        "typescript": "^5.7.2"
     }
 }