@pisell/materials 3.3.104 → 3.3.105

package/es/components/pisellLookup/hooks/useDebounceSearch.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 防抖搜索 Hook
+ */
+export interface UseDebounceSearchOptions {
+    /**
+     * 关键词
+     */
+    keyword: string;
+    /**
+     * 防抖时间（毫秒）
+     */
+    debounceTime: number;
+    /**
+     * 搜索触发回调
+     */
+    onSearch?: (keyword: string) => void;
+    /**
+     * 是否启用防抖
+     */
+    enabled?: boolean;
+    /**
+     * 上次搜索的关键词（用于去重）
+     */
+    lastSearchKeyword?: string;
+    /**
+     * 是否跳过防抖触发（用于手动选择场景）
+     */
+    skipDebounce?: boolean;
+}
+export interface UseDebounceSearchResult {
+    /**
+     * 防抖后的关键词
+     */
+    debouncedKeyword: string;
+}
+/**
+ * 防抖搜索 Hook
+ * 用于实时搜索模式的防抖处理
+ */
+export declare const useDebounceSearch: (options: UseDebounceSearchOptions) => UseDebounceSearchResult;

package/es/components/pisellLookup/hooks/useSearchState.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 搜索状态管理 Hook
+ */
+export interface UseSearchStateOptions {
+    /**
+     * 受控的关键词
+     */
+    value?: string;
+    /**
+     * 默认关键词
+     */
+    defaultValue?: string;
+    /**
+     * 受控的可见性
+     */
+    visible?: boolean;
+    /**
+     * 默认可见性
+     */
+    defaultVisible?: boolean;
+    /**
+     * 关键词变化回调
+     */
+    onChange?: (value: string) => void;
+    /**
+     * 可见性变化回调
+     */
+    onVisibleChange?: (visible: boolean) => void;
+    /**
+     * 打开回调
+     */
+    onOpen?: () => void;
+    /**
+     * 关闭回调
+     */
+    onClose?: () => void;
+}
+export interface UseSearchStateResult {
+    /**
+     * 当前关键词
+     */
+    keyword: string;
+    /**
+     * 设置关键词
+     */
+    setKeyword: (value: string) => void;
+    /**
+     * 是否可见
+     */
+    visible: boolean;
+    /**
+     * 设置可见性
+     */
+    setVisible: (visible: boolean) => void;
+    /**
+     * 打开
+     */
+    open: () => void;
+    /**
+     * 关闭
+     */
+    close: () => void;
+    /**
+     * 切换可见性
+     */
+    toggle: () => void;
+    /**
+     * 是否为受控的关键词
+     */
+    isControlledKeyword: boolean;
+    /**
+     * 是否为受控的可见性
+     */
+    isControlledVisible: boolean;
+}
+/**
+ * 搜索状态管理 Hook
+ * 支持受控和非受控模式
+ */
+export declare const useSearchState: (options: UseSearchStateOptions) => UseSearchStateResult;

package/es/components/pisellLookup/utils/storage.d.ts

@@ -0,0 +1,42 @@
+/**
+ * localStorage 工具函数
+ * 用于管理搜索历史的存储
+ */
+/**
+ * 从 localStorage 加载历史记录
+ * @param key 存储的 key
+ * @returns 历史记录数组
+ */
+export declare const loadHistory: (key: string) => string[];
+/**
+ * 保存历史记录到 localStorage
+ * @param key 存储的 key
+ * @param history 历史记录数组
+ * @param maxCount 最大数量限制
+ */
+export declare const saveHistory: (key: string, history: string[], maxCount: number) => void;
+/**
+ * 清除历史记录
+ * @param key 存储的 key
+ */
+export declare const clearHistory: (key: string) => void;
+/**
+ * 添加历史记录项
+ * @param key 存储的 key
+ * @param item 新的历史记录项
+ * @param maxCount 最大数量限制
+ * @returns 更新后的历史记录数组
+ */
+export declare const addHistoryItem: (key: string, item: string, maxCount: number) => string[];
+/**
+ * 删除历史记录项
+ * @param key 存储的 key
+ * @param item 要删除的历史记录项
+ * @returns 更新后的历史记录数组
+ */
+export declare const removeHistoryItem: (key: string, item: string) => string[];
+/**
+ * 检查 localStorage 是否可用
+ * @returns 是否可用
+ */
+export declare const isLocalStorageAvailable: () => boolean;

