@pisell/materials 1.8.23 → 1.8.24

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

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { PisellNumberProps } from '../types';
+/**
+ * PisellNumber 编辑态视图组件
+ *
+ * 负责渲染编辑态的输入框，基于 Ant Design InputNumber 组件
+ *
+ * 功能：
+ * - 数值输入
+ * - 实时或失焦校验
+ * - 错误提示展示
+ * - 步进器调节
+ * - 前后缀、前后置标签
+ *
+ * @param props 组件 Props
+ */
+declare const EditView: React.FC<PisellNumberProps>;
+export default EditView;

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

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { PisellNumberProps } from '../types';
+/**
+ * PisellNumber 只读态视图组件
+ *
+ * 负责渲染只读态的纯文本展示
+ *
+ * 功能：
+ * - 格式化数值并展示
+ * - 支持自定义字体样式
+ * - 处理空值显示
+ *
+ * @param props 组件 Props
+ */
+declare const ReadOnlyView: React.FC<PisellNumberProps>;
+export default ReadOnlyView;

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

@@ -0,0 +1,6 @@
+/**
+ * PisellNumber 子组件导出
+ */
+export { default as ReadOnlyView } from './ReadOnlyView';
+export { default as EditView } from './EditView';
+export { default as DisabledView } from './DisabledView';

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

@@ -0,0 +1,7 @@
+/**
+ * PisellNumber 组件导出
+ */
+import PisellNumber from './PisellNumber';
+export { PisellNumber };
+export type { PisellNumberProps } from './types';
+export type { DisplayState, ValidationResult, NumberInputState, BaseNumberInputProps } from './types';

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

@@ -0,0 +1,168 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { BaseNumberInputProps } from '@pisell/utils';
+/**
+ * 从 @pisell/utils 重新导出公共类型
+ */
+export type { DisplayState, ValidationResult, NumberInputState, BaseNumberInputProps, } from '@pisell/utils';
+/**
+ * PisellNumber 组件 Props 类型定义
+ *
+ * 基于 Ant Design InputNumber，提供三态视图（只读/编辑/禁用）
+ */
+export interface PisellNumberProps extends BaseNumberInputProps {
+    /**
+     * 显示模式
+     * - read: 只读态，纯文本展示
+     * - edit: 编辑态，显示输入控件
+     * @default 'edit'
+     */
+    mode?: 'read' | 'edit';
+    /**
+     * 是否禁用
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 回车键回调
+     * @param value 当前值
+     */
+    onPressEnter?: (value: number | null) => void;
+    /**
+     * 步进值
+     * @default 1
+     */
+    step?: number;
+    /**
+     * 小数精度（小数位数）
+     * @example precision={2} 表示保留2位小数
+     */
+    precision?: number;
+    /**
+     * 是否使用千分位分隔符
+     * @default false
+     * @example 1234567 → 1,234,567
+     */
+    useGrouping?: boolean;
+    /**
+     * 自定义格式化函数
+     * @param value 数值
+     * @returns 格式化后的字符串
+     * @example
+     * formatter={(value) => `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}
+     */
+    formatter?: (value: number | null) => string;
+    /**
+     * 自定义解析函数（将显示值转换为数值）
+     * @param displayValue 显示的字符串
+     * @returns 解析后的数值
+     * @example
+     * parser={(value) => value.replace(/\$\s?|(,*)/g, '')}
+     */
+    parser?: (displayValue: string | undefined) => number | null;
+    /**
+     * 是否自动修正超出范围的值
+     * @default false
+     * @description 当值超出 min/max 范围时，自动修正为边界值
+     */
+    autoCorrect?: boolean;
+    /**
+     * 占位文本
+     * @default '请输入数字'
+     */
+    placeholder?: string;
+    /**
+     * 是否显示清空按钮
+     * @default false
+     */
+    allowClear?: boolean;
+    /**
+     * 是否自动聚焦
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * 前缀图标或文本
+     */
+    prefix?: ReactNode;
+    /**
+     * 后缀图标或文本
+     */
+    suffix?: ReactNode;
+    /**
+     * 前置标签
+     * @example addonBefore="￥"
+     */
+    addonBefore?: ReactNode;
+    /**
+     * 后置标签
+     * @example addonAfter="元"
+     */
+    addonAfter?: ReactNode;
+    /**
+     * 输入框尺寸
+     * @default 'middle'
+     */
+    size?: 'large' | 'middle' | 'small';
+    /**
+     * 是否启用键盘上下键
+     * @default true
+     */
+    keyboard?: boolean;
+    /**
+     * 控制字符
+     * @description 自定义控制字符，用于格式化显示
+     */
+    controls?: boolean | {
+        upIcon?: ReactNode;
+        downIcon?: ReactNode;
+    };
+    /**
+     * 字号
+     * @example '14px' 或 14
+     */
+    fontSize?: string | number;
+    /**
+     * 字重
+     * @example 'bold' 或 600
+     */
+    fontWeight?: string | number;
+    /**
+     * 文本颜色
+     * @example '#000000' 或 'rgba(0, 0, 0, 0.85)'
+     */
+    color?: string;
+    /**
+     * 文本对齐方式
+     * @default 'left'
+     */
+    textAlign?: 'left' | 'center' | 'right';
+    /**
+     * 空值时的显示文本
+     * @default '-'
+     */
+    emptyText?: string;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * ARIA 标签
+     */
+    'aria-label'?: string;
+    /**
+     * ARIA 描述
+     */
+    'aria-describedby'?: string;
+    /**
+     * HTML id 属性
+     */
+    id?: string;
+    /**
+     * HTML name 属性
+     */
+    name?: string;
+}

