nfx-ui 0.7.4 → 0.9.0

package/dist/src/themes/themes/index.d.ts

@@ -0,0 +1,2 @@
+export { themes, defaultTheme, darkTheme, cosmicTheme, corporateTheme, forestTheme, coffeeTheme, wineTheme } from './colors';
+export { bases } from './bases';

package/dist/src/themes/types/components.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+import { BaseEnum, ThemeEnum } from './theme';
+/** 主题 Provider 的 props。ThemeProvider props. */
+export interface ThemeProviderProps {
+    /** 子节点。Children. */
+    children: ReactNode;
+    /** 默认颜色主题。Default color theme. */
+    defaultTheme?: ThemeEnum;
+    /** 默认基础主题（如圆角规范）。Default base theme (e.g. radius). */
+    defaultBase?: BaseEnum;
+}
+/** 主题切换器 props。ThemeSwitcher props. */
+export interface ThemeSwitcherProps {
+    /** 样式状态。Visual status. */
+    status?: "primary" | "default";
+    /** 根据 theme 返回显示名称；未传则使用 theme 原值。Display name for theme; default is theme value. */
+    getThemeDisplayName?: (theme: ThemeEnum) => string;
+    /** 处理主题改变。Handle theme change. */
+    handleChangeTheme?: (theme: ThemeEnum) => void;
+}

package/dist/src/themes/types/context.d.ts

@@ -0,0 +1,16 @@
+import { BaseEnum, Theme, ThemeEnum } from './theme';
+/** useTheme 返回值类型。Return type of useTheme. */
+export interface ThemeContextType {
+    /** 当前完整主题（颜色+基础）。Current full theme (colors + base). */
+    currentTheme: Theme;
+    /** 当前颜色主题名。Current color theme name. */
+    themeName: ThemeEnum;
+    /** 当前基础主题名。Current base theme name. */
+    baseName: BaseEnum;
+    setTheme: (themeName: ThemeEnum) => void;
+    setBase: (baseName: BaseEnum) => void;
+    /** 可选颜色主题列表。Available color themes. */
+    availableThemes: ThemeEnum[];
+    /** 可选基础主题列表。Available base themes. */
+    availableBases: BaseEnum[];
+}

package/dist/src/themes/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 主题模块类型统一导出。All theme module types re-exported.
+ */
+export * from './theme';
+export * from './components';
+export * from './context';

package/dist/src/themes/types/theme.d.ts

