nfx-ui 0.20.0 → 0.22.0

package/src/constants/querykeys.ts

@@ -0,0 +1,78 @@
+/**
+ * 通用 React Query key 工厂（公用包层）
+ * Universal React Query key factories for shared use.
+ *
+ * @example
+ * ```ts
+ * import { createListKey, createItemKey } from "@/constants";
+ *
+ * const CATALOG_CATEGORY_LIST = createListKey("catalog", "category");
+ * const CATALOG_CATEGORY = createItemKey("catalog", "category");
+ *
+ * useQuery({ queryKey: CATALOG_CATEGORY_LIST, queryFn: ... });
+ * useQuery({ queryKey: CATALOG_CATEGORY(id), queryFn: ... });
+ * ```
+ */
+import type { QueryKey } from "@tanstack/react-query";
+import type { ItemKeyChainable } from "./query.itemkeys";
+import type { ListKeyChainable } from "./query.listkeys";
+
+import { createItemKey } from "./query.itemkeys";
+import { createListKey } from "./query.listkeys";
+
+/** 含 list / item 且可链式 withPrefix 的 bundle 类型 */
+type QueryKeysBundle = {
+  list: ListKeyChainable;
+  item: ItemKeyChainable;
+  withPrefix(...prefix: unknown[]): QueryKeysBundle;
+};
+
+function createQueryKeysBundle(list: ListKeyChainable, item: ItemKeyChainable): QueryKeysBundle {
+  return {
+    list,
+    item,
+    withPrefix(...prefix: unknown[]) {
+      return createQueryKeysBundle(list.withPrefix(...prefix), item.withPrefix(...prefix));
+    },
+  };
+}
+
+/**
+ * 创建自定义 query key（任意片段，用于 stats 等）
+ * Creates a custom query key from arbitrary segments (e.g. for stats).
+ *
+ * @param segments - 任意片段（字符串或其它）。Arbitrary segments (strings or other).
+ * @returns 由片段组成的 query key。Query key composed of the segments.
+ * @example
+ * ```ts
+ * const key = createKey("catalog", "stats", "category", "count");
+ * * key => ["catalog", "stats", "category", "count"]
+ * ```
+ */
+function createKey(...segments: unknown[]): QueryKey {
+  return segments;
+}
+
+/**
+ * 根据同一 domain + subDomain 生成 list key 与 item key 工厂
+ * Returns both list key and item key factory for the given domain and subDomain.
+ *
+ * @param domain - 域名。Domain name (e.g. "catalog", "auth").
+ * @param subDomain - 子域。Sub-domain (e.g. "category", "product").
+ * @returns 含 list、item 及 withPrefix 的 bundle，可链式加前缀。Bundle with list, item, and chainable withPrefix.
+ * @example
+ * ```ts
+ * const { list, item } = createQueryKeys("catalog", "category");
+ * * list => ["catalog", "list", "category"]
+ * * item("id-1") => ["catalog", "item", "category", "id-1"]
+ * const withApi = createQueryKeys("catalog", "category").withPrefix("api");
+ * * withApi.list => ["api", "catalog", "list", "category"]
+ * * withApi.item("id-1") => ["api", "catalog", "item", "category", "id-1"]
+ * ```
+ */
+function createQueryKeys(domain: string, subDomain: string): QueryKeysBundle {
+  return createQueryKeysBundle(createListKey(domain, subDomain), createItemKey(domain, subDomain));
+}
+
+export { createKey, createQueryKeys };
+export type { QueryKeysBundle };

package/src/elements/index.ts

@@ -0,0 +1,2 @@
+/** UI elements by domain. Keep this barrel empty until a real cross-product element exists. */
+export {};

package/src/enums/auth.ts

