sky-ui-kit 0.1.7 → 0.1.9

package/docs/CSS-THEME.md

@@ -1,5 +1,9 @@
 # CSS 变量主题与样式隔离
 
+MapPageLayout 使用 --map-layout-layer-content/panel/legend/toolbar/focus/hover 统一区域层级。与原平台一致：content=1、panel=2、legend=3、toolbar=4、focus=5、hover=6，时间轴和右栏同样参与；hover 高于 focus；content 内部即使使用较大 z-index 也不跨越区域堆叠上下文。图例和底部外层允许内容溢出，避免浮层被父区域裁剪；内部滚动由业务组件负责。
+
+MapPageLayout 是新增独立区域布局，读取现有主题变量及库作用域默认变量，不改写全局颜色。所有面板的 hover 层级高于 focus-within；右栏始终按固定区域关系避让。旧 TemplateLayout 的业务选择器保留以兼容已有消费者，新布局不继承这些选择器。MapPageLayout 与 DefenseMapLayout structured 模式继承 VFit 尺寸变量，不在 720px 以下切换布局；会商网格按 minmax(0, 1fr) 均分剩余高度，默认模式保留兼容。
+
 库不导出 useThemeStore，也不依赖使用方 Pinia。根入口和 /components 导出相同组件。
 
 ## 默认：隔离模式
@@ -238,3 +242,43 @@ import { DefenseMapLayout, UiButton } from 'sky-ui-kit'
 
 
 按需 JS 入口不改变 CSS 约定，style.css 仍为整体公共样式，不是逐组件 CSS。
+
+
+模型工作区主题限定 .sky-model-workspace，theme 属性控制明暗，原生控件适配显式开启；变量与边界见 MODEL-WORKSPACE.md。
+
+
+独立 model-workspace.css 面向原生 HTML，无 Vue/Element Plus 样式依赖；与 style.css 的模型主题来自同一源文件，Vue 无需重复导入。
+
+
+## 2026-11-03：可配置 VFit 尺寸（源码待发布）
+
+数字尺寸代表设计单位，由组件转换为 `calc(var(--cp-font-1, 1px) * n)`；CSS 字符串原样使用，不额外注册 VFit 或 transform。DesignSpacing 支持单值及2/3/4项数组，遵循CSS间距顺序。0是有效值。调用方传裸字符串 `"12"` 不是合法CSS长度，应使用 `:gap="12"`；`"12px"` 是固定CSS像素。
+
+所有新增参数有默认值；下表空字符串表示使用组件现有布局/样式默认值，不是0。根style可控制组件根尺寸，内部内边距通过对应props调整，无需deep覆盖。
+
+| 组件 | 参数与默认值 |
+| --- | --- |
+| MapPageLayout | 新增gap=12；已有rightPanelWidth=328、leftPanelWidth=320、edge=12等参数兼容字符串并支持数字；top/bottom/toolbar/timeline偏移默认空字符串，沿用自动避让 |
+| DefenseMapLayout | gap=4、padding=4、toolbarGap=12、toolbarPadding=12；topOffset默认64设计单位，兼容数字/字符串 |
+| MapWorkspacePanel | headerPadding=16、bodyPadding=16、footerPadding=[12,16]、gap=16 |
+| ModelWorkspacePanel | headerPadding=[12,16]、bodyPadding=16、footerPadding=[12,16]、gap=12 |
+| WorkbenchPanel | width='auto'、height='auto'、padding=0、gap=0；gap只在调用方使用flex/grid时产生间距，不强改display |
+| ManagementResourceLayout | gap=20、padding=[0,24,20]（内容区域）、introPadding=24、filterGap=20、filterPadding=[20,24]、inputWidth=260、selectWidth=160、cascaderWidth=280、responsive=false |
+| AppSelect | width='100%'、controlHeight=''（按size取主题小/中/大高度）、controlPadding=[0,10]；多选内容可增高；浮层不再设100%最小宽度，使用底层fit-input-width等配置 |
+| ProjectMenu | width=''、itemHeight=''、itemPadding=''、padding=''（分别保留横/纵菜单已有默认值）、gap=2 |
+| MapTimeline | padding=[10,12]、gap=9、trackHeight=88、controlHeight=30；不改变播放/时次数据API |
+| MapBottomProcessPanel | height=320、maxHeight='42dvh'、headerPadding=[10,16]、metaPadding=[8,16,0]、gap=12 |
+| ProcessDataTable | cellPadding=[6,10]、paginationGap=12、paginationPadding=5 |
+
+ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切换；旧调用方如需原断点布局显式传responsive=true。这是需要在升级说明中说明的行为变化。其内容区域padding与介绍区padding分开，避免改变原默认留白。
+
+地图布局时间轴测量改为offsetHeight，使用布局坐标而非transform后的视口像素，防止再次乘入缩放系数。UiButton/UiSelect/UiTable等基础组件继续使用底层size、width、height及主题token，无重复同义接口。旧TemplateLayout保留兼容接口，不冒充MapPageLayout别名。
+
+示例：
+```vue
+<MapWorkspacePanel title="降水统计" :header-padding="[12, 16]" :body-padding="[8, 12]" :gap="8">
+  业务内容
+</MapWorkspacePanel>
+<MapPageLayout :right-panel-width="320" :edge="12" :gap="8" />
+```
+预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。

