@pisell/materials 6.11.48 → 6.11.50

package/es/components/Pagination/index.d.ts

@@ -4,7 +4,8 @@ declare const Pagination: (props: PaginationProps) => JSX.Element | null;
 export declare const paginationConfig: {
     className: string;
     defaultCurrent: number;
-    showTotal: (total: number, range: [number, number]) => string;
+    /** 无 props 上下文时仅能根据 total + range 近似推算（见 resolveCurrentPage） */
+    showTotal: (totalRecords: number, range: [number, number]) => any;
     responsive: boolean;
     size: string;
 };

package/es/components/Pagination/index.js

@@ -8,7 +8,7 @@ function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
-import React, { useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 // import { ArrowLeft, ArrowRight } from "@pisell/icon/es";
 import ArrowRight from '@pisell/icon/es/ArrowRight';
 import ArrowLeft from '@pisell/icon/es/ArrowLeft';
@@ -26,16 +26,32 @@ function getPaginationText(key) {
   if (fromUtils !== fullKey) return fromUtils;
   return (_getText = getText(fullKey)) !== null && _getText !== void 0 ? _getText : getText("table-pagination-".concat(key));
 }
+
+/**
+ * antd Pagination 的 showTotal(total, range) 中 range 为本页条目序号区间 [start, end]，
+ * 不是页码。未受控时用 range 与 pageSize 推算当前页。
+ */
+function resolveCurrentPage(props, range, pageSize) {
+  var _props$current;
+  var fromProps = (_props$current = props.current) !== null && _props$current !== void 0 ? _props$current : props.defaultCurrent;
+  if (typeof fromProps === 'number' && fromProps >= 1) {
+    return fromProps;
+  }
+  var start = range[0];
+  if (start == null || start < 1 || pageSize < 1) {
+    return 1;
+  }
+  return Math.floor((start - 1) / pageSize) + 1;
+}
 var Pagination = function Pagination(props) {
   var show = useMemo(function () {
     return Object.keys(props).length;
   }, [props]);
   var isMiniPagination = useIsMobileTable();
-  var effectiveConfig = useMemo(function () {
+  var itemRenderFn = useMemo(function () {
     var prevText = getPaginationText('previous');
     var nextText = getPaginationText('next');
-    var showTotalFn = getPaginationText('showTotal');
-    var itemRenderFn = function itemRenderFn(_, type, originalElement) {
+    return function (_, type, originalElement) {
       if (type === 'prev') {
         return /*#__PURE__*/React.createElement("div", {
           className: classNames('paginator-page-btn', 'left')
@@ -56,20 +72,28 @@ var Pagination = function Pagination(props) {
       }
       return originalElement;
     };
-    var showTotal = typeof showTotalFn === 'function' ? function (total, range) {
-      return showTotalFn(range[0], range[1]);
-    } : function (total, range) {
-      return "Page ".concat(range[0], " of ").concat(range[1]);
-    };
+  }, []);
+  var showTotalDefault = useCallback(function (totalRecords, range) {
+    var _ref, _props$pageSize;
+    var pageSize = (_ref = (_props$pageSize = props.pageSize) !== null && _props$pageSize !== void 0 ? _props$pageSize : props.defaultPageSize) !== null && _ref !== void 0 ? _ref : 10;
+    var currentPage = resolveCurrentPage(props, range, pageSize);
+    var totalPages = totalRecords <= 0 ? 1 : Math.max(1, Math.ceil(totalRecords / pageSize));
+    var showTotalFn = getPaginationText('showTotal');
+    if (typeof showTotalFn === 'function') {
+      return showTotalFn(currentPage, totalPages);
+    }
+    return "Page ".concat(currentPage, " of ").concat(totalPages);
+  }, [props.current, props.defaultCurrent, props.pageSize, props.defaultPageSize]);
+  var effectiveConfig = useMemo(function () {
     return {
       className: 'materials-grid-paginator',
       defaultCurrent: 1,
-      showTotal: showTotal,
+      showTotal: showTotalDefault,
       itemRender: itemRenderFn,
       responsive: true,
       size: 'small'
     };
-  }, []);
+  }, [itemRenderFn, showTotalDefault]);
   var content = useMemo(function () {
     if (!show) {
       return null;
@@ -85,18 +109,28 @@ var Pagination = function Pagination(props) {
 export var paginationConfig = {
   className: 'materials-grid-paginator',
   defaultCurrent: 1,
-  showTotal: function showTotal(total, range) {
-    return "Page ".concat(range[0], " of ").concat(range[1]);
+  /** 无 props 上下文时仅能根据 total + range 近似推算（见 resolveCurrentPage） */
+  showTotal: function showTotal(totalRecords, range) {
+    var pageSize = 10;
+    var currentPage = resolveCurrentPage({
+      pageSize: pageSize
+    }, range, pageSize);
+    var totalPages = totalRecords <= 0 ? 1 : Math.max(1, Math.ceil(totalRecords / pageSize));
+    var fn = getPaginationText('showTotal');
+    if (typeof fn === 'function') {
+      return fn(currentPage, totalPages);
+    }
+    return "Page ".concat(currentPage, " of ").concat(totalPages);
   },
   responsive: true,
   size: 'small'
 };
 export default Pagination;
 var MiniPagination = function MiniPagination(props) {
-  var _props$current = props.current,
-    current = _props$current === void 0 ? 1 : _props$current,
-    _props$pageSize = props.pageSize,
-    pageSize = _props$pageSize === void 0 ? 10 : _props$pageSize,
+  var _props$current2 = props.current,
+    current = _props$current2 === void 0 ? 1 : _props$current2,
+    _props$pageSize2 = props.pageSize,
+    pageSize = _props$pageSize2 === void 0 ? 10 : _props$pageSize2,
     _props$total = props.total,
     total = _props$total === void 0 ? 0 : _props$total;
 
@@ -163,13 +197,13 @@ var MiniPagination = function MiniPagination(props) {
     className: 'paginator-page-btn-right-icon'
   }))));
 };
-export var FormPagination = function FormPagination(_ref) {
-  var _ref$value = _ref.value,
-    value = _ref$value === void 0 ? {} : _ref$value,
-    onChange = _ref.onChange,
-    page = _ref.page,
-    pageSize = _ref.pageSize,
-    other = _objectWithoutProperties(_ref, _excluded);
+export var FormPagination = function FormPagination(_ref2) {
+  var _ref2$value = _ref2.value,
+    value = _ref2$value === void 0 ? {} : _ref2$value,
+    onChange = _ref2.onChange,
+    page = _ref2.page,
+    pageSize = _ref2.pageSize,
+    other = _objectWithoutProperties(_ref2, _excluded);
   var _useState = useState(page || 1),
     _useState2 = _slicedToArray(_useState, 2),
     _p = _useState2[0],

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

@@ -0,0 +1,13 @@
+/**
+ * PisellFloorMapLayout - 空间布局视图
+ * 支持两种用法：1) 仅传入 items + renderItem（原有用法）；2) 传入 floorMapConfig + dataSources + mode 使用平面图视图（含多画布/编辑态）
+ */
+import React from 'react';
+import type { FloorMapItemBase, PisellFloorMapLayoutProps, PisellFloorMapLayoutRef } from './types';
+import './PisellFloorMapLayout.less';
+/** 空间布局根组件：阅读/编辑、列表与平面图双模式，ref 见 {@link PisellFloorMapLayoutRef} */
+declare const PisellFloorMapLayout: <T extends FloorMapItemBase = FloorMapItemBase>(props: PisellFloorMapLayoutProps<T> & {
+    ref?: React.Ref<PisellFloorMapLayoutRef | null> | undefined;
+}) => React.ReactElement;
+export { PisellFloorMapLayout };
+export default PisellFloorMapLayout;

package/es/components/pisellFloorMapLayout/PisellFloorMapLayout.js

@@ -70,6 +70,7 @@ function PisellFloorMapLayoutInner(props, ref) {
     controls = _p$controls === void 0 ? {} : _p$controls,
     _p$enableHover = p.enableHover,
     enableHover = _p$enableHover === void 0 ? true : _p$enableHover,
+    readModeSelectedItemId = p.readModeSelectedItemId,
     onItemClick = p.onItemClick,
     onItemHover = p.onItemHover,
     onItemLeave = p.onItemLeave,
@@ -797,7 +798,8 @@ function PisellFloorMapLayoutInner(props, ref) {
       onItemHover: onItemHover,
       onItemLeave: onItemLeave,
       getMergedItemWrapperStyle: getMergedItemWrapperStyle,
-      onInteractionChange: setIsInteractingWithElement
+      onInteractionChange: setIsInteractingWithElement,
+      readModeSelectedItemId: readModeSelectedItemId
     }), isFloorMapView && mode === 'edit' && (placeMode === null || placeMode === void 0 ? void 0 : placeMode.type) === 'scene' && /*#__PURE__*/React.createElement("div", {
       className: placeOverlayClass,
       style: {

package/es/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 样式的圆桌卡片（顶部资源信息 chip + 圆形主体，圆形主体只展示状态相关内容） */
+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/es/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/es/components/pisellFloorMapLayout/components/FloorMapEditTopBar.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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;
+    /** 撤销当前编辑步骤（不传则不显示按钮） */
+    onUndo?: () => void;
+    /** 重做最近一次撤销（不传则不显示按钮） */
+    onRedo?: () => void;
+    /** 是否还有可撤销步骤 */
+    canUndo?: boolean;
+    /** 是否还有可重做步骤 */
+    canRedo?: boolean;
+    /**
+     * 退出编辑模式回调（不保存）。
+     * 传入后顶栏右侧会渲染「取消编辑」+「完成」两个按钮，替代原独立「保存」按钮：
+     * - 取消编辑 → `onCancelEdit?.() ?? onExitEdit()`
+     * - 完成 → `onSave?.()` + `onExitEdit()`
+     * 不传则维持旧版「保存」按钮（保存但不退出）。
+     */
+    onExitEdit?: () => void;
+    /**
+     * 「取消编辑」专用回调（可选）。传入时取消按钮优先调它，业务层可以在这里
+     * 完成「丢弃草稿 + 退出编辑」组合，从而保证回到阅读态不会看到未保存的脏数据。
+     * 不传时取消按钮回退到 `onExitEdit`。完成按钮链路不受此 prop 影响。
+     */
+    onCancelEdit?: () => void;
+    className?: string;
+}
+export declare function FloorMapEditTopBar(props: FloorMapEditTopBarProps): JSX.Element | null;
+export default FloorMapEditTopBar;

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