@@ -0,0 +1,209 @@
+/**
+ * 主题相关类型：颜色变量、基础变量、主题枚举与常量。
+ * Theme types: color/base variables, theme enums and constants.
+ */
+/** 颜色变量（主题色、背景、边框、文字、图表等一切与颜色相关） */
+export interface ColorVariables {
+    /** 主品牌色 — 按钮、链接、激活态 | `--color-primary` */
+    primary: string;
+    /** 主色悬停 — 按钮 hover / ShowFilter active | `--color-primary-hover` */
+    primaryHover: string;
+    /** 主色浅色 — 标签底色、浅色按钮、选中态背景 | `--color-primary-light` */
+    primaryLight: string;
+    /** 主色极浅底 — Input/SearchInput focus 发光底、选中行底 | `--color-primary-bg` */
+    primaryBg: string;
+    /** 主色 RGB 三元组 — 用于 `rgba(var(--color-primary-rgb), α)` 计算 | `--color-primary-rgb` */
+    primaryRgb: string;
+    /** 主色半透明 — focus ring 外环、Dropdown 聚焦阴影 | `--color-primary-transparent` `--color-primary-alpha` */
+    primaryTransparent: string;
+    /** 主色上的前景文字 — 按钮白字 / 深色背景字 | `--color-primary-fg` */
+    primaryFg: string;
+    /** 成功色 — Toast 成功、状态徽标 | `--color-success` */
+    success: string;
+    /** 成功色浅底 — 成功 Alert 背景 | `--color-success-light` */
+    successLight: string;
+    /** 成功色 RGB — `rgba(var(--color-success-rgb), α)` | `--color-success-rgb` */
+    successRgb: string;
+    /** 信息色 — 提示 Alert、Badge | `--color-info` */
+    info: string;
+    /** 信息色浅底 — 信息 Alert 背景 | `--color-info-light` */
+    infoLight: string;
+    /** 信息色 RGB — `rgba(var(--color-info-rgb), α)` | `--color-info-rgb` */
+    infoRgb: string;
+    /** 警告色 — 警告 Toast、图标 | `--color-warning` */
+    warning: string;
+    /** 警告色浅底 — 警告 Alert 背景 | `--color-warning-light` */
+    warningLight: string;
+    /** 警告色 RGB — `rgba(var(--color-warning-rgb), α)` | `--color-warning-rgb` */
+    warningRgb: string;
+    /** 危险色 — 删除按钮、表单错误边框 | `--color-danger` `--color-error` */
+    danger: string;
+    /** 危险色浅底 — 危险按钮 hover、错误 Alert 底 | `--color-danger-light` */
+    dangerLight: string;
+    /** 危险色 RGB — Input/Textarea 错误 focus ring | `--color-danger-rgb` `--color-error-rgb` */
+    dangerRgb: string;
+    /** 页面底色 — html body、最外层容器 | `--color-bg` `--color-bg-1` */
+    bg: string;
+    /** 二级背景 — Sidebar、Footer、卡片 | `--color-bg-2` */
+    bg2: string;
+    /** 三级背景 — 菜单 hover、条纹行 | `--color-bg-3` */
+    bg3: string;
+    /** 四级背景 — 深层嵌套面板 | `--color-bg-4` */
+    bg4: string;
+    /** 辅助背景 — Suspense fallback 面板 | `--color-bg-secondary` */
+    bgSecondary: string;
+    /** 最浅边框 — 容器默认边框 | `--color-border` */
+    border: string;
+    /** 二级边框 — 分隔线 | `--color-border-2` */
+    border2: string;
+    /** 三级边框 — Input 非激活边、列表分隔 | `--color-border-3` */
+    border3: string;
+    /** 四级边框 — Input/Button 默认边框 | `--color-border-4` */
+    border4: string;
+    /** 五级边框（最深） — disabled Input 边框 | `--color-border-5` */
+    border5: string;
+    /** 悬停边框 — Suspense retry hover、ShowFilter hover | `--color-border-hover` */
+    borderHover: string;
+    /** 辅助图标色 — icon placeholder、ShowFilter 默认色 | `--color-fg` */
+    fg: string;
+    /** 正文文字 — 段落、表格内容 | `--color-fg-text` */
+    fgText: string;
+    /** 标题文字 — h1-h6、Input label | `--color-fg-heading` */
+    fgHeading: string;
+    /** 高亮文字 — 链接、Dropdown 选中项 | `--color-fg-highlight` */
+    fgHighlight: string;
+    /** 次要文字 — placeholder、hint、辅助说明 | `--color-fg-muted` */
+    fgMuted: string;
+    /** 主色上的文字 — primary 按钮/Badge 内文字 | `--color-fg-on-primary` */
+    fgOnPrimary: string;
+    /** 分隔线 — Sidebar 底部分隔、Dropdown 选项间隔 | `--color-separator` */
+    separator: string;
+    /** 遮罩层 — Modal/Drawer 背景蒙版 | `--color-overlay` */
+    overlay: string;
+    /** 阴影色 — 卡片/弹出层 box-shadow 基色 | `--color-shadow` */
+    shadow: string;
+    /** 焦点环 — 键盘 Tab 导航 focus outline | `--color-ring` */
+    ring: string;
+    /** 图表系列 1（通常=主色） — 多系列折线/柱状图第 1 组 | `--color-chart-1` */
+    chart1: string;
+    /** 图表系列 2 — 第 2 组数据线 | `--color-chart-2` */
+    chart2: string;
+    /** 图表系列 3 — 第 3 组数据线 | `--color-chart-3` */
+    chart3: string;
+    /** 图表系列 4 — 第 4 组数据线 | `--color-chart-4` */
+    chart4: string;
+    /** 图表系列 5 — 第 5 组数据线 | `--color-chart-5` */
+    chart5: string;
+    /** 温度计仪表盘 — 圆弧填充渐变（5 色由浅到深）、空弧、滑块 */
+    temperature: {
+        arcFill: string[];
+        arcEmpty: string;
+        thumbBg: string;
+        thumbBorder: string;
+    };
+    /** 太阳能面板图 — 渐变、阴影、第二系列 */
+    solar: {
+        gradientLeft: string;
+        gradientRight: string;
+        shadowColor: string;
+        secondSeriesFill: string;
+    };
+    /** 流量图 — tooltip、坐标轴、数据点、渐变 */
+    traffic: {
+        tooltipBg: string;
+        tooltipBorderColor: string;
+        tooltipTextColor: string;
+        yAxisSplitLine: string;
+        lineBg: string;
+        itemColor: string;
+        itemBorderColor: string;
+        itemEmphasisBorderColor: string;
+        shadowLineDarkBg: string;
+        shadowLineShadow: string;
+        gradFrom: string;
+        gradTo: string;
+    };
+    /** 电力图 — tooltip、坐标轴、折线渐变、面积渐变 */
+    electricity: {
+        tooltipBg: string;
+        tooltipLineColor: string;
+        tooltipBorderColor: string;
+        tooltipTextColor: string;
+        axisLineColor: string;
+        xAxisTextColor: string;
+        yAxisSplitLine: string;
+        itemBorderColor: string;
+        lineGradFrom: string;
+        lineGradTo: string;
+        lineShadow: string;
+        areaGradFrom: string;
+        areaGradTo: string;
+        shadowLineDarkBg: string;
+    };
+    /** ECharts 全局 — 画布底色、文字、坐标轴、tooltip */
+    echarts: {
+        bg: string;
+        textColor: string;
+        axisLineColor: string;
+        splitLineColor: string;
+        itemHoverShadowColor: string;
+        tooltipBackgroundColor: string;
+    };
+    /** Chart.js 全局 — 坐标轴、文字 */
+    chartjs: {
+        axisLineColor: string;
+        textColor: string;
+    };
+}
+/** 非颜色变量（圆角等，可随平台不同：iOS 24 / Android|Windows 6 / Linux 4） */
+export interface BaseVariables {
+    /** 按钮圆角（px） | `--radius-button` */
+    buttonRadius: number;
+    /** 卡片圆角（px） | `--radius-card` */
+    cardRadius: number;
+    /** 输入框圆角（px） | `--radius-input` */
+    inputRadius: number;
+}
+/** 颜色主题：name/displayName 表示这套配色是谁 */
+export interface ColorTheme {
+    name: string;
+    displayName: string;
+    variables: ColorVariables;
+}
+/** 基础主题：name/displayName 表示这套基础规范是谁（如 iOS / Android / 默认） */
+export interface BaseTheme {
+    name: string;
+    displayName: string;
+    variables: BaseVariables;
+}
+/** 完整主题 = 颜色主题 + 基础主题 */
+export interface Theme {
+    colors: ColorTheme;
+    base: BaseTheme;
+}
+/** 颜色主题枚举 */
+export declare enum ThemeEnum {
+    DEFAULT = "default",
+    LIGHT = "light",
+    CORPORATE = "corporate",
+    FOREST = "forest",
+    DARK = "dark",
+    COSMIC = "cosmic",
+    COFFEE = "coffee",
+    WINE = "wine",
+    WHEAT = "wheat"
+}
+export declare const DEFAULT_THEME = ThemeEnum.DEFAULT;
+export declare const THEME_VALUES: ThemeEnum[];
+/** 基础主题枚举（平台/圆角等，如 iOS 24 / Android|Windows 6 / Linux 4） */
+export declare enum BaseEnum {
+    DEFAULT = "default",
+    IOS = "ios",
+    ANDROID = "android",
+    WINDOWS = "windows",
+    LINUX = "linux"
+}
+export declare const DEFAULT_BASE = BaseEnum.DEFAULT;
+export declare const BASE_VALUES: BaseEnum[];
+export declare const COLOR_STORAGE_KEY = "theme-color";
+export declare const BASE_STORAGE_KEY = "theme-base";

