@pisell/materials 1.0.1059 → 1.0.1062

package/es/components/pisellFloorMapLayout/types.js

@@ -1 +1,148 @@
-export {};
+/**
+ * 资源项形状
+ * @description 展示层支持的基础形状
+ */
+
+/**
+ * 底层背景类型
+ * @description 地图底层的展示方式
+ */
+
+/**
+ * 平移边界策略
+ * @description 拖拽/手势平移时的边界行为
+ */
+
+/**
+ * 资源项坐标/尺寸单位
+ * - cell：x/y/width/height 为格子数，由 cellSize 转为像素
+ * - pixel：x/y/width/height 为像素
+ */
+
+/**
+ * 资源项基础类型
+ * @description 每个资源至少包含 id 与坐标 (x, y)，其余由外部扩展。
+ * 单位由布局的 itemUnit 决定：cell 时为格子数，pixel 时为像素。
+ */
+
+/**
+ * 底层（MapLayer）配置
+ */
+
+/**
+ * 缩放配置
+ */
+
+/**
+ * 平移配置
+ */
+
+/**
+ * 视图控制显隐（默认仅显示放大/缩小，复位与区域定位需配置开启）
+ */
+
+/**
+ * 布局模式（规则网格 vs 完全自由坐标）
+ */
+
+/**
+ * 规则网格布局配置（layoutMode 为 grid 时可用）
+ */
+
+// ---------- 方案：画布 / 图元 / 视图配置 ----------
+
+/** 图元类型：是否绑定业务资源 */
+
+/**
+ * 画布名称多语言结构（与低代码 Translation 字段一致）
+ */
+
+/** 画布（对应一个 Tab，如 1楼、2楼） */
+
+/** 文字槽位（编辑时在 SVG 上添加，阅读态通过参数传文案） */
+
+/** 地图图元：资源或装饰，编辑与阅读共用（name/zIndex 继承自 FloorMapItemBase） */
+
+/** 单门店 Floor Map 数据（编辑/阅读共用） */
+
+/** 多数据源：key 为数据源标识，value 为该数据源下的记录列表 */
+
+/**
+ * 画布图元与可选数据源行的绑定（无绑定时仅展示图元种类默认态）
+ */
+
+/**
+ * 画布上的单一图元实例（原 dataSourcePlacements + decorations 合并为同一结构）
+ */
+
+/**
+ * 矩形区域类装饰（无数据源绑定），如画布上的「舞台/舞池」等。
+ * 在 `elementKinds` 中配置 `{ value: 'stage', label: '…', showInPalette: true }`，名称在编辑面板「显示名称」中修改。
+ */
+export var FLOOR_MAP_STAGE_ELEMENT_KIND = 'stage';
+
+/**
+ * 图片图元：无数据源绑定，通过 `imageUrl` 展示位图；适合铺底图或与业务图元叠放（调 `zIndex`）。
+ */
+export var FLOOR_MAP_IMAGE_ELEMENT_KIND = 'floorMapImage';
+
+/** 图元是否接受数据源及是否必填 */
+
+/** 图元种类所属分类（调色板分组） */
+
+/** 无数据源行时的占位展示文案/扩展（与 defaultShape 等并列） */
+
+/** 图元间连线（边） */
+
+/** 图元种类配置（由后端或上层注入） */
+
+/**
+ * 画布/编辑器层能力：新建图元、布局与画布 Tab 的编辑权限
+ * @description 与 `canvases` 列表配合使用，统一挂在平面图配置的「画布 UI」下
+ */
+
+/** Floor Map 视图配置（仅平面图视图需要持久化） */
+
+/** 编辑态：选中图元种类后的放置模式（点击画布落点） */
+
+/** 阅读态 renderItem 可选第三参数 */
+
+/** 数据源记录表单列配置（用于编辑面板中的「数据源记录」区块） */
+
+/**
+ * 自定义「数据源记录」表单（ReactNode 或 render prop）可用的上下文
+ * @description 与内置 {@link FloorMapDataForm} 数据源一致，便于复杂表单、多步校验、联动等
+ */
+
+/**
+ * 按 dataSourceKey 替换「数据源记录」区块的表单内容：静态节点或通过 context 渲染
+ */
+
+/** 选中图元后编辑面板参数 */
+
+/**
+ * 合并当前画布的 sceneElements 为 items（用于 Layout 渲染）
+ */
+
+/**
+ * 平面图编辑态全屏 UI 策略（`floorMapFullscreenMode`）
+ *
+ * - **toggle**（默认）：顶栏提供进入/退出全屏，与浏览器 Fullscreen API 联动
+ * - **locked**：始终使用全屏顶栏（Tab + 保存等），**不提供退出全屏**；适合外层遮罩铺满
+ * - **disabled**：**不提供全屏按钮**，仅小屏顶栏 + 侧栏保存
+ */
+
+/**
+ * 平面图 Layout 注入上下文：数据、保存、侧栏表单与状态等（不包含 renderItem/mapLayer 等展示向 props）。
+ * 由 `FloorMapLayoutProvider` / RecordBoard `floorMapLayoutContext` 提供，与 `PisellFloorMapLayout` props 按 `??` 合并，props 优先。
+ */
+
+/**
+ * PisellFloorMapLayout 组件 Props
+ * @template T - 资源项类型，需继承 FloorMapItemBase 或兼容 id/x/y
+ */
+
+/**
+ * PisellFloorMapLayout Ref 方法
+ * @description 供外部调用缩放、复位、区域定位等
+ */

