sky-ui-kit 0.1.7 → 0.1.9

package/dist/utils/dimensions.d.ts

@@ -0,0 +1,5 @@
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string;
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength];
+export declare function designLength(value: DesignLength): string;
+export declare function designSpacing(value: DesignSpacing): string;

package/docs/AI-CHANGELOG.md

@@ -1,7 +1,45 @@
 # 团队 AI 模块变更记录
 
+## 2026-11-02 · 沿用原平台浮动区域层级
+
+- MapPageLayout 对齐 metrics/TemplateLayout.vue 的聚焦 5、移入 6；沿用内容 1、普通区域 2、图例 3、工具栏 4，统一覆盖时间轴与右栏，保持透明工具间隙穿透与子面板随区域置顶。
+- 同步文档与生成 API；未发包，未修改参考项目。
+
+## 2026-11-02 · 模块移入置顶
+
+- 统一区域层级变量，区域子展开面板随模块置顶；限定普通内容层，透明工具间隙不拦截地图。
+- 图例及底部外层移除滚动裁剪，预览新增模拟遮挡开关；未发布或修改消费项目。
+
+## 2026-11-02 · 按用户约定改用 VFit 缩放
+
+- 撤回新增的 720px 容器断点、右侧抽屉、compact 属性/事件及会商单列重排；保持区域与列数，使用应用 VFit 尺寸变量。
+- 会商网格移除 260px 最小行高，均分顶部操作区之外的剩余高度，消除该最小行高引起的内部滚动条；删除外壳固定 1px 尺寸覆盖。
+- 同步预览说明、示例和行为检查。未构建、发包或修改消费项目布局。
+
+## 2026-11-02 · 完善地图布局行为（源码待用户预览）
+
+- 导航直接显示 MapPageLayout 名称，开发指南增加地图布局直达入口，避免新组件沿用旧名称而难以查找。
+
+- 新增 MapPageLayout，与旧 TemplateLayout 并行，旧接口不变；新布局仅负责区域排列，位置参数独立于业务类名。
+- 增加实际容器宽度检测、非模态右侧覆盖面板、关闭事件、区域 hover / focus 层级和时间轴避让。
+- DefenseMapLayout 新增可选 structured 模式、toolbar、列数与窄容器单列；默认保持原样式外壳。
+- 预览支持宽窄容器、右栏和时间轴开关；同步接入、样式、组件指南与生成 API。未发布，未更新消费项目布局。
+
+## 2026-11-02 · 布局说明按三层重写（待用户预览确认）
+
+- 开发指南新增“布局怎么选”直达入口（#layout-guide），避免说明藏在基础组件深层目录。
+
+- 布局容器页新增“平台外壳 → 页面分区 → 局部面板”示意及按场景选择组件的说明，区分 WorkbenchShell、TemplateLayout、管理布局、面板与基础容器。
+- 修正地图布局说明中的默认工具栏、遗漏 left 插槽及项目同名组件 API 混用；明确右栏受控条件和应用的地图生命周期责任。
+- 同步 AI 指南并生成 AI 文档；未发布 npm，未更新消费项目布局。由用户在预览站确认文案后再安排发布。
+
 本文件记录源码模块调整与接入影响，不作为 npm 发布完成的依据。团队使用安装包时以包内文档及 package.json 版本为准；使用当前源码时读取仓库中的同名文档。
 
+## 2026-11-02 · 清理历史本地联调锁记录
+
+- 删除 package-lock.json 中一体机消费项目的 extraneous 记录及其中旧 vendor tgz 引用；现有库依赖版本保持不变，未修改消费项目。
+- 同步 AI 指南并重新生成 AI 文档；未构建、打包、发布或提交 Git。
+
 ## 2026-10-13 · 0.1.2 发布准备
 
 - 核对并重新生成组件 API、AI 指南、llms 索引和完整文档，包含项目图标、全局适配、独立常驻示例和导航调整。
