@pisell/materials 1.8.38 → 1.8.41

package/lib/components/pisellFloorMapLayout/docs/pisellFloorMapLayout.md

@@ -32,85 +32,44 @@ PisellFloorMapLayout 是**空间布局视图**组件，在二维平面内按坐
 - 🗺 **底图层**：支持无背景 / 纯色 / 图片 / SVG 背景、可选网格线、底层 padding 与 gap。
 - 🎯 **Item 交互**：支持 hover 高亮与开关（`enableHover`），以及 `onItemClick`、`onItemHover`、`onItemLeave` 事件。
 - 🎭 **TypeScript**：完整类型导出（Props、Ref、FloorMapItemBase、各类 Config、Shape 等）。
-- 📦 **可选 Context**：**`FloorMapLayoutProvider`** 注入 **`FloorMapLayoutContextValue`**（配置/保存/数据源/侧栏表单等）；*
-  *`PisellRecordBoard`** 根级 **`floorMapLayoutContext`** 由 Shell **内置 Provider**，无需再包一层。
 
-## 运行模式与代码结构
+## 组件结构
 
-### 两种用法
-
-| 模式       | 条件                      | 渲染数据来源                                                                                                                                            | 说明                                                                                                        |
-|----------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
-| **基础布局** | 不传 `floorMapConfig`     | 外部传入的 **`items`** + **`renderItem`**                                                                                                              | 与早期版本一致；`itemUnit` 可为 `cell` 或 `pixel`。                                                                   |
-| **平面图**  | 传入 **`floorMapConfig`** | 内部用 **`mergeCanvasItems`** 合并当前画布的 **`sceneElements`** 得到 **`FloorMapMergedItem[]`**（`id` = `instanceId`），作为内部 `items`；**`itemUnit` 强制为 `pixel`** | 需同时提供 **`dataSources`**；行级绑定见各图元的 **`dataBinding`**；可选 **`renderItemByKind`**、**`onElementRenderError`**。 |
-
-逻辑封装在 **`useFloorMapEditState`**（草稿/画布/选中/落位/侧栏参数）与 **`useFloorMapTransformMetrics`**（内容区尺寸、缩放
-fitBounds、全屏等）；纯计算在 **`utils/layoutMeasurements.ts`**、**`utils/floorMapConfigMerge.ts`**，占位渲染在 *
-*`utils/floorMapFallbackRender.tsx`**。目录与职责详见 [开发文档](./pisellFloorMapLayout.$tab-dev.md)。
-
-### 阅读态下的组件树（未传 floorMapConfig 或 mode='read'）
-
-根容器内由 **react-zoom-pan-pinch** 的 `TransformWrapper` 提供缩放/平移；**`ViewControlsWithZoom`** 在 Wrapper 子树内使用
-`useControls` 桥接 **`ViewControls`**。
-
-```
-PisellFloorMapLayout 根容器
-└── TransformWrapper
-    ├── TransformComponent
-    │   ├── MapLayer（背景、网格、padding、gap）
-    │   └── ItemLayer（items + renderItem，可选 hover/点击）
-    └── ViewControlsWithZoom → ViewControls（左下角：缩放 / 复位 / fitBounds / 全屏）
-```
-
-### 编辑态下的组件树（floorMapConfig + mode='edit'）
-
-在「阅读态」树之外，增加：**顶部 `FloorMapEditTopBar`（内含 `CanvasTabs` + 保存/全屏/区域定位等）**、**左侧 `FloorMapToolbar`
-**、**Transform 内 `EditableItemLayer` 替代 `ItemLayer`**、可选 **落点遮罩**、**拖入图源层**、**右侧 `FloorMapEditPanel`**。
+当前组件的层级与职责如下。根容器内由 **react-zoom-pan-pinch** 的 `TransformWrapper` 提供缩放/平移能力，可变换内容放在
+`TransformComponent` 内（底图层 + 展示层），视图控制条在 wrapper 内、内容区外，固定在视口左下角。
 
 ```
 PisellFloorMapLayout 根容器
-├── FloorMapEditTopBar（toggle：紧凑顶栏含进入全屏 / 全屏后含保存与退出；locked：始终全屏顶栏且无退出；disabled：仅 Tab）
-└── 双栏 flex
-    ├── FloorMapToolbar（图元调色板可拖至画布、绑定数据；保存见 toolbarShowSave）
-    └── 地图区
-        └── TransformWrapper
-            ├── TransformComponent
-            │   ├── MapLayer（编辑态底层通常 pointer-events: none）
-            │   ├── EditableItemLayer（选中、拖拽、缩放）或 ItemLayer（只读）
-            │   ├── [可选] 落点遮罩 .pisell-floor-map-layout-place-overlay
-            │   └── 拖入图源层 .pisell-floor-map-layout-map-drop-layer（激活时接收 drop）
-            ├── ViewControlsWithZoom（编辑态下全屏/fitBounds 已迁至顶栏时，此处仅缩放等）
-            └── FloorMapEditPanel（图元属性 + 数据源记录）
+└── TransformWrapper（react-zoom-pan-pinch）
+    ├── TransformComponent（可缩放/平移的内容区）
+    │   ├── MapLayer 底图层（背景、网格线、padding、gap）
+    │   └── ItemLayer 展示层（按 items + renderItem 渲染资源项）
+    └── ViewControls（左下角固定：缩放 Stepper / 复位 / 区域定位 / 全屏）
 ```
 