package/es/components/pisellFloorMapLayout/utils/floorMapCanvasDisplay.d.ts

@@ -0,0 +1,20 @@
+import type { FloorMapCanvas, FloorMapCanvasNameI18n } from '../types';
+/**
+ * 合并平面图 Tab 用多语言包（与业务侧 `locales.init` 可叠加）。
+ */
+export declare function initFloorMapLayoutLocales(engineLocale: string): void;
+/**
+ * 从多语言对象中取当前 locale 下展示字符串，缺省按 en → 其余首个非空。
+ */
+export declare function pickFloorMapCanvasI18nString(obj: FloorMapCanvasNameI18n, engineLocale: string): string;
+/**
+ * 画布在 Tab / 下拉中的展示名：
+ * 1. `name` 为多语言对象时 **优先** 按引擎 locale 取字段（与配置内嵌文案一致）；
+ * 2. 否则 `nameKey` + `locales.getText`（需业务侧已 init 对应语言包）；
+ * 3. 否则 `name` 字符串。
+ */
+export declare function getFloorMapCanvasDisplayName(canvas: FloorMapCanvas, engineLocale: string): string;
+/**
+ * 打开重命名弹层时的初始多语言值（与 Translation 表单一致）。
+ */
+export declare function seedFloorMapCanvasNameI18n(canvas: FloorMapCanvas, displayFallback: string): FloorMapCanvasNameI18n;

package/es/components/pisellFloorMapLayout/utils/floorMapCanvasDisplay.js

