nfx-ui 0.20.0 → 0.22.0

package/src/hooks/auth.ts

@@ -0,0 +1,487 @@
+/**
+ * Auth hooks — 组件勿直接调 apis/auth
+ */
+import type { AxiosError } from "axios";
+import type { CurrentProfileResult, Login, Profile, Signup } from "@/types";
+
+import { useEffect } from "react";
+import { useMutation } from "@tanstack/react-query";
+import { useAuthRepository } from "@/apis/repositories";
+import { AUTH_EMAILS, AUTH_ME, AUTH_PHONES, AUTH_PROFILES } from "@/constants";
+import { AuthSignupPlatformEnum, LanguageEnum, ProfileKindEnum } from "@/enums";
+import { authEventEmitter, authEvents } from "@/events/auth";
+import { systemEventEmitter } from "@/events/system";
+import {
+  AuthStore,
+  clearAuth,
+  EMPTY_PROFILE_ID,
+  hasSelectedProfile,
+  setCurrentAccountId,
+  setCurrentProfileId,
+  setCurrentProfileKind,
+  setIsAuthValid,
+  setTokens,
+  useAuthStore,
+} from "@/stores/auth";
+import { ensureDeviceIdStorage } from "@/stores/system";
+import { getApiErrorMessage } from "@/utils/apiError";
+import { pickProfile } from "@/utils/domain/account";
+import { useUnifiedQuery } from "@/utils/factory";
+import { safeOr, safeStringable } from "@/utils/safe";
+import { useTranslation } from "react-i18next";
+
+export function useAuthQueryScope() {
+  const aID = useAuthStore((s) => s.currentAccountId);
+  const pID = useAuthStore((s) => s.currentProfileId);
+  const isAuthValid = useAuthStore((s) => s.isAuthValid);
+  const kind = useAuthStore((s) => s.currentProfileKind);
+  return { aID, pID, isAuthValid, kind, profileScope: kind };
+}
+
+function useLogoutOnAuthError(isError: boolean, aID: string) {
+  useEffect(() => {
+    if (!isError || !AuthStore.getState().isAuthValid) return;
+    if (!hasSelectedProfile(AuthStore.getState().currentProfileId)) return;
+    authEventEmitter.emit(authEvents.LOGOUT, aID);
+    clearAuth();
+  }, [isError, aID]);
+}
+
+export function useCurrentProfile(): CurrentProfileResult {
+  const auth = useAuthRepository();
+  const { aID, pID, isAuthValid, kind } = useAuthQueryScope();
+  const result = useUnifiedQuery(
+    ({ kind }: { kind: ProfileKindEnum }) => auth.GetCurrentFullAccountInformationWithProfile(kind),
+    AUTH_ME(aID, pID),
+    { kind },
+    { enabled: isAuthValid && hasSelectedProfile(pID) },
+  );
+  useLogoutOnAuthError(result.isError, aID);
+  return {
+    kind,
+    data: result.data,
+    profile: pickProfile(kind, result.data),
+    isLoading: result.isLoading,
+    isError: result.isError,
+    refetch: result.refetch,
+  } as CurrentProfileResult;
+}
+
+export const useSendVerificationCode = () => {
+  const auth = useAuthRepository();
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: (params: Signup.Request.SendVerificationCode) => auth.SendVerificationCode(params),
+    onSuccess: () => {
+      systemEventEmitter.showSuccess(t("sendVerificationCodeSuccess", { defaultValue: "Code sent" }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useSendVerificationCode] error"));
+    },
+  });
+};
+
+export const useSignupWithEmail = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: async ({
+      rememberMe,
+      ...params
+    }: {
+      rememberMe: boolean;
+    } & Omit<Signup.Request.SignupWithEmail, "deviceId">) =>
+      auth.SignupWithEmail({
+        ...params,
+        deviceId: await ensureDeviceIdStorage(),
+      }),
+    onSuccess: (result, variables) => {
+      if (!result?.accessToken) return;
+      setCurrentProfileId(result.profileId || EMPTY_PROFILE_ID);
+      setTokens(
+        {
+          accessToken: result.accessToken,
+          refreshToken: safeStringable(result.refreshToken),
+        },
+        { rememberMe: variables.rememberMe },
+      );
+      setIsAuthValid(true);
+      if (result.accountId) setCurrentAccountId(result.accountId);
+      if (result.profileId) {
+        setCurrentProfileKind(ProfileKindEnum.FORGER);
+        authEventEmitter.emit(authEvents.LOGIN_SUCCESS, result.accountId);
+      }
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useSignup] error"));
+    },
+  });
+};
+
+export const useLoginWithEmail = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: async ({ rememberMe, ...params }: { email: string; password: string; rememberMe: boolean }) =>
+      auth.LoginWithEmail({
+        ...params,
+        deviceId: await ensureDeviceIdStorage(),
+      }),
+    onSuccess: (result, variables) => {
+      if (!result?.accessToken) return;
+      setCurrentProfileId(EMPTY_PROFILE_ID);
+      setTokens(
+        {
+          accessToken: result.accessToken,
+          refreshToken: safeStringable(result.refreshToken),
+        },
+        { rememberMe: variables.rememberMe },
+      );
+      setIsAuthValid(true);
+      if (result.accountId) setCurrentAccountId(result.accountId);
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useLogin] error"));
+    },
+  });
+};
+
+export const useSelectProfile = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: async ({ profileId, kind }: { profileId: string; kind: Login.ProfileKind }) =>
+      auth.SelectProfile({
+        profileId,
+        kind,
+        deviceId: await ensureDeviceIdStorage(),
+      }),
+    onSuccess: (result, variables) => {
+      if (result?.accessToken) {
+        setTokens({
+          accessToken: result.accessToken,
+          refreshToken: safeStringable(result.refreshToken),
+        });
+        setCurrentProfileKind(variables.kind);
+        if (result.profileId) setCurrentProfileId(result.profileId);
+        authEventEmitter.emit(authEvents.LOGIN_SUCCESS, result.accountId);
+      }
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useSelectProfile] error"));
+    },
+  });
+};
+
+export const usePatchProfile = (options?: { silent?: boolean }) => {
+  const auth = useAuthRepository();
+  const { kind } = useAuthQueryScope();
+  const silent = safeOr(options?.silent, false);
+  const { t } = useTranslation("pages.User.Profile.Edit");
+  return useMutation({
+    mutationFn: (body: Profile.Request.PatchProfile) => auth.PatchProfile(kind, body),
+    onSuccess: () => {
+      if (!silent) systemEventEmitter.showSuccess(t("saveSuccess", { defaultValue: "Saved" }));
+      const aID = AuthStore.getState().currentAccountId;
+      authEventEmitter.invalidateProfiles({ aID, kind });
+    },
+    onError: (error: AxiosError) => {
+      if (!silent) systemEventEmitter.showError(getApiErrorMessage(error, "[usePatchProfile] error"));
+    },
+  });
+};
+
+export const useUpdateProfileSettings = () => {
+  const auth = useAuthRepository();
+  const { kind } = useAuthQueryScope();
+  return useMutation({
+    mutationFn: (body: Profile.Request.PatchProfileSettings) => auth.PatchProfileSettings(kind, body),
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useUpdateProfileSettings] error"));
+    },
+  });
+};
+
+export const useListProfiles = <K extends ProfileKindEnum>(kind: K) => {
+  const auth = useAuthRepository();
+  const { aID, isAuthValid } = useAuthQueryScope();
+  return useUnifiedQuery(
+    () => auth.ListProfiles(kind, { limit: 50, offset: 0 }),
+    AUTH_PROFILES(aID, kind),
+    undefined,
+    { enabled: isAuthValid && Boolean(aID) },
+  );
+};
+
+export const useCreateForgerProfile = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: (body: Login.Request.CreateForgerProfile) => auth.CreateForgerProfile(body),
+    onSuccess: () => {
+      const aID = AuthStore.getState().currentAccountId;
+      authEventEmitter.invalidateProfiles({ aID, kind: ProfileKindEnum.FORGER });
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useCreateForgerProfile] error"));
+    },
+  });
+};
+
+export const useCreateAuthorityProfile = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: (body: Login.Request.CreateAuthorityProfile) => auth.CreateAuthorityProfile(body),
+    onSuccess: () => {
+      const aID = AuthStore.getState().currentAccountId;
+      authEventEmitter.invalidateProfiles({ aID, kind: ProfileKindEnum.AUTHORITY });
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useCreateAuthorityProfile] error"));
+    },
+  });
+};
+
+export const useDeleteProfile = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: ({ kind, profileId }: { kind: ProfileKindEnum; profileId: string }) => auth.DeleteProfile(kind, profileId),
+    onSuccess: (_void, variables) => {
+      const aID = AuthStore.getState().currentAccountId;
+      authEventEmitter.invalidateProfiles({ aID, kind: variables.kind });
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useDeleteProfile] error"));
+    },
+  });
+};
+
+export const useGetGitHubAuthorizeUrl = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: () => auth.GetGitHubAuthorizeUrl(),
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useGetGitHubAuthorizeUrl] error"));
+    },
+  });
+};
+
+export const useLoginWithGitHub = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: async (params: { code: string; state: string; signupPlatform: AuthSignupPlatformEnum }) =>
+      auth.LoginWithGitHub({
+        ...params,
+        deviceId: await ensureDeviceIdStorage(),
+      }),
+    onSuccess: (result) => {
+      if (!result?.accessToken) return;
+      setCurrentProfileId(EMPTY_PROFILE_ID);
+      setTokens({
+        accessToken: result.accessToken,
+        refreshToken: safeStringable(result.refreshToken),
+      });
+      setIsAuthValid(true);
+      if (result.accountId) setCurrentAccountId(result.accountId);
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useLoginWithGitHub] error"));
+    },
+  });
+};
+
+export const useLinkGitHub = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: (params: Login.Request.LinkGitHub) => auth.LinkGitHub(params),
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useLinkGitHub] error"));
+    },
+  });
+};
+
+export const useUnlinkGitHub = () => {
+  const auth = useAuthRepository();
+  return useMutation({
+    mutationFn: () => auth.UnlinkGitHub(),
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useUnlinkGitHub] error"));
+    },
+  });
+};
+
+export const useConfirmProfileAvatar = () => {
+  const auth = useAuthRepository();
+  const { kind } = useAuthQueryScope();
+  return useMutation({
+    mutationFn: (body: Profile.Request.ConfirmProfileAvatar) => auth.ConfirmProfileAvatar(kind, body),
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useConfirmProfileAvatar] error"));
+    },
+  });
+};
+
+export const useClearProfileAvatar = () => {
+  const auth = useAuthRepository();
+  const { kind } = useAuthQueryScope();
+  return useMutation({
+    mutationFn: () => auth.ClearProfileAvatar(kind),
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useClearProfileAvatar] error"));
+    },
+  });
+};
+
+export const useListEmails = () => {
+  const auth = useAuthRepository();
+  const { aID, isAuthValid } = useAuthQueryScope();
+  return useUnifiedQuery(() => auth.ListEmails({ limit: 50, offset: 0 }), AUTH_EMAILS(aID), undefined, {
+    enabled: isAuthValid && Boolean(aID),
+  });
+};
+
+export const useListPhones = () => {
+  const auth = useAuthRepository();
+  const { aID, isAuthValid } = useAuthQueryScope();
+  return useUnifiedQuery(() => auth.ListPhones({ limit: 50, offset: 0 }), AUTH_PHONES(aID), undefined, {
+    enabled: isAuthValid && Boolean(aID),
+  });
+};
+
+export const useCreateEmail = () => {
+  const auth = useAuthRepository();
+  const accountId = AuthStore.getState().currentAccountId;
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: (body: Login.Request.CreateEmail) => auth.CreateEmail(body),
+    onSuccess: () => {
+      authEventEmitter.invalidateEmails(accountId);
+      systemEventEmitter.showSuccess(t("createEmailSuccess", { defaultValue: "Email added." }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useCreateEmail] error"));
+    },
+  });
+};
+
+export const useSendEmailVerificationCode = () => {
+  const auth = useAuthRepository();
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: ({ emailId, lang }: { emailId: string; lang?: LanguageEnum }) => auth.SendEmailVerificationCode(emailId, { lang }),
+    onSuccess: () => {
+      systemEventEmitter.showSuccess(t("sendVerificationCodeSuccess", { defaultValue: "Code sent" }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useSendEmailVerificationCode] error"));
+    },
+  });
+};
+
+export const useVerifyEmail = () => {
+  const auth = useAuthRepository();
+  const accountId = AuthStore.getState().currentAccountId;
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: ({ emailId, verificationCode }: { emailId: string; verificationCode: string }) =>
+      auth.VerifyEmail(emailId, { verificationCode }),
+    onSuccess: () => {
+      authEventEmitter.invalidateEmails(accountId);
+      systemEventEmitter.showSuccess(t("verifyEmailSuccess", { defaultValue: "Email verified." }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useVerifyEmail] error"));
+    },
+  });
+};
+
+export const useUpdateEmail = () => {
+  const auth = useAuthRepository();
+  const accountId = AuthStore.getState().currentAccountId;
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: ({ emailId, email }: { emailId: string; email: string }) => auth.UpdateEmail(emailId, { email }),
+    onSuccess: () => {
+      authEventEmitter.invalidateEmails(accountId);
+      systemEventEmitter.showSuccess(t("updateEmailSuccess", { defaultValue: "Email updated." }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useUpdateEmail] error"));
+    },
+  });
+};
+
+export const useSetPrimaryEmail = () => {
+  const auth = useAuthRepository();
+  const accountId = AuthStore.getState().currentAccountId;
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: (emailId: string) => auth.SetPrimaryEmail(emailId),
+    onSuccess: () => {
+      authEventEmitter.invalidateEmails(accountId);
+      authEventEmitter.emit(authEvents.UPDATE_ACCOUNT_SUCCESS, accountId);
+      systemEventEmitter.showSuccess(t("setPrimaryEmailSuccess", { defaultValue: "Primary email updated." }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useSetPrimaryEmail] error"));
+    },
+  });
+};
+
+export const useDeleteEmail = () => {
+  const auth = useAuthRepository();
+  const accountId = AuthStore.getState().currentAccountId;
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: (emailId: string) => auth.DeleteEmail(emailId),
+    onSuccess: () => {
+      authEventEmitter.invalidateEmails(accountId);
+      systemEventEmitter.showSuccess(t("deleteEmailSuccess", { defaultValue: "Email removed." }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useDeleteEmail] error"));
+    },
+  });
+};
+
+export const useSendChangePasswordVerificationCode = () => {
+  const auth = useAuthRepository();
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: (body: Login.Request.SendChangePasswordVerificationCode = {}) => auth.SendChangePasswordVerificationCode(body),
+    onSuccess: () => {
+      systemEventEmitter.showSuccess(t("sendVerificationCodeSuccess", { defaultValue: "Code sent" }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useSendChangePasswordVerificationCode] error"));
+    },
+  });
+};
+
+export const useChangePassword = () => {
+  const auth = useAuthRepository();
+  const { t } = useTranslation("hooks", { keyPrefix: "account" });
+  return useMutation({
+    mutationFn: (body: Login.Request.ChangePassword) => auth.ChangePassword(body),
+    onSuccess: () => {
+      systemEventEmitter.showSuccess(t("changePasswordSuccess", { defaultValue: "Password updated." }));
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useChangePassword] error"));
+    },
+  });
+};
+
+export const useConfirmProfileBackgrounds = () => {
+  const auth = useAuthRepository();
+  const { kind } = useAuthQueryScope();
+  return useMutation({
+    mutationFn: (body: Profile.Request.ConfirmProfileBackgrounds) => auth.ConfirmProfileBackgrounds(kind, body),
+    onSuccess: () => {
+      const aID = AuthStore.getState().currentAccountId;
+      authEventEmitter.emit(authEvents.UPDATE_ACCOUNT_SUCCESS, aID);
+    },
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useConfirmProfileBackgrounds] error"));
+    },
+  });
+};
+
+export { hasSelectedProfile, AuthStore, useAuthStore };
+export { LanguageEnum, AuthSignupPlatformEnum };

