fast-element-plus 1.0.21 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to Fast.Element.Plus are documented in this file.
+
+## [2.0.1] - 2026-08-28
+
+### Changed
+
+- Externalized declared runtime dependencies from the ESM build so package managers resolve the installed dependency graph without copying third-party modules into `dist/node_modules`; the CDN IIFE remains self-contained.
+
+### Removed
+
+- Removed the redundant named `FastElementPlus` component namespace export; components remain available as tree-shakable named exports and the default export remains the complete Vue plugin.
+
+## [2.0.0] - 2026-08-28
+
+### Added
+
+- Added one typed ESM package entry for 26 Vue components, 6 directives, 3 browser UI hooks, constants, Decimal, and the complete application plugin.
+- Added Vue global component and directive declarations through `fast-element-plus/global`.
+- Added a separately minified CDN IIFE and a documented `fast-element-plus/style.css` entry.
+- Added strict type checking, local ESLint Flat Config, formatting checks, runtime tests, consumer type tests, package-contract tests, Publint, and Node.js 22/24 CI.
+- Added synchronized English and Chinese README and API references, runtime contract, contribution guidance, security policy, and development/release instructions.
+- Standardized repository-root publishing with one `package.json` and one root `dist/` directory.
+- Added an Element Plus `2.14.x` compatibility audit that checks native runtime Props and Emits and blocks unreviewed minor-version upgrades.
+- Added public Slot type exports and missing native events, Slots, and exposed methods for Form, Image, Tree, TreeSelect, SelectV2, and Table wrappers.
+- Added phone, tablet, and desktop responsive styles that follow Element Plus light/dark CSS Variables directly.
+
+### Changed
+
+- Established the TypeScript 6 and tsdown build pipeline.
+- Organized source code under `src/` and component styles under `styles/`.
+- Merged declaration generation into the root `tsconfig.json`.
+- Synchronized the complete applicable Fast.ESLint.Config rule set in the repository-local Flat Config while retaining explanatory Chinese comments.
+- Kept Vue, Element Plus, and both required icon implementations as external runtime peers, and moved the required Fast.Utils behavior into non-public `src/utils/` modules.
+- Documented Fast.Element.Plus as an officially open-source Fast business SDK rather than a drop-in Element Plus replacement.
+- Applied Element Plus default Props and MessageBox shortcut enhancements during root-module evaluation while keeping only CSS declared as a package side effect.
+- Preserved Fast default Props and MessageBox shortcut conventions while preventing caller option mutation and duplicate completion; MessageBox `beforeClose` callbacks close by default after settling.
+- Made remote Select, SelectPage, SelectV2, TreeSelect, Tree, and Table data loading resistant to stale request results.
+- Improved upload request configuration, concurrent loading state, native custom requests, removal hooks, and model synchronization.
+- Improved Dialog and Drawer model synchronization, accessibility, resizing, and cleanup while preserving Fast asynchronous `open` and `close` event semantics without duplicate native forwarding.
+- Restored the pre-Element Plus 2.14 empty `ElInput` clearable layout for Table, Tree, SelectPage, and dynamic Table search fields so hidden clear icons do not reserve space.
+- Scoped Table styles and added responsive IconSelector styling.
+- Improved dialogs, drawers, tables, forms, trees, selectors, car-number input, images, and uploads for dark mode, touch input, and narrow viewports.
+
+[2.0.1]: https://gitee.com/FastDotnet/fast.element.plus/releases/tag/v2.0.1
+[2.0.0]: https://gitee.com/FastDotnet/fast.element.plus/releases/tag/v2.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to Fast.Element.Plus
+
+Thank you for improving Fast.Element.Plus. Contributions should preserve a predictable Vue component API, explicit Element Plus behavior, and reproducible package output.
+
+## Requirements
+
+- Node.js `^22.18.0 || ^24.18.0`
+- pnpm `^11.0.0` through Corepack
+- Git with LF line endings
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+Use `pnpm dev` when a long-running tsdown watch build is useful during implementation.
+Use `pnpm docs:dev` to review component examples and documentation changes in the VitePress site.
+
+## Design rules
+
+- Keep the repository root as the only npm package and `dist/` as the only publication output.
+- Preserve the documented root, global-type, and style entries.
+- Reuse existing components, directives, hooks, constants, and `src/utils/` helpers before adding another abstraction.
+- Keep Vue and Element Plus external to package-manager builds; icon implementations and internal utilities remain bundled.
+- Do not access `window` or `document` during module import; resolve browser capabilities only when an API is called.
+- Avoid new runtime dependencies unless the platform and existing dependency set cannot provide the behavior safely.
+- Keep component state instance-local unless a documented global UI facility intentionally owns shared state.
+
+## Public API and comments
+
+Every public component, function, type, interface, method, property, option, prop, emit, slot, and exposed member must include TSDoc/JSDoc covering the applicable items:
+
+- purpose and non-obvious design rationale;
+- parameters, defaults, accepted ranges, and units;
+- return values, asynchronous behavior, and failure semantics;
+- Vue, Element Plus, browser, accessibility, and package-entry constraints;
+- a focused example when the signature alone is insufficient.
+
+Line comments must explain intent, constraints, lifecycle ordering, or compatibility behavior. Preserve useful existing comments. Do not translate syntax into prose, repeat the type signature, or add comments only to increase volume. Keep Chinese source comments clear and keep identifiers, package names, and API casing unchanged.
+
+## Tests
+
+- Add a regression test for every defect.
+- Add compile-only cases to `tests/public-api.test.ts` for public type behavior.
+- Keep runtime tests deterministic and independent of real network, credentials, timers, and user data.
+- Update both README files, API references, runtime contract, and tests when public behavior changes.
+
+Run the narrowest relevant command during development, then run the full set before opening a pull request:
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm docs:build
+pnpm format:check
+pnpm --config.ignore-scripts=true pack --dry-run
+```
+
+## Dependencies
+
+Development tools use reviewed caret ranges and are resolved exactly by `pnpm-lock.yaml`. Before changing a dependency:
+
+1. verify Node.js, Vue, Element Plus, and peer requirements;
+2. review public type and runtime effects;
+3. update only the pnpm lock file and relevant manifests;
+4. run type, lint, test, build, package, peer, and dry-run checks;
+5. avoid unrelated upgrades in the same pull request.
+
+This repository defines its own ESLint Flat Config and must not depend on `@fast-china/eslint-config`.
+
+## Pull requests
+
+- Keep the diff focused and avoid repository-wide formatting unrelated to the change.
+- Update English and Chinese docs for user-visible behavior.
+- Add a dated `CHANGELOG.md` entry only when preparing a release.
+- Describe component API, runtime, type, style, accessibility, security, and size impact.
+- Never include credentials, private endpoints, private assets, or production data.
+- Do not publish, tag, push, or deploy from a contribution workflow.
+
+## Security reports
+
+Do not open a public issue for a suspected vulnerability. Follow [SECURITY.md](./SECURITY.md).

package/README.md

@@ -1,164 +1,123 @@
-[中](https://gitee.com/FastDotnet/Fast.Element.Plus) | **En**
+[中文](./README.zh.md) | **English**
 
 <h1 align="center">Fast.Element.Plus</h1>
 
 <p align="center">
-  <code>Fast</code> platform An component library built based on <code>Vue3</code>, <code>Vite</code>, <code>TypeScript</code>, and <code>Element Plus</code>.
+	Typed Vue 3 components, directives, and hooks for business applications built on Element Plus.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/fast-element-plus">
-    <img src="https://img.shields.io/npm/v/fast-element-plus?color=orange&label=" alt="version" />
-  </a>
-  <a href="https://gitee.com/FastDotnet/Fast.Element.Plus/blob/master/LICENSE">
-    <img src="https://img.shields.io/npm/l/fast-element-plus" alt="license" />
-  </a>
+	<a href="https://www.npmjs.com/package/fast-element-plus"><img src="https://img.shields.io/npm/v/fast-element-plus?color=orange" alt="npm version" /></a>
+	<a href="https://gitee.com/FastDotnet/fast.element.plus/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/fast-element-plus" alt="license" /></a>
 </p>
 
-## Preface
+Fast.Element.Plus is an officially open-source Fast business SDK for the Fast team and developers who adopt its coding and interaction conventions. It provides opinionated form, selection, table, tree, upload, layout, dialog, drawer, image, icon, and utility components, plus installable directives, browser UI hooks, shared constants, global component types, and one complete `app.use()` plugin.
 
-#### Why would we encapsulate a component library based on `Element Plus`?
+The SDK builds business behavior on Element Plus and is not a drop-in replacement. Some defaults, event semantics, remote-data flows, and interactions intentionally follow Fast team conventions.
 
-  > **Predecessors plant trees, and future generations enjoy the shade**
-  > Because of my limited skills, I can only stand on the shoulders of giants and look far into the distance. (To put it bluntly, I am a vegetable)
-  > **Development efficiency**
-  > Because in actual business development, the efficiency of a simple `Element Plus` component library will be very low if used directly. * (But I did not say that `Element Plus` is not easy to use)*
-  > **Suitable encapsulation**
-  > On the contrary, it is precisely because it is easy to use that I encapsulated it, making it the most suitable and fastest development efficiency for me, or for those of us `engineers/developers` who only know `CRUD` every day.
+## Requirements
 
-## Install
-
-#### Standing on the shoulders of giants <a href="https://github.com/element-plus/element-plus">`Element Plus`</a>
-
-```
-Because the framework depends on Element Plus, you need to install Element Plus at the same time to use it properly.
-```
-
-#### Using a Package Manager
-
-```sh
-# Choose a package manager of your choice
+- ES2022 modern browsers or WebViews.
+- Vue `^3.5.41`.
+- Element Plus `^2.14.5`.
+- Element Plus Icons `^2.3.2`.
+- Fast.Element.Plus.Icons `^2.0.0`.
 