@@ -0,0 +1,129 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+import { locales } from '@pisell/utils';
+import floorMapLayoutLocales from "../locales";
+import { createTranslationText } from "../../translation/utils";
+
+/**
+ * 合并平面图 Tab 用多语言包（与业务侧 `locales.init` 可叠加）。
+ */
+export function initFloorMapLayoutLocales(engineLocale) {
+  locales.init(floorMapLayoutLocales, engineLocale);
+}
+var I18N_LOCALE_ORDER = ['en', 'zh-CN', 'zh-HK', 'ja', 'pt'];
+
+/**
+ * 引擎 locale 与画布 name 对象字段对齐（如 en-US → en、zh_CN → zh-CN）。
+ */
+function localeKeysToTryForCanvasName(engineLocale) {
+  var out = [];
+  var push = function push(k) {
+    if (!out.includes(k)) out.push(k);
+  };
+  push(engineLocale);
+  if (engineLocale === 'en-US' || engineLocale === 'en-GB') {
+    push('en');
+  }
+  if (engineLocale === 'zh_CN' || engineLocale === 'zh') {
+    push('zh-CN');
+  }
+  var _iterator = _createForOfIteratorHelper(I18N_LOCALE_ORDER),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var k = _step.value;
+      push(k);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return out;
+}
+
+/**
+ * 从多语言对象中取当前 locale 下展示字符串，缺省按 en → 其余首个非空。
+ */
+export function pickFloorMapCanvasI18nString(obj, engineLocale) {
+  var _iterator2 = _createForOfIteratorHelper(localeKeysToTryForCanvasName(engineLocale)),
+    _step2;
+  try {
+    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+      var loc = _step2.value;
+      var _v = obj[loc];
+      if (typeof _v === 'string' && _v.trim()) return _v.trim();
+    }
+  } catch (err) {
+    _iterator2.e(err);
+  } finally {
+    _iterator2.f();
+  }
+  for (var _i = 0, _Object$values = Object.values(obj); _i < _Object$values.length; _i++) {
+    var v = _Object$values[_i];
+    if (typeof v === 'string' && v.trim()) return v.trim();
+  }
+  return '';
+}
+function isCanvasNameI18nObject(n) {
+  if (!n || _typeof(n) !== 'object' || Array.isArray(n)) return false;
+  var o = n;
+  var _iterator3 = _createForOfIteratorHelper(I18N_LOCALE_ORDER),
+    _step3;
+  try {
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var k = _step3.value;
+      if (typeof o[k] === 'string') return true;
+    }
+  } catch (err) {
+    _iterator3.e(err);
+  } finally {
+    _iterator3.f();
+  }
+  return false;
+}
+
+/**
+ * 画布在 Tab / 下拉中的展示名：
+ * 1. `name` 为多语言对象时 **优先** 按引擎 locale 取字段（与配置内嵌文案一致）；
+ * 2. 否则 `nameKey` + `locales.getText`（需业务侧已 init 对应语言包）；
+ * 3. 否则 `name` 字符串。
+ */
+export function getFloorMapCanvasDisplayName(canvas, engineLocale) {
+  initFloorMapLayoutLocales(engineLocale);
+  var n = canvas.name;
+  if (isCanvasNameI18nObject(n)) {
+    var fromObj = pickFloorMapCanvasI18nString(n, engineLocale);
+    if (fromObj) return fromObj;
+  }
+  if (canvas.nameKey) {
+    var t = locales.getText(canvas.nameKey);
+    if (t !== canvas.nameKey) return t;
+  }
+  if (typeof n === 'string') return n;
+  if (n && _typeof(n) === 'object' && !Array.isArray(n)) {
+    return pickFloorMapCanvasI18nString(n, engineLocale);
+  }
+  return '';
+}
+
+/**
+ * 打开重命名弹层时的初始多语言值（与 Translation 表单一致）。
+ */
+export function seedFloorMapCanvasNameI18n(canvas, displayFallback) {
+  var n = canvas.name;
+  if (n && _typeof(n) === 'object') {
+    var _n$en, _n$zhCN, _n$zhHK, _n$ja, _n$pt;
+    return {
+      en: (_n$en = n.en) !== null && _n$en !== void 0 ? _n$en : '',
+      'zh-CN': (_n$zhCN = n['zh-CN']) !== null && _n$zhCN !== void 0 ? _n$zhCN : '',
+      'zh-HK': (_n$zhHK = n['zh-HK']) !== null && _n$zhHK !== void 0 ? _n$zhHK : '',
+      ja: (_n$ja = n.ja) !== null && _n$ja !== void 0 ? _n$ja : '',
+      pt: (_n$pt = n.pt) !== null && _n$pt !== void 0 ? _n$pt : ''
+    };
+  }
+  var s = typeof n === 'string' && n.trim() ? n.trim() : displayFallback;
+  return createTranslationText(s, true);
+}

