@pisell/materials 1.0.1086 → 1.0.1087

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

@@ -0,0 +1,46 @@
+/**
+ * EditableItemLayer - 编辑态图元层：拖拽、缩放、选中、吸附
+ */
+import React, { type CSSProperties } from 'react';
+import type { FloorMapItemBase, FloorMapMergedItem, FloorMapRenderOptions } from '../types';
+import { type FloorMapEditQuickActionLabels } from './FloorMapEditQuickActions';
+import './EditableItemLayer.less';
+export interface EditableItemLayerProps<T extends FloorMapItemBase = FloorMapMergedItem> {
+    items: T[];
+    renderItem: (item: T, index: number, options?: FloorMapRenderOptions) => React.ReactNode;
+    rowKey?: string | ((item: T, index: number) => string);
+    cellSize: number;
+    itemUnit?: 'cell' | 'pixel';
+    itemGap?: number;
+    contentWidth: number;
+    contentHeight: number;
+    /** 内容区 X/Y 偏移（画布包围盒向左/上扩展时，图元层整体平移） */
+    contentOffsetX?: number;
+    contentOffsetY?: number;
+    selectedId: string | null;
+    onSelect: (id: string | null) => void;
+    onUpdateItem: (itemId: string, patch: Partial<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>) => void;
+    snapStep?: number;
+    /** 画布当前缩放，用于将屏幕位移转为内容位移 */
+    scale?: number;
+    /** 拖拽/缩放图元时通知父组件，用于禁用画布平移，避免松手时画布跟着动 */
+    onInteractionChange?: (active: boolean) => void;
+    /** 每项外层容器额外样式（与定位样式合并） */
+    getMergedItemWrapperStyle?: (item: T, index: number) => CSSProperties | undefined;
+    className?: string;
+    /** 编辑态选中时图元旁快捷栏（上锁 / 复制 / 删除） */
+    editQuickBar?: {
+        labels: FloorMapEditQuickActionLabels;
+        isLocked: boolean;
+        onToggleLock: () => void;
+        onDuplicate: () => void;
+        onDelete: () => void;
+    } | null;
+}
+export declare function EditableItemLayer<T extends FloorMapItemBase>(props: EditableItemLayerProps<T>): JSX.Element;
+export default EditableItemLayer;

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

@@ -0,0 +1,39 @@
+/// <reference types="react" />
+import type { FloorMapMergedItem, FloorMapDataSources } from '../types';
+export declare type FigmaTableStatus = 'available' | 'reserved' | 'waiting' | 'dining' | 'billed' | 'availableSoon';
+/** 方桌/圆桌卡片展示用数据结构（与 Figma 设计一致，支持桌号/状态/人数/区域等） */
+export interface FigmaTableCardItem {
+    id: string;
+    /**
+     * 无绑定或无可展示数据行时与蘸料摆台占位一致：浅灰底 + 虚线框 + 提示文案
+     * @see getRenderItemByKindCondimentStation（RecordBoard Story）
+     */
+    isNoDataPlaceholder?: boolean;
+    placeholderBorderColor?: string;
+    placeholderHint?: string;
+    /** 占位主标题：优先图元名称，否则「餐桌」/「圆桌」 */
+    placeholderTitle?: string;
+    /** 桌号/名称，空闲态居中显示 */
+    displayName?: string;
+    status?: FigmaTableStatus;
+    customerName?: string;
+    reserveTime?: string;
+    /** 当前用餐人数（与 Figma 设计一致） */
+    guests?: number;
+    /** 可坐人数（与表格列「可坐人数」绑定） */
+    capacity?: number;
+    dishes?: string;
+    duration?: string;
+    /** 区域（与表格列「区域」绑定，如大厅/包厢A） */
+    area?: string;
+}
+/** 从 merged item + dataSources 得到卡片数据 */
+export declare function getFigmaTableCardFromMerged(item: FloorMapMergedItem, dataSources: FloorMapDataSources): FigmaTableCardItem;
+/** 渲染 Figma 样式的方桌卡片（上下小条 + 白底卡片 + 状态边框） */
+export declare function renderFigmaStyleTableCard(cardItem: FigmaTableCardItem): JSX.Element;
+/** 渲染 Figma 样式的圆桌卡片（圆形轮廓，展示桌号/状态/人数/区域） */
+export declare function renderFigmaStyleRoundTableCard(cardItem: FigmaTableCardItem): JSX.Element;
+/** 返回用于 renderItemByKind.table 的渲染函数（方桌） */
+export declare function getRenderItemByKindTable(dataSources: FloorMapDataSources): (item: unknown) => JSX.Element;
+/** 返回用于 renderItemByKind.roundTable 的渲染函数（圆桌） */
+export declare function getRenderItemByKindRoundTable(dataSources: FloorMapDataSources): (item: unknown) => JSX.Element;

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