package/dist/src/themes/utils/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 主题模块工具函数。Theme module utils.
+ */
+export { getThemeBaseStorage, getThemeColorStorage, removeThemeStorage, setThemeBaseStorage, setThemeColorStorage, } from './themeStorage';

package/dist/src/themes/utils/themeStorage.d.ts

@@ -0,0 +1,7 @@
+import { Nilable } from '../../../types/utils';
+import { BaseEnum, ThemeEnum } from '../types';
+export declare function getThemeColorStorage(): Nilable<ThemeEnum>;
+export declare function setThemeColorStorage(value: ThemeEnum): void;
+export declare function getThemeBaseStorage(): Nilable<BaseEnum>;
+export declare function setThemeBaseStorage(value: BaseEnum): void;
+export declare function removeThemeStorage(): void;

package/dist/src/types/api.d.ts

@@ -0,0 +1,75 @@
+import { Array } from './utils';
+/** 基础响应（status、errCode、message）。Base response (status, errCode, message). */
+interface BaseResponse {
+    /** 状态码。Status code. */
+    status?: number;
+    /** 错误码。Error code. */
+    errCode?: string;
+    /** 消息。Message. */
+    message?: string;
+}
+/** 列表元信息（如 total）。List meta (e.g. total). */
+interface ListMeta {
+    /** 总数。Total count. */
+    total?: number;
+}
+/** 带 data 与可选 meta 的响应。Response with data and optional meta. */
+interface DataResponse<T, M = Record<string, unknown>> extends BaseResponse {
+    /** 数据。Data payload. */
+    data: T;
+    /** 元信息。Meta. */
+    meta?: M;
+}
+/** 数字 offset 分页参数（用于 makeCursorFetchFunction 等）。Number offset pagination params; used by makeCursorFetchFunction etc. */
+interface OffsetLimitNumber {
+    /** 偏移量。Offset. */
+    offset: number;
+    /** 每页条数。Limit. */
+    limit: number;
+}
+/** 字符串游标分页参数（用于 makeStringCursorFetchFunction 等）。String cursor pagination params; used by makeStringCursorFetchFunction etc. */
+interface OffsetLimitString {
+    /** 游标（字符串）。Cursor (string). */
+    offset: string;
+    /** 每页条数。Limit. */
+    limit: number;
+}
+/** 列表 + 总数：items + total（用于 offset/limit 分页的返回）。List with total count; used as offset/limit response. */
+interface ListDTOWithTotalNumber<T> {
+    /** 列表项。Items. */
+    items: Array<T>;
+    /** 总数。Total count. */
+    total: number;
+}
+/** 字符串游标列表：items + nextCursor（用于 nextCursor 为 string 的 API）。List with string nextCursor. */
+interface ListDTOWithNextCursor<T> {
+    /** 列表项。Items. */
+    items: Array<T>;
+    /** 下一页游标。Next cursor. */
+    nextCursor: string;
+}
+/** 分页响应（data、total、page、pageSize）。Paginated response (data, total, page, pageSize). */
+interface PaginatedResponse<T> {
+    /** 数据列表。Data array. */
+    data: Array<T>;
+    /** 总数。Total count. */
+    total: number;
+    /** 当前页。Current page. */
+    page: number;
+    /** 每页条数。Page size. */
+    pageSize: number;
+}
+/** 错误响应。Error response. */
+interface ApiErrorBody {
+    /** 状态码。Status code. */
+    status?: number;
+    /** 错误码。Error code. */
+    errCode?: string;
+    /** 消息。Message. */
+    message?: string;
+    /** 详情。Details. */
+    details?: unknown;
+    /** 追踪 ID。Trace ID. */
+    traceId?: string;
+}
+export type { BaseResponse, DataResponse, ListDTOWithNextCursor, ListDTOWithTotalNumber, ListMeta, OffsetLimitNumber, OffsetLimitString, PaginatedResponse, ApiErrorBody, };

