@pisell/materials 6.11.223 → 6.11.225

package/lib/components/pisellFloorMapLayout/types.d.ts

@@ -0,0 +1,769 @@
+import type { CSSProperties, MouseEvent as ReactMouseEvent, ReactNode } from 'react';
+import type { FloorMapAppearanceMode } from './appearance/floorMapAppearance';
+export type { FloorMapAppearanceMode } from './appearance/floorMapAppearance';
+/**
+ * 资源项形状
+ * @description 展示层支持的基础形状
+ */
+export declare type FloorMapItemShape = 'rect' | 'circle' | 'triangle' | 'polygon' | 'custom';
+/**
+ * 底层背景类型
+ * @description 地图底层的展示方式
+ */
+export declare type FloorMapBackgroundType = 'none' | 'color' | 'image' | 'svg';
+/**
+ * 平移边界策略
+ * @description 拖拽/手势平移时的边界行为
+ */
+export declare type FloorMapPanBoundary = 'none' | 'clamp' | 'bounce';
+/**
+ * 资源项坐标/尺寸单位
+ * - cell：x/y/width/height 为格子数，由 cellSize 转为像素
+ * - pixel：x/y/width/height 为像素
+ */
+export declare type FloorMapItemUnit = 'cell' | 'pixel';
+/**
+ * 资源项基础类型
+ * @description 每个资源至少包含 id 与坐标 (x, y)，其余由外部扩展。
+ * 单位由布局的 itemUnit 决定：cell 时为格子数，pixel 时为像素。
+ */
+export interface FloorMapItemBase {
+    /** 唯一标识 */
+    id: string;
+    /** 坐标 x（cell 时为格子索引，pixel 时为像素） */
+    x: number;
+    /** 坐标 y */
+    y: number;
+    /** 显示名称，与 x/y 同级，所有图元可编辑 */
+    name?: string;
+    /** 层级，与 x/y 同级，所有图元可编辑；数值越大越靠前 */
+    zIndex?: number;
+    /** 宽度（可选；cell 时为格子数，pixel 时为像素，缺省时 cell 为 1，pixel 为 cellSize） */
+    width?: number;
+    /** 高度（可选） */
+    height?: number;
+    /** 形状，默认 rect */
+    shape?: FloorMapItemShape;
+}
+/**
+ * 底层（MapLayer）配置
+ */
+export interface FloorMapLayerConfig {
+    /** 背景类型 */
+    backgroundType?: FloorMapBackgroundType;
+    /**
+     * 纯色背景时的显式颜色（backgroundType 为 color 时有效）。
+     * 一旦配置，应优先于 `appearanceMode` 提供的画布背景兜底色。
+     */
+    backgroundColor?: string;
+    /** 图片背景 URL（backgroundType 为 image 时有效） */
+    backgroundImage?: string;
+    /** SVG 背景内容或 URL（backgroundType 为 svg 时有效） */
+    backgroundSvg?: string;
+    /** 是否显示网格线，默认 false */
+    showGrid?: boolean;
+    /** 底层内边距（如 16 或 "16px"） */
+    padding?: number | string;
+    /** 格子/元素间距 */
+    gap?: number | string;
+    /** 坐标吸附间隔（逻辑单位），0 表示不吸附 */
+    snapStep?: number;
+    /**
+     * 平面图像素模式：按图元包围盒外扩的单侧留白（像素），影响画布尺寸与初始对齐。
+     * 不传时默认约 56；若需更大拖拽边距可设大值（如 200）。
+     */
+    boundingPadding?: number;
+}
+/**
+ * 缩放配置
+ */
+export interface FloorMapZoomConfig {
+    /** 默认缩放比例，如 1 表示 100% */
+    defaultScale?: number;
+    /** 最小缩放，默认 0.5 (50%) */
+    min?: number;
+    /** 最大缩放，默认 2 (200%) */
+    max?: number;
+    /** 缩放步进，默认 0.1 (10%) */
+    step?: number;
+    /**
+     * 为 false 时关闭；未传或其它值时默认开启（平面图像素模式且当前画布有图元时，每画布自动 fitBounds 一次，可视区域刚好容纳全部图元）。
+     * 开启时跳过「首帧 defaultScale 左上对齐」，避免与 fit 闪动叠加。
+     */
+    autoFitOnMount?: boolean;
+}
+/**
+ * 平移配置
+ */
+export interface FloorMapPanConfig {
+    /** 是否允许平移，默认 false */
+    enabled?: boolean;
+    /**
+     * 平移边界：`none` 时不限制（无限拖动画布）；`clamp` / `bounce` / 未传时限制在内容区内（对齐 react-zoom-pan-pinch `limitToBounds`）。
+     */
+    boundary?: FloorMapPanBoundary;
+}
+/**
+ * 视图控制显隐（默认仅显示放大/缩小，复位与区域定位需配置开启）
+ */
+export interface FloorMapControlsConfig {
+    /** 是否显示缩放按钮（+ / −），默认 true */
+    showZoom?: boolean;
+    /** 是否显示复位按钮，默认 false */
+    showReset?: boolean;
+    /** 是否显示区域定位（fitBounds）按钮，默认 false */
+    showFitBounds?: boolean;
+    /** 是否显示全屏按钮，默认 false */
+    showFullscreen?: boolean;
+    /**
+     * 是否显示网格开关（写入当前画布 draft 的 mapLayer.showGrid），默认 false
+     */
+    showGridToggle?: boolean;
+    /**
+     * 是否显示连线显隐开关（需 `enableEdges` 且主组件传入 `onToggleEdgesLayer`），默认 false
+     */
+    showEdgesToggle?: boolean;
+    /**
+     * 是否显示「视口锁定」按钮：锁定后画布的位置 / 缩放不允许通过任何用户交互（拖拽、滚轮、触摸缩放、缩放按钮、适配视口）改变，
+     * 防止误触改变视图。默认 false；平面图模式下由 PisellFloorMapLayout 默认置 true（与是否持久化视口到本地无关）。显式传 false 可隐藏。
+     */
+    showViewportLock?: boolean;
+    /**
+     * 悬浮控件条水平位置：`start` 左下（默认），`end` 右下
+     */
+    horizontalAlign?: 'start' | 'end';
+}
+/**
+ * 布局模式（规则网格 vs 完全自由坐标）
+ */
+export declare type FloorMapLayoutMode = 'grid' | 'free';
+/**
+ * 规则网格布局配置（layoutMode 为 grid 时可用）
+ */
+export interface FloorMapGridLayoutConfig {
+    /** 每行列数 */
+    columns?: number;
+}
+/** 图元类型：是否绑定业务资源 */
+export declare type FloorMapElementType = 'resource' | 'decoration';
+/**
+ * 画布名称多语言结构（与低代码 Translation 字段一致）
+ */
+export declare type FloorMapCanvasNameI18n = {
+    en: string;
+    'zh-CN': string;
+    'zh-HK': string;
+    ja: string;
+    pt: string;
+};
+/** 画布（对应一个 Tab，如 1楼、2楼） */
+export interface FloorMapCanvas {
+    id: string;
+    /**
+     * 展示名：纯字符串或各语言对象；对象时按引擎 locale 取字段，缺省回退 `en` 等。
+     */
+    name: string | FloorMapCanvasNameI18n;
+    /**
+     * 多语言文案 key（`locales.getText`）；配置后 Tab / 侧栏「所属画布」优先显示当前语言译名。
+     * 用户重命名后会清除 `nameKey`，以 `name` 为准。
+     */
+    nameKey?: string;
+    /**
+     * Tab 标签旁 (n) 数量；未配置时 `mergeCanvasesForTabs` 可按 `sceneElements` 数量推断（>0 才显示）。
+     */
+    tabBadge?: number;
+    order: number;
+    enabled: boolean;
+    background?: string;
+    categoryIds?: string[];
+    mapLayer?: FloorMapLayerConfig;
+}
+/** 文字槽位（编辑时在 SVG 上添加，阅读态通过参数传文案） */
+export interface FloorMapTextSlot {
+    id: string;
+    x: number;
+    y: number;
+    align?: 'left' | 'center' | 'right';
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    defaultText?: string;
+}
+/** 地图图元：资源或装饰，编辑与阅读共用（name/zIndex 继承自 FloorMapItemBase） */
+export interface FloorMapElement extends FloorMapItemBase {
+    canvasId: string;
+    type: FloorMapElementType;
+    elementKind?: string;
+    fillColor?: string;
+    strokeColor?: string;
+    resourceId?: string;
+    capacity?: number;
+    textSlots?: FloorMapTextSlot[];
+    points?: [number, number][];
+    svgPath?: string;
+    svgUrl?: string;
+    imageUrl?: string;
+    /**
+     * 内置图形图元（`floorMapBuiltinShape`）的预设图形 key（如 `toilet`/`sofa` 等）。
+     * 非内置图形 kind 时不会被读取。
+     */
+    builtinShapeKey?: string;
+    extensions?: Record<string, unknown>;
+}
+/** 单门店 Floor Map 数据（编辑/阅读共用） */
+export interface FloorMapData {
+    canvases: FloorMapCanvas[];
+    elements: FloorMapElement[];
+}
+/** 多数据源：key 为数据源标识，value 为该数据源下的记录列表 */
+export declare type FloorMapDataSources = Record<string, Array<{
+    id: string;
+    [k: string]: unknown;
+}>>;
+/**
+ * 画布图元与可选数据源行的绑定（无绑定时仅展示图元种类默认态）
+ */
+export interface FloorMapSceneElementDataBinding {
+    dataSourceKey: string;
+    recordId: string;
+}
+/**
+ * 画布上的单一图元实例（原 dataSourcePlacements + decorations 合并为同一结构）
+ */
+export interface FloorMapSceneElement {
+    /** 实例唯一 id，持久化主键 */
+    instanceId: string;
+    /** 所属画布 id */
+    canvasId: string;
+    x: number;
+    y: number;
+    name?: string;
+    zIndex?: number;
+    width?: number;
+    height?: number;
+    elementKind?: string;
+    scale?: number;
+    shape?: FloorMapItemShape;
+    fillColor?: string;
+    strokeColor?: string;
+    textSlots?: FloorMapTextSlot[];
+    points?: [number, number][];
+    svgPath?: string;
+    svgUrl?: string;
+    imageUrl?: string;
+    /**
+     * 内置图形图元（`floorMapBuiltinShape`）的预设图形 key（如 `toilet`/`sofa` 等）。
+     * 非内置图形 kind 时不会被读取；由 {@link FLOOR_MAP_BUILTIN_SHAPES} 枚举驱动。
+     */
+    builtinShapeKey?: string;
+    extensions?: Record<string, unknown>;
+    dataBinding?: FloorMapSceneElementDataBinding;
+    /**
+     * 为 true 时：侧栏锁定 X/Y/层级/宽高的编辑，且画布上不可拖拽、不可缩放控制点。
+     * 仍可改名称、图片地址等其它字段（如适用）。
+     */
+    layoutTransformLocked?: boolean;
+}
+/**
+ * 矩形区域类装饰（无数据源绑定），如画布上的「舞台/舞池」等。
+ * 在 `elementKinds` 中配置 `{ value: 'stage', label: '…', showInPalette: true }`，名称在编辑面板「显示名称」中修改。
+ */
+export declare const FLOOR_MAP_STAGE_ELEMENT_KIND = "stage";
+/**
+ * 选区图元 kind：虚线框 + 名称。成员关系按**几何完全包含**实时计算（图元包围盒完全落在选区矩形内即为成员），不持久化成员列表。
+ * 编辑态拖动选区时，拖拽开始那一刻被完全框住的图元随选区一起平移。建议配合较低 `zIndex`（默认 -50），
+ * 保证框内图元仍可被单独点选/拖动。
+ */
+export declare const FLOOR_MAP_SELECTION_ZONE_ELEMENT_KIND = "floorMapSelectionZone";
+/**
+ * 图片图元：无数据源绑定，通过 `imageUrl` 展示位图；适合铺底图或与业务图元叠放（调 `zIndex`）。
+ */
+export declare const FLOOR_MAP_IMAGE_ELEMENT_KIND = "floorMapImage";
+/**
+ * 内置图形图元：无数据源绑定，通过 `builtinShapeKey` 在内置枚举（厕所 / 分隔 / 柱子 /
+ * 沙发 / 大门）中选择预设图形。形状由 {@link FLOOR_MAP_BUILTIN_SHAPES} 驱动，
+ * 与图片图元等同地铺底 / 标记场地结构。
+ */
+export declare const FLOOR_MAP_BUILTIN_SHAPE_ELEMENT_KIND = "floorMapBuiltinShape";
+/** 图元是否接受数据源及是否必填 */
+export declare type FloorMapElementDataBindingPolicy = 'none' | 'optional' | 'required';
+/** 图元种类所属分类（调色板分组） */
+export interface FloorMapElementKindCategory {
+    id: string;
+    label: string;
+    order?: number;
+}
+/** 无数据源行时的占位展示文案/扩展（与 defaultShape 等并列） */
+export interface FloorMapElementDefaultPresentation {
+    title?: string;
+    subtitle?: string;
+    extensions?: Record<string, unknown>;
+}
+/** 连线锚点（图元边框侧） */
+export declare type FloorMapEdgeAnchor = 'top' | 'right' | 'bottom' | 'left' | 'center';
+/** 连线状态（影响默认颜色与虚线） */
+export declare type FloorMapEdgeStatus = 'online' | 'offline' | 'warning' | 'unknown';
+/**
+ * 连线手动路由：用户拖动手柄后保存的「完整 path 快照」。
+ *
+ * `pathSnapshot` 是 final path 的全部点列（含两端锚点）。一旦设置：
+ * - `buildEdgeRoute` **不再调用自动路由**，仅把 snapshot 的两端对齐到当前图元
+ *   锚点位置（更新「最近的两个点」），中间路径完整保留，避免图元拖动时整条线
+ *   被重算。
+ * - 拖动连线手柄时（无论首段、末段、还是内部段）都直接对 snapshot 做形变，
+ *   首/末段拖动会在 snapshot 前/后追加一对 stub 转角，可以无限叠加。
+ */
+export interface FloorMapEdgeRouting {
+    pathSnapshot?: [number, number][];
+}
+/** 图元间连线（边） */
+export interface FloorMapEdge {
+    id: string;
+    /** 对应 {@link FloorMapSceneElement.instanceId} */
+    sourceId: string;
+    targetId: string;
+    sourceAnchor?: FloorMapEdgeAnchor;
+    targetAnchor?: FloorMapEdgeAnchor;
+    /** 在线/离线/告警；缺省为 unknown */
+    status?: FloorMapEdgeStatus;
+    /** 自定义描边色，优先于 status 色板 */
+    color?: string;
+    strokeWidth?: number;
+    /** 强制虚线（offline 等状态也会虚线） */
+    dashed?: boolean;
+    /** 起点端口标签，如 G3/WAN */
+    sourceLabel?: string;
+    /** 终点端口标签 */
+    targetLabel?: string;
+    /** 连线中段主标签 */
+    label?: string;
+    /** 手动路由覆盖（拖拽中段手柄后回写） */
+    routing?: FloorMapEdgeRouting;
+    extensions?: Record<string, unknown>;
+}
+/** 图元种类配置（由后端或上层注入） */
+export interface FloorMapElementKindConfig {
+    value: string;
+    label: string;
+    /** 调色板分组，对应 {@link FloorMapViewConfig.elementKindCategories} 的 id */
+    categoryId?: string;
+    /**
+     * 是否接受数据源绑定：none 纯图元；optional 可先占位后绑定；required 在存在可选行时须先选行再落点（数据源为空时仍允许占位 recordId）
+     */
+    dataBindingPolicy?: FloorMapElementDataBindingPolicy;
+    /** 允许绑定的数据源 key，缺省表示不限制（在 policy 非 none 时生效） */
+    allowedDataSourceKeys?: string[];
+    /** 校验绑定行是否包含这些字段（有绑定且行存在时检查） */
+    expectedRecordFields?: string[];
+    defaultShape?: FloorMapItemShape;
+    defaultFillColor?: string;
+    defaultStrokeColor?: string;
+    showInPalette?: boolean;
+    defaultPoints?: [number, number][];
+    defaultSvgUrl?: string;
+    defaultSvgPath?: string;
+    defaultImageUrl?: string;
+    /** 无绑定或行缺失时的说明向展示 */
+    defaultPresentation?: FloorMapElementDefaultPresentation;
+    /**
+     * 是否允许该 kind 的图元在编辑面板里勾选「将图元名作为资源标题」。
+     * 缺省 false：新增 kind 默认不显示该选项，需业务显式开启，向前兼容。
+     *
+     * 勾选效果（业务展示侧统一通过 {@link resolveSceneElementDisplayTitle} 接入）：
+     *   `el.name` 非空时优先于业务字段（如预约页的 `row.main_field`/`row.code`）作为标题；
+     *   未勾选保持现状（业务字段为主，`el.name` 仅作兜底）。
+     */
+    nameAsTitleConfigurable?: boolean;
+}
+/**
+ * 画布/编辑器层能力：新建图元、布局与画布 Tab 的编辑权限
+ * @description 与 `canvases` 列表配合使用，统一挂在平面图配置的「画布 UI」下
+ */
+export interface FloorMapCanvasUiConfig {
+    /** 是否展示左侧调色板并从新建模式落点图元 */
+    canCreate: boolean;
+    /**
+     * 是否允许：画布 Tab 增删改名、选中图元侧栏、保存布局与数据源记录、画布内拖拽等
+     */
+    canEdit: boolean;
+}
+/** Floor Map 视图配置（仅平面图视图需要持久化） */
+export interface FloorMapViewConfig {
+    canvases: FloorMapCanvas[];
+    /** 画布编辑能力（原根级 canCreate / canEdit，现归并于此） */
+    canvasUi: FloorMapCanvasUiConfig;
+    /** 图元分类，供调色板分组 */
+    elementKindCategories?: FloorMapElementKindCategory[];
+    elementKinds: FloorMapElementKindConfig[];
+    /** 画布上的全部图元实例（合并原落位与装饰） */
+    sceneElements: FloorMapSceneElement[];
+    datasourceComponents?: Record<string, {
+        componentId?: string;
+        [k: string]: unknown;
+    }>;
+    edges?: FloorMapEdge[];
+}
+/** 编辑态：选中图元种类后的放置模式（点击画布落点） */
+export declare type FloorMapPlaceMode = null | {
+    type: 'scene';
+    elementKind: string;
+    dataSourceKey?: string;
+    /** 单选落一条；与 {@link recordIds} 二选一，多选时优先 {@link recordIds} */
+    recordId?: string;
+    /** 多选后在画布一次落多条，按锚点阶梯偏移 */
+    recordIds?: string[];
+    /**
+     * 内置图形 kind（`floorMapBuiltinShape`）专用：用户在侧栏 Select 预选的图形 key
+     * （取自 {@link FLOOR_MAP_BUILTIN_SHAPES}）。落点 / 拖放时作为初始 `builtinShapeKey`
+     * 写入 sceneElement；未选时回退为枚举首项。其它 kind 不读取此字段。
+     */
+    builtinShapeKey?: string;
+};
+/** 阅读态 renderItem 可选第三参数 */
+export interface FloorMapRenderOptions {
+    textSlotValues?: Record<string, string>;
+    /**
+     * 平面图画布当前缩放（如 TransformWrapper 的 scale）。
+     * 用于房间内卡片等需按「视觉短边」降级密度时与布局像素相乘。
+     */
+    viewportScale?: number;
+}
+/** 数据源记录表单列配置（用于编辑面板中的「数据源记录」区块） */
+export interface DataSourceFormColumn {
+    key: string;
+    label: string;
+    type?: 'string' | 'number' | 'select';
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+/**
+ * 自定义「数据源记录」表单（ReactNode 或 render prop）可用的上下文
+ * @description 与内置 {@link FloorMapDataForm} 数据源一致，便于复杂表单、多步校验、联动等
+ */
+export interface FloorMapRecordFormRenderContext {
+    /** 当前数据源 key */
+    dataSourceKey: string;
+    /** 当前绑定的记录 id */
+    recordId: string;
+    /** 当前行数据（来自 dataSources） */
+    record: Record<string, unknown>;
+    /** 全量数据源，只读引用 */
+    dataSources: FloorMapDataSources;
+    /** 当前画布图元实例（含坐标、绑定等） */
+    sceneElement: FloorMapSceneElement;
+    /** 当前平面图草稿配置 */
+    config: FloorMapViewConfig;
+    /** 与侧栏「保存记录」一致：写入单条记录；未配置 {@link PisellFloorMapLayoutProps.onDataSourceRecordSave} 时为 undefined */
+    onSaveRecord?: (newData: Record<string, unknown>) => void;
+    /** 内置表单保存中的 loading 同步字段，自定义表单可自行维护 loading */
+    savingRecord: boolean;
+}
+/**
+ * 按 dataSourceKey 替换「数据源记录」区块的表单内容：静态节点或通过 context 渲染
+ */
+export declare type FloorMapDataSourceRecordFormContent = ReactNode | ((ctx: FloorMapRecordFormRenderContext) => ReactNode);
+/** 选中图元后编辑面板参数 */
+export interface FloorMapEditPanelParams {
+    itemId: string;
+    sceneElement: FloorMapSceneElement;
+    onUpdate: (patch: Partial<FloorMapSceneElement>) => void;
+    onSaveRecord?: (dataSourceKey: string, id: string, newData: Record<string, unknown>) => void;
+    onClose: () => void;
+    /** 从草稿中移除当前选中的图元，并关闭面板（需用户再点「保存」持久化布局） */
+    onDelete?: () => void;
+    /** 按 dataSourceKey 配置记录表单列（标签、类型、选项），不传则自动列举 record 除 id 外字段 */
+    recordFormColumns?: Record<string, DataSourceFormColumn[]>;
+    /**
+     * 按 dataSourceKey 完全替换「数据源记录」内的表单区域（仍保留上方「选择数据行」等）
+     * 若某 key 存在且非空，则不再渲染该 key 下的 {@link FloorMapDataForm}（列配置仅作未自定义时的后备）
+     */
+    dataSourceRecordForm?: Record<string, FloorMapDataSourceRecordFormContent>;
+    /** 数据源 key → 展示名（侧栏「数据源」下拉与工具栏一致） */
+    dataSourceLabels?: Record<string, string>;
+    /**
+     * 布局草稿相对上游持久化配置已变更（拖拽、绑定、侧栏应用等均会写入草稿）；
+     * 用于提示用户点击顶部「保存」持久化布局草稿。
+     */
+    layoutDraftDirty?: boolean;
+    /**
+     * 为 false 时不渲染「数据绑定」下方的数据源记录编辑表单（FloorMapDataForm / 自定义 record 表单）；
+     * 数据绑定选数据源与选行仍可展示。
+     */
+    showDataSourceRecordFormBlock?: boolean;
+}
+/**
+ * 合并当前画布的 sceneElements 为 items（用于 Layout 渲染）
+ */
+export declare type FloorMapMergedItem = FloorMapItemBase & {
+    /** 与 {@link FloorMapSceneElement.instanceId} 一致 */
+    id: string;
+    instanceId: string;
+    _sceneElement: FloorMapSceneElement;
+    elementKind?: string;
+};
+/**
+ * 平面图编辑态全屏 UI 策略（`floorMapFullscreenMode`）
+ *
+ * - **toggle**（默认）：顶栏提供进入/退出全屏，与浏览器 Fullscreen API 联动
+ * - **locked**：始终使用全屏顶栏（Tab + 保存等），**不提供退出全屏**；适合外层遮罩铺满
+ * - **disabled**：**不提供全屏按钮**，仅小屏顶栏 + 侧栏保存
+ */
+export declare type FloorMapFullscreenMode = 'toggle' | 'locked' | 'disabled';
+/**
+ * 平面图 Layout 注入上下文：数据、保存、侧栏表单与状态等（不包含 renderItem/mapLayer 等展示向 props）。
+ * 由 `FloorMapLayoutProvider` / RecordBoard `floorMapLayoutContext` 提供，与 `PisellFloorMapLayout` props 按 `??` 合并，props 优先。
+ */
+export declare type FloorMapLayoutContextValue = Partial<Pick<PisellFloorMapLayoutProps<FloorMapItemBase>, 'floorMapConfig' | 'dataSources' | 'onSave' | 'onDataSourceRecordSave' | 'dataSourceLabels' | 'dataSourceFormColumns' | 'dataSourceRecordForm' | 'loading' | 'saveError' | 'onElementRenderError' | 'toolbarShowSave' | 'paletteSidebarVisibleLimit' | 'floorMapFullscreenMode' | 'appearanceMode' | 'showDataSourceRecordFormBlock' | 'viewportDockToolButtons' | 'viewportDockTrailing'>>;
+/**
+ * PisellFloorMapLayout 组件 Props
+ * @template T - 资源项类型，需继承 FloorMapItemBase 或兼容 id/x/y
+ */
+export interface PisellFloorMapLayoutProps<T extends FloorMapItemBase = FloorMapItemBase> {
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式（作用于最外层容器）
+     */
+    style?: CSSProperties;
+    /**
+     * 资源列表；每项至少包含 id、x、y
+     */
+    items: T[];
+    /**
+     * 每个资源项的渲染函数；内容与样式由调用方完全控制
+     * 当使用 floorMapConfig 时可选传入第三参数 options（如 textSlotValues）
+     */
+    renderItem: (item: T, index: number, options?: FloorMapRenderOptions) => ReactNode;
+    /**
+     * 指定每项的唯一 key，默认使用 item.id
+     */
+    rowKey?: string | ((item: T, index: number) => string);
+    /**
+     * 按 elementKind 的渲染函数（key 为 kind value），优先于 renderItem
+     * 仅在使用 floorMapConfig 时生效
+     */
+    renderItemByKind?: Record<string, (item: T, index: number, options?: FloorMapRenderOptions) => ReactNode>;
+    /**
+     * 合并图元**外层定位容器**的额外样式（如列表/搜索筛选未命中时降低透明度）。
+     * 在宽高与定位样式之后展开合并，适合传 `opacity`；避免覆盖 `position/left/top/width/height` 除非有意为之。
+     */
+    getMergedItemWrapperStyle?: (item: T, index: number) => CSSProperties | undefined;
+    /**
+     * 是否启用连线（edge）相关的渲染与编辑能力：
+     * - 阅读态：渲染 EdgeLayer（连线路径与端口标签）
+     * - 编辑态：选中节点的 4 锚点圆点、连线手柄、拖动新建/编辑连线
+     *
+     * **默认 `false`**：仅在拓扑（PisellTopology）等明确需要连线能力的场景显式开启。
+     * pisell-reservation、record-board 等通用业务画布不应开启，避免选中图元时出现锚点
+     * 圆点或拖动产生连线。
+     */
+    enableEdges?: boolean;
+    /**
+     * 底层（地图层）配置：背景、网格、padding、gap、吸附
+     */
+    mapLayer?: FloorMapLayerConfig;
+    /**
+     * 每格像素尺寸（itemUnit 为 cell 时：逻辑 1 单位对应的像素；为 pixel 时：缺省宽高的默认像素）
+     * @default 64
+     */
+    cellSize?: number;
+    /**
+     * item 坐标与尺寸单位：cell 格子数，pixel 像素
+     * @default 'cell'
+     */
+    itemUnit?: FloorMapItemUnit;
+    /**
+     * 布局模式：grid 规则网格，free 完全按坐标
+     * @default 'free'
+     */
+    layoutMode?: FloorMapLayoutMode;
+    /**
+     * 规则网格时的配置（列数等）
+     */
+    gridLayout?: FloorMapGridLayoutConfig;
+    /**
+     * 缩放配置
+     */
+    zoom?: FloorMapZoomConfig;
+    /**
+     * 平移配置
+     */
+    pan?: FloorMapPanConfig;
+    /**
+     * 视图控制按钮显隐
+     */
+    controls?: FloorMapControlsConfig;
+    /**
+     * 视口（画布位置 + 缩放百分比）持久化开关，默认 `true`。
+     * 设为 `false` 时完全不读不写 localStorage，始终走 autoFit / 初始对齐行为。
+     *
+     * 仅在平面图模式（有 `floorMapConfig`）下生效；其它模式没有「画布」概念。
+     */
+    viewportPersist?: boolean;
+    /**
+     * 视口持久化的业务命名空间（建议传入店铺 / floor plan 维度的稳定标识，如 floor plan code）。
+     *
+     * 存储 key 形如 `pisell-floor-map-layout.viewport:<namespace>:<canvasId>`；
+     * 不传时 fallback 为仅用 `<canvasId>`，同一 `canvasId` 在跨业务场景（不同店铺 / 不同平面图）会共享视角，
+     * 若 `canvasId` 存在全局冲突（例如业务里使用固定常量作 canvasId），务必传入此字段做隔离。
+     */
+    viewportPersistNamespace?: string;
+    /**
+     * 是否开启 hover 高亮或 hover 事件，默认 true
+     */
+    enableHover?: boolean;
+    /**
+     * 阅读态（`mode === 'read'`）：与 {@link rowKey} 解析出的图元 id 相等时，外层容器加选中描边（如详情弹层打开时锚定画布上的桌位）。
+     * 传 `null` / `undefined` / 空字符串时不展示选中外圈。
+     */
+    readModeSelectedItemId?: string | null;
+    /**
+     * 资源项点击回调
+     */
+    onItemClick?: (item: T, index: number, event: ReactMouseEvent<HTMLElement>) => void;
+    /**
+     * 资源项鼠标进入
+     */
+    onItemHover?: (item: T, index: number, event: ReactMouseEvent<HTMLElement>) => void;
+    /**
+     * 资源项鼠标离开
+     */
+    onItemLeave?: (item: T, index: number, event: ReactMouseEvent<HTMLElement>) => void;
+    /** 编辑态全屏按钮与顶栏形态，见 {@link FloorMapFullscreenMode} */
+    floorMapFullscreenMode?: FloorMapFullscreenMode;
+    /**
+     * FloorMap 外观模式；当前仅提供画布背景兜底色。
+     * 若当前画布或根级 `mapLayer.backgroundColor` 显式传入颜色，应优先使用显式背景色。
+     * @default 'light'
+     */
+    appearanceMode?: FloorMapAppearanceMode;
+    /**
+     * 模式：read 仅展示，edit 可编辑；与 floorMapConfig 同时使用时生效
+     */
+    mode?: 'read' | 'edit';
+    /**
+     * 平面图视图配置；传入时由组件内部按当前画布合并 items，忽略外部传入的 items
+     */
+    floorMapConfig?: FloorMapViewConfig;
+    /**
+     * 多数据源；与 floorMapConfig 同时使用
+     */
+    dataSources?: FloorMapDataSources;
+    /** 保存平面图配置，由上层调接口持久化 */
+    onSave?: (config: FloorMapViewConfig) => void;
+    /**
+     * 退出编辑模式回调（不保存）。
+     * 传入后编辑态顶栏会展示「取消编辑」+「完成」两个按钮：
+     * - 取消编辑 → `onExitEdit()`（业务层负责把 `mode` 切回 `read`）
+     * - 完成 → 先 `onSave(config)` 再 `onExitEdit()`
+     * 不传则保持旧版「保存」按钮行为（仅保存，不退出）。
+     */
+    onExitEdit?: () => void;
+    /** 保存单条数据源记录 */
+    onDataSourceRecordSave?: (dataSourceKey: string, id: string, newData: Record<string, unknown>) => void;
+    /** 数据源展示名，key 为 dataSourceKey */
+    dataSourceLabels?: Record<string, string>;
+    /** 按 dataSourceKey 配置编辑面板「数据源记录」表单列（标签、类型、选项） */
+    dataSourceFormColumns?: Record<string, DataSourceFormColumn[]>;
+    /**
+     * 按 dataSourceKey 自定义侧栏「数据源记录」表单：传入 ReactNode 或 `(ctx) => ReactNode`；
+     * 指定 key 后优先于 dataSourceFormColumns + 内置 FloorMapDataForm，用于复杂业务表单
+     */
+    dataSourceRecordForm?: Record<string, FloorMapDataSourceRecordFormContent>;
+    /** 编辑态 loading */
+    loading?: boolean;
+    /** 保存失败时的错误信息 */
+    saveError?: Error | string;
+    /**
+     * 单图元渲染抛出异常或内部校验失败时回调（如 renderItemByKind 抛错、绑定数据不合法）
+     */
+    onElementRenderError?: (element: FloorMapSceneElement, error: unknown) => void;
+    /**
+     * 是否在左侧工具栏底部显示「保存」（默认 true；非全屏时顶栏为 Tab+全屏，保存多在侧栏；全屏时保存仅在顶栏）
+     */
+    toolbarShowSave?: boolean;
+    /**
+     * 资源选择 Modal 渲染槽位。
+     * 通用基础 modal 已下线，业务侧需注入实现（如 `PisellProResourcePickerModal`）。
+     * 未注入时不会渲染资源选择弹窗，资源类图元的「画布添加」入口将无可用 picker。
+     */
+    renderResourcePickerModal?: (props: import('./utils/floorMapResourcePickerTypes').FloorMapResourcePickerSlotProps) => ReactNode;
+    /**
+     * 侧栏 palette「查看全部」弹窗渲染槽位。
+     * 业务可在此复用统一选择弹窗（例如 private-materials 的 Selector + valueType="object"）。
+     */
+    renderPaletteViewAllModal?: import('./components/FloorMapToolbar').FloorMapToolbarProps['renderPaletteViewAllModal'];
+    /**
+     * 编辑态侧栏每个调色板分类直接展示的图元数量；超出则显示「查看全部」弹窗。
+     * 默认 5，见 `FLOOR_MAP_TOOLBAR_PALETTE_SIDEBAR_LIMIT`。
+     */
+    paletteSidebarVisibleLimit?: number;
+    /**
+     * 为 false 时隐藏侧栏「数据源记录」表单区（保留数据绑定选源/选行）。
+     */
+    showDataSourceRecordFormBlock?: boolean;
+    /**
+     * 手机布局：编辑态顶栏拆成两行（画布 Tab 一行 + 撤销/完成等一行），并收紧内边距。
+     */
+    editTopBarPhoneLayout?: boolean;
+    /**
+     * 画布 Tab 行右侧扩展（阅读态顶栏、编辑态 compact/full 顶栏）。
+     * 传入且阅读态仅单画布时仍会显示顶栏以便放置该插槽；全屏入口在左下 Dock（`viewportDockTrailing` 亦放 Dock，不占顶栏）。
+     */
+    canvasTabsBarTrailing?: ReactNode;
+    /**
+     * 视口左下角 Dock 展开区内、与缩放/网格等工具按钮平级的业务按钮插槽。
+     */
+    viewportDockToolButtons?: ReactNode;
+    /**
+     * 视口左下角 Dock 展开区业务插槽（与缩放/全屏同条），不占用顶栏 Tab 行；平面图模式推荐放「编辑画布」等。
+     */
+    viewportDockTrailing?: ReactNode;
+    /**
+     * 平面图模式：`floorMapViewportOverlay` 锚点；默认左上，预约 HUD 等可用左下。
+     */
+    viewportOverlayPlacement?: 'top-start' | 'bottom-start';
+    /**
+     * 视口悬浮层容器额外类名（如场控抽屉打开时需叠在固定层之上）。
+     */
+    viewportOverlayClassName?: string;
+    /**
+     * 平面图模式：在地图视口内悬浮层（不随画布缩放平移），如状态统计。
+     * 传入函数时可拿到当前画布合并后的 items 与数据源。
+     */
+    floorMapViewportOverlay?: ReactNode | ((args: FloorMapViewportOverlayRenderArgs<T>) => ReactNode);
+}
+/**
+ * {@link PisellFloorMapLayoutProps.floorMapViewportOverlay} 函数形态时的参数
+ */
+export declare type FloorMapViewportOverlayRenderArgs<T extends FloorMapItemBase = FloorMapItemBase> = {
+    items: T[];
+    dataSources: FloorMapDataSources | undefined;
+    currentCanvasId: string | null;
+    mode: 'read' | 'edit';
+};
+/**
+ * `PisellFloorMapLayout` 通过 ref 暴露的 imperative API。
+ * 缩放/复位委托内部 `react-zoom-pan-pinch`；`fitBounds` / `saveLayout` 依赖当前画布与编辑状态。
+ */
+export interface PisellFloorMapLayoutRef {
+    /** 在允许范围内放大一级（与右下角「+」一致） */
+    zoomIn: () => void;
+    /** 在允许范围内缩小一级（与右下角「−」一致） */
+    zoomOut: () => void;
+    /** 重置 transform 为初始 scale 与 initialPosition（与「复位」控件一致） */
+    reset: () => void;
+    /** 计算内容包盒并将视口平移/缩放至全部图元可见 */
+    fitBounds: () => void;
+    /** 触发与顶栏/侧栏相同的保存流程（无 `onSave` 时内部可能为 no-op，由 hook 决定） */
+    saveLayout: () => void;
+    /**
+     * 在编辑态把外部算好的整张 `FloorMapViewConfig` 灌入草稿（一次 `commitDraft`，
+     * 可被 undo/redo 撤销）。仅在 `mode='edit'` 时生效；非编辑态调用为 no-op。
+     * 典型用例：业务侧的「自动排列 / 一键重排」按钮算出新版 config 后注入草稿，
+     * 让用户点「完成编辑」时再走原有保存流程，而不是绕过 onSave 直接持久化。
+     */
+    applySceneSnapshot: (config: FloorMapViewConfig) => void;
+}