@pisell/materials 3.3.88 → 3.3.89

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

@@ -0,0 +1,42 @@
+import type { DisplayType, TriggerType } from '../types';
+/**
+ * 触发器相关工具函数
+ */
+/**
+ * 根据触发器类型获取默认的展示类型
+ * @param triggerType 触发器类型
+ * @param hasTrigger 是否有自定义触发器
+ * @returns 默认的展示类型
+ */
+export declare const getDefaultDisplayType: (triggerType?: TriggerType, hasTrigger?: boolean) => DisplayType;
+/**
+ * 判断是否为输入框触发器
+ * @param triggerType 触发器类型
+ * @returns 是否为输入框触发器
+ */
+export declare const isInputTrigger: (triggerType?: TriggerType) => boolean;
+/**
+ * 判断是否为按钮类触发器（button、icon、text、自定义）
+ * @param triggerType 触发器类型
+ * @param hasTrigger 是否有自定义触发器
+ * @returns 是否为按钮类触发器
+ */
+export declare const isButtonLikeTrigger: (triggerType?: TriggerType, hasTrigger?: boolean) => boolean;
+/**
+ * 判断展示类型是否需要容器（modal、drawer）
+ * @param displayType 展示类型
+ * @returns 是否需要容器
+ */
+export declare const needsContainer: (displayType?: DisplayType) => boolean;
+/**
+ * 判断展示类型是否需要浮层（popup）
+ * @param displayType 展示类型
+ * @returns 是否需要浮层
+ */
+export declare const needsPopup: (displayType?: DisplayType) => boolean;
+/**
+ * 判断展示类型是否为内联（inline）
+ * @param displayType 展示类型
+ * @returns 是否为内联
+ */
+export declare const isInline: (displayType?: DisplayType) => 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/pisellMultipleSelect/PisellMultipleSelect.d.ts

@@ -0,0 +1,9 @@
+/**
+ * PisellMultipleSelect - 多选下拉组件
+ * 基于 Ant Design Select 封装，提供符合 Pisell 设计规范的多选功能
+ */
+import React from 'react';
+import type { PisellMultipleSelectProps, MultipleSelectRef } from './types';
+import './PisellMultipleSelect.less';
+declare const PisellMultipleSelect: React.ForwardRefExoticComponent<PisellMultipleSelectProps<string | number> & React.RefAttributes<MultipleSelectRef<string | number>>>;
+export default PisellMultipleSelect;

package/es/components/pisellMultipleSelect/components/EditView.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PisellMultipleSelect - EditView (编辑态视图)
+ * 正常可编辑状态下的渲染
+ */
+import React from 'react';
+import type { EditViewProps } from '../types';
+declare const EditView: React.ForwardRefExoticComponent<EditViewProps<string | number> & React.RefAttributes<any>>;
+export default EditView;

package/es/components/pisellNumber/PisellNumber.d.ts