-# NPM
-npm install fast-element-plus
+Vue, Element Plus, Element Plus Icons, and Fast.Element.Plus.Icons are required peer dependencies. Both icon packages remain external to the build. Package managers install declared runtime dependencies automatically, and the ESM build keeps those imports external instead of copying them into `dist/node_modules`; the CDN IIFE bundles them for direct browser use. Component-only utilities are included in the Fast.Element.Plus build.
 
-# Yarn
-yarn add fast-element-plus
+The current manually audited Element Plus baseline is `2.14.x`. When the Element Plus minor version changes, for example from `2.14.x` to `2.15.x` or later, native Props, Emits, Slots, exposed methods, defaults, and internal style structures must be audited again. See [Element Plus compatibility and upgrade audit](./docs/ELEMENT_PLUS_COMPATIBILITY.md).
 
-# pnpm (recommend)
-pnpm install fast-element-plus
-```
-
-#### Direct browser import
-
-##### unpkg
-
-```html
-<head>
-  <!-- Import style -->
-  <link rel="stylesheet" href="//unpkg.com/element-plus/dist/index.css" />
-  <!-- Import Vue 3 -->
-  <script src="//unpkg.com/vue@3"></script>
-  <!-- Import Element Plus component library -->
-  <script src="//unpkg.com/element-plus"></script>
-  <!-- Import component library -->
-  <script src="//unpkg.com/fast-element-plus"></script>
-</head>
-```
+## Install
 
-##### jsDelivr
-
-```html
-<head>
-  <!-- Import style -->
-  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/element-plus/dist/index.css" />
-  <!-- Import Vue 3 -->
-  <script src="//cdn.jsdelivr.net/npm/vue@3"></script>
-  <!-- Import Element Plus component library -->
-  <script src="//cdn.jsdelivr.net/npm/element-plus"></script>
-  <!-- Import component library -->
-  <script src="//cdn.jsdelivr.net/npm/fast-element-plus"></script>
-</head>
+```bash
+pnpm add fast-element-plus vue element-plus @element-plus/icons-vue @fast-element-plus/icons-vue
 ```
 
 ## Use
 
