nfx-ui 0.20.0 → 0.22.0

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

@@ -0,0 +1,14 @@
+{
+  "themeSwitcher": {
+    "light": "浅色",
+    "dark": "深色",
+    "system": "跟随系统"
+  },
+  "baseSwitcher": {
+    "default": "其他",
+    "ios": "iOS",
+    "android": "Android",
+    "windows": "Windows",
+    "linux": "Linux"
+  }
+}

package/src/languages/types/components.ts

@@ -0,0 +1,4 @@
+/**
+ * 语言相关组件的 Props 类型。
+ */
+export type { LanguageProviderProps } from "@/providers/LanguageProvider";

package/src/languages/types/i18n.ts

@@ -0,0 +1,36 @@
+/**
+ * i18n 相关类型：文案包、资源结构、初始化选项等。
+ * i18n-related types: bundle, resources, init options.
+ */
+import type { LanguageEnum } from "./language";
+
+/** 单语言下的命名空间 → 文案对象。One language: namespace -> key-value bundle. */
+export type NamespaceBundle = Record<string, unknown>;
+
+/** 所有语言的资源：语言码 → 命名空间 → 文案。Resources: lng -> ns -> bundle. */
+export type Resources = Record<string, Record<string, NamespaceBundle>>;
+
+/** 命名空间映射：命名空间 key → 命名空间字符串（用于 ns 列表）。Name space key -> string. */
+export type NameSpacesMap = Record<string, string>;
+
+/** createI18nResources 返回值，含 RESOURCES / NAME_SPACES_MAP / NAME_SPACES。Return type of createI18nResources. */
+export interface CreateI18nResourcesResult {
+  RESOURCES: Resources;
+  NAME_SPACES_MAP: NameSpacesMap;
+  NAME_SPACES: string[];
+}
+
+/** 单条额外 bundle：命名空间 + 文案对象，由 initI18n 注入到 i18n。 */
+export interface ExtraBundleItem {
+  namespace: string;
+  bundle: Record<string, unknown>;
+}
+
+export type onLoadExtraBundles = (lng: LanguageEnum) => Promise<ExtraBundleItem | ExtraBundleItem[] | null | undefined>;
+
+/** initI18n 的选项。Options for initI18n. */
+export interface InitI18nOptions {
+  getBuiltinBundles: () => CreateI18nResourcesResult;
+  fallbackLng?: LanguageEnum;
+  onLoadExtraBundles?: onLoadExtraBundles;
+}

package/src/languages/types/index.ts

@@ -0,0 +1,6 @@
+/**
+ * 语言模块类型统一导出。All language module types re-exported.
+ */
+export * from "./language";
+export * from "./i18n";
+export * from "./components";

package/src/languages/types/language.ts

@@ -0,0 +1,4 @@
+/**
+ * 语言枚举与常量 — 从 enums 再导出，避免 languages 模块重复定义。
+ */
+export { LanguageEnum, DEFAULT_LANGUAGE, LANGUAGE_VALUES, Language } from "@/enums/language";

package/src/languages/utils/getLocalLanguage.ts

@@ -0,0 +1,9 @@
+/**
+ * 获取本地语言：PreferenceStore 为唯一真相。
+ */
+import { PreferenceStore } from "@/stores/preference";
+import { DEFAULT_LANGUAGE, type LanguageEnum } from "@/enums/language";
+
+export function getLocalLanguage(): LanguageEnum {
+  return PreferenceStore.getState().language ?? DEFAULT_LANGUAGE;
+}

package/src/languages/utils/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 语言模块工具函数。Language module utils.
+ */
+export { getLocalLanguage } from "./getLocalLanguage";
+export {
+  getLanguageStorage,
+  removeLanguageStorage,
+  setLanguageStorage,
+} from "./languageStorage";

package/src/languages/utils/languageStorage.ts

