@pisell/materials 6.11.223 → 6.11.225

package/lib/components/pisellEmail/utils/emailHelper.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 邮箱辅助函数
+ */
+import type { MailtoOptions } from '../types';
+/**
+ * 提取邮箱域名
+ * @param email 邮箱地址
+ * @returns 域名部分
+ *
+ * @example
+ * extractEmailDomain('user@example.com') // 'example.com'
+ */
+export declare function extractEmailDomain(email: string): string;
+/**
+ * 提取邮箱本地部分
+ * @param email 邮箱地址
+ * @returns 本地部分（@ 前面的部分）
+ *
+ * @example
+ * extractEmailLocal('user@example.com') // 'user'
+ */
+export declare function extractEmailLocal(email: string): string;
+/**
+ * 规范化邮箱地址（转小写）
+ * @param email 邮箱地址
+ * @returns 规范化后的邮箱地址
+ *
+ * @example
+ * normalizeEmail('User@Example.COM') // 'user@example.com'
+ */
+export declare function normalizeEmail(email: string): string;
+/**
+ * 邮箱域名脱敏（partial 模式）
+ * 只显示本地部分的第一个字符，其余用 *** 替代
+ *
+ * @param email 邮箱地址
+ * @returns 脱敏后的邮箱（u***@gmail.com）
+ *
+ * @example
+ * hideEmailDomain('user@gmail.com') // 'u***@gmail.com'
+ */
+export declare function hideEmailDomain(email: string): string;
+/**
+ * 邮箱域名完全隐藏（full 模式）
+ * 隐藏整个域名部分
+ *
+ * @param email 邮箱地址
+ * @returns 脱敏后的邮箱（user@***）
+ *
+ * @example
+ * maskEmailDomain('user@gmail.com') // 'user@***'
+ */
+export declare function maskEmailDomain(email: string): string;
+/**
+ * 处理 mailto 点击，唤起邮件客户端
+ *
+ * @param email 邮箱地址
+ * @param options mailto 可选参数（主题、正文、抄送等）
+ *
+ * @example
+ * handleEmailClick('support@example.com', {
+ *   subject: '产品咨询',
+ *   body: '您好，我想咨询...'
+ * })
+ */
+export declare function handleEmailClick(email: string, options?: MailtoOptions): void;

package/lib/components/pisellEmail/utils/emailValidator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 邮箱校验工具函数
+ */
+/**
+ * 标准邮箱格式校验
+ * @param email 邮箱地址
+ * @returns 是否通过校验
+ *
+ * @example
+ * validateEmail('user@example.com') // true
+ * validateEmail('invalid-email') // false
+ */
+export declare function validateEmail(email: string): boolean;
+/**
+ * 严格邮箱格式校验（RFC 5322）
+ * @param email 邮箱地址
+ * @returns 是否通过校验
+ *
+ * @example
+ * validateEmailStrict('user@example.com') // true
+ */
+export declare function validateEmailStrict(email: string): boolean;
+/**
+ * 邮箱分部校验
+ * 检查邮箱的各个部分是否符合规范
+ *
+ * @param email 邮箱地址
+ * @returns 校验结果
+ */
+export declare function validateEmailParts(email: string): {
+    isValid: boolean;
+    errors: string[];
+};
+/**
+ * 域名白名单/黑名单校验
+ *
+ * @param email 邮箱地址
+ * @param allowedDomains 白名单域名列表
+ * @param blockedDomains 黑名单域名列表
+ * @returns 校验结果
+ */
+export declare function validateEmailDomain(email: string, allowedDomains?: string[], blockedDomains?: string[]): {
+    isValid: boolean;
+    errors: string[];
+};

package/lib/components/pisellEmail/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PisellEmail 工具函数导出
+ */
+export * from './emailValidator';
+export * from './emailHelper';
+export * from './domainSuggestions';

package/lib/components/pisellFilter/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import { PisellFilterProps } from './type';
+declare const PisellFilter: (props: PisellFilterProps) => JSX.Element;
+export default PisellFilter;

package/lib/components/pisellFilter/type.d.ts

@@ -0,0 +1,7 @@
+import { FilterListProps } from '../filter/components/FilterButton/types';
+/**
+ * 筛选弹层 + 快筛列表；内部通过 Form.useForm 托管表单，无需也不应把 antd FormInstance 并入 props。
+ */
+export declare type PisellFilterProps = FilterListProps & {
+    hasForm?: boolean;
+};