@@ -0,0 +1,81 @@
+/**
+ * Auth 枚举，镜像 Identity 后端。
+ * ProfileKindEnum 与 JWT profile_scope 共用 wire 值 "forger" | "authority"。
+ * 角色不在 JWT；能力门控按纯成员判定（hasRole / hasAnyRole）。
+ */
+
+import type { Nilable } from "@/types";
+
+import { safeArray, safeEnum } from "@/utils/safe";
+
+export function hasRole<T>(role: T, roles: Nilable<readonly T[]>): boolean {
+  return safeArray(roles).includes(role);
+}
+
+export function hasAnyRole<T>(roles: Nilable<readonly T[]>, ...candidates: T[]): boolean {
+  return candidates.some((role) => hasRole(role, roles));
+}
+
+/** 与后端 ProfileKind / profile_scope 一致。 */
+export enum ProfileKindEnum {
+  FORGER = "forger",
+  AUTHORITY = "authority",
+}
+
+export const DEFAULT_PROFILE_KIND = ProfileKindEnum.FORGER;
+export const PROFILE_KIND_VALUES = Object.values(ProfileKindEnum);
+export const ProfileKind = (value: Nilable<string>) => safeEnum(value, PROFILE_KIND_VALUES, DEFAULT_PROFILE_KIND);
+
+/** 普通档 forger_roles。 */
+export enum AuthForgerRoleEnum {
+  FORGER = "forger",
+}
+export const DEFAULT_AUTH_FORGER_ROLE = AuthForgerRoleEnum.FORGER;
+export const AUTH_FORGER_ROLE_VALUES = Object.values(AuthForgerRoleEnum);
+export const AuthForgerRole = (value: Nilable<string>) => safeEnum(value, AUTH_FORGER_ROLE_VALUES, DEFAULT_AUTH_FORGER_ROLE);
+
+/** 管理档 authority_roles。角色不是包含关系。 */
+export enum AuthAuthorityRoleEnum {
+  AUDITOR = "auditor",
+  ADMINISTRATOR = "administrator",
+  OWNER = "owner",
+}
+
+export const DEFAULT_AUTH_AUTHORITY_ROLE = AuthAuthorityRoleEnum.ADMINISTRATOR;
+export const AUTH_AUTHORITY_ROLE_VALUES = Object.values(AuthAuthorityRoleEnum);
+export const AuthAuthorityRole = (value: Nilable<string>) =>
+  safeEnum(value, AUTH_AUTHORITY_ROLE_VALUES, DEFAULT_AUTH_AUTHORITY_ROLE);
+
+/** 可通过 UI/API 分配的权限角色（owner 仅允许数据库手动变更）。 */
+export const UI_ASSIGNABLE_AUTH_AUTHORITY_ROLES = AUTH_AUTHORITY_ROLE_VALUES.filter(
+  (role): role is Exclude<AuthAuthorityRoleEnum, AuthAuthorityRoleEnum.OWNER> => role !== AuthAuthorityRoleEnum.OWNER,
+);
+
+export type ProfileRole = AuthForgerRoleEnum | AuthAuthorityRoleEnum;
+
+export enum AuthSignupPlatformEnum {
+  NFXIDENTITY = "nfxidentity",
+  NFXNEWS = "nfxnews",
+  NFXSTORAGES = "nfxstorages",
+  NFXVAULT = "nfxvault",
+}
+export const DEFAULT_AUTH_SIGNUP_PLATFORM = AuthSignupPlatformEnum.NFXIDENTITY;
+export const AUTH_SIGNUP_PLATFORM_VALUES = Object.values(AuthSignupPlatformEnum);
+export const AuthSignupPlatform = (value: Nilable<string>) =>
+  safeEnum(value, AUTH_SIGNUP_PLATFORM_VALUES, DEFAULT_AUTH_SIGNUP_PLATFORM);
+
+export enum AuthIdentityProviderEnum {
+  PASSWORD = "password",
+  GITHUB = "github",
+}
+export const DEFAULT_AUTH_IDENTITY_PROVIDER = AuthIdentityProviderEnum.PASSWORD;
+export const AUTH_IDENTITY_PROVIDER_VALUES = Object.values(AuthIdentityProviderEnum);
+export const AuthIdentityProvider = (value: Nilable<string>) =>
+  safeEnum(value, AUTH_IDENTITY_PROVIDER_VALUES, DEFAULT_AUTH_IDENTITY_PROVIDER);
+
+export enum AssetKindEnum {
+  IMAGES = "images",
+  FILES = "files",
+  VIDEOS = "videos",
+  AUDIOS = "audios",
+}

package/src/enums/dashboard.ts