package/es/components/pisellMetricCard/components/MetricTitle.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { MetricTitleProps } from '../types';
+/**
+ * MetricTitle 标题组件
+ *
+ * 负责渲染标题、副标题和提示信息
+ * 支持自定义字号、字重、颜色等样式
+ *
+ * @param props 组件属性
+ */
+declare const MetricTitle: React.FC<MetricTitleProps>;
+export default MetricTitle;

package/es/components/pisellMetricCard/components/MetricValue.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { MetricValueProps } from '../types';
+/**
+ * MetricValue 数值展示组件
+ *
+ * 负责渲染格式化后的主数值
+ * 支持自定义字号、字重、颜色等样式
+ *
+ * @param props 组件属性
+ */
+declare const MetricValue: React.FC<MetricValueProps>;
+export default MetricValue;

package/es/components/pisellMetricCard/components/TrendIcon.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { TrendIconProps } from '../types';
+/**
+ * TrendIcon 趋势箭头组件
+ *
+ * 根据趋势类型显示上升或下降箭头
+ * - up: 显示上升箭头 ↑
+ * - down: 显示下降箭头 ↓
+ * - neutral: 不显示箭头
+ *
+ * @param props 组件属性
+ */
+declare const TrendIcon: React.FC<TrendIconProps>;
+export default TrendIcon;

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