@@ -0,0 +1,20 @@
+/**
+ * Language helpers backed by PreferenceStore (CityPulso: no separate language-storage key).
+ */
+import type { Nilable } from "@/types/utils";
+
+import { LANGUAGE_VALUES, LanguageEnum } from "@/enums/language";
+import { PreferenceStore, setPreference } from "@/stores/preference";
+
+export function getLanguageStorage(): Nilable<LanguageEnum> {
+  const raw = PreferenceStore.getState().language;
+  return (LANGUAGE_VALUES as readonly string[]).includes(raw) ? raw : undefined;
+}
+
+export function setLanguageStorage(value: LanguageEnum): void {
+  setPreference({ language: value });
+}
+
+export function removeLanguageStorage(): void {
+  setPreference({ language: LanguageEnum.ZH });
+}

package/src/navigations/GuestRoute.tsx

@@ -0,0 +1,24 @@
+/**
+ * Guest-only outlet — redirects away when session + profile are already selected.
+ * Host supplies product home path via `redirectTo`.
+ */
+import { hasSelectedProfile, useAuthStore } from "@/stores/auth";
+import { Navigate, Outlet } from "react-router";
+
+export interface GuestRouteProps {
+  /** Where to send authenticated users with a selected profile (e.g. ROUTES.HOME). */
+  redirectTo: string;
+}
+
+export function GuestRoute({ redirectTo }: GuestRouteProps) {
+  const isAuthValid = useAuthStore((state) => state.isAuthValid);
+  const currentProfileId = useAuthStore((state) => state.currentProfileId);
+
+  if (isAuthValid && hasSelectedProfile(currentProfileId)) {
+    return <Navigate to={redirectTo} replace />;
+  }
+
+  return <Outlet />;
+}
+
+export default GuestRoute;

package/src/navigations/ProtectedRoute.tsx

@@ -0,0 +1,25 @@
+/**
+ * Auth-gated outlet — redirects to login when session/profile missing.
+ * Host supplies product login path via `redirectTo`.
+ */
+import { hasSelectedProfile, useAuthStore } from "@/stores/auth";
+import { Navigate, Outlet, useLocation } from "react-router";
+
+export interface ProtectedRouteProps {
+  /** Where to send unauthenticated users (e.g. ROUTES.LOGIN). */
+  redirectTo: string;
+}
+
+export function ProtectedRoute({ redirectTo }: ProtectedRouteProps) {
+  const location = useLocation();
+  const isAuthValid = useAuthStore((state) => state.isAuthValid);
+  const currentProfileId = useAuthStore((state) => state.currentProfileId);
+
+  if (!isAuthValid || !hasSelectedProfile(currentProfileId)) {
+    return <Navigate to={redirectTo} replace state={{ from: location }} />;
+  }
+
+  return <Outlet />;
+}
+
+export default ProtectedRoute;

package/src/navigations/index.ts

@@ -0,0 +1,2 @@
+export { default as GuestRoute, type GuestRouteProps } from "./GuestRoute";
+export { default as ProtectedRoute, type ProtectedRouteProps } from "./ProtectedRoute";

package/src/providers/DataProvider/index.tsx

@@ -0,0 +1,42 @@
+import type { IdentityRepositories } from "@/apis";
+import type { ReactNode } from "react";
+
+import { useEffect } from "react";
+import { ApiAssetRepository, ApiAuthRepository, IdentityRepositoriesContext, setIdentityRepositories } from "@/apis";
+import { scheduleAccessTokenRefresh } from "@/apis/authRefresh";
+import { AuthStore, subscribeAuthStorageSync } from "@/stores/auth";
+
+const defaultIdentityRepositories: IdentityRepositories = {
+  auth: new ApiAuthRepository(),
+  asset: new ApiAssetRepository(),
+};
+
+setIdentityRepositories(defaultIdentityRepositories);
+
+export interface DataProviderProps {
+  children: ReactNode;
+  repositories?: IdentityRepositories;
+}
+
+function AuthSessionBootstrap() {
+  useEffect(() => {
+    const accessToken = AuthStore.getState().accessToken;
+    if (accessToken) scheduleAccessTokenRefresh(accessToken);
+    return subscribeAuthStorageSync(() => {
+      const next = AuthStore.getState().accessToken;
+      if (next) scheduleAccessTokenRefresh(next);
+    });
+  }, []);
+  return null;
+}
+
+export function DataProvider({ children, repositories }: DataProviderProps) {
+  const value = repositories ?? defaultIdentityRepositories;
+  setIdentityRepositories(value);
+  return (
+    <IdentityRepositoriesContext.Provider value={value}>
+      <AuthSessionBootstrap />
+      {children}
+    </IdentityRepositoriesContext.Provider>
+  );
+}