package/lib/components/pisellFind/PisellFind.stories.d.ts

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellFind } from './index';
+/**
+ * PisellFind 组件 Storybook
+ * 基于 PisellLookup 的组件内查找优化版本
+ */
+declare const meta: Meta<typeof PisellFind>;
+export default meta;
+declare type Story = StoryObj<typeof PisellFind>;
+/**
+ * 基础示例 - 列表查找
+ */
+export declare const Basic: Story;
+/**
+ * 表格查找
+ */
+export declare const TableFind: Story;
+/**
+ * Input 模式查找
+ */
+export declare const InputMode: Story;
+/**
+ * 使用 Ref 控制
+ */
+export declare const WithRef: Story;
+/**
+ * 显示确认按钮
+ */
+export declare const WithConfirmButton: Story;
+/**
+ * 关闭历史记录
+ */
+export declare const NoHistory: Story;
+/**
+ * 多字段搜索
+ */
+export declare const MultiFieldSearch: Story;
+/**
+ * Drawer 模式
+ */
+export declare const DrawerMode: Story;
+/**
+ * Playground - 自由配置
+ */
+export declare const Playground: Story;

package/lib/components/pisellFloorMapLayout/PisellFloorMapLayout.stories.d.ts

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellFloorMapLayout } from './PisellFloorMapLayout';
+/**
+ * PisellFloorMapLayout 楼层图布局
+ *
+ * 空间布局视图：在二维平面按坐标渲染资源（桌台/房间/工位等），
+ * 支持缩放、平移、复位、区域定位，仅负责展示与交互。
+ */
+declare const meta: Meta<typeof PisellFloorMapLayout>;
+export default meta;
+declare type Story = StoryObj<typeof PisellFloorMapLayout>;
+/**
+ * 默认 - 纯色底 + 简单格子（格子单位，默认 item 间距 8px）
+ */
+export declare const Default: Story;
+/**
+ * 显示网格线（item 间距由 mapLayer.gap 控制）
+ */
+export declare const WithGrid: Story;
+/**
+ * 开启平移 - 可拖拽画布
+ */
+export declare const WithPan: Story;
+export declare const WithShapes: Story;
+export declare const WithVariableSizes: Story;
+export declare const PixelUnits: Story;
+/**
+ * 点击与 Hover 事件
+ */
+export declare const WithEvents: Story;
+/**
+ * Ref 调用 - 外部按钮控制缩放/复位/区域定位
+ */
+export declare const WithRefControls: Story;
+export declare const FloorMapViewEdit: Story;
+/**
+ * 平面图编辑态 + 自定义数据源记录表单（`dataSourceRecordForm.sales`）
+ */
+export declare const FloorMapViewEditCustomRecordForm: Story;
+/**
+ * Floor Map 视图 - 阅读态（方桌同样用 Figma 样式）
+ */
+export declare const FloorMapViewRead: Story;
+/**
+ * 平面图阅读态 - 验证 appearanceMode 的暗色背景兜底
+ */
+export declare const DarkBackground: Story;
+/**
+ * 自定义控制按钮显隐
+ */
+export declare const ControlsHidden: Story;
+/**
+ * `FloorMapLayoutProvider` 注入 `floorMapConfig` / `dataSources`；Layout 仅传展示向 props
+ */
+export declare const FloorMapWithLayoutProvider: Story;
+/**
+ * Figma 设计稿效果 - 餐厅桌台状态图（顶部 Tab + 图例参考 node 14131:6266，内容区不变）
+ */
+export declare const FigmaDesign: Story;

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

@@ -0,0 +1,29 @@
+import type { FloorMapEdgeStatus } from '../types';
+export declare type FloorMapAppearanceMode = 'light' | 'dark';
+export interface FloorMapEdgeStatusStyle {
+    readonly stroke: string;
+    readonly dashed: boolean;
+}
+export interface FloorMapAppearanceTokens {
+    readonly mode: FloorMapAppearanceMode;
+    /**
+     * 外观模式提供的画布背景兜底色。
+     * 若调用方显式传入 `mapLayer.backgroundColor`，应以显式背景色为准。
+     */
+    readonly fallbackCanvasBackgroundColor: string;
+    /** 按连线状态默认描边样式 */
+    readonly edgeStatusStyles: Record<FloorMapEdgeStatus, FloorMapEdgeStatusStyle>;
+    readonly edgeSelectedStroke: string;
+    readonly edgeGhostStroke: string;
+    readonly edgePortLabelBackground: string;
+    readonly edgePortLabelText: string;
+    readonly edgePortLabelBorder: string;
+    /** 拖动/缩放图元时的边对齐辅助线颜色（主题色） */
+    readonly alignGuideStroke: string;
+}
+/**
+ * 按外观模式返回 floorMap 画布背景 token。
+ * 当前仅承载通用画布背景兜底色，不包含业务壳层颜色；
+ * 渲染层应先尊重显式 `mapLayer.backgroundColor`，再回退到这里的 token。
+ */
+export declare function getFloorMapAppearanceTokens(mode: FloorMapAppearanceMode): FloorMapAppearanceTokens;

