@tuwaio/docs-ui 0.5.2 → 0.5.4

package/dist/components/ThemeSwitcher.cjs

@@ -26,7 +26,7 @@ var import_jsx_runtime = require("react/jsx-runtime");
 var import_solid = require("@heroicons/react/24/solid");
 var import_utils = require("@tuwaio/nova-core/utils");
 var import_react = require("react");
-function ThemeSwitcher({ theme, onToggle }) {
+function ThemeSwitcher({ theme, onToggle, ariaLabel = "Toggle theme" }) {
   const [mounted, setMounted] = (0, import_react.useState)(false);
   (0, import_react.useEffect)(() => {
     setMounted(true);
@@ -52,7 +52,7 @@ function ThemeSwitcher({ theme, onToggle }) {
         "tuwadocs:group tuwadocs:relative tuwadocs:flex tuwadocs:h-10 tuwadocs:w-20 tuwadocs:md:h-8 tuwadocs:md:w-16 tuwadocs:cursor-pointer tuwadocs:items-center tuwadocs:rounded-[var(--tuwa-rounded-corners)] tuwadocs:p-1 tuwadocs:transition-all tuwadocs:duration-300 tuwadocs:ease-in-out tuwadocs:backdrop-blur-sm tuwadocs:border",
         defaultStyles
       ),
-      "aria-label": "Toggle theme",
+      "aria-label": ariaLabel,
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
           "div",
@@ -82,7 +82,7 @@ function ThemeSwitcher({ theme, onToggle }) {
           /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "tuwadocs:flex tuwadocs:flex-1 tuwadocs:justify-center", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
             import_solid.MoonIcon,
             {
-              className: `tuwadocs:h-6 tuwadocs:w-6 tuwadocs:relative tuwadocs:left-[2px] tuwadocs:md:h-5 tuwadocs:md:w-5 tuwadocs:transition-colors tuwadocs:duration-300 ${isDark ? "tuwadocs:text-indigo-400" : "tuwadocs:text-slate-500 tuwadocs:group-hover:text-indigo-300"}`
+              className: `tuwadocs:h-6 tuwadocs:w-6 tuwadocs:relative tuwadocs:left-[2px] tuwadocs:md:h-5 tuwadocs:md:w-5 tuwadocs:transition-colors tuwadocs:duration-300 ${isDark ? "tuwadocs:text-cyan-400" : "tuwadocs:text-slate-500 tuwadocs:group-hover:text-cyan-300"}`
             }
           ) })
         ] })

package/dist/components/ThemeSwitcher.d.cts

@@ -8,6 +8,8 @@ interface ThemeSwitcherProps {
     theme: string;
     /** Called when the switch is clicked; switch the theme of the site here (for example with `next-themes`) */
     onToggle: () => void;
+    /** Accessible name of the switch button (default: `'Toggle theme'`) */
+    ariaLabel?: string;
 }
 /**
  * A light/dark switch with a sliding indicator. It stores no theme itself: pass the resolved theme and a toggle. Until
@@ -17,7 +19,7 @@ interface ThemeSwitcherProps {
  * @param props - See {@link ThemeSwitcherProps}.
  * @returns The switch button.
  */
-declare function ThemeSwitcher({ theme, onToggle }: ThemeSwitcherProps): react.JSX.Element;
+declare function ThemeSwitcher({ theme, onToggle, ariaLabel }: ThemeSwitcherProps): react.JSX.Element;
 
 export { ThemeSwitcher };
 export type { ThemeSwitcherProps };

package/dist/components/ThemeSwitcher.d.ts

@@ -8,6 +8,8 @@ interface ThemeSwitcherProps {
     theme: string;
     /** Called when the switch is clicked; switch the theme of the site here (for example with `next-themes`) */
     onToggle: () => void;
+    /** Accessible name of the switch button (default: `'Toggle theme'`) */
+    ariaLabel?: string;
 }
 /**
  * A light/dark switch with a sliding indicator. It stores no theme itself: pass the resolved theme and a toggle. Until
@@ -17,7 +19,7 @@ interface ThemeSwitcherProps {
  * @param props - See {@link ThemeSwitcherProps}.
  * @returns The switch button.
  */
-declare function ThemeSwitcher({ theme, onToggle }: ThemeSwitcherProps): react.JSX.Element;
+declare function ThemeSwitcher({ theme, onToggle, ariaLabel }: ThemeSwitcherProps): react.JSX.Element;
 
 export { ThemeSwitcher };
 export type { ThemeSwitcherProps };

