create-secra 0.1.5 → 0.1.7

package/antd-adapter-template/packages/sdk/src/components/i18n-switch-dropdown.tsx

@@ -0,0 +1,139 @@
+import { TranslationOutlined } from "@ant-design/icons";
+import { Button, Dropdown, Space, type MenuProps } from "antd";
+import { useLocale } from "@vlian/framework/core";
+import { LocaleSwitch } from "@vlian/framework/components";
+import { useCallback, useEffect, useMemo } from "react";
+import type { SdkLang } from "../i18n/index.js";
+import { cache, type StorageStrategy } from "../storage/index.js";
+
+const LANG_LABEL: Record<SdkLang, string> = {
+  "en-US": "English",
+  "zh-CN": "简体中文",
+};
+
+const isSdkLang = (lang: string): lang is SdkLang => {
+  return lang === "en-US" || lang === "zh-CN";
+};
+
+const normalizeLang = (lang?: string): SdkLang => {
+  if (lang === "en-US") {
+    return "en-US";
+  }
+  return "zh-CN";
+};
+
+export interface I18nSwitchDropdownProps {
+  storageType?: StorageStrategy;
+  storageKey?: string;
+}
+
+export const I18nSwitchDropdown = ({
+  storageType = "localstorage",
+  storageKey = "sdk-lang",
+}: I18nSwitchDropdownProps) => {
+  const { setLocale } = useLocale();
+
+  useEffect(() => {
+    if (storageType !== "indexeddb") {
+      return;
+    }
+
+    let disposed = false;
+
+    const restoreLang = async () => {
+      const nextLang = await cache.indexeddb.get<SdkLang>(storageKey);
+      if (disposed || !nextLang || !isSdkLang(nextLang)) {
+        return;
+      }
+      setLocale(nextLang);
+    };
+
+    void restoreLang();
+    return () => {
+      disposed = true;
+    };
+  }, [setLocale, storageKey, storageType]);
+
+  const persistence = useMemo(() => {
+    if (typeof window === "undefined") {
+      return { enabled: false, key: storageKey };
+    }
+
+    if (storageType === "localstorage") {
+      return { key: storageKey, storage: window.localStorage };
+    }
+
+    if (storageType === "sessionStorage") {
+      return { key: storageKey, storage: window.sessionStorage };
+    }
+
+    return { enabled: false, key: storageKey };
+  }, [storageKey, storageType]);
+
+  const handleChange = useCallback(
+    (locale: SdkLang) => {
+      if (storageType === "indexeddb") {
+        void cache.indexeddb.set(storageKey, locale, -1);
+      }
+    },
+    [storageKey, storageType],
+  );
+
+  const renderDropdown = useCallback(
+    ({
+      locale,
+      locales,
+      setLocale: setLocaleValue,
+      isChanging,
+      labels,
+    }: {
+      locale: SdkLang;
+      locales: SdkLang[];
+      setLocale: (nextLocale: SdkLang) => void;
+      isChanging: boolean;
+      labels: Record<SdkLang, string>;
+    }) => {
+      const menu: MenuProps = {
+        selectedKeys: [normalizeLang(locale)],
+        onClick: ({ key }) => {
+          if (!isSdkLang(key)) {
+            return;
+          }
+          setLocaleValue(key);
+        },
+        items: locales.map((item) => ({
+          key: item,
+          label: (
+            <Space size={8}>
+              {labels[item]}
+            </Space>
+          ),
+        })),
+      };
+
+      return (
+        <Dropdown menu={menu} trigger={["click"]}>
+          <Button
+            type="text"
+            size="small"
+            shape={"circle"}
+            aria-label="切换语言"
+            loading={isChanging}
+          >
+            <TranslationOutlined />
+          </Button>
+        </Dropdown>
+      );
+    },
+    [],
+  );
+
+  return (
+    <LocaleSwitch
+      labels={LANG_LABEL}
+      persistence={persistence}
+      onChange={handleChange}
+      render={renderDropdown}
+    />
+  );
+};

package/antd-adapter-template/packages/sdk/src/components/index.ts

@@ -0,0 +1,2 @@
+export * from "./theme-switch-dropdown.js";
+export * from "./i18n-switch-dropdown.js";

package/antd-adapter-template/packages/sdk/src/components/theme-switch-dropdown.tsx