@@ -0,0 +1,42 @@
+import React from 'react';
+import type { PisellNumberProps } from './types';
+import './PisellNumber.less';
+/**
+ * PisellNumber 数值组件
+ *
+ * 通用的数值输入/展示组件，支持只读、编辑、禁用三种状态。
+ * 基于 Ant Design InputNumber 组件开发，提供完整的校验框架。
+ *
+ * @param props 组件 Props
+ *
+ * @example
+ * // 受控模式
+ * const [value, setValue] = useState(0);
+ * <PisellNumber
+ *   value={value}
+ *   onChange={setValue}
+ *   min={0}
+ *   max={100}
+ * />
+ *
+ * @example
+ * // 非受控模式
+ * <PisellNumber
+ *   defaultValue={10}
+ *   min={0}
+ *   max={999}
+ *   step={10}
+ * />
+ *
+ * @example
+ * // 只读态
+ * <PisellNumber
+ *   mode="read"
+ *   value={1234.567}
+ *   precision={2}
+ *   useGrouping
+ * />
+ */
+export declare const PisellNumber: React.FC<PisellNumberProps>;
+declare const MemoizedPisellNumber: React.NamedExoticComponent<PisellNumberProps>;
+export default MemoizedPisellNumber;

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

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { PisellPhoneProps } from './types';
+import './PisellPhone.less';
+/**
+ * PisellPhone 电话号码组件
+ *
+ * 电话号码输入/展示组件，支持只读、编辑、禁用三种状态。
+ * 基于 Ant Design Input 和 Select 组件开发，提供国家码选择、自动格式化、格式校验和拨号功能。
+ *
+ * @param props 组件 Props
+ *
+ * @example
+ * // 编辑态（中国手机号）
+ * <PisellPhone
+ *   placeholder="请输入手机号"
+ *   required
+ * />
+ *
+ * @example
+ * // 只读态（可拨号）
+ * <PisellPhone
+ *   mode="read"
+ *   value="13800000000"
+ *   countryCode="+86"
+ * />
+ *
+ * @example
+ * // 国家码选择
+ * <PisellPhone
+ *   showCountrySelector
+ *   availableCountryCodes={['+86', '+1', '+44']}
+ * />
+ */
+export declare const PisellPhone: React.FC<PisellPhoneProps>;
+declare const _default: React.NamedExoticComponent<PisellPhoneProps>;
+export default _default;

package/es/components/pisellPhone/components/EditView.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+import type { PisellPhoneProps } from '../types';
+/**
+ * PisellPhone 编辑态视图组件
+ *
+ * 负责渲染编辑态的电话号码输入，包含国家码选择器和号码输入框
+ *
+ * 功能：
+ * - 国家码选择器（下拉，支持搜索）
+ * - 电话号码输入（只保留数字）
+ * - 自动格式化（根据国家码）
+ * - 动态设置最大长度（根据国家码）
+ * - 实时或失焦校验
+ * - 错误提示展示
+ *
+ * @param props 组件 Props
+ */
+declare const EditView: React.FC<PisellPhoneProps>;
+export default EditView;

package/es/components/pisellPhone/constants/countryCodes.d.ts

@@ -0,0 +1,20 @@
+import type { CountryCode } from '../types';
+/**
+ * 预设的国家码列表（24个常见国家）
+ *
+ * 包含：
+ * - 亚洲：中国、香港、澳门、台湾、日本、韩国、新加坡、马来西亚、泰国、印度
+ * - 欧洲：英国、法国、德国、意大利、西班牙、俄罗斯
+ * - 美洲：美国、加拿大、墨西哥、巴西
+ * - 大洋洲：澳大利亚、新西兰
+ * - 中东：阿联酋、沙特阿拉伯
+ */
+export declare const PRESET_COUNTRY_CODES: CountryCode[];
+/**
+ * 默认国家码
+ */
+export declare const DEFAULT_COUNTRY_CODE = "+86";
+/**
+ * 常用国家码（可作为默认的 commonCountryCodes）
+ */
+export declare const COMMON_COUNTRY_CODES: string[];

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