@@ -0,0 +1,17 @@
+/// <reference types="react" />
+import type { FloorMapDataSources, DataSourceFormColumn } from '../types';
+import './FloorMapDataForm.less';
+export interface FloorMapDataFormProps {
+    dataSourceKey: string;
+    recordId: string;
+    record: Record<string, unknown>;
+    dataSources: FloorMapDataSources;
+    onSave: (dataSourceKey: string, id: string, newData: Record<string, unknown>) => void;
+    saving?: boolean;
+    /** 列配置：标签、类型（string/number/select）、选项（select 时）；不传则自动列举 record 除 id 外字段 */
+    columns?: DataSourceFormColumn[];
+    className?: string;
+}
+/** 简单通用表单：可编辑记录中的字段；支持 columns 配置标签与控件类型 */
+export declare function FloorMapDataForm(props: FloorMapDataFormProps): JSX.Element;
+export default FloorMapDataForm;

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

@@ -0,0 +1,11 @@
+/// <reference types="react" />
+import type { FloorMapEditPanelParams, FloorMapViewConfig, FloorMapDataSources } from '../types';
+import './FloorMapEditPanel.less';
+export interface FloorMapEditPanelProps extends FloorMapEditPanelParams {
+    config: FloorMapViewConfig;
+    dataSources: FloorMapDataSources;
+    savingRecord?: boolean;
+    className?: string;
+}
+export declare function FloorMapEditPanel(props: FloorMapEditPanelProps): JSX.Element;
+export default FloorMapEditPanel;

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

@@ -0,0 +1,21 @@
+/// <reference types="react" />
+export interface FloorMapEditQuickActionLabels {
+    lock: string;
+    unlock: string;
+    duplicate: string;
+    delete: string;
+    popTitle: string;
+    popDesc: string;
+    cancel: string;
+    okDelete: string;
+    ariaToolbar: string;
+}
+export interface FloorMapEditQuickActionsProps {
+    className?: string;
+    labels: FloorMapEditQuickActionLabels;
+    isLocked: boolean;
+    onToggleLock: () => void;
+    onDuplicate: () => void;
+    onDelete: () => void;
+}
+export declare function FloorMapEditQuickActions(props: FloorMapEditQuickActionsProps): JSX.Element;

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

@@ -0,0 +1,38 @@
+/**
+ * FloorMapEditTopBar - 编辑态顶栏
+ * - `mode="compact"`：画布 Tab + 可选 `canvasTabsBarTrailing`（全屏入口在左下 Dock）
+ * - `mode="full"`：画布 Tab + `canvasTabsBarTrailing` + 保存（仅非浏览器全屏时）+ 扩展操作
+ */
+import React from 'react';
+import type { CanvasTabsProps } from './CanvasTabs';
+import type { FloorMapControlsConfig, FloorMapViewConfig } from '../types';
+import './FloorMapEditTopBar.less';
+export declare type FloorMapEditTopBarMode = 'full' | 'compact';
+export interface FloorMapEditTopBarProps {
+    /** full：全屏时的完整顶栏；compact：非全屏时 Tab + 扩展区 */
+    mode?: FloorMapEditTopBarMode;
+    config: FloorMapViewConfig;
+    canvases: CanvasTabsProps['canvases'];
+    currentCanvasId: CanvasTabsProps['currentCanvasId'];
+    onTabChange: CanvasTabsProps['onTabChange'];
+    canEditTabs?: CanvasTabsProps['canEdit'];
+    onAddCanvas?: CanvasTabsProps['onAddCanvas'];
+    onRemoveCanvas?: CanvasTabsProps['onRemoveCanvas'];
+    onRenameCanvas?: CanvasTabsProps['onRenameCanvas'];
+    onSave?: () => void;
+    saving?: boolean;
+    saveError?: Error | string;
+    layoutDirty?: boolean;
+    /** full 模式：浏览器全屏时为 true，顶栏不展示保存（改由侧栏） */
+    isFullscreen?: boolean;
+    controls?: FloorMapControlsConfig;
+    /** 顶栏右侧扩展（如「区域定位」等），仅 full 模式 */
+    extraActions?: React.ReactNode;
+    /** 画布 Tab 同排最右侧业务区 */
+    canvasTabsBarTrailing?: React.ReactNode;
+    /** 启用画布仅 1 个时隐藏 Tab 行，仅保留右侧操作区（全屏顶栏保存等） */
+    hideCanvasTabs?: boolean;
+    className?: string;
+}
+export declare function FloorMapEditTopBar(props: FloorMapEditTopBarProps): JSX.Element | null;
+export default FloorMapEditTopBar;

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