package/es/components/pisellFloorMapLayout/utils/floorMapConfigMerge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 将当前画布的 sceneElements 合并为 Layout 使用的 FloorMapMergedItem[]
+ */
+import type { FloorMapViewConfig, FloorMapMergedItem } from '../types';
+/**
+ * 合并指定画布下的 sceneElements 为一份 items（用于 ItemLayer / EditableItemLayer）
+ */
+export declare function mergeCanvasItems(canvasId: string, config: Pick<FloorMapViewConfig, 'sceneElements' | 'elementKinds'>, defaultCellSize?: number): FloorMapMergedItem[];

package/es/components/pisellFloorMapLayout/utils/floorMapConfigMerge.js

@@ -0,0 +1,87 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+/**
+ * 将当前画布的 sceneElements 合并为 Layout 使用的 FloorMapMergedItem[]
+ */
+
+import { FLOOR_MAP_IMAGE_ELEMENT_KIND } from "../types";
+import { getElementKindConfig } from "./floorMapElementKindUtils";
+var DEFAULT_SIZE = 48;
+var IMAGE_KIND_DEFAULT_SIZE = {
+  width: 400,
+  height: 240
+};
+function getDefaultSize(elementKind, elementKinds) {
+  if (!elementKind) return {
+    width: DEFAULT_SIZE,
+    height: DEFAULT_SIZE
+  };
+  if (elementKind === FLOOR_MAP_IMAGE_ELEMENT_KIND) {
+    return _objectSpread({}, IMAGE_KIND_DEFAULT_SIZE);
+  }
+  var found = elementKinds.find(function (k) {
+    return k.value === elementKind;
+  });
+  if (!found) return {
+    width: DEFAULT_SIZE,
+    height: DEFAULT_SIZE
+  };
+  return {
+    width: DEFAULT_SIZE,
+    height: DEFAULT_SIZE
+  };
+}
+
+/**
+ * 合并指定画布下的 sceneElements 为一份 items（用于 ItemLayer / EditableItemLayer）
+ */
+export function mergeCanvasItems(canvasId, config) {
+  var defaultCellSize = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : DEFAULT_SIZE;
+  var _config$sceneElements = config.sceneElements,
+    sceneElements = _config$sceneElements === void 0 ? [] : _config$sceneElements,
+    _config$elementKinds = config.elementKinds,
+    elementKinds = _config$elementKinds === void 0 ? [] : _config$elementKinds;
+  var items = [];
+  var onCanvas = sceneElements.filter(function (el) {
+    return el.canvasId === canvasId;
+  });
+  var _iterator = _createForOfIteratorHelper(onCanvas),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var _ref, _el$width, _ref2, _el$height, _el$shape;
+      var el = _step.value;
+      var size = getDefaultSize(el.elementKind, elementKinds);
+      var w = (_ref = (_el$width = el.width) !== null && _el$width !== void 0 ? _el$width : size.width) !== null && _ref !== void 0 ? _ref : defaultCellSize;
+      var h = (_ref2 = (_el$height = el.height) !== null && _el$height !== void 0 ? _el$height : size.height) !== null && _ref2 !== void 0 ? _ref2 : defaultCellSize;
+      var kindConfig = getElementKindConfig({
+        elementKinds: elementKinds
+      }, el.elementKind);
+      items.push({
+        id: el.instanceId,
+        instanceId: el.instanceId,
+        x: el.x,
+        y: el.y,
+        width: w,
+        height: h,
+        name: el.name,
+        zIndex: el.zIndex,
+        shape: (_el$shape = el.shape) !== null && _el$shape !== void 0 ? _el$shape : kindConfig === null || kindConfig === void 0 ? void 0 : kindConfig.defaultShape,
+        elementKind: el.elementKind,
+        _sceneElement: el
+      });
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return items;
+}