@@ -0,0 +1,201 @@
+import type { CSSProperties, ReactNode } from 'react';
+/**
+ * 趋势类型
+ */
+export declare type TrendType = 'up' | 'down' | 'neutral';
+/**
+ * 数值格式化配置
+ */
+export interface ValueFormatConfig {
+    /** 小数精度（小数位数），默认 0 */
+    precision?: number;
+    /** 是否使用千分位分隔符，默认 false */
+    useGrouping?: boolean;
+    /** 是否显示货币符号，默认 false */
+    showCurrencySymbol?: boolean;
+    /** 货币符号（如 $, ¥），默认 '' */
+    currencySymbol?: string;
+    /** 自定义格式化函数 */
+    formatter?: (value: number | null) => string;
+    /** 整数时隐藏小数部分，默认 true */
+    hideDecimalForWholeNumbers?: boolean;
+}
+/**
+ * 环比配置
+ */
+export interface ComparisonConfig {
+    /** 环比数值（支持正负值） */
+    value: number | string | null;
+    /** 环比前缀文本，默认 'v.s. pre' */
+    text?: string;
+    /** 是否显示趋势箭头，默认 true */
+    showTrendIcon?: boolean;
+    /** 正向趋势颜色，默认 '#52c41a' */
+    positiveColor?: string;
+    /** 负向趋势颜色，默认 '#ff4d4f' */
+    negativeColor?: string;
+    /** 环比字号，默认 14 */
+    size?: number | string;
+}
+/**
+ * 样式配置
+ */
+export interface MetricCardStyleConfig {
+    /** 卡片容器样式 */
+    card?: {
+        /** 是否显示边框，默认 true */
+        bordered?: boolean;
+        /** 圆角大小（px），默认 12 */
+        borderRadius?: number;
+        /** 内边距（px），默认 16 */
+        padding?: number;
+        /** 阴影效果，默认 true */
+        shadow?: boolean | string;
+        /** 背景色，默认 '#ffffff' */
+        background?: string;
+        /** 卡片宽度，默认 'auto' */
+        width?: string | number;
+    };
+    /** 标题样式 */
+    title?: {
+        /** 字号，默认 14 */
+        size?: number | string;
+        /** 字重，默认 400 */
+        weight?: number | string;
+        /** 颜色，默认 'rgba(0, 0, 0, 0.45)' */
+        color?: string;
+    };
+    /** 数值样式 */
+    value?: {
+        /** 字号，默认 30 */
+        size?: number | string;
+        /** 字重，默认 600 */
+        weight?: number | string;
+        /** 颜色，默认 'rgba(0, 0, 0, 0.85)' */
+        color?: string;
+    };
+}
+/**
+ * PisellMetricCard 组件 Props
+ *
+ * 采用扁平 + 对象组合的设计，降低复杂度和耦合
+ *
+ * @example 基础用法
+ * ```tsx
+ * <PisellMetricCard
+ *   title="Total Sales"
+ *   value={1580}
+ * />
+ * ```
+ *
+ * @example 带格式化和环比
+ * ```tsx
+ * <PisellMetricCard
+ *   title="Revenue"
+ *   value={1580}
+ *   format={{
+ *     showCurrencySymbol: true,
+ *     currencySymbol: '$',
+ *     useGrouping: true
+ *   }}
+ *   comparison={{
+ *     value: 120,
+ *     text: 'v.s. last month'
+ *   }}
+ * />
+ * ```
+ */
+export interface PisellMetricCardProps {
+    /** 标题文本 */
+    title: string | ReactNode;
+    /** 主数值 */
+    value: number | string | null;
+    /** 副标题文本（可选） */
+    subtitle?: string | ReactNode;
+    /** 标签内容（可选） */
+    tag?: ReactNode;
+    /** 提示信息内容（可选） */
+    tooltip?: string | ReactNode;
+    /**
+     * 数值格式化配置
+     * @example format={{ precision: 2, useGrouping: true, currencySymbol: '$' }}
+     */
+    format?: ValueFormatConfig;
+    /**
+     * 环比配置
+     * @example comparison={{ value: 120, text: 'v.s. pre' }}
+     */
+    comparison?: ComparisonConfig;
+    /**
+     * 样式配置
+     * @example
+     * styleConfig={{
+     *   card: { borderRadius: 8, padding: 24 },
+     *   title: { size: 16, weight: 600 },
+     *   value: { size: 36, color: '#1890ff' }
+     * }}
+     */
+    styleConfig?: MetricCardStyleConfig;
+    /** 是否显示副标题，默认 false */
+    showSubtitle?: boolean;
+    /** 是否显示标签，默认 false */
+    showTag?: boolean;
+    /** 是否显示提示信息，默认 false */
+    showTooltip?: boolean;
+    /** 是否显示加载状态，默认 false */
+    loading?: boolean;
+    /** 鼠标悬停是否有交互效果，默认 true */
+    hoverable?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: CSSProperties;
+    /** 点击卡片回调 */
+    onClick?: () => void;
+}
+/**
+ * FormatOptions (别名，用于导出)
+ */
+export interface FormatOptions extends ValueFormatConfig {
+}
+/**
+ * MetricTitle 组件 Props
+ */
+export interface MetricTitleProps {
+    title: string | ReactNode;
+    subtitle?: string | ReactNode;
+    tooltip?: string | ReactNode;
+    titleSize?: number | string;
+    titleWeight?: number | string;
+    titleColor?: string;
+}
+/**
+ * MetricValue 组件 Props
+ */
+export interface MetricValueProps {
+    value: string | null;
+    valueSize?: number | string;
+    valueWeight?: number | string;
+    valueColor?: string;
+}
+/**
+ * MetricComparison 组件 Props
+ */
+export interface MetricComparisonProps {
+    comparison: number | string | null;
+    comparisonText?: string;
+    showTrendIcon?: boolean;
+    positiveColor?: string;
+    negativeColor?: string;
+    comparisonSize?: number | string;
+    precision?: number;
+    showCurrencySymbol?: boolean;
+    currencySymbol?: string;
+}
+/**
+ * TrendIcon 组件 Props
+ */
+export interface TrendIconProps {
+    trend: TrendType;
+    color?: string;
+}

package/es/components/pisellMetricCard/utils/calculateTrend.d.ts