@@ -0,0 +1,6 @@
+/// <reference types="react" />
+export interface FloorMapImageElementProps {
+    imageUrl?: string;
+    name?: string;
+}
+export declare function FloorMapImageElement(props: FloorMapImageElementProps): JSX.Element;

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

@@ -0,0 +1,35 @@
+/**
+ * FloorMapToolbar - 编辑态左侧侧边栏：按分类添加图元、绑定数据源与行；保存可选（默认用顶栏）
+ */
+import React from 'react';
+import type { FloorMapViewConfig, FloorMapDataSources, FloorMapMergedItem, FloorMapSceneElement, FloorMapPlaceMode } from '../types';
+import { type FloorMapPaletteDragPayload } from '../utils/floorMapDropUtils';
+import './FloorMapToolbar.less';
+export type { FloorMapPlaceMode as PlaceMode };
+export interface FloorMapToolbarProps {
+    config: FloorMapViewConfig;
+    dataSources: FloorMapDataSources;
+    dataSourceLabels?: Record<string, string>;
+    canCreate: boolean;
+    placeMode: FloorMapPlaceMode;
+    onPlaceModeChange: (mode: FloorMapPlaceMode) => void;
+    renderPreviewItem?: (item: FloorMapMergedItem) => React.ReactNode;
+    placementPreviewSize?: {
+        width: number;
+        height: number;
+    };
+    decorationPreviewSize?: number;
+    sceneElements?: FloorMapSceneElement[];
+    onSave?: () => void;
+    saving?: boolean;
+    saveError?: Error | string;
+    /** 布局草稿已相对持久化配置变更，提示用户点击本栏「保存」 */
+    layoutDirty?: boolean;
+    className?: string;
+    /** 触摸/笔：Pointer 拖拽落点（mouse 仍用 HTML5 DnD） */
+    onPaletteCardPointerDown?: (payload: FloorMapPaletteDragPayload, e: React.PointerEvent<HTMLButtonElement>) => void;
+    /** 触摸拖放结束后吞掉按钮 click，避免误触切换落点模式 */
+    consumeToolbarClickIfTouchDrag?: () => boolean;
+}
+export declare function FloorMapToolbar(props: FloorMapToolbarProps): JSX.Element;
+export default FloorMapToolbar;

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

@@ -0,0 +1,53 @@
+/**
+ * ItemLayer - 楼层图展示层
+ * 按 items 的 (x, y) 与 cellSize 定位，用 renderItem 渲染每项内容
+ */
+import React from 'react';
+import type { FloorMapItemBase, FloorMapItemUnit } from '../types';
+import type { CSSProperties } from 'react';
+import './ItemLayer.less';
+export interface ItemLayerProps<T extends FloorMapItemBase> {
+    /** 资源列表 */
+    items: T[];
+    /** 每项渲染函数 */
+    renderItem: (item: T, index: number) => React.ReactNode;
+    /** 每项 key */
+    rowKey?: string | ((item: T, index: number) => string);
+    /** 每格像素尺寸（cell 单位时用；pixel 单位时作为缺省宽高） */
+    cellSize: number;
+    /** item 坐标与尺寸单位：cell 格子数，pixel 像素 */
+    itemUnit?: FloorMapItemUnit;
+    /** item 之间的间距（像素），仅 cell 单位时生效 */
+    itemGap?: number;
+    /** 内容区总宽度（像素），由 items 推导或外部传入 */
+    contentWidth: number;
+    /** 内容区总高度（像素） */
+    contentHeight: number;
+    /** 内容区 X 偏移（画布包围盒向左/上扩展时，图元层整体平移） */
+    contentOffsetX?: number;
+    /** 内容区 Y 偏移 */
+    contentOffsetY?: number;
+    /** 是否启用 hover 事件 */
+    enableHover?: boolean;
+    /**
+     * 是否在 hover 时显示外沿描边（选中感高亮）。默认 true。
+     * 平面图只读态可由布局关闭，仅去掉描边，不影响 onItemHover。
+     */
+    itemHoverOutline?: boolean;
+    /** 点击回调 */
+    onItemClick?: (item: T, index: number, e: React.MouseEvent<HTMLElement>) => void;
+    /** hover 进入 */
+    onItemHover?: (item: T, index: number, e: React.MouseEvent<HTMLElement>) => void;
+    /** hover 离开 */
+    onItemLeave?: (item: T, index: number, e: React.MouseEvent<HTMLElement>) => void;
+    /** 每项外层容器额外样式（与定位样式合并） */
+    getMergedItemWrapperStyle?: (item: T, index: number) => CSSProperties | undefined;
+    /**
+     * 与编辑态一致：在含 `data-pisell-floor-room-scroll-surface` 的区域内按下时置 true，
+     * 用于禁用 Transform 画布平移，避免图元内纵向滑动拖动画布。
+     */
+    onInteractionChange?: (active: boolean) => void;
+    className?: string;
+}
+export declare function ItemLayer<T extends FloorMapItemBase>(props: ItemLayerProps<T>): JSX.Element;
+export default ItemLayer;

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