package/src/providers/LanguageProvider/index.tsx

@@ -0,0 +1,64 @@
+/**
+ * Shared LanguageProvider — host passes product builtin bundles.
+ */
+import type { CreateI18nResourcesResult, ExtraBundleItem, onLoadExtraBundles } from "@/languages/types";
+import type { ReactNode } from "react";
+
+import { useEffect, useRef } from "react";
+
+import { DEFAULT_LANGUAGE, LANGUAGE_VALUES, LanguageEnum } from "@/enums/language";
+import i18n, { initI18n, toSupportedLanguage } from "@/languages/languages/i18n";
+import { PreferenceStore } from "@/stores/preference";
+
+export interface LanguageProviderProps {
+  children: ReactNode;
+  getBuiltinBundles: () => CreateI18nResourcesResult;
+  fallbackLng?: LanguageEnum;
+  onLoadExtraBundles?: onLoadExtraBundles;
+}
+
+function normalizeExtra(result: Awaited<ReturnType<onLoadExtraBundles>>): ExtraBundleItem[] {
+  if (result == null) return [];
+  return Array.isArray(result) ? result : [result];
+}
+
+const LanguageProvider = ({ children, getBuiltinBundles, fallbackLng, onLoadExtraBundles }: LanguageProviderProps) => {
+  const hasInitialized = useRef(false);
+  if (!hasInitialized.current) {
+    initI18n({
+      fallbackLng,
+      getBuiltinBundles,
+      onLoadExtraBundles: onLoadExtraBundles
+        ? async (lng) => {
+            const extra = normalizeExtra(await onLoadExtraBundles(lng));
+            return extra.length > 0 ? extra : null;
+          }
+        : undefined,
+    });
+    hasInitialized.current = true;
+  }
+
+  useEffect(() => {
+    const resolvedFallback = fallbackLng ?? DEFAULT_LANGUAGE;
+    const apply = (lng: LanguageEnum) => {
+      const current = toSupportedLanguage(i18n.language || resolvedFallback, resolvedFallback);
+      if (current !== lng) {
+        void i18n.changeLanguage(lng);
+      }
+    };
+
+    apply(PreferenceStore.getState().language);
+    return PreferenceStore.subscribe((state, prev) => {
+      if (state.language !== prev.language) {
+        apply(state.language);
+      }
+    });
+  }, [fallbackLng]);
+
+  return <>{children}</>;
+};
+
+LanguageProvider.displayName = "LanguageProvider";
+export default LanguageProvider;
+
+export { LANGUAGE_VALUES };

package/src/providers/ThemeProvider/index.tsx

