nfx-ui 0.7.4 → 0.8.0

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

@@ -0,0 +1,21 @@
+/**
+ * 结果类型：成功为 [T, null]，失败为 [null, Error]。
+ * Result type: success [T, null], failure [null, Error].
+ * @template T - 成功时的值类型。Value type on success.
+ * @example const [data, err] = await withRetryResult(() => fetchData()); if (err) return; use(data);
+ */
+export type Result<T> = [T, null] | [null, Error];
+/**
+ * 构造成功结果。Create a successful result.
+ * @param v - 结果值。Result value.
+ * @returns [v, null]
+ * @example ok(42) // [42, null]
+ */
+export declare const ok: <T>(v: T) => Result<T>;
+/**
+ * 构造失败结果（非 Error 会包装为 Error）。Create a failed result; non-Error wrapped in Error.
+ * @param e - 错误或任意值。Error or any value.
+ * @returns [null, Error]
+ * @example err(new Error("fail")) // [null, Error]
+ */
+export declare const err: (e: unknown) => Result<never>;

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

@@ -0,0 +1,15 @@
+import { Options as RetryOptions } from 'async-retry';
+import { Result } from './result';
+export type WithRetryOptions = RetryOptions & {
+    /** 若返回 true 则不再重试，直接 bail。If true, do not retry and bail. */
+    isNonRetryable?: (e: Error) => boolean;
+};
+/**
+ * 带重试执行异步函数，成功返回 ok(value)，失败返回 err(error)。
+ * Retry async function until success or max attempts; returns Result.
+ * @param fn - 可接收 bail 与 attempt 的异步函数。Async function receiving bail and attempt.
+ * @param opts - async-retry 选项及 isNonRetryable。async-retry options and isNonRetryable.
+ * @returns Promise<Result<T>>
+ * @example const [data, err] = await withRetryResult(() => fetchData(), { retries: 3 });
+ */
+export declare function withRetryResult<T>(fn: (bail: (e: Error) => void, attempt: number) => Promise<T>, opts?: WithRetryOptions): Promise<Result<T>>;

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