@@ -389,3 +427,57 @@ SVG 图库从主入口移到可选 icons 入口，SvgIcon 不再自动注册；
 ## 2026-10-29 · 0.1.7 发布准备
 
 正式发布按需入口与可选图库，默认主题和组件 CSS 随 npm 包分发，无开发机样式依赖。构建前清理 dist 防止旧 chunk 混入；图标注册迁移见 ON-DEMAND.md。
+
+
+## 2026-10-30 · 四项目模型主题
+
+读取四个项目最终覆盖主题，提取蓝白/深蓝青绿 token、渐变标题与面板。新增三个隔离主题组件、显式原生表单适配和可复制示例。公共 CSS 合入 style.css；未构建、未发布。
+
+
+## 2026-10-30 · HTML / Vue 双接入文档
+
+新增独立 model-workspace.css 发布出口，原生 HTML 用 CSS 和结构类，Vue 用主题组件与公共 CSS。补齐两套完整示例、主题切换、事件绑定和部署路径说明，未构建发布。
+
+## 2026-11-02 · 0.1.8 发布准备
+
+- 发布当前组件源码、按需入口及模型工作区主题；HTML 使用 model-workspace.css，Vue 使用组件与 style.css。清除旧消费项目锁记录。发布状态以 npm 注册表为准。
+
+
+
+## 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查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
+
+## 2026-11-03 · 0.1.9 发布准备
+
+- 将当前布局、面板、尺寸适配与主题调整纳入新版，重新生成 AI 文档并检查组件包。发布结果以 npm 注册表为准。
+

package/docs/AI-GUIDE.md

@@ -1,5 +1,32 @@
 # sky-ui-kit：AI 使用指南
 
+MapPageLayout 沿用参考项目 D:/Work/01-项目code/一体化平台/webv1/src/components/layout/TemplateLayout.vue 的 1/2/3/4/5/6 层级约定，并补齐底部时间轴和右侧面板。层级按区域统一管理：鼠标移入 left/top/toolbar/right/legend/timeline 时提升整个区域到 hover 层，优先于 focus-within；子展开面板随所属区域一起提升，移出后恢复。普通 content 限定在底层独立堆叠上下文，透明工具间隙穿透地图。图例和时间轴外层不再 overflow:auto 裁剪浮层；长内容滚动由内部业务组件负责。Teleport 到 body 的浮层仍由组件自身管理层级。预览“模拟模块遮挡”可核对重叠交互；完全被覆盖的部分不接收鼠标，应从模块可见区域移入。
+
+## 新地图布局行为（源码待预览，尚未发布）
+
+预览入口：开发指南 → MapPageLayout 地图布局（#project-template-layout）；基础组件 → 布局容器下也显示“地图布局 · MapPageLayout”，支持按组件名搜索。
+
+新页面优先用 MapPageLayout；旧 TemplateLayout 保持接口及业务样式兼容，并非两者 API 的别名。MapPageLayout 不携带任何依赖 rainfall-process、地图标题或分析面板类名的定位规则。消费方使用 topOffset / bottomOffset / toolbarTop / timelineLeft / timelineRight / timelineBottom / edge 配置位置。
+
+rightOpen 与 rightPanelEnabled、right 插槽共同决定右栏显示。区域关系固定，右栏打开时工具栏、图例及时间轴始终避让。按用户约定移除 compactBreakpoint / compactRightMode / compact-change：不按 720px 容器宽度切抽屉或重排。尺寸由消费项目注册的 VFit 写入 --cp-vfit-scale，再经 --cp-font-1 等变量传入；库不重复注册 VFit，不额外 transform 缩放。
+
+默认区域层级 2、图例 3、工具栏 4；键盘 focus-within 为 5，鼠标 hover 为 6。时间轴高度通过 timeline-height 通知，图例自动避让；监听在卸载释放。
+
+DefenseMapLayout 默认 structured=false 保留原样式壳。structured=true 提供 toolbar 与网格内容，columns 为 1 或 2，保持指定列数，均分剩余高度，不设 260px 最小行高或内部滚动条。间距和 topOffset 继承 VFit 尺寸变量；地图、联动、路由及持久挂载由应用负责。
+
+## 布局怎么选：平台外壳 → 页面分区 → 局部面板
+
+预览站“开发指南 → 布局怎么选”可直接进入说明（#layout-guide）；“基础组件 → 布局容器”也会展示。说明先展示通俗选型说明与三层嵌套示意，再展示地图区域和组合示例。说明源文件为 src/LayoutGuide.vue；本次只调整说明，不改变组件 API 或运行行为。
+
+- WorkbenchShell 是整个平台的外壳，提供 header / workspace；management 模式才提供内置左侧分组菜单，路由仍由应用接入。
+- TemplateLayout 是地图页面的摆放架，提供 left、top、toolbar、right、legend、timeline、content 和默认插槽。应用先提供有明确宽高、position: relative 的地图容器。rightOpen、rightPanelEnabled 与 right 插槽共同决定右栏显示；没有默认工具、图例或地图实例。
+- ManagementResourceLayout 用于管理页的概览、筛选、标题、操作及内容区域。
+- WorkbenchPanel 是局部外观容器；MapWorkspacePanel 是带标题、actions、default、footer 的业务面板。两者不负责路由和地图生命周期。
+- DefenseMapLayout 是会商样式外壳，默认插槽由应用提供地图内容和联动；ModelWorkspace 面向模型编辑，不是通用平台外壳。
+- UiContainer / UiHeader / UiAside / UiMain / UiFooter 是自定义普通布局的基础积木。
+
+项目内 TemplateLayout 与库组件同名但接口不同，不能只换 import。原 right-toggle、map-toolbar-info 和 rightPanelDefaultOpen 需要应用适配层衔接。公共布局稳定挂载、地图是否重建、容器改变后的地图与图表 resize 均由消费项目负责；替换布局组件不自动消除菜单切换闪烁。
+
 适用于 Vue 3 + TypeScript。此文件描述包的真实 API 和约束，不是自动执行的代理指令。AI 工具需要主动读取这些文档；安装包不会自动改变其上下文。
 
 管理布局：使用 WorkbenchShell management 模式与内容插槽，详见本文末尾最新说明。账号、菜单路由和数据由消费方提供，库不提供认证。