package/es/components/pisellPercent/PisellPercent.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import type { PisellPercentProps } from './types';
+import './PisellPercent.less';
+/**
+ * PisellPercent 百分比组件
+ *
+ * 基于 PisellNumber 派生，专门处理百分比数据。
+ * 支持文本、进度条、环形进度三种展示变体。
+ *
+ * @param props 组件 Props
+ *
+ * @example
+ * // 基础使用
+ * const [value, setValue] = useState(85.5);
+ * <PisellPercent
+ *   value={value}
+ *   onChange={setValue}
+ * />
+ *
+ * @example
+ * // 进度条展示
+ * <PisellPercent
+ *   mode="read"
+ *   value={75}
+ *   variant="progress"
+ * />
+ *
+ * @example
+ * // 滑块 + 输入框
+ * <PisellPercent
+ *   value={value}
+ *   onChange={setValue}
+ *   showSlider
+ * />
+ */
+export declare const PisellPercent: React.FC<PisellPercentProps>;
+declare const MemoizedPisellPercent: React.NamedExoticComponent<PisellPercentProps>;
+export default MemoizedPisellPercent;

package/es/components/pisellPercent/PisellPercent.stories.d.ts

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellPercent } from './PisellPercent';
+/**
+ * PisellPercent 组件 Storybook
+ */
+declare const meta: Meta<typeof PisellPercent>;
+export default meta;
+declare type Story = StoryObj<typeof PisellPercent>;
+/**
+ * 基础示例 - Text 变体
+ */
+export declare const Basic: Story;
+/**
+ * 只读态 - Text
+ */
+export declare const ReadOnlyText: Story;
+/**
+ * 只读态 - Progress 进度条
+ */
+export declare const ReadOnlyProgress: Story;
+/**
+ * 只读态 - Circle 环形进度
+ */
+export declare const ReadOnlyCircle: Story;
+/**
+ * 进度条 - 不同状态
+ */
+export declare const ProgressStates: Story;
+/**
+ * 环形进度 - 不同配置
+ */
+export declare const CircleVariants: Story;
+/**
+ * 范围转换
+ */
+export declare const RangeConversion: Story;
+/**
+ * 编辑态 - 仅输入框
+ */
+export declare const EditWithInput: Story;
+/**
+ * 编辑态 - 滑块 + 输入框
+ */
+export declare const EditWithSlider: Story;
+/**
+ * 项目进度看板
+ */
+export declare const ProjectDashboard: Story;
+/**
+ * 禁用态
+ */
+export declare const Disabled: Story;

package/es/components/pisellPercent/components/DisabledView.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import type { PisellPercentProps } from '../types';
+/**
+ * PisellPercent 禁用态视图组件
+ *
+ * 负责渲染禁用态的输入框
+ *
+ * @param props 组件 Props
+ */
+declare const DisabledView: React.FC<PisellPercentProps>;
+export default DisabledView;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import type { PisellPercentProps } from '../types';
+/**
+ * PisellPercent 编辑态视图组件
+ *
+ * 负责渲染编辑态的输入框
+ *
+ * 功能：
+ * - 百分比输入（后缀显示 %）
+ * - 可选：滑块调节
+ * - 滑块和输入框双向同步
+ * - 实时或失焦校验
+ *
+ * @param props 组件 Props
+ */
+declare const EditView: React.FC<PisellPercentProps>;
+export default EditView;

package/es/components/pisellPercent/components/ReadOnlyView.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { PisellPercentProps } from '../types';
+/**
+ * PisellPercent 只读态视图组件
+ *
+ * 根据 variant 渲染不同形式：
+ * - text: 纯文本（85.5%）
+ * - progress: 进度条
+ * - circle: 环形进度
+ *
+ * @param props 组件 Props
+ */
+declare const ReadOnlyView: React.FC<PisellPercentProps>;
+export default ReadOnlyView;

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

@@ -0,0 +1,6 @@
+/**
+ * PisellPercent 子组件导出
+ */
+export { default as ReadOnlyView } from './ReadOnlyView';
+export { default as EditView } from './EditView';
+export { default as DisabledView } from './DisabledView';

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

@@ -0,0 +1,7 @@
+/**
+ * PisellPercent 组件导出
+ */
+import PisellPercent from './PisellPercent';
+export { PisellPercent };
+export type { PisellPercentProps } from './types';
+export type { DisplayState, ValidationResult, NumberInputState, BaseNumberInputProps } from './types';

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