package/lib/components/pisellFloorMapLayout/components/EdgeLayer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * EdgeLayer - 拓扑连线 SVG 层（正交折线 + 端口标签）
+ */
+import React from 'react';
+import type { FloorMapAppearanceTokens } from '../appearance/floorMapAppearance';
+import type { FloorMapEdge } from '../types';
+import { type FloorMapEdgeRoute, type FloorMapItemPixelRect } from '../utils/edgeRouting';
+import './EdgeLayer.less';
+export interface EdgeLayerProps {
+    width: number;
+    height: number;
+    contentOffsetX?: number;
+    contentOffsetY?: number;
+    edges: FloorMapEdge[];
+    routes: FloorMapEdgeRoute[];
+    rectsById: Map<string, FloorMapItemPixelRect>;
+    appearance: FloorMapAppearanceTokens;
+    mode: 'read' | 'edit';
+    selectedEdgeId?: string | null;
+    ghostPathD?: string | null;
+    onEdgeClick?: (edgeId: string, event: React.MouseEvent) => void;
+    /** 画布 viewport scale，用于段手柄反向缩放 */
+    viewportScale?: number;
+    /** 段手柄拖动开始（含首/末段以触发 stub 插入） */
+    onSegmentDragStart?: (params: {
+        edgeId: string;
+        role: 'first' | 'last' | 'inner';
+        segmentIndex: number;
+        axis: 'h' | 'v';
+        startPosition: number;
+        clientX: number;
+        clientY: number;
+        segmentLength?: number;
+    }) => void;
+    className?: string;
+}
+export declare function EdgeLayer(props: EdgeLayerProps): JSX.Element;

package/lib/components/pisellFloorMapLayout/components/EditableItemLayer.d.ts

@@ -0,0 +1,89 @@
+/**
+ * EditableItemLayer - 编辑态图元层：拖拽、缩放、选中、吸附
+ */
+import React, { type CSSProperties } from 'react';
+import type { FloorMapItemBase, FloorMapMergedItem, FloorMapRenderOptions } from '../types';
+import { type AlignGuide } from '../utils/alignSnap';
+import { type FloorMapEditQuickActionLabels } from './FloorMapEditQuickActions';
+import './EditableItemLayer.less';
+export interface EditableItemLayerProps<T extends FloorMapItemBase = FloorMapMergedItem> {
+    items: T[];
+    renderItem: (item: T, index: number, options?: FloorMapRenderOptions) => React.ReactNode;
+    rowKey?: string | ((item: T, index: number) => string);
+    cellSize: number;
+    itemUnit?: 'cell' | 'pixel';
+    itemGap?: number;
+    contentWidth: number;
+    contentHeight: number;
+    /** 内容区 X/Y 偏移（画布包围盒向左/上扩展时，图元层整体平移） */
+    contentOffsetX?: number;
+    contentOffsetY?: number;
+    selectedId: string | null;
+    onSelect: (id: string | null) => void;
+    onUpdateItem: (itemId: string, patch: Partial<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>) => void;
+    /**
+     * 一次提交多个图元的坐标变更（选区分组拖拽时整组落库），用于一步撤销。
+     * 未传时分组拖拽降级为不落库（仅预览）。
+     */
+    onUpdateItemsBatch?: (patches: Array<{
+        id: string;
+        patch: Partial<{
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }>;
+    }>) => void;
+    snapStep?: number;
+    /** 画布当前缩放，用于将屏幕位移转为内容位移 */
+    scale?: number;
+    /** 拖拽/缩放图元时通知父组件，用于禁用画布平移，避免松手时画布跟着动 */
+    onInteractionChange?: (active: boolean) => void;
+    /**
+     * 拖拽/缩放过程中的像素矩形（内容坐标），用于 EdgeLayer 实时重算连线。
+     * itemId 为 null 表示结束交互。
+     */
+    onLiveRectChange?: (itemId: string | null, rect: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | null) => void;
+    /**
+     * 选区分组拖拽过程中，选区与全部成员的实时像素矩形（内容坐标），用于 EdgeLayer 重算连线。
+     * 传 null 表示结束分组交互。
+     */
+    onLiveRectsChange?: (rects: Record<string, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }> | null) => void;
+    /**
+     * 对齐阈值（屏幕像素，组件内会按 scale 折算到内容坐标）。
+     * 0 或负数关闭对齐。
+     */
+    alignSnapThresholdPx?: number;
+    /** 命中的对齐辅助线变化；交互结束时回调一次空数组 */
+    onAlignGuidesChange?: (guides: AlignGuide[]) => void;
+    /** 对齐辅助线颜色（推荐用主题 token `alignGuideStroke`） */
+    alignGuideStroke?: string;
+    /** 每项外层容器额外样式（与定位样式合并） */
+    getMergedItemWrapperStyle?: (item: T, index: number) => CSSProperties | undefined;
+    className?: string;
+    /** 编辑态选中时图元旁快捷栏（上锁 / 复制 / 删除） */
+    editQuickBar?: {
+        labels: FloorMapEditQuickActionLabels;
+        isLocked: boolean;
+        onToggleLock: () => void;
+        onDuplicate: () => void;
+        onDelete: () => void;
+    } | null;
+}
+export declare function EditableItemLayer<T extends FloorMapItemBase>(props: EditableItemLayerProps<T>): JSX.Element;
+export default EditableItemLayer;