-在 `main.ts`
+Register the complete component library:
 
-```typescript
+```ts
 import { createApp } from "vue";
-import ElementPlus from "element-plus";
 import "element-plus/dist/index.css";
 import FastElementPlus from "fast-element-plus";
+import "fast-element-plus/style.css";
 import App from "./App.vue";
 
-const app = createApp(App);
-
-// Global Registration
-app.use(FastElementPlus);
-
-app.mount('#app');
+createApp(App).use(FastElementPlus).mount("#app");
 ```
 
-#### Volar Support
+### Theme and responsive layout
 
-If you use Volar, specify the global component type via `compilerOptions.type` in your `tsconfig.json`.
+Fast.Element.Plus uses Element Plus CSS Variables and supports its official `html.dark` dark mode. Import the official dark variables before the Fast styles when dark mode is required:
 
-```json
-{
-  "compilerOptions": {
-    // ...
-    "types": ["fast-element-plus/global"]
-  }
-}
+```ts
+import "element-plus/dist/index.css";
+import "element-plus/theme-chalk/dark/css-vars.css";
+import "fast-element-plus/style.css";
+
+document.documentElement.classList.toggle("dark", isDark);
 ```
 
-## Update log
+Desktop is the base layout. Responsive rules cover phones below `768px` and tablets from `768px` through `1199px`, including dialogs, drawers, tables, search forms, pagination, trees, selectors, and upload areas. Applications may customize branding, surfaces, borders, shadows, and spacing through Element Plus CSS Variables.
 
