@pistonite/pure 0.0.12

package/src/log/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Client side log util
+ *
+ * @module
+ */
+
+import Denque from "denque";
+import { errstr } from "../result/index.ts";
+
+const LIMIT = 500;
+
+/** Global log queue */
+const LogQueue = new Denque<string>();
+function pushLog(msg: string) {
+    if (LogQueue.length > LIMIT) {
+        LogQueue.shift();
+    }
+    LogQueue.push(`[${new Date().toISOString()}]${msg}`);
+}
+
+/** Get the current log */
+export function getLogLines(): string[] {
+    return LogQueue.toArray();
+}
+
+/** A general-purpose client side logger */
+export class Logger {
+    /** The prefix of the logger */
+    private prefix: string;
+
+    constructor(prefix: string) {
+        this.prefix = prefix;
+    }
+
+    /** Log an info message */
+    public info(msg: string) {
+        const msgWithPrefix = `[${this.prefix}] ${msg}`;
+        self.console.info(msgWithPrefix);
+        pushLog(msgWithPrefix);
+    }
+
+    /** Log a warning message */
+    public warn(msg: string) {
+        const msgWithPrefix = `[${this.prefix}] ${msg}`;
+        self.console.warn(msgWithPrefix);
+        pushLog(msgWithPrefix);
+    }
+
+    /** Log an error message */
+    public error(msg: unknown) {
+        const msgWithPrefix = `[${this.prefix}] ${errstr(msg)}`;
+        self.console.error(msgWithPrefix);
+        self.console.error(msg);
+        pushLog(msgWithPrefix);
+    }
+}

package/src/pref/dark.ts

@@ -0,0 +1,184 @@
+/**
+ * Dark mode wrappers
+ *
+ * ## Detect user preference
+ * User preference is detected with `matchMedia` API, if available.
+ * ```typescript
+ * import { prefersDarkMode } from "@pistonite/pure/dark";
+ *
+ * console.log(prefersDarkMode());
+ * ```
+ *
+ * ## Global dark mode state
+ * `initDark` initializes the dark mode state.
+ * ```typescript
+ * import { initDark, isDark, setDark, addDarkSubscriber } from "@pistonite/pure/dark";
+ *
+ * initDark();
+ * console.log(isDark());
+ *
+ * addDarkSubscriber((dark) => { console.log("Dark mode changed: ", dark); });
+ * setDark(true); // will trigger the subscriber
+ * ```
+ *
+ * ## Use with React
+ * A React hook is provided in the [`pure-react`](https://jsr.io/@pistonite/pure-react/doc/pref) package
+ * to get the dark mode state from React components.
+ *
+ * Use `setDark` to change the dark mode state from React compoenents like you would from anywhere else.
+ *
+ * ## Persisting to localStorage
+ * You can persist the dark mode preference to by passing `persist: true` to `initDark`.
+ * This will make `initDark` also load the preference from localStorage.
+ * ```typescript
+ * import { initDark } from "@pistonite/pure/dark";
+ *
+ * initDark({ persist: true });
+ * ```
+ *
+ * ## Setting `color-scheme` CSS property
+ * The `color-scheme` property handles dark mode for native components like buttons
+ * and scrollbars. By default, `initDark` will handle setting this property for the `:root` selector.
+ * You can override this by passing a `selector` option.
+ * ```typescript
+ * import { initDark } from "@pistonite/pure/dark";
+ *
+ * // will set `.my-app { color-scheme: dark }`
+ * initDark({ selector: ".my-app" });
+ * ```
+ *
+ * @module
+ */
+
+import { injectStyle } from "./injectStyle.ts";
+
+const KEY = "Pure.Dark";
+
+let dark = false;
+const subscribers: ((dark: boolean) => void)[] = [];
+
+/**
+ * Returns if dark mode is prefered in the browser environment
+ *
+ * If `window.matchMedia` is not available, it will return `false`
+ */
+export const prefersDarkMode = (): boolean => {
+    return !!globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches;
+};
+
+/** Value for the `color-scheme` CSS property */
+export type ColorScheme = "light" | "dark";
+/** Option for initializing dark mode */
+export type DarkOptions = {
+    /**
+     * Initial value for dark mode
+     *
+     * If not set, it will default to calling `prefersDarkMode()`.
+     *
+     * If `persist` is `true`, it will also check the value from localStorage
+     */
+    initial?: boolean;
+    /** Persist the dark mode preference to localStorage */
+    persist?: boolean;
+    /**
+     * The selector to set `color-scheme` property
+     *
+     * Defaults to `:root`. If set to empty string, CSS will not be updated
+     */
+    selector?: string;
+};
+
+/**
+ * Initializes dark mode
+ *
+ * @param options Options for initializing dark mode
+ */
+export const initDark = (options: DarkOptions = {}): void => {
+    let _dark = options.initial || prefersDarkMode();
+
+    if (options.persist) {
+        const value = localStorage.getItem(KEY);
+        if (value !== null) {
+            _dark = !!value;
+        }
+        addDarkSubscriber((dark: boolean) => {
+            localStorage.setItem(KEY, dark ? "1" : "");
+        });
+    } else {
+        localStorage.removeItem(KEY);
+    }
+
+    setDark(_dark);
+
+    const selector = options.selector ?? ":root";
+    if (selector) {
+        // notify immediately to update the style initially
+        addDarkSubscriber((dark: boolean) => {
+            updateStyle(dark, selector);
+        }, true /* notify */);
+    }
+};
+
+/**
+ * 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
+ */
+export const isDark = (): boolean => dark;
+
+/**
+ * Set the value of dark mode
+ */
+export const setDark = (value: boolean): void => {
+    if (dark === value) {
+        return;
+    }
+    dark = value;
+    const len = subscribers.length;
+    for (let i = 0; i < len; i++) {
+        subscribers[i](dark);
+    }
+};
+/**
+ * Add a subscriber to dark mode changes
+ *
+ * If `notifyImmediately` is `true`, the subscriber will be called immediately with the current value
+ */
+export const addDarkSubscriber = (
+    subscriber: (dark: boolean) => void,
+    notifyImmediately?: boolean,
+): void => {
+    subscribers.push(subscriber);
+    if (notifyImmediately) {
+        subscriber(dark);
+    }
+};
+
+/**
+ * Remove a subscriber from dark mode changes
+ */
+export const removeDarkSubscriber = (
+    subscriber: (dark: boolean) => void,
+): void => {
+    const index = subscribers.indexOf(subscriber);
+    if (index >= 0) {
+        subscribers.splice(index, 1);
+    }
+};
+
+const updateStyle = (dark: boolean, selector: string) => {
+    const text = `${selector} { color-scheme: ${dark ? "dark" : "light"}; }`;
+    injectStyle(KEY, text);
+};