package/es/components/pisellFloorMapLayout/utils/floorMapDropUtils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 平面图编辑态：侧栏图元拖拽到画布的 DataTransfer 与坐标
+ */
+/** 与 setData 一致，用于识别左侧图元栏发起的拖拽 */
+export declare const FLOOR_MAP_PALETTE_DRAG_MIME = "application/x-pisell-floor-map-element";
+export interface FloorMapPaletteDragPayload {
+    elementKind: string;
+    dataSourceKey?: string;
+    recordId?: string;
+}
+/**
+ * 与 {@link useFloorMapEditState} 落点一致：内容区 drop 的 offset 减去内容区 padding 偏移
+ */
+export declare function sceneXYFromContentDropOffset(offsetX: number, offsetY: number, contentOffset: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+};
+/** 是否为左侧图元栏拖拽（非本地文件 / 外链图片） */
+export declare function isFloorMapPaletteDrag(dt: DataTransfer | null): boolean;
+/**
+ * 解析侧栏拖拽 payload；非法时返回 null
+ */
+export declare function parsePaletteDragPayload(dt: DataTransfer): FloorMapPaletteDragPayload | null;

package/es/components/pisellFloorMapLayout/utils/floorMapDropUtils.js

@@ -0,0 +1,47 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+/**
+ * 平面图编辑态：侧栏图元拖拽到画布的 DataTransfer 与坐标
+ */
+
+/** 与 setData 一致，用于识别左侧图元栏发起的拖拽 */
+export var FLOOR_MAP_PALETTE_DRAG_MIME = 'application/x-pisell-floor-map-element';
+/**
+ * 与 {@link useFloorMapEditState} 落点一致：内容区 drop 的 offset 减去内容区 padding 偏移
+ */
+export function sceneXYFromContentDropOffset(offsetX, offsetY, contentOffset) {
+  return {
+    x: Math.round(offsetX - contentOffset.x),
+    y: Math.round(offsetY - contentOffset.y)
+  };
+}
+
+/** 是否为左侧图元栏拖拽（非本地文件 / 外链图片） */
+export function isFloorMapPaletteDrag(dt) {
+  var _dt$types;
+  if (!dt) return false;
+  return Array.from((_dt$types = dt.types) !== null && _dt$types !== void 0 ? _dt$types : []).includes(FLOOR_MAP_PALETTE_DRAG_MIME);
+}
+
+/**
+ * 解析侧栏拖拽 payload；非法时返回 null
+ */
+export function parsePaletteDragPayload(dt) {
+  try {
+    var raw = dt.getData(FLOOR_MAP_PALETTE_DRAG_MIME);
+    if (!raw) return null;
+    var o = JSON.parse(raw);
+    if (!o || _typeof(o) !== 'object') return null;
+    var rec = o;
+    var elementKind = rec.elementKind;
+    if (typeof elementKind !== 'string' || !elementKind) return null;
+    var dataSourceKey = typeof rec.dataSourceKey === 'string' ? rec.dataSourceKey : undefined;
+    var recordId = typeof rec.recordId === 'string' ? rec.recordId : undefined;
+    return {
+      elementKind: elementKind,
+      dataSourceKey: dataSourceKey,
+      recordId: recordId
+    };
+  } catch (_unused) {
+    return null;
+  }
+}

package/es/components/pisellFloorMapLayout/utils/floorMapElementKindUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 图元种类解析与绑定展示前校验（供合并项渲染、工具栏逻辑复用）
+ */
+import type { FloorMapElementKindConfig, FloorMapViewConfig, FloorMapSceneElement, FloorMapDataSources, FloorMapElementDataBindingPolicy } from '../types';
+/** dataBindingPolicy 缺省视为 none */
+export declare function resolveDataBindingPolicy(kind: FloorMapElementKindConfig | undefined): FloorMapElementDataBindingPolicy;
+export declare function getElementKindConfig(config: Pick<FloorMapViewConfig, 'elementKinds'> | undefined, elementKind: string | undefined): FloorMapElementKindConfig | undefined;
+/**
+ * @returns 人类可读错误文案；无问题时返回 null
+ */
+export declare function getSceneElementRenderIssue(element: FloorMapSceneElement, kind: FloorMapElementKindConfig | undefined, dataSources: FloorMapDataSources | undefined): string | null;

