@pisell/materials 3.3.104 → 3.3.105

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

@@ -0,0 +1,352 @@
+import type { CSSProperties } from 'react';
+import type { Dayjs } from 'dayjs';
+/**
+ * 布局方向
+ * - horizontal: 水平布局（默认）- 时间在上，日期+星期在下
+ * - vertical: 垂直布局 - 时间、日期、星期分别独立成行
+ * - inline: 单行布局 - 所有信息横向排列，用分隔符连接
+ */
+export declare type LayoutDirection = 'horizontal' | 'vertical' | 'inline';
+/**
+ * 日期顺序
+ * - YMD: 年-月-日（如：2026-03-21）
+ * - MDY: 月-日-年（如：Mar 21, 2026）
+ * - DMY: 日-月-年（如：21 Mar 2026）
+ */
+export declare type DateOrder = 'YMD' | 'MDY' | 'DMY';
+/**
+ * 对齐方式
+ */
+export declare type TextAlign = 'left' | 'center' | 'right';
+/**
+ * 字段类型
+ */
+export declare type FieldType = 'time' | 'date' | 'weekday';
+/**
+ * 时间格式配置
+ */
+export interface TimeFormatConfig {
+    /**
+     * 是否使用12小时制
+     * @default false
+     * @example true -> "1:45 PM" | false -> "13:45"
+     */
+    use12Hour?: boolean;
+    /**
+     * 是否显示秒
+     * @default false
+     * @example true -> "13:45:30" | false -> "13:45"
+     */
+    showSeconds?: boolean;
+    /**
+     * 小时是否补零
+     * @default false
+     * @example true -> "01:45 PM" | false -> "1:45 PM"
+     */
+    padHour?: boolean;
+    /**
+     * 是否只显示小时
+     * @default false
+     * @example true -> "13" | false -> "13:45"
+     */
+    onlyShowHour?: boolean;
+}
+/**
+ * 日期格式配置
+ */
+export interface DateFormatConfig {
+    /**
+     * 日期顺序
+     * @default 'YMD'
+     */
+    order?: DateOrder;
+    /**
+     * 英文月份是否简写
+     * @default true
+     * @example true -> "Mar" | false -> "March"
+     */
+    shortMonth?: boolean;
+    /**
+     * 英文月份是否数字展示
+     * @default false
+     * @example true -> "03" | false -> "Mar"
+     */
+    numericMonth?: boolean;
+    /**
+     * 中文是否显示"年月日"汉字
+     * @default false
+     * @example true -> "2026年3月21日" | false -> "2026-03-21"
+     */
+    showChineseUnit?: boolean;
+    /**
+     * 分隔符
+     * @default '-'
+     * @example '-' -> "2026-03-21" | '/' -> "2026/03/21"
+     */
+    separator?: string;
+    /**
+     * 是否显示年
+     * @default false
+     */
+    showYear?: boolean;
+    /**
+     * 是否显示月
+     * @default true
+     */
+    showMonth?: boolean;
+    /**
+     * 是否显示日
+     * @default true
+     */
+    showDay?: boolean;
+    /**
+     * 英文 DMY 时年月之间是否加逗号（如 21 Mar, 2026；false 时为 22 Jan 2025）
+     * @default true
+     */
+    useCommaBeforeYear?: boolean;
+    /**
+     * 是否在「今天/昨天/明天」时用相对日替换具体日期
+     * 开启后：与参考日同天显示「今天」，前一天「昨天」，后一天「明天」；其他日期仍按原格式
+     * @default false
+     */
+    showRelativeDay?: boolean;
+    /**
+     * 相对日文案覆盖（用于 i18n 或自定义）
+     * 不传时按 locale 使用默认：zh 今天/昨天/明天，en Today/Yesterday/Tomorrow
+     */
+    relativeDayLabels?: {
+        today?: string;
+        yesterday?: string;
+        tomorrow?: string;
+    };
+}
+/**
+ * 星期格式配置
+ */
+export interface WeekdayFormatConfig {
+    /**
+     * 是否完整展示
+     * @default false
+     * @example true -> "Saturday" / "星期六" | false -> "Sat" / "周六"
+     */
+    full?: boolean;
+    /**
+     * 是否单字母展示
+     * @default false
+     * @example true -> "S" / "六" | false -> "Sat" / "周六"
+     */
+    singleLetter?: boolean;
+    /**
+     * 是否在星期后加逗号（用于与日期拼接如 "Sat, 21 Mar, 2026"）
+     * @default false
+     */
+    trailingComma?: boolean;
+}
+/**
+ * 字段配置
+ */
+export interface FieldConfig {
+    /**
+     * 是否显示时间字段
+     * @default true
+     */
+    showTime?: boolean;
+    /**
+     * 是否显示日期字段
+     * @default true
+     */
+    showDate?: boolean;
+    /**
+     * 是否显示星期字段
+     * @default true
+     */
+    showWeekday?: boolean;
+    /**
+     * 字段顺序
+     * @default ['time', 'date', 'weekday']
+     */
+    fieldOrder?: FieldType[];
+    /**
+     * 单行布局时每段之间的分隔符，按顺序对应字段之间
+     * 如 ['date','time','weekday'] 配 inlineSeparators: [' - ', ' '] => "2025-12-31 - 2:00 周四"
+     * 不足时用组件 inlineSeparator 补齐
+     */
+    inlineSeparators?: string[];
+}
+/**
+ * 文本样式配置
+ */
+export interface TextStyleConfig {
+    /**
+     * 字体大小
+     * @example 14 | '14px' | '1rem'
+     */
+    fontSize?: number | string;
+    /**
+     * 字体粗细
+     * @example 400 | '400' | 'bold'
+     */
+    fontWeight?: number | string;
+    /**
+     * 字体颜色
+     * @example '#000' | 'rgba(0, 0, 0, 0.85)'
+     */
+    color?: string;
+    /**
+     * 行高
+     * @example 1.5 | '1.5' | '24px'
+     */
+    lineHeight?: number | string;
+}
+/**
+ * 容器样式配置
+ */
+export interface ContainerStyleConfig {
+    /**
+     * 背景色
+     * @example '#fff' | 'transparent'
+     */
+    background?: string;
+    /**
+     * 圆角
+     * @example 8 | '8px'
+     */
+    borderRadius?: number | string;
+    /**
+     * 边框
+     * @example '1px solid #ddd'
+     */
+    border?: string;
+    /**
+     * 阴影
+     * @example '0 2px 8px rgba(0, 0, 0, 0.1)'
+     */
+    boxShadow?: string;
+    /**
+     * 内边距
+     * @example 16 | '16px' | '16px 24px'
+     */
+    padding?: number | string;
+    /**
+     * 间距（子元素之间的间距）
+     * @example 8 | '8px'
+     */
+    gap?: number | string;
+}
+/**
+ * 多语言格式预设（日期/时间/星期 + 字段顺序与分隔符）
+ * 用于 formatByLocale[locale] 或默认多语言配置
+ */
+export interface DateTimeDisplayFormatPreset {
+    dateFormat?: DateFormatConfig;
+    timeFormat?: TimeFormatConfig;
+    weekdayFormat?: WeekdayFormatConfig;
+    fields?: FieldConfig;
+}
+/**
+ * PisellDateTimeDisplay 组件 Props
+ */
+export interface PisellDateTimeDisplayProps {
+    /**
+     * 传入时展示该时间，不传则展示当前时间（并可按 refreshInterval 刷新）
+     * @description 用于表格列、详情等展示给定时间；支持 dayjs、时间戳、ISO 字符串
+     */
+    value?: Dayjs | string | number;
+    /**
+     * 布局方向
+     * @default 'horizontal'
+     */
+    layout?: LayoutDirection;
+    /**
+     * 文本对齐方式
+     * @default 'center'
+     */
+    textAlign?: TextAlign;
+    /**
+     * 字段显示配置
+     */
+    fields?: FieldConfig;
+    /**
+     * 多语言格式配置：按 locale 取对应格式预设，再与下方单项配置合并（单项优先）
+     * @example formatByLocale={{ 'zh-cn': { dateFormat: {...}, fields: { fieldOrder: ['date','time','weekday'], inlineSeparators: [' - ', ' '] } }, 'en': {...} }}
+     */
+    formatByLocale?: Record<string, Partial<DateTimeDisplayFormatPreset>>;
+    /**
+     * 时间格式配置
+     */
+    timeFormat?: TimeFormatConfig;
+    /**
+     * 日期格式配置
+     */
+    dateFormat?: DateFormatConfig;
+    /**
+     * 星期格式配置
+     */
+    weekdayFormat?: WeekdayFormatConfig;
+    /**
+     * 自定义格式化字符串（优先级最高，类似 dayjs().format()）
+     * @example 'YYYY-MM-DD HH:mm:ss' | 'MM/DD/YYYY'
+     * @description 当设置此属性时，其他格式化配置将被忽略
+     */
+    customFormat?: string;
+    /**
+     * 单行模式分隔符
+     * @default ' · '
+     * @example ' | ' | ' - '
+     */
+    inlineSeparator?: string;
+    /**
+     * 容器样式
+     */
+    containerStyle?: ContainerStyleConfig;
+    /**
+     * 时间文本样式
+     */
+    timeStyle?: TextStyleConfig;
+    /**
+     * 日期文本样式
+     */
+    dateStyle?: TextStyleConfig;
+    /**
+     * 星期文本样式
+     */
+    weekdayStyle?: TextStyleConfig;
+    /**
+     * 自定义刷新间隔（毫秒）
+     * @description 不设置则根据 showSeconds 自动判断（显示秒=1000ms，否则=60000ms）
+     * @example 1000 | 5000 | 60000
+     */
+    refreshInterval?: number;
+    /**
+     * 是否禁用自动刷新
+     * @default false
+     * @description 设置为 true 时，组件只显示初始时间，不会自动更新
+     */
+    disableAutoRefresh?: boolean;
+    /**
+     * dayjs locale（语言代码）
+     * @default 优先使用全局配置（usePisellConfig），其次使用 i18n 当前语言（getCurrentLocale：全局配置 / umi_locale）
+     * @example 'zh-CN' | 'zh-HK' | 'en' | 'en-US' | 'ja'
+     * @description
+     * - 支持标准 BCP 47 语言代码，会自动标准化为 dayjs 兼容格式
+     * - 优先级：组件 locale 属性 > PisellConfigProvider 全局配置 > i18n 当前语言
+     */
+    locale?: string;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * 时间更新回调
+     * @param currentTime 当前时间（Dayjs 对象）
+     */
+    onTimeUpdate?: (currentTime: Dayjs) => void;
+    /**
+     * 点击回调
+     */
+    onClick?: () => void;
+}