@@ -0,0 +1,14 @@
+import type { TrendType } from '../types';
+/**
+ * 计算趋势方向
+ *
+ * @param comparison 环比数值
+ * @returns 'up' | 'down' | 'neutral'
+ *
+ * @example
+ * calculateTrend(120) // 'up'
+ * calculateTrend(-230) // 'down'
+ * calculateTrend(0) // 'neutral'
+ * calculateTrend(null) // 'neutral'
+ */
+export declare function calculateTrend(comparison: number | string | null | undefined): TrendType;

package/es/components/pisellMobileDateRangePicker/PisellMobileDateRangePicker.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { PisellMobileDateRangePickerProps } from './types';
+import 'antd-mobile/es/global/global.css';
+import './PisellMobileDateRangePicker.less';
+/**
+ * antd-mobile CalendarPicker（range）薄封装：受控 value/onChange 与 RecordBoard 快筛 dayjs[] 对齐。
+ */
+export declare const PisellMobileDateRangePicker: React.FC<PisellMobileDateRangePickerProps>;

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

@@ -0,0 +1,2 @@
+export { PisellMobileDateRangePicker } from './PisellMobileDateRangePicker';
+export type { PisellMobileDateRangePickerProps } from './types';

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

@@ -0,0 +1,28 @@
+import type { Dayjs } from 'dayjs';
+import type { CSSProperties, ReactNode } from 'react';
+import type { CalendarPickerProps } from 'antd-mobile';
+/** toolbar：顶栏快筛 32px；filter：Filter 弹层内与 Select 对齐的 48px 触发器 */
+export declare type PisellMobileDateRangePickerVariant = 'toolbar' | 'filter';
+export declare const PISELL_MOBILE_DATE_RANGE_PICKER_FILTER_POPUP_CLASS = "pisell-mobile-date-range-picker__popup";
+export interface PisellMobileDateRangePickerProps {
+    value?: unknown;
+    onChange?: (value: [Dayjs, Dayjs] | undefined) => void;
+    /** 展示格式，默认 DD/MM/YYYY */
+    format?: string;
+    placeholder?: string;
+    className?: string;
+    style?: CSSProperties;
+    title?: ReactNode;
+    confirmText?: string;
+    allowClear?: boolean;
+    min?: Date;
+    max?: Date;
+    /** 默认 toolbar；filter 用于手机 Filter 弹层 */
+    variant?: PisellMobileDateRangePickerVariant;
+    getContainer?: CalendarPickerProps['getContainer'];
+    popupClassName?: CalendarPickerProps['popupClassName'];
+    popupStyle?: CalendarPickerProps['popupStyle'];
+    /** Filter 弹层：日历打开时通知外层保持 Popover 不收起 */
+    onOpen?: () => void;
+    onClose?: () => void;
+}

package/es/components/pisellPercent/utils/rangeConverter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 百分比范围转换工具函数
+ */
+/**
+ * 将值转换为百分比（0-100）
+ *
+ * @param value 原始值
+ * @param range 值的范围
+ * @returns 转换后的百分比值（0-100）
+ *
+ * @example
+ * // [0, 100] 范围 - 直接返回
+ * convertToPercent(85.5, [0, 100])  // 返回: 85.5
+ *
+ * @example
+ * // [0, 1] 范围 - 乘以 100
+ * convertToPercent(0.855, [0, 1])  // 返回: 85.5
+ *
+ * @example
+ * // 自定义范围 - 按比例计算
+ * convertToPercent(855, [0, 1000])  // 返回: 85.5
+ */
+export declare function convertToPercent(value: number | null | undefined, range: [number, number]): number | null;
+/**
+ * 将百分比值转换回原始范围
+ *
+ * @param percent 百分比值（0-100）
+ * @param range 目标范围
+ * @returns 转换后的值
+ *
+ * @example
+ * convertFromPercent(85.5, [0, 100])  // 返回: 85.5
+ * convertFromPercent(85.5, [0, 1])    // 返回: 0.855
+ * convertFromPercent(85.5, [0, 1000]) // 返回: 855
+ */
+export declare function convertFromPercent(percent: number | null | undefined, range: [number, number]): number | null;

