mazey 5.3.1 → 5.4.1

package/lib/index.d.ts

@@ -127,6 +127,18 @@ interface BrowserInfo {
   colorScheme: string;
 }
 
+/**
+ * A resolved preference value and its human-readable label.
+ *
+ * @category Browser Information
+ */
+interface PreferenceResult<T extends string = string> {
+  /** Machine-readable value used by application logic. */
+  value: T;
+  /** Human-readable label suitable for display. */
+  label: string;
+}
+
 interface DefineListeners {
   [key: string]: any;
 }
@@ -3396,151 +3408,185 @@ type ThemePreference = "system" | "light" | "dark";
  */
 type ResolvedTheme = "light" | "dark";
 /**
- * Human-readable names for supported theme preferences.
+ * Resolve the current website theme.
  *
- * @category Browser Information
- */
-type ThemePreferenceDisplayName = "System" | "Light" | "Dark";
-/**
- * The highest-priority source that selected a theme preference.
+ * Resolution checks the fixed `theme` URL query, the supplied local-storage
+ * key, the current `prefers-color-scheme` media query, and finally the fixed
+ * `light` fallback. Query values accept only `light` and `dark`. Storage also
+ * accepts `system`, which resolves to a concrete value while retaining the
+ * `System` label. A valid query preference is written under the supplied
+ * storage key when browser storage is available; resolution still succeeds
+ * when the write fails.
  *
- * @category Browser Information
- */
-type ThemePreferenceSource = "query" | "storage" | "system" | "fallback";
-/**
- * Options for {@link resolveThemePreference}.
+ * Resolution matrix:
  *
- * @category Browser Information
- */
-interface ResolveThemePreferenceOptions {
-    /** Project-specific local-storage key, such as `MAZEY_THEME`. */
-    storageKey: string;
-    /** URL query parameter name. Defaults to `theme`. */
-    queryParam?: string;
-    /** URL inspected for a query override. Defaults to `window.location.href` when available. */
-    url?: string | URL;
-    /** Storage used to read a persisted preference. Defaults to `window.localStorage` when available. */
-    storage?: Pick<Storage, "getItem"> | null;
-    /** Media-query implementation. Defaults to `window.matchMedia` when available. */
-    matchMedia?: (query: string) => Pick<MediaQueryList, "matches">;
-    /** Theme used when the system preference is unavailable. Defaults to `light`. */
-    fallback?: ResolvedTheme;
-}
-/**
- * Options for {@link setThemePreference}.
+ * | Query   | Storage  | System dark | Result                                |
+ * | ------- | -------- | ----------: | ------------------------------------- |
+ * | `dark`  | `light`  |       false | `{ value: "dark", label: "Dark" }`    |
+ * | `light` | `dark`   |        true | `{ value: "light", label: "Light" }`  |
+ * | invalid | `dark`   |       false | `{ value: "dark", label: "Dark" }`    |
+ * | missing | `light`  |        true | `{ value: "light", label: "Light" }`  |
+ * | missing | `system` |        true | `{ value: "dark", label: "System" }`  |
+ * | missing | `system` |       false | `{ value: "light", label: "System" }` |
+ * | missing | invalid  |        true | `{ value: "dark", label: "System" }`  |
+ * | missing | missing  |       false | `{ value: "light", label: "System" }` |
+ * | missing | missing  | unavailable | `{ value: "light", label: "Light" }`  |
+ *
+ * Usage:
  *
+ * ```ts
+ * import {
+ *   resolveThemePreference,
+ *   setThemePreference,
+ * } from "mazey";
+ *
+ * const theme = resolveThemePreference(
+ *   "MY_WEBSITE_THEME"
+ * );
+ *
+ * console.log(theme);
+ *
+ * setThemePreference(
+ *   "MY_WEBSITE_THEME",
+ *   "system"
+ * );
+ * ```
+ *
+ * Possible output:
+ *
+ * ```text
+ * {
+ *   value: "dark",
+ *   label: "System"
+ * }
+ * ```
+ *
+ * @param storageKey Project-specific local-storage key.
+ * @returns The concrete `light` or `dark` value and the label of the preference that selected it.
+ * @throws {TypeError} If `storageKey` is not a non-empty string.
+ * @remarks Safe during SSR and resilient to unavailable or throwing browser APIs. A valid URL preference is written to storage when possible; other resolution paths remain read-only. The function never mutates the DOM or adds listeners.
  * @category Browser Information
  */
