nfx-ui 0.20.0 → 0.22.0

package/src/languages/hooks/useLanguageLabel.ts

@@ -0,0 +1,47 @@
+import i18n from "i18next";
+import { useTranslation } from "react-i18next";
+
+import { BaseEnum } from "@/enums/theme";
+import { LanguageEnum } from "../types";
+
+function getLanguageI18nKey(lang: LanguageEnum): string {
+  const keyMap: Record<LanguageEnum, string> = {
+    [LanguageEnum.EN]: "languageSwitcher.english",
+    [LanguageEnum.ZH]: "languageSwitcher.chinese",
+    [LanguageEnum.FR]: "languageSwitcher.french",
+  };
+  return keyMap[lang];
+}
+
+export function useLanguageLabel(): {
+  getLanguageDisplayName: (lang: LanguageEnum) => string;
+} {
+  const { t } = useTranslation("language");
+  const getLanguageDisplayName = (lang: LanguageEnum): string =>
+    t(getLanguageI18nKey(lang), {
+      defaultValue: lang,
+    });
+
+  return { getLanguageDisplayName };
+}
+
+export function getLanguageDisplayName(lang: LanguageEnum): string {
+  const fallbackMap: Record<LanguageEnum, string> = {
+    [LanguageEnum.EN]: "English",
+    [LanguageEnum.ZH]: "中文",
+    [LanguageEnum.FR]: "Français",
+  };
+  return fallbackMap[lang];
+}
+
+function getBaseDisplayNameImpl(base: BaseEnum): string {
+  return i18n.t("baseSwitcher." + base, { ns: "theme", defaultValue: base });
+}
+
+export function useBaseLabel(): {
+  getBaseDisplayName: (base: BaseEnum) => string;
+} {
+  return { getBaseDisplayName: getBaseDisplayNameImpl };
+}
+
+export { getBaseDisplayNameImpl as getBaseDisplayName };

package/src/languages/hooks/useLayoutLabel.ts

@@ -0,0 +1,20 @@
+/**
+ * 返回 { getLayoutDisplayName }，便于扩展；getLayoutDisplayName 可传给 SlideDownSwitcher 的 getDisplayName。
+ * Returns { getLayoutDisplayName } for extensibility; pass to SlideDownSwitcher getDisplayName.
+ */
+import type { LayoutModeEnum } from "@/enums/layout";
+
+import { useCallback, useMemo } from "react";
+
+import i18n from "../languages/i18n";
+
+function getLayoutDisplayNameImpl(mode: LayoutModeEnum): string {
+  return i18n.t("layoutSwitcher." + mode, { ns: "layout", defaultValue: mode });
+}
+
+export function useLayoutLabel(): { getLayoutDisplayName: (mode: LayoutModeEnum) => string } {
+  const getLayoutDisplayName = useCallback(getLayoutDisplayNameImpl, []);
+  return useMemo(() => ({ getLayoutDisplayName }), [getLayoutDisplayName]);
+}
+
+export { getLayoutDisplayNameImpl as getLayoutDisplayName };

package/src/languages/hooks/usePreferenceLabel.ts

@@ -0,0 +1,20 @@
+/**
+ * 返回 { getPreferenceDisplayName }（Base 展示名），便于扩展；可传给 SlideDownSwitcher 的 getDisplayName。
+ * Returns { getPreferenceDisplayName } for extensibility; pass to SlideDownSwitcher getDisplayName.
+ */
+import type { BaseEnum } from "@/enums/theme";
+
+import { useCallback, useMemo } from "react";
+
+import i18n from "../languages/i18n";
+
+function getPreferenceDisplayNameImpl(base: BaseEnum): string {
+  return i18n.t("baseSwitcher." + base, { ns: "preference", defaultValue: base });
+}
+
+export function usePreferenceLabel(): { getPreferenceDisplayName: (base: BaseEnum) => string } {
+  const getPreferenceDisplayName = useCallback(getPreferenceDisplayNameImpl, []);
+  return useMemo(() => ({ getPreferenceDisplayName }), [getPreferenceDisplayName]);
+}
+
+export { getPreferenceDisplayNameImpl as getPreferenceDisplayName };

