nfx-ui 0.7.3 → 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.3",
+  "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/README

@@ -1,323 +0,0 @@
-# NFX-UI — Unified Frontend UI Library
-
-**NFX-UI** is the shared frontend UI library of the NebulaForgeX ecosystem. It provides React components, design tokens, theme system, layout primitives, i18n, and utilities for a consistent look and behavior across NFX Console and other applications. Built with **React 18/19**, **TypeScript**, and **Vite** (library mode), NFX-UI is distributed as ESM/CJS with inlined styles and full type definitions—no separate CSS import required.
-
-<div align="center">
-  <img src="https://github.com/NebulaForgeX/NFX-UI/raw/main/docs/image1.png" alt="NFX-UI Logo" width="200">
-</div>
-
----
-
-## How to use in your app
-
-### 1. Install
-
-- **Option A:** After publishing to npm, run `npm install nfx-ui` in your app.
-- **Option B:** When unpublished, run `npm run build` and `npm link` in NFX-UI, then `npm link nfx-ui` in your app.
-- If your environment requires a script (e.g. `source /volume1/use-menv.sh`) before npm, run it first.
-
-```bash
-# Option A (in your app)
-npm install nfx-ui
-
-# Option B
-# Step 1: in NFX-UI repo
-cd /path/to/NFX-UI
-npm run link
-
-# Step 2: in your app
-cd /path/to/your-app
-npm link nfx-ui
-```
-
-### 2. Peer dependencies
-
-Your project must have `react` and `react-dom` (^18.0.0 or ^19.0.0). For themes, charts, etc., you may need `lucide-react`, `recharts`, `@tanstack/react-query`, `zustand` (see NFX-UI `package.json` peerDependencies).
-
-### 3. Usage
-
-Use **subpath imports**; no separate CSS import. Components have typed props; use `import type { ... } from "nfx-ui/..."` for types; styles are inlined.
-
-```tsx
-import { ThemeProvider } from "nfx-ui/themes";
-import { LanguageProvider } from "nfx-ui/languages";
-import { LayoutProvider } from "nfx-ui/layouts";
-import { Button, Input } from "nfx-ui/components";
-import type { LanguageEnum } from "nfx-ui/languages";
-import type { ApiErrorBody } from "nfx-ui/types";
-
-export function App() {
-  return (
-    <ThemeProvider defaultTheme="default">
-      <LanguageProvider>
-        <LayoutProvider>
-          <Button>Confirm</Button>
-          <Input placeholder="Enter" />
-        </LayoutProvider>
-      </LanguageProvider>
-    </ThemeProvider>
-  );
-}
-```
-
-### 4. Full steps in another project
-
-1. **Environment:** If required, run `source /volume1/use-menv.sh` (or your local equivalent) before any npm commands.
-2. **Install or link:** Published: `npm install nfx-ui`. Unpublished: run `npm run link` in NFX-UI, then `npm link nfx-ui` in this project.
-3. **Peer deps:** Ensure `react` and `react-dom` (v18 or v19) are in your project.
-4. **Optional runtime deps:** When using themes, icons, charts, etc., install `lucide-react`, `@tanstack/react-query`, `recharts`, `zustand` in your app (versions compatible with NFX-UI’s `package.json`).
-5. **Wrap with Providers:** Wrap your root with `ThemeProvider`, `LanguageProvider`, `LayoutProvider`, etc. (see code above).
-6. **Import by subpath:** `import { Button } from "nfx-ui/components"`, `import { useTheme } from "nfx-ui/themes"`, etc.; use `import type { ... } from "nfx-ui/types"` for types.
-7. **Build & run:** Use your usual scripts (`npm run dev` / `npm run build`); the bundler will resolve nfx-ui and tree-shake unused exports.
-
----
-
-## What’s included
-
-Main modules and contents below; full component and API docs: [docs/](./docs/).
-
-| Module        | Contents |
-|---------------|----------|
-| **themes**    | ThemeProvider, useTheme, theme vars |
-| **languages** | LanguageProvider, i18n, useLanguageLabel, useThemeLabel |
-| **layouts**   | LayoutProvider, Sidebar, Header, Footer, Background |
-| **components**| Button, Input, Dropdown, Slider, VirtualList, SlideDownSwitcher, etc. |
-| **animations**| WaveBackground, ECGLoading, TruckLoading, BounceLoading, etc. |
-| **hooks**     | makeUnifiedQuery, makeUnifiedInfiniteQuery |
-| **preference**| User preference (e.g. profile.preference) |
-| **types**     | Shared TypeScript types |
-| **utils**     | getApiErrorMessage, formatDisplayDate, retry, etc. |
-| **constants** | Query key factories, defineEnum |
-
----
-
-## Development (this repo)
-
-### Setup
-
-This repo is library-only: no dev server or demo; test via `npm link` in a real app. Run `npm install` after clone.
-
-```bash
-npm install
-```
-
-### Build
-
-Run `npm run build`. Output in `dist/`: ESM (`.mjs`), CJS (`.cjs`), and `.d.ts`; styles inlined.
-
-```bash
-npm run build
-```
-
-### Build messages and warnings
-
-You may see these during build; both are safe to ignore:
-1. **TypeScript version:** vite-plugin-dts uses an older TS in API Extractor; the “consider upgrading API Extractor” message does not affect type output.
-2. **PLUGIN_TIMINGS:** Plugin timing breakdown; informational only.
-
-### Test locally (npm link)
-
-1. In NFX-UI: `npm run link`.
-2. In your app: `npm link nfx-ui`.
-3. After changing NFX-UI, run `npm run build` in NFX-UI again.
-
-### Lint & format
-
-`npm run lint` for ESLint; `npm run lint:code-format` for Prettier check; `npm run format` for Prettier write.
-
-```bash
-npm run lint
-npm run lint:code-format
-npm run format
-```
-
----
-
-## Project structure
-
-`src/` contains entry and modules; path alias `@/` (points to `src/`) is used in this repo.
-
-```
-src/
-├── designs/       # layouts, components, animations
-├── languages/      # i18n, LanguageProvider, useLanguageLabel, etc.
-├── themes/         # ThemeProvider, useTheme, theme data
-├── hooks/          # makeUnifiedQuery, makeUnifiedInfiniteQuery
-├── preference/     # User preference
-├── types/          # Shared types
-├── utils/          # Helpers
-├── constants/      # Query keys, enums
-├── stores/         # Zustand stores
-├── events/         # EventEmitter
-├── apis/           # API path helpers
-└── ...
-```
-
----
-
-## License
-
-[MIT](LICENSE) — see [LICENSE](LICENSE) for details.
-
----
-
----
-
-# NFX-UI — 统一前端 UI 库
-
-**NFX-UI** 是 NebulaForgeX 生态的统一前端 UI 库，提供 React 组件、设计令牌、主题系统、布局基元、多语言与工具函数，为 NFX 控制台及其他应用提供一致的外观与交互。基于 **React 18/19**、**TypeScript** 与 **Vite**（库模式）构建，以 ESM/CJS 发布，样式内联、类型完整，使用方无需单独引入 CSS。
-
----
-
-## 外部项目如何使用
-
-### 1. 安装
-
-- **方式 A**：发布到 npm 后，在业务项目中执行 `npm install nfx-ui`。
-- **方式 B**：未发布时，在 NFX-UI 目录执行 `npm run build` 与 `npm link`，在业务项目目录执行 `npm link nfx-ui`。
-- 若本机约定先加载环境（如 `source /volume1/use-menv.sh`），请在执行任何 npm 命令前先执行。
-
-```bash
-# 方式 A（在业务项目）
-npm install nfx-ui
-
-# 方式 B
-# 步骤 1：在 NFX-UI 仓库
-cd /path/to/NFX-UI
-npm run link
-
-# 步骤 2：在要使用 NFX-UI 的项目
-cd /path/to/your-app
-npm link nfx-ui
-```
-
-### 2. 依赖要求
-
-你的项目需已安装 `react`、`react-dom`（^18.0.0 或 ^19.0.0）。若使用主题、图表等，可能还需按需安装 `lucide-react`、`recharts`、`@tanstack/react-query`、`zustand` 等（见 NFX-UI 的 `package.json` peerDependencies）。
-
-### 3. 在代码里使用
-
-使用**子路径导入**，无需单独引入 CSS。组件直接使用即有 props 类型提示；类型通过 `import type { ... } from "nfx-ui/..."` 获取；样式已内联。
-
-```tsx
-import { ThemeProvider } from "nfx-ui/themes";
-import { LanguageProvider } from "nfx-ui/languages";
-import { LayoutProvider } from "nfx-ui/layouts";
-import { Button, Input } from "nfx-ui/components";
-import type { LanguageEnum } from "nfx-ui/languages";
-import type { ApiErrorBody } from "nfx-ui/types";
-
-export function App() {
-  return (
-    <ThemeProvider defaultTheme="default">
-      <LanguageProvider>
-        <LayoutProvider>
-          <Button>确定</Button>
-          <Input placeholder="请输入" />
-        </LayoutProvider>
-      </LanguageProvider>
-    </ThemeProvider>
-  );
-}
-```
-
-### 4. 其他项目中的完整步骤示例
-
-在「别的项目」里从零用上 NFX-UI 的推荐顺序：
-
-1. **确保环境**：若团队要求，先执行 `source /volume1/use-menv.sh`（或你本机的等价命令）。
-2. **安装或链接**：已发布：`npm install nfx-ui`。未发布：在 NFX-UI 里执行 `npm run link`，再在本项目执行 `npm link nfx-ui`。
-3. **确认 peer**：项目里已有 `react`、`react-dom`（版本 18 或 19）。
-4. **按需装运行时依赖**：用到主题/图标/图表等时，在业务项目安装 `lucide-react`、`@tanstack/react-query`、`recharts`、`zustand` 等（与 NFX-UI 的 `package.json` 一致或兼容）。
-5. **在入口外包一层 Provider**：在根组件外包上 `ThemeProvider`、`LanguageProvider`、`LayoutProvider` 等（见上面代码）。
-6. **按子路径引入**：`import { Button } from "nfx-ui/components"`，`import { useTheme } from "nfx-ui/themes"` 等；类型用 `import type { ... } from "nfx-ui/types"`。
-7. **构建与运行**：按你项目原有方式（如 `npm run dev` / `npm run build`）即可，打包器会从 nfx-ui 解析并做 tree-shaking。
-
----
-
-## 包含模块
-
-下表为包内主要模块与内容；完整组件与 API 见 [docs/](./docs/)。
-
-| 模块         | 内容 |
-|--------------|------|
-| **themes**   | ThemeProvider、useTheme、主题变量 |
-| **languages**| LanguageProvider、i18n、useLanguageLabel、useThemeLabel |
-| **layouts**  | LayoutProvider、Sidebar、Header、Footer、Background |
-| **components** | Button、Input、Dropdown、Slider、VirtualList、SlideDownSwitcher 等 |
-| **animations** | WaveBackground、ECGLoading、TruckLoading、BounceLoading 等 |
-| **hooks**    | makeUnifiedQuery、makeUnifiedInfiniteQuery |
-| **preference** | 用户偏好（如 profile.preference） |
-| **types**    | 共享 TypeScript 类型 |
-| **utils**    | getApiErrorMessage、formatDisplayDate、retry 等 |
-| **constants**| Query key 工厂、defineEnum 等 |
-
----
-
-## 本仓库开发
-
-### 安装依赖
-
-本仓库为纯库，无 dev 服务器或 demo，需在真实应用中通过 `npm link` 测试。克隆后执行 `npm install` 安装依赖。
-
-```bash
-npm install
-```
-
-### 构建
-
-执行 `npm run build`，产物在 `dist/`：ESM（.mjs）、CJS（.cjs）、类型（.d.ts），样式已内联。
-
-```bash
-npm run build
-```
-
-### 构建时的提示与警告
-
-构建过程中可能出现以下提示，均可忽略，不影响产物：
-1. **TypeScript 版本提示**：vite-plugin-dts 内置的 API Extractor 使用较旧 TS 版本，项目使用 5.9.x 时会提示 “consider upgrading API Extractor”，类型仍会正确生成。
-2. **PLUGIN_TIMINGS**：Vite 输出的插件耗时统计，仅作参考，无需处理。
-
-### 本地联调（npm link）
-
-1. 在 NFX-UI 目录执行 `npm run link`。
-2. 在消费项目中执行 `npm link nfx-ui`。
-3. 修改 NFX-UI 后需在 NFX-UI 目录再次执行 `npm run build` 才能生效。
-
-### 代码检查与格式化
-
-`npm run lint` 运行 ESLint；`npm run lint:code-format` 检查 Prettier；`npm run format` 执行 Prettier 格式化。
-
-```bash
-npm run lint
-npm run lint:code-format
-npm run format
-```
-
----
-
-## 项目结构
-
-`src/` 下为入口与各模块；本仓库内使用路径别名 `@/`（指向 `src/`）。
-
-```
-src/
-├── designs/       # layouts、components、animations
-├── languages/     # i18n、LanguageProvider、useLanguageLabel 等
-├── themes/        # ThemeProvider、useTheme、主题数据
-├── hooks/         # makeUnifiedQuery、makeUnifiedInfiniteQuery
-├── preference/    # 用户偏好
-├── types/         # 共享类型
-├── utils/         # 工具函数
-├── constants/     # Query keys、枚举等
-├── stores/        # Zustand stores
-├── events/        # EventEmitter
-├── apis/          # API path 等
-└── ...
-```
-
----
-
-## 许可证
-
-[MIT](LICENSE) — 详见 [LICENSE](LICENSE)。

package/dist/animations.d.ts

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