djm-ui 0.0.0-stage → 0.67.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DJM UI contributors
+
+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/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# DJM 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.
+面向企业级中后台的 Vue 3 组件库：100 个组件、明暗主题与品牌色、中英文文案、按钮权限，自带完整文档与无障碍校验。
+
+- 官网与文档：https://ui.duojumi.com
+- npm：https://www.npmjs.com/package/djm-ui
+
+## 环境要求
+
+- Vue 3.4+
+- 现代浏览器：Chrome / Edge / Firefox / Safari 最近两个大版本（不支持 IE）
+- 组件在挂载后访问 DOM，SSR 场景需在客户端调用 `initTheme()`，服务端只渲染结构
+
+## 安装
+
+```bash
+npm i djm-ui
+```
+
+## 使用
+
+### 全量注册
+
+```js
+import { createApp } from 'vue'
+import DjmUI from 'djm-ui'
+import 'djm-ui/styles'
+import App from './App.js'
+
+createApp(App)
+  .use(DjmUI, { locale: 'zh-CN' })
+  .mount('#app')
+```
+
+`.use(DjmUI, options)` 会注册全部组件与 `v-permission` 指令，`options.locale` 可省略，默认中文。
+
+### 按需引入
+
+ESM 产物支持 tree-shaking，按名字引入即可，未使用的组件不会进入打包结果：
+
+```js
+import { DjmButton, DjmTable } from 'djm-ui'
+import 'djm-ui/styles'
+```
+
+只要部分组件样式时，按依赖顺序引入基础样式与组件样式：
+
+```js
+import 'djm-ui/styles/tokens.css'          // 设计变量
+import 'djm-ui/styles/theme-dark.css'      // 暗色主题
+import 'djm-ui/styles/base.css'            // 基础重置与工具类
+import 'djm-ui/styles/components/button.css'
+import 'djm-ui/styles/components/motion.css' // 弹窗、抽屉等过渡动画
+```
+
+栅格由 Row / Col 两部分组成，按需引入走各自路径：
+
+```js
+import DjmRow from 'djm-ui/components/grid/row'
+import DjmCol from 'djm-ui/components/grid/col'
+```
+
+### CDN
+
+UMD 产物复用全局 Vue，不会重复打包 Vue。Vue 必须先加载：
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/djm-ui@0.67.2/dist/djm-ui.min.css" />
+<script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/djm-ui@0.67.2/dist/djm-ui.umd.min.js"></script>
+
+<script>
+  Vue.createApp({
+    template: '<DjmButton variant="primary">按钮</DjmButton>'
+  }).use(DjmUI).mount('#app')
+</script>
+```
+
+## 响应式
+
+组件按容器宽度自适应，不依赖具体业务布局，断点与行为如下：
+
+| 断点 | 行为 |
+|---|---|
+| ≤1320px | 顶部菜单布局收起横向菜单，改用侧栏抽屉 |
+| ≤960px | 侧栏改为抽屉；个人资料、修改密码等左右两栏改为上下堆叠 |
+| ≤760px | 栅格强制单列、横向表单标签上移、行内筛选竖排、列表页整页自然滚动；日期范围只显示一个月，日期时间面板改为上下排 |
+| ≤620px | 顶栏搜索收成图标，点开后铺满顶栏 |
+| ≤420px | 隐藏皮肤按钮、分页按钮压缩、日期区间上下排 |
+
+组件自身的窄屏处理：
+
+- 表格、周日程、甘特图、看板在容器内横向滚动，不把页面撑宽
+- 下拉、日期、颜色、树选择等浮层按视口自动向上翻转并限制在视口内，超高时面板内部滚动
+- 图标类按钮（清空、关闭、展开）在手机端扩大透明点击区，文字操作按钮补充高度
+- 动态字段、导入向导、批量操作条等复合组件在手机上改为单列排布
+
+## 主题与主色
+
+```js
+import { initTheme, toggleTheme, setPrimaryColor, resetPrimaryColor, PRESET_COLORS } from 'djm-ui'
+
+initTheme()                 // 启动时恢复上次选择
+toggleTheme()               // light / dark
+setPrimaryColor('#12855a')  // 自定义主色，自动推导整套色阶
+resetPrimaryColor()         // 回到默认蓝
+```
+
+## 国际化
+
+```js
+import { setLocale, localeState, t } from 'djm-ui'
+
+setLocale('en-US')
+localeState.code          // 当前语言
+t('table.empty')          // 取文案，支持 t('diff.expand', { count: 12 })
+```
+
+## 按钮权限
+
+```js
+import { setPermissions } from 'djm-ui'
+
+setPermissions(['user:add', 'user:edit'])
+```
+
+```html
+<DjmButton v-permission="'user:add'">新增用户</DjmButton>
+<DjmButton v-permission.disable="['user:export']">导出</DjmButton>
+```
+
+没有权限时元素被移除；加 `.disable` 修饰符则只禁用置灰。界面显隐不能替代服务端校验。
+
+## 构建产物
+
+| 文件 | 用途 |
+|---|---|
+| `dist/djm-ui.esm.js` / `.min.js` | 现代打包器入口，Vue 作为 peer 外置 |
+| `dist/djm-ui.cjs` / `.min.cjs` | CommonJS 环境 |
+| `dist/djm-ui.umd.js` / `.min.js` | 浏览器 `<script>`，读取全局 Vue |
+| `dist/djm-ui.css` / `.min.css` | 组件库样式，不含示例应用样式 |
+
+## 本地开发
+
+```bash
+npm run dev        # 官网 http://localhost:5180（首页落地页，/app/ 示例应用，/docs/ 文档）
+npm run docs       # 文档站 http://localhost:5181
+npm test           # 语法 + 类名命名空间 + 组件一致性审计
+npm run typecheck  # 类型声明校验
+npm run build      # 构建样式与 ESM / CJS / UMD
+npm run visual     # 视觉回归
+```
+
+## 官网部署
+
+官网跑在 `ui.duojumi.com`，宝塔静态站点，目录 `/www/wwwroot/ui.duojumi.com`：
+
+| 路径 | 内容 |
+|---|---|
+| `/` | 落地页（仓库根 `index.html`，自带 SEO meta 与 JSON-LD） |
+| `/app/` | 示例应用（`app/index.html`） |
+| `/docs/` | 组件文档（`docs/`） |
+| `/robots.txt`、`/sitemap.xml` | 搜索引擎配置 |
+
+文档页依赖仓库里的 `docs/`、`src/styles`、`vendor/` 保持相对路径，所以整块同步：
+
+```bash
+./scripts/deploy-docs.sh
+```
+
+脚本默认走 `root@100.112.203.74` + `~/.ssh/jzjl_deploy`，可用 `DJM_DOCS_HOST` / `DJM_DOCS_KEY` / `DJM_DOCS_PATH` 覆盖。Nginx 配置见 `deploy/nginx/ui.duojumi.com.conf`。
+
+## 发布
+
+```bash
+npm run release -- patch   # 或 minor / major / 1.2.3
+npm publish
+```
+
+发布前需在 `CHANGELOG.md` 顶部补好对应版本段落，脚本会拒绝在没有更新说明时改版本号。
+
+## 许可
+
+[MIT](./LICENSE)