@pisell/materials 6.11.16 → 6.11.17

package/lib/components/pisellPercent/types.d.ts

@@ -0,0 +1,68 @@
+import type { PisellNumberProps } from '../pisellNumber';
+import type { ProgressProps, SliderSingleProps } from 'antd';
+/**
+ * 从 @pisell/utils 重新导出公共类型
+ */
+export type { DisplayState, ValidationResult, NumberInputState, BaseNumberInputProps, } from '@pisell/utils';
+/**
+ * PisellPercent 组件 Props 类型定义
+ *
+ * 基于 PisellNumber 扩展，专门处理百分比数据
+ */
+export interface PisellPercentProps extends PisellNumberProps {
+    /**
+     * 是否显示百分号 %
+     * @default true
+     */
+    showPercentSymbol?: boolean;
+    /**
+     * 百分比范围
+     * @default [0, 100]
+     * @example [0, 100] - 常用范围，值直接作为百分比
+     * @example [0, 1] - 小数范围，值会乘以100转换
+     * @example [0, 1000] - 自定义范围，按比例转换
+     */
+    range?: [number, number];
+    /**
+     * 展示变体
+     * - text: 纯文本显示（如 85.5%）
+     * - progress: 进度条显示
+     * - circle: 环形进度显示
+     * @default 'text'
+     */
+    variant?: 'text' | 'progress' | 'circle';
+    /**
+     * 进度条额外配置（variant='progress' 时使用）
+     */
+    progressProps?: ProgressProps;
+    /**
+     * 环形进度额外配置（variant='circle' 时使用）
+     */
+    circleProps?: ProgressProps;
+    /**
+     * 编辑态是否显示滑块
+     * @default false
+     * @description 启用后，会在输入框上方显示滑块，便于快速调整
+     */
+    showSlider?: boolean;
+    /**
+     * 滑块额外配置
+     */
+    sliderProps?: SliderSingleProps;
+    /**
+     * 小数精度
+     * @default 1
+     * @description 百分比默认保留1位小数
+     */
+    precision?: number;
+    /**
+     * 最小值
+     * @default 0
+     */
+    min?: number;
+    /**
+     * 最大值
+     * @default 100
+     */
+    max?: number;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * PisellPercent 工具函数导出
+ */
+export { formatPercent } from './percentFormatter';
+export type { PercentFormatOptions } from './percentFormatter';
+export { convertToPercent, convertFromPercent } from './rangeConverter';

package/lib/components/pisellPercent/utils/percentFormatter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 百分比格式化选项
+ */
+export interface PercentFormatOptions {
+    /** 是否显示百分号 */
+    showPercentSymbol: boolean;
+    /** 小数精度 */
+    precision: number;
+    /** 百分比范围 */
+    range: [number, number];
+}
+/**
+ * 格式化百分比数值
+ *
+ * @param value 数值
+ * @param options 格式化选项
+ * @returns 格式化后的百分比字符串
+ *
+ * @example
+ * formatPercent(85.5, { showPercentSymbol: true, precision: 1, range: [0, 100] })
+ * // 返回: '85.5%'
+ *
+ * @example
+ * formatPercent(0.855, { showPercentSymbol: true, precision: 1, range: [0, 1] })
+ * // 返回: '85.5%'
+ */
+export declare function formatPercent(value: number | null | undefined, options: PercentFormatOptions): string | null;

package/lib/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/lib/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/lib/components/pisellPhone/PisellPhone.stories.d.ts

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellPhone } from './PisellPhone';
+/**
+ * PisellPhone 是一个电话号码输入/展示组件。
+ *
+ * ## 功能特性
+ * - 支持三种状态：只读、编辑、禁用
+ * - 国家码选择（预设24个常见国家）
+ * - 自动格式化
+ * - 格式校验
+ * - 移动端拨号
+ * - 号码脱敏
+ */
+declare const meta: Meta<typeof PisellPhone>;
+export default meta;
+declare type Story = StoryObj<typeof PisellPhone>;
+/**
+ * 基础编辑态（中国手机号）
+ */
+export declare const Basic: Story;
+/**
+ * 国家码选择器（显示所有国家）
+ */
+export declare const WithCountrySelector: Story;
+/**
+ * 国家码选择器（过滤显示）
+ */
+export declare const FilteredCountries: Story;
+/**
+ * 国家码选择器（常用国家置顶）
+ */
+export declare const CommonCountriesTop: Story;
+/**
+ * 只读态 - 格式化显示
+ */
+export declare const ReadMode: Story;
+/**
+ * 只读态 - 脱敏显示（中间）
+ */
+export declare const ReadModeMaskedMiddle: Story;
+/**
+ * 只读态 - 脱敏显示（末尾）
+ */
+export declare const ReadModeMaskedLast: Story;
+/**
+ * 只读态 - 可拨号（移动端）
+ */
+export declare const ReadModeDialable: Story;
+/**
+ * 禁用态
+ */
+export declare const Disabled: Story;
+/**
+ * 必填校验
+ */
+export declare const Required: Story;
+/**
+ * 格式校验
+ */
+export declare const FormatValidation: Story;
+/**
+ * 美国号码
+ */
+export declare const USPhone: Story;
+/**
+ * 自动格式化对比
+ */
+export declare const AutoFormatComparison: Story;
+/**
+ * 多国号码展示
+ */
+export declare const MultiCountryDisplay: Story;
+/**
+ * 脱敏模式对比
+ */
+export declare const MaskingComparison: Story;
+/**
+ * 完整功能示例
+ */
+export declare const CompleteExample: Story;