package/src/languages/hooks/useThemeLabel.ts

@@ -0,0 +1,19 @@
+/**
+ * Accent / appearance labels for ThemeSettings.
+ */
+import type { AccentColorEnum } from "@/enums/theme";
+
+import { useCallback, useMemo } from "react";
+
+import i18n from "../languages/i18n";
+
+function getThemeDisplayNameImpl(accent: AccentColorEnum): string {
+  return i18n.t("accent." + accent, { ns: "theme", defaultValue: accent });
+}
+
+export function useThemeLabel(): { getThemeDisplayName: (accent: AccentColorEnum) => string } {
+  const getThemeDisplayName = useCallback(getThemeDisplayNameImpl, []);
+  return useMemo(() => ({ getThemeDisplayName }), [getThemeDisplayName]);
+}
+
+export { getThemeDisplayNameImpl as getThemeDisplayName };

package/src/languages/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 语言模块统一导出。Languages module barrel exports.
+ */
+export * from "./hooks";
+export * from "./languages";
+export { default as i18n } from "./languages/i18n";
+export * from "./resources";
+export * from "./types";
+export * from "./utils";

package/src/languages/languages/i18n.ts

@@ -0,0 +1,107 @@
+/**
+ * i18n 初始化与实例：initI18n 由 LanguageProvider 调用。
+ * 默认合并 NFX-UI 自带的 theme / language / layout / preference 命名空间。
+ */
+import type { CreateI18nResourcesResult, ExtraBundleItem, InitI18nOptions } from "../types";
+
+import i18n from "i18next";
+import LanguageDetector from "i18next-browser-languagedetector";
+import { initReactI18next } from "react-i18next";
+
+import { LanguageEnum, LANGUAGE_VALUES } from "@/enums/language";
+import { PreferenceStore, setPreference } from "@/stores/preference";
+import { safeEnum, safeStringable } from "@/utils/safe";
+
+import { getDefaultNfxBundles } from "../resources";
+
+export function toSupportedLanguage(lng: string, fallbackLng: LanguageEnum): LanguageEnum {
+  const prefix = safeStringable(lng.split("-")[0]?.toLowerCase());
+  return safeEnum<LanguageEnum>(prefix || undefined, LANGUAGE_VALUES, fallbackLng);
+}
+
+function applyDocumentLang(lng: string, fallbackLng: LanguageEnum) {
+  if (typeof document === "undefined") return;
+  document.documentElement.lang = toSupportedLanguage(lng, fallbackLng);
+}
+
+let languagePersistAttached = false;
+
+function applyExtraBundles(lng: string, fallbackLng: LanguageEnum, items: ExtraBundleItem[]) {
+  const code = toSupportedLanguage(lng, fallbackLng);
+  for (const { namespace, bundle } of items) {
+    if (namespace && bundle && typeof bundle === "object") {
+      i18n.addResourceBundle(code, namespace, bundle, true, true);
+    }
+  }
+}
+
+export function initI18n(options: InitI18nOptions): void {
+  const fallbackLng = options.fallbackLng ?? LanguageEnum.ZH;
+
+  if (i18n.isInitialized) {
+    applyDocumentLang(i18n.language || fallbackLng, fallbackLng);
+    return;
+  }
+
+  const nfx = getDefaultNfxBundles();
+  const user: CreateI18nResourcesResult = options.getBuiltinBundles();
+  const RESOURCES = ([LanguageEnum.EN, LanguageEnum.ZH, LanguageEnum.FR] as const).reduce(
+    (acc, lang) => ({
+      ...acc,
+      [lang]: {
+        ...(nfx.RESOURCES[lang] ?? {}),
+        ...(user.RESOURCES[lang] ?? {}),
+      },
+    }),
+    {} as typeof user.RESOURCES,
+  );
+  const NAME_SPACES = [...user.NAME_SPACES, ...nfx.NAME_SPACES.filter((n) => !user.NAME_SPACES.includes(n))];
+  const initialLng = PreferenceStore.getState().language;
+
+  const persistLanguage = (lng: string) => {
+    const code = toSupportedLanguage(lng, fallbackLng);
+    setPreference({ language: code });
+    applyDocumentLang(code, fallbackLng);
+  };
+
+  if (!languagePersistAttached) {
+    i18n.on("languageChanged", persistLanguage);
+    languagePersistAttached = true;
+  }
+
+  i18n
+    .use(LanguageDetector)
+    .use(initReactI18next)
+    .init({
+      compatibilityJSON: "v4",
+      resources: RESOURCES,
+      lng: initialLng,
+      fallbackLng,
+      supportedLngs: [...LANGUAGE_VALUES],
+      load: "languageOnly",
+      ns: NAME_SPACES,
+      defaultNS: NAME_SPACES[0],
+      interpolation: { escapeValue: false },
+      keySeparator: ".",
+      detection: {
+        order: ["navigator", "htmlTag", "path", "subdomain"],
+        caches: [],
+      },
+    });
+
+  applyDocumentLang(i18n.language || initialLng || fallbackLng, fallbackLng);
+
+  const onLoad = options.onLoadExtraBundles;
+  if (onLoad) {
+    const apply = async (lng: string) => {
+      const result = await onLoad(toSupportedLanguage(lng, fallbackLng));
+      if (result == null) return;
+      const items = Array.isArray(result) ? result : [result];
+      applyExtraBundles(lng, fallbackLng, items);
+    };
+    void apply(i18n.language || fallbackLng);
+    i18n.on("languageChanged", (lng) => void apply(lng));
+  }
+}
+
+export default i18n;

