@pisell/materials 6.11.223 → 6.11.225

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

@@ -0,0 +1,64 @@
+/**
+ * 拖动/缩放图元时的「边缘对齐吸附」：对照其他图元的 6 条候选线
+ * （左/中/右 + 上/中/下），如果当前 rect 的对应边距离它们小于
+ * 阈值（内容坐标），就把 rect 平移到精确贴合，并返回参考辅助线，
+ * 供画布上渲染红色对齐线。
+ *
+ * 阈值应保持小（典型 4~8 px / scale），避免吞掉正常拖动手感。
+ */
+export interface AlignSnapRect {
+    /** 用于排除自身。可为 undefined 表示参与对齐的"其他" rect */
+    id?: string;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export declare type AlignGuideEdgeX = 'left' | 'centerX' | 'right';
+export declare type AlignGuideEdgeY = 'top' | 'centerY' | 'bottom';
+export interface AlignGuide {
+    orientation: 'v' | 'h';
+    /** 该参考线所在坐标（v: x；h: y） */
+    position: number;
+    /** 沿参考线方向的覆盖范围 [min, max]，便于 SVG 渲染端到端 */
+    start: number;
+    end: number;
+    /** 命中的当前 rect 边 */
+    selfEdge: AlignGuideEdgeX | AlignGuideEdgeY;
+    /** 命中的对方 rect 边 */
+    otherEdge: AlignGuideEdgeX | AlignGuideEdgeY;
+    /** 命中的对方 rect id（如果有） */
+    otherId?: string;
+}
+export interface AlignSnapResult {
+    rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    guides: AlignGuide[];
+}
+/** 拖动模式：x/y 两轴可独立平移；不改尺寸 */
+export interface AlignSnapDragOptions {
+    mode: 'drag';
+    threshold: number;
+}
+/** 缩放模式：根据 handle 决定 left/right/top/bottom 哪条边可动 */
+export interface AlignSnapResizeOptions {
+    mode: 'resize';
+    threshold: number;
+    /** 哪些边在当前缩放手柄下「可动」 */
+    movableEdgesX?: ('left' | 'right')[];
+    movableEdgesY?: ('top' | 'bottom')[];
+}
+export declare type AlignSnapOptions = AlignSnapDragOptions | AlignSnapResizeOptions;
+/**
+ * 对一个 rect 做边对齐吸附。返回 snap 后的 rect + 实际命中的辅助线（0~2 条）。
+ *
+ * 算法：对 x、y 轴独立处理；每轴在所有「自身 3 边 × 所有 other 3 边」组合
+ * 中选距离最小且 < threshold 的一对，把自身整体平移让它们贴齐；同时记录
+ * 所有「平移后仍精确贴齐」的参考线（可能不止 1 条，例如 left 和 centerX
+ * 同时与他人对齐时只有 1 条平移量但 2 条 guide）。
+ */
+export declare function snapRectToOthers(rect: AlignSnapRect, others: AlignSnapRect[], options: AlignSnapOptions): AlignSnapResult;

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

@@ -0,0 +1,45 @@
+/** 批量落点时图元之间的间距（内容坐标 px） */
+export declare const BATCH_PLACE_GAP = 16;
+export interface BatchPlacementSize {
+    width: number;
+    height: number;
+}
+export interface BatchPlacementRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface BatchPlacementLayoutContext {
+    /** 当前画布已有图元（用于计算右侧锚点） */
+    existingElements: BatchPlacementRect[];
+    contentWidth: number;
+    contentHeight: number;
+    /** 与 mapLayer.boundingPadding 一致的单侧 padding */
+    boundingPadding?: number;
+}
+/**
+ * 行列数尽量接近正方形（复用全览网格算法）。
+ */
+export declare function getSquareishGridDims(count: number): {
+    cols: number;
+    rows: number;
+};
+/**
+ * 计算批量落点左上角坐标列表（行优先：先填满第一行再换行）。
+ */
+export declare function computeBatchScenePlacementPositions(sizes: BatchPlacementSize[], ctx: BatchPlacementLayoutContext): Array<{
+    x: number;
+    y: number;
+}>;
+export interface PlacementBoundingBox {
+    minLeft: number;
+    minTop: number;
+    maxRight: number;
+    maxBottom: number;
+}
+/** 由批量落点坐标与尺寸计算轴对齐包围盒（可加 margin 便于视口聚焦留边） */
+export declare function getPlacementBoundingBox(positions: Array<{
+    x: number;
+    y: number;
+}>, sizes: BatchPlacementSize[], margin?: number): PlacementBoundingBox | null;

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

@@ -0,0 +1,267 @@
+/**
+ * 拓扑连线：锚点坐标、自动选边、正交折线路径
+ */
+import type { FloorMapEdge, FloorMapEdgeAnchor, FloorMapEdgeRouting, FloorMapItemBase } from '../types';
+export interface FloorMapItemPixelRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface FloorMapEdgeRoute {
+    edgeId: string;
+    points: [number, number][];
+    pathD: string;
+}
+declare const ANCHORS: FloorMapEdgeAnchor[];
+/**
+ * 将图元逻辑坐标转为内容区像素矩形（与 EditableItemLayer 一致）
+ */
+export declare function getItemPixelRect<T extends FloorMapItemBase>(item: T, options: {
+    cellSize: number;
+    itemUnit: 'cell' | 'pixel';
+    itemGap?: number;
+    override?: Partial<FloorMapItemPixelRect>;
+}): FloorMapItemPixelRect;
+export declare function rectCenter(rect: FloorMapItemPixelRect): {
+    x: number;
+    y: number;
+};
+/**
+ * 锚点在矩形边框上的坐标
+ */
+export declare function getAnchorPoint(rect: FloorMapItemPixelRect, anchor: FloorMapEdgeAnchor): {
+    x: number;
+    y: number;
+};
+/** 与 EdgeLayer 端口标签 pill 高度一致 */
+export declare const EDGE_PORT_LABEL_HEIGHT = 18;
+/** 标签中心相对边框锚点的外移间距（px） */
+export declare const EDGE_PORT_LABEL_OFFSET_GAP = 6;
+/**
+ * 编辑态连线锚点圆点外移距离（px），避开 EditableItemLayer 边中点 20×20 缩放手柄。
+ */
+export declare const EDGE_PORT_MARKER_OUTSET = 16;
+/** 折线绕开图元矩形的间距（px） */
+export declare const EDGE_ROUTE_RECT_CLEARANCE = 10;
+/**
+ * 编辑态锚点圆点 UI 位置（相对图元局部坐标），沿外法线外移，连线几何仍用 {@link getAnchorPoint}。
+ */
+export declare function getPortMarkerDisplayPoint(rect: FloorMapItemPixelRect, anchor: FloorMapEdgeAnchor, outset?: number): {
+    x: number;
+    y: number;
+};
+export declare function getPortLabelPosition(rect: FloorMapItemPixelRect, anchor: FloorMapEdgeAnchor, options?: {
+    labelHeight?: number;
+    gap?: number;
+}): {
+    x: number;
+    y: number;
+};
+/** 折线中段连接类型标签相对路径的默认外偏移（px） */
+export declare const EDGE_CENTER_LABEL_OFFSET = 8;
+export declare type EdgeCenterLabelPlacement = 'middle' | 'target-tail' | 'source-tail' | 'longest-horizontal';
+/** 与 EdgeLayer PortLabel 估算宽度一致 */
+export declare function estimateEdgeLabelWidth(text: string): number;
+/**
+ * 在折线指定段上计算标签中心（水平段：标签在线上方；竖直段：标签在线左侧）。
+ */
+export declare function getEdgeCenterLabelPositionOnSegment(points: [number, number][], segIndex: number, options?: {
+    along?: number;
+    offsetPx?: number;
+    perpOffsetPx?: number;
+}): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * 计算边 `label`（如 connection_type）在正交折线上的显示位置。
+ * 默认 `target-tail`：靠近路径末端（目标端），避免标在水平总线中段互相重叠。
+ */
+export declare function getEdgeCenterLabelPosition(points: [number, number][], options?: {
+    placement?: EdgeCenterLabelPlacement;
+    offsetPx?: number;
+    /** 0–1，沿标签所在段的位置 */
+    along?: number;
+    /** 垂直于段的额外偏移（水平段：y 方向；竖直段：x 方向，正数向左） */
+    perpOffsetPx?: number;
+    /** 指定段索引；缺省时由 placement 推导 */
+    segIndex?: number;
+}): {
+    x: number;
+    y: number;
+} | null;
+/** 标签防碰撞：中心点最小间距（px，约等于 pill 高度 + 间距） */
+export declare const EDGE_CENTER_LABEL_MIN_GAP = 22;
+export interface ResolveEdgeCenterLabelItem {
+    edgeId: string;
+    sourceId: string;
+    targetId: string;
+    points: [number, number][];
+    label?: string;
+}
+/**
+ * 为多条边的连接类型标签分配互不重叠的位置。
+ * - 多边汇入同一目标：优先标在各自「水平总线」段中点（天然错开）
+ * - 仍重叠时按 pill 宽高做 bbox 分离；必要时在目标图元左侧纵向堆叠
+ */
+export declare function resolveEdgeCenterLabelPositions(items: ResolveEdgeCenterLabelItem[], options?: {
+    placement?: EdgeCenterLabelPlacement;
+    offsetPx?: number;
+    rectsById?: Map<string, FloorMapItemPixelRect>;
+}): Map<string, {
+    x: number;
+    y: number;
+}>;
+/**
+ * 未指定锚点时，选朝向对方最近的一侧
+ */
+export declare function pickAutoAnchor(from: FloorMapItemPixelRect, to: FloorMapItemPixelRect): FloorMapEdgeAnchor;
+/** 拉线吸附端口时的命中半径（与 {@link EDGE_PORT_MARKER_OUTSET} 同量级） */
+export declare const EDGE_PORT_SNAP_THRESHOLD = 16;
+export interface DrawingTargetHit {
+    instanceId: string;
+    anchor: FloorMapEdgeAnchor;
+}
+/**
+ * 距矩形四边锚点最近的一侧
+ */
+export declare function pickNearestAnchorOnRect(pt: {
+    x: number;
+    y: number;
+}, rect: FloorMapItemPixelRect): FloorMapEdgeAnchor;
+/**
+ * 拉线过程中解析目标：优先吸附到端口圆点，否则落在图元内时取最近端口。
+ */
+export declare function resolveDrawingTargetAtPoint(pt: {
+    x: number;
+    y: number;
+}, instanceIds: string[], rectsById: Map<string, FloorMapItemPixelRect>, excludeInstanceId: string, snapThreshold?: number): DrawingTargetHit | null;
+/** 折线是否有线段穿过矩形内部 */
+export declare function pathCrossesRectInterior(points: [number, number][], rect: FloorMapItemPixelRect): boolean;
+export interface RouteOrthogonalOptions {
+    /** 需要绕开的图元矩形（通常为对端节点） */
+    obstacleRects?: FloorMapItemPixelRect[];
+    clearance?: number;
+    /** @deprecated 使用 obstacleRects；保留兼容，等价于 [targetRect] */
+    sourceRect?: FloorMapItemPixelRect;
+    targetRect?: FloorMapItemPixelRect;
+    /**
+     * 通道偏移（px，带符号）：用于让多条共享同一通道的连线错开，避免视觉重叠。
+     * 影响 Z 型中点（midX/midY）与外侧公共通道（above/below/left/right）。
+     */
+    channelOffset?: number;
+}
+/**
+ * 正交连线：先最短路径，再对穿框段绕一圈。
+ */
+export declare function routeOrthogonal(sourcePt: {
+    x: number;
+    y: number;
+}, sourceSide: FloorMapEdgeAnchor, targetPt: {
+    x: number;
+    y: number;
+}, targetSide: FloorMapEdgeAnchor, 
+/** @deprecated 已取消固定 stub；可传 number（忽略）或 RouteOrthogonalOptions */
+stubOrOptions?: number | RouteOrthogonalOptions, maybeOptions?: RouteOrthogonalOptions): [number, number][];
+/**
+ * 折线转带圆角的 SVG path d
+ */
+export declare function pathFromPoints(points: [number, number][], radius?: number): string;
+export interface BuildEdgeRouteOptions {
+    /** 共享通道时的横向/纵向错位偏移 */
+    channelOffset?: number;
+    /** 用户手动调整后的路由覆盖；优先于 edge.routing 字段 */
+    routingOverride?: FloorMapEdgeRouting;
+}
+/**
+ * 把一条已存在的 path 快照（snapshot）的两端「平移对齐」到新的源/目标锚点位置，
+ * 中间路径完全保留。用于「手动编辑过的连线」在图元被拖动后只更新最近两端。
+ *
+ * 规则：
+ * - 首段（snapshot[0] → snapshot[1]）：
+ *   - 若是水平段（y0 === y1）：新 snapshot[0] = srcPt；新 snapshot[1] = (原 snapshot[1].x, srcPt.y)
+ *   - 若是竖直段（x0 === x1）：新 snapshot[0] = srcPt；新 snapshot[1] = (srcPt.x, 原 snapshot[1].y)
+ *   - 若是斜段（理论上 snapshot 都是正交，但兜底）：仅平移 snapshot[0]，snapshot[1] 保持不变
+ * - 末段（snapshot[n-2] → snapshot[n-1]）：对称处理
+ * - 同时对 snapshot[2] / snapshot[n-3] 做"必要的轴向跟随"：snapshot[1] → snapshot[2] 段必须保持
+ *   正交，因此 snapshot[2] 的相邻轴坐标需要跟随 snapshot[1] 更新（同理末端）。
+ */
+export declare function alignSnapshotToAnchors(snapshot: [number, number][], srcPt: {
+    x: number;
+    y: number;
+}, tgtPt: {
+    x: number;
+    y: number;
+}): [number, number][];
+/**
+ * 将「中段坐标覆盖」应用到一条正交折线 path 上。
+ *
+ * 内部段（既非首段也非末段）按顺序对应 `midSegmentPositions[k]`。
+ * - 水平段（y1 === y2）→ 把 result[i].y / result[i+1].y 都改成 v
+ * - 竖直段（x1 === x2）→ 把 result[i].x / result[i+1].x 都改成 v
+ *
+ * 移动一个内部段只是平移它的主轴坐标，相邻段（必是另一个方向）会随之延长/缩短，
+ * 不会破坏正交性。多余的 override 项被忽略，null/undefined 项跳过。
+ */
+/** 首/末段拖动后默认插入的 stub 长度（px）；过短时按段长 50% 自动缩小 */
+export declare const DEFAULT_EDGE_STUB_LENGTH = 24;
+/**
+ * 在路径起点处插入 stub 转角：把首段变成「沿首段实际方向走 stub → 90° 转弯 →
+ * 走到原 corner」。
+ *
+ * 注意：方向取自 *path 首段实际指向*（points[0]→points[1]），而非 sourceAnchor 字段——
+ * 这样在 path 已经经过手动编辑、首段方向与锚点 outward 不一致时仍能正确插入。
+ *
+ * 路径点数 +2；新增 2 个内部段（stub 段 + 「被拖动段」）。被拖动段的初始另一轴
+ * 坐标与原首段重合（视觉直线），后续由拖动调整。
+ */
+export declare function applySourceStub(points: [number, number][], stubLength: number | undefined, 
+/** @deprecated 仅向后兼容，实际方向由 path 首段决定 */
+sourceAnchor?: FloorMapEdgeAnchor): [number, number][];
+/**
+ * 对称地在路径末端插入 stub 转角。方向取自 *path 末段实际指向*。
+ *
+ * 路径点数 +2；新增 2 个内部段（「被拖动段」 + stub 段）。
+ */
+export declare function applyTargetStub(points: [number, number][], stubLength: number | undefined, 
+/** @deprecated 仅向后兼容，实际方向由 path 末段决定 */
+targetAnchor?: FloorMapEdgeAnchor): [number, number][];
+export declare function applyMidSegmentOverrides(points: [number, number][], overrides: (number | null | undefined)[] | undefined): [number, number][];
+/**
+ * 返回正交折线中所有「内部段」的元信息（不含首段与末段），
+ * 供 UI 渲染中段手柄使用。
+ */
+export interface EdgeInnerSegmentInfo {
+    /** 该内部段在 `midSegmentPositions` 中的索引（0 = path 的第 2 段） */
+    index: number;
+    /** path.points 中该段起点的下标（终点为 i+1） */
+    pointIndex: number;
+    axis: 'h' | 'v';
+    /** 段的主轴坐标：水平段 = y，竖直段 = x */
+    position: number;
+    /** 段中点坐标（用于摆放手柄） */
+    midX: number;
+    midY: number;
+    /** 段长度（绝对值），用于判定是否值得渲染手柄（防止极短段误触） */
+    length: number;
+}
+export declare function getEdgeInnerSegments(points: [number, number][]): EdgeInnerSegmentInfo[];
+export declare function buildEdgeRoute(edge: FloorMapEdge, rectsById: Map<string, FloorMapItemPixelRect>, options?: BuildEdgeRouteOptions): FloorMapEdgeRoute | null;
+/**
+ * 去掉路径中"三点共线"的冗余中间点（比如 routeOrthogonal 里 srcPt → sOut →
+ * 中段折点都在同一 y 上时，sOut 是冗余的）。
+ *
+ * 保留零长度段：用户拖动 first/last 段创建 stub 时，stubEnd 与 midCorner 短暂
+ * 重合（零长度），不能被合并掉，否则会立刻丢失新插入的转角结构。
+ */
+export declare function simplifyCollinearPath(points: [number, number][]): [number, number][];
+/**
+ * 按 edge 顺序分配交替偏移，让落到同一通道的多条线错开。
+ * 序列：0, +step, -step, +2*step, -2*step, ...
+ */
+export declare function getEdgeChannelOffset(index: number, step?: number): number;
+/** 命中检测：点到折线最近距离 */
+export declare function distanceToPolyline(px: number, py: number, points: [number, number][]): number;
+export declare function hitTestEdgeAtPoint(px: number, py: number, routes: FloorMapEdgeRoute[], threshold?: number): string | null;
+export { ANCHORS as FLOOR_MAP_EDGE_ANCHORS };

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

@@ -0,0 +1,59 @@
+/**
+ * 内置图形图元（`floorMapBuiltinShape`）的预设清单。
+ *
+ * 每个预设：
+ * - `key`：持久化在 `sceneElement.builtinShapeKey`，跨语言稳定；
+ * - `labelKey`：展示名 i18n key（在 `locales.ts` / `-ja` / `-pt` 中维护）；
+ * - `defaultSize`：调色板落点 / 切换 kind 时的初始像素尺寸，比例与下文 viewBox 一致；
+ * - `render(props)`：内置 SVG 图形（统一 `preserveAspectRatio="xMidYMid meet"`，
+ *   按 viewBox 自然比例缩放并居中，容器尺寸变化时不会被拉伸变形）。
+ *
+ * 不引入图片资源 / 字体图标，全部 inline SVG，避免额外构建依赖与请求。
+ */
+import React from 'react';
+/** 内置图形渲染函数共享 props（容器已限定 100% 宽高） */
+export interface FloorMapBuiltinShapeRenderProps {
+    /** 主体填充色（壳层为浅灰），允许通过 sceneElement.fillColor 覆盖 */
+    fillColor?: string;
+    /** 描边色，允许通过 sceneElement.strokeColor 覆盖 */
+    strokeColor?: string;
+}
+export interface FloorMapBuiltinShapeDef {
+    key: string;
+    /** i18n 文案 key（在 locales.ts 中维护中英繁日葡） */
+    labelKey: string;
+    /** 调色板落点时的默认像素尺寸；比例与 viewBox 对齐，避免落点后立刻变形 */
+    defaultSize: {
+        width: number;
+        height: number;
+    };
+    /** 内置 SVG 渲染（按 viewBox 比例缩放，容器变化时居中保比例） */
+    render: (props: FloorMapBuiltinShapeRenderProps) => React.ReactElement;
+    /**
+     * 是否随容器宽高自动切换横/竖方向。
+     * - `true`：容器高 > 宽时，wrapper 自动给整张图形 rotate 90deg，让图形在画
+     *   布上看起来始终「贴墙 / 贴边」。比追加一个 `*-vertical` key 更直观，
+     *   也不需要持久化方向，纯几何 fit。
+     * - 默认 `false`（厕所 / 柱子 / 分隔等无方向语义或自带 stretch 策略的图形）。
+     */
+    orientationAware?: boolean;
+}
+/** 默认主色 / 描边色：偏中性灰，与地面其它图元（房间 / 桌位）调性一致 */
+declare const DEFAULT_FILL = "#f1f3f5";
+declare const DEFAULT_STROKE = "#6b7280";
+/**
+ * 内置图形预设清单（顺序即调色板 / 编辑面板下拉的展示顺序）。
+ * `defaultSize` 比例严格跟随对应 SVG 的 viewBox：
+ * - 厕所 / 柱子 / 大门：正方形（viewBox 100×100）
+ * - 分隔：viewBox 100×100，但渲染层用 `preserveAspectRatio="none"`，
+ *   `defaultSize` 给个常用的瘦高比例（32×160）作为「默认竖分隔」落点，
+ *   用户可直接拖宽变横分隔，不需要换 key。
+ * - 沙发：2:1 水平（viewBox 200×100）
+ *
+ * 新增预设：在此追加一项即可，编辑面板 / 调色板 / fallback 渲染会自动适配。
+ */
+export declare const FLOOR_MAP_BUILTIN_SHAPES: FloorMapBuiltinShapeDef[];
+/** 通过 key 查找预设，未命中返回 undefined（让上层显示「未选择」占位） */
+export declare function getFloorMapBuiltinShapeDef(key: string | undefined): FloorMapBuiltinShapeDef | undefined;
+export { DEFAULT_FILL as FLOOR_MAP_BUILTIN_SHAPE_DEFAULT_FILL };
+export { DEFAULT_STROKE as FLOOR_MAP_BUILTIN_SHAPE_DEFAULT_STROKE };

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

@@ -0,0 +1,83 @@
+/**
+ * 平面图内容区尺寸：由 items + padding 推导 contentWidth/Height 与 offset。
+ * 供 useFloorMapTransformMetrics（单画布视口）与 FloorMapOverview（多画布平铺）共用，
+ * 避免两处各自维护包围盒算法。
+ */
+import type { FloorMapItemBase, FloorMapItemUnit } from '../types';
+/** 内容区宽高与图元层偏移（与 Transform content 坐标系一致） */
+export interface FloorMapContentStage {
+    contentWidth: number;
+    contentHeight: number;
+    contentOffsetX: number;
+    contentOffsetY: number;
+    /**
+     * 使用 pixel 包围盒时的单侧 padding，用于 initialPosition 对齐；
+     * 非包围盒路径为 null。
+     */
+    alignPadSingle: number | null;
+}
+export interface ComputeFloorMapContentStageParams<T extends FloorMapItemBase = FloorMapItemBase> {
+    items: T[];
+    cellSize: number;
+    itemGap: number;
+    itemUnit: FloorMapItemUnit;
+    /** 单侧 bounding padding（与 mapLayer.boundingPadding 一致） */
+    boundingPadding: number;
+    /**
+     * 为 true 且 itemUnit 为 pixel、items 非空时，按图元包围盒扩边；
+     * 平面图主视图传 isFloorMapView，全览缩略图传 true。
+     */
+    preferPixelBoundingBox?: boolean;
+}
+/**
+ * 根据 items 计算内容区尺寸与偏移。
+ * 算法与 {@link useFloorMapTransformMetrics} 内原 useMemo 一致（不含「撑满视口」扩展）。
+ */
+export declare function computeFloorMapContentStage<T extends FloorMapItemBase>(params: ComputeFloorMapContentStageParams<T>): FloorMapContentStage;
+/**
+ * 全览网格行列：n≤3 单行；n≥4 用 ceil(√n) 列、ceil(n/cols) 行，行列接近且末行空格最少。
+ * 例：2→2×1，3→3×1，4→2×2，5/6→3×2，7-9→3×3，10-12→4×3。
+ *
+ * 仅供旧版「等大缩略图卡片」全览使用；新版 All 视图按原始尺寸装箱，请用
+ * {@link packCanvasesIntoShelves}。
+ */
+export declare function getOverviewGridDims(count: number): {
+    cols: number;
+    rows: number;
+};
+/** 装箱输入：每个画布在统一比例尺下的原始尺寸（像素） */
+export interface PackCanvasItem {
+    width: number;
+    height: number;
+}
+/** 装箱产物：每个画布的左上角坐标 + 总布局尺寸（不含外侧 padding） */
+export interface PackCanvasResult {
+    positions: Array<{
+        x: number;
+        y: number;
+    }>;
+    totalWidth: number;
+    totalHeight: number;
+}
+/**
+ * 多画布 All 视图的紧凑装箱（Bottom-Left Fill, BLF）：
+ *
+ * - 保留输入顺序（与 Tab 顺序一致），不旋转、不缩放，原始尺寸即渲染尺寸；
+ * - 对每张画布枚举候选落点 = `{(0,0)} ∪ 已放画布的{右侧, 下方}角`；过滤掉与已放冲突
+ *   的位置，再挑 **y 最小、再 x 最小** 的位置落下——优先填低洼，自然会把矮 / 窄画布
+ *   塞进高画布旁的空白；不会出现「等最高画布把整行撑满才换行」导致的大量空白；
+ * - 目标外框宽度 `targetWidth = max(最宽画布, √(总面积 × {@link aspectBias}))`，
+ *   令整体形状趋于 `aspectBias:1`（默认 2.5 → 宽:高 ≈ 2.5:1，轻微偏横）；
+ *   单张画布若本身比 targetWidth 还宽，仍允许独自首行铺开，避免被截。
+ *
+ * 复杂度 O(n²)（每个画布对所有已放做候选 + 冲突校验），n 通常 < 20，性能足够。
+ * 比旧的行装填（shelf packing）能显著减少长高画布旁的留白。
+ *
+ * @param boxes - 待装箱画布尺寸（保持顺序）
+ * @param gap - 画布之间的像素间距（同时作为冲突检测的最小净距）
+ * @param aspectBias - 目标宽高比偏置（width:height）；越大越横向，默认 2.5
+ *   - `1.5` ~ `2`：接近正方形，仅略偏横
+ *   - `2.5` ~ `3`：明显但温和的横向布局（推荐）
+ *   - `>= 4`：强横向，画布数较多时易接近单行
+ */
+export declare function packCanvasesIntoShelves(boxes: PackCanvasItem[], gap: number, aspectBias?: number): PackCanvasResult;

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/floorMapDataBindingUtils.d.ts

@@ -0,0 +1,21 @@
+import type { FloorMapDataSources, FloorMapMergedItem } from '../types';
+/**
+ * 数据源行：平面图 dataSources 列表项至少含 `id`（与 {@link FloorMapSceneElementDataBinding.recordId} 对应）。
+ */
+export declare type FloorMapDataSourceRow = {
+    id: string;
+    [key: string]: unknown;
+};
+/**
+ * 按画布图元上的 `dataBinding` 在 `dataSources[dataSourceKey]` 中查找对应行。
+ * 与 private-materials 预约 `findReservationRow` 算法一致：`recordId` 与行的 `id` 均按字符串比较。
+ */
+export declare function findFloorMapRowByDataBinding<T extends FloorMapDataSourceRow>(item: FloorMapMergedItem, dataSources: FloorMapDataSources): T | undefined;
+/**
+ * 当 {@link findFloorMapRowByDataBinding} 无结果时，占位卡可据此选择文案（业务层自行 i18n）。
+ */
+export declare type FloorMapBindingPlaceholderReason = 'missing_data_source_key' | 'missing_record_id' | 'new_unsaved_slot' | 'record_not_in_list';
+/**
+ * 若已能解析到数据源行则返回 `null`；否则返回占位原因（不含文案，便于各业务映射 locales）。
+ */
+export declare function getFloorMapBindingPlaceholderReason(item: FloorMapMergedItem, dataSources: FloorMapDataSources): FloorMapBindingPlaceholderReason | null;

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

@@ -0,0 +1,8 @@
+/**
+ * 平面图数据行在下拉选项中的展示文案（侧栏「选择数据行」、工具栏多选记录）
+ * 仅展示名称侧一条：main_field（取 ## 前段）→ code → name；不再拼接 id、form_code、status。
+ */
+export declare function formatDataRecordOptionLabel(record: {
+    id: string;
+    [k: string]: unknown;
+}): string;

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

@@ -0,0 +1,33 @@
+/**
+ * 平面图编辑态：侧栏图元拖拽到画布的 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;
+    recordIds?: string[];
+    /**
+     * 内置图形 kind 拖拽时，侧栏预选的图形 key（{@link FLOOR_MAP_BUILTIN_SHAPES}）；
+     * 落点会以此为初始 `sceneElement.builtinShapeKey` 与默认像素尺寸。
+     * 其它 kind 不读取此字段。
+     */
+    builtinShapeKey?: 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/floorMapElementNameAsTitle.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 「将图元名作为资源标题」开关：通用读写 + 标题解析。
+ *
+ * - 持久化在 `sceneElement.extensions[NAME_AS_TITLE_EXT_KEY]`，避免污染顶层 schema、
+ *   不影响未启用该能力的旧 / 新 kind。
+ * - 是否在编辑面板「显示」该选项，由 `FloorMapElementKindConfig.nameAsTitleConfigurable`
+ *   控制；展示侧（业务卡片渲染）只读 extensions，不依赖 kindConfig，确保即便业务方
+ *   后续撤回 kindConfig 开关，已落库的偏好仍生效。
+ */
+/** 持久化字段名：固定字符串，跨包共用，勿改 */
+export declare const NAME_AS_TITLE_EXT_KEY: "nameAsTitle";
+interface ElementWithExtensions {
+    name?: string;
+    extensions?: Record<string, unknown>;
+}
+/** 安全读取「图元名作为标题」开关 */
+export declare function isElementNameAsTitleEnabled(el: ElementWithExtensions | null | undefined): boolean;
+/**
+ * 计算 `extensions` patch：返回值供调用方写入 `sceneElement.extensions`。
+ *
+ * - `enabled === true` 时写入 `true`；
+ * - `enabled === false` 时**移除**该 key（而非写 `false`），避免持久化里残留无意义字段；
+ * - 返回 `undefined` 表示「extensions 整体可清空」（仅当结果是空对象时）。
+ *
+ * @example
+ * const nextExt = buildNameAsTitleExtensionsPatch(el.extensions, true);
+ * onUpdate({ extensions: nextExt });
+ */
+export declare function buildNameAsTitleExtensionsPatch(prev: Record<string, unknown> | undefined, enabled: boolean): Record<string, unknown> | undefined;
+/**
+ * 通用图元标题解析：业务展示层（卡片标题、占位标题等）统一调用本函数，
+ * 让「图元名作为资源标题」这一偏好对所有接入方一致生效。
+ *
+ * 优先级：
+ *   1. 启用了 nameAsTitle 且 `el.name` 非空 → `el.name`
+ *   2. `recordTitle`（业务侧按自己规则算出来的，如预约页 `row.main_field` / `row.code`）
+ *   3. `el.name`（业务字段缺失时的兜底，与历史行为一致）
+ *   4. `fallback`（如 kindLabel）
+ *   5. 空串
+ *
+ * 不更改 `displayRoomTitleFromRow` / `record.name` 等业务函数本身，
+ * 业务方只需把"按业务字段"算出来的结果以 `recordTitle` 传入即可，
+ * `bookingDetailModal` 等下游不会被联动改坏。
+ */
+export declare function resolveSceneElementDisplayTitle(opts: {
+    sceneElement?: ElementWithExtensions | null;
+    recordTitle?: string;
+    fallback?: string;
+}): string;
+export {};

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;