package/lib/components/pisellPhone/components/DisabledView.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { PisellPhoneProps } from '../types';
+/**
+ * PisellPhone 禁用态视图组件
+ *
+ * 负责渲染禁用态视图，基于原始 mode 渲染对应的视图，并添加禁用样式
+ *
+ * 设计规则：
+ * - 基于编辑态或只读态的视觉
+ * - 透明度 40%
+ * - 禁止所有交互行为（包括拨号）
+ *
+ * @param props 组件 Props
+ */
+declare const DisabledView: React.FC<PisellPhoneProps>;
+export default DisabledView;

package/lib/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/lib/components/pisellPhone/components/ReadOnlyView.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { PisellPhoneProps } from '../types';
+/**
+ * PisellPhone 只读态视图组件
+ *
+ * 负责渲染只读态的电话号码展示和拨号功能
+ *
+ * 功能：
+ * - 格式化或脱敏显示
+ * - 显示国旗图标（可选）
+ * - 移动端可点击拨号（tel: 协议）
+ * - 拨号图标（可选）
+ *
+ * @param props 组件 Props
+ */
+declare const ReadOnlyView: React.FC<PisellPhoneProps>;
+export default ReadOnlyView;

package/lib/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/lib/components/pisellPhone/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PisellPhone 组件导出
+ */
+import PisellPhone from './PisellPhone';
+export { PisellPhone };
+export type { PisellPhoneProps, CountryCode } from './types';
+export { PRESET_COUNTRY_CODES, DEFAULT_COUNTRY_CODE, COMMON_COUNTRY_CODES } from './constants/countryCodes';
+export type { DisplayState, ValidationResult, TextInputState } from './types';

package/lib/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';

package/lib/components/pisellPhone/utils/countryCodeHelper.d.ts

@@ -0,0 +1,35 @@
+import type { CountryCode, PisellPhoneProps } from '../types';
+/**
+ * 根据国家码获取国旗 emoji
+ * @param countryCode 国家码
+ * @returns 国旗 emoji
+ */
+export declare function getCountryFlag(countryCode: string): string;
+/**
+ * 根据国家码获取最大长度
+ * @param countryCode 国家码
+ * @param countryCodes 国家码列表
+ * @returns 最大长度
+ */
+export declare function getMaxLength(countryCode: string, countryCodes: CountryCode[]): number;
+/**
+ * 根据国家码获取配置
+ * @param countryCode 国家码
+ * @param countryCodes 国家码列表
+ * @returns 国家码配置
+ */
+export declare function getCountryConfig(countryCode: string, countryCodes: CountryCode[]): CountryCode | undefined;
+/**
+ * 获取最终的国家码列表
+ *
+ * 优先级：
+ * 1. props.countryCodes（完全自定义）
+ * 2. props.availableCountryCodes（从预设中过滤）
+ * 3. PRESET_COUNTRY_CODES（默认全部24个）
+ *
+ * 然后根据 props.commonCountryCodes 排序（置顶）
+ *
+ * @param props 组件 Props
+ * @returns 国家码列表
+ */
+export declare function getCountryCodes(props: PisellPhoneProps): CountryCode[];

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

@@ -0,0 +1,6 @@
+/**
+ * 电话号码工具函数导出
+ */
+export { formatPhone, formatChinaMobile, formatUSPhone, maskPhone, detectPhoneType } from './phoneFormatter';
+export { validatePhone } from './phoneValidator';
+export { getCountryFlag, getMaxLength, getCountryConfig, getCountryCodes, } from './countryCodeHelper';

package/lib/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/lib/components/pisellPhone/utils/phoneValidator.d.ts

@@ -0,0 +1,11 @@
+import type { CountryCode, PisellPhoneProps } from '../types';
+import type { ValidationResult } from '@pisell/utils';
+/**
+ * 电话号码校验
+ * @param phone 电话号码（纯数字）
+ * @param countryCode 国家码
+ * @param countryConfig 国家码配置
+ * @param props 组件 Props
+ * @returns 校验结果
+ */
+export declare function validatePhone(phone: string, countryCode: string, countryConfig: CountryCode | undefined, props: PisellPhoneProps): ValidationResult;

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

@@ -0,0 +1,11 @@
+import React from 'react';
+declare const pisellQuickFilter: React.ForwardRefExoticComponent<import("antd").FormInstance<any> & {
+    hasForm?: boolean | undefined;
+    children?: React.ReactNode;
+    formFiltersPrefix: string;
+    filterList?: import("../filter/types").FilterItemProps[] | undefined;
+    quickFilterMaxLength: number;
+    hiddenQuickFilter: boolean;
+    hiddenOtherFilter: boolean;
+} & React.RefAttributes<unknown>>;
+export default pisellQuickFilter;

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

@@ -0,0 +1,12 @@
+/// <reference types="react" />
+import { FilterItemProps } from '../filter/types';
+import { FormInstance } from 'antd';
+export declare type PisellQuickFilterProps = FormInstance & {
+    hasForm?: boolean;
+    children?: React.ReactNode;
+    formFiltersPrefix: string;
+    filterList?: FilterItemProps[];
+    quickFilterMaxLength: number;
+    hiddenQuickFilter: boolean;
+    hiddenOtherFilter: boolean;
+};