package/docs/ELEMENT-PLUS-COVERAGE.md

@@ -1,6 +1,6 @@
 # Element Plus 完整组件目录
 
-基准版本：2.14.7。共 111 个主 / 子组件、4 个服务出口、3 个指令出口。另保留 38 个项目特色组件。
+基准版本：2.14.7。共 111 个主 / 子组件、4 个服务出口、3 个指令出口。另保留 42 个项目特色组件。
 
 清单覆盖官方组件注册表及服务 / 指令，不包含内部工具函数。出口覆盖不代表所有组件的交互、独立示例和视觉状态均已验证。网站每项均提供导入和官方 API 索引，新增组合示例见 AI-GUIDE.md。
 

package/docs/INTEGRATION.md

@@ -1,5 +1,9 @@
 # 主题接入规则更新
 
+## 新布局接入（源码尚未发布）
+
+新地图页面用 MapPageLayout；旧 TemplateLayout 继续保留，接口不做强制迁移。MapPageLayout 的插槽为 left / top / toolbar / right / legend / timeline / content / default。父容器须具有明确宽高且 position:relative；地图宿主独立创建，避免路由切换时随业务面板卸载。rightOpen 用 v-model 控制，原项目工具事件、设置面板及开关插槽通过应用适配层接入。原降水过程图等专有定位改用 timelineLeft / timelineBottom 等参数；不要把旧 CSS 类名当作新布局 API。接入时保留消费项目的 VFit 缩放桥接，不按容器断点重排；在地图宿主尺寸变化后 resize。WorkbenchShell 是否常驻由应用路由结构决定。
+
 当前规则以 [CSS-THEME.md](CSS-THEME.md) 为准：库不导出主题 store、不要求 Pinia，保留原项目 store；库 CSS 为变量提供低优先级默认值。默认 style.css 隔离，global.css 为可选整站主题。
 
 # 发布与反向接入
@@ -162,3 +166,43 @@ flat 模式按钮此前错误使用 child 类而内部图标、文字使用 pare
 ## 0.1.7 正式安装与样式
 
 通过 npm 安装 sky-ui-kit，main.ts 依次引入 element-plus/dist/index.css 和 sky-ui-kit/style.css，包内已包含默认主题和组件样式，不依赖开发者电脑、原业务项目或远程样式服务。CSS 变量允许运行时主题覆盖。图标资源可从 sky-ui-kit/icons 显式注册，或由应用提供 sprite；SvgIcon 不再自动携带图库。按组件入口见 docs/ON-DEMAND.md。