package/src/pref/index.ts

@@ -0,0 +1,12 @@
+/**
+ * # pure/pref
+ * Preference utilities (things like locale and theme).
+ *
+ * These deal with raw CSS and DOM API, and is probably not
+ * very useful outside of browser environment.
+ *
+ * @module
+ */
+export * from "./dark.ts";
+export * from "./injectStyle.ts";
+export * from "./locale.ts";

package/src/pref/injectStyle.ts

@@ -0,0 +1,22 @@
+/**
+ * Inject a css string into a style tag identified by the id
+ *
+ * Will remove the old style tag(s) if exist
+ */
+export function injectStyle(id: string, style: string) {
+    const styleTags = document.querySelectorAll(`style[data-inject="${id}"`);
+    if (styleTags.length !== 1) {
+        const styleTag = document.createElement("style");
+        styleTag.setAttribute("data-inject", id);
+        styleTag.innerText = style;
+        document.head.appendChild(styleTag);
+        setTimeout(() => {
+            styleTags.forEach((tag) => tag.remove());
+        }, 0);
+    } else {
+        const e = styleTags[0] as HTMLStyleElement;
+        if (e.innerText !== style) {
+            e.innerText = style;
+        }
+    }
+}

package/src/pref/locale.ts

@@ -0,0 +1,341 @@
+/**
+ * Locale utilities and integration with i18next
+ *
+ * ## Initialization
+ * `initLocale` must be called before using the other functions.
+ *
+ * ```typescript
+ * import { initLocale } from "@pistonite/pure/pref";
+ *
+ * initLocale({
+ *     // required
+ *     supported: ["en", "zh-CN", "zh-TW"] as const,
+ *     default: "en",
+ *
+ *     // optional
+ *     persist: true, // save to localStorage
+ *     initial: "en-US", // initial value, instead of detecting
+ * });
+ * ```
+ *
+ * ## Connecting with i18next
+ * The typical usage for this component is to use i18next for localization.
+ * This module provides 2 plugins:
+ * - `detectLocale`:
+ *   - Provide the current language to i18next (as a language detector)
+ *   - Update the global locale state whenever `i18next.changeLanguage` is called
+ * - `connectI18next`:
+ *   - Call `i18next.changeLanguage` whenever `setLocale` is called
+ *
+ * You might only need one of these plugins, depending on your use case.
+ * For example, if you will never call `setLocale` manually, then you don't need `connectI18next`.
+ *
+ * ```typescript
+ * import i18next from "i18next";
+ * import { initLocale, detectLocale, connectI18next } from "@pistonite/pure/pref";
+ *
+ * // initialize locale
+ * initLocale({ supported: ["en", "es"], default: "en", persist: true });
+ *
+ * // connect with i18next
+ * i18next.use(detectLocale).use(connectI18next).init({
+ *   // ...other options not shown
+ * });
+ * ```
+ *
+ * ## Use with React
+ * A React hook is provided in the [`pure-react`](https://jsr.io/@pistonite/pure-react/doc/pref) package
+ * to get the current locale from React components.
+ *
+ * Changing the locale from React components is the same as from outside React,
+ * with `setLocale` or `i18next.changeLanguage`, depending on your setup.
+ *
+ * @module
+ */
+
+const KEY = "Pure.Locale";
+
+let supportedLocales: readonly string[] = [];
+let locale: string = "";
+let defaultLocale: string = "";
+const subscribers: ((locale: string) => void)[] = [];
+
+/**
+ * Use browser API to guess user's preferred locale
+ */
+export const getPreferredLocale = (): string => {
+    if (globalThis.Intl) {
+        try {
+            return globalThis.Intl.NumberFormat().resolvedOptions().locale;
+        } catch {
+            // ignore
+        }
+    }
+    if (globalThis.navigator?.languages) {
+        return globalThis.navigator.languages[0];
+    }
+    return "";
+};
+
+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: readonly TLocale[];
+    /**
+     * 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()`,
+     * which is based on the browser's language settings.
+     *
+     * If `persist` is `true`, it will also check the value from localStorage
+     *
+     * If the initial value is not supported, it will default to the default locale
+     */
+    initial?: TLocale;
+
+    /**
+     * Persist the locale preference to localStorage
+     */
+    persist?: boolean;
+};
+
+/** Initialize locale global state */
+export const initLocale = <TLocale extends string>(
+    options: LocaleOptions<TLocale>,
+): void => {
+    let _locale = "";
+    supportedLocales = options.supported;
+    if (options.initial) {
+        _locale = options.initial;
+    } else {
+        _locale =
+            convertToSupportedLocale(getPreferredLocale()) || options.default;
+    }
+    defaultLocale = options.default;
+    if (options.persist) {
+        const value = localStorage.getItem(KEY);
+        if (value !== null) {
+            const supported = convertToSupportedLocale(value);
+            if (supported) {
+                _locale = supported;
+            }
+        }
+        addLocaleSubscriber((locale: string) => {
+            localStorage.setItem(KEY, locale);
+        });
+    } else {
+        localStorage.removeItem(KEY);
+    }
+
+    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
+ *
+ * Returns `false` if the locale is not supported
+ */
+export const setLocale = (newLocale: string): boolean => {
+    const supported = convertToSupportedLocale(newLocale);
+    if (!supported) {
+        return false;
+    }
+    if (supported === locale) {
+        return true;
+    }
+    locale = supported;
+    const len = subscribers.length;
+    for (let i = 0; i < len; i++) {
+        subscribers[i](locale);
+    }
+    return true;
+};
+
+/**
+ * Convert a locale/language to a supported locale/language
+ *
+ * Returns `undefined` if no supported locale is found
+ *
+ * # Example
+ * It will first try to find an exact match for a locale (not language).
+ * If not found, it will try:
+ * - the first supported locale with a matching language
+ * - the first supported language
+ * ```typescript
+ * import { convertToSupportedLocale } from "@pistonite/pure/pref";
+ *
+ * // suppose supported locales are ["en", "zh", "zh-CN"]
+ * console.log(convertToSupportedLocale("en"));    // "en"
+ * console.log(convertToSupportedLocale("en-US")); // "en"
+ * console.log(convertToSupportedLocale("zh"));    // "zh-CN"
+ * console.log(convertToSupportedLocale("zh-CN")); // "zh-CN"
+ * console.log(convertToSupportedLocale("zh-TW")); // "zh"
+ * console.log(convertToSupportedLocale("es"));    // undefined
+ * ```
+ */
+export const convertToSupportedLocale = (
+    newLocale: string,
+): string | undefined => {
+    if (supportedLocales.includes(newLocale)) {
+        return newLocale;
+    }
+    const language = newLocale.split("-", 2)[0];
+    const len = supportedLocales.length;
+    for (let i = 0; i < len; i++) {
+        if (supportedLocales[i].startsWith(language)) {
+            return supportedLocales[i];
+        }
+    }
+    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
+ *
+ * If `notifyImmediately` is `true`, the subscriber will be called immediately with the current locale
+ */
+export const addLocaleSubscriber = (
+    fn: (locale: string) => void,
+    notifyImmediately?: boolean,
+): void => {
+    subscribers.push(fn);
+    if (notifyImmediately) {
+        fn(locale);
+    }
+};
+
+/**
+ * Remove a subscriber from locale changes
+ */
+export const removeLocaleSubscriber = (fn: (locale: string) => void): void => {
+    const index = subscribers.indexOf(fn);
+    if (index !== -1) {
+        subscribers.splice(index, 1);
+    }
+};
+
+/**
+ * Language detector plugin for i18next
+ *
+ * **Must call `initLocale` before initializaing i18next**
+ *
+ * This also sets the global locale state whenever `i18next.changeLanguage` is called.
+ *
+ * # Example
+ * ```typescript
+ * import i18next from "i18next";
+ * import { initLocale, detectLocale } from "@pistonite/pure/pref";
+ *
+ * initLocale({ supported: ["en", "es"], default: "en", persist: true });
+ *
+ * i18next.use(detectLocale).init({
+ *   // don't need to specify `lng` here
+ *
+ *   // ...other options not shown
+ * });
+ * ```
+ *
+ */
+export const detectLocale = {
+    type: "languageDetector" as const,
+    detect: () => locale,
+    cacheUserLanguage: (lng: string): void => {
+        setLocale(lng);
+    },
+};
+
+/**
+ * Bind the locale state to i18next, so whenever `setLocale`
+ * is called, it will also call `i18next.changeLanguage`.
+ *
+ * # Example
+ * ```typescript
+ * import i18next from "i18next";
+ * import { connectI18next, initLocale } from "@pistonite/pure/pref";
+ *
+ * initLocale({ supported: ["en", "es"], default: "en", persist: true });
+ * i18next.use(connectI18next).init({
+ *  // ...options
+ * });
+ *
+ */
+export const connectI18next = {
+    type: "3rdParty" as const,
+    init: (i18next: any): void => {
+        addLocaleSubscriber((locale) => {
+            if (i18next.language !== locale) {
+                i18next.changeLanguage(locale);
+            }
+        }, true);
+    },
+};
+
+const localizedLanguageNames = new Map();
+
+/**
+ * Get the localized name of a language using `Intl.DisplayNames`.
+ *
+ * The results are interanlly cached, so you don't need to cache this yourself.
+ */
+export const getLocalizedLanguageName = (language: string): string => {
+    if (language === "zh" || language === "zh-CN") {
+        return "\u7b80\u4f53\u4e2d\u6587";
+    }
+    if (language === "zh-TW") {
+        return "\u7e41\u9ad4\u4e2d\u6587";
+    }
+    if (localizedLanguageNames.has(language)) {
+        return localizedLanguageNames.get(language);
+    }
+    const languageWithoutLocale = language.split("-")[0];
+    const localized = new Intl.DisplayNames([language], {
+        type: "language",
+    }).of(languageWithoutLocale);
+    localizedLanguageNames.set(language, localized);
+    return localized || language;
+};