package/dist/src/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './api';
+export * from './utils';

package/dist/src/types/utils.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 数组类型。Array type.
+ * @example Array<string> => string[]
+ */
+type Array<T> = T[];
+/**
+ * 可为 null。Nullable: T | null.
+ * @example Nullable<string> => string | null
+ */
+type Nullable<T> = T | null;
+/**
+ * 可为 undefined。Maybe: T | undefined.
+ * @example Maybe<number> => number | undefined
+ */
+type Maybe<T> = T | undefined;
+/**
+ * 可为 null 或 undefined。Nilable: T | null | undefined.
+ * @example Nilable<boolean> => boolean | null | undefined
+ */
+type Nilable<T> = T | null | undefined;
+/**
+ * 可为 null、undefined 或空字符串。Emptyable: T | null | undefined | "".
+ * @example Emptyable<string> => string | null | undefined | ""
+ */
+type Emptyable<T> = T | null | undefined | "";
+/**
+ * 可为 0 的数值类型。Zeroable: T | 0，T 为 number 子类型。
+ * @example Zeroable<number> => number | 0
+ */
+type Zeroable<T extends number> = T | 0;
+/**
+ * 可为空字符串的类型。Stringable: T | ""，T 为 string 子类型。
+ * @example Stringable<string> => string | ""
+ */
+type Stringable<T extends string> = T | "";
+/**
+ * 可为空对象。Objectable: T | {}，T 为对象类型。
+ * @example Objectable<{ a: number }> => { a: number } | {}
+ */
+type Objectable<T extends Record<string, unknown>> = T | {};
+/**
+ * 可为空数组；T 为元素类型，等价于 ArrayType<T> | []。
+ * Arrayable: T[] | []，T 为数组元素类型。
+ * @example Arrayable<string> => string[] | []
+ */
+type Arrayable<T> = Array<T> | [];
+/**
+ * 存在性结果元组：有值时为 [T, true]，无值时为 [null, false]。用于区分「有值」与「无」而不依赖 undefined。
+ * Existence result tuple: [T, true] when present, [null, false] when absent.
+ * @example ExistenceResult<{ id: string }> => [{ id: string }, true] | [null, false]
+ */
+type ExistenceResult<T> = [T, true] | [null, false];
+/**
+ * 对象 T 所有属性值的联合类型。ValueOf: union of all property value types of T.
+ * @example ValueOf<{ a: number; b: string }> => number | string
+ */
+type ValueOf<T> = T[keyof T];
+/**
+ * 对象 T 的键字面量联合类型，即 keyof T。KeyOf: key type of T.
+ * @example KeyOf<{ a: 1; b: 2 }> => "a" | "b"
+ */
+type KeyOf<T> = keyof T;
+/**
+ * 定义品牌类型：用于 defineXxx 的返回值，仅对应的 createXxx/构造函数可接受；Tag 区分不同定义（如 "events" | "router"）。
+ * Define brand type: for defineXxx return value, only the matching createXxx accepts; Tag discriminates (e.g. "events" | "router").
+ * @example Defined<{ HOME: "/" }, "router"> 仅能传入 createRouter；Defined<{ FOO: "x" }, "events"> 仅能传入 EventEmitter
+ */
+type Defined<T, Tag extends string> = T & {
+    readonly __defineBrand?: Tag;
+};
+/**
+ * 判断结果为 OK 时的元组形态：[T, true]；与 ExistenceResult 的「有值」分支一致。
+ * Result is OK: tuple [T, true]; same as the present branch of ExistenceResult.
+ * @example isOK<{ id: string }> => [T, true]
+ */
+type isOK<T> = [T, true] | [null, false];
+/**
+ * 数组或单个元素：T[] | T。用于接口/参数既可传数组也可传单元素时。
+ * Array or single element: T[] | T. For APIs that accept either an array or one element.
+ * @example ArrayOrSingle<string> => string[] | string
+ */
+type ArrayOrSingle<T> = T[] | T;
+export type { Nullable, Maybe, Nilable, Emptyable, Zeroable, Stringable, Objectable, Arrayable, ExistenceResult, ValueOf, Defined, KeyOf, isOK, Array, ArrayOrSingle };

