@robot-admin/naive-ui-components 0.14.3 → 0.15.0

package/docs/engineering.en.md

@@ -0,0 +1,132 @@
+[← English README](../README_EN.md) · [中文](./engineering.md)
+
+# Development and build
+
+## Build Architecture
+
+### Six-stage Build Pipeline
+
+```
+bun run build
+  ├── 1. tsdown          → Multi-entry bundling (55 components ESM/CJS/DTS)
+  ├── 2. sass CLI        → Compile the shared-variable entry → global-scss.css
+  ├── 3. merge-css.js    → Merge Vue-compiled SFC CSS + global variables → style.css
+  ├── 4. gen-exports.js  → Auto-generate package.json exports map
+  ├── 5. check:dist      → Validate root, subpath, SSR, and DTS public exports
+  └── 6. check:size      → Enforce full/base CSS and package-size budgets
+```
+
+### Key Technical Details
+
+- **Build engine**: [tsdown](https://github.com/rolldown/tsdown) (Rolldown-based), 55 component entries plus the root entry and resolver
+- **SCSS processing**: Custom `scssTransformPlugin` compiles SFC SCSS within the Rolldown pipeline; standalone Sass CLI only compiles the shared-variable entry
+- **CSS merging**: Post-build merges Vue scoped-compiled per-chunk CSS with shared variables into a single `style.css`, avoiding duplicate styles and leaked raw `:deep()` selectors
+- **Type exports**: Unified `export *` barrel pattern with auto-generated `.d.ts`
+- **Subpath exports**: `gen-exports.js` auto-scans `dist/` and writes the `exports` field in `package.json`
+- **Export conflict detection**: `check-export-conflicts.js` ensures no naming collisions between components
+- **Artifact entry validation**: `check-dist-entries.js` prevents internal chunks from replacing root declarations and verifies component utility subpath types
+- **Package contract validation**: blocks Naive UI internal type paths, hidden optional installs, and plugin console side effects
+- **Size budgets**: `check-size-budget.js` prevents accidental growth of global, C_Form/C_Table, and total dist output
+- **Consumer budgets**: `check-consumer-size.js` builds four minimal Vite applications, sums gzip bytes along the emitted static JS import graph, and rejects eager editor, spreadsheet, screenshot, or print dependencies.
+
+### Build Output
+
+```
+dist/
+├── index.js / index.cjs / index.d.ts     # Main entry
+├── C_Form.js / C_Form.cjs / C_Form.d.ts  # Subpath entries (55 components)
+├── C_Form.base.css / C_Form.css         # Base/full style tiers
+├── C_Table.base.css / C_Table.css       # Base/full style tiers
+├── style.css                             # Merged full styles
+└── [chunk].js                            # Shared code chunks
+```
+
+## Development
+
+The environment baseline is Node.js 20.19.0+ and Bun 1.3.14. `.node-version`, `packageManager`, `engines`, and the frozen lockfile keep local and CI installs aligned.
+
+```bash
+bun install --frozen-lockfile # Install exactly from the lockfile
+bun run dev              # Dev mode (SCSS watch + tsdown watch)
+bun run build            # Full build
+bun run build:scss       # Compile global SCSS only
+bun run build:css        # Merge fresh tsdown CSS chunks; safely skips a finalized dist
+bun run build:exports    # Generate exports map only
+bun run check:exports    # Check export naming conflicts
+bun run check:dist       # Validate built JS / DTS public entries
+bun run check:consumer-contracts # Tarball consumer types and optional peer boundaries
+bun run check:package    # Validate dependencies, exports, and public source boundaries
+bun run check:quality    # Prevent any, console, and type-suppression debt regressions
+bun run check:audit      # Audit direct and transitive dependency vulnerabilities
+bun run check:size       # Enforce publish artifact size budgets
+bun run check:consumer-size # Check initial consumer bundles after building
+bun run type-check       # TypeScript type checking
+bun run test             # Run Bun unit tests
+bun run lint:check       # Oxlint + ESLint (check only)
+bun run lint:eslint      # Audit the existing ESLint rule backlog
+bun run verify           # Type, test, export, and build verification
+```
+
+Consumer budgets include Vue and Naive UI. The four applications are independent measurements and cannot be added to estimate one application's size. `C_Form/base` renders one input; `C_Table/base` renders one row and column. The other cases render one search input and one action button. Base CSS excludes the built-in rich-text editor styles. Dynamic JS is built and checked but excluded from initial bytes; using those features still loads it. This check measures transfer size, not browser interaction performance. Both `verify` and the pre-publish lifecycle include this gate.
+
+### Project Structure
+
+```
+naive-ui-components/
+├── src/
+│   ├── index.ts                     # Library entry (global registration + export * barrel)
+│   ├── styles/
+│   │   ├── variables.scss           # CSS variables (--c-*)
+│   │   └── global.scss              # Auto-generated shared-variable entry
+│   ├── components/
+│   │   └── C_[Name]/
+│   │       ├── index.vue            # Main component file
+│   │       ├── index.ts             # Barrel export
+│   │       ├── index.scss           # Component styles
+│   │       ├── types.ts             # Type definitions
+│   │       ├── constants.ts         # Constants
+│   │       ├── data.ts              # Static data
+│   │       ├── composables/         # Composable functions
+│   │       ├── components/          # Sub-components
+│   │       └── layouts/             # Layout variants (C_Form/C_AntV)
+│   ├── plugins/                     # highlight.js and other plugins
+│   └── utils/                       # Utility functions
+├── scripts/
+│   ├── gen-global-scss.js           # Generate global.scss (shared variables only)
+│   ├── watch-global-scss.js         # Dev mode SCSS watcher
+│   ├── merge-css.js                 # Merge CSS artifacts
+│   ├── gen-exports.js               # Auto-generate package.json exports
+│   └── check-export-conflicts.js    # Export naming conflict detection
+├── types/
+│   └── env.d.ts                     # .vue / .scss module declarations
+├── tsdown.config.ts                 # Build config (multi-entry + SCSS plugin + Vue plugin)
+└── tsconfig.json
+```
+
+### Adding a New Component
+
+1. Create `src/components/C_NewComponent/` directory
+2. Write `index.vue`, `index.ts` (barrel), `types.ts`
+3. Add `export * from './components/C_NewComponent'` in `src/index.ts`
+4. Add the component import and registration to the `components` array in `src/index.ts`
+5. Add the name to `componentNames` in `src/resolver.ts`
+6. Run `bun run verify` — build scripts will auto-generate subpath entries and exports mapping
+
+### Publishing
+
+```bash
+bun run changeset       # Record changes and release level
+bun run version         # Update package version and CHANGELOG
+bun run verify          # Run all pre-publish checks
+bun run release         # Publish pending Changesets releases
+```
+
+The official local Changesets changelog generator uses commit IDs and change summaries; `bun run version` does not require a GitHub token. npm authentication is still required for publishing. On Windows, if `bun run release` stalls while npm repeats `prepublishOnly`, first confirm `bun run verify` succeeds, then publish from PowerShell with `$env:npm_config_ignore_scripts='true'; bun run release`. This skips only the repeated lifecycle check, not the prerequisite verification.
+
+## Documentation assets
+
+Brand sources and exported PNGs are in [`assets/`](./assets/). See the [asset guide](./assets/README.md) for colors, logo usage and export instructions.
+
+## Architecture boundaries
+
+See [architecture and isolation](./architecture.en.md) for dependency direction, app-level ownership and future Element Plus adaptation.

package/docs/engineering.md

@@ -0,0 +1,133 @@
+[← 项目首页](../README.md) · [English](./engineering.en.md)
+
+# 开发与构建
+
+## 构建架构
+
+### 六阶段构建流水线
+
+```
+bun run build
+  ├── 1. tsdown          → 多入口打包（55 组件 ESM/CJS/DTS）
+  ├── 2. sass CLI        → 编译共享变量入口 → global-scss.css
+  ├── 3. merge-css.js    → 合并 Vue 编译后的 SFC CSS + 全局变量 → style.css
+  ├── 4. gen-exports.js  → 自动生成 package.json exports 映射
+  ├── 5. check:dist      → 校验根入口、子路径、SSR 及 DTS 公共导出
+  └── 6. check:size      → 校验全量/基础样式与发布包体积预算
+```
+
+### 技术要点
+
+- **构建引擎**：[tsdown](https://github.com/rolldown/tsdown)（基于 Rolldown），55 个组件入口，加主入口与 Resolver
+- **SCSS 处理**：自定义 `scssTransformPlugin` 在 Rolldown 管线内编译 SFC SCSS，独立 Sass CLI 仅编译共享变量入口
+- **CSS 合并**：构建后将 Vue 已完成 scoped 转换的 per-chunk CSS 与共享变量合并为单一 `style.css`，避免重复样式和原始 `:deep()` 选择器泄漏
+- **类型导出**：统一 `export *` barrel 模式，自动生成完整 `.d.ts`
+- **子路径导出**：`gen-exports.js` 自动扫描 `dist/` 并写入 `package.json` 的 `exports` 字段
+- **导出冲突检测**：`check-export-conflicts.js` 确保组件间无命名冲突
+- **产物入口校验**：`check-dist-entries.js` 防止内部 chunk 覆盖根声明，并保证组件工具的子路径类型完整
+- **包契约校验**：禁止 Naive UI 内部类型路径、隐式可选依赖和插件控制台副作用
+- **体积预算**：`check-size-budget.js` 阻止全量样式、C_Form/C_Table 样式和 dist 总量意外膨胀
+- **消费端预算**：`check-consumer-size.js` 用 Vite 构建四个最小消费应用，沿实际静态导入图累计首屏 JS gzip；同时检查编辑器、Excel、截图和打印依赖没有进入首屏。
+
+### 输出产物
+
+```
+dist/
+├── index.js / index.cjs / index.d.ts     # 主入口
+├── C_Form.js / C_Form.cjs / C_Form.d.ts  # 子路径入口（55 组件）
+├── C_Form.base.css / C_Form.css         # 基础/完整样式层级
+├── C_Table.base.css / C_Table.css       # 基础/完整样式层级
+├── style.css                             # 合并后的全量样式
+├── images/                               # Leaflet Marker/图层控件资源
+└── [chunk].js                            # 共享代码块
+```
+
+## 开发
+
+环境基线为 Node.js 20.19.0+ 与 Bun 1.3.14；仓库通过 `.node-version`、`packageManager`、`engines` 和冻结锁文件保持本地/CI 一致。
+
+```bash
+bun install --frozen-lockfile # 严格按锁文件安装依赖
+bun run dev              # 开发模式（SCSS watch + tsdown watch）
+bun run build            # 完整构建
+bun run build:scss       # 仅编译全局 SCSS
+bun run build:css        # 合并 tsdown 刚生成的 CSS chunk；已完成的 dist 会安全跳过
+bun run build:exports    # 仅生成 exports 映射
+bun run check:exports    # 检测导出命名冲突
+bun run check:dist       # 校验构建后的 JS / DTS 公共入口
+bun run check:consumer-contracts # 真实打包消费者类型与可选 peer 边界
+bun run check:package    # 校验依赖、导出和源码公共边界
+bun run check:quality    # 防止 any、console 与类型抑制债务反弹
+bun run check:audit      # 审计直接与传递依赖漏洞
+bun run check:size       # 校验发布产物体积预算
+bun run check:consumer-size # 构建后检查常用组件的消费端首屏预算
+bun run type-check       # TypeScript 类型检查
+bun run test             # 运行 Bun 单元测试
+bun run lint:check       # Oxlint + ESLint（只检查）
+bun run lint:eslint      # ESLint 存量规则审计
+bun run verify           # 类型、测试、导出和构建全量验证
+```
+
+消费端预算包含 Vue 和 Naive UI，四个独立场景分别测量，不能相加当作同一应用的体积。`C_Form/base` 为单输入字段，`C_Table/base` 为单列单行展示表格；另外测量一个输入查询和一个操作按钮。基础样式排除内置富文本编辑器样式。动态 JS 会完成构建检查，但不计入首屏；使用对应字段或功能时仍会加载。此检查衡量传输体积，不替代真实浏览器的交互性能测量。`verify` 和发布前生命周期均包含该门禁。
+
+### 项目结构
+
+```
+naive-ui-components/
+├── src/
+│   ├── index.ts                     # 库入口（全量注册 + export * barrel）
+│   ├── styles/
+│   │   ├── variables.scss           # CSS 变量 (--c-*)
+│   │   └── global.scss              # 自动生成的共享变量入口
+│   ├── components/
+│   │   └── C_[Name]/
+│   │       ├── index.vue            # 组件主文件
+│   │       ├── index.ts             # Barrel 导出
+│   │       ├── index.scss           # 组件样式
+│   │       ├── types.ts             # 类型定义
+│   │       ├── constants.ts         # 常量
+│   │       ├── data.ts              # 静态数据
+│   │       ├── composables/         # 组合式函数
+│   │       ├── components/          # 子组件
+│   │       └── layouts/             # 布局变体（C_Form/C_AntV）
+│   ├── plugins/                     # highlight.js 等插件
+│   └── utils/                       # 工具函数
+├── scripts/
+│   ├── gen-global-scss.js           # 生成 global.scss（仅共享变量）
+│   ├── watch-global-scss.js         # 开发模式 SCSS 监听
+│   ├── merge-css.js                 # 合并 CSS 产物
+│   ├── gen-exports.js               # 自动生成 package.json exports
+│   └── check-export-conflicts.js    # 导出命名冲突检测
+├── types/
+│   └── env.d.ts                     # .vue / .scss 模块声明
+├── tsdown.config.ts                 # 构建配置（多入口 + SCSS 插件 + Vue 插件）
+└── tsconfig.json
+```
+
+### 添加新组件
+
+1. 创建 `src/components/C_NewComponent/` 目录
+2. 编写 `index.vue`、`index.ts`（barrel）、`types.ts`
+3. 在 `src/index.ts` 中添加 `export * from './components/C_NewComponent'`
+4. 在 `src/index.ts` 中导入组件并加入 `components` 注册数组
+5. 在 `src/resolver.ts` 的 `componentNames` 中登记名称
+6. 运行 `bun run verify`—构建脚本会自动生成子路径入口和 exports 映射
+
+### 发布
+
+```bash
+bun run changeset       # 记录变更及版本级别
+bun run version         # 更新版本号与 CHANGELOG
+bun run verify          # 发布前完整验证
+bun run release         # 发布 Changesets 中待发布版本
+```
+
+变更日志使用 Changesets 官方本地生成器，根据 Changeset 与 Git 提交生成，无需额外 `GITHUB_TOKEN`。npm 发布仍需要有效的发布账号认证，凭据不得写入仓库。Windows 下如果 `bun run release` 在 npm 的 `prepublishOnly` 重复验证阶段停滞，可先单独确认 `bun run verify` 成功，再在 PowerShell 中用 `$env:npm_config_ignore_scripts='true'; bun run release` 发布；该设置仅跳过已手动完成的重复生命周期验证，不应省略前一步。
+
+## 文档资源
+
+品牌源文件与 PNG 导出位于 [`assets/`](./assets/)，配色、Logo 使用及导出方式见[资源说明](./assets/README.md)。
+
+## 架构边界
+
+依赖方向、应用所有权与后续 Element Plus 适配要求见[架构与隔离](./architecture.md)。