@@ -0,0 +1,27 @@
+/**
+ * MapLayer - 楼层图底层
+ * 负责背景（无/纯色/图片/SVG）、网格线、padding、gap
+ */
+import React from 'react';
+import type { FloorMapLayerConfig } from '../types';
+import './MapLayer.less';
+export interface MapLayerProps {
+    /** 底层配置 */
+    config?: FloorMapLayerConfig;
+    /** 内容区域宽度（逻辑单位或像素，用于网格线计算） */
+    contentWidth?: number;
+    /** 内容区域高度 */
+    contentHeight?: number;
+    /** 每格像素尺寸（用于网格线间距） */
+    cellSize?: number;
+    /** 为 true 时不应用纯色背景，让画布底层网格透出 */
+    preferCanvasGrid?: boolean;
+    /** 为 true 时容器设置 pointer-events: none，空白处点击可透传到下层，供 react-zoom-pan-pinch 画布平移 */
+    pointerEventsNone?: boolean;
+    /** 子节点（展示层会叠在上方） */
+    children?: React.ReactNode;
+    /** 自定义类名 */
+    className?: string;
+}
+export declare function MapLayer(props: MapLayerProps): JSX.Element;
+export default MapLayer;

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

@@ -0,0 +1,46 @@
+/**
+ * ViewControls - 内置视图控制：默认仅缩放；可选复位、区域定位、全屏等
+ * 平面图（dockChrome）：Dock 折叠入口 + 展开条（含业务插槽、空闲自动收起）
+ * 非平面图：单条横栏，缩放与工具始终同排（无 Menu 折叠）
+ */
+import React from 'react';
+import type { FloorMapControlsConfig } from '../types';
+import './ViewControls.less';
+/** 从 react-zoom-pan-pinch 拿到的控制 API（由主组件传入） */
+export interface ViewControlsApi {
+    zoomIn: () => void;
+    zoomOut: () => void;
+    resetTransform: () => void;
+    /** 区域定位，可能由主组件基于 items 计算后封装 */
+    fitBounds?: () => void;
+    /** 切换全屏（requestFullscreen / exitFullscreen） */
+    toggleFullscreen?: () => void;
+}
+export interface ViewControlsProps {
+    /** 控制 API */
+    api: ViewControlsApi;
+    /** 显隐配置 */
+    config?: FloorMapControlsConfig;
+    /** 当前缩放比例（1 = 100%），用于 Stepper 展示 */
+    scale?: number;
+    /** 当前是否处于全屏 */
+    isFullscreen?: boolean;
+    className?: string;
+    /** 与 config.showGridToggle 联用：当前画布是否显示网格 */
+    mapGridVisible?: boolean;
+    /** 切换当前画布 draft 的 mapLayer.showGrid */
+    onToggleMapGrid?: () => void;
+    /**
+     * 平面图 Dock：圆角浅底样式，默认折叠为单入口；展开后含缩放、工具、全屏与 dockExpandedTrailing
+     */
+    dockChrome?: boolean;
+    /** Dock 展开区最右侧业务插槽（如「编辑画布」） */
+    dockExpandedTrailing?: React.ReactNode;
+    /**
+     * Dock 展开后无操作自动收起（毫秒）；0 表示不自动收起
+     * @default 10000
+     */
+    autoCollapseDockMs?: number;
+}
+export declare function ViewControls(props: ViewControlsProps): JSX.Element | null;
+export default ViewControls;

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