package/dist/components/ThemeSwitcher.js

@@ -3,7 +3,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { MoonIcon, SunIcon } from "@heroicons/react/24/solid";
 import { cn } from "@tuwaio/nova-core/utils";
 import { useEffect, useState } from "react";
-function ThemeSwitcher({ theme, onToggle }) {
+function ThemeSwitcher({ theme, onToggle, ariaLabel = "Toggle theme" }) {
   const [mounted, setMounted] = useState(false);
   useEffect(() => {
     setMounted(true);
@@ -29,7 +29,7 @@ function ThemeSwitcher({ theme, onToggle }) {
         "tuwadocs:group tuwadocs:relative tuwadocs:flex tuwadocs:h-10 tuwadocs:w-20 tuwadocs:md:h-8 tuwadocs:md:w-16 tuwadocs:cursor-pointer tuwadocs:items-center tuwadocs:rounded-[var(--tuwa-rounded-corners)] tuwadocs:p-1 tuwadocs:transition-all tuwadocs:duration-300 tuwadocs:ease-in-out tuwadocs:backdrop-blur-sm tuwadocs:border",
         defaultStyles
       ),
-      "aria-label": "Toggle theme",
+      "aria-label": ariaLabel,
       children: [
         /* @__PURE__ */ jsx(
           "div",
@@ -59,7 +59,7 @@ function ThemeSwitcher({ theme, onToggle }) {
           /* @__PURE__ */ jsx("div", { className: "tuwadocs:flex tuwadocs:flex-1 tuwadocs:justify-center", children: /* @__PURE__ */ jsx(
             MoonIcon,
             {
-              className: `tuwadocs:h-6 tuwadocs:w-6 tuwadocs:relative tuwadocs:left-[2px] tuwadocs:md:h-5 tuwadocs:md:w-5 tuwadocs:transition-colors tuwadocs:duration-300 ${isDark ? "tuwadocs:text-indigo-400" : "tuwadocs:text-slate-500 tuwadocs:group-hover:text-indigo-300"}`
+              className: `tuwadocs:h-6 tuwadocs:w-6 tuwadocs:relative tuwadocs:left-[2px] tuwadocs:md:h-5 tuwadocs:md:w-5 tuwadocs:transition-colors tuwadocs:duration-300 ${isDark ? "tuwadocs:text-cyan-400" : "tuwadocs:text-slate-500 tuwadocs:group-hover:text-cyan-300"}`
             }
           ) })
         ] })

package/dist/i18n.cjs

@@ -0,0 +1,114 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var i18n_exports = {};
+__export(i18n_exports, {
+  LocaleVariant: () => LocaleVariant,
+  createI18n: () => createI18n,
+  useLocaleState: () => useLocaleState
+});
+module.exports = __toCommonJS(i18n_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_react = require("react");
+var import_locale = require("./locale");
+function applyDocumentLanguage(locale) {
+  if (typeof document !== "undefined") document.documentElement.lang = locale;
+}
+function useLocaleState(options = {}) {
+  const { initialLocale, storageKey = import_locale.LOCALE_STORAGE_KEY } = options;
+  const [locale, setLocaleState] = (0, import_react.useState)(initialLocale ?? import_locale.DEFAULT_LOCALE);
+  const [resolved, setResolved] = (0, import_react.useState)(Boolean(initialLocale));
+  (0, import_react.useEffect)(() => {
+    const next = initialLocale ?? (0, import_locale.resolveClientLocale)(storageKey);
+    setLocaleState(next);
+    setResolved(true);
+    applyDocumentLanguage(next);
+  }, [initialLocale, storageKey]);
+  (0, import_react.useEffect)(() => {
+    if (initialLocale) return;
+    const onStorage = (event) => {
+      if (event.key !== storageKey) return;
+      const next = (0, import_locale.normalizeLocale)(event.newValue);
+      if (next) {
+        setLocaleState(next);
+        applyDocumentLanguage(next);
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, [initialLocale, storageKey]);
+  const setLocale = (0, import_react.useCallback)(
+    (target) => {
+      const next = (0, import_locale.normalizeLocale)(target) ?? import_locale.DEFAULT_LOCALE;
+      setLocaleState(next);
+      applyDocumentLanguage(next);
+      try {
+        window.localStorage.setItem(storageKey, next);
+      } catch {
+      }
+    },
+    [storageKey]
+  );
+  return { locale, setLocale, resolved };
+}
+function createI18n(dictionaries, defaults = {}) {
+  const fallback = {
+    locale: import_locale.DEFAULT_LOCALE,
+    setLocale: () => {
+    },
+    resolved: false,
+    t: dictionaries[import_locale.DEFAULT_LOCALE],
+    format: import_locale.formatLabel
+  };
+  const Context = (0, import_react.createContext)(fallback);
+  function I18nProvider({ children, initialLocale, storageKey }) {
+    const state = useLocaleState({
+      initialLocale: initialLocale ?? defaults.initialLocale,
+      storageKey: storageKey ?? defaults.storageKey
+    });
+    const { locale, setLocale, resolved } = state;
+    const value = (0, import_react.useMemo)(
+      () => ({
+        locale,
+        setLocale,
+        resolved,
+        t: dictionaries[locale] ?? dictionaries[import_locale.DEFAULT_LOCALE],
+        format: import_locale.formatLabel
+      }),
+      [locale, setLocale, resolved]
+    );
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Context.Provider, { value, children });
+  }
+  function useI18n() {
+    return (0, import_react.useContext)(Context);
+  }
+  return { I18nProvider, useI18n, dictionaries };
+}
+function LocaleVariant({
+  locale,
+  variants
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: variants[locale] ?? variants[import_locale.DEFAULT_LOCALE] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LocaleVariant,
+  createI18n,
+  useLocaleState
+});

package/dist/i18n.d.cts

@@ -0,0 +1,81 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { TuwaLocale, formatLabel } from './locale.cjs';
+
+/** State and setter returned by {@link useLocaleState}. */
+interface LocaleState {
+    /** The active locale: {@link DEFAULT_LOCALE} on the server and in the first client render. */
+    locale: TuwaLocale;
+    /** Switches the locale, saves it under the storage key and updates `<html lang>`. Unknown values fall back. */
+    setLocale: (next: TuwaLocale | string) => void;
+    /** Whether the locale of the browser has been read (`false` during SSR and the first client render). */
+    resolved: boolean;
+}
+/** Options of {@link useLocaleState} and {@link createI18n}. */
+interface LocaleStateOptions {
+    /** Fixed locale (tests, a page rendered in one language): detection is skipped. */
+    initialLocale?: TuwaLocale;
+    /** Local Storage key of the picked locale (default: {@link LOCALE_STORAGE_KEY}). */
+    storageKey?: string;
+}
+/**
+ * Locale state without dictionaries: renders {@link DEFAULT_LOCALE} first, so the server HTML and the first client
+ * render match, then reads the locale of the browser after mount ({@link resolveClientLocale}). Use it directly when an
+ * app keeps its texts elsewhere; {@link createI18n} builds on it.
+ *
+ * @param options - See {@link LocaleStateOptions}.
+ * @returns The locale, its setter and whether detection ran.
+ */
+declare function useLocaleState(options?: LocaleStateOptions): LocaleState;
+/** Value of the context created by {@link createI18n}. */
+interface I18nContextValue<Labels> extends LocaleState {
+    /** Texts of the active locale. */
+    t: Labels;
+    /** {@link formatLabel}, for `{name}` tokens in the texts. */
+    format: typeof formatLabel;
+}
+/** Props of the provider created by {@link createI18n}. */
+interface I18nProviderProps extends LocaleStateOptions {
+    children: ReactNode;
+}
+/** What {@link createI18n} returns. */
+interface I18nKit<Labels> {
+    /** Provides the locale and the texts to the tree. */
+    I18nProvider: ComponentType<I18nProviderProps>;
+    /** Reads the locale, its setter and the texts; outside the provider it returns the English texts and a no-op. */
+    useI18n: () => I18nContextValue<Labels>;
+    /** The dictionaries, by locale. */
+    dictionaries: Readonly<Record<TuwaLocale, Labels>>;
+}
+/**
+ * Creates a typed i18n kit for one app: a provider and a hook over its own dictionaries. Each TUWA site keeps its texts
+ * (and their schema) in the app, and shares detection, persistence and switching through this package.
+ *
+ * @example
+ * ```tsx
+ * export const { I18nProvider, useI18n } = createI18n<SiteLabels>({ en, uk, 'zh-CN': zhCN });
+ * ```
+ *
+ * @param dictionaries - The texts of every {@link TuwaLocale}; the English ones are the fallback.
+ * @param defaults - Options applied to every provider of the kit.
+ * @returns The provider, the hook and the dictionaries.
+ */
+declare function createI18n<Labels>(dictionaries: Readonly<Record<TuwaLocale, Labels>>, defaults?: LocaleStateOptions): I18nKit<Labels>;
+/**
+ * Renders the child of the active locale: content prepared for every locale on the server (translated MDX pages),
+ * switched on the client without a request. The server HTML holds the {@link DEFAULT_LOCALE} child, so crawlers and
+ * the search index read English.
+ *
+ * @param props.locale - The active locale.
+ * @param props.variants - Content by locale; a missing locale shows the default.
+ * @returns The content of the locale.
+ */
+declare function LocaleVariant({ locale, variants, }: {
+    locale: TuwaLocale;
+    variants: Partial<Record<TuwaLocale, ReactNode>> & {
+        en: ReactNode;
+    };
+}): react.JSX.Element;
+
+export { LocaleVariant, createI18n, useLocaleState };
+export type { I18nContextValue, I18nKit, I18nProviderProps, LocaleState, LocaleStateOptions };

package/dist/i18n.d.ts

@@ -0,0 +1,81 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { TuwaLocale, formatLabel } from './locale.js';
+
+/** State and setter returned by {@link useLocaleState}. */
+interface LocaleState {
+    /** The active locale: {@link DEFAULT_LOCALE} on the server and in the first client render. */
+    locale: TuwaLocale;
+    /** Switches the locale, saves it under the storage key and updates `<html lang>`. Unknown values fall back. */
+    setLocale: (next: TuwaLocale | string) => void;
+    /** Whether the locale of the browser has been read (`false` during SSR and the first client render). */
+    resolved: boolean;
+}
+/** Options of {@link useLocaleState} and {@link createI18n}. */
+interface LocaleStateOptions {
+    /** Fixed locale (tests, a page rendered in one language): detection is skipped. */
+    initialLocale?: TuwaLocale;
+    /** Local Storage key of the picked locale (default: {@link LOCALE_STORAGE_KEY}). */
+    storageKey?: string;
+}
+/**
+ * Locale state without dictionaries: renders {@link DEFAULT_LOCALE} first, so the server HTML and the first client
+ * render match, then reads the locale of the browser after mount ({@link resolveClientLocale}). Use it directly when an
+ * app keeps its texts elsewhere; {@link createI18n} builds on it.
+ *
+ * @param options - See {@link LocaleStateOptions}.
+ * @returns The locale, its setter and whether detection ran.
+ */
+declare function useLocaleState(options?: LocaleStateOptions): LocaleState;
+/** Value of the context created by {@link createI18n}. */
+interface I18nContextValue<Labels> extends LocaleState {
+    /** Texts of the active locale. */
+    t: Labels;
+    /** {@link formatLabel}, for `{name}` tokens in the texts. */
+    format: typeof formatLabel;
+}
+/** Props of the provider created by {@link createI18n}. */
+interface I18nProviderProps extends LocaleStateOptions {
+    children: ReactNode;
+}
+/** What {@link createI18n} returns. */
+interface I18nKit<Labels> {
+    /** Provides the locale and the texts to the tree. */
+    I18nProvider: ComponentType<I18nProviderProps>;
+    /** Reads the locale, its setter and the texts; outside the provider it returns the English texts and a no-op. */
+    useI18n: () => I18nContextValue<Labels>;
+    /** The dictionaries, by locale. */
+    dictionaries: Readonly<Record<TuwaLocale, Labels>>;
+}
+/**
+ * Creates a typed i18n kit for one app: a provider and a hook over its own dictionaries. Each TUWA site keeps its texts
+ * (and their schema) in the app, and shares detection, persistence and switching through this package.
+ *
+ * @example
+ * ```tsx
+ * export const { I18nProvider, useI18n } = createI18n<SiteLabels>({ en, uk, 'zh-CN': zhCN });
+ * ```
+ *
+ * @param dictionaries - The texts of every {@link TuwaLocale}; the English ones are the fallback.
+ * @param defaults - Options applied to every provider of the kit.
+ * @returns The provider, the hook and the dictionaries.
+ */
+declare function createI18n<Labels>(dictionaries: Readonly<Record<TuwaLocale, Labels>>, defaults?: LocaleStateOptions): I18nKit<Labels>;
+/**
+ * Renders the child of the active locale: content prepared for every locale on the server (translated MDX pages),
+ * switched on the client without a request. The server HTML holds the {@link DEFAULT_LOCALE} child, so crawlers and
+ * the search index read English.
+ *
+ * @param props.locale - The active locale.
+ * @param props.variants - Content by locale; a missing locale shows the default.
+ * @returns The content of the locale.
+ */
+declare function LocaleVariant({ locale, variants, }: {
+    locale: TuwaLocale;
+    variants: Partial<Record<TuwaLocale, ReactNode>> & {
+        en: ReactNode;
+    };
+}): react.JSX.Element;
+
+export { LocaleVariant, createI18n, useLocaleState };
+export type { I18nContextValue, I18nKit, I18nProviderProps, LocaleState, LocaleStateOptions };

package/dist/i18n.js

@@ -0,0 +1,101 @@
+"use client";
+import { Fragment, jsx } from "react/jsx-runtime";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+import {
+  DEFAULT_LOCALE,
+  formatLabel,
+  LOCALE_STORAGE_KEY,
+  normalizeLocale,
+  resolveClientLocale
+} from "./locale";
+function applyDocumentLanguage(locale) {
+  if (typeof document !== "undefined") document.documentElement.lang = locale;
+}
+function useLocaleState(options = {}) {
+  const { initialLocale, storageKey = LOCALE_STORAGE_KEY } = options;
+  const [locale, setLocaleState] = useState(initialLocale ?? DEFAULT_LOCALE);
+  const [resolved, setResolved] = useState(Boolean(initialLocale));
+  useEffect(() => {
+    const next = initialLocale ?? resolveClientLocale(storageKey);
+    setLocaleState(next);
+    setResolved(true);
+    applyDocumentLanguage(next);
+  }, [initialLocale, storageKey]);
+  useEffect(() => {
+    if (initialLocale) return;
+    const onStorage = (event) => {
+      if (event.key !== storageKey) return;
+      const next = normalizeLocale(event.newValue);
+      if (next) {
+        setLocaleState(next);
+        applyDocumentLanguage(next);
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, [initialLocale, storageKey]);
+  const setLocale = useCallback(
+    (target) => {
+      const next = normalizeLocale(target) ?? DEFAULT_LOCALE;
+      setLocaleState(next);
+      applyDocumentLanguage(next);
+      try {
+        window.localStorage.setItem(storageKey, next);
+      } catch {
+      }
+    },
+    [storageKey]
+  );
+  return { locale, setLocale, resolved };
+}
+function createI18n(dictionaries, defaults = {}) {
+  const fallback = {
+    locale: DEFAULT_LOCALE,
+    setLocale: () => {
+    },
+    resolved: false,
+    t: dictionaries[DEFAULT_LOCALE],
+    format: formatLabel
+  };
+  const Context = createContext(fallback);
+  function I18nProvider({ children, initialLocale, storageKey }) {
+    const state = useLocaleState({
+      initialLocale: initialLocale ?? defaults.initialLocale,
+      storageKey: storageKey ?? defaults.storageKey
+    });
+    const { locale, setLocale, resolved } = state;
+    const value = useMemo(
+      () => ({
+        locale,
+        setLocale,
+        resolved,
+        t: dictionaries[locale] ?? dictionaries[DEFAULT_LOCALE],
+        format: formatLabel
+      }),
+      [locale, setLocale, resolved]
+    );
+    return /* @__PURE__ */ jsx(Context.Provider, { value, children });
+  }
+  function useI18n() {
+    return useContext(Context);
+  }
+  return { I18nProvider, useI18n, dictionaries };
+}
+function LocaleVariant({
+  locale,
+  variants
+}) {
+  return /* @__PURE__ */ jsx(Fragment, { children: variants[locale] ?? variants[DEFAULT_LOCALE] });
+}
+export {
+  LocaleVariant,
+  createI18n,
+  useLocaleState
+};

package/dist/index.cjs

@@ -42,6 +42,8 @@ __reExport(index_exports, require("./components/Orb"), module.exports);
 __reExport(index_exports, require("./components/PolicyDocument"), module.exports);
 var import_StarryBackground = __toESM(require("./components/StarryBackground"), 1);
 __reExport(index_exports, require("./components/ThemeSwitcher"), module.exports);
+__reExport(index_exports, require("./i18n"), module.exports);
+__reExport(index_exports, require("./locale"), module.exports);
 __reExport(index_exports, require("./policies"), module.exports);
 __reExport(index_exports, require("./preferences"), module.exports);
 __reExport(index_exports, require("./utils"), module.exports);
@@ -56,6 +58,8 @@ __reExport(index_exports, require("./utils"), module.exports);
   ...require("./components/Orb"),
   ...require("./components/PolicyDocument"),
   ...require("./components/ThemeSwitcher"),
+  ...require("./i18n"),
+  ...require("./locale"),
   ...require("./policies"),
   ...require("./preferences"),
   ...require("./utils")