@@ -0,0 +1,69 @@
+import { Nullable, Maybe, Nilable, Emptyable, Zeroable, Stringable, Array } from '../../types';
+/**
+ * 将 Nilable 规范为 Nullable：undefined 转为 null，null 与 T 原样返回。返回类型 Nullable<T>。
+ * Normalize Nilable to Nullable: convert undefined to null; null and T unchanged. Returns Nullable<T>.
+ * @param value - 可能为 null 或 undefined 的值 (value that may be null or undefined)
+ * @returns 若为 undefined 则 null，否则原值 (null if undefined, otherwise value)
+ * @example safeNullable(apiResponse.data) // undefined → null，便于区分「未设置」与「空」
+ */
+export declare function safeNullable<T>(value: Nilable<T>): Nullable<T>;
+/**
+ * 将 Nilable 规范为 Maybe：null 转为 undefined，undefined 与 T 原样返回。返回类型 Maybe&lt;T&gt;。等同 value ?? undefined。
+ * Normalize Nilable to Maybe: convert null to undefined; undefined and T unchanged. Returns Maybe&lt;T&gt;. Same as value ?? undefined.
+ * @param value - 可能为 null 或 undefined 的值 (value that may be null or undefined)
+ * @returns 若为 null 或 undefined 则 undefined，否则原值 (undefined if null/undefined, otherwise value)
+ * @example safeMaybe(product.price) // 代替 product.price ?? undefined
+ */
+export declare function safeMaybe<T>(value: Nilable<T>): Maybe<T>;
+/**
+ * 将 Emptyable 字符串规范为 Nilable：空字符串转为 undefined，null/undefined/非空串原样。返回类型 Nilable&lt;T&gt;。常用于表单、接口字段。
+ * Normalize Emptyable string to Nilable: "" to undefined; null, undefined, non-empty string unchanged. Returns Nilable&lt;T&gt;. For form/API fields.
+ * @param value - 可能为 null、undefined 或空字符串 (value that may be null, undefined or "")
+ * @returns 若为 "" 则 undefined，否则原值 (undefined if "", otherwise value)
+ * @example safeNilable(product.remark) // "" 也视为「无值」
+ */
+export declare function safeNilable<T extends string>(value: Emptyable<T>): Nilable<T>;
+/**
+ * 将 Nilable 数组规范为数组：null/undefined 转为 [] 或 defaultValue。返回类型 Array&lt;T&gt;（即 T[]）。
+ * Normalize Nilable array to array: null/undefined to [] or defaultValue. Returns Array&lt;T&gt; (i.e. T[]).
+ * @param value - 可能为 null 或 undefined 的数组 (array that may be null or undefined)
+ * @param defaultValue - 可选，当 value 为 null/undefined 时使用；缺省为 [] (optional default when value is null/undefined; default is [])
+ * @returns value ?? defaultValue ?? [] (never null/undefined)
+ * @example safeArray(product.tags) // product.tags ?? []
+ * @example safeArray(product.tags, ['default'])
+ */
+export declare function safeArray<T>(value: Nilable<Array<T>>, defaultValue?: Array<T>): Array<T>;
+/**
+ * 将 Nilable 数值规范为 Zeroable：null/undefined 转为 0。返回类型 Zeroable&lt;number&gt;（即 number，0 为兜底）。
+ * Normalize Nilable number to Zeroable: null/undefined to 0. Returns Zeroable&lt;number&gt; (number with 0 as fallback).
+ * @param value - 可能为 null 或 undefined 的数值 (number that may be null or undefined)
+ * @returns value ?? 0 (never null/undefined)
+ * @example safeZeroable(product.stock) // 代替 product.stock ?? 0
+ */
+export declare function safeZeroable(value: Nilable<number>): Zeroable<number>;
+/**
+ * 将 Emptyable 字符串规范为 Stringable：null/undefined/"" 转为 ""。返回类型 Stringable&lt;string&gt;（即 string，"" 为兜底）。
+ * Normalize Emptyable string to Stringable: null/undefined/"" to "". Returns Stringable&lt;string&gt; (string with "" as fallback).
+ * @param value - 可能为 null、undefined 或空字符串 (value that may be null, undefined or "")
+ * @returns 若为 null、undefined 或 "" 则 ""，否则原值 ("" if null/undefined/"", otherwise value)
+ * @example safeStringable(product.name) // 代替 product.name ?? ""
+ */
+export declare function safeStringable<T extends string>(value: Emptyable<T>): Stringable<T>;
+/**
+ * 若值为 null/undefined 则返回默认值，否则返回原值。等同 value ?? defaultValue。
+ * Return defaultValue when value is null/undefined, otherwise value. Same as value ?? defaultValue.
+ * @param value - 可能为 null 或 undefined 的值 (value that may be null or undefined)
+ * @param defaultValue - 默认值 (default value)
+ * @returns value ?? defaultValue
+ * @example safeOr(product.stock, 0)
+ * @example safeOr(product.name, '')
+ */
+export declare function safeOr<T, D>(value: Nilable<T>, defaultValue: D): T | D;
+/**
+ * 安全取数字：null/undefined/NaN 转为 undefined，合法数字原样。返回类型 Maybe&lt;number&gt;。
+ * Safe number: null/undefined/NaN to undefined; valid number unchanged. Returns Maybe&lt;number&gt;.
+ * @param value - 可能为 null、undefined 或非数字 (value that may be null, undefined or NaN)
+ * @returns 若为 null、undefined 或 NaN 则 undefined，否则数字 (undefined if null/undefined/NaN, otherwise number)
+ * @example safeNum(product.price) // 用于严格「有值才用」的场景
+ */
+export declare function safeNum(value: Nilable<number>): Maybe<number>;

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

@@ -0,0 +1,21 @@
+/** 可实例化的构造函数类型。Instantiable constructor type. */
+type Constructor<T extends object = object> = new (...args: unknown[]) => T;
+/**
+ * 单例工厂：将传入的构造函数包装为单例模式；Proxy 拦截 construct，多次 new 返回同一实例。
+ * Singleton factory: wrap constructor so that multiple new calls return the same instance.
+ *
+ * @template T - 实例类型（需为 object）。Instance type (must be object).
+ * @param className - 被包装的构造函数（class）。Constructor (class) to wrap.
+ * @returns 代理后的构造函数，调用时始终返回同一实例。Proxied constructor returning same instance.
+ *
+ * @example
+ * ```ts
+ * class MyService { ... }
+ * const SingletonService = singleton(MyService);
+ * const a = new SingletonService();
+ * const b = new SingletonService();
+ * console.log(a === b); // true
+ * ```
+ */
+export declare const singleton: <T extends object>(className: Constructor<T>) => Constructor<T>;
+export {};

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

