@pisell/materials 1.8.34 → 1.8.36

package/es/components/pisellFloorMapLayout/PisellFloorMapLayout.js

@@ -15,6 +15,7 @@ import { gapToPx } from "./utils/layoutMeasurements.js";
 import { useFloorMapEditState } from "./hooks/useFloorMapEditState.js";
 import { useFloorMapTransformMetrics } from "./hooks/useFloorMapTransformMetrics.js";
 import { renderFloorMapFallbackPlaceholder, renderFloorMapRenderError } from "./utils/floorMapFallbackRender.js";
+import { getFloorMapAppearanceTokens } from "./appearance/floorMapAppearance.js";
 import { useFloorMapPaletteTouchDrag } from "./hooks/useFloorMapPaletteTouchDrag.js";
 import { mergeCanvasesForTabs } from "./utils/mergeCanvasesForTabs.js";
 import { useFloorMapLayoutContext } from "./context/FloorMapLayoutContext.js";
@@ -36,8 +37,8 @@ import "./PisellFloorMapLayout.less";
 * 负责：上下文与 props 合并、编辑态/阅读态分支、Transform 视口、图元层与工具栏联动。
 */
 function PisellFloorMapLayoutInner(props, ref) {
-	var _engineCtx$engine, _config$sceneElements;
-	const { className, style, items: itemsProp, renderItem, rowKey, renderItemByKind, getMergedItemWrapperStyle, mapLayer, cellSize: cellSizeProp, itemUnit = "cell", zoom = {}, pan = {}, controls = {}, enableHover = true, readModeSelectedItemId, onItemClick, onItemHover, onItemLeave, mode = "read", floorMapConfig: floorMapConfigProp, dataSources, onSave, onExitEdit, onDataSourceRecordSave, dataSourceLabels, dataSourceFormColumns, dataSourceRecordForm, loading, saveError, onElementRenderError, toolbarShowSave = true, floorMapFullscreenMode, showDataSourceRecordFormBlock, floorMapViewportOverlay, viewportOverlayPlacement = "top-start", viewportOverlayClassName, canvasTabsBarTrailing, viewportDockTrailing, viewportPersist = true, viewportPersistNamespace } = mergeFloorMapLayoutPropsFromContext(props, useFloorMapLayoutContext());
+	var _ref, _currentCanvas$mapLay2, _currentCanvas$mapLay3, _engineCtx$engine, _config$sceneElements;
+	const { className, style, items: itemsProp, renderItem, rowKey, renderItemByKind, getMergedItemWrapperStyle, mapLayer, cellSize: cellSizeProp, itemUnit = "cell", zoom = {}, pan = {}, controls = {}, enableHover = true, readModeSelectedItemId, onItemClick, onItemHover, onItemLeave, mode = "read", floorMapConfig: floorMapConfigProp, dataSources, onSave, onExitEdit, onDataSourceRecordSave, dataSourceLabels, dataSourceFormColumns, dataSourceRecordForm, loading, saveError, onElementRenderError, toolbarShowSave = true, floorMapFullscreenMode, appearanceMode = "light", showDataSourceRecordFormBlock, floorMapViewportOverlay, viewportOverlayPlacement = "top-start", viewportOverlayClassName, canvasTabsBarTrailing, viewportDockToolButtons, viewportDockTrailing, viewportPersist = true, viewportPersistNamespace } = mergeFloorMapLayoutPropsFromContext(props, useFloorMapLayoutContext());
 	const { token } = theme.useToken();
 	const isFloorMapView = Boolean(floorMapConfigProp);
 	const contentOffsetRef = useRef({
@@ -62,6 +63,18 @@ function PisellFloorMapLayoutInner(props, ref) {
 		showDataSourceRecordFormBlock
 	});
 	/**
+	* 当前选中的画布配置：用于提取当前画布级 mapLayer 显式配置。
+	*/
+	const currentCanvas = useMemo(() => {
+		var _config$canvases$find;
+		if (!isFloorMapView || !config || !currentCanvasId) return null;
+		return (_config$canvases$find = config.canvases.find((canvas) => canvas.id === currentCanvasId)) !== null && _config$canvases$find !== void 0 ? _config$canvases$find : null;
+	}, [
+		isFloorMapView,
+		config,
+		currentCanvasId
+	]);
+	/**
 	* 「取消编辑」组合：先丢弃 draft（同步把 draftConfig replace 回上游 props 的值），
 	* 再调用业务侧 onExitEdit 退出编辑模式。
 	*
@@ -75,16 +88,16 @@ function PisellFloorMapLayoutInner(props, ref) {
 	}, [discardDraft, onExitEdit]);
 	/** 当前画布下的 mapLayer：全局 `mapLayer` 与画布级配置合并，供 MapLayer / 吸附等读取 */
 	const effectiveMapLayer = useMemo(() => {
-		var _canvas$mapLayer;
-		if (!isFloorMapView || !config || !currentCanvasId) return mapLayer;
-		const canvas = config.canvases.find((c) => c.id === currentCanvasId);
-		return _objectSpread2(_objectSpread2({}, mapLayer !== null && mapLayer !== void 0 ? mapLayer : {}), (_canvas$mapLayer = canvas === null || canvas === void 0 ? void 0 : canvas.mapLayer) !== null && _canvas$mapLayer !== void 0 ? _canvas$mapLayer : {});
+		var _currentCanvas$mapLay;
+		if (!isFloorMapView || !currentCanvas) return mapLayer;
+		return _objectSpread2(_objectSpread2({}, mapLayer !== null && mapLayer !== void 0 ? mapLayer : {}), (_currentCanvas$mapLay = currentCanvas.mapLayer) !== null && _currentCanvas$mapLay !== void 0 ? _currentCanvas$mapLay : {});
 	}, [
 		isFloorMapView,
-		config,
-		currentCanvasId,
+		currentCanvas,
 		mapLayer
 	]);
+	const appearanceTokens = useMemo(() => getFloorMapAppearanceTokens(appearanceMode), [appearanceMode]);
+	const canvasBackgroundColor = (_ref = (_currentCanvas$mapLay2 = currentCanvas === null || currentCanvas === void 0 || (_currentCanvas$mapLay3 = currentCanvas.mapLayer) === null || _currentCanvas$mapLay3 === void 0 ? void 0 : _currentCanvas$mapLay3.backgroundColor) !== null && _currentCanvas$mapLay2 !== void 0 ? _currentCanvas$mapLay2 : mapLayer === null || mapLayer === void 0 ? void 0 : mapLayer.backgroundColor) !== null && _ref !== void 0 ? _ref : appearanceTokens.fallbackCanvasBackgroundColor;
 	/**
 	* 必须与下方 TransformWrapper 的 `key` 完全一致。
 	* 远程/合并配置落地后 boundingPadding 等会变 → Wrapper 重挂载 → 若 autoFit 仍按旧「仅 canvasId」帧认为已 done，首屏会停在初始 transform；切换画布才因 id 变化再次 fit。
@@ -602,7 +615,7 @@ function PisellFloorMapLayoutInner(props, ref) {
 			wrapperStyle: {
 				width: "100%",
 				height: "100%",
-				backgroundColor: "#F2F4F7",
+				backgroundColor: canvasBackgroundColor,
 				overflow: "visible"
 			},
 			contentStyle: {
@@ -612,7 +625,7 @@ function PisellFloorMapLayoutInner(props, ref) {
 				minHeight: contentHeight,
 				position: "relative",
 				overflow: "visible",
-				backgroundColor: "#F2F4F7"
+				backgroundColor: canvasBackgroundColor
 			}
 		}, /* @__PURE__ */ React.createElement(MapLayer, {
 			config: effectiveMapLayer,
@@ -643,6 +656,7 @@ function PisellFloorMapLayoutInner(props, ref) {
 		}) : /* @__PURE__ */ React.createElement(ItemLayer, {
 			items,
 			renderItem: effectiveRenderItem,
+			viewportScale: scale,
 			rowKey,
 			cellSize,
 			itemUnit: effectiveItemUnit,
@@ -690,6 +704,7 @@ function PisellFloorMapLayoutInner(props, ref) {
 			viewportLocked,
 			onToggleViewportLock: isFloorMapView ? toggleViewportLocked : void 0,
 			dockChrome: isFloorMapView,
+			dockExpandedToolButtons: viewportDockToolButtons,
 			dockExpandedTrailing: viewportDockTrailing,
 			autoCollapseDockMs: 1e4
 		}), isFloorMapView && floorMapViewportOverlay != null ? /* @__PURE__ */ React.createElement("div", { className: classNames(`${FLOOR_MAP_LAYOUT_CLASS_PREFIX}-viewport-overlay`, { [`${FLOOR_MAP_LAYOUT_CLASS_PREFIX}-viewport-overlay--bottom-start`]: viewportOverlayPlacement === "bottom-start" }, viewportOverlayClassName) }, typeof floorMapViewportOverlay === "function" ? floorMapViewportOverlay({

package/es/components/pisellFloorMapLayout/appearance/floorMapAppearance.d.ts

@@ -0,0 +1,4 @@
+//#region src/components/pisellFloorMapLayout/appearance/floorMapAppearance.d.ts
+type FloorMapAppearanceMode = 'light' | 'dark';
+//#endregion
+export { FloorMapAppearanceMode };

package/es/components/pisellFloorMapLayout/appearance/floorMapAppearance.js

@@ -0,0 +1,22 @@
+import { _objectSpread2 } from "../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
+//#region src/components/pisellFloorMapLayout/appearance/floorMapAppearance.ts
+const FLOOR_MAP_APPEARANCE_TOKENS = {
+	light: {
+		mode: "light",
+		fallbackCanvasBackgroundColor: "#F2F4F7"
+	},
+	dark: {
+		mode: "dark",
+		fallbackCanvasBackgroundColor: "#31353d"
+	}
+};
+/**
+* 按外观模式返回 floorMap 画布背景 token。
+* 当前仅承载通用画布背景兜底色，不包含业务壳层颜色；
+* 渲染层应先尊重显式 `mapLayer.backgroundColor`，再回退到这里的 token。
+*/
+function getFloorMapAppearanceTokens(mode) {
+	return _objectSpread2({}, FLOOR_MAP_APPEARANCE_TOKENS[mode]);
+}
+//#endregion
+export { getFloorMapAppearanceTokens };

package/es/components/pisellFloorMapLayout/components/EditableItemLayer.js

@@ -238,7 +238,7 @@ function EditableItemLayer(props) {
 				}, shapeStyle), wrapperStyle), {}, { zIndex: isSelected ? SELECTED_ITEM_STACK_Z + ((_item$zIndex2 = item.zIndex) !== null && _item$zIndex2 !== void 0 ? _item$zIndex2 : 0) : baseZ }),
 				onPointerDown: (e) => handlePointerDown(e, item, index),
 				onClick: (e) => handleItemClick(e, item)
-			}, /* @__PURE__ */ React.createElement("div", { className: `${PREFIX}-editable-item-inner` }, renderItem(item, index)), isSelected && !isSceneLayoutTransformLocked(merged) && /* @__PURE__ */ React.createElement(React.Fragment, null, [
+			}, /* @__PURE__ */ React.createElement("div", { className: `${PREFIX}-editable-item-inner` }, renderItem(item, index, { viewportScale: scale })), isSelected && !isSceneLayoutTransformLocked(merged) && /* @__PURE__ */ React.createElement(React.Fragment, null, [
 				"nw",
 				"n",
 				"ne",
@@ -270,7 +270,8 @@ function EditableItemLayer(props) {
 		handleItemClick,
 		handleResizePointerDown,
 		getMergedItemWrapperStyle,
-		editQuickBar
+		editQuickBar,
+		scale
 	]);
 	return /* @__PURE__ */ React.createElement("div", {
 		ref: contentRef,

package/es/components/pisellFloorMapLayout/components/ItemLayer.js

@@ -31,7 +31,7 @@ function getShapeStyle(shape = "rect") {
 	}
 }
 function ItemLayer(props) {
-	const { items, renderItem, rowKey, cellSize, itemUnit = "cell", itemGap = 0, contentWidth, contentHeight, contentOffsetX = 0, contentOffsetY = 0, enableHover = true, itemHoverOutline = true, onItemClick, onItemHover, onItemLeave, getMergedItemWrapperStyle, onInteractionChange, readModeSelectedItemId, className } = props;
+	const { items, renderItem, viewportScale, rowKey, cellSize, itemUnit = "cell", itemGap = 0, contentWidth, contentHeight, contentOffsetX = 0, contentOffsetY = 0, enableHover = true, itemHoverOutline = true, onItemClick, onItemHover, onItemLeave, getMergedItemWrapperStyle, onInteractionChange, readModeSelectedItemId, className } = props;
 	/** 触控/指针在房间卡滚动区内按下时禁用画布 pan，松手恢复 */
 	const notifyRoomScrollSurfaceActive = useCallback(() => {
 		if (!onInteractionChange) return;
@@ -84,10 +84,12 @@ function ItemLayer(props) {
 	const itemNodes = useMemo(() => {
 		const isPixel = itemUnit === "pixel";
 		const g = itemGap;
-		return [...items].sort((a, b) => {
+		const sorted = [...items].sort((a, b) => {
 			var _a$zIndex, _b$zIndex;
 			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);
-		}).map((item, index) => {
+		});
+		const renderOpts = viewportScale != null && Number.isFinite(viewportScale) && viewportScale > 0 ? { viewportScale } : void 0;
+		return sorted.map((item, index) => {
 			var _item$zIndex, _item$zIndex2;
 			let left;
 			let top;
@@ -132,11 +134,12 @@ function ItemLayer(props) {
 				onMouseLeave: (e) => onItemLeave === null || onItemLeave === void 0 ? void 0 : onItemLeave(item, index, e),
 				onPointerDownCapture: handleItemPointerDownCapture,
 				onTouchStartCapture: handleItemTouchStartCapture
-			}, renderItem(item, index));
+			}, renderItem(item, index, renderOpts));
 		});
 	}, [
 		items,
 		renderItem,
+		viewportScale,
 		rowKey,
 		cellSize,
 		itemUnit,

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

@@ -27,3 +27,13 @@
     box-shadow: 0 0 0 1px rgba(22, 119, 255, 0.25);
   }
 }
+
+/**
+ * 房台小卡（tooltip-time）需要允许 tooltip 浮层越出格子边界。
+ * 仅在 item 内包含该类卡片时放开 overflow，避免影响其它图元定位/裁剪。
+ */
+.pisell-floor-map-layout-item:has(.pisell-res-floor-room-card[data-tooltip-time='on']),
+.pisell-floor-map-layout-item:has(.pisell-res-floor-room-card[data-reserved-halo='on']) {
+  overflow: visible;
+  z-index: 1;
+}

package/es/components/pisellFloorMapLayout/components/ViewControls.js

@@ -13,7 +13,7 @@ const PREFIX = "pisell-floor-map-layout";
 const I18N_VC = "pisell-floor-map-layout.view-controls";
 function ViewControls(props) {
 	var _config$horizontalAli;
-	const { api, config = {}, scale = 1, isFullscreen = false, fitBoundsActive = false, className, mapGridVisible = false, onToggleMapGrid, viewportLocked = false, onToggleViewportLock, dockChrome = false, dockExpandedTrailing, autoCollapseDockMs = 1e4 } = props;
+	const { api, config = {}, scale = 1, isFullscreen = false, fitBoundsActive = false, className, mapGridVisible = false, onToggleMapGrid, viewportLocked = false, onToggleViewportLock, dockChrome = false, dockExpandedToolButtons, dockExpandedTrailing, autoCollapseDockMs = 1e4 } = props;
 	const showZoom = config.showZoom !== false;
 	const showReset = config.showReset === true;
 	const showFitBounds = config.showFitBounds === true;
@@ -27,9 +27,10 @@ function ViewControls(props) {
 	const horizontalAlign = (_config$horizontalAli = config.horizontalAlign) !== null && _config$horizontalAli !== void 0 ? _config$horizontalAli : "start";
 	const scalePercent = Math.round(scale * 100);
 	const showTools = showReset || showFitBounds || showFullscreen || showGridToggle || showViewportLock;
+	const hasDockToolButtons = dockExpandedToolButtons != null && dockExpandedToolButtons !== false;
 	const hasTrailingSlot = dockExpandedTrailing != null && dockExpandedTrailing !== false;
-	const dockHasExpandable = dockChrome && (showTools || hasTrailingSlot);
-	const showBar = showZoom || showTools || dockChrome && hasTrailingSlot;
+	const dockHasExpandable = dockChrome && (showTools || hasDockToolButtons || hasTrailingSlot);
+	const showBar = showZoom || showTools || dockChrome && (hasDockToolButtons || hasTrailingSlot);
 	/**
 	* Dock：展开条是否拉宽（与 CSS max-width 过渡联动）。
 	* dockChrome 下 slide 内嵌合并 toggle 按钮，slide 始终 mounted；
@@ -156,13 +157,13 @@ function ViewControls(props) {
 		disabled: viewportLocked,
 		"aria-disabled": viewportLocked,
 		"aria-label": locales.getText(`${I18N_VC}.zoom-in-aria`)
-	}, /* @__PURE__ */ React.createElement(PlusOutlined, null))) : null, showZoom && (dockExpandedBarHasToolButtons || hasTrailingSlot) ? /* @__PURE__ */ React.createElement("div", {
+	}, /* @__PURE__ */ React.createElement(PlusOutlined, null))) : null, showZoom && (dockExpandedBarHasToolButtons || hasDockToolButtons || hasTrailingSlot) ? /* @__PURE__ */ React.createElement("div", {
 		className: `${PREFIX}-view-controls-bar-divider`,
 		"aria-hidden": true
 	}) : null, dockExpandedBarHasToolButtons ? renderToolButtons({
 		omitViewportLock: true,
 		omitFitBounds: true
-	}) : null, hasTrailingSlot ? /* @__PURE__ */ React.createElement("div", { className: `${PREFIX}-view-controls-dock-trailing` }, dockExpandedTrailing) : null);
+	}) : null, hasDockToolButtons ? dockExpandedToolButtons : null, hasTrailingSlot ? /* @__PURE__ */ React.createElement("div", { className: `${PREFIX}-view-controls-dock-trailing` }, dockExpandedTrailing) : null);
 	if (!showBar) return null;
 	/**
 	* dockChrome 屏右缘常驻按钮：「锁 / 全览」。两者都是单击操作，与展开条解耦。

package/es/components/pisellFloorMapLayout/components/ViewControls.less

@@ -233,7 +233,21 @@
       align-items: center;
     }
 
-    .pisell-floor-map-layout-view-controls-bar--dock > .pisell-floor-map-layout-view-controls-tool-btn {
+    .pisell-floor-map-layout-view-controls-bar--dock > .pisell-floor-map-layout-view-controls-tool-btn,
+    .pisell-floor-map-layout-view-controls-dock-trailing > .pisell-floor-map-layout-view-controls-tool-btn {
+      flex-shrink: 0;
+      box-sizing: border-box;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: 0;
+      margin: 0;
+      border: none;
+      background: transparent;
+      cursor: pointer;
+      color: #101828;
+      appearance: none;
+      vertical-align: middle;
       width: @dock-btn-size;
       min-width: @dock-btn-size;
       max-width: @dock-btn-size;
@@ -244,6 +258,18 @@
       font-size: @dock-icon-px;
       line-height: 0;
 
+      &:hover {
+        background: #f2f4f7;
+        color: #101828;
+      }
+
+      &:disabled,
+      &[aria-disabled='true'] {
+        background: transparent;
+        color: #d0d5dd;
+        cursor: not-allowed;
+      }
+
       .anticon,
       .pisell-lowcode-icon,
       span[role='img'] {
@@ -267,7 +293,8 @@
      * 展开条内激活态：与外侧折叠 pill（锁定 / 全览）同一套色，选择器挂在 bar--dock 上提高优先级，
      * 避免与其它 hover / 尺寸规则叠在一起时展开条观感发灰、与 pill 不一致。
      */
-    .pisell-floor-map-layout-view-controls-bar--dock > .pisell-floor-map-layout-view-controls-tool-btn--active {
+    .pisell-floor-map-layout-view-controls-bar--dock > .pisell-floor-map-layout-view-controls-tool-btn--active,
+    .pisell-floor-map-layout-view-controls-dock-trailing > .pisell-floor-map-layout-view-controls-tool-btn--active {
       .vc-tool-btn-active-colors();
     }
 

package/es/components/pisellFloorMapLayout/components/ViewControlsWithZoom.js

@@ -31,6 +31,7 @@ function ViewControlsWithZoom(props) {
 		viewportLocked: props.viewportLocked,
 		onToggleViewportLock: props.onToggleViewportLock,
 		dockChrome: props.dockChrome,
+		dockExpandedToolButtons: props.dockExpandedToolButtons,
 		dockExpandedTrailing: props.dockExpandedTrailing,
 		autoCollapseDockMs: props.autoCollapseDockMs
 	});

package/es/components/pisellFloorMapLayout/context/mergeFloorMapLayoutContext.js

@@ -4,7 +4,7 @@ import { _objectSpread2 } from "../../../_virtual/_@oxc-project_runtime@0.122.0/
 * 将 `FloorMapLayoutContext` 与 Layout props 合并：各字段 props ?? ctx，props 显式值优先。
 */
 function mergeFloorMapLayoutPropsFromContext(props, ctx) {
-	var _props$floorMapConfig, _props$dataSources, _props$onSave, _props$onDataSourceRe, _props$dataSourceLabe, _props$dataSourceForm, _props$dataSourceReco, _props$loading, _props$saveError, _props$onElementRende, _props$toolbarShowSav, _props$floorMapFullsc, _props$showDataSource, _props$viewportDockTr;
+	var _props$floorMapConfig, _props$dataSources, _props$onSave, _props$onDataSourceRe, _props$dataSourceLabe, _props$dataSourceForm, _props$dataSourceReco, _props$loading, _props$saveError, _props$onElementRende, _props$toolbarShowSav, _props$floorMapFullsc, _props$appearanceMode, _props$showDataSource, _props$viewportDockTo, _props$viewportDockTr;
 	if (ctx == null) return props;
 	return _objectSpread2(_objectSpread2({}, props), {}, {
 		floorMapConfig: (_props$floorMapConfig = props.floorMapConfig) !== null && _props$floorMapConfig !== void 0 ? _props$floorMapConfig : ctx.floorMapConfig,
@@ -19,7 +19,9 @@ function mergeFloorMapLayoutPropsFromContext(props, ctx) {
 		onElementRenderError: (_props$onElementRende = props.onElementRenderError) !== null && _props$onElementRende !== void 0 ? _props$onElementRende : ctx.onElementRenderError,
 		toolbarShowSave: (_props$toolbarShowSav = props.toolbarShowSave) !== null && _props$toolbarShowSav !== void 0 ? _props$toolbarShowSav : ctx.toolbarShowSave,
 		floorMapFullscreenMode: (_props$floorMapFullsc = props.floorMapFullscreenMode) !== null && _props$floorMapFullsc !== void 0 ? _props$floorMapFullsc : ctx.floorMapFullscreenMode,
+		appearanceMode: (_props$appearanceMode = props.appearanceMode) !== null && _props$appearanceMode !== void 0 ? _props$appearanceMode : ctx.appearanceMode,
 		showDataSourceRecordFormBlock: (_props$showDataSource = props.showDataSourceRecordFormBlock) !== null && _props$showDataSource !== void 0 ? _props$showDataSource : ctx.showDataSourceRecordFormBlock,
+		viewportDockToolButtons: (_props$viewportDockTo = props.viewportDockToolButtons) !== null && _props$viewportDockTo !== void 0 ? _props$viewportDockTo : ctx.viewportDockToolButtons,
 		viewportDockTrailing: (_props$viewportDockTr = props.viewportDockTrailing) !== null && _props$viewportDockTr !== void 0 ? _props$viewportDockTr : ctx.viewportDockTrailing
 	});
 }

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

@@ -1,3 +1,4 @@
+import { FloorMapAppearanceMode } from "./appearance/floorMapAppearance.js";
 import { CSSProperties, MouseEvent, ReactNode } from "react";
 
 //#region src/components/pisellFloorMapLayout/types.d.ts
@@ -51,7 +52,10 @@ interface FloorMapItemBase {
 interface FloorMapLayerConfig {
   /** 背景类型 */
   backgroundType?: FloorMapBackgroundType;
-  /** 纯色背景时的颜色（backgroundType 为 color 时有效） */
+  /**
+   * 纯色背景时的显式颜色（backgroundType 为 color 时有效）。
+   * 一旦配置，应优先于 `appearanceMode` 提供的画布背景兜底色。
+   */
   backgroundColor?: string;
   /** 图片背景 URL（backgroundType 为 image 时有效） */
   backgroundImage?: string;
@@ -318,6 +322,11 @@ interface FloorMapViewConfig {
 /** 阅读态 renderItem 可选第三参数 */
 interface FloorMapRenderOptions {
   textSlotValues?: Record<string, string>;
+  /**
+   * 平面图画布当前缩放（如 TransformWrapper 的 scale）。
+   * 用于房间内卡片等需按「视觉短边」降级密度时与布局像素相乘。
+   */
+  viewportScale?: number;
 }
 /** 数据源记录表单列配置（用于编辑面板中的「数据源记录」区块） */
 interface DataSourceFormColumn {
@@ -376,7 +385,7 @@ type FloorMapFullscreenMode = 'toggle' | 'locked' | 'disabled';
  * 平面图 Layout 注入上下文：数据、保存、侧栏表单与状态等（不包含 renderItem/mapLayer 等展示向 props）。
  * 由 `FloorMapLayoutProvider` / RecordBoard `floorMapLayoutContext` 提供，与 `PisellFloorMapLayout` props 按 `??` 合并，props 优先。
  */
-type FloorMapLayoutContextValue = Partial<Pick<PisellFloorMapLayoutProps<FloorMapItemBase>, 'floorMapConfig' | 'dataSources' | 'onSave' | 'onDataSourceRecordSave' | 'dataSourceLabels' | 'dataSourceFormColumns' | 'dataSourceRecordForm' | 'loading' | 'saveError' | 'onElementRenderError' | 'toolbarShowSave' | 'floorMapFullscreenMode' | 'showDataSourceRecordFormBlock' | 'viewportDockTrailing'>>;
+type FloorMapLayoutContextValue = Partial<Pick<PisellFloorMapLayoutProps<FloorMapItemBase>, 'floorMapConfig' | 'dataSources' | 'onSave' | 'onDataSourceRecordSave' | 'dataSourceLabels' | 'dataSourceFormColumns' | 'dataSourceRecordForm' | 'loading' | 'saveError' | 'onElementRenderError' | 'toolbarShowSave' | 'floorMapFullscreenMode' | 'appearanceMode' | 'showDataSourceRecordFormBlock' | 'viewportDockToolButtons' | 'viewportDockTrailing'>>;
 /**
  * PisellFloorMapLayout 组件 Props
  * @template T - 资源项类型，需继承 FloorMapItemBase 或兼容 id/x/y
@@ -486,6 +495,12 @@ interface PisellFloorMapLayoutProps<T extends FloorMapItemBase = FloorMapItemBas
   onItemLeave?: (item: T, index: number, event: MouseEvent<HTMLElement>) => void;
   /** 编辑态全屏按钮与顶栏形态，见 {@link FloorMapFullscreenMode} */
   floorMapFullscreenMode?: FloorMapFullscreenMode;
+  /**
+   * FloorMap 外观模式；当前仅提供画布背景兜底色。
+   * 若当前画布或根级 `mapLayer.backgroundColor` 显式传入颜色，应优先使用显式背景色。
+   * @default 'light'
+   */
+  appearanceMode?: FloorMapAppearanceMode;
   /**
    * 模式：read 仅展示，edit 可编辑；与 floorMapConfig 同时使用时生效
    */
@@ -540,6 +555,10 @@ interface PisellFloorMapLayoutProps<T extends FloorMapItemBase = FloorMapItemBas
    * 传入且阅读态仅单画布时仍会显示顶栏以便放置该插槽；全屏入口在左下 Dock（`viewportDockTrailing` 亦放 Dock，不占顶栏）。
    */
   canvasTabsBarTrailing?: ReactNode;
+  /**
+   * 视口左下角 Dock 展开区内、与缩放/网格等工具按钮平级的业务按钮插槽。
+   */
+  viewportDockToolButtons?: ReactNode;
   /**
    * 视口左下角 Dock 展开区业务插槽（与缩放/全屏同条），不占用顶栏 Tab 行；平面图模式推荐放「编辑画布」等。
    */

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

@@ -1,4 +1,4 @@
-import { DEFAULT_RESOURCE_WALL_LAYOUT_PERSIST, RecordBoardBlockedTimeMergedRange, RecordBoardBlockedTimePanelPayload, RecordBoardBodyView, RecordBoardBookingMoveDraft, RecordBoardCalendarBlockedTimePayload, RecordBoardCalendarBookingLike, RecordBoardCalendarBookingRenderArgs, RecordBoardCalendarDayOverlayBooking, RecordBoardCalendarProps, RecordBoardCalendarResource, RecordBoardCalendarResourceRenderArgs, RecordBoardCalendarSelectedFreeSlot, RecordBoardCalendarTimelineHeaderGroup, RecordBoardCalendarTimelineHeaderRenderContext, RecordBoardChildComponentProps, RecordBoardColumnFilterConfig, RecordBoardColumnType, RecordBoardContextValue, RecordBoardFieldType, RecordBoardFloorMapProps, RecordBoardGetOptions, RecordBoardGridProps, RecordBoardLayoutType, RecordBoardOptionItem, RecordBoardProps, RecordBoardResourceWallCardModel, RecordBoardResourceWallLayoutPersist, RecordBoardResourceWallProps, RecordBoardToolBarProps } from "./types.js";
+import { DEFAULT_RESOURCE_WALL_LAYOUT_PERSIST, RecordBoardBlockedTimeMergedRange, RecordBoardBlockedTimePanelPayload, RecordBoardBodyView, RecordBoardBookingMoveDraft, RecordBoardCalendarBlockedTimePayload, RecordBoardCalendarBookingLike, RecordBoardCalendarBookingRenderArgs, RecordBoardCalendarDayOverlayBooking, RecordBoardCalendarProps, RecordBoardCalendarResource, RecordBoardCalendarResourceRenderArgs, RecordBoardCalendarSelectedFreeSlot, RecordBoardCalendarTimelineHeaderGroup, RecordBoardCalendarTimelineHeaderRenderContext, RecordBoardChildComponentProps, RecordBoardColumnFilterConfig, RecordBoardColumnType, RecordBoardContextValue, RecordBoardCreateBookingDayGroup, RecordBoardCreateBookingFromSelectionPayload, RecordBoardFieldType, RecordBoardFloorMapProps, RecordBoardGetOptions, RecordBoardGridProps, RecordBoardLayoutType, RecordBoardOptionItem, RecordBoardProps, RecordBoardResourceWallCardModel, RecordBoardResourceWallLayoutPersist, RecordBoardResourceWallProps, RecordBoardToolBarProps } from "./types.js";
 import { RecordBoardGridView } from "./layouts/GridLayout/Grid.js";
 import { GridLayout } from "./layouts/GridLayout/index.js";
 import { RecordBoardCardList } from "./layouts/CardLayout/CardList.js";