package/es/components/pisellFloorMapLayout/utils/floorMapElementKindUtils.js

@@ -0,0 +1,69 @@
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+/**
+ * 图元种类解析与绑定展示前校验（供合并项渲染、工具栏逻辑复用）
+ */
+
+/** dataBindingPolicy 缺省视为 none */
+export function resolveDataBindingPolicy(kind) {
+  var _kind$dataBindingPoli;
+  return (_kind$dataBindingPoli = kind === null || kind === void 0 ? void 0 : kind.dataBindingPolicy) !== null && _kind$dataBindingPoli !== void 0 ? _kind$dataBindingPoli : 'none';
+}
+export function getElementKindConfig(config, elementKind) {
+  var _config$elementKinds;
+  if (!elementKind || !(config !== null && config !== void 0 && (_config$elementKinds = config.elementKinds) !== null && _config$elementKinds !== void 0 && _config$elementKinds.length)) return undefined;
+  return config.elementKinds.find(function (k) {
+    return k.value === elementKind;
+  });
+}
+
+/**
+ * @returns 人类可读错误文案；无问题时返回 null
+ */
+export function getSceneElementRenderIssue(element, kind, dataSources) {
+  var policy = resolveDataBindingPolicy(kind);
+  var binding = element.dataBinding;
+  if (policy === 'required' && !binding) {
+    return '该图元须绑定数据源行';
+  }
+  if (!binding) return null;
+  var keys = kind === null || kind === void 0 ? void 0 : kind.allowedDataSourceKeys;
+  if (keys !== null && keys !== void 0 && keys.length && !keys.includes(binding.dataSourceKey)) {
+    return "\u6570\u636E\u6E90\u300C".concat(binding.dataSourceKey, "\u300D\u4E0D\u5728\u8BE5\u56FE\u5143\u5141\u8BB8\u5217\u8868\u5185");
+  }
+  var rows = dataSources === null || dataSources === void 0 ? void 0 : dataSources[binding.dataSourceKey];
+  var rid = binding.recordId != null ? String(binding.recordId).trim() : '';
+
+  /**
+   * 未选行、new_ 占位、或列表中已无该行：不在这里拦截，
+   * 交给 renderItemByKind（方桌/圆桌/蘸料等）使用统一的浅底虚线占位，避免只有红字无卡片感。
+   */
+  if (rid === '' || rid.startsWith('new_')) {
+    return null;
+  }
+  var row = rows === null || rows === void 0 ? void 0 : rows.find(function (r) {
+    return r.id === rid;
+  });
+  if (!row) {
+    return null;
+  }
+  var expected = kind === null || kind === void 0 ? void 0 : kind.expectedRecordFields;
+  if (expected !== null && expected !== void 0 && expected.length) {
+    var _iterator = _createForOfIteratorHelper(expected),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var f = _step.value;
+        if (row[f] === undefined || row[f] === null || row[f] === '') {
+          return "\u6570\u636E\u884C\u7F3A\u5C11\u5FC5\u586B\u5B57\u6BB5\uFF1A".concat(f);
+        }
+      }
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+  }
+  return null;
+}

package/es/components/pisellFloorMapLayout/utils/floorMapFallbackRender.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 无 renderItemByKind 时的占位渲染（装饰、舞台等），避免画布上不显示
+ */
+import React from 'react';
+import type { FloorMapMergedItem } from '../types';
+/**
+ * @returns 与 PisellFloorMapLayout 内联 fallback 一致的渲染函数（useCallback 由调用方包裹）
+ */
+/** 绑定校验失败或 renderItemByKind 抛错时的占位 */
+export declare function renderFloorMapRenderError(message: string): React.ReactNode;
+export declare function renderFloorMapFallbackPlaceholder(item: FloorMapMergedItem): React.ReactNode;

package/es/components/pisellFloorMapLayout/utils/floorMapFallbackRender.js