package/lib/components/pisellFloorMapLayout/components/FloorMapEditQuickActions.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="react" />
+export interface FloorMapEditQuickActionLabels {
+    lock: string;
+    unlock: string;
+    duplicate: string;
+    delete: string;
+    popTitle: string;
+    popDesc: string;
+    cancel: string;
+    okDelete: string;
+    ariaToolbar: string;
+}
+export interface FloorMapEditQuickActionsProps {
+    className?: string;
+    labels: FloorMapEditQuickActionLabels;
+    isLocked: boolean;
+    onToggleLock: () => void;
+    onDuplicate: () => void;
+    onDelete: () => void;
+    /** 画布 viewport scale，用于按 1/scale 反向缩放整个工具条，保持视觉尺寸恒定 */
+    viewportScale?: number;
+}
+export declare function FloorMapEditQuickActions(props: FloorMapEditQuickActionsProps): JSX.Element;

package/lib/components/pisellFloorMapLayout/components/FloorMapOverview.d.ts

@@ -0,0 +1,49 @@
+/**
+ * FloorMapOverview - 阅读态「All」全览视图（纯渲染版）
+ *
+ * 仅负责把 {@link OverviewLayout} 中各画布的图元渲染到对应的绝对定位区域里；
+ * 由 PisellFloorMapLayout 在主 TransformWrapper 内挂载，与单画布共享同一套
+ * 视口控件（缩放、平移、锁定、全屏、fitBounds、网格按钮等）。
+ *
+ * 设计要点：
+ * - 不再自带 TransformWrapper / ResizeObserver / fit 算法；
+ * - 每个画布作为独立区域，仅一条细边框作分隔，无背景色/网格；
+ * - 画布名显示在边框外的标题带；标题不拦截图元交互；
+ * - 仅渲染 ItemLayer（阅读态），与单画布的 hover/click 行为一致；编辑层不渲染。
+ */
+import React from 'react';
+import type { OverviewLayout } from '../utils/floorMapOverviewLayout';
+import type { FloorMapItemBase, FloorMapItemUnit, FloorMapRenderOptions, FloorMapViewConfig } from '../types';
+import './FloorMapOverview.less';
+export interface FloorMapOverviewProps<T extends FloorMapItemBase> {
+    /** 由 PisellFloorMapLayout 算好的整体布局（区域位置 + 总尺寸） */
+    overviewLayout: OverviewLayout;
+    /**
+     * 仅用于把 `canvas.id` 映射成展示名（区域左上角 chip）。
+     * 直接传 config 而非映射表，避免父组件再多构造一层。
+     */
+    config: FloorMapViewConfig;
+    itemUnit?: FloorMapItemUnit;
+    renderItem: (item: T, index: number, options?: FloorMapRenderOptions) => React.ReactNode;
+    /**
+     * 主 TransformWrapper 的当前缩放，透传到各区域 ItemLayer 的 `viewportScale`。
+     * 缺省（undefined）时下游 `renderItem` 拿不到 viewportScale，预约/桌位卡只能
+     * 按布局像素算 visualShortSide，**永远停在 comfortable 档**，进不去 tooltip-time
+     * 小卡片模式——这正是 All 视图缩放后看不到小卡的根因。
+     */
+    viewportScale?: number;
+    enableHover?: boolean;
+    onItemClick?: (item: T, index: number, e: React.MouseEvent<HTMLElement>) => void;
+    onItemHover?: (item: T, index: number, e: React.MouseEvent<HTMLElement>) => void;
+    onItemLeave?: (item: T, index: number, e: React.MouseEvent<HTMLElement>) => void;
+    getMergedItemWrapperStyle?: (item: T, index: number) => React.CSSProperties | undefined;
+    readModeSelectedItemId?: string | null;
+    /**
+     * 点击区域标题（画布名标签）时回调，传入该区域的 `canvasId`。
+     * 传入后标题标签变为可点击（pointer-events 放开 + 指针光标），用于从 All 视图切回该画布。
+     */
+    onSelectCanvas?: (canvasId: string) => void;
+    className?: string;
+}
+export declare function FloorMapOverview<T extends FloorMapItemBase>(props: FloorMapOverviewProps<T>): JSX.Element;
+export default FloorMapOverview;