package/src/languages/languages/i18nResources.ts

@@ -0,0 +1,32 @@
+/**
+ * 文案包工厂：createI18nResources(resources, nameSpacesMap) 供用户自建 JSON 后生成 i18n 所需结构。
+ * Bundle factory: createI18nResources(resources, nameSpacesMap) for building i18n structure from user JSON.
+ */
+import type { CreateI18nResourcesResult, LanguageEnum, NameSpacesMap, Resources } from "../types";
+
+import i18n from "./i18n";
+import { setPreference } from "@/stores/preference";
+
+/**
+ * 由调用方传入 resources 和 nameSpacesMap，生成 i18n 所需的 RESOURCES、NAME_SPACES_MAP、NAME_SPACES。
+ * Caller provides resources and nameSpacesMap; returns RESOURCES, NAME_SPACES_MAP, NAME_SPACES for i18n.
+ *
+ * @param resources - 各语言下的命名空间文案。Bundles per language.
+ * @param nameSpacesMap - 命名空间 key → 命名空间字符串。Namespace key to string.
+ */
+function createI18nResources(resources: Resources, nameSpacesMap: NameSpacesMap): CreateI18nResourcesResult {
+  return {
+    RESOURCES: resources,
+    NAME_SPACES_MAP: nameSpacesMap,
+    NAME_SPACES: Object.values(nameSpacesMap),
+  };
+}
+
+/** 切换当前语言；唯一真相是 PreferenceStore。 */
+function changeLanguage(lng: LanguageEnum): void {
+  setPreference({ language: lng });
+  void i18n.changeLanguage(lng);
+}
+
+export { createI18nResources, changeLanguage };
+export type { CreateI18nResourcesResult, Resources, NameSpacesMap, NamespaceBundle } from "../types";

package/src/languages/languages/index.ts

@@ -0,0 +1,2 @@
+export * from "./i18n";
+export * from "./i18nResources";

package/src/languages/resources/en/language.json

@@ -0,0 +1,47 @@
+{
+  "languageSwitcher": {
+    "english": "English",
+    "chinese": "中文",
+    "french": "Français",
+    "en": "English",
+    "zh": "Chinese",
+    "fr": "French"
+  },
+  "header": {
+    "home": "Home",
+    "about": "About",
+    "openMenu": "Open menu",
+    "contact": "Contact",
+    "login": "Login",
+    "signup": "Signup",
+    "profile": "Profile",
+    "logout": "Logout",
+    "preferences": "Preferences",
+    "theme": "Theme",
+    "accentColor": "Accent color",
+    "grayColor": "Gray color",
+    "appearance": "Appearance",
+    "appearanceMode": {
+      "light": "Light",
+      "dark": "Dark",
+      "system": "System"
+    },
+    "panelBackground": "Panel background",
+    "panelBackgroundMode": {
+      "solid": "Solid",
+      "translucent": "Translucent"
+    },
+    "radius": "Platform",
+    "scaling": "Scaling",
+    "language": "Language",
+    "panel": "Control panel"
+  },
+  "sidebar": {
+    "collapse": "Collapse sidebar",
+    "expand": "Expand sidebar",
+    "openMenu": "Open menu",
+    "logout": "Logout",
+    "helpCenter": "Help Center",
+    "settingsItem": "Settings"
+  }
+}