@@ -0,0 +1,17 @@
+import type { Array, Nilable } from "@/types";
+
+import { safeEnum } from "@/utils/safe";
+
+/** 仪表盘背景。Dashboard background. */
+export enum DashboardBackgroundEnum {
+  NONE = "none",
+  WAVES = "waves",
+  SQUARES = "squares",
+  LETTER_GLITCH = "letterGlitch",
+  PIXEL_BLAST = "pixelBlast",
+}
+
+export const DEFAULT_DASHBOARD_BACKGROUND = DashboardBackgroundEnum.NONE;
+export const DASHBOARD_BACKGROUND_VALUES: Array<DashboardBackgroundEnum> = Object.values(DashboardBackgroundEnum);
+export const DashboardBackground = (value: Nilable<string>) =>
+  safeEnum(value, DASHBOARD_BACKGROUND_VALUES, DEFAULT_DASHBOARD_BACKGROUND);

package/src/enums/index.ts

@@ -0,0 +1,5 @@
+export * from "./theme";
+export * from "./language";
+export * from "./dashboard";
+export * from "./auth";
+export * from "./layout";

package/src/enums/language.ts

@@ -0,0 +1,16 @@
+/**
+ * 语言枚举与常量，不引用任何 JSON，供需要轻量引用的模块使用。
+ */
+import type { Nilable } from "@/types";
+
+import { safeEnum } from "@/utils/safe";
+
+export enum LanguageEnum {
+  EN = "en",
+  ZH = "zh",
+  FR = "fr",
+}
+
+export const DEFAULT_LANGUAGE = LanguageEnum.ZH;
+export const LANGUAGE_VALUES = Object.values(LanguageEnum);
+export const Language = (value: Nilable<string>) => safeEnum(value, LANGUAGE_VALUES, DEFAULT_LANGUAGE);

package/src/enums/layout.ts

@@ -0,0 +1,12 @@
+import type { Nilable } from "@/types";
+
+import { safeEnum } from "@/utils/safe";
+
+export enum LayoutModeEnum {
+  SHOW = "show",
+  HIDE = "hide",
+}
+
+export const DEFAULT_LAYOUT_MODE = LayoutModeEnum.SHOW;
+export const LAYOUT_MODE_VALUES = Object.values(LayoutModeEnum);
+export const LayoutMode = (value: Nilable<string>) => safeEnum(value, LAYOUT_MODE_VALUES, DEFAULT_LAYOUT_MODE);

package/src/enums/theme.ts