-interface SetThemePreferenceOptions {
-    /** Project-specific local-storage key, such as `MAZEY_THEME`. */
-    storageKey: string;
-    /** Supported preference to persist. */
-    preference: ThemePreference;
-    /** Storage used to persist the preference. Defaults to `window.localStorage` when available. */
-    storage?: Pick<Storage, "setItem"> | null;
-}
+declare function resolveThemePreference(storageKey: string): PreferenceResult<ResolvedTheme>;
 /**
- * Result returned by {@link resolveThemePreference}.
+ * Persist a website theme preference.
+ *
+ * The exact lowercase value `system`, `light`, or `dark` is written under the
+ * project-specific key. The function does not resolve or apply the theme.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { setThemePreference } from "mazey";
+ *
+ * const stored = setThemePreference(
+ *   "MY_WEBSITE_THEME",
+ *   "dark"
+ * );
+ *
+ * console.log(stored);
+ * ```
+ *
+ * Output when browser storage is available:
+ *
+ * ```text
+ * true
+ * ```
  *
+ * @param storageKey Project-specific local-storage key.
+ * @param value Theme preference to persist.
+ * @returns `true` when storage succeeds, or `false` when storage is unavailable or rejects the write.
+ * @throws {TypeError} If `storageKey` is empty or `value` is not `system`, `light`, or `dark`.
+ * @remarks Safe during SSR. This function writes only the preference and never mutates the DOM, applies a theme, or adds listeners.
  * @category Browser Information
  */
-interface ThemePreferenceResult {
-    /** Selected user-facing preference. */
-    preference: ThemePreference;
-    /** Effective light or dark theme. */
-    resolvedTheme: ResolvedTheme;
-    /** Human-readable name of the selected preference. */
-    displayName: ThemePreferenceDisplayName;
-    /** Highest-priority source that supplied the selected preference. */
-    source: ThemePreferenceSource;
-}
+declare function setThemePreference(storageKey: string, value: ThemePreference): boolean;
+
 /**
- * Resolve a website theme preference without mutating the DOM or storage.
+ * Resolve the current website language.
  *
- * Resolution uses four priority levels: a `light` or `dark` URL query
- * override, a stored `system`/`light`/`dark` preference, the current system
- * color scheme, and finally a configured `light` or `dark` fallback. The
- * default query parameter is `theme`, and the storage key must be supplied by
- * the consuming project. Query `system` and all unsupported values are ignored.
+ * Resolution checks the fixed `lang` URL query, the supplied local-storage
+ * key, `navigator.language`, and finally the fixed `en` fallback. Each value
+ * is trimmed, treats `_` as `-`, and is canonicalized as a language tag.
+ * `navigator.languages` is intentionally ignored.
  *
- * The result separates the selected preference from the effective theme and
- * includes its display name (`System`, `Light`, or `Dark`) and source. A stored
- * `system` preference retains `source: "storage"` while its effective theme is
- * resolved from the current media query or fallback.
+ * The label is generated at runtime with `Intl.DisplayNames` in the resolved
+ * language when available. Runtime wording may vary; the canonical language
+ * value is used as the label when display-name generation is unavailable.
  *
  * Usage:
  *
- * ```javascript
- * import { resolveThemePreference } from "mazey";
+ * ```ts
+ * import {
+ *   resolveLanguagePreference,
+ *   setLanguagePreference,
+ * } from "mazey";
  *
- * const theme = resolveThemePreference({
- *   storageKey: "MY_WEBSITE_THEME",
- * });
- * console.log(theme.preference);
- * console.log(theme.resolvedTheme);
- * console.log(theme.displayName);
- * console.log(theme.source);
- * ```
+ * const language =
+ *   resolveLanguagePreference(
+ *     "MY_WEBSITE_LANGUAGE"
+ *   );
  *
- * Possible output:
+ * console.log(language);
  *
- * ```text
- * system
- * dark
- * System
- * system
+ * setLanguagePreference(
+ *   "MY_WEBSITE_LANGUAGE",
+ *   "ja-JP"
+ * );
  * ```
  *
- * URL override:
+ * Possible output:
  *
- * ```javascript
- * const theme = resolveThemePreference({
- *   storageKey: "MY_WEBSITE_THEME",
- *   url: "https://example.com/?theme=light",
- * });
+ * ```text
+ * {
+ *   value: "ja-JP",
+ *   label: "日本語（日本）"
+ * }
  * ```
  *
- * @param options Project storage key and optional URL, storage, media-query, and fallback inputs.
- * @returns The selected preference, effective theme, display name, and preference source.
- * @throws {TypeError} If required options or explicitly supplied option values are invalid.
- * @remarks Safe during SSR and resilient to unavailable or throwing browser APIs. This function does not write storage, mutate the DOM, or add listeners. System resolution reads the current media-query result rather than cached browser information.
+ * @param storageKey Project-specific local-storage key.
+ * @returns The canonical current language and a runtime-generated display label.
+ * @throws {TypeError} If `storageKey` is not a non-empty string.
+ * @remarks Safe during SSR and resilient to unavailable or throwing browser and `Intl` APIs. This function reads preferences only and never writes storage, mutates the DOM, loads translations, redirects, or adds listeners.
  * @category Browser Information
  */