@@ -0,0 +1,10 @@
+import { Nilable } from '../../types';
+/**
+ * 若值为 null/undefined 则抛出 Promise 使 React Suspense 挂起，否则返回该值。
+ * If value is null/undefined, throw a promise to suspend (React Suspense); otherwise return value.
+ * @param value - 待检查的值。Value to check.
+ * @param delay - 重试前的延迟（毫秒）。Delay in ms before retry.
+ * @returns 非空时的 value。Value when non-null.
+ * @example const data = suspenseIfNull(resource); // 在 Suspense 边界内，data 非空时才渲染
+ */
+export declare function suspenseIfNull<T>(value: Nilable<T>, delay?: number): T;

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

@@ -0,0 +1,49 @@
+/**
+ * 格式化日期为 YYYY/MM/DD（空或无效返回 ""）
+ * Format date as YYYY/MM/DD; empty or invalid returns "".
+ * @param dateString - 日期字符串
+ * @returns 格式化后的日期字符串，无效则 ""
+ */
+export declare const formatDisplayDate: (dateString: string | undefined | null) => string;
+/**
+ * 格式化为相对时间（如 2 days ago, 3 months ago）
+ * Format as relative time (e.g. 2 days ago, 3 months ago).
+ * @param dateString - 日期字符串
+ * @returns 相对时间字符串，无效为 "Invalid date"，空为 "Unknown"
+ */
+export declare const formatRelativeTime: (dateString: string | undefined | null) => string;
+/**
+ * 格式化 ISO 日期为图表轴/提示用短格式（如：Jan 4, 02:30 PM）
+ * Format ISO date for chart axis/tooltip (e.g. Jan 4, 02:30 PM).
+ * @param iso - ISO 日期字符串
+ * @returns 格式化字符串，解析失败则返回原串
+ */
+export declare function formatTickDate(iso: string): string;
+/**
+ * 格式化时间显示年月日时分 (YYYY/MM/DD HH:mm)
+ * Format date-time as year/month/day hour:minute.
+ * @param dateString - 时间字符串
+ * @returns 格式化后的时间字符串，无效则返回原串
+ */
+export declare const formatDateTime: (dateString: string) => string;
+/**
+ * 格式化时间显示月日时分 (MM/DD HH:mm)
+ * Format date-time as month/day hour:minute.
+ * @param dateString - 时间字符串
+ * @returns 格式化后的时间字符串，无效则返回原串
+ */
+export declare const formatMonthDayTime: (dateString: string) => string;
+/**
+ * 格式化日期仅年月日 (YYYY/MM/DD)，用于生日等
+ * Format date as year/month/day only.
+ * @param dateString - 日期字符串，如 "2000-01-15" 或 ISO
+ * @returns 格式化后的日期字符串，无效则返回原串
+ */
+export declare const formatDate: (dateString: string) => string;
+/**
+ * 格式化时间显示时分 (HH:mm)
+ * Format time as hour:minute.
+ * @param dateString - 时间字符串
+ * @returns 格式化后的时间字符串，无效则返回原串
+ */
+export declare const formatTime: (dateString: string) => string;

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

@@ -0,0 +1,10 @@
+/**
+ * 从字符串列表创建键值映射对象；可选 valueMapper 指定值
+ * Create record from string list; optional valueMapper for values.
+ * @param list - 字符串数组（作为键）
+ * @param valueMapper - 可选，(item, index) => value，缺省时值为键本身
+ * @returns Record<list[number], V>
+ * @example createMap(["a","b","c"]) // { a: "a", b: "b", c: "c" }
+ * @example createMap(["a","b","c"], (_, i) => i) // { a: 0, b: 1, c: 2 }
+ */
+export declare function createMap<T extends string, V = T>(list: ReadonlyArray<T>, valueMapper?: (item: T, index: number) => V): Record<T, V>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nfx-ui",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "type": "module",
   "sideEffects": false,
   "description": "Unified frontend UI library for the NFX product family: shared React components, design tokens, theme variables, and layout primitives for a consistent look and behavior across NFX console and other apps.",