package/lib/components/pisellFloorMapLayout/components/FloorMapSelectionZoneElement.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="react" />
+import './FloorMapSelectionZoneElement.less';
+export interface FloorMapSelectionZoneElementProps {
+    /** 选区名称；为空时展示「未命名选区」占位 */
+    name?: string;
+}
+export declare function FloorMapSelectionZoneElement(props: FloorMapSelectionZoneElementProps): JSX.Element;

package/lib/components/pisellFloorMapLayout/components/HistoryIcons.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 编辑顶栏 Undo / Redo 自定义 SVG icon。
+ *
+ * 设计来源：业务方提供的「圆勾箭头」风格 —— 整圈 ~270° 回环 + 末端三角箭头。
+ * 替换 antd 的 `UndoOutlined` / `RedoOutlined`：原版箭头偏方、回勾过短，
+ * 在 24/16px 的小尺寸下与界面其它细线 icon 不齐，且 Undo/Redo 镜像不够直观。
+ *
+ * 实现要点：
+ * - `stroke="currentColor"`、无填充：颜色完全跟随父级 `color`，与 Ant Button text 模式一致；
+ * - viewBox 14×14，配合 `font-size: 14px` 自动得到 14px icon；调用方可通过 fontSize/CSS 调整；
+ * - `stroke-linecap=round` + `stroke-linejoin=round`：在 1.5px 细线下保持圆润、抗锯齿友好；
+ * - 箭头用同色 `path` 三角，避免 marker-end 在不同浏览器下的尺寸漂移；
+ * - 接受 `className` / `style` / 其它 SVG 属性透传（与 antd icon 体感一致）。
+ */
+import React from 'react';
+declare type HistoryIconProps = React.SVGProps<SVGSVGElement> & {
+    /** 与 antd icon 类似：用于覆盖默认 1em 尺寸 */
+    size?: number | string;
+};
+/**
+ * Undo 图标：「↰」L 形带小圆角 —— 箭头在左侧水平指向左，主干由箭头水平向右、
+ * 经一个 1.5 半径的圆角折下、再竖直向下。
+ *
+ * 关于"看起来偏上"：antd `.anticon { vertical-align: -0.125em }` 已经把整个 svg
+ * 相对文字基线下移 ~0.125em，但我们的形状在 viewBox 内是几何居中的（y ∈ [3,11]），
+ * 与 antd 自家 outline icon（路径几乎铺满 viewBox）在视觉密度上不同 ——
+ * 留白对称会让人眼判断"图形在 viewBox 上半"。
+ *
+ * 解决：把形状整体下移 1 单位到 y ∈ [4, 12]，上侧留 4 / 下侧留 2，
+ * 让 icon 视觉中心匹配文字 x-height 中心，与 "Undo" 文本视觉齐平。
+ * x 仍保持 [3, 11] 居中。
+ */
+export declare function UndoHistoryIcon(props: HistoryIconProps): JSX.Element;
+/**
+ * Redo 图标：与 Undo 水平镜像，箭头在右侧指向右，干线右→左→下。
+ * 几何范围与 Undo 完全对称：x ∈ [3, 11]、y ∈ [4, 12]。
+ */
+export declare function RedoHistoryIcon(props: HistoryIconProps): JSX.Element;
+export {};

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