@@ -0,0 +1,19 @@
+/**
+ * 在 TransformWrapper 内用 useControls 拿到 zoom 控制并渲染 ViewControls，确保点击加减能缩放
+ */
+import React from 'react';
+import type { FloorMapControlsConfig } from '../types';
+export interface ViewControlsWithZoomProps {
+    config?: FloorMapControlsConfig;
+    scale?: number;
+    isFullscreen?: boolean;
+    fitBounds: () => void;
+    /** 未传时不展示全屏按钮（如编辑态 floorMapFullscreenMode 为 disabled） */
+    toggleFullscreen?: () => void;
+    mapGridVisible?: boolean;
+    onToggleMapGrid?: () => void;
+    dockChrome?: boolean;
+    dockExpandedTrailing?: React.ReactNode;
+    autoCollapseDockMs?: number;
+}
+export declare function ViewControlsWithZoom(props: ViewControlsWithZoomProps): JSX.Element;

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

@@ -0,0 +1,21 @@
+/**
+ * 楼层图布局子组件导出
+ */
+export { MapLayer } from './MapLayer';
+export { ItemLayer } from './ItemLayer';
+export { ViewControls } from './ViewControls';
+export { ViewControlsWithZoom } from './ViewControlsWithZoom';
+export { CanvasTabs } from './CanvasTabs';
+export { EditableItemLayer } from './EditableItemLayer';
+export { FloorMapToolbar } from './FloorMapToolbar';
+export { FloorMapEditTopBar } from './FloorMapEditTopBar';
+export { FloorMapEditPanel } from './FloorMapEditPanel';
+export { FloorMapDataForm } from './FloorMapDataForm';
+export type { ViewControlsApi } from './ViewControls';
+export type { ViewControlsWithZoomProps } from './ViewControlsWithZoom';
+export type { CanvasTabsProps } from './CanvasTabs';
+export type { EditableItemLayerProps } from './EditableItemLayer';
+export type { FloorMapToolbarProps, PlaceMode } from './FloorMapToolbar';
+export type { FloorMapEditTopBarProps, FloorMapEditTopBarMode, } from './FloorMapEditTopBar';
+export type { FloorMapEditPanelProps } from './FloorMapEditPanel';
+export type { FloorMapDataFormProps } from './FloorMapDataForm';

package/lib/components/pisellFloorMapLayout/context/FloorMapLayoutContext.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 平面图数据/保存等注入上下文；单独页面包 `FloorMapLayoutProvider`，RecordBoard 由 Shell 内置 Provider。
+ */
+import React from 'react';
+import type { FloorMapLayoutContextValue } from '../types';
+/**
+ * 未传 `floorMapLayoutContext` 时 Shell 使用该稳定引用，避免无意义变更引用。
+ */
+export declare const EMPTY_FLOOR_MAP_LAYOUT_CONTEXT: FloorMapLayoutContextValue;
+export declare function useFloorMapLayoutContext(): FloorMapLayoutContextValue | undefined;
+export interface FloorMapLayoutProviderProps {
+    value: FloorMapLayoutContextValue;
+    children: React.ReactNode;
+}
+/** 注入 `FloorMapLayoutContextValue`；`value` 建议由调用方 `useMemo` 稳定化 */
+export declare function FloorMapLayoutProvider({ value, children, }: FloorMapLayoutProviderProps): JSX.Element;

package/lib/components/pisellFloorMapLayout/context/mergeFloorMapLayoutContext.d.ts

@@ -0,0 +1,5 @@
+import type { FloorMapItemBase, FloorMapLayoutContextValue, PisellFloorMapLayoutProps } from '../types';
+/**
+ * 将 `FloorMapLayoutContext` 与 Layout props 合并：各字段 props ?? ctx，props 显式值优先。
+ */
+export declare function mergeFloorMapLayoutPropsFromContext<T extends FloorMapItemBase>(props: PisellFloorMapLayoutProps<T>, ctx: FloorMapLayoutContextValue | undefined): PisellFloorMapLayoutProps<T>;

package/lib/components/pisellFloorMapLayout/hooks/useFloorMapEditState.d.ts