package/src/languages/resources/en/layout.json

@@ -0,0 +1,6 @@
+{
+  "layoutSwitcher": {
+    "show": "Show Sidebar",
+    "hide": "Hide Sidebar"
+  }
+}

package/src/languages/resources/en/preference.json

@@ -0,0 +1,49 @@
+{
+  "baseSwitcher": {
+    "default": "Default",
+    "ios": "iOS",
+    "android": "Android",
+    "windows": "Windows",
+    "linux": "Linux"
+  },
+  "preference": {
+    "theme": "Theme",
+    "language": "Language",
+    "layout": "Layout",
+    "preferences": "Preferences"
+  },
+  "actions": {
+    "reset": "Reset",
+    "saveTheme": "Save theme"
+  },
+  "labels": {
+    "appearance": "Appearance",
+    "accent": "Accent",
+    "gray": "Gray",
+    "radius": "Radius",
+    "scaling": "Scaling",
+    "panelBackground": "Panel background",
+    "font": "Font",
+    "livePreview": "Live preview",
+    "previewBadge": "Preview",
+    "previewSolid": "Solid",
+    "previewSoft": "Soft",
+    "sampleInput": "Sample input",
+    "notifications": "Notifications",
+    "unsavedChanges": "Unsaved changes",
+    "fontSystem": "System",
+    "fontIbmPlex": "IBM Plex",
+    "fontNoto": "Noto Sans",
+    "fontSourceSans": "Source Sans 3",
+    "langEn": "English",
+    "langZh": "中文",
+    "langFr": "Français",
+    "colorAndAppearance": "Appearance & color",
+    "layoutAndType": "Radius & type"
+  },
+  "sections": {
+    "language": {
+      "title": "Language"
+    }
+  }
+}

package/src/languages/resources/en/theme.json

@@ -0,0 +1,14 @@
+{
+  "themeSwitcher": {
+    "light": "Light",
+    "dark": "Dark",
+    "system": "System"
+  },
+  "baseSwitcher": {
+    "default": "Other",
+    "ios": "iOS",
+    "android": "Android",
+    "windows": "Windows",
+    "linux": "Linux"
+  }
+}

package/src/languages/resources/fr/language.json

@@ -0,0 +1,47 @@
+{
+  "languageSwitcher": {
+    "english": "English",
+    "chinese": "中文",
+    "french": "Français",
+    "en": "Anglais",
+    "zh": "Chinois",
+    "fr": "Français"
+  },
+  "header": {
+    "home": "Accueil",
+    "about": "À propos",
+    "openMenu": "Ouvrir le menu",
+    "contact": "Contact",
+    "login": "Connexion",
+    "signup": "Inscription",
+    "profile": "Profil",
+    "logout": "Déconnexion",
+    "preferences": "Préférences",
+    "theme": "Thème",
+    "accentColor": "Couleur d'accent",
+    "grayColor": "Gris",
+    "appearance": "Apparence",
+    "appearanceMode": {
+      "light": "Clair",
+      "dark": "Sombre",
+      "system": "Système"
+    },
+    "panelBackground": "Fond de panneau",
+    "panelBackgroundMode": {
+      "solid": "Solide",
+      "translucent": "Translucide"
+    },
+    "radius": "Plateforme",
+    "scaling": "Échelle",
+    "language": "Langue",
+    "panel": "Panneau"
+  },
+  "sidebar": {
+    "collapse": "Réduire",
+    "expand": "Développer",
+    "openMenu": "Ouvrir le menu",
+    "logout": "Déconnexion",
+    "helpCenter": "Aide",
+    "settingsItem": "Réglages"
+  }
+}