-| 节点                                | 职责                                                                        | 主要输入                                              |
-|-----------------------------------|---------------------------------------------------------------------------|---------------------------------------------------|
-| **PisellFloorMapLayout**          | 编排子组件；`forwardRef` 暴露缩放/fitBounds；注入 `contentOffsetRef` 供落点换算             | 见 **API** 与 `types.ts`                            |
-| **useFloorMapEditState**          | `draftConfig`、`mergedItems`、`placeMode`、`editPanelParams`、落点/侧栏回调         | `floorMapConfig`、`dataSources`、`onSave` 等         |
-| **useFloorMapTransformMetrics**   | `contentWidth/Height`、`contentOffsetX/Y`、`fitBounds`、全屏、拖拽图元后恢复 transform | `items`、`zoom`、`mode`、refs                        |
-| **MapLayer**                      | 底层背景/网格/padding                                                           | `mapLayer`、content 尺寸                             |
-| **ItemLayer / EditableItemLayer** | 按坐标渲染图元；编辑态可拖拽缩放                                                          | `items`、`renderItem` 或 `effectiveRenderItem`      |
-| **FloorMapEditTopBar**            | 画布 Tab、布局保存、全屏、可选区域定位                                                     | `config`、`onSave`、`controls`、`toggleFullscreen` 等 |
-| **FloorMapToolbar**               | 放置模式、数据源预览；保存可选（`toolbarShowSave`）                                        | `config`、`dataSources`、`placeMode`                |
-| **FloorMapEditPanel**             | 图元表单；**数据源记录**（绑定行 + `FloorMapDataForm` **或** `dataSourceRecordForm`）     | `editPanelParams`                                 |
-| **ViewControlsWithZoom**          | 在 Transform 上下文内连接 `ViewControls`                                         | `fitBounds`、`toggleFullscreen`、`scale`            |
-
-**数据流简述（基础模式）**：外部 `items` + `mapLayer` + `cellSize` + `itemUnit` → `useFloorMapTransformMetrics` 中
-`getContentSize` / `getPixelBoundingBox` 得到 content 尺寸与偏移 → MapLayer、ItemLayer；缩放由 `onTransformed` 同步。
+| 节点                       | 职责                                                                    | 主要输入                                                                                        |
+|--------------------------|-----------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
+| **PisellFloorMapLayout** | 解析 props、计算 content 尺寸、组装子组件、暴露 Ref（zoomIn/zoomOut/reset/fitBounds）   | items、renderItem、mapLayer、zoom、pan、controls 等                                               |
+| **TransformWrapper**     | 提供缩放/平移上下文与 API；onTransformed 同步 scale 给 ViewControls                 | initialScale、minScale、maxScale、step、panning                                                 |
+| **TransformComponent**   | 承载可缩放、可平移的 DOM 区域，尺寸为 contentWidth × contentHeight                    | contentStyle、wrapperStyle                                                                   |
+| **MapLayer**             | 渲染底层：背景（无/纯色/图片/SVG）、可选网格线、padding/gap                                | config（mapLayer）、contentWidth、contentHeight、cellSize                                        |
+| **ItemLayer**            | 按 items 的 (x, y) 与单位（cell/pixel）定位，用 renderItem 渲染每个资源项；派发点击、hover 事件 | items、renderItem、rowKey、cellSize、itemUnit、itemGap、content 尺寸、事件回调                           |
+| **ViewControls**         | 左下角固定：缩放 Stepper（减号 + 百分比 + 加号）、复位、区域定位、全屏按钮                          | api（zoomIn/zoomOut/resetTransform/fitBounds/toggleFullscreen）、config（显隐）、scale、isFullscreen |
 
-**数据流简述（平面图编辑）**：外部 `floorMapConfig` 写入 **`draftConfig`**（内存草稿）→ **`onSave(draftConfig)`**
-持久化布局；业务行数据通过 **`onDataSourceRecordSave`** 写回各数据源，**与布局配置分离**。
+**数据流简述**：`items`、`mapLayer`、`cellSize`、`itemUnit` 等由父组件传入 → 主组件用 `getContentSize` 算出 `contentWidth` /
+`contentHeight` → 传给 MapLayer、ItemLayer；缩放状态由 TransformWrapper 的 `onTransformed` 回写为 `scale`，再传入
+ViewControls 显示百分比。交互：用户操作 ViewControls 或直接滚轮/拖拽 → TransformWrapper 更新变换 → 仅展示与事件向上抛出，无内部业务状态。
 
 **使用技术**：
 
-| 技术                       | 用途                                                                                               |
-|--------------------------|--------------------------------------------------------------------------------------------------|
-| **React**                | 组件与 Hooks；主文件组合双 Hook。                                                                           |
-| **TypeScript**           | `types.ts`：`PisellFloorMapLayoutProps`、`FloorMapViewConfig`、`FloorMapRecordFormRenderContext` 等。 |
-| **react-zoom-pan-pinch** | `TransformWrapper` / `TransformComponent`、`useControls`。                                         |
-| **Less**                 | 类名前缀 `pisell-floor-map-layout`。                                                                  |
-| **classNames**           | 根样式变体（floor-map-view、mode-edit）。                                                                 |
-| **@ant-design/icons**    | 视图控制图标；侧栏关闭等。                                                                                    |
+| 技术                       | 用途                                                                                          |
+|--------------------------|---------------------------------------------------------------------------------------------|
+| **React**                | 组件框架；使用 useMemo、useRef、useImperativeHandle、useCallback、useState 等 Hooks。                    |
+| **TypeScript**           | 类型定义与导出（Props、Ref、FloorMapItemBase、各类 Config 等见 `types.ts`）。                                |
+| **react-zoom-pan-pinch** | 缩放与平移：`TransformWrapper` 提供上下文与 API，`TransformComponent` 承载可变换内容；支持滚轮、捏合、拖拽。                |
+| **Less**                 | 样式：主组件与子组件（MapLayer、ItemLayer、ViewControls）均使用 `.less` 编写，类名统一前缀 `pisell-floor-map-layout`。 |
+| **classNames**           | 动态类名拼接。                                                                                     |
+| **@ant-design/icons**    | ViewControls 中缩放 Stepper 的减号、加号图标（MinusOutlined、PlusOutlined）。                              |
 
 ## 基础用法
 
@@ -131,37 +90,35 @@ const itemColors: Record<string, { bg: string; border: string }> = {
     C: {bg: '#fff7e6', border: '#fa8c16'},
 };
 