@@ -0,0 +1,131 @@
+import {
+  SunOutlined,
+  DesktopOutlined,
+  MoonOutlined,
+} from "@ant-design/icons";
+import { Button, Dropdown, Space, type MenuProps } from "antd";
+import { ThemeSwitch } from "@vlian/framework/components";
+import { useCallback, useEffect, useMemo } from "react";
+import { cache, type StorageStrategy } from "../storage/index.js";
+import { useThemeSwitch, type ThemeMode } from "../theme/index.js";
+
+const MODE_ICON: Record<ThemeMode, React.ReactNode> = {
+  light: <SunOutlined />,
+  dark: <MoonOutlined />,
+  system: <DesktopOutlined />,
+};
+
+export interface ThemeSwitchDropdownProps {
+  storageType?: StorageStrategy;
+  storageKey?: string;
+}
+
+export const ThemeSwitchDropdown = ({
+  storageType = "localstorage",
+  storageKey = "theme-mode",
+}: ThemeSwitchDropdownProps) => {
+  const { setThemeMode } = useThemeSwitch();
+
+  useEffect(() => {
+    if (storageType !== "indexeddb") {
+      return;
+    }
+
+    let disposed = false;
+
+    const restoreThemeMode = async () => {
+      const nextMode = await cache.indexeddb.get<ThemeMode>(storageKey);
+      if (disposed || !nextMode) {
+        return;
+      }
+      if (nextMode === "light" || nextMode === "dark" || nextMode === "system") {
+        setThemeMode(nextMode);
+      }
+    };
+
+    void restoreThemeMode();
+    return () => {
+      disposed = true;
+    };
+  }, [setThemeMode, storageKey, storageType]);
+
+  const persistence = useMemo(() => {
+    if (typeof window === "undefined") {
+      return { enabled: false, key: storageKey };
+    }
+
+    if (storageType === "localstorage") {
+      return { key: storageKey, storage: window.localStorage };
+    }
+
+    if (storageType === "sessionStorage") {
+      return { key: storageKey, storage: window.sessionStorage };
+    }
+
+    return { enabled: false, key: storageKey };
+  }, [storageKey, storageType]);
+
+  const handleChange = useCallback(
+    (nextMode: ThemeMode) => {
+      if (storageType === "indexeddb") {
+        void cache.indexeddb.set(storageKey, nextMode, -1);
+      }
+    },
+    [storageKey, storageType],
+  );
+
+  const renderDropdown = useCallback(
+    ({
+      mode,
+      modes,
+      labels,
+      setMode,
+    }: {
+      mode: ThemeMode;
+      modes: ThemeMode[];
+      labels: Record<ThemeMode, string>;
+      setMode: (nextMode: ThemeMode) => void;
+    }) => {
+      const menu: MenuProps = {
+        selectedKeys: [mode],
+        onClick: ({ key }) => {
+          if (key !== "light" && key !== "dark" && key !== "system") {
+            return;
+          }
+          setMode(key as ThemeMode);
+        },
+        items: modes.map((item) => ({
+          key: item,
+          label: (
+            <Space size={8}>
+              {MODE_ICON[item]}
+              {labels[item]}
+            </Space>
+          ),
+        })),
+      };
+
+      return (
+        <Dropdown menu={menu} trigger={["click"]}>
+          <Button type="text" size="small" shape={"circle"} aria-label="切换主题">
+            {MODE_ICON[mode]}
+          </Button>
+        </Dropdown>
+      );
+    },
+    [],
+  );
+
+  return (
+    <ThemeSwitch
+      labels={{
+        light: "浅色",
+        dark: "深色",
+        system: "跟随系统",
+      }}
+      persistence={persistence}
+      onChange={handleChange}
+      render={renderDropdown}
+    />
+  );
+};

package/antd-adapter-template/packages/sdk/src/hooks/auth/core.ts