package/dist/src/utils/address.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 规范化地址字符串：去除首尾空白并将连续空白合并为单个空格
+ * Normalize address string: trim and collapse consecutive spaces to one.
+ * @param address - 原始地址字符串
+ * @returns 规范化后的地址
+ */
+export declare function normalizeAddress(address: string): string;

package/dist/src/utils/apiError.d.ts

@@ -0,0 +1,16 @@
+import { ApiErrorBody } from '../../types/api';
+/**
+ * 仅当为后端错误（有 response.data）时解析为 ApiErrorBody，否则返回 null
+ * Parse to ApiErrorBody only when response.data exists; otherwise null.
+ * @param error - 通常为 Axios 错误或 unknown
+ * @returns ApiErrorBody 或 null
+ */
+export declare function getApiError(error: unknown): ApiErrorBody | null;
+/**
+ * UI 展示用错误文案：优先 i18n errors 命名空间（errCode），其次 api.message，最后 fallback
+ * Get display message: i18n errors namespace (by errCode) → api.message → fallback.
+ * @param error - 通常为 Axios 错误
+ * @param fallback - 无法解析时的默认文案
+ * @returns 展示用字符串
+ */
+export declare function getApiErrorMessage(error: unknown, fallback: string): string;

package/dist/src/utils/array.d.ts

