@pisell/materials 1.8.41 → 1.8.43

package/es/components/pisellRecordBoard/docs/PisellRecordBoard.md

@@ -27,6 +27,76 @@ PisellRecordBoard 是列表类页面的**容器**，不直接渲染表格或卡
 - 支持有 type 时用 render/filter/sort 覆盖
 - 快速筛选（左侧内联）+ 高级筛选（右侧弹层）
 - 多选与 BatchActionBar
+- **可选平面图**：在 `ShellFrame` 内声明 **`PisellRecordBoard.FloorMap`**（与 `GridLayout` / `CardLayout` 并列）；**仅表格
+  **、**仅平面图**、**双视图**（此时 ToolBar 出现「表格 / 平面图」）由你传了哪些子节点决定；根级 `floorMap` 仍兼容（如
+  SalesGrid），与子组件 props 合并且 **子优先**。平面图模式下不显示底部分页
+
+## 架构总览
+
+### 组件树（推荐：ShellFrame + GridLayout [+ FloorMap]）
+
+```
+PisellRecordBoard（根容器：flex 列、minHeight:0，注入 RecordBoardProvider）
+└─ PisellRecordBoard.ShellFrame（PisellShellFrame：toolbar + batch + 内容区）
+   ├─ RecordBoardToolBar（搜索 / 快筛 / [可选] 表格·平面图切换 / 列设置 / …）
+   ├─ RecordBoardBatchActionBar（有选中行时出现）
+   ├─ 主内容区（由 ShellFrame 解析子节点）
+   │  ├─ 子节点示例：<GridLayout /> 与 <FloorMap {...pisellFloorMapProps} /> 并列
+   │  ├─ bodyView === 'grid'：ScrollAreaMeasurer（可选）→ 非 FloorMap 子树（如 GridLayout → Grid）
+   │  └─ bodyView === 'floorMap'：PisellFloorMapLayout（props 来自 FloorMap + 可选根级 floorMap 合并）
+   └─ RecordBoardPagination（仅 grid 子视图；平面图模式隐藏）
+```
+
+- **`layoutType`**（`'grid' | 'card'`）描述「内容区用哪套 Layout 组件集合」；**`bodyView`**（`'grid' | 'floorMap'`）在 *
+  *存在平面图能力**（Shell 内出现 `FloorMap` 或根级传入 `floorMap`）且 **同时存在表格区子节点** 时，用于切换主内容；仅
+  `FloorMap`、无 Grid/Card 时固定为平面图，无 Segmented。
+- **数据不重复请求**：`data` / `loading` / `total` / `pagination` / `searchParams` / `onSearch` / `onPageChange`
+  由上层统一维护（如 DataSource、useRequest）；RecordBoard 只负责 Context 分发与 UI 组合。
+
+### Context（RecordBoardContextValue）速查
+
+| 分类   | 字段                                                                                | 说明                                                                                                |
+|------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
+| 列表   | `data`、`loading`、`total`                                                          | 当前页数据、加载态、总条数                                                                                     |
+| 分页   | `pagination`、`onPageChange`                                                       | `{ pageNumber, pageSize }`、翻页回调                                                                   |
+| 搜索   | `searchParams`、`onSearch`、`onReset`                                               | 含 `keyword`、`filter`、`sort` 等；`onSearch` 一般会重置到第一页（由业务实现）                                         |
+| 布局   | `layoutType`                                                                      | `grid` / `card`                                                                                   |
+| 多选   | `selectedKeys`、`selectedRows`、`onSelectionChange`、`rowKey`                        | 若 `grid` 传入受控多选，则与 context 合并为受控态                                                                 |
+| 列 UI | `columnVisibility`、`onColumnVisibilityChange`、`columnOrder`、`onColumnOrderChange` | 容器内部状态；**不从 props 传入**                                                                            |
+| 透传   | `childComponentProps`                                                             | 由根组件从打散 props 合并 `grid` / `toolBar` / … 注入                                                        |
+| 高度   | `fillHeight`、`scrollAreaHeight`、`setScrollAreaHeight`                             | 默认 `fillHeight: true`；`scroll.autoCalc` 时 ShellFrame 测量内容区高度写回                                    |
+| 筛选重置 | `filterResetKey`、`setFilterResetKey`                                              | 重置按钮递增 key，强制 PisellFilter 重挂载                                                                    |
+| 双视图  | `bodyView`、`setBodyView`、`floorMapProps`                                          | 根级可选 `floorMap`；Shell 内 **`FloorMap` 与根级合并**，子优先；无平面图槽位时一般为 grid（仅 FloorMap 时由 Shell 置为 floorMap） |
+
+子组件使用 **`PisellRecordBoard.useRecordBoardContext()`**；传入 **`{ displayName: 'grid' }`** 时，返回值会合并 *
+*`childComponentProps.grid`**（便于 Grid 直接拿到 `columns`、`scroll` 等）。
+
+### searchParams 约定（与 ToolBar 联动）
+
+| 字段        | 含义                                             | 典型写入方                           |
+|-----------|------------------------------------------------|---------------------------------|
+| `keyword` | 关键词搜索                                          | PisellFind（ToolBar 内）           |
+| `filter`  | 筛选结构：`{ quickFilter?, otherFilter?, values? }` | ToolBarQuickFilter、PisellFilter | 
+| `sort`    | 排序，单值字符串                                       | Sort 组件                         |
+
+- 左侧 **QuickFilter** 与 **`searchParams.filter.quickFilter`** 同步；右侧 **PisellFilter** 传入时会 **清空 quickFilter
+  数组**（`hiddenQuickFilter: true`），避免与左侧重复。
+- **筛选默认值**：在受控 `searchParams` 初始对象中带上 `filter`，在 `values` 里按筛项 `name`/`key` 赋默认值（见下文「筛选默认值」小节）。
+
+### 列显隐与列顺序持久化
+
+- 列显示隐藏由容器 **`useState`** 维护，初始值来自 **`grid.defaultHiddenColumnKeys`**、列上 **`hidden: true`**，并可与 *
+  *localStorage** 合并。
+- 传入 **`columnVisibilityStorageKey`**（字符串）时，使用 **`@pisell/utils`** 的列设置存储（`saveColumnVisibilityToLocal` /
+  `getRecordBoardColumnSettingFromLocal`）：持久化 **显隐** 与 **列顺序**（ColumnSetting 拖拽）。低代码场景可传 **`__id`**
+  作为存储 key（与 DataSourceContainer 规则一致）。
+- **仅影响表格/卡片列展示**，不参与筛选/排序配置生成。
+
+### 打散 props 与 childComponentProps
+
+根组件 **`mergeChildComponentProps`** 将 `grid`、`toolBar`、`search`、`paginationConfig`、`batchActionBar`、`cardList` 合并为
+Context 中的 **`childComponentProps`**，供 ShellFrame 内各模块读取。列表数据字段 **`data` / `pagination` / `searchParams`
+等仍为根级 props**，勿放进 `childComponentProps`。
 
 ## 何时使用
 