@@ -30,6 +57,8 @@ UiAutocomplete 提供独立站点搜索示例：fetch-suggestions 回调、聚
 
 ## 文档读取顺序
 
+依赖维护：库的 package.json 与 package-lock.json 不应记录消费项目的本地目录或历史 vendor 安装包。已清除一体机项目遗留的 extraneous 锁记录；消费项目自行管理其安装依赖。
+
 安装或升级最新正式版使用 `npm install sky-ui-kit@latest`。latest 指向 npm 的正式发布标签，尚未发布的源码修改不在安装包内；依据当前已安装包的版本和文档使用组件。
 
 团队先读取 llms.txt，并结合 AI-CHANGELOG.md 了解模块变更及接入影响。后续所有代码、预览页面、样式和接入说明修改均同步相关 AI 文档，并运行 npm run docs:ai；快速开始代码与页面使用同一份源文件生成。
@@ -202,6 +231,39 @@ MapLayerControl 参考平台 LayerControl/LayerTreeNode，提供底图选择、
 
 flat 模式按钮此前错误使用 child 类而内部图标、文字使用 parent 类，导致 active 样式不匹配。统一按钮及内容层级类，保留现有单选、多选及事件逻辑。
 
+## 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查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
+
 <!-- GENERATED EXAMPLES -->
 
 ### 快速开始：安装最新正式版本