@@ -0,0 +1,21 @@
+import { Array } from '../../types';
+/**
+ * 按 id 将 items 合并进数组：insert 仅插入新 id，upsert 覆盖同 id 并插入新 id；可 prepend 或 append
+ * Merge items into array by id: insert = only new ids, upsert = overwrite same id + insert new; place = prepend | append.
+ * @param arr - 原数组
+ * @param items - 待合并项
+ * @param idOf - 取 id 的函数
+ * @param place - 新项插入位置
+ * @param mode - insert 不覆盖已有 id；upsert 覆盖同 id
+ * @returns 合并后的新数组
+ */
+export declare function mergeById<T>(arr: Array<T>, items: Array<T>, idOf: (x: T) => string, place: "prepend" | "append", mode: "insert" | "upsert"): Array<T>;
+/**
+ * 从数组中移除 id 在集合 ids 中的项，返回新数组
+ * Remove elements whose id is in the given set; return new array.
+ * @param arr - 原数组
+ * @param ids - 要移除的 id 集合
+ * @param idOf - 取 id 的函数
+ * @returns 若无变化返回原数组，否则返回新数组
+ */
+export declare function pruneArray<T>(arr: Array<T>, ids: ReadonlySet<string>, idOf: (x: T) => string): Array<T>;

package/dist/src/utils/colors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 将任意颜色统一为指定透明度的 RGBA（rgb/rgba/hex 均用新 alpha 覆盖）
+ * Convert any color to RGBA with given alpha (overwrites existing alpha).
+ * @param color - rgb / rgba / hex 字符串
+ * @param alpha - 透明度 0–1
+ * @returns rgba(r, g, b, alpha) 字符串
+ */
+export declare const toRgbaWithAlpha: (color: string, alpha: number) => string;
+/**
+ * 将 RGB 颜色转换为 RGBA
+ * @param rgb - RGB 颜色字符串，格式: "rgb(r, g, b)"
+ * @param alpha - 透明度，范围 0-1
+ * @returns RGBA 颜色字符串，格式: "rgba(r, g, b, alpha)"
+ *
+ * @example
+ * rgbToRgba("rgb(250, 30, 22)", 0.3) // "rgba(250, 30, 22, 0.3)"
+ */
+export declare const rgbToRgba: (rgb: string, alpha: number) => string;
+/**
+ * 将 HEX 颜色转换为 RGBA
+ * @param hex - HEX 颜色字符串，格式: "#RRGGBB" 或 "#RGB"
+ * @param alpha - 透明度，范围 0-1
+ * @returns RGBA 颜色字符串，格式: "rgba(r, g, b, alpha)"
+ *
+ * @example
+ * hexToRGBA("#FA1E16", 0.3) // "rgba(250, 30, 22, 0.3)"
+ */
+export declare const hexToRGBA: (hex: string, alpha: number) => string;
+/**
+ * 在两色之间按 factor 线性插值（支持 hex / rgb）
+ * Linear color interpolation between start and end by factor (0–1); supports hex and rgb.
+ * @param start - 起始颜色
+ * @param end - 结束颜色
+ * @param factor - 插值系数 0–1
+ * @returns rgb(r, g, b) 字符串
+ */
+export declare const interpolateColor: (start: string, end: string, factor: number) => string;
+/**
+ * Pick one color from a string pool; fallback to white.
+ */
+export declare const pickColor: (pool: string[]) => string;