package/src/languages/resources/fr/layout.json

@@ -0,0 +1,6 @@
+{
+  "layoutSwitcher": {
+    "show": "Afficher la barre latérale",
+    "hide": "Masquer la barre latérale"
+  }
+}

package/src/languages/resources/fr/preference.json

@@ -0,0 +1,49 @@
+{
+  "baseSwitcher": {
+    "default": "Défaut",
+    "ios": "iOS",
+    "android": "Android",
+    "windows": "Windows",
+    "linux": "Linux"
+  },
+  "preference": {
+    "theme": "Thème",
+    "language": "Langue",
+    "layout": "Disposition",
+    "preferences": "Préférences"
+  },
+  "actions": {
+    "reset": "Réinitialiser",
+    "saveTheme": "Enregistrer le thème"
+  },
+  "labels": {
+    "appearance": "Apparence",
+    "accent": "Accent",
+    "gray": "Gris",
+    "radius": "Rayon",
+    "scaling": "Échelle",
+    "panelBackground": "Fond de panneau",
+    "font": "Police",
+    "livePreview": "Aperçu",
+    "previewBadge": "Aperçu",
+    "previewSolid": "Solide",
+    "previewSoft": "Doux",
+    "sampleInput": "Exemple",
+    "notifications": "Notifications",
+    "unsavedChanges": "Modifications non enregistrées",
+    "fontSystem": "Système",
+    "fontIbmPlex": "IBM Plex",
+    "fontNoto": "Noto Sans",
+    "fontSourceSans": "Source Sans 3",
+    "langEn": "English",
+    "langZh": "中文",
+    "langFr": "Français",
+    "colorAndAppearance": "Apparence et couleur",
+    "layoutAndType": "Rayon et police"
+  },
+  "sections": {
+    "language": {
+      "title": "Langue"
+    }
+  }
+}

package/src/languages/resources/fr/theme.json

@@ -0,0 +1,14 @@
+{
+  "themeSwitcher": {
+    "light": "Clair",
+    "dark": "Sombre",
+    "system": "Système"
+  },
+  "baseSwitcher": {
+    "default": "Autre",
+    "ios": "iOS",
+    "android": "Android",
+    "windows": "Windows",
+    "linux": "Linux"
+  }
+}

package/src/languages/resources/index.ts

@@ -0,0 +1,62 @@
+/**
+ * NFX-UI 内置多语言资源：theme / language / layout / preference 四个命名空间，en / zh / fr 三种语言。
+ * Built-in i18n resources: namespaces theme, language, layout, preference; languages en, zh, fr.
+ *
+ * LanguageProvider 会把这些命名空间与宿主 getBuiltinBundles 合并。
+ * LanguageProvider merges these namespaces with host getBuiltinBundles.
+ */
+import type { CreateI18nResourcesResult, NameSpacesMap, Resources } from "../types";
+
+import enLayout from "./en/layout.json";
+import enLanguage from "./en/language.json";
+import enPreference from "./en/preference.json";
+import enTheme from "./en/theme.json";
+import frLayout from "./fr/layout.json";
+import frLanguage from "./fr/language.json";
+import frPreference from "./fr/preference.json";
+import frTheme from "./fr/theme.json";
+import zhLayout from "./zh/layout.json";
+import zhLanguage from "./zh/language.json";
+import zhPreference from "./zh/preference.json";
+import zhTheme from "./zh/theme.json";
+
+export const NFX_NAMESPACES = ["theme", "language", "layout", "preference"] as const;
+export const NFX_NAMESPACES_MAP: NameSpacesMap = {
+  theme: "theme",
+  language: "language",
+  layout: "layout",
+  preference: "preference",
+};
+
+const DEFAULT_NFX_RESOURCES: Resources = {
+  en: {
+    theme: enTheme as Record<string, unknown>,
+    language: enLanguage as Record<string, unknown>,
+    layout: enLayout as Record<string, unknown>,
+    preference: enPreference as Record<string, unknown>,
+  },
+  zh: {
+    theme: zhTheme as Record<string, unknown>,
+    language: zhLanguage as Record<string, unknown>,
+    layout: zhLayout as Record<string, unknown>,
+    preference: zhPreference as Record<string, unknown>,
+  },
+  fr: {
+    theme: frTheme as Record<string, unknown>,
+    language: frLanguage as Record<string, unknown>,
+    layout: frLayout as Record<string, unknown>,
+    preference: frPreference as Record<string, unknown>,
+  },
+};
+
+/**
+ * 返回 NFX-UI 默认文案包，可与使用方自建 resources 合并后传入 createI18nResources。
+ * Returns default NFX bundles; merge with your resources and pass to createI18nResources.
+ */
+export function getDefaultNfxBundles(): CreateI18nResourcesResult {
+  return {
+    RESOURCES: DEFAULT_NFX_RESOURCES,
+    NAME_SPACES_MAP: NFX_NAMESPACES_MAP,
+    NAME_SPACES: [...NFX_NAMESPACES],
+  };
+}