package/es/components/pisellDateTimeDisplay/utils/formatTime.d.ts

@@ -0,0 +1,19 @@
+import type { Dayjs } from 'dayjs';
+import type { TimeFormatConfig } from '../types';
+/**
+ * 格式化时间
+ * @param time dayjs 时间对象
+ * @param config 时间格式配置
+ * @returns 格式化后的时间字符串
+ *
+ * @example
+ * formatTime(dayjs(), { use12Hour: false, showSeconds: false, padHour: false })
+ * // => "13:45"
+ *
+ * formatTime(dayjs(), { use12Hour: true, showSeconds: false, padHour: true })
+ * // => "01:45 PM"
+ *
+ * formatTime(dayjs(), { use12Hour: false, showSeconds: true, padHour: false })
+ * // => "13:45:30"
+ */
+export declare function formatTime(time: Dayjs, config?: TimeFormatConfig): string;

package/es/components/pisellDateTimeDisplay/utils/getRefreshInterval.d.ts

@@ -0,0 +1,18 @@
+import type { TimeFormatConfig } from '../types';
+/**
+ * 根据时间格式配置计算刷新间隔
+ * @param timeFormat 时间格式配置
+ * @returns 刷新间隔（毫秒）
+ *
+ * @description
+ * - 显示秒时：1000ms (1秒刷新一次)
+ * - 不显示秒时：60000ms (60秒刷新一次)
+ *
+ * @example
+ * getRefreshInterval({ showSeconds: true })
+ * // => 1000
+ *
+ * getRefreshInterval({ showSeconds: false })
+ * // => 60000
+ */
+export declare function getRefreshInterval(timeFormat?: TimeFormatConfig): number;