-export default function Demo() {
-    return (
-        <PisellFloorMapLayout
-            items={items}
-            renderItem={(item) => {
-                const {bg, border} = itemColors[item.id] || {bg: '#f5f5f5', border: '#d9d9d9'};
-                return (
-                    <div style={{
-                        width: '100%',
-                        height: '100%',
-                        boxSizing: 'border-box',
-                        display: 'flex',
-                        alignItems: 'center',
-                        justifyContent: 'center',
-                        background: bg,
-                        border: `3px solid ${border}`,
-                        borderRadius: 6,
-                        fontWeight: 600,
-                        color: '#262626'
-                    }}>
-                        {item.id}
-                    </div>
-                );
-            }}
-            mapLayer={{backgroundType: 'color', backgroundColor: '#f0f0f0', padding: 16, gap: 8}}
-            zoom={{defaultScale: 1, min: 0.5, max: 2}}
-            pan={{enabled: true}}
-            style={{height: 400}}
-        />
-    );
-}
+export default () => (
+    <PisellFloorMapLayout
+        items={items}
+        renderItem={(item) => {
+            const {bg, border} = itemColors[item.id] || {bg: '#f5f5f5', border: '#d9d9d9'};
+            return (
+                <div style={{
+                    width: '100%',
+                    height: '100%',
+                    boxSizing: 'border-box',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    background: bg,
+                    border: `3px solid ${border}`,
+                    borderRadius: 6,
+                    fontWeight: 600,
+                    color: '#262626'
+                }}>
+                    {item.id}
+                </div>
+            );
+        }}
+        mapLayer={{backgroundType: 'color', backgroundColor: '#f0f0f0', padding: 16, gap: 8}}
+        zoom={{defaultScale: 1, min: 0.5, max: 2}}
+        pan={{enabled: true}}
+        style={{height: 400}}
+    />
+);
 ```
 
 ## 坐标与尺寸单位（itemUnit）
@@ -183,30 +140,28 @@ const items: FloorMapItemBase[] = [
     {id: '2', x: 1, y: 0, width: 2, height: 1},
 ];
 
-export default function CellDemo() {
-    return (
-        <PisellFloorMapLayout
-            itemUnit="cell"
-            cellSize={64}
-            mapLayer={{gap: 8, backgroundType: 'color', backgroundColor: '#e8e8e8'}}
-            items={items}
-            renderItem={(item) => (
-                <div
-                    style={{
-                        width: '100%', height: '100%', boxSizing: 'border-box',
-                        display: 'flex', alignItems: 'center', justifyContent: 'center',
-                        background: item.id === '1' ? '#d6e4ff' : '#d9f7be',
-                        border: `3px solid ${item.id === '1' ? '#597ef7' : '#73d13d'}`,
-                        borderRadius: 6, fontWeight: 600, color: '#262626',
-                    }}
-                >
-                    {item.id}
-                </div>
-            )}
-            style={{height: 320}}
-        />
-    );
-}
+export default () => (
+    <PisellFloorMapLayout
+        itemUnit="cell"
+        cellSize={64}
+        mapLayer={{gap: 8, backgroundType: 'color', backgroundColor: '#e8e8e8'}}
+        items={items}
+        renderItem={(item) => (
+            <div
+                style={{
+                    width: '100%', height: '100%', boxSizing: 'border-box',
+                    display: 'flex', alignItems: 'center', justifyContent: 'center',
+                    background: item.id === '1' ? '#d6e4ff' : '#d9f7be',
+                    border: `3px solid ${item.id === '1' ? '#597ef7' : '#73d13d'}`,
+                    borderRadius: 6, fontWeight: 600, color: '#262626',
+                }}
+            >
+                {item.id}
+            </div>
+        )}
+        style={{height: 320}}
+    />
+);
 ```
 
 **像素布局示例**（自由位置与尺寸）：
@@ -221,30 +176,28 @@ const items: FloorMapItemBase[] = [
     {id: '2', x: 140, y: 20, width: 200, height: 80},
 ];
 
-export default function PixelDemo() {
-    return (
-        <PisellFloorMapLayout
-            itemUnit="pixel"
-            cellSize={64}
-            items={items}
-            mapLayer={{backgroundType: 'color', backgroundColor: '#f0f0f0', padding: 12}}
-            renderItem={(item) => (
-                <div
-                    style={{
-                        width: '100%', height: '100%', boxSizing: 'border-box',
-                        display: 'flex', alignItems: 'center', justifyContent: 'center',
-                        background: item.id === '1' ? '#ffd6e7' : '#ffe7ba',
-                        border: `3px solid ${item.id === '1' ? '#eb2f96' : '#fa8c16'}`,
-                        borderRadius: 8, fontWeight: 600, color: '#262626',
-                    }}
-                >
-                    {item.id}
-                </div>
-            )}
-            style={{height: 320}}
-        />
-    );
-}
+export default () => (
+    <PisellFloorMapLayout
+        itemUnit="pixel"
+        cellSize={64}
+        items={items}
+        mapLayer={{backgroundType: 'color', backgroundColor: '#f0f0f0', padding: 12}}
+        renderItem={(item) => (
+            <div
+                style={{
+                    width: '100%', height: '100%', boxSizing: 'border-box',
+                    display: 'flex', alignItems: 'center', justifyContent: 'center',
+                    background: item.id === '1' ? '#ffd6e7' : '#ffe7ba',
+                    border: `3px solid ${item.id === '1' ? '#eb2f96' : '#fa8c16'}`,
+                    borderRadius: 8, fontWeight: 600, color: '#262626',
+                }}
+            >
+                {item.id}
+            </div>
+        )}
+        style={{height: 320}}
+    />
+);
 ```
 
 ## 视图控制与 Ref
@@ -253,11 +206,6 @@ export default function PixelDemo() {
 `showFitBounds`、`showFullscreen` 才会显示复位、区域定位与全屏按钮。全屏按钮点击后对根容器调用 `requestFullscreen()`，再次点击或按
 Esc 退出全屏。
 
-**平面图编辑态**（`floorMapConfig` + `mode='edit'`）：默认 **`floorMapFullscreenMode='toggle'`** 时，**非浏览器全屏**顶栏为*
-*画布 Tab + 进入全屏**；**全屏**后顶栏另含保存、`showFitBounds` 区域定位与**退出全屏**。设为 **`locked`** 时始终使用「全屏顶栏」布局且
-**不展示退出全屏**（适合外层遮罩铺满）；**`disabled`** 时**无全屏按钮**，保存仍在侧栏（与 `toolbarShowSave` 一致）。左下角控件条保留缩放（及
-`showReset` 若开启）。
-
 通过 **ref** 可编程控制视图：
 
 | 方法            | 说明            |
@@ -274,7 +222,7 @@ import type {PisellFloorMapLayoutRef, FloorMapItemBase} from '@pisell/materials'
 
 const items: FloorMapItemBase[] = [{id: '1', x: 0, y: 0}];
 
-export default function Demo() {
+export default () => {
     const ref = useRef<PisellFloorMapLayoutRef>(null);
     return (
         <>
@@ -308,7 +256,7 @@ export default function Demo() {
             />
         </>
     );
-}
+};
 ```
 
 ## 事件