@@ -0,0 +1,66 @@
+import type { MouseEvent, MutableRefObject } from 'react';
+import type { DataSourceFormColumn, FloorMapCanvasNameI18n, FloorMapDataSourceRecordFormContent, FloorMapDataSources, FloorMapItemBase, FloorMapMergedItem, FloorMapPlaceMode, FloorMapSceneElement, FloorMapViewConfig } from '../types';
+export interface UseFloorMapEditStateParams<T extends FloorMapItemBase> {
+    floorMapConfigProp: FloorMapViewConfig | undefined;
+    isFloorMapView: boolean;
+    itemsProp: T[];
+    cellSizeProp?: number;
+    dataSources: FloorMapDataSources | undefined;
+    onSave: ((config: FloorMapViewConfig) => void) | undefined;
+    onDataSourceRecordSave: ((dataSourceKey: string, id: string, newData: Record<string, unknown>) => void) | undefined;
+    dataSourceFormColumns: Record<string, DataSourceFormColumn[]> | undefined;
+    dataSourceRecordForm: Record<string, FloorMapDataSourceRecordFormContent> | undefined;
+    dataSourceLabels?: Record<string, string>;
+    layoutPrefix: string;
+    contentOffsetRef: MutableRefObject<{
+        x: number;
+        y: number;
+    }>;
+    showDataSourceRecordFormBlock?: boolean;
+}
+export declare function useFloorMapEditState<T extends FloorMapItemBase>(params: UseFloorMapEditStateParams<T>): {
+    config: FloorMapViewConfig | null;
+    currentCanvasId: string | null;
+    setCurrentCanvasId: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    selectedId: string | null;
+    setSelectedId: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    placeMode: FloorMapPlaceMode;
+    setPlaceMode: import("react").Dispatch<import("react").SetStateAction<FloorMapPlaceMode>>;
+    mergedItems: FloorMapMergedItem[];
+    items: T[];
+    saving: boolean;
+    savingRecord: boolean;
+    handleAddCanvas: () => void;
+    handleRemoveCanvas: (canvasId: string) => void;
+    handleRenameCanvas: (canvasId: string, name: string | FloorMapCanvasNameI18n) => void;
+    handleUpdateItem: (itemId: string, patch: Partial<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>) => void;
+    handleCanvasPlaceClick: (e: MouseEvent<HTMLDivElement>) => void;
+    handleSave: () => void;
+    placeSceneElementFromPaletteDrop: (contentX: number, contentY: number, scene: Extract<FloorMapPlaceMode, {
+        type: 'scene';
+    }>) => void;
+    editPanelParams: {
+        itemId: string;
+        sceneElement: FloorMapSceneElement;
+        onUpdate: (patch: Partial<FloorMapSceneElement>) => void;
+        onSaveRecord: ((dataSourceKey: string, id: string, newData: Record<string, unknown>) => void) | undefined;
+        onClose: () => void;
+        onDelete: (() => void) | undefined;
+        recordFormColumns: Record<string, DataSourceFormColumn[]> | undefined;
+        dataSourceRecordForm: Record<string, FloorMapDataSourceRecordFormContent> | undefined;
+        dataSourceLabels: Record<string, string> | undefined;
+        layoutDraftDirty: boolean;
+        showDataSourceRecordFormBlock: boolean | undefined;
+    } | null;
+    placeOverlayClass: string;
+    isLayoutDirty: boolean;
+    toggleDraftCanvasShowGrid: () => void;
+    toggleSelectedLayoutLock: () => void;
+    duplicateSelectedElement: () => void;
+    deleteSelectedElement: () => void;
+};

package/lib/components/pisellFloorMapLayout/hooks/useFloorMapPaletteTouchDrag.d.ts

@@ -0,0 +1,21 @@
+import type { MutableRefObject, PointerEvent as ReactPointerEvent } from 'react';
+import type { FloorMapPaletteDragPayload } from '../utils/floorMapDropUtils';
+export interface UseFloorMapPaletteTouchDragParams {
+    enabled: boolean;
+    mapDropLayerRef: MutableRefObject<HTMLDivElement | null>;
+    contentWidth: number;
+    contentHeight: number;
+    contentOffsetRef: MutableRefObject<{
+        x: number;
+        y: number;
+    }>;
+    setMapPaletteDragActive: (v: boolean) => void;
+    onDropInScene: (payload: FloorMapPaletteDragPayload, sceneX: number, sceneY: number) => void;
+}
+export interface UseFloorMapPaletteTouchDragResult {
+    /** 挂在图元预览按钮上；mouse 不处理，交给 HTML5 DnD */
+    handlePaletteCardPointerDown: (payload: FloorMapPaletteDragPayload, e: ReactPointerEvent<HTMLElement>) => void;
+    /** 图元按钮 onClick 前检查：触摸拖放过则吞掉本次点击 */
+    consumeToolbarClickIfTouchDrag: () => boolean;
+}
+export declare function useFloorMapPaletteTouchDrag(params: UseFloorMapPaletteTouchDragParams): UseFloorMapPaletteTouchDragResult;