package/dist/src/utils/email.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 校验邮箱格式是否有效（简单正则：含 @ 与点）
+ * Check if email format is valid (simple regex: contains @ and dot).
+ * @param email - 待校验的邮箱字符串
+ * @returns 是否有效
+ */
+export declare const isValidEmail: (email: string) => boolean;

package/dist/src/utils/form.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 将任意值转为文本输入框可用的字符串（用于表单回显）
+ * Convert any value to a string suitable for text input (e.g. form display).
+ * @param value - 任意值
+ * @returns 字符串；null/undefined → ""；数组 → 逗号拼接；对象 → JSON 字符串
+ */
+export declare function toTextInputValue(value: unknown): string;
+/**
+ * 将任意值转为数字输入框可用的字符串（用于表单回显）
+ * Convert any value to a string suitable for number input (e.g. form display).
+ * @param value - 任意值
+ * @returns 字符串；null/undefined → ""；非有限数字 → ""；数组取首项
+ */
+export declare function toNumberInputValue(value: unknown): string;

package/dist/src/utils/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Utils 统一导出 / Utils barrel exports
+ * 地址、数组、API 错误、浏览器、颜色、邮箱、表单、图片、对象、电话、轮询、价格、safe、
+ * Promise、Result、重试、单例、Suspense、时间、类型工具、类型等
+ */
+export * from './address';
+export * from './lstorage';
+export * from './apiError';
+export * from './array';
+export * from './colors';
+export * from './email';
+export * from './form';
+export * from './object';
+export * from './polling';
+export * from './price';
+export * from './promise';
+export * from './result';
+export * from './retry';
+export * from './safe';
+export * from './singleton';
+export * from './suspense';
+export * from './time';
+export * from './random';
+export * from './types';

package/dist/src/utils/lstorage.d.ts

@@ -0,0 +1,4 @@
+import { Nilable } from '../../types/utils';
+export declare function removeItem(key: string): void;
+export declare function getItem(key: string): Nilable<string>;
+export declare function setItem(key: string, value: string): void;