package/src/hooks/dom.ts

@@ -0,0 +1,78 @@
+import { useEffect, useRef, useState } from "react";
+
+/** 防抖值；用于搜索等输入。Debounced value for search inputs etc. */
+export function useDebouncedValue<T>(value: T, delayMs = 300): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => setDebounced(value), delayMs);
+    return () => window.clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debounced;
+}
+
+/** 鼠标悬停时，将垂直滚轮映射为 horizontal scroll。Maps vertical wheel delta to horizontal scroll while hovered. */
+export function useWheelHorizontalScroll<T extends HTMLElement>() {
+  const cleanupRef = useRef<Nullable<() => void>>(null);
+
+  const ref = (el: Nullable<T>) => {
+    cleanupRef.current?.();
+    cleanupRef.current = null;
+    if (!el) return;
+
+    const onWheel = (event: WheelEvent) => {
+      if (event.ctrlKey || event.metaKey) return;
+
+      const { scrollWidth, clientWidth, scrollLeft } = el;
+      if (scrollWidth <= clientWidth) return;
+
+      const delta = Math.abs(event.deltaY) >= Math.abs(event.deltaX) ? event.deltaY : event.deltaX;
+      if (delta === 0) return;
+
+      const maxScroll = scrollWidth - clientWidth;
+      const atStart = scrollLeft <= 0;
+      const atEnd = scrollLeft >= maxScroll - 1;
+
+      if ((delta > 0 && atEnd) || (delta < 0 && atStart)) return;
+
+      event.preventDefault();
+      el.scrollLeft += delta;
+    };
+
+    el.addEventListener("wheel", onWheel, { passive: false });
+    cleanupRef.current = () => el.removeEventListener("wheel", onWheel);
+  };
+
+  useEffect(
+    () => () => {
+      cleanupRef.current?.();
+      cleanupRef.current = null;
+    },
+    [],
+  );
+
+  return ref;
+}
+
+const DESKTOP_VIEWPORT_MQ = "(min-width: 901px)";
+
+/** 桌面端锁定 document 滚动（固定视口详情页）；移动端不锁定。Lock document scroll on desktop fixed-viewport detail pages only. */
+export function useLockDocumentScrollOnDesktop() {
+  useEffect(() => {
+    const mq = window.matchMedia(DESKTOP_VIEWPORT_MQ);
+    const html = document.documentElement;
+    const prev = html.style.overflow;
+
+    const apply = () => {
+      html.style.overflow = mq.matches ? "hidden" : prev || "";
+    };
+
+    apply();
+    mq.addEventListener("change", apply);
+    return () => {
+      mq.removeEventListener("change", apply);
+      html.style.overflow = prev;
+    };
+  }, []);
+}