package/es/components/pisellEmail/constants/emailDomains.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 常用邮箱域名列表
+ * 用于域名自动补全功能
+ */
+export declare const COMMON_EMAIL_DOMAINS: string[];

package/es/components/pisellEmail/constants/emailRegex.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 邮箱正则表达式常量
+ */
+/**
+ * 标准邮箱格式正则
+ * 覆盖99%的常见邮箱格式
+ */
+export declare const EMAIL_REGEX: RegExp;
+/**
+ * 严格邮箱格式正则（RFC 5322）
+ * 支持更复杂的邮箱格式，符合 RFC 5322 标准
+ */
+export declare const STRICT_EMAIL_REGEX: RegExp;

package/es/components/pisellEmail/utils/domainSuggestions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 域名补全工具函数（框架占位符）
+ * TODO: 实现完整的补全逻辑
+ */
+/**
+ * 获取邮箱域名补全建议
+ * @param input 用户输入
+ * @param domains 域名列表
+ * @returns 补全建议列表
+ *
+ * @example
+ * getEmailSuggestions('user@g', COMMON_EMAIL_DOMAINS)
+ * // 返回: ['user@gmail.com']
+ */
+export declare function getEmailSuggestions(input: string, domains?: string[]): string[];

package/es/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/es/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/es/components/pisellFloorMapLayout/floorMapLayoutConstants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 平面图布局根节点 BEM 前缀，与 `PisellFloorMapLayout.less` 中主 class 一致。
+ */
+export declare const FLOOR_MAP_LAYOUT_CLASS_PREFIX = "pisell-floor-map-layout";
+/** 手机左侧图元栏 Drawer，低于右侧属性抽屉 */
+export declare const FLOOR_MAP_PHONE_TOOLBAR_DRAWER_Z_INDEX = 2001;
+/** 手机右侧图元详情 Drawer */
+export declare const FLOOR_MAP_PHONE_EDIT_DRAWER_Z_INDEX = 2002;
+/**
+ * 高于 {@link FLOOR_MAP_PHONE_EDIT_DRAWER_Z_INDEX}，用于面板内 Popconfirm 等，避免被抽屉挡住。
+ */
+export declare const FLOOR_MAP_CONFIRM_OVERLAY_Z_INDEX = 2100;
+/**
+ * 「全览」伪画布 Tab id。
+ * 仅在阅读态、启用画布 > 1 时插入到画布 Tab 列表末尾，用来承载「同时查看所有画布」的入口。
+ * 不会写入 `config.canvases`，也不参与视口持久化、items 计算等真实画布逻辑。
+ */
+export declare const FLOOR_MAP_OVERVIEW_TAB_ID = "__pisell_floor_map_overview__";
+/**
+ * 全览视图：每个画布区块上方预留的标题带高度（像素）。
+ * 装箱时计入画布有效高度，保证画布之间的 gap 能容纳外置标题条。
+ */
+export declare const FLOOR_MAP_OVERVIEW_TITLE_BAND_HEIGHT = 36;
+/** 全览视图：画布区块之间的最小间距（像素，含标题带外的净距） */
+export declare const FLOOR_MAP_OVERVIEW_AREA_GAP = 40;
+/**
+ * 编辑态侧栏调色板：每个分类直接展示的图元数量上限。
+ * 超出时显示「查看全部」，在弹窗内选择数量并批量落点（所有分类通用）。
+ */
+export declare const FLOOR_MAP_TOOLBAR_PALETTE_SIDEBAR_LIMIT = 5;
+/**
+ * 右下 ViewControls Dock 底部留白（px）：`bottom: 14` + chrome `56` + 与面板间距 `8`。
+ * 编辑/连线属性面板滚动区 `padding-bottom` 引用同名 CSS 变量。
+ */
+export declare const FLOOR_MAP_VIEWPORT_DOCK_BOTTOM_CLEARANCE = 78;