@@ -0,0 +1,59 @@
+/**
+ * ItemLayer - 楼层图展示层
+ * 按 items 的 (x, y) 与 cellSize 定位，用 renderItem 渲染每项内容
+ */
+import React from 'react';
+import type { FloorMapItemBase, FloorMapItemUnit, FloorMapRenderOptions } from '../types';
+import type { CSSProperties } from 'react';
+import './ItemLayer.less';
+export interface ItemLayerProps<T extends FloorMapItemBase> {
+    /** 资源列表 */
+    items: T[];
+    /** 每项渲染函数 */
+    renderItem: (item: T, index: number, options?: FloorMapRenderOptions) => React.ReactNode;
+    /** 画布缩放（与平面图 zoom 一致），透传给 renderItem 第三参数 */
+    viewportScale?: number;
+    /** 每项 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/lib/components/pisellFloorMapLayout/components/MapLayer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MapLayer - 楼层图底层
+ * 负责背景（无/纯色/图片/SVG）、网格线、padding、gap
+ */
+import React from 'react';
+import type { FloorMapLayerConfig } from '../types';
+import './MapLayer.less';
+export interface MapLayerProps {
+    /** 底层配置 */
+    config?: FloorMapLayerConfig;
+    /** 内容区域宽度（逻辑单位或像素，用于网格线计算） */
+    contentWidth?: number;
+    /** 内容区域高度 */
+    contentHeight?: number;
+    /** 每格像素尺寸（用于网格线间距） */
+    cellSize?: number;
+    /** 为 true 时不应用纯色背景，让画布底层网格透出 */
+    preferCanvasGrid?: boolean;
+    /** 为 true 时容器设置 pointer-events: none，空白处点击可透传到下层，供 react-zoom-pan-pinch 画布平移 */
+    pointerEventsNone?: boolean;
+    /** 子节点（展示层会叠在上方） */
+    children?: React.ReactNode;
+    /** 自定义类名 */
+    className?: string;
+}
+export declare function MapLayer(props: MapLayerProps): JSX.Element;
+export default MapLayer;

package/lib/components/pisellFloorMapLayout/components/NodePortMarkers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * NodePortMarkers - 选中图元时显示四向锚点，用于拉线
+ */
+import React from 'react';
+import type { FloorMapEdgeAnchor } from '../types';
+import { type FloorMapItemPixelRect } from '../utils/edgeRouting';
+import './NodePortMarkers.less';
+export interface NodePortMarkersProps {
+    rect: FloorMapItemPixelRect;
+    contentOffsetX?: number;
+    contentOffsetY?: number;
+    /** 仅展示/高亮（拉线吸附目标），不可点击 */
+    previewOnly?: boolean;
+    onAnchorPointerDown?: (anchor: FloorMapEdgeAnchor, event: React.PointerEvent) => void;
+    highlightAnchors?: FloorMapEdgeAnchor[];
+    className?: string;
+    /** 画布 viewport scale，用于把圆点和外移距离按 1/scale 反向缩放，保持视觉尺寸恒定 */
+    viewportScale?: number;
+}
+export declare function NodePortMarkers(props: NodePortMarkersProps): JSX.Element;

package/lib/components/pisellFloorMapLayout/components/ViewControlsWithZoom.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 在 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;
+    edgesLayerVisible?: boolean;
+    onToggleEdgesLayer?: () => void;
+    /** 视口锁定态（true 时所有视角写入入口被禁用） */
+    viewportLocked?: boolean;
+    /** 切换视口锁定；未传时不展示锁定按钮 */
+    onToggleViewportLock?: () => void;
+    dockChrome?: boolean;
+    dockExpandedToolButtons?: React.ReactNode;
+    dockExpandedTrailing?: React.ReactNode;
+    autoCollapseDockMs?: number;
+}
+export declare function ViewControlsWithZoom(props: ViewControlsWithZoomProps): JSX.Element;