package/src/languages/resources/zh/language.json

@@ -0,0 +1,47 @@
+{
+  "languageSwitcher": {
+    "english": "English",
+    "chinese": "中文",
+    "french": "Français",
+    "en": "英语",
+    "zh": "中文",
+    "fr": "法语"
+  },
+  "header": {
+    "home": "首页",
+    "about": "关于",
+    "openMenu": "打开菜单",
+    "contact": "联系",
+    "login": "登录",
+    "signup": "注册",
+    "profile": "资料",
+    "logout": "退出",
+    "preferences": "偏好",
+    "theme": "主题",
+    "accentColor": "强调色",
+    "grayColor": "灰色",
+    "appearance": "外观",
+    "appearanceMode": {
+      "light": "浅色",
+      "dark": "深色",
+      "system": "跟随系统"
+    },
+    "panelBackground": "面板背景",
+    "panelBackgroundMode": {
+      "solid": "实色",
+      "translucent": "半透明"
+    },
+    "radius": "平台",
+    "scaling": "缩放",
+    "language": "语言",
+    "panel": "控制台"
+  },
+  "sidebar": {
+    "collapse": "收起侧栏",
+    "expand": "展开侧栏",
+    "openMenu": "打开菜单",
+    "logout": "退出",
+    "helpCenter": "帮助中心",
+    "settingsItem": "设置"
+  }
+}

package/src/languages/resources/zh/layout.json

@@ -0,0 +1,6 @@
+{
+  "layoutSwitcher": {
+    "show": "显示侧边栏",
+    "hide": "隐藏侧边栏"
+  }
+}

package/src/languages/resources/zh/preference.json

@@ -0,0 +1,49 @@
+{
+  "baseSwitcher": {
+    "default": "默认",
+    "ios": "iOS",
+    "android": "Android",
+    "windows": "Windows",
+    "linux": "Linux"
+  },
+  "preference": {
+    "theme": "主题",
+    "language": "语言",
+    "layout": "布局",
+    "preferences": "偏好"
+  },
+  "actions": {
+    "reset": "重置",
+    "saveTheme": "保存主题"
+  },
+  "labels": {
+    "appearance": "外观",
+    "accent": "强调色",
+    "gray": "灰色",
+    "radius": "圆角",
+    "scaling": "缩放",
+    "panelBackground": "面板背景",
+    "font": "字体",
+    "livePreview": "实时预览",
+    "previewBadge": "预览",
+    "previewSolid": "实心",
+    "previewSoft": "柔和",
+    "sampleInput": "示例输入",
+    "notifications": "通知",
+    "unsavedChanges": "有未保存更改",
+    "fontSystem": "系统",
+    "fontIbmPlex": "IBM Plex",
+    "fontNoto": "Noto Sans",
+    "fontSourceSans": "Source Sans 3",
+    "langEn": "English",
+    "langZh": "中文",
+    "langFr": "Français",
+    "colorAndAppearance": "外观与颜色",
+    "layoutAndType": "圆角与字体"
+  },
+  "sections": {
+    "language": {
+      "title": "语言"
+    }
+  }
+}