package/es/components/pisellFloorMapLayout/hooks/floorMapViewportPersistence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 平面图视口缓存：localStorage 读写、锁定态；供 useFloorMapTransformMetrics 使用。
+ */
+/** 平面图包围盒单侧默认外扩（像素）；过大会导致首屏大量空白 */
+export declare const DEFAULT_BOUNDING_PADDING = 56;
+/** 视口内与首屏对齐时，图元束左上与容器边缘的留白 */
+export declare const VIEWPORT_TOP_LEFT_MARGIN = 16;
+/** 平面图视口（缩放 + 平移）持久化到 localStorage 的 key 前缀 */
+export declare const VIEWPORT_STORAGE_PREFIX = "pisell-floor-map-layout.viewport:";
+/** 视口锁定态持久化前缀（与视口位置分开存储） */
+export declare const VIEWPORT_LOCK_STORAGE_PREFIX = "pisell-floor-map-layout.viewport-lock:";
+/** 视口持久化写入节流（避免拖动 / 缩放过程中高频写 localStorage） */
+export declare const VIEWPORT_PERSIST_DEBOUNCE_MS = 300;
+/** 判定当前 transform 是否处于「适配视口」结果时的容差 */
+export declare const FIT_BOUNDS_MATCH_POS_EPSILON = 0.5;
+export declare const FIT_BOUNDS_MATCH_SCALE_EPSILON = 0.005;
+export interface ViewportSnapshot {
+    x: number;
+    y: number;
+    scale: number;
+}
+export declare function readPersistedViewport(key: string): ViewportSnapshot | null;
+export declare function writePersistedViewport(key: string, snapshot: ViewportSnapshot): void;
+export declare function readPersistedViewportLock(key: string): boolean;
+export declare function writePersistedViewportLock(key: string, locked: boolean): void;

