@pisell/materials 6.11.49 → 6.11.50

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

@@ -0,0 +1,57 @@
+/**
+ * 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;
+    /**
+     * 阅读态：与 {@link rowKey} 解析 id 相等的图元加选中外圈（如详情 Modal 打开时）。
+     */
+    readModeSelectedItemId?: string | null;
+    /**
+     * 与编辑态一致：在含 `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/es/components/pisellFloorMapLayout/components/ItemLayer.js

@@ -21,6 +21,9 @@ var PREFIX = 'pisell-floor-map-layout';
 
 /** 图元内可滚动区标记（如预约房间卡 body / multi-list），与 private-materials 约定一致 */
 var ROOM_SCROLL_SURFACE_SELECTOR = '[data-pisell-floor-room-scroll-surface]';
+
+/** 与 EditableItemLayer `SELECTED_ITEM_STACK_Z` 一致：阅读态选中时抬升，避免邻桌图形盖住描边 */
+var READ_MODE_SELECTED_STACK_Z = 1000000;
 function getItemKey(item, index, rowKey) {
   var _rowKey;
   if (!rowKey) return item.id;
@@ -73,6 +76,7 @@ export function ItemLayer(props) {
     onItemLeave = props.onItemLeave,
     getMergedItemWrapperStyle = props.getMergedItemWrapperStyle,
     onInteractionChange = props.onInteractionChange,
+    readModeSelectedItemId = props.readModeSelectedItemId,
     className = props.className;
 
   /** 触控/指针在房间卡滚动区内按下时禁用画布 pan，松手恢复 */
@@ -137,7 +141,7 @@ export function ItemLayer(props) {
       return ((_a$zIndex = a.zIndex) !== null && _a$zIndex !== void 0 ? _a$zIndex : 0) - ((_b$zIndex = b.zIndex) !== null && _b$zIndex !== void 0 ? _b$zIndex : 0);
     });
     return sorted.map(function (item, index) {
-      var _item$zIndex;
+      var _item$zIndex, _item$zIndex2;
       var left;
       var top;
       var width;
@@ -159,9 +163,10 @@ export function ItemLayer(props) {
       }
       var key = getItemKey(item, index, rowKey);
       var shapeStyle = getShapeStyle(item.shape);
+      var selectedRead = readModeSelectedItemId != null && String(readModeSelectedItemId).trim() !== '' && key === String(readModeSelectedItemId);
       return /*#__PURE__*/React.createElement("div", {
         key: key,
-        className: classNames("".concat(PREFIX, "-item"), _defineProperty(_defineProperty({}, "".concat(PREFIX, "-item-hoverable"), enableHover), "".concat(PREFIX, "-item-hover-outline"), enableHover && itemHoverOutline)),
+        className: classNames("".concat(PREFIX, "-item"), _defineProperty(_defineProperty(_defineProperty({}, "".concat(PREFIX, "-item-hoverable"), enableHover), "".concat(PREFIX, "-item-hover-outline"), enableHover && itemHoverOutline), "".concat(PREFIX, "-item-read-selected"), selectedRead)),
         style: _objectSpread(_objectSpread({
           position: 'absolute',
           left: left,
@@ -169,7 +174,7 @@ export function ItemLayer(props) {
           width: width,
           height: height,
           boxSizing: 'border-box',
-          zIndex: (_item$zIndex = item.zIndex) !== null && _item$zIndex !== void 0 ? _item$zIndex : 0
+          zIndex: selectedRead ? READ_MODE_SELECTED_STACK_Z + ((_item$zIndex = item.zIndex) !== null && _item$zIndex !== void 0 ? _item$zIndex : 0) : (_item$zIndex2 = item.zIndex) !== null && _item$zIndex2 !== void 0 ? _item$zIndex2 : 0
         }, shapeStyle), getMergedItemWrapperStyle === null || getMergedItemWrapperStyle === void 0 ? void 0 : getMergedItemWrapperStyle(item, index)),
         onClick: function onClick(e) {
           return onItemClick === null || onItemClick === void 0 ? void 0 : onItemClick(item, index, e);
@@ -184,7 +189,7 @@ export function ItemLayer(props) {
         onTouchStartCapture: handleItemTouchStartCapture
       }, renderItem(item, index));
     });
-  }, [items, renderItem, rowKey, cellSize, itemUnit, itemGap, enableHover, itemHoverOutline, onItemClick, onItemHover, onItemLeave, getMergedItemWrapperStyle, handleItemPointerDownCapture, handleItemTouchStartCapture]);
+  }, [items, renderItem, rowKey, cellSize, itemUnit, itemGap, enableHover, itemHoverOutline, onItemClick, onItemHover, onItemLeave, getMergedItemWrapperStyle, handleItemPointerDownCapture, handleItemTouchStartCapture, readModeSelectedItemId]);
   return /*#__PURE__*/React.createElement("div", {
     className: classNames("".concat(PREFIX, "-item-layer"), className),
     style: {

package/es/components/pisellFloorMapLayout/components/ItemLayer.less

@@ -13,10 +13,17 @@
 
   /** hover 描边与编辑态选中一致（见 EditableItemLayer：`pisell-floor-map-layout-editable-item-selected`） */
 
-  &-hoverable&-hover-outline:hover {
+  // &-hoverable&-hover-outline:hover {
+  //   outline: 3px solid var(--fmap-primary, #1677ff);
+  //   outline-offset: 0;
+  //   box-shadow: 0 0 0 1px rgba(22, 119, 255, 0.25);
+  //   z-index: 1;
+  // }
+
+  /** 阅读态：详情弹层等打开时由业务传入 `readModeSelectedItemId`，与编辑态选中描边一致 */
+  &-read-selected {
     outline: 3px solid var(--fmap-primary, #1677ff);
     outline-offset: 0;
     box-shadow: 0 0 0 1px rgba(22, 119, 255, 0.25);
-    z-index: 1;
   }
 }

package/es/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/es/components/pisellFloorMapLayout/components/ViewControls.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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;
+    /** 当前 transform 是否处于「适配视口」结果（用于按钮激活态） */
+    fitBoundsActive?: boolean;
+    className?: string;
+    /** 与 config.showGridToggle 联用：当前画布是否显示网格 */
+    mapGridVisible?: boolean;
+    /** 切换当前画布 draft 的 mapLayer.showGrid */
+    onToggleMapGrid?: () => void;
+    /**
+     * 视口锁定态：true 时显示「已锁定」图标，并禁用所有改变视角的按钮
+     * （zoom +/- / reset / fitBounds）。pan / wheel / pinch 由调用方在 TransformWrapper 上同步关闭。
+     */
+    viewportLocked?: boolean;
+    /** 切换视口锁定；未传时不展示锁定按钮 */
+    onToggleViewportLock?: () => 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/es/components/pisellFloorMapLayout/components/ViewControlsWithZoom.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 在 TransformWrapper 内用 useControls 拿到 zoom 控制并渲染 ViewControls，确保点击加减能缩放
+ */
+import React from 'react';
+import type { FloorMapControlsConfig } from '../types';
+export interface ViewControlsWithZoomProps {
+    config?: FloorMapControlsConfig;
+    scale?: number;
+    isFullscreen?: boolean;
+    /** 当前 transform 是否吻合「适配视口」结果，用于按钮激活态 */
+    fitBoundsActive?: boolean;
+    fitBounds: () => void;
+    /** 未传时不展示全屏按钮（如编辑态 floorMapFullscreenMode 为 disabled） */
+    toggleFullscreen?: () => void;
+    mapGridVisible?: boolean;
+    onToggleMapGrid?: () => void;
+    /** 视口锁定态（true 时所有视角写入入口被禁用） */
+    viewportLocked?: boolean;
+    /** 切换视口锁定；未传时不展示锁定按钮 */
+    onToggleViewportLock?: () => void;
+    dockChrome?: boolean;
+    dockExpandedTrailing?: React.ReactNode;
+    autoCollapseDockMs?: number;
+}
+export declare function ViewControlsWithZoom(props: ViewControlsWithZoomProps): JSX.Element;

package/es/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/es/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/es/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/es/components/pisellFloorMapLayout/hooks/useFloorMapEditState.d.ts

@@ -0,0 +1,71 @@
+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;
+    discardDraft: () => 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;
+    undoDraft: () => void;
+    redoDraft: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+};

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

@@ -0,0 +1,89 @@
+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;
+    /**
+     * react-zoom-pan-pinch v3 实际签名：(x, y, scale, animationTime?, animationType?)
+     * 默认 animationTime≈200ms；传 0 立即落点，避免被前一次动画吃掉或与之冲突
+     * （restore / 缓存恢复路径应使用 0 立即覆盖已在缓动中的 fit 动画）。
+     * 这里只暴露我们用到的前 4 参；库 animationType 是 `keyof typeof animations` 联合，
+     * 暴露过来反而限制传入对象的兼容性，我们也确实不传它。
+     */
+    setTransform: (x: number, y: number, scale: number, animationTime?: 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;
+    /**
+     * 视口持久化标识（通常拼自 canvasId）。传入后：
+     *   - 切换 / 挂载时若 localStorage 中有缓存，自动恢复 transform 并跳过本帧 autoFit；
+     *   - 用户拖动 / 缩放时（节流 300ms）写回缓存；
+     *   - 主动 fitBounds / 进入伪全屏后由 fitBounds 触发的写入也会同步保存。
+     * 不传则完全不读不写 localStorage。
+     */
+    viewportPersistKey?: 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;
+    isAtFitBounds: boolean;
+    notifyTransformed: (x: number, y: number, nextScale: number) => void;
+    persistCurrentViewport: () => void;
+    attachTransformContext: (ctx: NonNullable<FloorMapTransformContext>) => void;
+    lastTransformRef: MutableRefObject<{
+        x: number;
+        y: number;
+        scale: number;
+    }>;
+    isInteractingWithElement: boolean;
+    setIsInteractingWithElement: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    viewportLocked: boolean;
+    setViewportLocked: (next: boolean) => void;
+    toggleViewportLocked: () => void;
+};

package/es/components/pisellFloorMapLayout/hooks/useFloorMapTransformMetrics.js

@@ -17,6 +17,12 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 import { getContentSize, getPixelBoundingBox } from "../utils/layoutMeasurements";
 import { DEFAULT_BOUNDING_PADDING, FIT_BOUNDS_MATCH_POS_EPSILON, FIT_BOUNDS_MATCH_SCALE_EPSILON, VIEWPORT_PERSIST_DEBOUNCE_MS, VIEWPORT_TOP_LEFT_MARGIN, readPersistedViewport, readPersistedViewportLock, writePersistedViewport, writePersistedViewportLock } from "./floorMapViewportPersistence";
 
+/**
+ * react-zoom-pan-pinch：`setTransform` 未显式传 `animationTime` 时默认约 200ms 缓动；
+ * 兜底清除「全览激活保持」略大于该值，避免极少数帧未到容差时限位不解除。
+ */
+var FIT_BOUNDS_PROGRAMMATIC_TWEEN_GUARD_MS = 400;
+
 /** react-zoom-pan-pinch TransformWrapper render 注入的上下文 */
 
 export function useFloorMapTransformMetrics(params) {
@@ -116,6 +122,20 @@ export function useFloorMapTransformMetrics(params) {
     isAtFitBounds = _useState10[0],
     setIsAtFitBounds = _useState10[1];
 
+  /**
+   * 程序化 fitBounds 使用库默认缓动时，`onTransformed` 中间帧与快照不等会关掉「全览」激活态。
+   * 缓动持有期内不按中间帧降级，仅在到达快照（容差内）或兜底超时后再按真实 transform 对齐。
+   */
+  var fitBoundsTweenHoldRef = useRef(false);
+  var fitBoundsTweenHoldClearTimerRef = useRef(null);
+  var clearFitBoundsTweenHold = useCallback(function () {
+    if (fitBoundsTweenHoldClearTimerRef.current != null) {
+      clearTimeout(fitBoundsTweenHoldClearTimerRef.current);
+      fitBoundsTweenHoldClearTimerRef.current = null;
+    }
+    fitBoundsTweenHoldRef.current = false;
+  }, []);
+
   /**
    * 视口锁定态：按 viewportPersistKey 维度持久化到 localStorage。
    * - 切 / 挂载时按 key 读初始值；
@@ -302,7 +322,37 @@ export function useFloorMapTransformMetrics(params) {
     var wrapper = container.querySelector('.react-transform-wrapper');
     if (!wrapper) return false;
     var wrapperRect = wrapper.getBoundingClientRect();
-    if (wrapperRect.width <= 0 || wrapperRect.height <= 0) return false;
+    var wEl = wrapper;
+    /**
+     * 祖先链上若有 transform: scale / zoom，getBoundingClientRect 为「视觉」尺寸，
+     * clientWidth/Height 为布局盒尺寸。react-zoom-pan-pinch 的平移/缩放工作在布局坐标系，
+     * 若全览仅用 rect 算 avail 与 position，会与库内部不一致（日志：visual/layout≈0.864）。
+     */
+    var layoutW = wEl.clientWidth > 0 ? wEl.clientWidth : wrapperRect.width;
+    var layoutH = wEl.clientHeight > 0 ? wEl.clientHeight : wrapperRect.height;
+    if (layoutW <= 0 || layoutH <= 0) return false;
+
+    /** 程序化 setTransform 默认带缓动：写入快照后立即保持「全览激活」，缓动结束前不因中间帧关掉 */
+    var applyProgrammaticFit = function applyProgrammaticFit(fx, fy, fScale) {
+      clearFitBoundsTweenHold();
+      lastFitSnapshotRef.current = {
+        x: fx,
+        y: fy,
+        scale: fScale
+      };
+      setIsAtFitBounds(true);
+      fitBoundsTweenHoldRef.current = true;
+      fitBoundsTweenHoldClearTimerRef.current = setTimeout(function () {
+        fitBoundsTweenHoldClearTimerRef.current = null;
+        fitBoundsTweenHoldRef.current = false;
+        var cur = lastTransformRef.current;
+        var s = lastFitSnapshotRef.current;
+        if (!s) return;
+        var same = Math.abs(s.x - cur.x) < FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(s.y - cur.y) < FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(s.scale - cur.scale) < FIT_BOUNDS_MATCH_SCALE_EPSILON;
+        setIsAtFitBounds(same);
+      }, FIT_BOUNDS_PROGRAMMATIC_TWEEN_GUARD_MS);
+      ctx.setTransform(fx, fy, fScale);
+    };
 
     /**
      * 平面图像素模式：按「图元轴对齐包围盒」缩放并居中，不按整块 content（含编辑态撑满视口的空白）适配。
@@ -314,40 +364,28 @@ export function useFloorMapTransformMetrics(params) {
       var bw = Math.max(1, pixelBox.maxRight - pixelBox.minLeft);
       var bh = Math.max(1, pixelBox.maxBottom - pixelBox.minTop);
       var edgePx = 0;
-      var availW = Math.max(1, wrapperRect.width - 2 * edgePx);
-      var availH = Math.max(1, wrapperRect.height - 2 * edgePx);
+      var availW = Math.max(1, layoutW - 2 * edgePx);
+      var availH = Math.max(1, layoutH - 2 * edgePx);
       var _raw = Math.min(availW / bw, availH / bh);
       var _nextScale = Math.min(_raw, (_zoom$max2 = zoom.max) !== null && _zoom$max2 !== void 0 ? _zoom$max2 : 2);
       var ap = alignPadSingle !== null && alignPadSingle !== void 0 ? alignPadSingle : padSingle;
       var bboxCx = ap + bw / 2;
       var bboxCy = ap + bh / 2;
-      var _x = wrapperRect.width / 2 - bboxCx * _nextScale;
-      var _y = wrapperRect.height / 2 - bboxCy * _nextScale;
-      ctx.setTransform(_x, _y, _nextScale);
-      lastFitSnapshotRef.current = {
-        x: _x,
-        y: _y,
-        scale: _nextScale
-      };
-      setIsAtFitBounds(true);
+      var _x = layoutW / 2 - bboxCx * _nextScale;
+      var _y = layoutH / 2 - bboxCy * _nextScale;
+      applyProgrammaticFit(_x, _y, _nextScale);
       return true;
     }
     if (contentWidth <= 0 || contentHeight <= 0) return false;
     /** 非平面图或无图元：仍按整块 content 适配 */
-    var raw = Math.min(wrapperRect.width / contentWidth, wrapperRect.height / contentHeight);
+    var raw = Math.min(layoutW / contentWidth, layoutH / contentHeight);
     var nextScale = Math.min(raw, (_zoom$max3 = zoom.max) !== null && _zoom$max3 !== void 0 ? _zoom$max3 : 2);
     var padA = alignPadSingle !== null && alignPadSingle !== void 0 ? alignPadSingle : 0;
     var x = VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
     var y = VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
-    ctx.setTransform(x, y, nextScale);
-    lastFitSnapshotRef.current = {
-      x: x,
-      y: y,
-      scale: nextScale
-    };
-    setIsAtFitBounds(true);
+    applyProgrammaticFit(x, y, nextScale);
     return true;
-  }, [contentWidth, contentHeight, zoom.max, transformRef, alignPadSingle, isFloorMapView, effectiveItemUnit, items, cellSize, padSingle]);
+  }, [clearFitBoundsTweenHold, contentWidth, contentHeight, zoom, transformRef, alignPadSingle, isFloorMapView, effectiveItemUnit, items, cellSize, padSingle]);
 
   /** 让"进入伪全屏后自动 fit"的 effect 能拿到最新的 fitBounds 实现 */
   fitBoundsRef.current = fitBounds;
@@ -528,6 +566,14 @@ export function useFloorMapTransformMetrics(params) {
     var snap = lastFitSnapshotRef.current;
     if (snap) {
       var same = Math.abs(snap.x - x) < FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(snap.y - y) < FIT_BOUNDS_MATCH_POS_EPSILON && Math.abs(snap.scale - nextScale) < FIT_BOUNDS_MATCH_SCALE_EPSILON;
+      if (fitBoundsTweenHoldRef.current) {
+        if (same) {
+          clearFitBoundsTweenHold();
+          setIsAtFitBounds(true);
+        }
+        /** 缓动中间帧：保持已设的「全览激活」，不因尚未对齐快照而关掉 */
+        return;
+      }
       setIsAtFitBounds(function (prev) {
         return prev === same ? prev : same;
       });
@@ -536,7 +582,7 @@ export function useFloorMapTransformMetrics(params) {
         return prev ? false : prev;
       });
     }
-  }, []);
+  }, [clearFitBoundsTweenHold]);
 
   /**
    * 用户交互结束时（pan / zoom / pinch / wheel stop）调用：
@@ -572,6 +618,7 @@ export function useFloorMapTransformMetrics(params) {
    *    防止后续 effect 反向覆盖缓存值。
    */
   var applyPersistedViewport = useCallback(function (cached) {
+    clearFitBoundsTweenHold();
     var ctx = transformRef.current;
     if (!ctx) return false;
     ctx.setTransform(cached.x, cached.y, cached.scale, 0);
@@ -585,7 +632,7 @@ export function useFloorMapTransformMetrics(params) {
       cachedRestoredFrameRef.current = String(currentFrame);
     }
     return true;
-  }, [transformRef]);
+  }, [clearFitBoundsTweenHold, transformRef]);
 
   /**
    * 切换 viewportPersistKey 或 frameResetKey 时（含挂载、wrapper 重挂载）：
@@ -683,6 +730,10 @@ export function useFloorMapTransformMetrics(params) {
       }
       (_flushPersistRef$curr = flushPersistRef.current) === null || _flushPersistRef$curr === void 0 || _flushPersistRef$curr.call(flushPersistRef);
       flushPersistRef.current = null;
+      if (fitBoundsTweenHoldClearTimerRef.current != null) {
+        clearTimeout(fitBoundsTweenHoldClearTimerRef.current);
+        fitBoundsTweenHoldClearTimerRef.current = null;
+      }
     };
   }, [viewportPersistKey]);
   return {

package/es/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;