-Update log [Click to view](https://gitee.com/FastDotnet/Fast.Element.Plus/commits/master)
+Or import named APIs and let the application control registration:
 
-## Protocol
+```ts
+import { FaButton, FaTable, useOverlay, vCopy } from "fast-element-plus";
 
-[Fast.Element.Plus](https://gitee.com/FastDotnet/Fast.Element.Plus) complies with the [Apache-2.0](https://gitee.com/FastDotnet/Fast.Element.Plus/blob/master/LICENSE) open source agreement. Welcome to submit `PR` or `Issue`.
+app.use(FaButton);
+app.use(FaTable);
+app.directive("copy", vCopy);
 
+useOverlay.show();
 ```
-Apache Open Source License
 
-Copyright © 2018-Now xiaoFang
+For global component and directive types, add the package type entry to the application `tsconfig.json`:
 
-License:
-This Agreement grants any individual or organization that obtains a copy of this software and its related documentation (hereinafter referred to as the "Software").
-Subject to the terms of this Agreement, you have the right to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the Software:
-1.All copies or major parts of the Software must retain this Copyright Notice and this License Agreement.
-2.The use, copying, modification, or distribution of the Software shall not violate applicable laws or infringe upon the legitimate rights and interests of others.
-3.Modified or derivative works must clearly indicate the original author and the source of the original Software.
+```jsonc
+{
+	"compilerOptions": {
+		"types": ["element-plus/global", "fast-element-plus/global"],
+	},
+}
+```
 
-Special Statement:
-- This Software is provided "as is" without any express or implied warranty of any kind, including but not limited to the warranty of merchantability, fitness for purpose, and non-infringement.
-- In no event shall the author or copyright holder be liable for any direct or indirect loss caused by the use or inability to use this Software.
-- Including but not limited to data loss, business interruption, etc.
+## Public modules
 
-Disclaimer:
-It is prohibited to use this software to engage in illegal activities such as endangering national security, disrupting social order, or infringing on the legitimate rights and interests of others.
-The author does not assume any responsibility for any legal disputes and liabilities caused by the secondary development of this software.
-```
+| Module     | Public APIs                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Components | `FaAvatar`, `FaButton`, `FaCarNumber`, `FaContextMenu`, `FaDialog`, `FaDrawer`, `FaForm`, `FaFormItem`, `FaFormItemTip`, `FaIcon`, `FaIconSelector`, `FaImage`, `FaInputDialogPage`, `FaLayoutGrid`, `FaLayoutGridItem`, `FaSelect`, `FaSelectOption`, `FaSelectPage`, `FaSelectV2`, `FaTable`, `FaTableColumn`, `FaTree`, `FaTreeSelect`, `FaUpload`, `FaUploadImage`, `FaUploadImages` |
+| Directives | `vCopy`, `vDebounce`, `vDraggable`, `vIconCopy`, `vLongpress`, `vThrottle`                                                                                                                                                                                                                                                                                                               |
+| Hooks      | `useLoading`, `useOverlay`, `useScreenFull`                                                                                                                                                                                                                                                                                                                                              |
+| Constants  | `FaMimeType`, `RegExps`                                                                                                                                                                                                                                                                                                                                                                  |
+| Utilities  | `Decimal`, `install`, `version`                                                                                                                                                                                                                                                                                                                                                          |
 
-## Disclaimer
+The package root is the only JavaScript API entry. `fast-element-plus/global` provides Vue global declarations, and `fast-element-plus/style.css` provides the component styles. Files under `dist/` are implementation details.
 
-```
-Please do not use it for projects that violate our country's laws
-```
+## CDN
 
-## Contributors
+The `unpkg` and `jsdelivr` fields select `dist/index.global.min.js`. Load Vue, Element Plus, Element Plus Icons, and Fast.Element.Plus.Icons first, then access the library as `globalThis.FastElementPlus`. Load `dist/index.css` separately.
 
-Thank you for all their contributions!
+## Documentation
 
-<a href="https://github.com/China-xiaoFang/Fast.Element.Plus/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=China-xiaoFang/Fast.Element.Plus" />
-</a>
+- [Component documentation and interactive examples (Chinese)](./docs/components/overview.md)
+- [Installation guide (Chinese)](./docs/guide/installation.md)
+- [Documentation build and deployment (Chinese)](./docs/guide/deployment.md)
+- [API reference](./docs/API.md)
+- [Runtime contract](./docs/RUNTIME_CONTRACT.md)
+- [Element Plus compatibility and upgrade audit](./docs/ELEMENT_PLUS_COMPATIBILITY.md)
+- [Development and release guide (Chinese)](./docs/DEVELOPMENT_RELEASE.zh-CN.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
 
-## Supplementary instructions
+Run the complete documentation site locally:
 
+```bash
+pnpm docs:dev
 ```
-If it is helpful to you, you can click ⭐Star in the upper right corner to collect it and get the latest updates. Thank you!
-```
+
+## License
+
+[Apache-2.0](./LICENSE)

package/README.zh.md

@@ -1,164 +1,123 @@
-**中** | [En](https://github.com/China-xiaoFang/Fast.Element.Plus)
+**中文** | [English](./README.md)
 
 <h1 align="center">Fast.Element.Plus</h1>
 
 <p align="center">
-  <code>Fast</code> 平台下基于 <code>Vue3</code>，<code>Vite</code>，<code>TypeScript</code>，<code>Element Plus</code> 构建的组件库。
+	基于 Element Plus 构建的 Vue 3 类型化业务组件、指令与 Hook。
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/fast-element-plus">
-    <img src="https://img.shields.io/npm/v/fast-element-plus?color=orange&label=" alt="version" />
-  </a>
-  <a href="https://gitee.com/FastDotnet/Fast.Element.Plus/blob/master/LICENSE">
-    <img src="https://img.shields.io/npm/l/fast-element-plus" alt="license" />
-  </a>
+	<a href="https://www.npmjs.com/package/fast-element-plus"><img src="https://img.shields.io/npm/v/fast-element-plus?color=orange" alt="npm 版本" /></a>
+	<a href="https://gitee.com/FastDotnet/fast.element.plus/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/fast-element-plus" alt="开源协议" /></a>
 </p>
 
-## 前言
+Fast.Element.Plus 是正式开源的 Fast 系列业务 SDK，面向 Fast 团队以及认同 Fast 团队编码与交互约定的开发者。它提供表单、选择器、表格、树、上传、布局、对话框、抽屉、图片、图标等约定式组件，以及可安装指令、浏览器 UI Hook、共享常量、全局组件类型和完整的 `app.use()` 插件。
 
-#### 为什么又会基于 `Element Plus` 去封装一层组件库呢？
+本 SDK 基于 Element Plus 进行业务增强，不承诺无差异替代 Element Plus 原生组件。部分默认 Props、事件语义、远程数据流程和交互行为会遵循 Fast 团队约定。
 
-  > **前人栽树 后人乘凉**
-  > 因为本人技术有限，导致只能站在巨人的肩膀上去遥望远方。（说白了就是菜）
-  > **开发效率**
-  > 因为在实际的业务开发中，单纯的 `Element Plus` 组件库如果直接使用的话效率会很低。*（但是我并没有说 `Element Plus` 不好用）*
-  > **适合的封装**
-  > 相反，恰恰是因为它好用，所以我才进行了封装，使其对于我来说，或者说对于我们这些每天只会 `CRUD` 的 `工程师/开发者` 来说，才是最合适的，开发效率最快的。
+## 环境要求
 
-## 安装
-
-#### 站在巨人肩膀上 <a href="https://github.com/element-plus/element-plus">`Element Plus`</a>
-
-```
-因框架依赖 Element Plus，所以需要同时安装 Element Plus 才可正常使用。
-```
-
-#### 使用包管理器
-
-```sh
-# 选择一个你喜欢的包管理器
+- 支持 ES2022 的现代浏览器或 WebView。
+- Vue `^3.5.41`。
+- Element Plus `^2.14.5`。
+- Element Plus Icons `^2.3.2`。
+- Fast.Element.Plus.Icons `^2.0.0`。
 
-# NPM
-npm install fast-element-plus
+Vue、Element Plus、Element Plus Icons 和 Fast.Element.Plus.Icons 均为强制 Peer Dependency。两套图标包保持在构建产物之外。包管理器会自动安装正式 Runtime Dependency，ESM 构建保留这些外部导入，不再将其复制到 `dist/node_modules`；CDN IIFE 仍会内联依赖以支持浏览器直接使用。组件内部工具包含在 Fast.Element.Plus 构建产物中。
 
-# Yarn
-yarn add fast-element-plus
+当前 Element Plus 人工审计基线为 `2.14.x`。当 Element Plus 次版本号发生变化，例如由 `2.14.x` 升级到 `2.15.x` 或更高时，必须重新核对封装涉及的原生 Props、Emits、Slots、Expose、默认值和内部样式结构，详见 [Element Plus 兼容性与升级核对](./docs/ELEMENT_PLUS_COMPATIBILITY.zh-CN.md)。
 
-# pnpm（推荐）
-pnpm install fast-element-plus
-```
-
-#### 浏览器直接引入
-
-##### unpkg
-
-```html
-<head>
-  <!-- 导入样式 -->
-  <link rel="stylesheet" href="//unpkg.com/element-plus/dist/index.css" />
-  <!-- 导入 Vue 3 -->
-  <script src="//unpkg.com/vue@3"></script>
-  <!-- 导入 Element Plus 组件库 -->
-  <script src="//unpkg.com/element-plus"></script>
-  <!-- 导入组件库 -->
-  <script src="//unpkg.com/fast-element-plus"></script>
-</head>
-```
+## 安装
 
-##### jsDelivr
-
-```html
-<head>
-  <!-- 导入样式 -->
-  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/element-plus/dist/index.css" />
-  <!-- 导入 Vue 3 -->
-  <script src="//cdn.jsdelivr.net/npm/vue@3"></script>
-  <!-- 导入 Element Plus 组件库 -->
-  <script src="//cdn.jsdelivr.net/npm/element-plus"></script>
-  <!-- 导入组件库 -->
-  <script src="//cdn.jsdelivr.net/npm/fast-element-plus"></script>
-</head>
+```bash
+pnpm add fast-element-plus vue element-plus @element-plus/icons-vue @fast-element-plus/icons-vue
 ```
 
 ## 使用
 
-在 `main.ts`
+注册完整组件库：
 
-```typescript
+```ts
 import { createApp } from "vue";
-import ElementPlus from "element-plus";
 import "element-plus/dist/index.css";
 import FastElementPlus from "fast-element-plus";
+import "fast-element-plus/style.css";
 import App from "./App.vue";
 
-const app = createApp(App);
-
-// 全局注册
-app.use(FastElementPlus);
-
-app.mount('#app');
+createApp(App).use(FastElementPlus).mount("#app");
 ```
 
-#### Volar 支持
+### 主题与响应式
 
-如果您使用 Volar，请在 `tsconfig.json` 中通过 `compilerOptions.type` 指定全局组件类型。
+Fast.Element.Plus 使用 Element Plus CSS Variables，并兼容其官方 `html.dark` 深色模式。需要深色模式时，在 Fast 样式之前额外导入官方深色变量：
 
-```json
-{
-  "compilerOptions": {
-    // ...
-    "types": ["fast-element-plus/global"]
-  }
-}
+```ts
+import "element-plus/dist/index.css";
+import "element-plus/theme-chalk/dark/css-vars.css";
+import "fast-element-plus/style.css";
+
+document.documentElement.classList.toggle("dark", isDark);
 ```
 
-## 更新日志
+基础样式以 PC 为默认布局，并为手机（小于 `768px`）和平板（`768px` 至 `1199px`）提供弹窗、抽屉、表格、搜索表单、分页、树、选择器和上传区域的响应式规则。业务应用可通过 Element Plus CSS Variables 调整品牌色、表面、边框、阴影和间距。
 
-更新日志 [点击查看](https://gitee.com/FastDotnet/Fast.Element.Plus/commits/master)
+也可以使用具名 API，由应用自行控制注册范围：
 
-## 协议
+```ts
+import { FaButton, FaTable, useOverlay, vCopy } from "fast-element-plus";
 
-[Fast.Element.Plus](https://gitee.com/FastDotnet/Fast.Element.Plus) 遵循 [Apache-2.0](https://gitee.com/FastDotnet/Fast.Element.Plus/blob/master/LICENSE) 开源协议，欢迎大家提交 `PR` 或 `Issue`。
+app.use(FaButton);
+app.use(FaTable);
+app.directive("copy", vCopy);
 
+useOverlay.show();
 ```
-Apache开源许可证
 
-版权所有 © 2018-Now 小方
+如需全局组件和指令类型，在应用 `tsconfig.json` 中加入包类型入口：
 
-许可授权：
-本协议授予任何获得本软件及其相关文档（以下简称“软件”）副本的个人或组织。
-在遵守本协议条款的前提下，享有使用、复制、修改、合并、发布、分发、再许可、销售软件副本的权利：
-1.所有软件副本或主要部分必须保留本版权声明及本许可协议。
-2.软件的使用、复制、修改或分发不得违反适用法律或侵犯他人合法权益。
-3.修改或衍生作品须明确标注原作者及原软件出处。
+```jsonc
+{
+	"compilerOptions": {
+		"types": ["element-plus/global", "fast-element-plus/global"],
+	},
+}
+```
 
-特别声明：
-- 本软件按“原样”提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、适用性和非侵权的保证。
-- 在任何情况下，作者或版权持有人均不对因使用或无法使用本软件导致的任何直接或间接损失的责任。
-- 包括但不限于数据丢失、业务中断等情况。
+## 公开模块
 
-免责条款：
-禁止利用本软件从事危害国家安全、扰乱社会秩序或侵犯他人合法权益等违法活动。
-对于基于本软件二次开发所引发的任何法律纠纷及责任，作者不承担任何责任。
-```
+| 模块 | 公开 API                                                                                                                                                                                                                                                                                                                                                                                 |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 组件 | `FaAvatar`、`FaButton`、`FaCarNumber`、`FaContextMenu`、`FaDialog`、`FaDrawer`、`FaForm`、`FaFormItem`、`FaFormItemTip`、`FaIcon`、`FaIconSelector`、`FaImage`、`FaInputDialogPage`、`FaLayoutGrid`、`FaLayoutGridItem`、`FaSelect`、`FaSelectOption`、`FaSelectPage`、`FaSelectV2`、`FaTable`、`FaTableColumn`、`FaTree`、`FaTreeSelect`、`FaUpload`、`FaUploadImage`、`FaUploadImages` |
+| 指令 | `vCopy`、`vDebounce`、`vDraggable`、`vIconCopy`、`vLongpress`、`vThrottle`                                                                                                                                                                                                                                                                                                               |
+| Hook | `useLoading`、`useOverlay`、`useScreenFull`                                                                                                                                                                                                                                                                                                                                              |
+| 常量 | `FaMimeType`、`RegExps`                                                                                                                                                                                                                                                                                                                                                                  |
+| 工具 | `Decimal`、`install`、`version`                                                                                                                                                                                                                                                                                                                                                          |
 
-## 免责申明
+包根入口是唯一 JavaScript API 入口；`fast-element-plus/global` 提供 Vue 全局声明，`fast-element-plus/style.css` 提供组件样式。`dist/` 下的其他文件均为实现细节。
 
-```
-请勿用于违反我国法律的项目上
-```
+## CDN
 
-## 贡献者
+`unpkg` 和 `jsdelivr` 字段都指向 `dist/index.global.min.js`。页面先加载 Vue、Element Plus、Element Plus Icons 和 Fast.Element.Plus.Icons，再通过 `globalThis.FastElementPlus` 访问组件库。样式需单独加载 `dist/index.css`。
 
-感谢他们的所做的一切贡献！
+## 文档
 
-<a href="https://github.com/China-xiaoFang/Fast.Element.Plus/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=China-xiaoFang/Fast.Element.Plus" />
-</a>
+- [组件文档与交互案例](./docs/components/overview.md)
+- [安装与使用](./docs/guide/installation.md)
+- [文档站构建与部署](./docs/guide/deployment.md)
+- [API 参考](./docs/API.zh-CN.md)
+- [运行时契约](./docs/RUNTIME_CONTRACT.md)
+- [Element Plus 兼容性与升级核对](./docs/ELEMENT_PLUS_COMPATIBILITY.zh-CN.md)
+- [开发与发布指南](./docs/DEVELOPMENT_RELEASE.zh-CN.md)
+- [贡献指南](./CONTRIBUTING.md)
+- [安全策略](./SECURITY.md)
+- [更新日志](./CHANGELOG.md)
 
-## 补充说明
+本地运行完整文档站：
 
+```bash
+pnpm docs:dev
 ```
-如果对您有帮助，您可以点右上角 ⭐Star 收藏一下 ，获取第一时间更新，谢谢！
-```
+
+## 开源协议
+
+[Apache-2.0](./LICENSE)