@@ -319,323 +267,25 @@ export default function Demo() {
 
 可通过 `enableHover={false}` 关闭 hover 高亮与 hover 事件。
 
-## 平面图与数据源（可选）
-
-当传入 **`floorMapConfig`** 时进入**平面图模式**：
-
-- **布局持久化**：编辑态修改画布列表、落位、装饰等，通过顶栏 **「保存」**（`onSave`）将完整 **`FloorMapViewConfig`**
-  （草稿）交给上游保存。若需在左侧工具栏重复保存按钮，可设 **`toolbarShowSave`**。
-- **侧栏拖拽落位**：从左侧图元栏**拖拽**图元卡片到画布，在落点生成对应 `sceneElement`
-  （规则与先选类型再点击画布落点一致）。不再支持将外部图片文件/链接拖入画布自动转为图源图元。
-- **业务记录**：侧栏「数据源记录」通过 **`onDataSourceRecordSave(dataSourceKey, recordId, partialRecord)`** 更新单行；与表格等
-  UI 同源时，应在同一 state 上合并，保证列表与画布卡片一致。
-- **记录表单**：
-  - **`dataSourceFormColumns`**：按数据源 key 配置列，内置 **`FloorMapDataForm`** 自动生成表单项；
-  - **`dataSourceRecordForm`**：按 key 传入 **`ReactNode`** 或 **`(ctx: FloorMapRecordFormRenderContext) => ReactNode`**，
-    **替换**该 key 下的内置表单，用于复杂校验、分步、联动；`ctx.onSaveRecord` 与内置保存通道一致（需配置
-    `onDataSourceRecordSave`）。
-- **与 RecordBoard**：`floorMap` 使用本组件 **`Partial<PisellFloorMapLayoutProps>`**；根级还可传 **`floorMapLayoutContext`
-  **（与 **`FloorMapLayoutContextValue`** 同形），由 Shell **内置 `FloorMapLayoutProvider`**。完整组合示例见下文「RecordBoard
-  根级注入」；Story **PisellRecordBoard → Default** 已拆分 `floorMapLayoutContext` 与精简 `FloorMap`。
-
-### FloorMapLayoutProvider 与数据分流
-
-**合并规则**：`PisellFloorMapLayout` 内部对 Context 承载字段按 **`props ?? context`** 合并，**Layout 上显式传入的 props 优先
-**。未使用 Provider 或未传某字段时，行为与原先全部走 props 一致。
-
-**适合放入 Context（`FloorMapLayoutContextValue`）的字段**：`floorMapConfig`、`dataSources`（见下注意）、`onSave`、
-`onDataSourceRecordSave`、`dataSourceLabels`、`dataSourceFormColumns`、`dataSourceRecordForm`、`loading`、`saveError`、
-`onElementRenderError`、`toolbarShowSave`、`floorMapFullscreenMode`。
-
-**建议仍走 Layout / RecordBoard `floorMap` 的 props**：`renderItem`、`renderItemByKind`、`mapLayer`、`cellSize`、`zoom` /
-`pan` / `controls`、`className` / `style`、基础模式 `items`、`enableHover`、`onItemClick` 等展示与交互。
-
-**RecordBoard 与 `dataSources`**：Shell 会将根级 **`dataSources`** 与 **`floorMap.dataSources`** 合并后以 **props** 传入
-Layout，**会覆盖** Context 中的 **`dataSources`**。表格与平面图共用多数据源时，请仍使用根级 / `floorMap` 的 **`dataSources`
-**，不要仅依赖 **`floorMapLayoutContext.dataSources`**。
-
-**工具栏读取配置**：平面图节点在 **`FloorMapLayoutProvider`** 子树内；**`useRecordBoardContext().floorMapLayoutContext`**
-与注入 Provider 的 value **同源**，供 ToolBar 等不在平面图 DOM 子树内的节点读取。
-
-| 数据类型                                 | Context / `floorMapLayoutContext` | 直接 `PisellFloorMapLayout` props | RecordBoard `floorMap` + 根级 `dataSources` |
-|--------------------------------------|-----------------------------------|---------------------------------|-------------------------------------------|
-| 布局配置、保存回调、加载/错误                      | 推荐                                | 可                               | 可（合并后以 props 进入 Layout）                   |
-| 与表格共用的 `dataSources`                 | 易被 RecordBoard 的 props 覆盖         | 可                               | **推荐**                                    |
-| `renderItem`、`mapLayer`、`controls` 等 | 不推荐放入 Context                     | 推荐                              | **推荐写在 `floorMap` / `FloorMap`**          |
-
-#### 示例一：单独页面 — `FloorMapLayoutProvider` + Layout（仅展示向在 Layout）
-
-业务在父组件请求/聚合配置与数据源，将 **`value` 用 `useMemo` 稳定化**；子树内任意深度的 **`PisellFloorMapLayout`** 均可合并到
-Context。
-
-```tsx
-import React, {useCallback, useMemo, useState} from 'react';
-import {
-    PisellFloorMapLayout,
-    FloorMapLayoutProvider,
-} from '@pisell/materials';
-import type {FloorMapLayoutContextValue, FloorMapViewConfig} from '@pisell/materials';
-
-export default function FloorMapEditorWithProvider() {
-    const [config, setConfig] = useState<FloorMapViewConfig | undefined>();
-    const [tables, setTables] = useState<Array<{ id: string; name?: string }>>([]);
-    const [loading] = useState(false);
-    const [saveError, setSaveError] = useState<Error | undefined>();
-
-    const handleSave = useCallback((next: FloorMapViewConfig) => {
-        setSaveError(undefined);
-        setConfig(next);
-        void fetch('/api/floor-map', {
-            method: 'PUT',
-            body: JSON.stringify(next),
-        }).catch((e) => {
-            setSaveError(e instanceof Error ? e : new Error(String(e)));
-        });
-    }, []);
-
-    const providerValue = useMemo<FloorMapLayoutContextValue>(
-        () => ({
-            floorMapConfig: config,
-            dataSources: {tables},
-            onSave: handleSave,
-            onDataSourceRecordSave: (key, id, partial) => {
-                setTables((prev) =>
-                    prev.map((row) => (row.id === id ? {...row, ...partial} : row))
-                );
-            },
-            dataSourceLabels: {tables: '桌台'},
-            loading,
-            saveError,
-        }),
-        [config, tables, handleSave, loading, saveError]
-    );
-
-    return (
-        <FloorMapLayoutProvider value={providerValue}>
-            <div style={{height: '100vh'}}>
-                <PisellFloorMapLayout
-                    items={[]}
-                    mode="edit"
-                    mapLayer={{backgroundType: 'color', backgroundColor: '#f0f0f0', padding: 16}}
-                    controls={{showFitBounds: true}}
-                    renderItem={(item) => <span>{item.id}</span>}
-                />
-            </div>
-        </FloorMapLayoutProvider>
-    );
-}
-```
-
-#### 示例二：props 覆盖 Context
-
-同一 Provider 下，某一 Layout 需要**不同的** `loading` 等时，在 **`PisellFloorMapLayout`** 上显式传入即可（该字段优先）。
-
-```tsx
-import React, {useMemo} from 'react';
-import {
-    PisellFloorMapLayout,
-    FloorMapLayoutProvider,
-} from '@pisell/materials';
-import type {FloorMapLayoutContextValue} from '@pisell/materials';
-
-export default function FloorMapOverrideLoading() {
-    const providerValue = useMemo<FloorMapLayoutContextValue>(
-        () => ({loading: true}),
-        []
-    );
-    return (
-        <FloorMapLayoutProvider value={providerValue}>
-            <PisellFloorMapLayout
-                items={[{id: '1', x: 0, y: 0}]}
-                renderItem={(item) => <span>{item.id}</span>}
-                loading={false}
-                mapLayer={{backgroundType: 'color', backgroundColor: '#f5f5f5', padding: 16}}
-            />
-        </FloorMapLayoutProvider>
-    );
-}
-```
-
-#### 示例三：深层节点读取 — `useFloorMapLayoutContext`
-
-```tsx
-import React from 'react';
-import {useFloorMapLayoutContext} from '@pisell/materials';
-
-export default function FloorMapCanvasTitle() {
-    const ctx = useFloorMapLayoutContext();
-    const name = ctx?.floorMapConfig?.canvases?.[0]?.name ?? '—';
-    return <span>当前画布：{name}</span>;
-}
-```
-
-无 Provider 时 **`useFloorMapLayoutContext()`** 返回 **`undefined`**，调用方需判空。该组件须渲染在 *
-*`FloorMapLayoutProvider`** 子树下（RecordBoard 下即平面图区域所在子树）。
-
-#### 示例四：PisellRecordBoard — 根级 `floorMapLayoutContext`（无需再包 Provider）
-
-**`floorMap` / `PisellRecordBoard.FloorMap`** 写展示向配置；**`floorMapLayoutContext`** 写 **`floorMapConfig`**、*
-*`onSave`**、侧栏表单等。Shell 内 **`GridLayout` / 列配置**
-等见 [PisellRecordBoard 文档](../pisellRecordBoard/docs/PisellRecordBoard.md)。
-
-```tsx
-import React, {useCallback, useMemo, useState} from 'react';
-import {PisellRecordBoard} from '@pisell/materials';
-import type {FloorMapLayoutContextValue, FloorMapViewConfig} from '@pisell/materials';
-
-export default function RecordBoardFloorMapContextDemo() {
-    const [floorMapConfig, setFloorMapConfig] = useState<FloorMapViewConfig | undefined>();
-    const handleSaveLayout = useCallback((config: FloorMapViewConfig) => {
-        setFloorMapConfig(config);
-    }, []);
-    const handleSaveRecord = useCallback(
-        (_dataSourceKey: string, _id: string, _patch: Record<string, unknown>) => {
-        },
-        []
-    );
-
-    const floorMapLayoutContext = useMemo<FloorMapLayoutContextValue>(
-        () => ({
-            floorMapConfig,
-            onSave: handleSaveLayout,
-            onDataSourceRecordSave: handleSaveRecord,
-            loading: false,
-            floorMapFullscreenMode: 'toggle',
-        }),
-        [floorMapConfig, handleSaveLayout, handleSaveRecord]
-    );
-
-    return (
-        <PisellRecordBoard
-            data={[]}
-            dataSources={{tables: []}}
-            pagination={{pageNumber: 1, pageSize: 10}}
-            onPageChange={() => {
-            }}
-            searchParams={{}}
-            onSearch={() => {
-            }}
-            floorMapLayoutContext={floorMapLayoutContext}
-            floorMap={{
-                mode: 'edit',
-                mapLayer: {backgroundType: 'color', backgroundColor: '#f5f5f5', padding: 16},
-                items: [],
-                renderItem: () => null,
-            }}
-            grid={{
-                columns: [{title: 'ID', dataIndex: 'id', key: 'id'}],
-            }}
-        >
-            <PisellRecordBoard.ShellFrame>
-                <PisellRecordBoard.GridLayout/>
-                <PisellRecordBoard.FloorMap/>
-            </PisellRecordBoard.ShellFrame>
-        </PisellRecordBoard>
-    );
-}
-```
-
-**导出说明**（自 **`@pisell/materials`** 或包内 **`pisellFloorMapLayout`**）：**`FloorMapLayoutProvider`**、*
-*`FloorMapLayoutProviderProps`**、**`useFloorMapLayoutContext`**、**`EMPTY_FLOOR_MAP_LAYOUT_CONTEXT`**、*
-*`mergeFloorMapLayoutPropsFromContext`**、类型 **`FloorMapLayoutContextValue`**。详见下文 **API** 小节。
-
-更多实现细节见 **`types.ts`** 与 [开发文档](./pisellFloorMapLayout.$tab-dev.md)。
-
-**自定义记录表单最小示例**（自包含，需已安装 `antd`）：
-
-```tsx
-import React from 'react';
-import {Form, Input, Button} from 'antd';
-import type {FloorMapRecordFormRenderContext} from '@pisell/materials';
-
-export default function buildSalesRecordForm() {
-    return {
-        sales: (ctx: FloorMapRecordFormRenderContext) => (
-            <Form
-                layout="vertical"
-                size="small"
-                initialValues={ctx.record}
-                onFinish={(values) => ctx.onSaveRecord?.(values as Record<string, unknown>)}
-            >
-                <Form.Item name="name" label="名称">
-                    <Input/>
-                </Form.Item>
-                <Button type="primary" htmlType="submit" loading={ctx.savingRecord} block size="small">
-                    保存
-                </Button>
-            </Form>
-        ),
-    };
-}
-
-// 传入 PisellFloorMapLayout：dataSourceRecordForm={buildSalesRecordForm()}
-```
-
 ## API
 
-### PisellFloorMapLayout Props（基础）
-
-| 参数               | 说明                                           | 类型                                                     | 默认值                  | 版本 |
-|------------------|----------------------------------------------|--------------------------------------------------------|----------------------|----|
-| items            | 资源列表；**平面图模式下由内部合并结果覆盖，可传 `[]` 占位**          | `T[]`                                                  | 必填                   | -  |
-| renderItem       | 渲染每项内容；平面图下无 `renderItemByKind` 匹配时仍可能走到此项   | `(item, index, options?) => ReactNode`                 | 必填                   | -  |
-| rowKey           | 列表 key，用于 React key                          | `string \| (item, index) => string`                    | `item.id`            | -  |
-| renderItemByKind | **仅平面图**：按 `elementKind` 渲染，优先于 `renderItem` | `Record<string, (item, index, options?) => ReactNode>` | -                    | -  |
-| mapLayer         | 底图层：背景、网格、padding、gap                        | `FloorMapLayerConfig`                                  | -                    | -  |
-| cellSize         | 格子像素尺寸（cell 模式）；pixel 模式缺省宽高时用此值             | `number`                                               | `64`                 | -  |
-| itemUnit         | 坐标与尺寸单位                                      | `'cell' \| 'pixel'`                                    | `'cell'`             | -  |
-| zoom             | 缩放配置                                         | `FloorMapZoomConfig`                                   | -                    | -  |
-| pan              | 平移配置                                         | `FloorMapPanConfig`                                    | `{ enabled: false }` | -  |
-| controls         | 视图控制显隐                                       | `FloorMapControlsConfig`                               | 见下                   | -  |
-| enableHover      | 是否开启 hover 高亮与事件                             | `boolean`                                              | `true`               | -  |
-| onItemClick      | 项点击回调                                        | `(item, index, e) => void`                             | -                    | -  |
-| onItemHover      | 项 hover 进入                                   | `(item, index) => void`                                | -                    | -  |
-| onItemLeave      | 项 hover 离开                                   | `(item, index) => void`                                | -                    | -  |
-
-### PisellFloorMapLayout Props（平面图 / 编辑）
-
-以下在传入 **`floorMapConfig`** 时生效（具体类型见 `types.ts`）。
-
-| 参数                        | 说明                                                                       | 类型                                                | 默认值        |
-|---------------------------|--------------------------------------------------------------------------|---------------------------------------------------|------------|
-| floorMapConfig            | 画布列表、`canvasUi`、`sceneElements`、`elementKindCategories`、`elementKinds` 等 | `FloorMapViewConfig`                              | -          |
-| mode                      | `'read'` 只读；`'edit'` 可编辑（工具栏、侧栏、拖拽）                                      | `'read' \| 'edit'`                                | `'read'`   |
-| dataSources               | 多数据源：`Record<key, Array<{ id, ... }>>`，落位 `dataSourceKey` + `id` 对应其中一行  | `FloorMapDataSources`                             | -          |
-| onSave                    | 编辑态保存**布局草稿**                                                            | `(config: FloorMapViewConfig) => void`            | -          |
-| onDataSourceRecordSave    | 侧栏保存**单条业务记录**                                                           | `(dataSourceKey, id, newData) => void`            | -          |
-| dataSourceLabels          | 工具栏等处数据源展示名                                                              | `Record<string, string>`                          | -          |
-| dataSourceFormColumns     | 内置 `FloorMapDataForm` 的列配置                                               | `Record<string, DataSourceFormColumn[]>`          | -          |
-| dataSourceRecordForm      | **自定义**记录区：按 key 的 `ReactNode` 或 render prop，**优先生效**                    | `Record<string, ReactNode \| (ctx) => ReactNode>` | -          |
-| getMergedItemWrapperStyle | 合并图元**外层定位容器**额外样式（如列表/搜索未命中时 `opacity`）；不影响子项内部布局                       | `(item, index) => CSSProperties \| undefined`     | -          |
-| onElementRenderError      | `renderItemByKind` 抛错或绑定校验失败时回调（失败时画布上仍会显示错误占位）                          | `(element, error) => void`                        | -          |
-| floorMapFullscreenMode    | 编辑态全屏 UI：`toggle`（默认，可进/退全屏）、`locked`（始终全屏顶栏、组件内不可退出）、`disabled`（无全屏按钮）  | `FloorMapFullscreenMode`                          | `'toggle'` |
-| toolbarShowSave           | 是否在左侧工具栏显示保存（全屏或 `locked` 顶栏已含保存时侧栏保存会隐藏）                                | `boolean`                                         | `true`     |
-| loading                   | 编辑/加载态                                                                   | `boolean`                                         | -          |
-| saveError                 | 保存错误提示                                                                   | `Error \| string`                                 | -          |
-
-上述字段也可通过 **`FloorMapLayoutContextValue`**（**`FloorMapLayoutProvider`** 或 RecordBoard **`floorMapLayoutContext`
-**）注入，与 props 按 **`??`** 合并，**props 优先**。
-
-### FloorMapLayoutProvider / Context（导出）
-
-| 名称                                                    | 说明                                                                                                    |
-|-------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
-| **`FloorMapLayoutProvider`**                          | 接收 **`value: FloorMapLayoutContextValue`** 与 **`children`**，注入 Context；**`value` 建议 `useMemo` 稳定引用**。 |
-| **`FloorMapLayoutProviderProps`**                     | Provider 的 props 类型。                                                                                  |
-| **`useFloorMapLayoutContext()`**                      | 返回当前 Context 或 **`undefined`**（无 Provider）。                                                           |
-| **`EMPTY_FLOOR_MAP_LAYOUT_CONTEXT`**                  | 模块级稳定空对象；RecordBoard Shell 在未传 **`floorMapLayoutContext`** 时用作 Provider **`value`**。                  |
-| **`mergeFloorMapLayoutPropsFromContext(props, ctx)`** | 将 Layout props 与 Context 按字段合并（与组件内部逻辑一致），供测试或二次封装。                                                   |
-| **`FloorMapLayoutContextValue`**                      | Context 值类型，为 **`PisellFloorMapLayoutProps`** 中平面图相关字段的 **`Partial<Pick<...>>`**。                     |
-
-#### `floorMapConfig.canvasUi`（画布编辑能力）
-
-| 字段          | 说明                                             |
-|-------------|------------------------------------------------|
-| `canCreate` | 是否展示左侧调色板并允许「新建图元」落点模式。                        |
-| `canEdit`   | 是否允许画布 Tab 增删改名、选中图元侧栏、`onSave` 保存布局、侧栏绑定与删除等。 |
-
-从侧栏注入的 **`floorMapConfig`** 在运行时应包含 **`canvasUi`**。若仅兼容历史根级 `canCreate` / `canEdit`（无 `canvasUi`），
-`useFloorMapEditState` 会在同步草稿时自动归并为 `canvasUi`。
+### PisellFloorMapLayout Props
+
+| 参数          | 说明                                                  | 类型                                  | 默认值                  | 版本 |
+|-------------|-----------------------------------------------------|-------------------------------------|----------------------|----|
+| items       | 资源列表，每项至少含 `id`、`x`、`y`；可含 `width`、`height`、`shape` | `T[]`                               | 必填                   | -  |
+| renderItem  | 渲染每项内容                                              | `(item, index) => ReactNode`        | 必填                   | -  |
+| rowKey      | 列表 key，用于 React key                                 | `string \| (item, index) => string` | `item.id`            | -  |
+| mapLayer    | 底图层：背景、网格、padding、gap                               | `FloorMapLayerConfig`               | -                    | -  |
+| cellSize    | 格子像素尺寸（cell 模式）；pixel 模式缺省宽高时用此值                    | `number`                            | `64`                 | -  |
+| itemUnit    | 坐标与尺寸单位                                             | `'cell' \| 'pixel'`                 | `'cell'`             | -  |
+| zoom        | 缩放配置                                                | `FloorMapZoomConfig`                | -                    | -  |
+| pan         | 平移配置                                                | `FloorMapPanConfig`                 | `{ enabled: false }` | -  |
+| controls    | 视图控制显隐                                              | `FloorMapControlsConfig`            | 见下                   | -  |
+| enableHover | 是否开启 hover 高亮与事件                                    | `boolean`                           | `true`               | -  |
+| onItemClick | 项点击回调                                               | `(item, index, e) => void`          | -                    | -  |
+| onItemHover | 项 hover 进入                                          | `(item, index) => void`             | -                    | -  |
+| onItemLeave | 项 hover 离开                                          | `(item, index) => void`             | -                    | -  |
 
 ### controls（视图控制）
 
@@ -676,14 +326,9 @@ export default function buildSalesRecordForm() {
 
 ### 类型导出
 
-可从 `@pisell/materials`（或包内 `pisellFloorMapLayout` 路径）获取：`PisellFloorMapLayoutProps`、`PisellFloorMapLayoutRef`、
-`FloorMapItemBase`、`FloorMapMergedItem`、`FloorMapSceneElement`、`FloorMapViewConfig`、`FloorMapDataSources`、
-`FloorMapElementKindConfig`、`FloorMapRecordFormRenderContext`、`FloorMapDataSourceRecordFormContent`、
-`FloorMapFullscreenMode`、**`FloorMapLayoutContextValue`**、**`FloorMapLayoutProviderProps`**、
-`FLOOR_MAP_STAGE_ELEMENT_KIND`，以及各类 Layer/Zoom/Pan/Controls/Shape 等配置类型（见 `types.ts` 与 `index.tsx` 导出列表）。
-
-命名空间 **`PisellLayouts`** 下亦 re-export **`FloorMapLayoutProvider`**、**`useFloorMapLayoutContext`**、*
-*`mergeFloorMapLayoutPropsFromContext`**、**`EMPTY_FLOOR_MAP_LAYOUT_CONTEXT`** 及上述类型（见 `PisellLayouts/index.tsx`）。
+可从 `@pisell/materials` 获取：`PisellFloorMapLayoutProps`、`PisellFloorMapLayoutRef`、`FloorMapItemBase`、
+`FloorMapItemUnit`、`FloorMapLayerConfig`、`FloorMapZoomConfig`、`FloorMapPanConfig`、`FloorMapControlsConfig`、
+`FloorMapItemShape`、`FloorMapBackgroundType`、`FloorMapPanBoundary`、`FloorMapLayoutMode`、`FloorMapGridLayoutConfig` 等。
 
 ---
 
@@ -705,22 +350,18 @@ npm run storybook
 
 ### Story 列表与说明
 
-| Story 名称                             | 说明                                                                                   |
-|--------------------------------------|--------------------------------------------------------------------------------------|
-| **Default**                          | 基础渲染：5×4 格子布局、默认 controls（仅缩放）、简单格子样式。                                               |
-| **WithGrid**                         | 开启底图网格线（`mapLayer.showGrid: true`）、平移。                                               |
-| **WithPan**                          | 平移与视图控制条。                                                                            |
-| **WithShapes**                       | 多种形状（矩形、圆、三角）与不同 width/height。                                                       |
-| **WithVariableSizes**                | cell 模式下不同格子宽高（跨格）。                                                                  |
-| **PixelUnits**                       | pixel 模式：自由像素位置与尺寸。                                                                  |
-| **WithEvents**                       | 点击、hover、leave 事件与回调示例。                                                              |
-| **WithRefControls**                  | 通过 ref 调用 zoomIn/zoomOut/reset/fitBounds，配合外部按钮。                                     |
-| **ControlsHidden**                   | 隐藏视图控制（`controls.showZoom: false` 等）。                                                |
-| **FloorMapWithLayoutProvider**       | **`FloorMapLayoutProvider`** 注入 `floorMapConfig` / `dataSources`，Layout 仅传展示向 props。 |
-| **FloorMapViewEdit**                 | 平面图 **编辑态**：Tab、工具栏、侧栏、`mergeCanvasItems` + Figma 桌卡片。                               |
-| **FloorMapViewRead**                 | 平面图 **只读**：无工具栏/侧栏。                                                                  |
-| **FloorMapViewEditCustomRecordForm** | 编辑态 + **`dataSourceRecordForm.sales`** 自定义侧栏表单示例。                                    |
-| **FigmaDesign**                      | **Figma 设计稿还原**：顶部 Tab + 图例 + 像素布局桌台图（见下）。                                           |
+| Story 名称              | 说明                                               |
+|-----------------------|--------------------------------------------------|
+| **Default**           | 基础渲染：5×4 格子布局、默认 controls（仅缩放）、简单格子样式。           |
+| **WithGrid**          | 开启底图网格线（`mapLayer.showGrid: true`）、平移。           |
+| **WithPan**           | 平移与视图控制条。                                        |
+| **WithShapes**        | 多种形状（矩形、圆、三角）与不同 width/height。                   |
+| **WithVariableSizes** | cell 模式下不同格子宽高（跨格）。                              |
+| **PixelUnits**        | pixel 模式：自由像素位置与尺寸。                              |
+| **WithEvents**        | 点击、hover、leave 事件与回调示例。                          |
+| **WithRefControls**   | 通过 ref 调用 zoomIn/zoomOut/reset/fitBounds，配合外部按钮。 |
+| **ControlsHidden**    | 隐藏视图控制（`controls.showZoom: false` 等）。            |
+| **FigmaDesign**       | **Figma 设计稿还原**：顶部 Tab + 图例 + 像素布局桌台图（见下）。       |
 
 ### Figma 完整示例代码（与 Storybook FigmaDesign 一致）
 
@@ -1116,71 +757,70 @@ function LegendItem14131({color, label, fill = false}: { color: string; label: s
     );
 }
 
-export default function FigmaDesignDemo() {
-    return (
-        <div style={{
+export default () => (
+    <div style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 20,
+        background: FIGMA.gray50,
+        padding: 24,
+        borderRadius: 12,
+        fontFamily: FIGMA.fontFamily
+    }}>
+        <div className="figma-story-header-14131" style={{
             display: 'flex',
-            flexDirection: 'column',
-            gap: 20,
-            background: FIGMA.gray50,
-            padding: 24,
-            borderRadius: 12,
-            fontFamily: FIGMA.fontFamily
+            flexDirection: 'row',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            flexWrap: 'nowrap',
+            gap: 24
         }}>
-            <div className="figma-story-header-14131" style={{
-                display: 'flex',
-                flexDirection: 'row',
-                alignItems: 'center',
-                justifyContent: 'space-between',
-                flexWrap: 'nowrap',
-                gap: 24
+            <div className="figma-story-tabs-wrap-14131" style={{
+                flexShrink: 0,
+                background: FIGMA.gray50,
+                border: `1px solid ${FIGMA.gray200}`,
+                padding: 6,
+                borderRadius: 8,
+                display: 'inline-flex',
+                gap: 8
             }}>
-                <div className="figma-story-tabs-wrap-14131" style={{
-                    flexShrink: 0,
-                    background: FIGMA.gray50,
-                    border: `1px solid ${FIGMA.gray200}`,
-                    padding: 6,
-                    borderRadius: 8,
-                    display: 'inline-flex',
-                    gap: 8
-                }}>
-                    <Tabs defaultActiveKey="main" size="middle" style={{marginBottom: 0}}
-                          items={[{key: 'main', label: 'Main Area'}, {
-                              key: 'secondary',
-                              label: 'Secondary Area'
-                          }, {key: 'vip', label: 'VIP Area'}]} className="figma-story-tabs figma-story-tabs-14131"/>
-                </div>
-                <div className="figma-story-legend-14131" style={{
-                    display: 'flex',
-                    flexWrap: 'wrap',
-                    gap: '12px 40px',
-                    alignItems: 'center',
-                    justifyContent: 'flex-end',
-                    minWidth: 0
-                }}>
-                    <LegendItem14131 color={FIGMA.gray200} label="Available (4)" fill={false}/>
-                    <LegendItem14131 color={FIGMA.legendReserved} label="Reserved (2)" fill/>
-                    <LegendItem14131 color={FIGMA.legendWaiting} label="Waiting (3)" fill/>
-                    <LegendItem14131 color={FIGMA.legendDining} label="Dining (1)" fill/>
-                    <LegendItem14131 color={FIGMA.legendBilled} label="Billed (2)" fill/>
-                    <LegendItem14131 color={FIGMA.legendAvailableSoon} label="Available Soon (1)" fill/>
-                </div>
+                <Tabs defaultActiveKey="main" size="middle" style={{marginBottom: 0}}
+                      items={[{key: 'main', label: 'Main Area'}, {
+                          key: 'secondary',
+                          label: 'Secondary Area'
+                      }, {key: 'vip', label: 'VIP Area'}]} className="figma-story-tabs figma-story-tabs-14131"/>
             </div>
-            <div className="figma-story-map-wrap" style={{
-                height: 520,
-                background: FIGMA.white,
-                border: `4px solid ${FIGMA.gray200}`,
-                borderRadius: 8,
-                overflow: 'hidden',
-                boxShadow: FIGMA.shadowSm
+            <div className="figma-story-legend-14131" style={{
+                display: 'flex',
+                flexWrap: 'wrap',
+                gap: '12px 40px',
+                alignItems: 'center',
+                justifyContent: 'flex-end',
+                minWidth: 0
             }}>
-                <PisellFloorMapLayout className="figma-story-map" items={figma13998PixelItems}
-                                      renderItem={(item) => renderFigmaTableCard(item as FigmaTableItem)}
-                                      itemUnit="pixel" cellSize={64} mapLayer={{showGrid: false, padding: 20}}
-                                      zoom={{defaultScale: 0.8, min: 0.5, max: 2}} pan={{enabled: true}}
-                                      controls={{showZoom: true}} style={{height: '100%'}}/>
+                <LegendItem14131 color={FIGMA.gray200} label="Available (4)" fill={false}/>
+                <LegendItem14131 color={FIGMA.legendReserved} label="Reserved (2)" fill/>
+                <LegendItem14131 color={FIGMA.legendWaiting} label="Waiting (3)" fill/>
+                <LegendItem14131 color={FIGMA.legendDining} label="Dining (1)" fill/>
+                <LegendItem14131 color={FIGMA.legendBilled} label="Billed (2)" fill/>
+                <LegendItem14131 color={FIGMA.legendAvailableSoon} label="Available Soon (1)" fill/>
             </div>
-            <style>{`
+        </div>
+        <div className="figma-story-map-wrap" style={{
+            height: 520,
+            background: FIGMA.white,
+            border: `4px solid ${FIGMA.gray200}`,
+            borderRadius: 8,
+            overflow: 'hidden',
+            boxShadow: FIGMA.shadowSm
+        }}>
+            <PisellFloorMapLayout className="figma-story-map" items={figma13998PixelItems}
+                                  renderItem={(item) => renderFigmaTableCard(item as FigmaTableItem)} itemUnit="pixel"
+                                  cellSize={64} mapLayer={{showGrid: false, padding: 20}}
+                                  zoom={{defaultScale: 0.8, min: 0.5, max: 2}} pan={{enabled: true}}
+                                  controls={{showZoom: true}} style={{height: '100%'}}/>
+        </div>
+        <style>{`
 .figma-story-tabs-wrap-14131 .ant-tabs-nav { margin: 0; }
 .figma-story-tabs-wrap-14131 .ant-tabs-nav-list { gap: 8px; }
 .figma-story-tabs.figma-story-tabs-14131 .ant-tabs-tab { font-family: ${FIGMA.fontFamily}; padding: 10px 14px; margin: 0; font-size: 16px; font-weight: 600; line-height: 24px; color: ${FIGMA.gray500}; border-radius: 6px; }
@@ -1194,9 +834,8 @@ export default function FigmaDesignDemo() {
 .figma-table-card { color: ${FIGMA.gray900}; }
 .figma-table-card .ant-avatar { flex-shrink: 0; }
       `}</style>
-        </div>
-    );
-}
+    </div>
+);
 ```
 
 ### Figma 示例（FigmaDesign）说明
@@ -1243,7 +882,3 @@ export default function FigmaDesignDemo() {
 ## 测试指南
 
 详见 [测试文档](./pisellFloorMapLayout.$tab-test.md)
-
-## 后端接口
-
-店铺端平面图 CRUD 与 `layout` 载荷说明见 [平面图编辑器 API](pisellFloorMapLayout.$tab-api.md)。