package/src/hooks/index.ts

@@ -0,0 +1,17 @@
+export * from "./preference";
+export * from "../utils/factory/hooks";
+export * from "./auth";
+export * from "./asset";
+export * from "./dom";
+export {
+  getLanguageDisplayName,
+  useLanguageLabel,
+  getBaseDisplayName,
+  useBaseLabel,
+  getLayoutDisplayName,
+  useLayoutLabel,
+  getPreferenceDisplayName,
+  usePreferenceLabel,
+  getThemeDisplayName,
+  useThemeLabel,
+} from "@/languages/hooks";

package/src/hooks/preference.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared preference hooks — appearance resolve + host-configured server sync.
+ */
+import type { PreferencePatch, ResolvedPreference } from "@/stores/preference";
+import type { RadixAppearance } from "@/themes/radix";
+
+import { useEffect, useRef, useState } from "react";
+
+import { AppearanceEnum } from "@/enums/theme";
+import {
+  PreferenceStore,
+  replacePreference,
+  setPreference,
+  usePreferenceStore,
+} from "@/stores/preference";
+import { readSystemRadixAppearance, resolveRadixAppearance } from "@/themes/radix";
+
+/** 将 theme.appearance（含 system）解析为当前生效的 Radix light|dark，并在跟随系统时响应 OS 切换。 */
+export function useResolvedAppearance(): RadixAppearance {
+  const appearance = usePreferenceStore((s) => s.theme.appearance);
+  const [systemAppearance, setSystemAppearance] = useState<RadixAppearance>(readSystemRadixAppearance);
+
+  useEffect(() => {
+    if (appearance !== AppearanceEnum.SYSTEM) return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => setSystemAppearance(mq.matches ? AppearanceEnum.DARK : AppearanceEnum.LIGHT);
+    onChange();
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, [appearance]);
+
+  return appearance === AppearanceEnum.SYSTEM ? systemAppearance : resolveRadixAppearance(appearance);
+}
+
+function patchHasServerField(patch: PreferencePatch): boolean {
+  if (patch.language !== undefined) return true;
+  if (patch.theme && Object.keys(patch.theme).length > 0) return true;
+  if (patch.layoutMode !== undefined) return true;
+  if (patch.dashboardBackground !== undefined) return true;
+  return false;
+}
+
+type PreferenceSyncFn = (state: ResolvedPreference) => void | Promise<void>;
+let preferenceSync: PreferenceSyncFn | undefined;
+
+/** Hosts register persistence here — no CityPulso API. */
+export function configurePreferenceSync(fn: PreferenceSyncFn | undefined): void {
+  preferenceSync = fn;
+}
+
+/** 登录后用服务端偏好覆盖本地；无服务端数据时保留本地 persist。 */
+export const useApplyPreferenceOnLoad = (args: {
+  isAuthValid: boolean;
+  applyKey?: string | null;
+  serverPreference?: ResolvedPreference | null;
+}) => {
+  const { isAuthValid, applyKey, serverPreference } = args;
+  const lastAppliedKey = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!isAuthValid || !serverPreference) return;
+    const key = applyKey ?? "default";
+    if (lastAppliedKey.current === key) return;
+    lastAppliedKey.current = key;
+    replacePreference(serverPreference);
+  }, [isAuthValid, applyKey, serverPreference]);
+};
+
+export const useSyncPreference = () => {
+  const syncPreference = (patch: PreferencePatch) => {
+    setPreference(patch);
+    if (!patchHasServerField(patch)) return;
+    void Promise.resolve(preferenceSync?.(PreferenceStore.getState())).catch((error) => {
+      console.error("Failed to sync preference:", error);
+    });
+  };
+
+  return { syncPreference };
+};

package/src/languages/hooks/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 语言模块 Hooks：返回 { getXxxDisplayName }，便于扩展；getXxxDisplayName 可传给 SlideDownSwitcher getDisplayName。
+ * Language hooks: return { getXxxDisplayName } for extensibility; pass to SlideDownSwitcher getDisplayName.
+ */
+export { getLanguageDisplayName, useLanguageLabel, getBaseDisplayName, useBaseLabel } from "./useLanguageLabel";
+export { getLayoutDisplayName, useLayoutLabel } from "./useLayoutLabel";
+export { getPreferenceDisplayName, usePreferenceLabel } from "./usePreferenceLabel";
+export { getThemeDisplayName, useThemeLabel } from "./useThemeLabel";