@@ -0,0 +1,101 @@
+import type { StorageStrategy } from "../../storage/index.js";
+
+/**
+ * 默认 access token 存储键。
+ * 业务方可通过 AuthTokenOptions.key 覆盖该键以复用同一套读写逻辑。
+ */
+export const AUTH_TOKEN_KEY = "user:token";
+
+/**
+ * 统一的 access token 存储键（业务登录场景）。
+ */
+export const ACCESS_TOKEN_KEY = "auth-access-token";
+
+/**
+ * 统一的 refresh token 存储键（业务登录场景）。
+ */
+export const REFRESH_TOKEN_KEY = "auth-refresh-token";
+
+/**
+ * 默认 token 存储介质。
+ * 当前默认使用 localstorage，确保页面刷新后仍可读取。
+ */
+export const AUTH_TOKEN_STORAGE: StorageStrategy = "localstorage";
+
+const SDK_STORAGE_PREFIX = "secra-admin-sdk";
+
+/**
+ * Token 读写配置项。
+ * - key: 自定义 token 对应的存储 key
+ * - strategy: 存储策略（localstorage / sessionStorage / indexeddb）
+ */
+export interface AuthTokenOptions {
+  key?: string;
+  strategy?: StorageStrategy;
+}
+
+/**
+ * 归一化 token 配置，补齐默认值，避免调用方重复传参。
+ */
+export const resolveAuthTokenOptions = (
+  options?: AuthTokenOptions,
+): Required<AuthTokenOptions> => ({
+  key: options?.key || AUTH_TOKEN_KEY,
+  strategy: options?.strategy || AUTH_TOKEN_STORAGE,
+});
+
+type SyncStorageStrategy = Exclude<StorageStrategy, "indexeddb">;
+type SerializedStoragePayload = {
+  data?: unknown;
+  exp?: number;
+  sign?: string;
+};
+
+const getSyncStorageByStrategy = (strategy: SyncStorageStrategy): Storage | null => {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  return strategy === "sessionStorage" ? window.sessionStorage : window.localStorage;
+};
+
+const resolveRawStoredValue = (storage: Storage, key: string): string | null => {
+  const prefixedKey = `${SDK_STORAGE_PREFIX}:${key}`;
+  return storage.getItem(prefixedKey) ?? storage.getItem(key);
+};
+
+const parseStoredToken = (rawValue: string): string | null => {
+  try {
+    const payload = JSON.parse(rawValue) as SerializedStoragePayload;
+    const exp = payload.exp ?? -1;
+    if (exp !== -1 && Date.now() > exp) {
+      return null;
+    }
+    return typeof payload.data === "string" && payload.data ? payload.data : null;
+  } catch {
+    return rawValue || null;
+  }
+};
+
+/**
+ * 同步判断当前是否已登录。
+ * 仅支持 localstorage / sessionStorage；indexeddb 回退为 false。
+ */
+export const isAuthenticatedSync = (options?: AuthTokenOptions): boolean => {
+  const { key, strategy } = resolveAuthTokenOptions(options);
+  if (strategy === "indexeddb") {
+    return false;
+  }
+
+  const storage = getSyncStorageByStrategy(strategy);
+  if (!storage) {
+    return false;
+  }
+
+  const rawValue = resolveRawStoredValue(storage, key);
+  if (!rawValue) {
+    return false;
+  }
+
+  return Boolean(parseStoredToken(rawValue));
+};
+

package/antd-adapter-template/packages/sdk/src/hooks/auth/index.ts