@@ -0,0 +1,48 @@
+/**
+ * Shared Radix Theme provider — reads unified preference store.
+ * Host may pass document side-effects (e.g. favicon) via `onAppearanceChange`.
+ */
+import type { RadixAppearance } from "@/themes/radix";
+import type { ReactNode } from "react";
+
+import { useEffect } from "react";
+import { Theme } from "@radix-ui/themes";
+
+import { useResolvedAppearance } from "@/hooks/preference";
+import { usePreferenceStore } from "@/stores/preference";
+
+import "@/themes/index.css";
+
+export interface ThemeProviderProps {
+  children: ReactNode;
+  onAppearanceChange?: (appearance: RadixAppearance) => void;
+}
+
+const ThemeProvider = ({ children, onAppearanceChange }: ThemeProviderProps) => {
+  const theme = usePreferenceStore((s) => s.theme);
+  const resolvedAppearance = useResolvedAppearance();
+
+  useEffect(() => {
+    document.documentElement.dataset.appearance = resolvedAppearance;
+    onAppearanceChange?.(resolvedAppearance);
+  }, [onAppearanceChange, resolvedAppearance]);
+
+  return (
+    <Theme
+      appearance={resolvedAppearance}
+      accentColor={theme.accent}
+      grayColor={theme.gray}
+      radius={theme.radius}
+      scaling={theme.scaling}
+      panelBackground={theme.panelBackground}
+      hasBackground
+      className="radix-app-theme"
+      data-font-family={theme.fontFamily}
+    >
+      {children}
+    </Theme>
+  );
+};
+
+ThemeProvider.displayName = "ThemeProvider";
+export default ThemeProvider;

package/src/providers/index.ts

@@ -0,0 +1,6 @@
+export { default as ThemeProvider } from "./ThemeProvider";
+export type { ThemeProviderProps } from "./ThemeProvider";
+export { default as LanguageProvider } from "./LanguageProvider";
+export type { LanguageProviderProps } from "./LanguageProvider";
+export { DataProvider } from "./DataProvider";
+export type { DataProviderProps } from "./DataProvider";

package/src/schemas/index.ts

@@ -0,0 +1,3 @@
+export * from "./loginSchema";
+export * from "./signupSchema";
+export * from "./profileEditSchema";

package/src/schemas/loginSchema.ts

@@ -0,0 +1,32 @@
+import type { TFunction } from "i18next";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useForm } from "react-hook-form";
+import { useTranslation } from "react-i18next";
+import { z } from "zod";
+
+/** 登录表单；校验文案来自 host `pages.Account.Login` → `form.validation.*` */
+export function createLoginSchema(t: TFunction) {
+  return z.object({
+    email: z.string().min(1, t("form.validation.emailRequired")).email(t("form.validation.emailInvalid")),
+    password: z.string().min(1, t("form.validation.passwordRequired")),
+    rememberMe: z.boolean().optional(),
+  });
+}
+
+export type LoginFormData = z.infer<ReturnType<typeof createLoginSchema>>;
+
+export const useInitLoginForm = () => {
+  const { t } = useTranslation("pages.Account.Login");
+  const schema = createLoginSchema(t);
+
+  return useForm<LoginFormData>({
+    resolver: zodResolver(schema),
+    mode: "onChange",
+    defaultValues: {
+      email: "",
+      password: "",
+      rememberMe: false,
+    },
+  });
+};

package/src/schemas/profileEditSchema.ts

