@pisell/materials 1.8.6 → 1.8.7

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/pisellMetricCard/utils/formatMetricValue.d.ts

@@ -0,0 +1,34 @@
+import type { FormatOptions } from '../types';
+/**
+ * 格式化指标数值
+ *
+ * 支持以下格式化选项：
+ * - 小数精度控制
+ * - 千分位分隔符
+ * - 货币符号显示
+ * - 自定义格式化函数
+ * - 整数时隐藏小数部分
+ *
+ * @param value 数值
+ * @param options 格式化选项
+ * @returns 格式化后的字符串，null 时返回 null
+ *
+ * @example
+ * formatMetricValue(1234.56, { precision: 2, useGrouping: true })
+ * // 返回: "1,234.56"
+ *
+ * @example
+ * formatMetricValue(1580, {
+ *   showCurrencySymbol: true,
+ *   currencySymbol: '$'
+ * })
+ * // 返回: "$1580"
+ *
+ * @example
+ * formatMetricValue(100.00, {
+ *   precision: 2,
+ *   hideDecimalForWholeNumbers: true
+ * })
+ * // 返回: "100"
+ */
+export declare function formatMetricValue(value: number | string | null | undefined, options?: FormatOptions): string | null;

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

@@ -0,0 +1,5 @@
+/**
+ * 工具函数导出
+ */
+export { formatMetricValue } from './formatMetricValue';
+export { calculateTrend } from './calculateTrend';

package/es/components/pisellModal/components/Information/index.d.ts

@@ -17,5 +17,5 @@ export interface InformationProps extends PisellModalProps {
     /** 右上角关闭按钮是否展示 */
     closable?: boolean;
 }
-declare const Information: (props: InformationProps) => JSX.Element;
+declare const Information: (props: InformationProps) => React.JSX.Element;
 export default Information;

package/es/components/pisellModal/components/IpadModal/index.d.ts

@@ -1,5 +1,6 @@
+import React from 'react';
 import { PcModalProps } from '../PcModal';
 export interface IpadModalProps extends PcModalProps {
 }
-declare const IpadModal: (props: IpadModalProps) => JSX.Element;
+declare const IpadModal: (props: IpadModalProps) => React.JSX.Element;
 export default IpadModal;

package/es/components/pisellModal/components/MobileModal/index.d.ts

@@ -1,8 +1,9 @@
+import React from 'react';
 import { PcModalProps } from '../PcModal';
 import './index.less';
 export interface MobileModalProps extends PcModalProps {
     /** 移动端展示时弹窗高度 默认null 在移动端全屏 */
     mobileModalHeight?: string | number;
 }
-declare const MobileModal: (props: MobileModalProps) => JSX.Element;
+declare const MobileModal: (props: MobileModalProps) => React.JSX.Element;
 export default MobileModal;

package/es/components/pisellModal/components/PcModal/index.d.ts

@@ -26,5 +26,5 @@ export interface PcModalProps extends ModalProps {
     /** header是否展示 */
     header?: boolean | null;
 }
-declare const PcModal: (props: PcModalProps) => JSX.Element;
+declare const PcModal: (props: PcModalProps) => React.JSX.Element;
 export default PcModal;

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

@@ -1,9 +1,10 @@
+/// <reference types="react" />
 import IpadModal from './IpadModal';
 import MobileModal from './MobileModal';
 import PcModal from './PcModal';
 declare const platformCpt: {
-    h5: (props: import("./MobileModal").MobileModalProps) => JSX.Element;
-    pc: (props: import("./PcModal").PcModalProps) => JSX.Element;
-    ipad: (props: import("./IpadModal").IpadModalProps) => JSX.Element;
+    h5: (props: import("./MobileModal").MobileModalProps) => import("react").JSX.Element;
+    pc: (props: import("./PcModal").PcModalProps) => import("react").JSX.Element;
+    ipad: (props: import("./IpadModal").IpadModalProps) => import("react").JSX.Element;
 };
 export { IpadModal, MobileModal, PcModal, platformCpt };

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

@@ -31,7 +31,7 @@ export interface PisellModalProps extends ModalProps {
     header?: boolean | null;
 }
 declare const PisellModal: {
-    (props: PisellModalProps): JSX.Element;
+    (props: PisellModalProps): React.JSX.Element;
     confirm: (props: import("./components/functions").PisellModalFuncProps) => {
         destroy: () => void;
         update: (configUpdate: import("antd").ModalFuncProps | ((prevConfig: import("antd").ModalFuncProps) => import("antd").ModalFuncProps)) => void;
@@ -53,6 +53,6 @@ declare const PisellModal: {
         destroy: () => void;
         update: (configUpdate: import("antd").ModalFuncProps | ((prevConfig: import("antd").ModalFuncProps) => import("antd").ModalFuncProps)) => void;
     };
-    Information: (props: import("./components/Information").InformationProps) => JSX.Element;
+    Information: (props: import("./components/Information").InformationProps) => React.JSX.Element;
 };
 export default PisellModal;

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

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import PisellMultipleSelect from './PisellMultipleSelect';
+/**
+ * PisellMultipleSelect 组件 Storybook
+ *
+ * 用于展示和测试组件的各种状态和配置
+ */
+declare const meta: Meta<typeof PisellMultipleSelect>;
+export default meta;
+declare type Story = StoryObj<typeof PisellMultipleSelect>;
+/**
+ * 基础示例
+ */
+export declare const Basic: Story;
+/**
+ * 带标签
+ */
+export declare const WithLabel: Story;
+/**
+ * 标签聚合功能
+ */
+export declare const TagAggregation: Story;
+/**
+ * 最大可选数量限制
+ */
+export declare const WithMaxCount: Story;
+/**
+ * 带搜索功能
+ */
+export declare const WithSearch: Story;
+/**
+ * 带清空按钮
+ */
+export declare const WithClear: Story;
+/**
+ * 禁用态
+ */
+export declare const Disabled: Story;
+/**
+ * 只读态
+ */
+export declare const ReadOnly: Story;
+/**
+ * 只读态 - 标签聚合
+ */
+export declare const ReadOnlyWithAggregation: Story;
+/**
+ * 只读态 - 空值
+ */
+export declare const ReadOnlyEmpty: Story;
+/**
+ * 错误状态
+ */
+export declare const WithError: Story;
+/**
+ * 不同尺寸
+ */
+export declare const Sizes: Story;
+/**
+ * 表单场景
+ */
+export declare const InForm: Story;
+/**
+ * 回调事件演示
+ */
+export declare const WithCallbacks: Story;
+/**
+ * 所有状态组合
+ */
+export declare const AllStates: Story;

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

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

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/pisellMultipleSelect/components/ReadOnlyView.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PisellMultipleSelect - ReadOnlyView (只读态视图)
+ * 只读状态下的渲染
+ */
+import React from 'react';
+import type { ReadOnlyViewProps } from '../types';
+declare const ReadOnlyView: React.FC<ReadOnlyViewProps>;
+export default ReadOnlyView;

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

@@ -0,0 +1,6 @@
+/**
+ * PisellMultipleSelect 组件导出
+ */
+export { default as PisellMultipleSelect } from './PisellMultipleSelect';
+export type { PisellMultipleSelectProps, MultipleSelectRef, EditViewProps, DisabledViewProps, ReadOnlyViewProps, TagRendererProps, } from './types';
+export type { SelectOption, FilterOptionFunc, SortDirection, MultipleSelectState, TagDisplayInfo, } from './types';

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