package/es/components/pisellPhone/utils/phoneFormatter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 电话号码格式化工具
+ */
+/**
+ * 中国大陆手机号格式化：138 0000 0000
+ */
+export declare function formatChinaMobile(phone: string): string;
+/**
+ * 美国/加拿大号码格式化：(555) 123-4567
+ */
+export declare function formatUSPhone(phone: string): string;
+/**
+ * 英国号码格式化：1234 567 8900
+ */
+export declare function formatUKPhone(phone: string): string;
+/**
+ * 根据国家码格式化电话号码
+ * @param phone 电话号码（纯数字）
+ * @param countryCode 国家码
+ * @returns 格式化后的电话号码
+ */
+export declare function formatPhone(phone: string, countryCode: string): string;
+/**
+ * 电话号码脱敏
+ * @param phone 电话号码
+ * @param pattern 脱敏模式
+ * @returns 脱敏后的号码
+ *
+ * @example
+ * maskPhone('13800000000', 'middle') // '138****0000'
+ * maskPhone('13800000000', 'last')   // '1380000****'
+ */
+export declare function maskPhone(phone: string, pattern?: 'middle' | 'last'): string;
+/**
+ * 检测号码类型（中国）
+ * @param phone 电话号码
+ * @returns 号码类型
+ */
+export declare function detectPhoneType(phone: string): 'mobile' | 'landline' | 'unknown';

package/es/components/pisellRecordBoard/shellFrame/Calendar/calendarI18n.d.ts

@@ -0,0 +1,4 @@
+/** 日历视图文案：占位符 `{name}`、`{date}` 等由调用方替换 */
+export declare function tCal(id: string, vars?: Record<string, string | number>): string;
+/** 月/周表头：周一为 0（与 rangeDays / startOfWeek 一致） */
+export declare const CALENDAR_WEEKDAY_IDS: readonly ["pisell2.recordBoard.calendar.weekday.mon", "pisell2.recordBoard.calendar.weekday.tue", "pisell2.recordBoard.calendar.weekday.wed", "pisell2.recordBoard.calendar.weekday.thu", "pisell2.recordBoard.calendar.weekday.fri", "pisell2.recordBoard.calendar.weekday.sat", "pisell2.recordBoard.calendar.weekday.sun"];

package/es/components/pisellRecordBoard/shellFrame/Calendar/calendarPersistGuard.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+/** 日历内会改本地预约数据的动作类型，供业务层拦截（如平面图未支持写接口时 toast） */
+export declare type CalendarPersistKind = 'moveBooking' | 'createBooking' | 'removeBlocks' | 'createBlock' | 'checkin' | 'checkinReschedule' | 'mergeOrder' | 'other';
+export interface CalendarPersistContextValue {
+    /**
+     * 返回 false 时日历组件应取消本次本地数据变更（由调用方决定是否已 toast）。
+     * 未提供时默认允许所有本地变更（Story / 独立演示）。
+     */
+    beforePersist?: (kind: CalendarPersistKind) => boolean;
+}
+export declare const CalendarPersistProvider: React.FC<{
+    children: React.ReactNode;
+    value?: CalendarPersistContextValue;
+}>;
+/**
+ * 在日历 Demo 内判断某类写操作是否允许执行本地 state 更新。
+ */
+export declare function useCalendarPersist(): (kind: CalendarPersistKind) => boolean;

package/es/components/pisellRecordBoard/shellFrame/ResourceWall/NoteTicker.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import './VenueWallMarquee.less';
+export interface NoteTickerProps {
+    text: string;
+    color: string;
+    /** 跑完一整段所需秒数 */
+    duration?: number;
+    shouldMarquee: boolean;
+}
+/**
+ * 底部说明条：短文案省略静态展示，长文案无缝跑马灯（多段 copy 与 `VenueWallMarquee.less` 中 -33.333% 动画配套）。
+ * 系统「减少动态效果」时强制静态展示；跑马灯区对读屏 `aria-hidden` 避免重复朗读。
+ */
+export declare const NoteTicker: React.NamedExoticComponent<NoteTickerProps>;