-declare function resolveThemePreference(options: ResolveThemePreferenceOptions): ThemePreferenceResult;
+declare function resolveLanguagePreference(storageKey: string): PreferenceResult<string>;
 /**
- * Persist a supported website theme preference.
- *
- * The preference is written as the exact lowercase value `system`, `light`,
- * or `dark` under a project-specific storage key. The function returns
- * `false` instead of throwing when storage is unavailable, including during
- * SSR and in privacy-restricted browser environments. It does not resolve or
- * apply the theme and does not mutate the DOM.
+ * Canonicalize and persist a website language.
  *
  * Usage:
  *
- * ```javascript
- * import { setThemePreference } from "mazey";
+ * ```ts
+ * import { setLanguagePreference } from "mazey";
+ *
+ * const stored = setLanguagePreference(
+ *   "MY_WEBSITE_LANGUAGE",
+ *   "ZH_cn"
+ * );
  *
- * const stored = setThemePreference({
- *   storageKey: "MY_WEBSITE_THEME",
- *   preference: "dark",
- * });
  * console.log(stored);
  * ```
  *
- * Output:
+ * Output when browser storage is available:
  *
  * ```text
  * true
  * ```
  *
- * @param options Project storage key, supported preference, and optional storage implementation.
- * @returns `true` when the preference was written, or `false` when storage is unavailable or rejects the write.
- * @throws {TypeError} If the options, storage key, preference, or explicitly supplied storage implementation is invalid.
- * @remarks This function writes only the selected preference. Applying a resolved theme and updating controls remain the consuming project's responsibility.
+ * The stored value is canonicalized to:
+ *
+ * ```text
+ * zh-CN
+ * ```
+ *
+ * @param storageKey Project-specific local-storage key.
+ * @param language Language tag to canonicalize and persist.
+ * @returns `true` when storage succeeds, or `false` when storage is unavailable or rejects the write.
+ * @throws {TypeError} If `storageKey` is empty or `language` is empty or malformed.
+ * @remarks Safe during SSR. This function writes only the canonical language and never mutates the DOM, applies translations, redirects, or adds listeners.
  * @category Browser Information
  */
-declare function setThemePreference(options: SetThemePreferenceOptions): boolean;
+declare function setLanguagePreference(storageKey: string, language: string): boolean;
 
 /**
  * Create a configurable wrapper around the global `console`.
@@ -3612,5 +3658,5 @@ declare const mazeyCon: Console;
  */
 declare const timeCon: Console;
 
-export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, extractElementText, fireEvent, floatFixed, floatToPercent, formatDate, formatDistanceToNow, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, parseJsonSafe, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLocalStorage, setSessionStorage, setThemePreference, sha256Hex, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
-export type { GitHubRepositoryDetails, IsSafePWAEnvOptions, ResolveThemePreferenceOptions, ResolvedTheme, SetThemePreferenceOptions, ThemePreference, ThemePreferenceDisplayName, ThemePreferenceResult, ThemePreferenceSource };
+export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, extractElementText, fireEvent, floatFixed, floatToPercent, formatDate, formatDistanceToNow, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, parseJsonSafe, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveLanguagePreference, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLanguagePreference, setLocalStorage, setSessionStorage, setThemePreference, sha256Hex, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
+export type { GitHubRepositoryDetails, IsSafePWAEnvOptions, PreferenceResult, ResolvedTheme, ThemePreference };