@zjhc/ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,51 @@
+MIT License
+
+Copyright (c) 2026 zjhc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---------------------------------------------------------------------------
+
+This package contains code derived from third-party projects:
+
+Element Plus — https://github.com/element-plus/element-plus
+Copyright (c) 2020-PRESENT Element Plus
+Licensed under the MIT License (full text below)
+
+MIT License
+
+Copyright (c) 2020-PRESENT Element Plus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,23 @@
+# NOTICE
+
+This package is a Vue 3 component library built on top of Element Plus.
+
+## 第三方来源
+
+### Element Plus
+
+- 项目地址: https://github.com/element-plus/element-plus
+- 版权: Copyright (c) 2020-PRESENT Element Plus
+- 许可证: MIT
+
+本项目的部分实现（包括 `src/utils`、`src/hooks` 中的若干工具与 `theme-chalk`
+主题变量的组织方式）派生自 Element Plus，并按 MIT 许可证的要求保留其版权声明。
+完整许可证文本见 `LICENSE` 文件。
+
+Element Plus 本身作为 `peerDependency` 使用，不会被本包打包。
+
+## 归属说明
+
+`src/components` 下的业务组件（complex-table、search-panel、dialog、
+table-toolbar、sticky-toolbar 等）源自内部业务组件库（发布形态为 `@cacp/ui@0.3.24`），
+由本仓库维护并统一改用 `zjhc` 命名空间。其对外接口与实现版权归本仓库所有。

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# @zjhc/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+基于 [Element Plus](https://element-plus.org) 的 Vue 3 业务组件库，提供复杂表格、搜索面板、可折叠面板、可拖拽弹窗等中后台常用组件。
+
+## 特性
+
+- Vue 3 + TypeScript 编写，完整类型声明
+- 直接复用 Element Plus 的能力与主题变量，无需重复引入基础组件
+- 提供 ESM / CJS 双格式产物与独立样式文件
+- 统一 `zjhc` 命名空间：类名前缀 `.zjhc-*`、CSS 变量前缀 `--zjhc-*`
+- 主题可通过 `theme-chalk` 中的 SCSS 变量定制
+
+## 安装
+
+```bash
+npm install @zjhc/ui element-plus
+```
+
+`element-plus`、`vue`、`crypto-js` 是 peerDependencies，需要由使用方自行安装。
+
+## 使用
+
+### 全量引入
+
+```ts
+import { createApp } from 'vue'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import ZjhcUI from '@zjhc/ui'
+import '@zjhc/ui/dist/index.css'
+import App from './App.vue'
+
+createApp(App).use(ElementPlus).use(ZjhcUI).mount('#app')
+```
+
+全量注册后 `ZjhcLoading` 会同时注册 `v-zjhc-loading` 指令与 `$zjhcLoading` 全局方法。
+
+### 按需引入
+
+```vue
+<script setup lang="ts">
+import { ZjhcComplexTable } from '@zjhc/ui'
+</script>
+
+<template>
+  <ZjhcComplexTable :data="rows" :actions="actions" />
+</template>
+```
+
+样式只需引一次：
+
+```ts
+import '@zjhc/ui/dist/index.css'
+```
+
+若要按组件体积更省，可以只引对应组件的样式：
+
+```ts
+import '@zjhc/ui/theme-chalk/complextable.css'
+```
+
+### 加载指令
+
+```vue
+<script setup lang="ts">
+import { ZjhcLoading } from '@zjhc/ui'
+</script>
+
+<template>
+  <div v-zjhc-loading="loading">内容</div>
+</template>
+```
+
+也可以直接调服务：`ZjhcLoading.service({ text: '加载中' })`。
+
+## 组件
+
+| 组件 | 说明 |
+| --- | --- |
+| `ZjhcComplexTable` | 带分页、工具栏、操作列的复杂表格 |
+| `ZjhcTableToolbar` | 表格工具栏 / 按钮组 |
+| `ZjhcSearchPanel` | 搜索面板 |
+| `ZjhcSearchPanelLayout` | 搜索面板布局 |
+| `ZjhcSearchLayout` | 搜索区布局容器 |
+| `ZjhcCollapseContainer` / `ZjhcCollapsePanel` | 可折叠容器/面板 |
+| `ZjhcDialog` | 可最小化、拖拽、全屏的弹窗 |
+| `ZjhcGroupContainer` | 分组容器 |
+| `ZjhcStickyToolbar` | 吸顶工具栏 |
+| `ZjhcAutocomplete` | 增强自动完成 |
+| `ZjhcEditTableColumn` | 可编辑表格列 |
+| `ZjhcLoading` | 加载指令与服务 |
+
+同时还导出 `hooks`（`useNamespace`、`useDraggableResize`、`useLoading`、
+`useComplexTable` 等）、`utils` 与 `constants`。
+
+## 命名空间
+
+类名与 CSS 变量统一使用 `zjhc` 前缀，由 `useNamespace` 与
+`theme-chalk/src/mixins/config.scss` 的 `$namespace` 共同决定：
+
+```css
+.zjhc-complex-table { }
+.zjhc-complex-table__header { }
+.zjhc-dialog--fullscreen { }
+
+:root { --zjhc-color-primary: #409eff; }
+```
+
+需要改前缀时这两处必须同时改，否则类名与样式选择器会对不上。
+业务侧覆盖样式时也应使用 `--zjhc-*` 变量。
+
+## 主题定制
+
+`theme-chalk/src` 下是完整的 SCSS 源码，通过覆盖变量重新编译即可换肤：
+
+```bash
+sass --no-source-map theme-chalk/src/index.scss my-theme.css
+```
+
+或在业务项目里用 Vite 的 `css.preprocessorOptions.scss.additionalData` 注入变量覆盖：
+
+```ts
+additionalData: `@use "@zjhc/ui/theme-chalk/src/mixins/config.scss" as *;`
+```
+
+## 产物
+
+| 文件 | 说明 |
+| --- | --- |
+| `dist/index.mjs` | ESM 入口（约 135 KB，gzip 30 KB） |
+| `dist/index.cjs` | CommonJS 入口 |
+| `dist/index.d.ts` | 类型入口，配套 100+ 个按模块拆分的声明文件 |
+| `dist/index.css` | 完整样式，由 `theme-chalk/src/index.scss` 编译得到 |
+| `theme-chalk/index.css` | 与 `dist/index.css` 内容相同的别名，兼容老写法 |
+| `theme-chalk/<name>.css` | 单组件样式，供按需引入 |
+| `theme-chalk/dark.css` | 暗色模式变量 |
+| `theme-chalk/src/**` | SCSS 源码，供自定义主题 |
+
+`vue`、`element-plus`、`crypto-js`、`@vueuse/core`、`lodash-es` 都是外部依赖，不会被打进产物。
+
+> 关于 CJS：`element-plus` 的深层子路径（`element-plus/es/...`）只对 ESM 开放，
+> 直接 `require` 会报 `ERR_PACKAGE_PATH_NOT_EXPORTED`。构建时已对 CJS 产物做路径改写，
+> 指向同构的 `element-plus/lib/*.js`，因此 ESM 与 CJS 两种格式都能在纯 Node 环境加载。
+
+## 定制命名空间
+
+`zjhc` 前缀来自两个地方，改的时候要成对修改：
+
+- `src/hooks/use-namespace/index.ts` 的 `defaultNamespace`
+- `theme-chalk/src/mixins/config.scss` 的 `$namespace`
+
+改完执行 `npm run build`，`scripts/build-css.mjs` 会校验产物中不含旧前缀。
+
+## 开发
+
+```bash
+npm install
+npm run build      # 产出 dist/index.mjs、dist/index.cjs、dist/index.d.ts，以及全部 CSS
+npm run build:css  # 只重编样式（dist/index.css + theme-chalk/*.css）
+npm run type-check
+npm test           # 冒烟测试：导出完整性 + 命名空间 + SSR 渲染
+npm run test:consume  # 模拟真实安装，验证 ESM/CJS 与各样式路径可解析
+npm run preflight  # 发布前自检：registry / 登录 / 2FA / 版本占用 / 产物
+```
+
+## 发布
+
+```bash
+npm run preflight     # 自检：registry / 登录 / 2FA / 版本占用 / 产物
+npm run publish:otp   # 账号已开 2FA，必须带动态码，脚本会提示输入
+```
+
+`npm publish` 直接跑会报 `E403 ... 2FA ... required`，因为 registry 返回的是 **E403**
+而非 **EOTP**，npm 不会弹窗索要验证码。详见 [docs/publish.md](docs/publish.md) 第四节「坑 3」。
+
+## 许可证
+
+MIT。部分实现派生自 Element Plus（MIT），版权声明见 `LICENSE` 与 `NOTICE`。

package/dist/component.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from 'vue';
+declare const _default: Plugin[];
+export default _default;

package/dist/components/autocomplete/index.d.ts

@@ -0,0 +1,5 @@
+import { default as AutoComplete } from './src/autoComplete.vue';
+import { SFCWithInstall } from '../../utils';
+export declare const ZjhcAutocomplete: SFCWithInstall<typeof AutoComplete>;
+export default ZjhcAutocomplete;
+export * from './src/autocomplete';