+
+
+四个模型项目的统一主题使用 ModelWorkspace 及 Header/Panel 结构，详情见 MODEL-WORKSPACE.md。原生 HTML 页面需要明确挂载/样式接入，不会因升级包自动改变。
+
+
+原生 HTML：部署包内 dist/model-workspace.css 并用 link 引入及结构类；Vue：使用 ModelWorkspace 系列组件并引入公共 style.css。完整双方案见 MODEL-WORKSPACE.md，不要将本地磁盘/node_modules 路径部署到网站。
+
+
+## 2026-11-03：可配置 VFit 尺寸（源码待发布）
+
+数字尺寸代表设计单位，由组件转换为 `calc(var(--cp-font-1, 1px) * n)`；CSS 字符串原样使用，不额外注册 VFit 或 transform。DesignSpacing 支持单值及2/3/4项数组，遵循CSS间距顺序。0是有效值。调用方传裸字符串 `"12"` 不是合法CSS长度，应使用 `:gap="12"`；`"12px"` 是固定CSS像素。
+
+所有新增参数有默认值；下表空字符串表示使用组件现有布局/样式默认值，不是0。根style可控制组件根尺寸，内部内边距通过对应props调整，无需deep覆盖。
+
+| 组件 | 参数与默认值 |
+| --- | --- |
+| MapPageLayout | 新增gap=12；已有rightPanelWidth=328、leftPanelWidth=320、edge=12等参数兼容字符串并支持数字；top/bottom/toolbar/timeline偏移默认空字符串，沿用自动避让 |
+| DefenseMapLayout | gap=4、padding=4、toolbarGap=12、toolbarPadding=12；topOffset默认64设计单位，兼容数字/字符串 |
+| MapWorkspacePanel | headerPadding=16、bodyPadding=16、footerPadding=[12,16]、gap=16 |
+| ModelWorkspacePanel | headerPadding=[12,16]、bodyPadding=16、footerPadding=[12,16]、gap=12 |
+| WorkbenchPanel | width='auto'、height='auto'、padding=0、gap=0；gap只在调用方使用flex/grid时产生间距，不强改display |
+| ManagementResourceLayout | gap=20、padding=[0,24,20]（内容区域）、introPadding=24、filterGap=20、filterPadding=[20,24]、inputWidth=260、selectWidth=160、cascaderWidth=280、responsive=false |
+| AppSelect | width='100%'、controlHeight=''（按size取主题小/中/大高度）、controlPadding=[0,10]；多选内容可增高；浮层不再设100%最小宽度，使用底层fit-input-width等配置 |
+| ProjectMenu | width=''、itemHeight=''、itemPadding=''、padding=''（分别保留横/纵菜单已有默认值）、gap=2 |
+| MapTimeline | padding=[10,12]、gap=9、trackHeight=88、controlHeight=30；不改变播放/时次数据API |
+| MapBottomProcessPanel | height=320、maxHeight='42dvh'、headerPadding=[10,16]、metaPadding=[8,16,0]、gap=12 |
+| ProcessDataTable | cellPadding=[6,10]、paginationGap=12、paginationPadding=5 |
+
+ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切换；旧调用方如需原断点布局显式传responsive=true。这是需要在升级说明中说明的行为变化。其内容区域padding与介绍区padding分开，避免改变原默认留白。
+
+地图布局时间轴测量改为offsetHeight，使用布局坐标而非transform后的视口像素，防止再次乘入缩放系数。UiButton/UiSelect/UiTable等基础组件继续使用底层size、width、height及主题token，无重复同义接口。旧TemplateLayout保留兼容接口，不冒充MapPageLayout别名。
+
+示例：
+```vue
+<MapWorkspacePanel title="降水统计" :header-padding="[12, 16]" :body-padding="[8, 12]" :gap="8">
+  业务内容
+</MapWorkspacePanel>
+<MapPageLayout :right-panel-width="320" :edge="12" :gap="8" />
+```
+预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。

package/docs/MODEL-WORKSPACE.md