package/lib/components/pisellFloorMapLayout/hooks/useFloorMapTransformMetrics.d.ts

@@ -0,0 +1,67 @@
+import type { MutableRefObject } from 'react';
+import type { FloorMapItemBase, FloorMapItemUnit, FloorMapZoomConfig } from '../types';
+/** react-zoom-pan-pinch TransformWrapper render 注入的上下文 */
+export declare type FloorMapTransformContext = {
+    zoomIn: () => void;
+    zoomOut: () => void;
+    resetTransform: () => void;
+    setTransform: (x: number, y: number, scale: number) => void;
+} | null;
+export interface UseFloorMapTransformMetricsParams<T extends FloorMapItemBase> {
+    items: T[];
+    cellSize: number;
+    itemGap: number;
+    effectiveItemUnit: FloorMapItemUnit;
+    isFloorMapView: boolean;
+    mode: 'read' | 'edit';
+    zoom: FloorMapZoomConfig;
+    transformRef: MutableRefObject<FloorMapTransformContext>;
+    /** 由父组件创建并传入 useFloorMapEditState，本 hook 每帧写入内容区偏移 */
+    contentOffsetRef: MutableRefObject<{
+        x: number;
+        y: number;
+    }>;
+    /** 与 mapLayer.boundingPadding 一致；未传用 DEFAULT_BOUNDING_PADDING */
+    boundingPadding?: number;
+    /**
+     * 平面图：当前画布 id（或其它在切换画布时应重置平移/对齐会话的 key）。
+     * 不传则不跑「异步加载图元后的首次左上对齐」逻辑。
+     */
+    frameResetKey?: string;
+}
+export declare function useFloorMapTransformMetrics<T extends FloorMapItemBase>(params: UseFloorMapTransformMetricsParams<T>): {
+    containerRef: import("react").RefObject<HTMLDivElement>;
+    mapAreaRef: import("react").RefObject<HTMLDivElement>;
+    viewportSize: {
+        width: number;
+        height: number;
+    };
+    mapAreaSize: {
+        width: number;
+        height: number;
+    };
+    contentWidth: number;
+    contentHeight: number;
+    contentOffsetX: number;
+    contentOffsetY: number;
+    initialPositionX: number;
+    initialPositionY: number;
+    zoomConfig: {
+        initialScale: number;
+        minScale: number;
+        maxScale: number;
+        step: number;
+    };
+    scale: number;
+    setScale: import("react").Dispatch<import("react").SetStateAction<number>>;
+    isFullscreen: boolean;
+    toggleFullscreen: () => void;
+    fitBounds: () => boolean;
+    lastTransformRef: MutableRefObject<{
+        x: number;
+        y: number;
+        scale: number;
+    }>;
+    isInteractingWithElement: boolean;
+    setIsInteractingWithElement: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+};

package/lib/components/pisellFloorMapLayout/hooks/useShopFloorPlanSubscription.d.ts

@@ -0,0 +1,19 @@
+import type { ShopFloorPlanDetail } from '../shopFloorPlan/shopFloorPlanTypes';
+import type { ShopFloorPlanByCodeRequestOptions } from '../shopFloorPlan/shopFloorPlanTypes';
+export declare type UseShopFloorPlanSubscriptionParams = {
+    /** `null` 时不发起请求（与预约页 `resolvedFloorPlanId` 一致）；清空状态由调用方处理 */
+    enabled: boolean;
+    code: string;
+    subscriberId: string;
+    ensureByCode: (code: string, opts?: ShopFloorPlanByCodeRequestOptions) => Promise<ShopFloorPlanDetail | null>;
+    unsubscribeQuery: (subscriberId: string) => Promise<void>;
+    onDetail: (detail: ShopFloorPlanDetail) => void;
+    onLoadError?: (err: unknown) => void;
+    /** 与预约一致：默认 true */
+    osServer?: boolean;
+};
+/**
+ * 按 code 订阅店铺平面图：首包 Promise + WebSocket callback 均归一为 `onDetail`。
+ * 不包含与业务默认 {@link FloorMapViewConfig} 的合并（由调用方在 `onDetail` 或后续 useMemo 完成）。
+ */
+export declare function useShopFloorPlanSubscription(params: UseShopFloorPlanSubscriptionParams): void;

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