@@ -945,20 +1007,45 @@ const items = [{ key: 'overview', label: '运行概览' }, { key: 'data', label:
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import { TemplateLayout, UiButton, MapTools, WorkbenchPanel } from 'sky-ui-kit'
+import { MapPageLayout, DefenseMapLayout, UiButton, MapTools, WorkbenchPanel, MapWorkspacePanel } from 'sky-ui-kit'
 const rightOpen = ref(true)
+const showTimeline = ref(true)
+const overlap = ref(false)
+const compactDimensions = ref(false)
 </script>
 <template>
-  <div style="position: relative; height: 460px">
-    <TemplateLayout :right-open="rightOpen">
-      <template #top><UiButton @click="rightOpen = !rightOpen">{{ rightOpen ? '收起右栏' : '展开右栏' }}</UiButton></template>
-      <template #toolbar><MapTools :items="[{ key: 'layers', label: '图层' }]" /></template>
-      <template #right><WorkbenchPanel style="height: 100%">right · 业务面板</WorkbenchPanel></template>
-      <template #legend>legend · 图例</template>
-      <template #timeline>timeline · 时间轴</template>
-    </TemplateLayout>
+  <div class="layout-demo-controls">
+    <UiButton @click="compactDimensions = !compactDimensions">{{ compactDimensions ? '切回默认尺寸' : '查看紧凑尺寸' }}</UiButton>
+    <UiButton @click="rightOpen = !rightOpen">{{ rightOpen ? '收起右栏' : '展开右栏' }}</UiButton>
+    <UiButton @click="showTimeline = !showTimeline">{{ showTimeline ? '隐藏时间轴' : '显示时间轴' }}</UiButton>
+    <UiButton @click="overlap = !overlap">{{ overlap ? '恢复正常避让' : '模拟模块遮挡' }}</UiButton>
+  </div>
+  <div class="layout-demo-map" >
+    <MapPageLayout v-model:right-open="rightOpen" :gap="compactDimensions ? 6 : 12" :edge="compactDimensions ? 6 : 12" :right-panel-width="compactDimensions ? 280 : 328" :timeline-right="overlap ? 'var(--map-layout-edge)' : ''">
+      <template #top><span>地图标题 / 查询区域</span></template>
+      <template #toolbar><MapTools :items="[{ key: 'layers', label: '图层' }]" /><WorkbenchPanel v-if="overlap" class="layout-demo-expanded">右上展开面板<br>鼠标移入时整个工具区域置顶</WorkbenchPanel></template>
+      <template #right><MapWorkspacePanel title="可配置面板" :header-padding="compactDimensions ? [8, 12] : 16" :body-padding="compactDimensions ? [8, 12] : 16" :gap="compactDimensions ? 8 : 16">数字为 VFit 设计尺寸；默认值无需重复传入。<template #footer>鼠标移入当前区域时置顶</template></MapWorkspacePanel></template>
+      <template #legend><WorkbenchPanel :class="{ 'layout-demo-overlap-legend': overlap }">图例 · 鼠标移入置顶</WorkbenchPanel></template>
+      <template v-if="showTimeline" #timeline><WorkbenchPanel class="layout-demo-timeline">时间轴 / 过程图区域 · 鼠标移入置顶</WorkbenchPanel></template>
+    </MapPageLayout>
+  </div>
+  <p>尺寸参数：数字自动跟随 VFit，数组为上/右/下/左间距，CSS 字符串原样使用。例如 :body-padding="[8, 12]"、:gap="8"。</p>
+  <h3>会商布局 · 顶部操作区 + 四个地图位置</h3>
+  <p>以下仅展示区域，不创建地图。保持两列布局，尺寸沿用 VFit 缩放变量；四个地图位置均分剩余高度，不产生内部滚动条。</p>
+  <div class="layout-demo-map" >
+    <DefenseMapLayout structured top-offset="0" :columns="2">
+      <template #toolbar>时次选择 / 设置按钮放在这里</template>
+      <WorkbenchPanel v-for="index in 4" :key="index">地图位置 {{ index }} · 由页面提供地图宿主</WorkbenchPanel>
+    </DefenseMapLayout>
   </div>
 </template>
+<style scoped>
+.layout-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-bottom: 12px; }
+.layout-demo-map { position: relative; height: calc(var(--cp-font-1, 1px) * 460); border: 1px dashed var(--color-soft-border); background: var(--surface-control); }
+.layout-demo-expanded { position: absolute; right: 0; top: calc(var(--cp-font-1, 1px) * 40); width: calc(var(--cp-font-1, 1px) * 260); height: calc(var(--cp-font-1, 1px) * 300); box-sizing: border-box; border: 1px solid var(--color-soft-border); background: var(--color-panel); }
+.layout-demo-overlap-legend { transform: translateY(calc(var(--cp-font-1, 1px) * 50)); background: var(--color-panel); border: 1px solid var(--color-soft-border); }
+.layout-demo-timeline { min-height: calc(var(--cp-font-1, 1px) * 90); background: var(--color-panel); border: 1px solid var(--color-soft-border); }
+</style>
 
 ```
 
@@ -2938,3 +3025,29 @@ const items = [{ key: 'rain', label: '降水', icon: Pouring }, { key: 'water',
 </style>
 
 ```
+
+### 模型工作区统一主题示例
+
+```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 name = ref('汉口站')
+const message = ref('等待配置')
+</script>
+<template>
+  <ModelWorkspace :theme="theme" native-controls>
+    <template #header><ModelWorkspaceHeader title="模型计算工作区" description="分布式水文 / 水资源配置 / 新安江 / LSTM 共用主题">
+      <template #actions><UiButton @click="theme = theme === 'light' ? 'dark' : 'light'">切换主题</UiButton></template>
+    </ModelWorkspaceHeader></template>
+    <ModelWorkspacePanel title="模型配置">
+      <UiInput v-model="name" placeholder="测站名称" />
+      <p>原生控件逐步迁移时，可显式启用 native-controls。</p>
+      <button type="button" class="primary" @click="message = '执行配置：' + name">原生操作示例</button>
+      <template #footer><span role="status">{{ message }}</span><UiButton @click="message = '保存配置由使用方接入'">保存配置</UiButton></template>
+    </ModelWorkspacePanel>
+  </ModelWorkspace>
+</template>
+
+```

package/docs/COMPONENT-API.md

@@ -27,6 +27,9 @@ Slots: No declared content slots.
 
 | Name | Type | Required | Default expression |
 |---|---|---|---|
+| width | DesignLength | false | '100%' |
+| controlHeight | DesignLength | false | '' |
+| controlPadding | DesignSpacing | false | () => [0, 10] |
 | modelValue | AppSelectValue | false | undefined |
 | options | AppSelectOption[] | false | () => [] |
 | emptyLabel | string | false | '暂无可选项' |
@@ -41,6 +44,10 @@ Slots: No declared content slots.
 Slots: No declared content slots.
 
 ```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
 export type AppSelectValue = string | number | boolean | Record<string, unknown> | AppSelectValue[] | null | undefined
 export type AppSelectOption = {
   label: string
@@ -55,6 +62,10 @@ export type AppSelectOption = {
 
 | Name | Type | Required | Default expression |
 |---|---|---|---|
+| padding | DesignSpacing | false | () => [10, 12] |
+| gap | DesignLength | false | 9 |
+| trackHeight | DesignLength | false | 88 |
+| controlHeight | DesignLength | false | 30 |
 | modelValue | number | false | 0 |
 | startTime | TimelineTimeInput | false | () => new Date() |
 | points | TimelinePoint[] | false | () => [] |
@@ -89,6 +100,10 @@ export type AppSelectOption = {
 Slots: date-select
 
 ```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
 type IntervalUnit = 'minute' | 'hour' | 'day' | 'month' | 'year'
 type TimelineKind = 'observed' | 'forecast'
 type TimelineTimeInput = string | number | Date
@@ -178,6 +193,11 @@ export type TimeRangeQuickOption = {
 
 | Name | Type | Required | Default expression |
 |---|---|---|---|
+| width | DesignLength | false | '' |
+| itemHeight | DesignLength | false | '' |
+| itemPadding | DesignSpacing | false | '' |
+| padding | DesignSpacing | false | '' |
+| gap | DesignLength | false | 2 |
 | direction | 'horizontal' &#124; 'vertical' | false | 'horizontal' |
 | active | string | false | '' |
 | items | ProjectMenuItem[] | false | () => [] |
@@ -191,6 +211,10 @@ export type TimeRangeQuickOption = {
 Slots: No declared content slots.
 
 ```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
 export interface ProjectMenuItem { key: string; label: string; disabled?: boolean; icon?: Component; children?: ProjectMenuItem[] }
 export interface ProjectMenuGroup { label: string; items: ProjectMenuItem[] }
 ```
@@ -298,6 +322,9 @@ Slots: No declared content slots.
 | times | string[] | true | undefined / no declared default |
 | series | { name: string; data: (number &#124; null)[] }[] | true | undefined / no declared default |
 | loading | boolean | false | undefined / no declared default |
+| cellPadding | DesignSpacing | false | () => [6, 10] |
+| paginationGap | DesignLength | false | 12 |
+| paginationPadding | DesignSpacing | false | 5 |
 
 ### Events
 
@@ -305,6 +332,13 @@ No declared events.
 
 Slots: No declared content slots.
 
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
+
 ## WorkbenchShell
 
 ### Props
@@ -332,6 +366,10 @@ Slots: header, sidebar-footer, workspace, default
 |---|---|---|---|
 | as | 'section' &#124; 'aside' &#124; 'div' | false | 'section' |
 | floating | boolean | false | true |
+| width | DesignLength | false | 'auto' |
+| height | DesignLength | false | 'auto' |
+| padding | DesignSpacing | false | 0 |
+| gap | DesignLength | false | 0 |
 
 ### Events
 
@@ -339,6 +377,13 @@ No declared events.
 
 Slots: default
 
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
+
 ## MetricCard
 
 ### Props
@@ -437,6 +482,39 @@ export interface MapLayerNode { id: string; name: string; visible?: boolean; opa
 
 Slots: left, top, toolbar, right, legend, timeline, content, default
 
+## MapPageLayout
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| gap | DesignLength | false | 12 |
+| rightOpen | boolean | false | false |
+| rightPanelEnabled | boolean | false | true |
+| rightPanelWidth | DesignLength | false | 'calc(var(--cp-font-1, 1px) * 328)' |
+| leftPanelWidth | DesignLength | false | 'calc(var(--cp-font-1, 1px) * 320)' |
+| edge | DesignLength | false | 'calc(var(--cp-font-1, 1px) * 12)' |
+| topOffset | DesignLength | false | '' |
+| bottomOffset | DesignLength | false | '' |
+| toolbarTop | DesignLength | false | '' |
+| timelineLeft | DesignLength | false | '' |
+| timelineRight | DesignLength | false | '' |
+| timelineBottom | DesignLength | false | '' |
+
+### Events
+
+- `update:rightOpen` — `[open: boolean]`
+- `timeline-height` — `[height: number]`
+
+Slots: left, top, toolbar, right, legend, timeline, content, default
+
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
+
 ## RainfallRankingTable
 
 ### Props
@@ -775,6 +853,15 @@ Slots: message, primary, default, footer
 | title | string | false | undefined / no declared default |
 | description | string | false | undefined / no declared default |
 | showIntro | boolean | false | true |
+| gap | DesignLength | false | 20 |
+| padding | DesignSpacing | false | () => [0, 24, 20] |
+| introPadding | DesignSpacing | false | 24 |
+| filterGap | DesignLength | false | 20 |
+| filterPadding | DesignSpacing | false | () => [20, 24] |
+| inputWidth | DesignLength | false | 260 |
+| selectWidth | DesignLength | false | 160 |
+| cascaderWidth | DesignLength | false | 280 |
+| responsive | boolean | false | false |
 
 ### Events
 
@@ -782,6 +869,13 @@ No declared events.
 
 Slots: summary, filters, heading, actions, default
 
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
+
 ## GlobalMapLayerDock
 
 ### Props
@@ -847,6 +941,11 @@ Slots: footer
 
 | Name | Type | Required | Default expression |
 |---|---|---|---|
+| height | DesignLength | false | 320 |
+| maxHeight | DesignLength | false | '42dvh' |
+| headerPadding | DesignSpacing | false | ()=>[10,16] |
+| metaPadding | DesignSpacing | false | ()=>[8,16,0] |
+| gap | DesignLength | false | 12 |
 | title | string | true | undefined / no declared default |
 | subtitle | string | false | '' |
 | demo | boolean | false | false |
@@ -862,6 +961,13 @@ Slots: footer
 
 Slots: No declared content slots.
 
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
+
 ## MapWorkspacePanel
 
 ### Props
@@ -870,6 +976,10 @@ Slots: No declared content slots.
 |---|---|---|---|
 | title | string | true | undefined / no declared default |
 | subtitle | string | false | undefined / no declared default |
+| headerPadding | DesignSpacing | false | 16 |
+| bodyPadding | DesignSpacing | false | 16 |
+| footerPadding | DesignSpacing | false | () => [12, 16] |
+| gap | DesignLength | false | 16 |
 
 ### Events
 
@@ -877,6 +987,13 @@ No declared events.
 
 Slots: actions, default, footer
 
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
+
 ## NationalHydroSidebar
 
 ### Props
@@ -944,12 +1061,81 @@ Slots: No declared content slots.
 
 | Name | Type | Required | Default expression |
 |---|---|---|---|
+| structured | boolean | false | false |
+| columns | 1 &#124; 2 | false | 2 |
+| gap | DesignLength | false | 4 |
+| padding | DesignSpacing | false | 4 |
+| toolbarGap | DesignLength | false | 12 |
+| toolbarPadding | DesignSpacing | false | 12 |
+| topOffset | DesignLength | false | 'calc(var(--cp-font-1, 1px) * 64)' |
 
 ### Events
 
 No declared events.
 
-Slots: default
+Slots: toolbar, default
+
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
+
+## ModelWorkspace
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| theme | 'light' &#124; 'dark' | false | 'light' |
+| nativeControls | boolean | false | false |
+
+### Events
+
+No declared events.
+
+Slots: header, default, footer
+
+## ModelWorkspaceHeader
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| title | string | true | undefined / no declared default |
+| description | string | false | undefined / no declared default |
+
+### Events
+
+No declared events.
+
+Slots: title, actions
+
+## ModelWorkspacePanel
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| title | string | false | undefined / no declared default |
+| headerPadding | DesignSpacing | false | () => [12, 16] |
+| bodyPadding | DesignSpacing | false | 16 |
+| footerPadding | DesignSpacing | false | () => [12, 16] |
+| gap | DesignLength | false | 12 |
+
+### Events
+
+No declared events.
+
+Slots: header, actions, default, footer
+
+```ts
+/** Numeric dimensions are VFit design units; CSS strings pass through unchanged. */
+export type DesignLength = number | string
+export type DesignSpacing = DesignLength | readonly [DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength] | readonly [DesignLength, DesignLength, DesignLength, DesignLength]
+
+```
 
 ## UiAffix
 

package/docs/COMPONENT-GUIDE.md

@@ -1,5 +1,11 @@
 # 组件使用说明
 
+## 布局选择（当前源码）
+
+WorkbenchShell 管平台外壳；MapPageLayout 管地图上的区域；WorkbenchPanel / MapWorkspacePanel 装具体业务内容。旧 TemplateLayout 保留历史行为，新页面建议 MapPageLayout，不能直接按同名接口替换。MapPageLayout 使用 v-model:right-open；保持区域关系，右栏打开时其他浮动区域避让，尺寸沿用应用的 VFit 变量，不提供按宽度切换抽屉的断点。它不创建地图，不自动解决路由重新挂载。
+
+DefenseMapLayout 默认是旧样式外壳；structured=true 启用顶部 toolbar 和 columns=1/2 网格，保持指定列数并均分剩余高度，不设最小行高撑出内部滚动条。默认插槽传各幅地图宿主，应用管理地图实例和联动。
+
 本指南说明当前包已导出的 11 个项目组件的用途、数据约定和交互边界。完整属性类型、默认值、事件签名和插槽列表见 [组件 API](COMPONENT-API.md)；完整示例见 [AI-GUIDE](AI-GUIDE.md)。原项目组件清单中的文件不一定已经进入本包，以 `src/components/index.ts` 和 `components.json` 为准。
 
 ## SvgIcon 与原项目适配