@@ -0,0 +1,116 @@
+# 模型工作区统一主题
+
+参考四个项目实际样式：分布式水文模型 hydrogrid/frontend/src/styles/workspace-theme.css；水资源配置 app/static/workspace-theme.css；新安江 static/style.css 后段覆盖；LSTM前端预报模型Git/web_ui_prototype.html 的 light/dark token。新安江前段旧深色规则不是最终主题。
+
+共同浅色：背景 #f3f7fb，面板 #fff，主色 #1677ff，文字 #172b4d，边框 #dce5ef，蓝色渐变标题。深色：背景 #0d1420，面板 #151f2e，主色 #36cbb7，文字 #e3ecf5，边框 #35485f。
+
+ModelWorkspace(theme=light|dark, nativeControls=false) 提供显式主题边界及 header/default/footer 插槽；ModelWorkspaceHeader(title, description) 提供 title/actions 插槽；ModelWorkspacePanel(title) 提供 header/actions/default/footer。theme 由应用控制，不写 localStorage 或 document 根节点。未设置应用变量也有完整默认效果，应用可在容器 class/style 覆盖变量。
+
+公共 CSS 仍仅在 main.ts 引入 element-plus/dist/index.css 和 sky-ui-kit/style.css 一次。组件包构建脚本把 model-workspace.css 合入 style.css。范围仅 sky-model-workspace，不修改原生 Element Plus 或容器外 body。body 自身仍由应用设置，容器高度由应用布局提供。
+
+native-controls 是渐进迁移适配，仅在显式容器中覆盖原生按钮/表单外观，保留原 DOM、事件、disabled 及表单语义，不自动重写业务。优先用 UiButton/UiInput 等库组件。body 上的浮层不能继承局部主题，使用默认局部浮层或显式传递主题。地图色带、图表配色和业务阈值不在该主题替换范围。
+
+四个参考项目本次只读。它们并非全部 Vue 应用：原生 HTML 项目不能直接使用 Vue 组件，使用独立 model-workspace.css 并显式添加 sky-model-workspace / data-theme 边界和对应结构类；只升级 npm 不会自动改写已有原生页面。下一版本发布后按上述方式接入。
+
+
+## 按项目技术栈选择
+
+| 项目 | 使用方式 | 依赖 |
+|---|---|---|
+| 原生 HTML / 服务端模板 | model-workspace.css + 原生 HTML 结构类 | 无 Vue / Element Plus 运行时要求 |
+| Vue 3 | ModelWorkspace / Header / Panel 组件 + style.css | Vue 和组件包声明的 peerDependencies |
+
+以下能力为当前源码新增，需等待包含该能力的新版本发布；已发布的 0.1.7 不包含独立 model-workspace.css 或三个 ModelWorkspace 组件。
+
+## 原生 HTML：直接引入主题
+
+从新发布包的 dist/model-workspace.css 复制到网站静态资源目录，例如 /static/vendor/sky-ui-kit/model-workspace.css，随网站一起部署。不要将 node_modules 路径或开发者磁盘路径写进线上 HTML。不需要引入组件 JS、Vue 或 Element Plus CSS。
+
+```html
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>模型工作区</title>
+  <link rel="stylesheet" href="/static/vendor/sky-ui-kit/model-workspace.css">
+  <style>body { margin: 0; } #workspace { min-height: 100vh; }</style>
+</head>
+<body>
+  <div id="workspace" class="sky-model-workspace" data-theme="light" data-native-controls>
+    <header class="sky-model-header">
+      <div>
+        <h1 class="sky-model-header__title">模型计算工作区</h1>
+        <p class="sky-model-header__description">统一背景、面板和原生表单主题</p>
+      </div>
+      <button id="toggle-theme" type="button">切换主题</button>
+    </header>
+    <main class="sky-model-workspace__content">
+      <section class="sky-model-panel">
+        <header class="sky-model-panel__header"><h2>模型配置</h2></header>
+        <div class="sky-model-panel__body">
+          <label>测站名称 <input id="station" value="汉口站"></label>
+        </div>
+        <footer class="sky-model-panel__footer">
+          <span id="status" role="status">等待配置</span>
+          <button id="save" type="button" class="primary">保存配置</button>
+        </footer>
+      </section>
+    </main>
+  </div>
+  <script>
+    const workspace = document.getElementById('workspace');
+    document.getElementById('toggle-theme').addEventListener('click', () => {
+      workspace.dataset.theme = workspace.dataset.theme === 'dark' ? 'light' : 'dark';
+    });
+    document.getElementById('save').addEventListener('click', () => {
+      document.getElementById('status').textContent = '当前测站：' + document.getElementById('station').value;
+      // 真实保存请求沿用应用现有逻辑。
+    });
+  </script>
+</body>
+</html>
+```
+
+带 Vite 等构建工具的原生页面也可以在其唯一公共入口 `import 'sky-ui-kit/model-workspace.css'`。HTML 结构类负责外观，原有表单提交、事件和业务逻辑仍由页面维护；data-native-controls 显式开启原生控件外观。
+
+## Vue 3：使用组件
+
+main.ts 只引入一次公共 CSS：
+
+```ts
+import 'element-plus/dist/index.css'
+import 'sky-ui-kit/style.css'
+```
+
+不再额外引入 model-workspace.css，style.css 已包含同一主题。页面示例：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ModelWorkspace, ModelWorkspaceHeader, ModelWorkspacePanel, UiButton, UiInput } from 'sky-ui-kit'
+const theme = ref<'light' | 'dark'>('light')
+const station = ref('汉口站')
+const message = ref('等待配置')
+</script>
+<template>
+  <ModelWorkspace :theme="theme" style="min-height: 100vh">
+    <template #header>
+      <ModelWorkspaceHeader title="模型计算工作区" description="统一模型页面主题">
+        <template #actions>
+          <UiButton @click="theme = theme === 'light' ? 'dark' : 'light'">切换主题</UiButton>
+        </template>
+      </ModelWorkspaceHeader>
+    </template>
+    <ModelWorkspacePanel title="模型配置">
+      <UiInput v-model="station" placeholder="测站名称" />
+      <template #footer>
+        <span role="status">{{ message }}</span>
+        <UiButton type="primary" @click="message = '当前测站：' + station">保存配置</UiButton>
+      </template>
+    </ModelWorkspacePanel>
+  </ModelWorkspace>
+</template>
+```
+
+HTML 与 Vue 共用同一份 token 和结构样式，切换方式分别为 data-theme 和 theme 属性；两种方式均不需要原项目本地样式文件。新增颜色和布局规则应修改组件库，使用方只绑定业务数据和事件。