@@ -0,0 +1,139 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { cache } from "../../storage/index.js";
+import {
+  ACCESS_TOKEN_KEY,
+  AUTH_TOKEN_KEY,
+  AUTH_TOKEN_STORAGE,
+  REFRESH_TOKEN_KEY,
+  type AuthTokenOptions,
+  isAuthenticatedSync,
+  resolveAuthTokenOptions,
+} from "./core.js";
+
+/**
+ * 读取 token（非 hooks 模式）。
+ *
+ * @param options 可选配置：自定义 key 和存储策略。
+ * @returns Promise<string | null> 返回 token 字符串；不存在时返回 null。
+ */
+export const getToken = async (options?: AuthTokenOptions): Promise<string | null> => {
+  const { key, strategy } = resolveAuthTokenOptions(options);
+  return cache[strategy].get<string>(key);
+};
+
+/**
+ * 写入 token（非 hooks 模式）。
+ *
+ * @param token 要持久化的 token 字符串。
+ * @param options 可选配置：自定义 key 和存储策略。
+ * @returns Promise<void>
+ */
+export const setToken = async (token: string, options?: AuthTokenOptions): Promise<void> => {
+  const { key, strategy } = resolveAuthTokenOptions(options);
+  await cache[strategy].set<string>(key, token);
+};
+
+/**
+ * 删除 token（非 hooks 模式）。
+ *
+ * @param options 可选配置：自定义 key 和存储策略。
+ * @returns Promise<void>
+ */
+export const removeToken = async (options?: AuthTokenOptions): Promise<void> => {
+  const { key, strategy } = resolveAuthTokenOptions(options);
+  await cache[strategy].remove(key);
+};
+
+/**
+ * useToken 返回结果。
+ * - token: 当前内存态 token
+ * - loading: 首次加载或手动刷新时的读取状态
+ * - getToken: 仅读取存储并同步到内存态
+ * - setToken: 写入存储并同步到内存态
+ * - removeToken: 删除存储并清空内存态
+ * - refresh: 强制刷新 token，通常用于登录态恢复场景
+ */
+export interface UseTokenResult {
+  token: string | null;
+  loading: boolean;
+  getToken: () => Promise<string | null>;
+  setToken: (value: string) => Promise<void>;
+  removeToken: () => Promise<void>;
+  refresh: () => Promise<string | null>;
+}
+
+/**
+ * Token 管理 Hook（hooks 模式）。
+ *
+ * 提供 token 的读取、写入、删除与刷新能力，并维护组件内可响应的 token 状态。
+ * 在组件挂载后会自动触发一次 refresh()，用于从持久化存储恢复 token。
+ *
+ * @param options 可选配置：自定义 key 和存储策略。
+ * @returns UseTokenResult token 状态与一组可复用操作方法。
+ */
+export const useToken = (options?: AuthTokenOptions): UseTokenResult => {
+  const [token, setTokenState] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const resolvedOptions = useMemo(
+    () => resolveAuthTokenOptions(options),
+    [options?.key, options?.strategy],
+  );
+
+  /**
+   * 从存储读取 token，并同步到 hook 内部状态。
+   */
+  const readToken = useCallback(async () => {
+    const value = await cache[resolvedOptions.strategy].get<string>(resolvedOptions.key);
+    setTokenState(value);
+    return value;
+  }, [resolvedOptions.key, resolvedOptions.strategy]);
+
+  /**
+   * 主动刷新 token：
+   * 1. 设置 loading=true
+   * 2. 读取并同步 token
+   * 3. 结束后恢复 loading=false
+   */
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    try {
+      return await readToken();
+    } finally {
+      setLoading(false);
+    }
+  }, [readToken]);
+
+  /**
+   * 持久化写入 token，并立即更新内存态，避免界面等待下一次读取。
+   */
+  const persistToken = useCallback(
+    async (value: string) => {
+      await cache[resolvedOptions.strategy].set<string>(resolvedOptions.key, value);
+      setTokenState(value);
+    },
+    [resolvedOptions.key, resolvedOptions.strategy],
+  );
+
+  /**
+   * 删除持久化 token，并同步清空内存态。
+   */
+  const clearToken = useCallback(async () => {
+    await cache[resolvedOptions.strategy].remove(resolvedOptions.key);
+    setTokenState(null);
+  }, [resolvedOptions.key, resolvedOptions.strategy]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  return {
+    token,
+    loading,
+    getToken: readToken,
+    setToken: persistToken,
+    removeToken: clearToken,
+    refresh,
+  };
+};
+export * from "./core.js";
+export * from "./with-auth.js";

package/antd-adapter-template/packages/sdk/src/hooks/auth/with-auth.tsx

@@ -0,0 +1,41 @@
+import type { ComponentType, FC } from "react";
+import { Navigate } from "react-router-dom";
+import { logger } from "@vlian/framework/utils";
+import { ACCESS_TOKEN_KEY, REFRESH_TOKEN_KEY, isAuthenticatedSync, type AuthTokenOptions } from "./core.js";
+
+export interface WithAuthOptions {
+  tokenOptions?: AuthTokenOptions;
+  refreshTokenOptions?: AuthTokenOptions | false;
+}
+
+const DEFAULT_LOGIN_PATH = "/auth/login";
+
+export const withAuth = <P extends object>(
+  WrappedComponent: ComponentType<P>,
+  options?: WithAuthOptions,
+): FC<P> => {
+  const accessTokenOptions = options?.tokenOptions ?? { key: ACCESS_TOKEN_KEY };
+  const refreshTokenOptions = options?.refreshTokenOptions ?? { key: REFRESH_TOKEN_KEY };
+  const getNow =
+    typeof performance !== "undefined" && typeof performance.now === "function"
+      ? () => performance.now()
+      : () => Date.now();
+
+  const AuthenticatedComponent: FC<P> = (props) => {
+    const start = getNow();
+    const hasAccessToken = isAuthenticatedSync(accessTokenOptions);
+    const hasRefreshToken =
+      refreshTokenOptions === false ? false : isAuthenticatedSync(refreshTokenOptions);
+    const end = getNow();
+    logger.debug("[withAuth] isAuthenticatedSync cost(ms)", Number((end - start).toFixed(2)));
+    const isLogin = hasAccessToken || hasRefreshToken;
+    if (isLogin) {
+      return <WrappedComponent {...props} />;
+    }
+    return <Navigate to={DEFAULT_LOGIN_PATH} />;
+  };
+
+  AuthenticatedComponent.displayName = `withAuth(${WrappedComponent.displayName || WrappedComponent.name || "Component"})`;
+
+  return AuthenticatedComponent;
+};

package/antd-adapter-template/packages/sdk/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./auth/index.js";