@@ -0,0 +1,124 @@
+import { safeEnum } from "@/utils/safe";
+
+import type { Nilable } from "@/types";
+
+/** 基础主题枚举（平台/圆角等，如 iOS 24 / Android|Windows 6 / Linux 4） */
+export enum BaseEnum {
+  DEFAULT = "default",
+  IOS = "ios",
+  ANDROID = "android",
+  WINDOWS = "windows",
+  LINUX = "linux",
+}
+
+export const DEFAULT_BASE = BaseEnum.DEFAULT;
+export const BASE_VALUES = Object.values(BaseEnum);
+export const Base = (value: Nilable<string>) => safeEnum(value, BASE_VALUES, DEFAULT_BASE);
+
+/** 外观偏好：浅色 / 深色 / 跟随系统（解析后才映射到 Radix light|dark） */
+export enum AppearanceEnum {
+  LIGHT = "light",
+  DARK = "dark",
+  SYSTEM = "system",
+}
+
+export const DEFAULT_APPEARANCE = AppearanceEnum.SYSTEM;
+export const APPEARANCE_VALUES = Object.values(AppearanceEnum);
+export const Appearance = (value: Nilable<string>) => safeEnum(value, APPEARANCE_VALUES, DEFAULT_APPEARANCE);
+
+/** Radix 强调色 */
+export enum AccentColorEnum {
+  GRAY = "gray",
+  GOLD = "gold",
+  BRONZE = "bronze",
+  BROWN = "brown",
+  YELLOW = "yellow",
+  AMBER = "amber",
+  ORANGE = "orange",
+  TOMATO = "tomato",
+  RED = "red",
+  RUBY = "ruby",
+  CRIMSON = "crimson",
+  PINK = "pink",
+  PLUM = "plum",
+  PURPLE = "purple",
+  VIOLET = "violet",
+  IRIS = "iris",
+  INDIGO = "indigo",
+  BLUE = "blue",
+  CYAN = "cyan",
+  TEAL = "teal",
+  JADE = "jade",
+  GREEN = "green",
+  GRASS = "grass",
+  LIME = "lime",
+  MINT = "mint",
+  SKY = "sky",
+}
+
+export const DEFAULT_ACCENT_COLOR = AccentColorEnum.TOMATO;
+export const ACCENT_COLOR_VALUES = Object.values(AccentColorEnum);
+export const AccentColor = (value: Nilable<string>) => safeEnum(value, ACCENT_COLOR_VALUES, DEFAULT_ACCENT_COLOR);
+
+/** Radix 中性灰 */
+export enum GrayColorEnum {
+  AUTO = "auto",
+  GRAY = "gray",
+  MAUVE = "mauve",
+  SLATE = "slate",
+  SAGE = "sage",
+  OLIVE = "olive",
+  SAND = "sand",
+}
+
+export const DEFAULT_GRAY_COLOR = GrayColorEnum.SLATE;
+export const GRAY_COLOR_VALUES = Object.values(GrayColorEnum);
+export const GrayColor = (value: Nilable<string>) => safeEnum(value, GRAY_COLOR_VALUES, DEFAULT_GRAY_COLOR);
+
+/** Radix 圆角档位（按平台映射：none=Linux / small=Android / medium=Other / large=Windows / full=iOS） */
+export enum RadiusEnum {
+  NONE = "none",
+  SMALL = "small",
+  MEDIUM = "medium",
+  LARGE = "large",
+  FULL = "full",
+}
+
+export const DEFAULT_RADIUS = RadiusEnum.MEDIUM;
+export const RADIUS_VALUES = Object.values(RadiusEnum);
+export const Radius = (value: Nilable<string>) => safeEnum(value, RADIUS_VALUES, DEFAULT_RADIUS);
+
+/** Radix 缩放比例 */
+export enum ScalingEnum {
+  S90 = "90%",
+  S95 = "95%",
+  S100 = "100%",
+  S105 = "105%",
+  S110 = "110%",
+}
+
+export const DEFAULT_SCALING = ScalingEnum.S100;
+export const SCALING_VALUES = Object.values(ScalingEnum);
+export const Scaling = (value: Nilable<string>) => safeEnum(value, SCALING_VALUES, DEFAULT_SCALING);
+
+/** Radix 面板背景 */
+export enum PanelBackgroundEnum {
+  SOLID = "solid",
+  TRANSLUCENT = "translucent",
+}
+
+export const DEFAULT_PANEL_BACKGROUND = PanelBackgroundEnum.TRANSLUCENT;
+export const PANEL_BACKGROUND_VALUES = Object.values(PanelBackgroundEnum);
+export const PanelBackground = (value: Nilable<string>) => safeEnum(value, PANEL_BACKGROUND_VALUES, DEFAULT_PANEL_BACKGROUND);
+
+/** UI 正文字体族（webfont 栈 / 系统默认；见 themes/fonts.ts + themes/index.css） */
+export enum ThemeFontFamilyEnum {
+  SYSTEM = "system",
+  IBM_PLEX = "ibm-plex",
+  NOTO = "noto",
+  SOURCE_SANS = "source-sans",
+}
+
+export const DEFAULT_THEME_FONT_FAMILY = ThemeFontFamilyEnum.SYSTEM;
+export const THEME_FONT_FAMILY_VALUES = Object.values(ThemeFontFamilyEnum);
+export const ThemeFontFamily = (value: Nilable<string>) => safeEnum(value, THEME_FONT_FAMILY_VALUES, DEFAULT_THEME_FONT_FAMILY);

package/src/events/EventEmitter.ts