@@ -0,0 +1,72 @@
+import type { TFunction } from "i18next";
+import type { Profile } from "@/types";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { Language, LanguageEnum } from "@/enums";
+import { toDateInputValue } from "@/utils/time";
+import { safeStringable } from "@/utils/safe";
+import { useForm } from "react-hook-form";
+import { useTranslation } from "react-i18next";
+import { z } from "zod";
+
+export function buildUserProfileEditDefaults(profile: Profile.Response.ProfileBase): UserProfileEditFormData {
+  return {
+    profileLanguage: Language(profile.profileLanguage),
+    displayName: safeStringable(profile.displayName),
+    firstName: safeStringable(profile.firstName),
+    lastName: safeStringable(profile.lastName),
+    country: safeStringable(profile.country),
+    city: safeStringable(profile.city),
+    gender: safeStringable(profile.gender),
+    birthday: toDateInputValue(profile.birthday),
+    website: safeStringable(profile.website),
+    timezone: safeStringable(profile.timezone),
+    bio: safeStringable(profile.bio),
+  };
+}
+
+export function createUserProfileEditSchema(t: TFunction) {
+  const optionalString = (max: number) => z.string().trim().max(max, t("edit.validation.maxLength", { max }));
+
+  return z.object({
+    profileLanguage: z.enum(LanguageEnum),
+    displayName: optionalString(150),
+    firstName: optionalString(100),
+    lastName: optionalString(100),
+    country: optionalString(100),
+    city: optionalString(100),
+    gender: optionalString(100),
+    birthday: z
+      .string()
+      .trim()
+      .refine((value) => value === "" || /^\d{4}-\d{2}-\d{2}$/.test(value), t("edit.validation.birthdayInvalid")),
+    website: optionalString(100).refine((value) => !value || /^https?:\/\/.+/i.test(value), t("edit.validation.websiteInvalid")),
+    timezone: optionalString(100),
+    bio: optionalString(5000),
+  });
+}
+
+export type UserProfileEditFormData = z.infer<ReturnType<typeof createUserProfileEditSchema>>;
+
+export function createUserProfileBackgroundsFieldSchema(t: TFunction, maxImages: number) {
+  return z
+    .array(
+      z.object({
+        imageId: z.string().min(1),
+        sortOrder: z.number().int().nonnegative(),
+      }),
+    )
+    .max(maxImages, t("backgroundUpload.limitReached", { max: maxImages }));
+}
+
+export function useInitUserProfileEditForm(profile: Profile.Response.ProfileBase) {
+  const { t } = useTranslation("pages.User.Profile.Edit");
+  const schema = createUserProfileEditSchema(t);
+  const defaultValues = buildUserProfileEditDefaults(profile);
+
+  return useForm<UserProfileEditFormData>({
+    resolver: zodResolver(schema),
+    mode: "onChange",
+    defaultValues,
+  });
+}

package/src/schemas/signupSchema.ts

@@ -0,0 +1,48 @@
+import type { TFunction } from "i18next";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { normalizeVerificationCode, VERIFICATION_CODE_ALPHABET } from "@/utils/domain/verificationCode";
+import { useForm } from "react-hook-form";
+import { useTranslation } from "react-i18next";
+import { z } from "zod";
+
+const VERIFICATION_CODE_PATTERN = new RegExp(`^[${VERIFICATION_CODE_ALPHABET}]{6}$`);
+
+/** 注册表单；校验文案来自 host `pages.Account.Signup` → `validation.*` */
+export function createSignupSchema(t: TFunction) {
+  return z
+    .object({
+      email: z.string().min(1, t("validation.emailRequired")).email(t("validation.emailInvalid")),
+      verificationCode: z
+        .string()
+        .min(1, t("validation.codeRequired"))
+        .transform((value) => normalizeVerificationCode(value))
+        .pipe(z.string().regex(VERIFICATION_CODE_PATTERN, t("validation.codeInvalid"))),
+      password: z.string().min(1, t("validation.passwordRequired")).min(8, t("validation.passwordMin")),
+      confirmPassword: z.string().min(1, t("validation.confirmRequired")),
+      rememberMe: z.boolean().optional(),
+    })
+    .refine((data) => data.password === data.confirmPassword, {
+      message: t("validation.passwordMismatch"),
+      path: ["confirmPassword"],
+    });
+}
+
+export type SignupFormData = z.infer<ReturnType<typeof createSignupSchema>>;
+
+export const useInitSignupForm = () => {
+  const { t } = useTranslation("pages.Account.Signup");
+  const schema = createSignupSchema(t);
+
+  return useForm<SignupFormData>({
+    resolver: zodResolver(schema),
+    mode: "onChange",
+    defaultValues: {
+      email: "",
+      verificationCode: "",
+      password: "",
+      confirmPassword: "",
+      rememberMe: false,
+    },
+  });
+};