@@ -14,103 +14,103 @@
   },
   "exports": {
     "./themes": {
-      "types": "./dist/themes.d.ts",
+      "types": "./dist/src/themes/index.d.ts",
       "import": "./dist/themes.mjs",
       "require": "./dist/themes.cjs",
       "default": "./dist/themes.mjs"
     },
     "./layouts": {
-      "types": "./dist/layouts.d.ts",
+      "types": "./dist/src/designs/layouts/index.d.ts",
       "import": "./dist/layouts.mjs",
       "require": "./dist/layouts.cjs",
       "default": "./dist/layouts.mjs"
     },
     "./components": {
-      "types": "./dist/components.d.ts",
+      "types": "./dist/src/designs/components/index.d.ts",
       "import": "./dist/components.mjs",
       "require": "./dist/components.cjs",
       "default": "./dist/components.mjs"
     },
     "./animations": {
-      "types": "./dist/animations.d.ts",
+      "types": "./dist/src/designs/animations/index.d.ts",
       "import": "./dist/animations.mjs",
       "require": "./dist/animations.cjs",
       "default": "./dist/animations.mjs"
     },
     "./hooks": {
-      "types": "./dist/hooks.d.ts",
+      "types": "./dist/src/hooks/index.d.ts",
       "import": "./dist/hooks.mjs",
       "require": "./dist/hooks.cjs",
       "default": "./dist/hooks.mjs"
     },
     "./preference": {
-      "types": "./dist/preference.d.ts",
+      "types": "./dist/src/preference/index.d.ts",
       "import": "./dist/preference.mjs",
       "require": "./dist/preference.cjs",
       "default": "./dist/preference.mjs"
     },
     "./stores": {
-      "types": "./dist/stores.d.ts",
+      "types": "./dist/src/stores/index.d.ts",
       "import": "./dist/stores.mjs",
       "require": "./dist/stores.cjs",
       "default": "./dist/stores.mjs"
     },
     "./apis": {
-      "types": "./dist/apis.d.ts",
+      "types": "./dist/src/apis/index.d.ts",
       "import": "./dist/apis.mjs",
       "require": "./dist/apis.cjs",
       "default": "./dist/apis.mjs"
     },
     "./events": {
-      "types": "./dist/events.d.ts",
+      "types": "./dist/src/events/index.d.ts",
       "import": "./dist/events.mjs",
       "require": "./dist/events.cjs",
       "default": "./dist/events.mjs"
     },
     "./services": {
-      "types": "./dist/services.d.ts",
+      "types": "./dist/src/services/index.d.ts",
       "import": "./dist/services.mjs",
       "require": "./dist/services.cjs",
       "default": "./dist/services.mjs"
     },
     "./navigations": {
-      "types": "./dist/navigations.d.ts",
+      "types": "./dist/src/navigations/index.d.ts",
       "import": "./dist/navigations.mjs",
       "require": "./dist/navigations.cjs",
       "default": "./dist/navigations.mjs"
     },
     "./types": {
-      "types": "./dist/types.d.ts",
+      "types": "./dist/src/types/index.d.ts",
       "import": "./dist/types.mjs",
       "require": "./dist/types.cjs",
       "default": "./dist/types.mjs"
     },
     "./utils": {
-      "types": "./dist/utils.d.ts",
+      "types": "./dist/src/utils/index.d.ts",
       "import": "./dist/utils.mjs",
       "require": "./dist/utils.cjs",
       "default": "./dist/utils.mjs"
     },
     "./constants": {
-      "types": "./dist/constants.d.ts",
+      "types": "./dist/src/constants/index.d.ts",
       "import": "./dist/constants.mjs",
       "require": "./dist/constants.cjs",
       "default": "./dist/constants.mjs"
     },
     "./languages": {
-      "types": "./dist/languages.d.ts",
+      "types": "./dist/src/languages/index.d.ts",
       "import": "./dist/languages.mjs",
       "require": "./dist/languages.cjs",
       "default": "./dist/languages.mjs"
     },
     "./icons": {
-      "types": "./dist/icons.d.ts",
+      "types": "./dist/src/icons/index.d.ts",
       "import": "./dist/icons.mjs",
       "require": "./dist/icons.cjs",
       "default": "./dist/icons.mjs"
     },
     "./pixel-blast": {
-      "types": "./dist/pixel-blast.d.ts",
+      "types": "./dist/src/designs/animations/PixelBlast/index.d.ts",
       "import": "./dist/pixel-blast.mjs",
       "require": "./dist/pixel-blast.cjs",
       "default": "./dist/pixel-blast.mjs"
@@ -216,9 +216,6 @@
   "overrides": {
     "vite": "^8.0.3",
     "esbuild": "^0.27.4",
-    "minimatch": "^10.2.4",
-    "@microsoft/api-extractor": {
-      "typescript": "~6.0.2"
-    }
+    "minimatch": "^10.2.4"
   }
 }

package/dist/animations.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/apis.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/components.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/constants.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/events.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/hooks.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/icons.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/languages.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/layouts.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/navigations.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/pixel-blast.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/preference.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/services.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/stores.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/themes.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/types.d.ts

@@ -1 +0,0 @@
-export { }

package/dist/utils.d.ts

@@ -1 +0,0 @@
-export { }