@@ -0,0 +1,115 @@
+/**
+ * 通用事件发射器（按事件名注册/注销/触发）
+ * Generic event emitter: subscribe, unsubscribe, and emit by event name.
+ *
+ * 不传 PayloadMap 时默认 PayloadMap = Record<E, unknown>，每个事件可无参或单参 (unknown)，通用。
+ * 传 PayloadMap 时可精确到：void（无参）、单类型（单参）、元组（多参）。
+ *
+ * @example 不传 PayloadMap（通用：无参或单参均可）
+ * ```ts
+ * const events = defineEvents({ A: "a", B: "b" });
+ * class Em extends EventEmitter<EventNamesOf<typeof events>> { constructor() { super(events); } }
+ * const em = new Em();
+ * em.on(events.A, () => {}); em.emit(events.A);
+ * em.on(events.B, (x) => console.log(x)); em.emit(events.B, data);
+ * ```
+ * @example 传 PayloadMap（严格单参/多参）
+ * ```ts
+ * type Map = { FOO: string; LOG: [string, number] };
+ * class Em extends EventEmitter<"FOO"|"LOG", Map> { ... }
+ * em.on(events.FOO, (x) => {}); em.emit(events.FOO, "hi");
+ * em.on(events.LOG, (msg, level) => {}); em.emit(events.LOG, "ok", 1);
+ * ```
+ */
+
+import type { Defined, ValueOf } from "@/types";
+
+/** 回调类型：内部存储与 on/off 默认(unknown)时均用此，任意函数即可，无需 as 断言。 */
+type EventCallback = (...args: any[]) => void;
+
+/**
+ * 将 PayloadMap[K] 规范为参数元组。
+ * void→[]；unknown（默认）→ [] | [unknown]；单类型 T→[T]；元组→不变。
+ */
+type ToArgs<P> = P extends void
+  ? []
+  : unknown extends P
+    ? [] | [P]
+    : P extends unknown[]
+      ? P
+      : [P];
+
+/** 由 defineEvents 返回的「已规范事件名对象」类型；constructor 只接受此类型。 */
+type DefinedEvents<T extends Record<string, string>> = Defined<T, "events">;
+
+/**
+ * 从 events 对象推导出事件名字符串联合。
+ * - 使用 `[T] extends [Defined<...>]` 稳定 `infer O`，避免部分 TS 版本下 `T extends Defined<infer O>` 推断失败得到 `never`。
+ * - 排除 `__defineBrand`，避免 `keyof O` 混入品牌键导致值联合含 `"events"` 或推断异常。
+ */
+type EventNamesOf<T> = [T] extends [Defined<infer O, "events">]
+  ? ValueOf<{ [K in keyof O as K extends "__defineBrand" ? never : K]: O[K] }>
+  : T extends Record<string, string>
+    ? T[keyof T]
+    : never;
+
+/**
+ * 规范创建「一级 key-value」事件名对象：仅允许 key → 字符串 value，禁止嵌套（类型约束）。
+ * 返回 DefinedEvents<T>，供 EventEmitter 构造使用。
+ * Define events object: one-level key-value (string values), no nested objects (type-only). Returns DefinedEvents<T> for EventEmitter.
+ *
+ * @param events - 事件名 key-value 对象。Event name key-value object (e.g. { FOO: "DOMAIN:FOO" }).
+ * @returns DefinedEvents<E>，仅此类型可传入 EventEmitter 构造。DefinedEvents<E>; only this type is accepted by EventEmitter constructor.
+ * @example
+ * ```ts
+ * const routerEvents = defineEvents({ NAVIGATE: "ROUTER:NAVIGATE", NAVIGATE_BACK: "ROUTER:NAVIGATE_BACK" });
+ * class RouterEmitter extends EventEmitter<EventNamesOf<typeof routerEvents>> { constructor() { super(routerEvents); } }
+ * ```
+ */
+function defineEvents<E extends Record<string, string>>(events: E): DefinedEvents<E> {
+  return events as DefinedEvents<E>;
+}
+
+function createListenersMap<E extends string>(eventNames: readonly E[]): Record<E, Set<EventCallback>> {
+  const map = {} as Record<E, Set<EventCallback>>;
+  for (const e of eventNames) {
+    map[e] = new Set();
+  }
+  return map;
+}
+
+/**
+ * 泛型 EventEmitter：构造函数仅接受 defineEvents 返回的 DefinedEvents 类型，提供 on / off / emit。
+ * PayloadMap[K] 可为 void（无参）、单类型 T（单参）、或元组 [A, B, ...]（多参），统一规范为参数列表。
+ * PayloadMap[K] can be void (no args), single type T (one arg), or tuple [A, B, ...] (multi arg).
+ *
+ * @param events - 须为 defineEvents(...) 的返回值（DefinedEvents）。Must be the return value of defineEvents(...) (DefinedEvents).
+ */
+class EventEmitter<E extends string, PayloadMap extends Record<E, unknown> = Record<E, unknown>> {
+  private listeners: Record<E, Set<EventCallback>>;
+
+  constructor(events: DefinedEvents<Record<string, E>>) {
+    this.listeners = createListenersMap(Object.values(events as Record<string, E>));
+  }
+
+  /** 注册事件监听；回调为任意函数，由 emit 时传入的参数决定实际类型。 */
+  on<K extends E>(event: K, callback: EventCallback): void {
+    this.listeners[event].add(callback);
+  }
+
+  /** 移除事件监听（需与 on 时同一引用）。 */
+  off<K extends E>(event: K, callback: EventCallback): void {
+    this.listeners[event].delete(callback);
+  }
+
+  /**
+   * 触发事件；参数与 PayloadMap[K] 一致：void 无参，T 单参，[A,B] 多参。
+   * Emit an event; args match PayloadMap[K]: void → no args, T → one arg, [A,B] → spread.
+   */
+  emit<K extends E>(event: K, ...args: ToArgs<PayloadMap[K]>): void {
+    this.listeners[event].forEach((cb) => cb(...args));
+  }
+}
+
+export { EventEmitter, defineEvents };
+export type { EventCallback, DefinedEvents, EventNamesOf };

