sky-ui-kit 0.0.0-stage → 0.1.0

package/docs/COMPONENT-LIBRARY.md

@@ -0,0 +1,79 @@
+# 主题接入规则更新
+
+当前规则以 [CSS-THEME.md](CSS-THEME.md) 为准：库不导出主题 store、不要求 Pinia，保留原项目 store；库 CSS 为变量提供低优先级默认值。默认 style.css 隔离，global.css 为可选整站主题。
+
+# 组件库组织与兼容约定
+
+## 三层结构
+
+| 层 | 入口 | 内容 |
+|---|---|---|
+| 基础组件 | components / Ui 前缀 | Element Plus 组件原实现的统一出口，加载项目主题 CSS |
+| 项目组件 | components / 原组件名 | 项目下拉框、时间轴、菜单、地图工具、标题、面板开关与过程表格 |
+| 主题 | 根入口 / style.css | 隔离 CSS、六色默认值、尺寸和状态变量；global.css 可选 |
+
+预览网站与包代码分开：src/components 是发布组件；App.vue、各 Preview.vue、CodeExample.vue、examples.ts、site.css 仅用于文档。业务接口和地图运行时不进入组件库。
+
+## 基础组件如何兼容
+
+基础组件调用 Element Plus 原实现，包装层转发属性、事件、插槽、v-model 与实例 ref，并自动添加主题作用域。ConfigProvider、Option、TableColumn、TabPane 保留原组件。浮层默认行为、附加 DOM 和局部主题限制见 [CSS-THEME.md](CSS-THEME.md)。原生 ElInput 在库作用域外保留原外观；UiInput 使用库主题。
+
+基于项目实际引用覆盖全部 56 个 Element Plus 组件 / 服务，另外提供 CheckboxGroup、RadioButton、Divider 等示例所需组件。`v-loading` 对应 `vUiLoading`；ElMessage / ElMessageBox / ElNotification 保留服务调用方式，对应 UiMessage / UiMessageBox / UiNotification。精确清单见 src/components/element-plus.ts 和 ALL-USED-COMPONENTS.md。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { UiInput, UiSelect, UiOption, UiCheckbox, UiCheckboxGroup,
+  UiButton, UiMessage, vUiLoading } from 'sky-ui-kit/components'
+import 'element-plus/dist/index.css'
+import 'sky-ui-kit/style.css'
+const name = ref('')
+const region = ref('yangtze')
+const checked = ref(['rain'])
+const busy = ref(false)
+function save() { UiMessage.success('已保存：' + name.value) }
+</script>
+<template>
+  <div v-ui-loading="busy">
+    <UiInput v-model="name" clearable placeholder="名称" />
+    <UiSelect v-model="region">
+      <UiOption label="长江流域" value="yangtze" />
+    </UiSelect>
+    <UiCheckboxGroup v-model="checked">
+      <UiCheckbox value="rain">降雨</UiCheckbox>
+    </UiCheckboxGroup>
+    <UiButton type="primary" @click="save">保存</UiButton>
+  </div>
+</template>
+```
+
+使用方可以继续注册 Element Plus 全局插件，也可以按组件显式导入。库不自动安装 Pinia、不注册全局组件、不覆盖 Element Plus 的全局注册名。
+
+## 两种下拉框不要混淆
+
+- UiSelect = ElSelect；UiSelectV2 = ElSelectV2，保持各自官方 API。
+- AppSelect 是项目现有 SelectV2 包装，提供 options 归一化和项目专用浮层外观，保留原调用兼容。
+- 不将 AppSelect 冒充 ElSelect 的完全替代。原页面用 el-option 子节点时应换 UiSelect，原页面用 options 属性的 AppSelect 可以直接换包 AppSelect。
+
+## 项目层 API
+
+| 组件 | 值 / 控制 | 事件与业务接线 |
+|---|---|---|
+| AppSelect | v-model、options | change 返回选中值 |
+| TreeSelectPanel | v-model、categories、dark | change / select 返回节点与分类 |
+| TimeRangeQuickSelect | v-model、options | change 返回范围选项 |
+| MapTimeline | v-model、v-model:playing/startTime/speed | change 返回 TimelinePoint；play / pause |
+| ProjectMenu | v-model:active、items / groups | select 返回菜单项，item.icon 为 Vue 组件；分组折叠内部处理 |
+| MapSideMenu | v-model:active/compact、items | select 返回菜单项；搜索与折叠内部处理；单分类 |
+| MapTools | v-model:active、icons | tool-click 返回 key，context-change 返回 boolean；刷新定位由应用接入 |
+| AtlasMapTitle | title / subtitle / rightOpen | 绝对定位，不处理业务 |
+| AtlasRightToggleButton | open | toggle，由应用控制面板 |
+| ProcessDataTable | times / series / loading | 内部分页，缺测 — |
+
+## 发布后替换策略
+
+基础组件优先只改 import / 标签名，原绑定和插槽保持不变。项目层采用 INTEGRATION.md 的路径映射；菜单和地图工具是适配替换，不能直接删掉原业务控制代码。主题采用单一 store，不让两个 store 同时写根变量。迁移每个页面时记录 API 差异和真实业务回归结果。
+
+## 当前状态
+
+整理后的源码可在开发网站使用；用户要求不运行构建，因此本次未更新 dist。发布前必须重新生成产物并检查打包，不能直接发布旧 dist。尚未发布，包名仍暂定，所有业务组件尚未完全迁移。

package/docs/CSS-THEME.md

@@ -0,0 +1,59 @@
+# CSS 变量主题与样式隔离
+
+库不导出 useThemeStore，也不依赖使用方 Pinia。根入口和 /components 导出相同组件。
+
+## 默认：隔离模式
+
+```ts
+import 'element-plus/dist/index.css'
+import 'sky-ui-kit/style.css'
+import { UiButton, UiSelect, AppSelect } from 'sky-ui-kit'
+```
+
+style.css 不向 :root 写入主题或尺寸变量，不包含裸 .el-* 覆盖规则。组件自动创建 userssite-theme 作用域，Element Plus 适配规则只在这个范围内生效。原生 ElButton 等放在库组件作用域之外时保留原来的外观；放在库组件插槽内部时，会继承这个范围的主题，这是预期行为。
+
+库内部使用 --userssite-* 私有变量，以 var(--color-primary, 默认值) 等形式读取项目已有变量，不回写公共变量。项目只定义部分变量时，其余使用库默认值。无需主题 store。
+
+```css
+:root {
+  --color-primary: #1677ff;
+  --color-bg: #ffffff;
+  --color-text: #1f2937;
+  --color-panel: #ffffff;
+}
+```
+
+已有项目全局 CSS 若自行覆盖 --el-* 或 .el-*，其自身仍会影响原生 Element Plus；隔离模式不会撤销项目已有规则。尺寸读取项目 --cp-vfit-scale，未定义时为 1。
+
+## 浮层与兼容边界
+
+- UiSelect、日期选择、Popover 等支持 teleported 的组件默认 false，使浮层保留祖先主题；需要时可以显式设置 true。这样可能受祖先 overflow 裁剪，使用方需按布局选择。
+- 支持 popperClass、modalClass 的组件自动合并 userssite-theme，保留用户类名。弹窗、抽屉移到 body 时仍拥有隔离默认主题。
+- UiMessage、UiMessageBox、UiNotification 以及 vUiLoading 给其浮层加专用类；原生 ElMessage 和 v-loading 不自动套用库主题。
+- 挂到 body 的浮层读取 html / :root 的项目变量。只在局部容器定义的变量不会跨 Teleport 继承；需将共享主题放在根节点，或通过 Element Plus 的 append-to 指定有主题变量的目标容器。消息服务无局部容器主题上下文。
+- ConfigProvider、Option、TableColumn、TabPane 保留原组件，依靠所属控件的主题作用域，避免破坏配置注入和父子组件关系。
+- 包装层转发 attrs、事件、slots 和实例 ref；UiSelect 默认浮层行为与原生有上述差别，DOM 中增加 display: contents 主题容器。依赖直属子节点的 CSS 和复杂布局迁移仍需核对。
+
+## 可选：整站主题
+
+```ts
+import 'element-plus/dist/index.css'
+import 'sky-ui-kit/style.css'
+import 'sky-ui-kit/global.css'
+```
+
+只有主动导入 global.css 才会写入全局公共变量和 --el-*，以及覆盖整站 .el-* 外观。此模式用于明确需要统一替换原项目主题的场景。
+
+## 默认暗色
+
+在 html 添加 theme-dark 类即可让库组件使用暗色默认值。若项目自己定义了同名颜色变量，项目变量优先，暗色也应由项目更新这些变量。预览站使用自己的 Pinia 调色面板并显式加载全局主题，不代表使用方需要 Pinia。
+
+## 验证与发布
+
+开发验证页 /isolation.html 将原生组件和库组件并排展示：局部紫色主题只作用于库组件。页面包含按钮事件、下拉框 v-model、弹窗和消息服务。
+
+本次不运行构建、不发布；dist 为旧产物。后续发布时构建脚本分别生成隔离 style.css 和可选 global.css。
+
+## 示例代码组织
+
+公共 CSS 只在项目 main.ts 引入一次。预览站的公共接入代码单独维护在 src/setup-examples.ts，各组件的查看代码只列组件 import、状态、事件与模板。查看代码中的接入链接指向公共配置；复制组件代码不会附带重复 CSS。已有 Element Plus CSS 引入时无需再添加。

package/docs/INTEGRATION.md

@@ -0,0 +1,71 @@
+# 主题接入规则更新
+
+当前规则以 [CSS-THEME.md](CSS-THEME.md) 为准：库不导出主题 store、不要求 Pinia，保留原项目 store；库 CSS 为变量提供低优先级默认值。默认 style.css 隔离，global.css 为可选整站主题。
+
+# 发布与反向接入
+
+## 当前交付范围
+
+本包是现有项目公共主题及组件的独立快照，不是原平台业务 SDK。全页面盘点见 PAGE-INVENTORY.md；全部原组件依赖见 COMPONENT-INVENTORY.md。扫描是完整源码静态读取，业务页面尚未逐页运行验证。尚未发布，不应现在把主项目全部替换。
+
+## 默认视觉
+
+| 项目 | 默认值 |
+|---|---|
+| 明亮六色 bg / text / primary / border / surface / panel | #ffffff / #1f2937 / #1677ff / #dbe3ef99 / #ffffffd9 / #ffffff |
+| 暗色六色 | #08111f / #e6edf7 / #4da3ff / #39506f99 / #101b2dee / #0c1525 |
+| 字号 micro / caption / body / title / heading | 10 / 13 / 14 / 16 / 18 px |
+| 圆角 small / medium / large / pill | 4 / 8 / 12 / 999 px |
+| 间距 small / medium / large | 6 / 10 / 16 px |
+| 控件 small / medium / large | 28 / 32 / 36 px |
+| 布局 header / sidebar / rightpanel / gutter | 58 / 244 / 320 / 10 px |
+| 动画 | 160 / 240ms，关闭时 0ms |
+| 阴影 | soft；支持 none / strong |
+| 字体 | HarmonyOS Sans SC + 系统中文回退；不包含字体文件 |
+
+派生变量、Element Plus 适配变量在 src/styles/theme.css、src/styles/element-plus.css；动态派生在 src/stores/theme.ts。默认缩放为 1，原项目仍需由 VFit 同步 `--cp-vfit-scale`。六色是可编辑基础，地图菜单和时间轴的语义配色单独保留。地图标题暗色下仍保留原项目的深色地图文字行为。
+
+## 组件替换映射
+
+| 原路径 | 包出口 | 兼容与接入事项 |
+|---|---|---|
+| common/AppSelect.vue | AppSelect | 保留 options、v-model、change、popperClass；补充数组值类型，避免同时加载旧组件 CSS |
+| common/TreeSelectPanel.vue | TreeSelectPanel | categories、v-model、select、change；dark 由主题传入；motion-v 外部依赖 |
+| common/MapTimeline.vue | MapTimeline | 保留 points、startTime、时区、步进、播放等 API；不会自己查询预报接口 |
+| common/TimeRangeQuickSelect.vue | TimeRangeQuickSelect | v-model 为 key；change 返回选项 |
+| atlas/AtlasMapTitle.vue | AtlasMapTitle | title 必填；绝对定位，父容器须 relative；rightOpen 留出右面板宽度 |
+| atlas/AtlasRightToggleButton.vue | AtlasRightToggleButton | open + toggle；使用方控制面板状态 |
+| atlas/ProcessDataTable.vue | ProcessDataTable | times / series 必填；loading 可选；100 条一页，缺测显示 — |
+| layout/Header.vue 的菜单部分 | ProjectMenu horizontal | **不是 Header 的直接替代**；业务路由、品牌、用户权限继续留在主项目 |
+| layout/SideMenu.vue 的菜单部分 | ProjectMenu vertical | groups / items / active；通过 select 接入路由，权限筛选由使用方完成 |
+| layout/SideMenuMap.vue 的菜单部分 | MapSideMenu | 当前单分类；搜索、折叠、compact、select；多业务分类须适配后替换 |
+| map/MapToolbar.vue 的工具部分 | MapTools | active、icons、tool-click、context-change；图层、定位、刷新及 GIS 逻辑留在原项目 |
+
+`ProjectMenuItem.icon`、`MapMenuItem.icon` 接受 Vue 组件，`MapTools.icons` 为 key → Vue 图标组件。图标从 @element-plus/icons-vue 导入；横向 ProjectMenu 沿用纯文字样式。示例代码在预览站可查看 / 复制。
+
+## 留在主项目的组件
+
+Header / SideMenu / MainLayout 的路由、权限、用户和布局状态；LayerControl 与地图 stores；各工程详情、视频全景、GIS 分析面板；业务 Legend 色带；BatchInfoPopover 的气象批次转换；区域选择器的行政区 JSON 和 API；图表的业务 option。AtlasRankingPanel / AtlasProcessPanel 只有插槽和类名，本身没有完整样式，不能据此宣称抽取完面板。TableLayout 含雨量等级、虚拟列表和数据格式化，应分离为无业务数据表后再进入包。
+
+所有未迁入组件都有原源码依赖清单，不能把它们默认为已支持。原生 btn 及地图 popup 样式当前仍在主项目 theme.css 的后半段，包仅提取变量区；迁移时必须保留这一段。
+
+## 按步骤反向接入
+
+1. 样式确认后确定 npm 包名 / scope、版本和许可证，删除 private，执行 typecheck、build、pack --dry-run 后发布。预览站用暂定包名，发布后更新文档示例。
+2. 主项目安装精确版本，保留 Vue / Pinia / Element Plus / motion-v / icons 依赖。先在独立分支接入一个非核心页面验证，不修改所有页面。
+3. main.ts 保持 Element Plus CSS 在前，包 style.css 在后。默认隔离；只有主动整站换肤时才额外引入 global.css。
+4. 选择原 theme store 继续作为单一主题控制者（推荐首轮）：先只迁组件和 CSS；保持原 `app-theme` 配置、RightPanel 和 App.vue 的 watch。不在此阶段引入包 store。
+5. 保留原项目 store、RightPanel 和 app-theme 配置；库只读取项目 CSS 变量，不导出 store，也不接管 localStorage。
+6. 旧 theme.css 拆成业务残留样式和字体声明；VFit 尺寸变量保留一个来源。不要删除全局 btn、地图 popup、字体、base.css 后才发现页面失去样式。
+7. 先替换 common 四个组件的 import，页面 props / events 原样保留。按 PAGE-INVENTORY 的依赖列逐页检查，而不是按文件名批量替换所有 CSS。
+8. 菜单与地图工具使用薄适配层：现有 routes 转成 items / groups；select 内调用原路由函数；tool-click 分发到原刷新、定位、面板方法；context-change 更新 ui store。原权限、地图引用、业务请求继续留在应用侧。
+9. 检查 Teleport 浮层、下拉宽度、暗色、键盘焦点、禁用、时间轴时区 / 范围 / 播放、图表和数据等级色带、1920×912 VFit 及窄屏。关闭页面后检查定时器与监听器释放。
+10. 删除旧组件必须先确认 rg 找不到引用，保留 codex-keep / @preserve 和用户注释。不要运行全项目格式化。升级完成记录 npm 精确版本和页面核对结果。
+
+## 回退
+
+保留迁移前分支和旧主题 JSON。回退时恢复旧 imports、CSS 顺序、原 store 与 app-theme 键；去掉包 CSS。主题迁移不要清空旧 localStorage。项目已有未提交修改，不应以重置整个工作区方式回退。
+
+## 验收门槛
+
+包：typecheck / build / npm pack 内容、公开导出及依赖清单。应用：typecheck / build、每个迁移页面运行核对、实际 API 和地图事件接线、明暗截图与业务回归。当前自动扫描与预览站构建不能替代实际业务验收。

package/package.json

@@ -1,6 +1,60 @@
-{
-  "name": "sky-ui-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "sky-ui-kit",
+  "version": "0.1.0",
+  "description": "Vue UI components compatible with Element Plus and the project theme",
+  "type": "module",
+  "files": [
+    "dist",
+    "docs/CSS-THEME.md",
+    "docs/COMPONENT-LIBRARY.md",
+    "docs/INTEGRATION.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components.js"
+    },
+    "./style.css": "./dist/style.css",
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components.js"
+    },
+    "./components.css": "./dist/style.css",
+    "./global.css": "./dist/global.css"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5180 --strictPort",
+    "build": "vite build && vite build --config vite.package.config.ts && node scripts/build-package.mjs && vue-tsc -p tsconfig.package.json",
+    "typecheck": "vue-tsc --noEmit",
+    "preview": "vite preview --host 127.0.0.1 --port 5180",
+    "prepack": "npm run build:package",
+    "build:package": "vite build --config vite.package.config.ts && node scripts/build-package.mjs && vue-tsc -p tsconfig.package.json"
+  },
+  "peerDependencies": {
+    "element-plus": "^2.14.2",
+    "vue": "^3.4.21",
+    "@element-plus/icons-vue": "^2.3.2",
+    "motion-v": "^2.3.0"
+  },
+  "devDependencies": {
+    "@element-plus/icons-vue": "^2.3.2",
+    "@vitejs/plugin-vue": "^4.5.2",
+    "element-plus": "^2.14.2",
+    "esbuild": "^0.18.20",
+    "motion-v": "^2.6.0",
+    "pinia": "^2.1.7",
+    "sass": "^1.101.0",
+    "typescript": "^5.4.2",
+    "vite": "^4.5.0",
+    "vue": "^3.4.21",
+    "vue-tsc": "^3.3.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "UNLICENSED"
+}