@@ -0,0 +1,25 @@
+/**
+ * PisellFloorMapLayout 组件入口
+ * 空间布局视图：在二维平面按坐标渲染资源，支持缩放/平移/复位；支持 floorMapConfig + mode 平面图视图
+ */
+export { PisellFloorMapLayout } from './PisellFloorMapLayout';
+export type { PisellFloorMapLayoutProps, PisellFloorMapLayoutRef, FloorMapItemBase, FloorMapItemUnit, FloorMapLayerConfig, FloorMapZoomConfig, FloorMapPanConfig, FloorMapControlsConfig, FloorMapItemShape, FloorMapBackgroundType, FloorMapPanBoundary, FloorMapLayoutMode, FloorMapGridLayoutConfig, FloorMapCanvas, FloorMapCanvasNameI18n, FloorMapElement, FloorMapData, FloorMapViewConfig, FloorMapCanvasUiConfig, FloorMapSceneElement, FloorMapSceneElementDataBinding, FloorMapPlaceMode, FloorMapElementKindCategory, FloorMapElementDataBindingPolicy, FloorMapElementDefaultPresentation, FloorMapEdge, FloorMapElementKindConfig, FloorMapElementType, FloorMapTextSlot, FloorMapDataSources, FloorMapRenderOptions, FloorMapEditPanelParams, DataSourceFormColumn, FloorMapMergedItem, FloorMapRecordFormRenderContext, FloorMapDataSourceRecordFormContent, FloorMapFullscreenMode, FloorMapLayoutContextValue, FloorMapViewportOverlayRenderArgs, } from './types';
+export { FLOOR_MAP_STAGE_ELEMENT_KIND, FLOOR_MAP_IMAGE_ELEMENT_KIND, } from './types';
+export { renderFloorMapFallbackPlaceholder } from './utils/floorMapFallbackRender';
+export { isFloorMapImageElementKind } from './utils/floorMapElementKindUtils';
+export { findFloorMapRowByDataBinding, getFloorMapBindingPlaceholderReason, } from './utils/floorMapDataBindingUtils';
+export type { FloorMapDataSourceRow, FloorMapBindingPlaceholderReason, } from './utils/floorMapDataBindingUtils';
+export { createShopFloorPlanClient, SHOP_FLOOR_PLAN_DUPLICATE_CODE, } from './shopFloorPlan/shopFloorPlanClient';
+export type { ShopFloorPlanDetail, ShopFloorPlanLayoutItem, PostShopFloorPlanBody, PutShopFloorPlanBody, ShopFloorPlanByCodeRequestOptions, ShopFloorPlanHttpAdapter, CreateShopFloorPlanClientOptions, EnsureShopFloorPlanByCodeOptions, } from './shopFloorPlan/shopFloorPlanTypes';
+export type { UseShopFloorPlanSubscriptionParams } from './hooks/useShopFloorPlanSubscription';
+export { pickFloorPlanDetail, parseLayoutFieldToViewConfigPatch, mergeFloorPlanViewRemote, floorMapSavedConfigToRemotePatch, viewConfigToLayoutPayload, inferCanvasSizeFromScene, buildFloorPlanPutBody, isShopFloorPlanNotFoundResponse, isHttpNotFoundError, isFloorPlanDuplicateCodeError, } from './shopFloorPlan/shopFloorPlanPure';
+export { sceneElementsToShopLayout, shopLayoutToSceneElements, } from './shopFloorPlan/shopFloorPlanMapping';
+export { useShopFloorPlanSubscription } from './hooks/useShopFloorPlanSubscription';
+export { wrapFloorMapOnSaveWithRemotePersist } from './utils/floorMapRemotePersist';
+export type { WrapFloorMapOnSaveWithRemotePersistParams } from './utils/floorMapRemotePersist';
+export { FloorMapLayoutProvider, useFloorMapLayoutContext, EMPTY_FLOOR_MAP_LAYOUT_CONTEXT, } from './context/FloorMapLayoutContext';
+export type { FloorMapLayoutProviderProps } from './context/FloorMapLayoutContext';
+export { mergeFloorMapLayoutPropsFromContext } from './context/mergeFloorMapLayoutContext';
+export { FloorMapImageElement } from './components/FloorMapImageElement';
+export { getFigmaTableCardFromMerged, renderFigmaStyleTableCard, renderFigmaStyleRoundTableCard, getRenderItemByKindTable, getRenderItemByKindRoundTable, } from './components/FigmaTableCard';
+export type { FigmaTableCardItem, FigmaTableStatus, } from './components/FigmaTableCard';