package/src/events/auth.ts

@@ -0,0 +1,48 @@
+import type { ProfileKindEnum } from "@/enums";
+import type { EventNamesOf } from "@/events/EventEmitter";
+
+import { defineEvents, EventEmitter } from "@/events/EventEmitter";
+import { singleton } from "@/utils/singleton";
+
+export const authEvents = defineEvents({
+  UPDATE_ACCOUNT_SUCCESS: "AUTH:UPDATE_ACCOUNT_SUCCESS",
+  LOGIN_SUCCESS: "AUTH:LOGIN_SUCCESS",
+  LOGOUT: "AUTH:LOGOUT",
+  INVALIDATE_EMAILS: "AUTH:INVALIDATE_EMAILS",
+  INVALIDATE_PROFILES: "AUTH:INVALIDATE_PROFILES",
+});
+
+type AuthEvent = EventNamesOf<typeof authEvents>;
+
+export type InvalidateProfilesPayload = {
+  aID: string;
+  kind: ProfileKindEnum;
+};
+
+class AuthEventEmitter extends EventEmitter<AuthEvent> {
+  constructor() {
+    super(authEvents);
+  }
+
+  invalidateEmails(aID?: string) {
+    this.emit(authEvents.INVALIDATE_EMAILS, aID);
+  }
+
+  invalidateProfiles(payload: InvalidateProfilesPayload) {
+    this.emit(authEvents.INVALIDATE_PROFILES, payload);
+  }
+
+  logout() {
+    this.emit(authEvents.LOGOUT);
+  }
+
+  onLogout(callback: () => void) {
+    this.on(authEvents.LOGOUT, callback);
+  }
+
+  offLogout(callback: () => void) {
+    this.off(authEvents.LOGOUT, callback);
+  }
+}
+
+export const authEventEmitter = new (singleton(AuthEventEmitter))();

package/src/events/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 事件模块：仅导出通用 EventEmitter。各域发射器请直接按路径引用（如 @/events/router）。
+ * Events module: exports only the generic EventEmitter. Use direct paths for domain emitters (e.g. @/events/router).
+ */
+export * from "./EventEmitter";
+export * from "./auth";
+export * from "./system";
+export * from "./query";

package/src/events/query.ts

@@ -0,0 +1,22 @@
+import type { EventNamesOf } from "@/events/EventEmitter";
+
+import { defineEvents, EventEmitter } from "@/events/EventEmitter";
+import { singleton } from "@/utils/singleton";
+
+export const queryEvents = defineEvents({
+  RESET_ACTIVE_QUERIES: "QUERY:RESET_ACTIVE_QUERIES",
+});
+
+type QueryDomainEvent = EventNamesOf<typeof queryEvents>;
+
+class QueryDomainEmitter extends EventEmitter<QueryDomainEvent> {
+  constructor() {
+    super(queryEvents);
+  }
+
+  resetActiveQueries(onDone?: () => void) {
+    this.emit(queryEvents.RESET_ACTIVE_QUERIES, onDone);
+  }
+}
+
+export const queryEventEmitter = new (singleton(QueryDomainEmitter))();

package/src/events/system.ts

