@pisell/materials 1.8.19 → 1.8.21

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

@@ -0,0 +1,160 @@
+import type { BaseSelectProps, SelectOption } from '@pisell/utils';
+/**
+ * PisellMultipleSelect 组件 Props 类型定义
+ *
+ * 继承 BaseSelectProps，添加多选特有的配置
+ * @template T 选项值的类型，默认为 string | number
+ */
+export interface PisellMultipleSelectProps<T = string | number> extends BaseSelectProps<T> {
+    /**
+     * 受控模式：当前选中值数组
+     */
+    value?: T[];
+    /**
+     * 非受控模式：默认选中值数组
+     */
+    defaultValue?: T[];
+    /**
+     * 值变化回调
+     * @param value 新的选中值数组
+     * @param options 选中的选项对象数组
+     */
+    onChange?: (value: T[], options: SelectOption<T>[]) => void;
+    /**
+     * 最多显示的标签数量
+     * 超出部分会显示 "+N" 聚合标签
+     * @default 3
+     */
+    maxTagCount?: number;
+    /**
+     * 超出标签 hover 时是否显示 Tooltip
+     * @default true
+     */
+    showTooltipOnOverflow?: boolean;
+    /**
+     * 最大可选数量
+     * 达到上限时阻止继续选择
+     * @default undefined（无限制）
+     */
+    maxCount?: number;
+    /**
+     * 取消选中某项时触发
+     * @param value 被取消选中的值
+     * @param option 被取消选中的选项对象
+     */
+    onDeselect?: (value: T, option: SelectOption<T>) => void;
+    /**
+     * ARIA 标签
+     */
+    'aria-label'?: string;
+    /**
+     * ARIA 是否必填
+     */
+    'aria-required'?: boolean;
+    /**
+     * ARIA 是否无效
+     */
+    'aria-invalid'?: boolean;
+    /**
+     * ARIA 描述关联 ID
+     */
+    'aria-describedby'?: string;
+    /**
+     * ARIA 多选标识
+     * @default true
+     */
+    'aria-multiselectable'?: boolean;
+}
+/**
+ * PisellMultipleSelect 组件 Ref 方法
+ * @template T 选项值的类型
+ */
+export interface MultipleSelectRef<T = string | number> {
+    /**
+     * 聚焦到组件
+     */
+    focus: () => void;
+    /**
+     * 失焦
+     */
+    blur: () => void;
+    /**
+     * 获取当前选中值数组
+     */
+    getValue: () => T[];
+    /**
+     * 设置选中值数组
+     */
+    setValue: (value: T[]) => void;
+    /**
+     * 清空所有选中值
+     */
+    clearValue: () => void;
+    /**
+     * 添加一个选中值
+     */
+    addValue: (value: T) => void;
+    /**
+     * 移除一个选中值
+     */
+    removeValue: (value: T) => void;
+}
+/**
+ * EditView 组件 Props
+ * @template T 选项值的类型
+ */
+export interface EditViewProps<T = string | number> extends PisellMultipleSelectProps<T> {
+    /**
+     * 内部状态管理对象（从 useSelectState Hook 传入）
+     */
+    state?: {
+        value: T[];
+        setValue: (value: T[]) => void;
+        addValue: (value: T) => void;
+        removeValue: (value: T) => void;
+        clearValue: () => void;
+    };
+    /**
+     * 内部 onChange 处理（包含 maxCount 限制等逻辑）
+     */
+    onChangeInternal?: (value: T[]) => void;
+}
+/**
+ * DisabledView 组件 Props
+ * @template T 选项值的类型
+ */
+export interface DisabledViewProps<T = string | number> extends PisellMultipleSelectProps<T> {
+}
+/**
+ * ReadOnlyView 组件 Props
+ * @template T 选项值的类型
+ */
+export interface ReadOnlyViewProps<T = string | number> extends PisellMultipleSelectProps<T> {
+}
+/**
+ * TagRenderer 组件 Props（可选，用于自定义标签渲染）
+ * @template T 选项值的类型
+ */
+export interface TagRendererProps<T = string | number> {
+    /**
+     * 当前选中值数组
+     */
+    value: T[];
+    /**
+     * 所有选项列表
+     */
+    options: SelectOption<T>[];
+    /**
+     * 最多显示的标签数量
+     */
+    maxTagCount: number;
+    /**
+     * 是否显示 Tooltip
+     */
+    showTooltip: boolean;
+    /**
+     * 移除标签回调
+     */
+    onRemove?: (value: T) => void;
+}
+export type { SelectOption, FilterOptionFunc, SortDirection, MultipleSelectState, TagDisplayInfo, } from '@pisell/utils';

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

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellNumber } from './PisellNumber';
+/**
+ * PisellNumber 组件 Storybook
+ *
+ * 用于展示和测试组件的各种状态和配置
+ */
+declare const meta: Meta<typeof PisellNumber>;
+export default meta;
+declare type Story = StoryObj<typeof PisellNumber>;
+/**
+ * 基础示例 - 编辑态
+ */
+export declare const Basic: Story;
+/**
+ * 只读态展示
+ */
+export declare const ReadOnly: Story;
+/**
+ * 禁用态
+ */
+export declare const Disabled: Story;
+/**
+ * 带范围限制
+ */
+export declare const WithRange: Story;
+/**
+ * 带精度控制
+ */
+export declare const WithPrecision: Story;
+/**
+ * 千分位分隔符
+ */
+export declare const WithGrouping: Story;
+/**
+ * 带前后缀
+ */
+export declare const WithAddon: Story;
+/**
+ * 带校验 - 必填
+ */
+export declare const WithValidationRequired: Story;
+/**
+ * 带校验 - 范围校验
+ */
+export declare const WithValidationRange: Story;
+/**
+ * 带校验 - 自定义校验
+ */
+export declare const WithCustomValidation: Story;
+/**
+ * 不同尺寸
+ */
+export declare const Sizes: Story;
+/**
+ * 只读态样式配置
+ */
+export declare const ReadOnlyStyles: Story;
+/**
+ * 表单场景
+ */
+export declare const InForm: Story;
+/**
+ * 空值处理
+ */
+export declare const EmptyValue: Story;

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

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

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';