package/es/components/pisellFloorMapLayout/hooks/useDraftConfigHistory.d.ts

@@ -0,0 +1,18 @@
+export interface DraftHistoryCommitOptions {
+    /** 同一 groupId 在合并窗口内连续提交将合并为一条历史 */
+    groupId?: string;
+    /** 合并窗口（毫秒），默认 600 */
+    mergeWindowMs?: number;
+}
+export interface DraftHistory<T> {
+    present: T | null;
+    /** 写入并入栈（按 group/time 自动合并） */
+    commit: (next: T | null | ((prev: T | null) => T | null), options?: DraftHistoryCommitOptions) => void;
+    /** 重置（不入栈），清空历史；用于上游 props 同步 */
+    replace: (next: T | null) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+}
+export declare function useDraftConfigHistory<T>(): DraftHistory<T>;

package/es/components/pisellFloorMapLayout/hooks/useFloorMapPaletteTouchDrag.d.ts

@@ -0,0 +1,21 @@
+import type { MutableRefObject, PointerEvent as ReactPointerEvent } from 'react';
+import type { FloorMapPaletteDragPayload } from '../utils/floorMapDropUtils';
+export interface UseFloorMapPaletteTouchDragParams {
+    enabled: boolean;
+    mapDropLayerRef: MutableRefObject<HTMLDivElement | null>;
+    contentWidth: number;
+    contentHeight: number;
+    contentOffsetRef: MutableRefObject<{
+        x: number;
+        y: number;
+    }>;
+    setMapPaletteDragActive: (v: boolean) => void;
+    onDropInScene: (payload: FloorMapPaletteDragPayload, sceneX: number, sceneY: number) => void;
+}
+export interface UseFloorMapPaletteTouchDragResult {
+    /** 挂在图元预览按钮上；mouse 不处理，交给 HTML5 DnD */
+    handlePaletteCardPointerDown: (payload: FloorMapPaletteDragPayload, e: ReactPointerEvent<HTMLElement>) => void;
+    /** 图元按钮 onClick 前检查：触摸拖放过则吞掉本次点击 */
+    consumeToolbarClickIfTouchDrag: () => boolean;
+}
+export declare function useFloorMapPaletteTouchDrag(params: UseFloorMapPaletteTouchDragParams): UseFloorMapPaletteTouchDragResult;