@@ -0,0 +1,88 @@
+/**
+ * 无 renderItemByKind 时的占位渲染（装饰、舞台等），避免画布上不显示
+ */
+import React from 'react';
+import { FLOOR_MAP_IMAGE_ELEMENT_KIND, FLOOR_MAP_STAGE_ELEMENT_KIND } from "../types";
+import { FloorMapImageElement } from "../components/FloorMapImageElement";
+import { STAGE_DECO_DEFAULT } from "./floorMapStageDefaults";
+
+/**
+ * @returns 与 PisellFloorMapLayout 内联 fallback 一致的渲染函数（useCallback 由调用方包裹）
+ */
+/** 绑定校验失败或 renderItemByKind 抛错时的占位 */
+export function renderFloorMapRenderError(message) {
+  return /*#__PURE__*/React.createElement("div", {
+    style: {
+      padding: 8,
+      fontSize: 12,
+      color: '#cf1322',
+      background: '#fff2f0',
+      border: '1px solid #ffccc7',
+      borderRadius: 4,
+      height: '100%',
+      boxSizing: 'border-box',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      textAlign: 'center',
+      wordBreak: 'break-word'
+    }
+  }, message);
+}
+export function renderFloorMapFallbackPlaceholder(item) {
+  var kind = (item === null || item === void 0 ? void 0 : item.elementKind) || 'item';
+  var isCircle = (item === null || item === void 0 ? void 0 : item.shape) === 'circle';
+  var isStage = kind === FLOOR_MAP_STAGE_ELEMENT_KIND;
+  var nameText = (item === null || item === void 0 ? void 0 : item.name) != null ? String(item.name).trim() : '';
+  var fallbackLabel = nameText || kind;
+  if (kind === FLOOR_MAP_IMAGE_ELEMENT_KIND) {
+    var _item$_sceneElement, _item$name, _item$_sceneElement2;
+    var url = (_item$_sceneElement = item._sceneElement) === null || _item$_sceneElement === void 0 ? void 0 : _item$_sceneElement.imageUrl;
+    return /*#__PURE__*/React.createElement(FloorMapImageElement, {
+      imageUrl: url,
+      name: (_item$name = item.name) !== null && _item$name !== void 0 ? _item$name : (_item$_sceneElement2 = item._sceneElement) === null || _item$_sceneElement2 === void 0 ? void 0 : _item$_sceneElement2.name
+    });
+  }
+  if (isStage) {
+    var display = nameText || STAGE_DECO_DEFAULT.name;
+    return /*#__PURE__*/React.createElement("div", {
+      style: {
+        width: '100%',
+        height: '100%',
+        boxSizing: 'border-box',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 8,
+        background: 'linear-gradient(180deg, #fafafa 0%, #ececec 100%)',
+        border: '2px dashed #595959',
+        borderRadius: 8,
+        fontSize: 15,
+        fontWeight: 600,
+        color: '#262626',
+        textAlign: 'center',
+        wordBreak: 'break-word',
+        lineHeight: 1.35,
+        overflow: 'hidden'
+      }
+    }, display);
+  }
+  return /*#__PURE__*/React.createElement("div", {
+    style: {
+      width: '100%',
+      height: '100%',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      background: '#f0f0f0',
+      border: '1px solid #d9d9d9',
+      borderRadius: isCircle ? '50%' : 4,
+      fontSize: 12,
+      color: '#666',
+      overflow: 'hidden',
+      padding: 4,
+      textAlign: 'center',
+      wordBreak: 'break-word'
+    }
+  }, fallbackLabel);
+}

package/es/components/pisellFloorMapLayout/utils/floorMapStageDefaults.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 舞台/区域类装饰：落点默认尺寸与默认显示名（与 FLOOR_MAP_STAGE_ELEMENT_KIND 配套）
+ */
+export declare const STAGE_DECO_DEFAULT: {
+    readonly width: 320;
+    readonly height: 120;
+    readonly name: "舞台";
+};