package/dist/src/utils/object.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 从对象中剔除指定键，返回新对象（不修改原对象）
+ * Omit specified keys from object and return a new object.
+ * @param obj - 源对象
+ * @param keys - 要剔除的键（数组或单个键，可再接多个键）
+ * @returns 剔除后的新对象
+ * @example omit({ a: 1, b: 2, c: 3 }, ['a', 'c']) // { b: 2 }
+ * @example omit({ a: 1, b: 2, c: 3 }, 'a', 'b')  // { c: 3 }
+ */
+export declare function omit<Obj extends object, Key extends keyof Obj>(obj: Obj, keys: Key[] | Key, ...restKeys: Key[]): Omit<Obj, Key>;

package/dist/src/utils/polling.d.ts

@@ -0,0 +1,12 @@
+import { Result } from './result';
+import { WithRetryOptions } from './retry';
+/**
+ * 轮询直到 isOK(data) 为 true（内部用 withRetryResult 重试）。
+ * Poll until fetcher returns data that satisfies isOK; uses withRetryResult.
+ * @param fetcher - 拉取数据的函数。Function that fetches data.
+ * @param isOK - 判断数据是否满足条件。Predicate to check if data is OK.
+ * @param opts - 重试选项。Retry options.
+ * @returns Promise<Result<T>>
+ * @example const [job] = await pollUntil(() => getJob(id), (j) => j.status === "done", { retries: 10 });
+ */
+export declare function pollUntil<T>(fetcher: () => Promise<T>, isOK: (data: T) => boolean, opts?: WithRetryOptions): Promise<Result<T>>;

package/dist/src/utils/price.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 显示价格 → 数据库价格（分）。用于提交到后端、保存草稿等
+ * Display price to database price (cents). For submit/save.
+ * @param displayPrice - 展示用价格（元）
+ * @returns 数据库存储价格（分）
+ */
+export declare function toDatabasePrice(displayPrice: number): number;
+/**
+ * 数据库价格（分）→ 显示价格字符串（两位小数）
+ * Database price (cents) to display string (2 decimal places).
+ * @param databasePrice - 数据库价格（分）
+ * @returns 如 "12.34"
+ */
+export declare function toDisplayPrice(databasePrice: number): string;
+/**
+ * 数据库价格（分）→ 显示价格数字。用于表单、计算等
+ * Database price (cents) to display number.
+ * @param databasePrice - 数据库价格（分）
+ * @returns 数字（元）
+ */
+export declare function toDisplayPriceNumber(databasePrice: number): number;
+/**
+ * 数字缩写显示（如 1.2k+、3.5M+、1.1B+）
+ * Format number to abbreviated string (e.g. 1.2k+, 3.5M+, 1.1B+).
+ * @param num - 数字
+ * @returns 缩写字符串
+ */
+export declare function formatNumberAbbreviated(num: number): string;

package/dist/src/utils/promise.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 包装为「仅执行一次」的异步函数（重复调用返回同一 Promise）。
+ * Wrap async function so it runs only once; repeated calls return the same promise.
+ * @param fn - 要执行的异步函数。Async function to run once.
+ * @returns 包装后的函数，多次调用只执行一次。Wrapped function; only first call runs.
+ * @example const loadOnce = onceAsync(() => fetch("/api/config")); loadOnce(); loadOnce(); // 只请求一次
+ */
+export declare function onceAsync<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>): (...args: Args) => Promise<T>;
+/**
+ * 按 key 仅执行一次的异步函数（同一 key 重复调用返回同一 Promise）。
+ * Async function that runs only once per key; same key returns same promise.
+ * @param fn - 要执行的异步函数。Async function to run.
+ * @param keyExtractor - 从参数中提取 key 的函数。Function to extract key from args.
+ * @returns 包装后的函数。Wrapped function.
+ * @example const fetchUser = onceAsyncByKey((id: string) => api.getUser(id), (id) => id); fetchUser("1"); fetchUser("1"); // 同 id 只请求一次
+ */
+export declare function onceAsyncByKey<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>, keyExtractor: (...args: Args) => string): (...args: Args) => Promise<T>;