@@ -0,0 +1,48 @@
+import type { EventNamesOf } from "@/events/EventEmitter";
+
+import { defineEvents, EventEmitter } from "@/events/EventEmitter";
+import { singleton } from "@/utils/singleton";
+
+/**
+ * Host-agnostic UI feedback. Package emits; WEB ModalProvider listens.
+ */
+export const systemEvents = defineEvents({
+  SHOW_ERROR: "SYSTEM:SHOW_ERROR",
+  SHOW_SUCCESS: "SYSTEM:SHOW_SUCCESS",
+});
+
+type SystemEvent = EventNamesOf<typeof systemEvents>;
+
+export type SystemShowErrorPayload = {
+  message: string;
+  title?: string;
+};
+
+export type SystemShowSuccessPayload =
+  | string
+  | {
+      message: string;
+      title?: string;
+      onClick?: () => void;
+    };
+
+type SystemPayloadMap = {
+  "SYSTEM:SHOW_ERROR": SystemShowErrorPayload;
+  "SYSTEM:SHOW_SUCCESS": SystemShowSuccessPayload;
+};
+
+class SystemEventEmitter extends EventEmitter<SystemEvent, SystemPayloadMap> {
+  constructor() {
+    super(systemEvents);
+  }
+
+  showError(message: string, title?: string) {
+    this.emit(systemEvents.SHOW_ERROR, { message, title });
+  }
+
+  showSuccess(props: SystemShowSuccessPayload) {
+    this.emit(systemEvents.SHOW_SUCCESS, props);
+  }
+}
+
+export const systemEventEmitter = new (singleton(SystemEventEmitter))();

package/src/hooks/asset.ts

@@ -0,0 +1,77 @@
+/**
+ * Asset upload hooks — 组件勿直接调 apis/asset
+ */
+import type { AxiosError } from "axios";
+import type { Asset } from "@/types";
+
+import { useMutation } from "@tanstack/react-query";
+import { useAssetRepository } from "@/apis/repositories";
+import { authEventEmitter, authEvents } from "@/events/auth";
+import { systemEventEmitter } from "@/events/system";
+import { AuthStore } from "@/stores/auth";
+import { getApiErrorMessage } from "@/utils/apiError";
+import { useUnifiedQuery } from "@/utils/factory";
+
+export type UseDeleteImageOptions = {
+  ifShowError?: boolean;
+};
+
+export const usePrepareUpload = () => {
+  const asset = useAssetRepository();
+  return useMutation({
+    mutationFn: ({ kind, params }: { kind: Asset.Kind; params: Asset.Request.PrepareUpload }) => asset.PrepareUpload(kind, params),
+  });
+};
+
+export const useConfirmUpload = () => {
+  const asset = useAssetRepository();
+  return useMutation({
+    mutationFn: ({ kind, params }: { kind: Asset.Kind; params: Asset.Request.ConfirmUpload }) => asset.ConfirmUpload(kind, params),
+  });
+};
+
+export const useDeleteAsset = () => {
+  const asset = useAssetRepository();
+  return useMutation({
+    mutationFn: ({ kind, id }: { kind: Asset.Kind; id: string }) => asset.Delete(kind, id),
+    onError: (error: AxiosError) => {
+      systemEventEmitter.showError(getApiErrorMessage(error, "[useDeleteAsset] error"));
+    },
+  });
+};
+
+export const useListAssets = (kind: Asset.Kind) => {
+  const asset = useAssetRepository();
+  return useUnifiedQuery(() => asset.List(kind), ["asset", "list", kind], undefined);
+};
+
+export const usePrepareImageUpload = () => {
+  const asset = useAssetRepository();
+  return useMutation<Asset.Response.PrepareUpload, AxiosError, Asset.Request.PrepareUpload>({
+    mutationFn: (params) => asset.PrepareUpload("images", params),
+  });
+};
+
+export const useConfirmImageUpload = () => {
+  const asset = useAssetRepository();
+  const accountId = AuthStore.getState().currentAccountId;
+  return useMutation<void, AxiosError, Asset.Request.ConfirmUpload>({
+    mutationFn: (params) => asset.ConfirmUpload("images", params),
+    onSuccess: () => {
+      authEventEmitter.emit(authEvents.UPDATE_ACCOUNT_SUCCESS, accountId);
+    },
+  });
+};
+
+export const useDeleteImage = (options?: UseDeleteImageOptions) => {
+  const asset = useAssetRepository();
+  const ifShowError = options?.ifShowError ?? true;
+  return useMutation({
+    mutationFn: (id: string) => asset.Delete("images", id),
+    onError: (error: AxiosError) => {
+      if (ifShowError) {
+        systemEventEmitter.showError(getApiErrorMessage(error, "[useDeleteImage] error"));
+      }
+    },
+  });
+};