package/es/components/pisellRecordBoard/shellFrame/ResourceWall/ResourceWallViewportToolbar.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+export interface ResourceWallViewportToolbarProps {
+    now: Date;
+    appearanceMode: 'light' | 'dark';
+    onAppearanceModeChange: (m: 'light' | 'dark') => void;
+    pseudoFullscreen: boolean;
+    onTogglePseudoFullscreen: () => void;
+    onOpenControlPanel: () => void;
+    headerBorder: string;
+    headerBg: string;
+    clockColor: string;
+    mutedText: string;
+    toolbarBtnBorder: string;
+    toolbarBtnBg: string;
+    toolbarBtnBgActive: string;
+}
+/** 资源墙顶栏：时钟、浅深切换、伪全屏、控制台入口 */
+export declare const ResourceWallViewportToolbar: React.FC<ResourceWallViewportToolbarProps>;

package/es/components/pisellRecordBoard/shellFrame/ResourceWall/resourceWallConstants.d.ts

@@ -0,0 +1,2 @@
+/** 说明文案超过该长度时用跑马灯（与 NoteTicker / VenueWallCard 共用） */
+export declare const RESOURCE_WALL_NOTE_MARQUEE_MIN_CHARS = 32;

package/es/components/pisellRecordBoard/shellFrame/ToolBar/recordBoardToolBarConstants.d.ts

@@ -0,0 +1,8 @@
+/** 与 RecordBoard ToolBar 行为绑定的 searchParams 字段名 */
+export declare const DEFAULT_SEARCH_FIELD = "keyword";
+/** 筛选在 searchParams 中的字段名 */
+export declare const FILTER_PARAMS_FIELD = "filter";
+/** 排序在 searchParams 中的字段名 */
+export declare const SORT_PARAMS_FIELD = "sort";
+/** 与 ResourceWall 默认 `filterFieldKey` 一致 */
+export declare const RESOURCE_WALL_QUICK_FILTER_KEY = "resource_wall_resource_ids";

package/es/components/pisellReservationSchedule/locales.d.ts

@@ -0,0 +1,43 @@
+/** PisellReservationSchedule 多语言；使用前 locales.init 合并 */
+declare const _default: {
+    en: {
+        'pisell-reservation-schedule.today': string;
+        'pisell-reservation-schedule.prev': string;
+        'pisell-reservation-schedule.next': string;
+        'pisell-reservation-schedule.prev-week': string;
+        'pisell-reservation-schedule.next-week': string;
+        'pisell-reservation-schedule.prev-month': string;
+        'pisell-reservation-schedule.next-month': string;
+        'pisell-reservation-schedule.pick-date': string;
+        'pisell-reservation-schedule.pick-date-title': string;
+        'pisell-reservation-schedule.pick-week-title': string;
+        'pisell-reservation-schedule.pick-month-title': string;
+    };
+    'zh-CN': {
+        'pisell-reservation-schedule.today': string;
+        'pisell-reservation-schedule.prev': string;
+        'pisell-reservation-schedule.next': string;
+        'pisell-reservation-schedule.prev-week': string;
+        'pisell-reservation-schedule.next-week': string;
+        'pisell-reservation-schedule.prev-month': string;
+        'pisell-reservation-schedule.next-month': string;
+        'pisell-reservation-schedule.pick-date': string;
+        'pisell-reservation-schedule.pick-date-title': string;
+        'pisell-reservation-schedule.pick-week-title': string;
+        'pisell-reservation-schedule.pick-month-title': string;
+    };
+    'zh-HK': {
+        'pisell-reservation-schedule.today': string;
+        'pisell-reservation-schedule.prev': string;
+        'pisell-reservation-schedule.next': string;
+        'pisell-reservation-schedule.prev-week': string;
+        'pisell-reservation-schedule.next-week': string;
+        'pisell-reservation-schedule.prev-month': string;
+        'pisell-reservation-schedule.next-month': string;
+        'pisell-reservation-schedule.pick-date': string;
+        'pisell-reservation-schedule.pick-date-title': string;
+        'pisell-reservation-schedule.pick-week-title': string;
+        'pisell-reservation-schedule.pick-month-title': string;
+    };
+};
+export default _default;