@@ -401,54 +471,68 @@ export default () => {
 - 传入 RecordBoard 的 `searchParams` 初始值里包含
   `filter: { values: { [字段名]: 默认值 }, quickFilter: [], otherFilter: [...] }`。
 - `filter.values` 的 key 需与 quickFilter 的 `filterList` 里每一项的 `name`/`key` 一致（如 `orderDate`）。
-- 日期范围等建议用 dayjs 实例，例如 `orderDate: [dayjs().subtract(7, 'day'), dayjs()]`。
+- 日期范围等传 **与快筛控件一致的值类型**（如 `[start, end]` 字符串、Date 等）。快筛项类型 **`rangePickerNew`** 使用 antd
+  `RangePicker`，**单独使用文档/示例时无需 MUI 上下文**；**`rangePicker`** 走自研日期范围（MUI X），应用根须包裹
+  **`LocalizationProvider` + `AdapterDayjs`**（见 `@pisell/date-picker`）。
 
-示例（orderDate 默认近 7 天）：
+示例（`orderDate` 默认一段固定日期范围；使用 **`rangePickerNew`**，仅演示结构）：
 
-```
+```tsx
 import React, {useState} from 'react';
-// import dayjs from 'dayjs';
 import {PisellRecordBoard} from '@pisell/materials';
 
-// 初始 searchParams 带默认筛选
-const [searchParams, setSearchParams] = useState<Record<string, unknown>>({
-    filter: {
-        quickFilter: [],
-        otherFilter: [], // 或你的 otherFilter 配置
-        values: {
-            // orderDate: [dayjs().subtract(7, 'day'), dayjs()],
+const list: { id: string }[] = [];
+
+export default () => {
+    const [searchParams, setSearchParams] = useState<Record<string, unknown>>({
+        filter: {
+            quickFilter: [],
+            otherFilter: [],
+            values: {
+                orderDate: ['2024-01-01', '2024-01-08'],
+            },
         },
-    },
-});
-
-// value 里 searchParams、onSearch 照常
-const value = {
-    data: list,
-    searchParams,
-    onSearch: (params) => setSearchParams(params),
-    // ...
-};
+    });
 
-// toolBar 里 quickFilter.filterList 的 name/key 为 orderDate，与上面 values.orderDate 对应
-<PisellRecordBoard
-    {...value}
-    toolBar={{
-        quickFilter: {
-            filterList: [
-                {
-                    type: 'rangePicker',
-                    name: 'orderDate',
-                    key: 'orderDate',
-                    label: '订单日期',
-                    props: {placeholder: ['开始', '结束']},
-                },
-            ],
+    const value = {
+        data: list,
+        loading: false,
+        total: 0,
+        pagination: {pageNumber: 1, pageSize: 10},
+        onPageChange: () => {
         },
-        filter: {hiddenQuickFilter: true},
-    }}
->
-    ...
-</PisellRecordBoard>
+        searchParams,
+        onSearch: (params: Record<string, unknown>) => setSearchParams(params),
+        layoutType: 'grid' as const,
+        rowKey: 'id',
+    };
+
+    return (
+        <PisellRecordBoard
+            rowKey="id"
+            {...value}
+            grid={{columns: []}}
+            toolBar={{
+                quickFilter: {
+                    filterList: [
+                        {
+                            type: 'rangePickerNew',
+                            name: 'orderDate',
+                            key: 'orderDate',
+                            label: '订单日期',
+                            props: {placeholder: ['开始', '结束']},
+                        },
+                    ],
+                },
+                filter: {hiddenQuickFilter: true},
+            }}
+        >
+            <PisellRecordBoard.ShellFrame>
+                <PisellRecordBoard.GridLayout/>
+            </PisellRecordBoard.ShellFrame>
+        </PisellRecordBoard>
+    );
+};
 ```
 
 这样首屏会显示默认日期范围，且首次请求会带上该筛选条件。
@@ -507,10 +591,14 @@ export default () => {
 
 ```
 // 默认开启，无需配置；若需关闭：
-grid={{
-  columns,
-  collapseUniformColumns: false,
-}}
+grid = {
+{
+    columns,
+        collapseUniformColumns
+:
+    false,
+}
+}
 ```
 
 ### grid 透传 antd Table props
@@ -586,33 +674,592 @@ export default function TableOnRowClickExample() {
 }
 ```
 
+## 平面图（Floor Map）
+
+**推荐用法**：在 **`PisellRecordBoard.ShellFrame`** 内与 **`GridLayout`（或 `CardLayout`）并列** 放置 *
+*`PisellRecordBoard.FloorMap`**，把与 **PisellFloorMapLayout** 对齐的 props 写在 `FloorMap` 上（类型为
+`Partial<PisellFloorMapLayoutProps>` 的 `RecordBoardFloorMapProps`）。**传什么用什么**：
+
+| ShellFrame 子节点组合                 | 行为                                                                  |
+|----------------------------------|---------------------------------------------------------------------|
+| 仅 `GridLayout` / `CardLayout`    | 仅表格（或卡片）区，**无**平面图切换                                                |
+| 仅 `FloorMap`                     | 仅平面图，**无** Segmented，无底部分页                                          |
+| `GridLayout`（或 Card）+ `FloorMap` | **双视图**：ToolBar 最左侧 **Segmented**「表格 \| 平面图」；`defaultBodyView` 控制首屏 |
+
+**兼容**：根级仍可传 **`floorMap`**（如 **PisellSalesGrid**、低代码透传）；若同时存在 **`FloorMap` 子组件**，则 *
+*`{...根级 floorMap, ...FloorMap.props}`**，**子 props 覆盖根级**。
+
+- **`defaultBodyView`**：`grid`（默认）或 `floorMap`，仅在 **双视图** 时影响首屏。
+
+- **`floorMapLayoutContext`**（根级，类型为 **`FloorMapLayoutContextValue`**，与 `@pisell/materials` 中平面图 Context 同形）：把
+  **`floorMapConfig`**、**`onSave`**、**`onDataSourceRecordSave`**、**`loading` / `saveError`**、*
+  *`dataSourceLabels` / `dataSourceFormColumns` / `dataSourceRecordForm`** 等注入 Shell *
+  *内置的 `FloorMapLayoutProvider`**，**`floorMap` / `FloorMap` 子组件可只保留展示向 props**（如 `renderItemByKind`、
+  `mapLayer`、`mode`、`getMergedItemWrapperStyle`）。**与表格共用的 `dataSources` 仍应走根级或 `floorMap.dataSources`**
+  ：Shell 合并后以 props 传入 Layout，会**覆盖** Context 中的 `dataSources`。*
+  *`useRecordBoardContext().floorMapLayoutContext`** 与注入 Provider 的 value **同源**，供 ToolBar 等（不在平面图 DOM
+  子树内）读取。
+
+**RecordBoard 层行为**（与 PisellFloorMapLayout 内部编辑能力正交，仅组合方式）：
+
+1. **ShellFrame**：解析子节点，抽出 `FloorMap` 的 props，与根级 `floorMap` 合并；`bodyView === 'grid'` 时为滚动区 + **非
+   FloorMap** 子树；`bodyView === 'floorMap'` 时用 **`FloorMapLayoutProvider`**（value 为根级 **`floorMapLayoutContext`**
+   或稳定空对象）包裹 **PisellFloorMapLayout**（不包 ScrollAreaMeasurer）。`items` /
+   `renderItem` 未传时仍补默认（空列表 / 空渲染）。
+2. **ToolBar**：仅当 **同时存在「表格区子节点」与「平面图槽位」** 时渲染 **Segmented**；否则不显示切换器。
+3. **分页**：仅在 **表格** 子视图展示；**平面图模式无底部分页**。
+
+### 仅平面图：左侧快筛与搜索（无 GridLayout）
+
+ShellFrame 内 **只放 `FloorMap`、不渲染 `GridLayout` / `CardLayout`** 时，ToolBar **仍会**展示 **QuickFilter**（若配置开启）与
+**PisellFind 搜索**；筛值、关键词仍落在 **`searchParams.filter.values`**、**`searchParams.keyword`**，通过 **`onSearch`**
+受控更新。**平面图上的高亮、压暗、按条件过滤展示**不会自动绑定表格逻辑，需业务侧根据 `searchParams` 过滤数据或透传 *
+*`getMergedItemWrapperStyle`** 等自行实现（见 PisellFloorMapLayout 文档）。
+
+配置左侧快筛有两种常见方式：
+
+| 方式       | 做法                                                                                    | 说明                                                                                                                                                                                                                                          |
+|----------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **列派生**  | 根级照常传 **`grid={{ columns }}`**，列上配置 **`filter: { quickFilter: true, … }`**（与其它表格用法一致） | ToolBar 通过 **`deriveFilterFromColumns`** 从 `grid.columns` 生成快筛；**不要求** Shell 内存在 Grid 子节点。不需要「列设置」入口时可设 **`toolBar.columnSetting: false`**。                                                                                                 |
+| **手写快筛** | **`toolBar.quickFilter: { filterList: [...] }`**                                      | `filterList` 项类型为 **`FilterItemProps`**（如 `packages/materials/src/components/filter/types.ts`），例如 `type: 'single'` + `props.options`。配置了 **`filterList`** 时通常 **优先于** 列派生（与 ToolBar 内逻辑一致）。也可写 **`toolBar.quickFilter: true`** 仅启用入口并依赖列派生。 |
+
+搜索行为与表格模式相同：**`toolBar.search`** 控制是否展示及透传 PisellFind。
+
+---
+
+### 数据契约：表格行 ⇄ 平面图落位
+
+| 概念                               | 约定                                     | 说明                                                                                                                                  |
+|----------------------------------|----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
+| 数据源 key                          | 根级或 `FloorMap` 上合并后的 `dataSources` 的键  | 如 `tables`、`assets`，与 `floorMapConfig` 里图元 `dataSourceKey`、落位 `dataSourceKey` 一致                                                    |
+| 行主键                              | 表格 `rowKey`（多为 `id`）                   | 平面图 **`sceneElements[].dataBinding.recordId`** 与表格行 id 一致时，图元与表格行一一对应                                                               |
+| 配置体                              | `floorMapConfig`（`FloorMapViewConfig`） | `canvases`、`canvasUi`（`canCreate`/`canEdit`）、`sceneElements`、`elementKinds`、`elementKindCategories` 等；详细字段见 PisellFloorMapLayout 文档 |
+| `elementKinds` 中 `dataSourceKey` | 可选                                     | 声明该图元从哪个数据源选行再落点                                                                                                                    |
+| `renderItemByKind`               | 按 `elementKind` 渲染卡片                   | 使用 `dataSources` 里对应行数据渲染只读/编辑卡片；可与 Story 中 `getRenderItemByKindTable` 同类                                                           |
+
+**易错点：`RecordBoard` 的 `data`、`dataSources` 与 `gridDataSourceKey`**
+
+- **`data`**：显式传入时，**始终**作为表格数据源（常见为服务端分页的「当前页」）。
+- **根级 `dataSources` + `gridDataSourceKey`**：当 **不传 `data`** 时，容器从 **`dataSources[gridDataSourceKey]`** 取行，并按
+  **`pagination` 做客户端切片** 写入 Context 的 `data`；**`total`** 未传时默认为该数组长度。
+- **`dataSources`（整份多 key）**：供 **平面图** 使用。ShellFrame 计算 *
+  *`mergedDataSources = { ...ctx.dataSources, ...floorMap.dataSources }`**（后者覆盖同 key）再传入 **PisellFloorMapLayout
+  **；**表格分页切片不得缩短此合并结果**，避免多源编辑/落位缺行。
+- 若 ToolBar **筛选/排序** 应对表格与平面图同源：把 **`filteredSortedRows`** 写入对应 key（如 **`dataSources.tables`**
+  ），或继续用显式 **`data` + 全量 `dataSources`** 自行对齐语义。
+
+---
+
+### `floorMap` 常用字段速查（与 RecordBoard 组合时）
+
+| 字段                                                  | 作用                                                                            |
+|-----------------------------------------------------|-------------------------------------------------------------------------------|
+| `floorMapConfig`                                    | 画布、图元类型、落位坐标与尺寸、装饰物等                                                          |
+| `dataSources`                                       | `Record<dataSourceKey, Array< { id: string, … }>>`，行 `id` 与 placement `id` 对齐 |
+| `mode`                                              | `'read'` 只浏览；`'edit'` 可拖放、改落位、侧栏改记录（视 FloorMap 能力）                            |
+| `onSave`                                            | 编辑后保存 **整份** `FloorMapViewConfig`（布局持久化）                                      |
+| `onDataSourceRecordSave`                            | 侧栏保存 **单行** `(dataSourceKey, id, patch)`，合并回业务列表                              |
+| `dataSourceFormColumns` / `dataSourceRecordForm`    | 侧栏「数据源记录」用内置列表单或自定义 React 表单                                                  |
+| `dataSourceLabels`                                  | 数据源展示名                                                                        |
+| `renderItemByKind`                                  | 按 kind 渲染占位上的卡片（需与 `floorMapConfig.elementKinds` 的 `value` 对齐）                |
+| `mapLayer` / `zoom`(`pixel` 下) / `pan` / `controls` | 底图与视口交互，同 PisellFloorMapLayout                                                |
+
+更完整的类型与编辑态说明见 **`pisellFloorMapLayout`** 包内 `docs/`。
+
+---
+
+### 示例一：只读平面图 + 表格分页（同源全量 `dataSources`）
+
+下列示例自包含：**同一批 `rows`** 全量进 `dataSources`，表格只取当前页切片；筛选未演示，避免与上一节「全量/分页」混写。
+`renderItemByKind` 用简单占位，实际项目可换成与设计稿一致的卡片组件。
+
+```tsx
+import React, {useMemo, useState} from 'react';
+import {PisellRecordBoard} from '@pisell/materials';
+import type {RecordBoardColumnType} from '@pisell/materials';
+
+const DS_KEY = 'desks';
+
+type DeskRow = { id: string; name: string; status: string };
+
+const allRows: DeskRow[] = [
+    {id: 'd1', name: 'A1', status: '空'},
+    {id: 'd2', name: 'A2', status: '用'},
+];
+
+/** dataBinding.recordId 与行 id 一致 */
+function buildFloorMapConfig() {
+    return {
+        canvases: [{id: 'main', name: '大厅', order: 0, enabled: true}],
+        canvasUi: {canCreate: false, canEdit: false},
+        elementKinds: [
+            {
+                value: 'table',
+                label: '桌位',
+                dataBindingPolicy: 'optional' as const,
+                allowedDataSourceKeys: [DS_KEY],
+                showInPalette: false,
+            },
+        ],
+        sceneElements: [
+            {
+                instanceId: 'elm_d1',
+                canvasId: 'main',
+                x: 64,
+                y: 64,
+                name: 'A1',
+                width: 120,
+                height: 80,
+                elementKind: 'table',
+                dataBinding: {dataSourceKey: DS_KEY, recordId: 'd1'},
+            },
+            {
+                instanceId: 'elm_d2',
+                canvasId: 'main',
+                x: 220,
+                y: 64,
+                name: 'A2',
+                width: 120,
+                height: 80,
+                elementKind: 'table',
+                dataBinding: {dataSourceKey: DS_KEY, recordId: 'd2'},
+            },
+        ],
+    };
+}
+
+const columns: RecordBoardColumnType[] = [
+    {title: '名称', dataIndex: 'name', key: 'name'},
+    {title: '状态', dataIndex: 'status', key: 'status'},
+];
+
+export default function RecordBoardFloorMapReadonlyExample() {
+    const [pageNumber, setPageNumber] = useState(1);
+    const pageSize = 1;
+    const [searchParams, setSearchParams] = useState<Record<string, unknown>>({});
+
+    const total = allRows.length;
+    const data = useMemo(() => {
+        const start = (pageNumber - 1) * pageSize;
+        return allRows.slice(start, start + pageSize);
+    }, [pageNumber, pageSize]);
+
+    const dataSources = useMemo(
+        () => ({[DS_KEY]: allRows}),
+        []
+    );
+
+    const [floorMapConfig, setFloorMapConfig] = useState(buildFloorMapConfig);
+
+    const floorMap = useMemo(
+        () => ({
+            floorMapConfig,
+            dataSources,
+            mode: 'read' as const,
+            onSave: setFloorMapConfig,
+            renderItemByKind: {
+                table: (item: { name?: string; status?: string }) => (
+                    <div style={{padding: 6, fontSize: 12}}>
+                        <div>{item.name}</div>
+                        <div style={{color: '#888'}}>{item.status}</div>
+                    </div>
+                ),
+            },
+            mapLayer: {backgroundType: 'color' as const, backgroundColor: '#f0f0f0', padding: 16},
+            zoom: {defaultScale: 1, min: 0.5, max: 2},
+            pan: {enabled: true, boundary: 'clamp' as const},
+        }),
+        [floorMapConfig, dataSources]
+    );
+
+    return (
+        <div style={{height: 560}}>
+            <PisellRecordBoard
+                rowKey="id"
+                data={data}
+                loading={false}
+                total={total}
+                pagination={{pageNumber, pageSize}}
+                onPageChange={(n) => {
+                    setPageNumber(n);
+                }}
+                searchParams={searchParams}
+                onSearch={setSearchParams}
+                defaultBodyView="grid"
+                grid={{columns, scroll: {x: 600}}}
+                toolBar={{search: false, filter: false, sort: false}}
+            >
+                <PisellRecordBoard.ShellFrame>
+                    <PisellRecordBoard.GridLayout/>
+                    <PisellRecordBoard.FloorMap {...floorMap} />
+                </PisellRecordBoard.ShellFrame>
+            </PisellRecordBoard>
+        </div>
+    );
+}
+```
+
+---
+
+### 示例二：编辑模式 + 布局保存 + 侧栏行数据写回
+
+与 Storybook **Default** 同一思路：**`onSave`** 更新 `floorMapConfig`；**`onDataSourceRecordSave`** 把侧栏补丁合并进 *
+*`rows` state**（表格与 `dataSources` 都引用该 state）。`mode` 在 `'read'` / `'edit'` 间切换即可。
+
+```tsx
+import React, {useMemo, useState, useCallback} from 'react';
+import {PisellRecordBoard} from '@pisell/materials';
+import type {RecordBoardColumnType} from '@pisell/materials';
+
+const DS_KEY = 'tables';
+
+type Row = { id: string; name: string; status: string; capacity: number };
+
+const columns: RecordBoardColumnType[] = [
+    {title: '名称', dataIndex: 'name', key: 'name', type: 'singleLineText'},
+    {
+        title: '状态',
+        dataIndex: 'status',
+        key: 'status',
+        type: 'singleSelect',
+        fieldProps: {
+            options: [
+                {label: '空', value: '空'},
+                {label: '用', value: '用'},
+            ],
+        },
+    },
+    {title: '人数', dataIndex: 'capacity', key: 'capacity', type: 'number'},
+];
+
+function buildConfig(): Record<string, unknown> {
+    return {
+        canvases: [{id: 'main', name: '大厅', order: 0, enabled: true}],
+        canvasUi: {canCreate: true, canEdit: true},
+        elementKinds: [
+            {
+                value: 'table',
+                label: '桌',
+                dataBindingPolicy: 'optional' as const,
+                allowedDataSourceKeys: [DS_KEY],
+                showInPalette: true,
+            },
+        ],
+        sceneElements: [
+            {
+                instanceId: 'elm_t1',
+                canvasId: 'main',
+                x: 80,
+                y: 80,
+                name: '1号',
+                width: 140,
+                height: 90,
+                elementKind: 'table',
+                dataBinding: {dataSourceKey: DS_KEY, recordId: 't1'},
+            },
+        ],
+    };
+}
+
+export default function RecordBoardFloorMapEditExample() {
+    const [rows, setRows] = useState<Row[]>([
+        {id: 't1', name: '1号', status: '空', capacity: 4},
+    ]);
+    const [floorMapConfig, setFloorMapConfig] = useState(buildConfig);
+    /** 可用 `<Switch checked={mapEdit} onChange={setMapEdit} />` 切换只读 / 编辑 */
+    const [mapEdit, setMapEdit] = useState(true);
+    const [pageNumber, setPageNumber] = useState(1);
+    const pageSize = 10;
+    const [searchParams, setSearchParams] = useState<Record<string, unknown>>({});
+
+    const total = rows.length;
+    const data = useMemo(() => {
+        const start = (pageNumber - 1) * pageSize;
+        return rows.slice(start, start + pageSize);
+    }, [rows, pageNumber, pageSize]);
+
+    const dataSources = useMemo(() => ({[DS_KEY]: rows}), [rows]);
+
+    const handleRecordSave = useCallback((key: string, id: string, patch: Record<string, unknown>) => {
+        if (key !== DS_KEY) return;
+        setRows((prev) => prev.map((r) => (r.id === id ? {...r, ...patch} : r)));
+    }, []);
+
+    const floorMap = useMemo(
+        () => ({
+            floorMapConfig,
+            dataSources,
+            mode: (mapEdit ? 'edit' : 'read') as 'read' | 'edit',
+            onSave: (cfg: Record<string, unknown>) => setFloorMapConfig(cfg),
+            onDataSourceRecordSave: handleRecordSave,
+            dataSourceLabels: {[DS_KEY]: '餐桌'},
+            dataSourceFormColumns: {
+                [DS_KEY]: [
+                    {key: 'name', label: '名称', type: 'string' as const},
+                    {
+                        key: 'status',
+                        label: '状态',
+                        type: 'select' as const,
+                        options: [
+                            {label: '空', value: '空'},
+                            {label: '用', value: '用'},
+                        ],
+                    },
+                    {key: 'capacity', label: '人数', type: 'number' as const},
+                ],
+            },
+            renderItemByKind: {
+                table: (item: Row) => (
+                    <div style={{padding: 6, fontSize: 12}}>
+                        {item.name} · {item.status}
+                    </div>
+                ),
+            },
+            mapLayer: {backgroundType: 'color' as const, backgroundColor: '#f5f5f5', padding: 16},
+            zoom: {defaultScale: 1, min: 0.4, max: 2},
+            pan: {enabled: true, boundary: 'clamp' as const},
+        }),
+        [floorMapConfig, dataSources, mapEdit, handleRecordSave]
+    );
+
+    return (
+        <div style={{height: 620}}>
+            <PisellRecordBoard
+                rowKey="id"
+                data={data}
+                loading={false}
+                total={total}
+                pagination={{pageNumber, pageSize}}
+                onPageChange={(n, s) => {
+                    setPageNumber(n);
+                }}
+                searchParams={searchParams}
+                onSearch={(p) => {
+                    setSearchParams(p);
+                    setPageNumber(1);
+                }}
+                defaultBodyView="grid"
+                grid={{columns, scroll: {x: 720}}}
+                toolBar={{filter: false, sort: false}}
+            >
+                <PisellRecordBoard.ShellFrame>
+                    <PisellRecordBoard.GridLayout/>
+                    <PisellRecordBoard.FloorMap {...floorMap} />
+                </PisellRecordBoard.ShellFrame>
+            </PisellRecordBoard>
+        </div>
+    );
+}
+```
+
+**自定义侧栏表单**：在 **`FloorMap` 的 props**（或与根级合并后的有效 props）上设置
+`dataSourceRecordForm: { [DS_KEY]: (ctx) => <YourForm ctx={ctx} /> }`，在表单提交里调用 `ctx.onSaveRecord?.(values)`
+；关闭该配置则走 `dataSourceFormColumns` 内置表单。完整类型见 PisellFloorMapLayout 的 `FloorMapRecordFormRenderContext`。
+
+---
+
+### 示例三：首屏打开平面图
+
+与 **示例一** 同源数据与 `floorMap` 结构，仅将 **`defaultBodyView` 设为 `"floorMap"`**，首屏即平面图；仍可通过 ToolBar *
+*Segmented** 切回表格。
+
+```tsx
+import React, { useMemo, useState } from 'react';
+import { PisellRecordBoard } from '@pisell/materials';
+import type { RecordBoardColumnType } from '@pisell/materials';
+
+const DS_KEY = 'desks';
+
+type DeskRow = { id: string; name: string; status: string };
+
+const allRows: DeskRow[] = [
+  { id: 'd1', name: 'A1', status: '空' },
+  { id: 'd2', name: 'A2', status: '用' },
+];
+
+function buildFloorMapConfig() {
+  return {
+    canvases: [{ id: 'main', name: '大厅', order: 0, enabled: true }],
+    canvasUi: { canCreate: false, canEdit: false },
+    elementKinds: [
+      {
+        value: 'table',
+        label: '桌位',
+        dataBindingPolicy: 'optional' as const,
+        allowedDataSourceKeys: [DS_KEY],
+        showInPalette: false,
+      },
+    ],
+    sceneElements: [
+      {
+        instanceId: 'elm_d1',
+        canvasId: 'main',
+        x: 64,
+        y: 64,
+        name: 'A1',
+        width: 120,
+        height: 80,
+        elementKind: 'table',
+        dataBinding: { dataSourceKey: DS_KEY, recordId: 'd1' },
+      },
+      {
+        instanceId: 'elm_d2',
+        canvasId: 'main',
+        x: 220,
+        y: 64,
+        name: 'A2',
+        width: 120,
+        height: 80,
+        elementKind: 'table',
+        dataBinding: { dataSourceKey: DS_KEY, recordId: 'd2' },
+      },
+    ],
+  };
+}
+
+const columns: RecordBoardColumnType[] = [
+  { title: '名称', dataIndex: 'name', key: 'name' },
+  { title: '状态', dataIndex: 'status', key: 'status' },
+];
+
+export default function RecordBoardFloorMapDefaultBodyExample() {
+  const [pageNumber, setPageNumber] = useState(1);
+  const pageSize = 1;
+  const [searchParams, setSearchParams] = useState<Record<string, unknown>>({});
+
+  const total = allRows.length;
+  const data = useMemo(() => {
+    const start = (pageNumber - 1) * pageSize;
+    return allRows.slice(start, start + pageSize);
+  }, [pageNumber, pageSize]);
+
+  const dataSources = useMemo(() => ({ [DS_KEY]: allRows }), []);
+
+  const [floorMapConfig, setFloorMapConfig] = useState(buildFloorMapConfig);
+
+  const floorMap = useMemo(
+    () => ({
+      floorMapConfig,
+      dataSources,
+      mode: 'read' as const,
+      onSave: setFloorMapConfig,
+      renderItemByKind: {
+        table: (item: { name?: string; status?: string }) => (
+          <div style={{ padding: 6, fontSize: 12 }}>
+            <div>{item.name}</div>
+            <div style={{ color: '#888' }}>{item.status}</div>
+          </div>
+        ),
+      },
+      mapLayer: {
+        backgroundType: 'color' as const,
+        backgroundColor: '#f0f0f0',
+        padding: 16,
+      },
+      zoom: { defaultScale: 1, min: 0.5, max: 2 },
+      pan: { enabled: true, boundary: 'clamp' as const },
+    }),
+    [floorMapConfig, dataSources]
+  );
+
+  return (
+    <div style={{ height: 560 }}>
+      <PisellRecordBoard
+        rowKey="id"
+        data={data}
+        loading={false}
+        total={total}
+        pagination={{ pageNumber, pageSize }}
+        onPageChange={(n) => setPageNumber(n)}
+        searchParams={searchParams}
+        onSearch={setSearchParams}
+        defaultBodyView="floorMap"
+        grid={{ columns, scroll: { x: 600 } }}
+        toolBar={{ search: false, filter: false, sort: false }}
+      >
+        <PisellRecordBoard.ShellFrame>
+          <PisellRecordBoard.GridLayout />
+          <PisellRecordBoard.FloorMap {...floorMap} />
+        </PisellRecordBoard.ShellFrame>
+      </PisellRecordBoard>
+    </div>
+  );
+}
+```
+
+---
+
+### 与 PisellFloorMapLayout 文档的关系
+
+平面图编辑态、`floorMapConfig` 各字段、`pixel` 坐标、`onSave` / `onDataSourceRecordSave`、`dataSourceFormColumns` /
+`dataSourceRecordForm`、多画布 Tab 等，以 **`pisellFloorMapLayout` 使用文档与开发文档** 为准。RecordBoard 只叠加：**工具栏视图切换
+**、**表格子树与平面图互斥主内容**、**表格模式下底部分页**。
+
+完整交互与「餐厅餐桌」数据（含 `getRenderItemByKindTable`、筛选与排序联动）见 **Storybook → `PisellRecordBoard` → Default**（
+`PisellRecordBoard.stories.tsx`）。
+
+## Storybook 一览
+
+| Story                                                               | 说明                                                                                                                                                           |
+|---------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Default**                                                         | **多源平面图示例**：根级 `dataSources`（餐桌 + 蘸料台）+ **`gridDataSourceKey="tables"`**（不传 `data`，容器客户端分页）；`onSave` / `onDataSourceRecordSave`；侧栏表单与 `getRenderItemByKind*` |
+| GridLayoutWithTable / GridLayoutWithColumnType                      | 基础表格与列 `type` 自动渲染                                                                                                                                           |
+| GridWithMultiplePages                                               | 多页分页                                                                                                                                                         |
+| GridLayoutWithCollapseUniformColumns / GridLayoutWithUniformCompare | 同值列折叠与 `uniformCompare`                                                                                                                                      |
+| GridWithOnRow                                                       | `grid.onRow` 行点击                                                                                                                                             |
+| GridLayoutToolBarSortAndFilter                                      | 工具栏排序与筛选                                                                                                                                                     |
+| GridLayoutWithQuickFilterOnLeft / CustomQuickFilterAndColumnsRender | 左侧快筛与自定义快筛列表                                                                                                                                                 |
+| CustomFilterSortRender                                              | 自定义 filter/sort/render                                                                                                                                       |
+| GridLayoutWithPisellFindInToolBar / GridLayoutToolBarSearchInput    | 搜索形态                                                                                                                                                         |
+| GridLayoutFull                                                      | 完整工具栏组合                                                                                                                                                      |
+| Placeholder / CardLayoutPlaceholder                                 | 占位                                                                                                                                                           |
+| CustomComposition / WithPisellFindSearch / SearchAndGridOnly        | 无 ShellFrame 的拼装                                                                                                                                             |
+
+源码：`PisellRecordBoard.stories.tsx`。
+
+## 类型导出（`@pisell/materials`）
+
+除默认导出的 **`PisellRecordBoard`** 外，可从包内命名导出：
+
+`RecordBoardProps`、`RecordBoardLayoutType`、`RecordBoardContextValue`、`RecordBoardChildComponentProps`、
+`RecordBoardGridProps`、`RecordBoardColumnType`、`RecordBoardFieldType`、`RecordBoardColumnFilterConfig`、
+`RecordBoardOptionItem`、`RecordBoardGetOptions`、`RecordBoardBodyView`、`RecordBoardFloorMapProps`、
+`useRecordBoardContext`。
+
 ## API
 
 ### PisellRecordBoard Props
 
-| 属性                                                                                     | 类型                        | 说明                                                                                                                                                                                                                                                                |
-|----------------------------------------------------------------------------------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| rowKey                                                                                 | string \| (record) => Key | 行主键                                                                                                                                                                                                                                                               |
-| layoutType                                                                             | 'grid' \| 'card'          | 布局类型                                                                                                                                                                                                                                                              |
-| data / loading / total / pagination / onPageChange / searchParams / onSearch / onReset | 各自类型                      | 打散的数据与回调                                                                                                                                                                                                                                                          |
-| grid / toolBar / search / paginationConfig / batchActionBar / cardList                 | 各自类型                      | 打散的子组件配置。**grid** 类型为 RecordBoardGridProps（基于 TableProps 省略 dataSource/loading/pagination/columns/scroll/size/rowSelection），多选在 grid 内；支持 **collapseUniformColumns**（当前页某列全同值/全空时隐藏该列并在表格上方展示总结区）；支持 Table 透传：onRow、onHeaderRow、expandable、rowClassName、summary 等 |
-
-默认占满父容器高度（父容器需有高度，如 `height: 100vh` 或 `height: 100%`），内容区可滚动，分页器贴底。
+| 属性                                                                                     | 类型                                                       | 说明                                                                                                                                                                                                                                                                |
+|----------------------------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| rowKey                                                                                 | string \| (record) => Key                                | 行主键                                                                                                                                                                                                                                                               |
+| layoutType                                                                             | 'grid' \| 'card'                                         | 布局类型                                                                                                                                                                                                                                                              |
+| data / loading / total / pagination / onPageChange / searchParams / onSearch / onReset | 各自类型                                                     | 打散的数据与回调                                                                                                                                                                                                                                                          |
+| dataSources                                                                            | `FloorMapDataSources`（`Record<key, Array<{ id, ... }>>`） | **可选**。根级多路字典，进 Context；与 `FloorMap`/根级 `floorMap` 的 `dataSources` 在 ShellFrame 内合并后给平面图。**不传 `data` 时**可配合 `gridDataSourceKey` 推导表格行（客户端分页切片）                                                                                                                    |
+| gridDataSourceKey                                                                      | `string`                                                 | **可选**。表格绑定的 `dataSources` key；**仅当根级未传 `data`** 时生效                                                                                                                                                                                                              |
+| columnVisibilityStorageKey                                                             | `string`                                                 | 可选；列显隐 + 列顺序持久化存储 key；未传时也可用低代码 `__id`                                                                                                                                                                                                                            |
+| floorMap                                                                               | RecordBoardFloorMapProps                                 | **可选、兼容透传**（如 SalesGrid）。推荐用 Shell 内 **`FloorMap`**；若同时存在，与子组件 props **合并，子优先**。仅根级有平面图而无 Grid 时也会出现平面图区                                                                                                                                                          |
+| defaultBodyView                                                                        | `'grid'` \| `'floorMap'`                                 | **双视图**（Grid/Card + `FloorMap`）时首屏子视图，默认 `'grid'`                                                                                                                                                                                                                 |
+| grid / toolBar / search / paginationConfig / batchActionBar / cardList                 | 各自类型                                                     | 打散的子组件配置。**grid** 类型为 RecordBoardGridProps（基于 TableProps 省略 dataSource/loading/pagination/columns/scroll/size/rowSelection），多选在 grid 内；支持 **collapseUniformColumns**（当前页某列全同值/全空时隐藏该列并在表格上方展示总结区）；支持 Table 透传：onRow、onHeaderRow、expandable、rowClassName、summary 等 |
+
+默认占满父容器高度（父容器需有高度，如 `height: 100vh` 或 `height: 100%`），内容区可滚动，分页器贴底（**平面图模式下分页不展示
+**）。
 
 ### 子组件
 
-| 子组件                                     | 说明                                                                                                                          |
-|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
-| PisellRecordBoard.ShellFrame            | 外壳：ToolBar + BatchActionBar + children(Layout) + Pagination；ToolBar 右侧可选列设置入口；分页使用定制样式（record-board-shell-frame-pagination） |
-| PisellRecordBoard.GridLayout            | 表格布局                                                                                                                        |
-| PisellRecordBoard.CardLayout            | 卡片布局                                                                                                                        |
-| PisellRecordBoard.ToolBar               | 工具栏（含搜索、QuickFilter、Sort、Filter、列设置、Reset、slots）                                                                            |
-| PisellRecordBoard.Search                | 搜索槽                                                                                                                         |
-| PisellRecordBoard.Pagination            | 分页槽                                                                                                                         |
-| PisellRecordBoard.Grid                  | 表格视图（支持 columnVisibility 列显示隐藏）                                                                                             |
-| PisellRecordBoard.CardList              | 卡片列表视图                                                                                                                      |
-| PisellRecordBoard.BatchActionBar        | 多选操作栏                                                                                                                       |
-| PisellRecordBoard.useRecordBoardContext | 消费上下文的 Hook                                                                                                                 |
+| 子组件                                     | 说明                                                                                                                                              |
+|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| PisellRecordBoard.ShellFrame            | 外壳：解析 GridLayout / CardLayout / **FloorMap** 子节点，合并平面图 props（子优先），渲染主内容与分页；双视图时 ToolBar 出现表格·平面图切换；切到平面图时不包裹 ScrollAreaMeasurer；**分页仅在表格子视图显示** |
+| PisellRecordBoard.GridLayout            | 表格布局                                                                                                                                            |
+| PisellRecordBoard.CardLayout            | 卡片布局                                                                                                                                            |
+| PisellRecordBoard.FloorMap              | 平面图槽位（无 DOM），props 对齐 PisellFloorMapLayout；仅在 ShellFrame 内使用；与 Grid/Card 并存时出现 Segmented                                                        |
+| PisellRecordBoard.ToolBar               | 工具栏（含搜索、QuickFilter、Sort、Filter、列设置、Reset、slots）                                                                                                |
+| PisellRecordBoard.Search                | 搜索槽                                                                                                                                             |
+| PisellRecordBoard.Pagination            | 分页槽                                                                                                                                             |
+| PisellRecordBoard.Grid                  | 表格视图（支持 columnVisibility 列显示隐藏）                                                                                                                 |
+| PisellRecordBoard.CardList              | 卡片列表视图                                                                                                                                          |
+| PisellRecordBoard.BatchActionBar        | 多选操作栏                                                                                                                                           |
+| PisellRecordBoard.useRecordBoardContext | 消费上下文的 Hook                                                                                                                                     |
 
 ### 列配置（RecordBoardColumnType）
 
@@ -644,9 +1291,8 @@ export default function TableOnRowClickExample() {
 
 ## 相关文档
 
-- [Shell Frame 外壳说明](./ShellFrame.md)
-- [架构说明](./architecture.md)
-- [列与筛选/排序绑定](./columns-filter-binding.md)
-- [设计文档](./PisellRecordBoard.$tab-design.md)
-- [开发文档](./PisellRecordBoard.$tab-dev.md)
-- [测试文档](./PisellRecordBoard.$tab-test.md)
+- [Shell Frame 外壳说明](./ShellFrame.md)（工具栏/批量栏/分页模块拆解）
+- [设计文档](./PisellRecordBoard.$tab-design.md)（概念、数据流、扩展）
+- [开发文档](./PisellRecordBoard.$tab-dev.md)（目录结构、实现细节、与 PisellFloorMapLayout 分支）
+- [测试文档](./PisellRecordBoard.$tab-test.md)（单测建议、Story、回归清单）
+- 平面图能力详见 **`pisellFloorMapLayout`** 组件文档（同包 `docs/`）