@@ -0,0 +1,209 @@
+import type { CSSProperties } from 'react';
+import type { BaseTextInputProps } from '@pisell/utils';
+/**
+ * 国家码配置类型
+ */
+export interface CountryCode {
+    /**
+     * 国家码
+     * @example '+86', '+1', '+44'
+     */
+    code: string;
+    /**
+     * 国家名称
+     * @example '中国', '美国', '英国'
+     */
+    name: string;
+    /**
+     * 国旗 emoji 或图标
+     * @example '🇨🇳', '🇺🇸', '🇬🇧'
+     */
+    flag: string;
+    /**
+     * 号码格式（可选，用于显示占位符）
+     * @example 'XXX XXXX XXXX', '(XXX) XXX-XXXX'
+     */
+    format?: string;
+    /**
+     * 最大长度
+     * @example 11 (中国), 10 (美国)
+     */
+    maxLength: number;
+    /**
+     * 校验正则
+     * @example /^1[3-9]\d{9}$/ (中国手机号)
+     */
+    pattern: RegExp;
+}
+/**
+ * PisellPhone 组件 Props 类型定义
+ *
+ * 继承 BaseTextInputProps，添加电话号码特有的配置
+ */
+export interface PisellPhoneProps extends BaseTextInputProps {
+    /**
+     * 状态模式
+     * @default 'edit'
+     */
+    mode?: 'read' | 'edit';
+    /**
+     * 是否禁用
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 当前选中的国家码
+     * @default '+86'
+     * @example '+86', '+1', '+44'
+     */
+    countryCode?: string;
+    /**
+     * 默认国家码（非受控模式）
+     * @default '+86'
+     */
+    defaultCountryCode?: string;
+    /**
+     * 是否显示国家码选择器
+     * @default true
+     */
+    showCountrySelector?: boolean;
+    /**
+     * 可用的国家码列表（从预设24个中过滤）
+     * @example ['+86', '+1', '+44']
+     */
+    availableCountryCodes?: string[];
+    /**
+     * 常用国家码（置顶显示）
+     * @example ['+86', '+1']
+     */
+    commonCountryCodes?: string[];
+    /**
+     * 完全自定义国家码列表（覆盖预设）
+     */
+    countryCodes?: CountryCode[];
+    /**
+     * 国家码变更回调
+     * @param code 新的国家码
+     */
+    onCountryCodeChange?: (code: string) => void;
+    /**
+     * 是否自动格式化
+     * @default true
+     */
+    autoFormat?: boolean;
+    /**
+     * 格式化规则
+     * @default 'auto'
+     */
+    formatRule?: 'mobile' | 'landline' | 'auto';
+    /**
+     * 格式化分隔符
+     * @default ' '
+     */
+    separator?: string;
+    /**
+     * 是否启用拨号（移动端）
+     * @default true
+     */
+    enableDial?: boolean;
+    /**
+     * 是否显示拨号图标
+     * @default false
+     */
+    showDialIcon?: boolean;
+    /**
+     * 拨号回调
+     * @param phone 完整的电话号码（含国家码）
+     */
+    onDial?: (phone: string) => void;
+    /**
+     * 是否脱敏显示（只读态）
+     * @default false
+     */
+    enableMasking?: boolean;
+    /**
+     * 脱敏模式
+     * - middle: 中间4位脱敏（138****0000）
+     * - last: 后4位脱敏（1380000****）
+     * - custom: 使用自定义函数
+     * @default 'middle'
+     */
+    maskPattern?: 'middle' | 'last' | 'custom';
+    /**
+     * 自定义脱敏函数
+     * @param phone 电话号码
+     * @returns 脱敏后的号码
+     */
+    customMask?: (phone: string) => string;
+    /**
+     * 是否显示国旗图标
+     * @default true
+     */
+    showFlag?: boolean;
+    /**
+     * 字号
+     * @example '14px' 或 14
+     * @default 16
+     */
+    fontSize?: string | number;
+    /**
+     * 字重
+     * @example 'bold' 或 600
+     * @default 500
+     */
+    fontWeight?: string | number;
+    /**
+     * 文本颜色
+     * @example '#000000'
+     * @default '#101828'
+     */
+    color?: string;
+    /**
+     * 占位文本
+     * @default '请输入电话号码'
+     */
+    placeholder?: string;
+    /**
+     * 最大长度（根据国家码自动设置）
+     */
+    maxLength?: number;
+    /**
+     * 是否显示清空按钮
+     * @default false
+     */
+    allowClear?: boolean;
+    /**
+     * 是否自动聚焦
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * 是否校验格式
+     * @default true
+     */
+    validateFormat?: boolean;
+    /**
+     * 自定义校验函数
+     * @param phone 电话号码（纯数字）
+     * @param countryCode 国家码
+     * @returns true 表示校验通过，string 表示错误信息
+     */
+    customValidator?: (phone: string, countryCode: string) => boolean | string;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * ARIA 标签
+     */
+    'aria-label'?: string;
+    /**
+     * ARIA 描述
+     */
+    'aria-describedby'?: string;
+}
+export type { DisplayState, ValidationResult, TextInputState } from '@pisell/utils';