@pisell/materials 1.8.9 → 1.8.10

package/lib/components/PisellCards/components/TextCard/components/TextContent.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import { TextContentProps } from '../types';
+/**
+ * TextContent 文本内容组件
+ * 负责渲染主文本内容，处理文本省略逻辑
+ *
+ * @example
+ * ```tsx
+ * <TextContent
+ *   text="这是一段很长的文本内容"
+ *   textConfig={{
+ *     maxLines: 2,
+ *     ellipsis: true,
+ *     fontSize: 14,
+ *     color: '#333'
+ *   }}
+ * />
+ * ```
+ */
+declare const TextContent: React.FC<TextContentProps>;
+export default TextContent;

package/lib/components/PisellCards/components/TextCard/types.d.ts

@@ -0,0 +1,270 @@
+import { CSSProperties, ReactNode } from 'react';
+import { PisellBasicCardProps } from '../../types';
+/**
+ * 样式变体类型
+ */
+export declare type TextCardVariant = 'text' | 'filled' | 'outlined' | 'light' | 'gradient' | 'dashed';
+/**
+ * 尺寸类型
+ */
+export declare type TextCardSize = 'small' | 'default' | 'large';
+/**
+ * 宽度模式
+ */
+export declare type TextCardWidthMode = 'auto' | 'fixed' | 'full';
+/**
+ * 图标配置
+ */
+export interface IconConfig {
+    /**
+     * 图标大小（单位：px）
+     */
+    size?: number;
+    /**
+     * 图标颜色
+     */
+    color?: string;
+}
+/**
+ * 标签配置
+ */
+export interface TagConfig {
+    /**
+     * 标签颜色
+     */
+    color?: string;
+    /**
+     * 标签自定义样式
+     */
+    style?: CSSProperties;
+}
+/**
+ * 角标类型
+ */
+export declare type BadgeType = 'dot' | 'number' | 'text';
+/**
+ * 角标位置
+ */
+export declare type BadgePosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+/**
+ * 角标配置
+ */
+export interface BadgeConfig {
+    /**
+     * 角标类型
+     * @default 'dot'
+     */
+    type?: BadgeType;
+    /**
+     * 角标内容（数字或文本）
+     * 当 type 为 'number' 或 'text' 时有效
+     */
+    content?: ReactNode;
+    /**
+     * 角标位置
+     * @default 'top-right'
+     */
+    position?: BadgePosition;
+    /**
+     * 角标偏移量 [x, y]
+     * 正数向右/下偏移，负数向左/上偏移
+     */
+    offset?: [number, number];
+    /**
+     * 角标颜色
+     */
+    color?: string;
+    /**
+     * 角标自定义样式
+     */
+    style?: CSSProperties;
+}
+/**
+ * 文本配置
+ */
+export interface TextConfig {
+    /**
+     * 字体大小（单位：px）
+     */
+    fontSize?: number;
+    /**
+     * 字体粗细
+     */
+    fontWeight?: string | number;
+    /**
+     * 文本颜色
+     */
+    color?: string;
+    /**
+     * 最大显示行数
+     * @default 1
+     */
+    maxLines?: number;
+    /**
+     * 是否显示省略号
+     * @default true
+     */
+    ellipsis?: boolean;
+    /**
+     * 文本对齐方式
+     * @default 'left'
+     */
+    textAlign?: 'left' | 'center' | 'right';
+    flex?: string;
+}
+/**
+ * TextCard 组件 Props
+ * 基于 PisellBasicCardProps 扩展
+ * 注意：重写 onClick 为可选属性
+ */
+export interface TextCardProps extends Omit<PisellBasicCardProps, 'onClick'> {
+    /**
+     * 卡片显示的文本内容（必填）
+     */
+    text: ReactNode;
+    /**
+     * 卡片样式变体
+     * @default 'text'
+     */
+    variant?: TextCardVariant;
+    /**
+     * 卡片尺寸
+     * @default 'default'
+     */
+    size?: TextCardSize;
+    /**
+     * 是否可点击
+     * @default true
+     */
+    clickable?: boolean;
+    /**
+     * 前置图标
+     * 支持 ReactNode（如 antd Icon、svg 等）
+     */
+    prefixIcon?: ReactNode;
+    /**
+     * 后置图标
+     * 支持 ReactNode（如 antd Icon、svg 等）
+     */
+    suffixIcon?: ReactNode;
+    /**
+     * 图标配置
+     * 统一配置前置和后置图标的大小和颜色
+     */
+    iconConfig?: IconConfig;
+    /**
+     * 后置标签
+     * 支持 ReactNode（如 antd Tag、Badge 等）
+     */
+    tag?: ReactNode;
+    /**
+     * 标签配置
+     */
+    tagConfig?: TagConfig;
+    /**
+     * 角标配置
+     * 用于显示红点、数字或文本提示
+     */
+    badge?: BadgeConfig;
+    /**
+     * 前置插槽
+     * 用于替换前置图标，优先级高于 prefixIcon
+     */
+    prefixSlot?: ReactNode;
+    /**
+     * 后置插槽
+     * 用于替换后置图标和标签，优先级高于 suffixIcon 和 tag
+     */
+    suffixSlot?: ReactNode;
+    /**
+     * 文本配置
+     * 用于自定义文本样式和显示行为
+     */
+    textConfig?: TextConfig;
+    /**
+     * 宽度模式
+     * - auto: 内容撑满，最大宽度 maxWidth
+     * - fixed: 固定宽度 width
+     * - full: 撑满父容器，最小宽度 28px
+     * @default 'auto'
+     */
+    widthMode?: TextCardWidthMode;
+    /**
+     * 固定宽度值
+     * 当 widthMode='fixed' 时有效
+     */
+    width?: number | string;
+    /**
+     * 最大宽度
+     * 当 widthMode='auto' 时有效
+     * @default 400
+     */
+    maxWidth?: number | string;
+    /**
+     * 点击事件
+     * 当 clickable=true 且不在 disabled/loading 状态时触发
+     * 注意：PisellBasicCardProps 中的 onClick 是必填的，这里重新定义为可选
+     */
+    onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+    /**
+     * 自定义渲染函数
+     * 完全自定义组件的渲染内容
+     * 当提供此函数时，组件内置的渲染逻辑将被忽略
+     */
+    render?: (props: TextCardProps) => ReactNode;
+}
+/**
+ * TextContent 组件 Props
+ * 文本内容子组件
+ */
+export interface TextContentProps {
+    /**
+     * 文本内容
+     */
+    text: ReactNode;
+    /**
+     * 文本配置
+     */
+    textConfig?: TextConfig;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    active?: PisellBasicCardProps['active'];
+}
+/**
+ * IconWrapper 组件 Props
+ * 图标包装子组件
+ */
+export interface IconWrapperProps {
+    /**
+     * 图标内容
+     */
+    icon: ReactNode;
+    /**
+     * 图标配置
+     */
+    config?: IconConfig;
+    /**
+     * 图标位置
+     */
+    position: 'prefix' | 'suffix';
+    /**
+     * 自定义类名
+     */
+    className?: string;
+}
+/**
+ * BadgeWrapper 组件 Props
+ * 角标包装子组件
+ */
+export interface BadgeWrapperProps {
+    /**
+     * 角标配置
+     */
+    badge?: BadgeConfig;
+    /**
+     * 子元素
+     */
+    children: ReactNode;
+}

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

@@ -1,4 +1,3 @@
-/// <reference types="react" />
 declare const PisellCards: {
     TabCard: (props: any) => import("react").JSX.Element;
     TextCard: (props: any) => import("react").JSX.Element;

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

@@ -9,7 +9,6 @@
  * <PisellFields.Number value={123} viewMode="readonly" />
  * <PisellFields.Currency value={1000} currencySymbol="$" />
  */
-/// <reference types="react" />
 declare const PisellFields: {
     SingleLineText: import("react").NamedExoticComponent<import("../pisellSingleLineText").PisellSingleLineTextProps>;
     LongText: import("react").NamedExoticComponent<import("../pisellLongText").PisellLongTextProps>;

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

@@ -13,7 +13,6 @@
  *   <Content />
  * </PisellLayouts.ScrollView>
  */
-/// <reference types="react" />
 declare const PisellLayouts: {
     BasicGrid: <T>(props: import("../PisellBasicGrid").PisellBasicGridProps<T>) => import("react").JSX.Element;
     ScrollView: import("react").ForwardRefExoticComponent<Omit<import("../PisellScrollView").PisellScrollViewProps, "ref"> & import("react").RefAttributes<import("../PisellScrollView").PisellScrollViewRef>>;

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

@@ -13,7 +13,6 @@
  * />
  * <PisellMetrics.StatisticList data={[...]} />
  */
-/// <reference types="react" />
 declare const PisellMetrics: {
     MetricCard: import("react").FC<import("../pisellMetricCard").PisellMetricCardProps>;
     StatisticList: (props: import("../pisellStatisticList").PisellStatisticListProps) => import("react").JSX.Element;

package/lib/components/PisellSteps/PisellSteps.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import './PisellSteps.less';
+import type { PisellStepsProps } from './types';
+/**
+ * PisellSteps 步骤条组件
+ *
+ * 基于 Ant Design Steps 组件进行二次封装和增强
+ * 支持多种展示样式、布局方式和丰富的交互功能
+ *
+ * @author Pisell Team
+ * @version 1.0.0
+ */
+declare const PisellSteps: React.FC<PisellStepsProps>;
+export default PisellSteps;

package/lib/components/PisellSuperTabs/PisellSuperTabs.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import './PisellSuperTabs.less';
+import type { PisellSuperTabsProps } from './types';
+interface PisellSuperTabsRef {
+    scrollItemByRowKey: (key: string) => void;
+}
+declare const _default: React.ForwardRefExoticComponent<PisellSuperTabsProps<unknown> & React.RefAttributes<PisellSuperTabsRef>>;
+export default _default;

package/lib/components/PisellSuperTabs/hooks/useTabsState.d.ts

@@ -0,0 +1,7 @@
+import { UseTabsStateParams, UseTabsStateReturn } from '../types';
+/**
+ * Tabs 状态管理 Hook
+ * @description 处理受控/非受控模式的状态管理
+ * @template T - 数据项类型
+ */
+export declare const useTabsState: <T = any>(params: UseTabsStateParams<T>) => UseTabsStateReturn<T>;

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

@@ -0,0 +1,212 @@
+import { CSSProperties, ReactNode } from 'react';
+import type { PisellBasicGridProps } from '../PisellBasicGrid/types';
+import type { PisellScrollViewProps } from '../PisellScrollView/types';
+import type { PisellBasicCardProps } from '../PisellCards/types';
+/**
+ * useTabsState Hook 参数
+ */
+export interface UseTabsStateParams<T = any> {
+    isControlled: boolean;
+    /**
+     * 当前激活的 Tab key（受控）
+     */
+    value?: string;
+    /**
+     * 默认激活的 Tab key（非受控）
+     */
+    defaultValue?: string;
+    /**
+     * Tab 切换时的回调
+     */
+    onChange?: (key: string, item: T) => void;
+}
+/**
+ * useTabsState Hook 返回值
+ */
+export interface UseTabsStateReturn<T = any> {
+    /**
+     * 当前激活的 Tab key
+     */
+    activeKey: string | undefined;
+    /**
+     * 切换 Tab 的方法
+     */
+    handleTabChange: (key: string, item: T) => void;
+}
+export interface RenderItemProps<T = any> extends PisellBasicCardProps {
+    index: number;
+    tabsState: UseTabsStateReturn<T>;
+    tabsProps: PisellSuperTabsProps<T>;
+}
+/**
+ * PisellSuperTabs 组件 Props
+ * @template T - 数据源项的类型
+ * @description 通用导航框架封装的全能型 Tab 组件
+ */
+export interface PisellSuperTabsProps<T = any> {
+    isControlled?: boolean;
+    /**
+     * 自定义类名
+     * @description 添加到最外层容器的类名
+     */
+    className?: string;
+    tabItemClassName?: string;
+    tabItemStyle?: CSSProperties;
+    /**
+     * 自定义样式
+     * @description 添加到最外层容器的样式
+     */
+    style?: CSSProperties;
+    /**
+     * 唯一标识
+     * @description 必填，用于区分不同的 TabItem
+     */
+    id?: string;
+    /**
+     * 数据源
+     * @description 支持多级嵌套，递归字段为 children
+     * @example
+     * [
+     *   { key: 'home', label: '首页' },
+     *   { key: 'products', label: '产品', children: [...] }
+     * ]
+     */
+    dataSource?: T[];
+    /**
+     * 数据项的唯一标识字段
+     * @default 'key'
+     * @description 可以是字符串（字段名）或函数（自定义获取逻辑）
+     * @example
+     * // 字符串形式
+     * rowKey="id"
+     *
+     * // 函数形式
+     * rowKey={(record, index) => `${record.type}-${index}`}
+     */
+    rowKey?: string | ((record: T, index: number) => string);
+    /**
+     * 当前激活的 Tab key
+     * @description 受控模式，需配合 onChange 使用
+     */
+    value?: string;
+    /**
+     * 默认激活的 Tab key
+     * @description 非受控模式，仅初始化时生效
+     */
+    defaultValue?: string;
+    /**
+     * Tab 切换时的回调
+     * @param key - 切换到的 Tab key
+     * @param item - 切换到的数据项
+     */
+    onChange?: (key: string, item: T) => void;
+    /**
+     * 自定义 TabItem 渲染
+     * @description 支持两种模式：
+     * 1. 函数模式：(item, index, active) => ReactNode
+     * 2. 插槽模式：直接传入 ReactNode
+     * @example
+     * // 函数模式
+     * renderItem={(item, index, active) => (
+     *   <PisellCards.TabCard
+     *     {...item}
+     *     active={{ value: active }}
+     *   />
+     * )}
+     *
+     * // 插槽模式
+     * renderItem={<PisellCards.TabCard />}
+     */
+    renderItem?: ((props: RenderItemProps<T>) => ReactNode) | ReactNode;
+    /**
+     * PisellBasicGrid 组件的配置
+     * @description 透传给 PisellBasicGrid 组件的所有 Props
+     * @see PisellBasicGridProps
+     * @example
+     * gridProps={{
+     *   direction: 'horizontal',
+     *   gap: 16,
+     *   wrap: 'wrap',
+     *   columns: 4,
+     * }}
+     */
+    gridProps?: Omit<PisellBasicGridProps<T>, 'dataSource' | 'renderItem' | 'rowKey' | 'children'>;
+    /**
+     * PisellScrollView 组件的配置
+     * @description 透传给 PisellScrollView 组件的所有 Props
+     * @see PisellScrollViewProps
+     * @example
+     * scrollViewProps={{
+     *   overflow: 'x',
+     *   scrollbarStyle: 'thin',
+     *   scrollActionsConfig: { show: true, type: 'lrArrows' },
+     * }}
+     */
+    scrollViewProps?: Omit<PisellScrollViewProps, 'children'>;
+    children?: ReactNode;
+    /**
+     * 左侧插槽
+     */
+    slotLeft?: ReactNode;
+    slotLeftClassName?: string;
+    slotLeftStyle?: CSSProperties;
+    /**
+     * 右侧插槽
+     */
+    slotRight?: ReactNode;
+    slotRightClassName?: string;
+    slotRightStyle?: CSSProperties;
+    /**
+     * 顶部插槽
+     */
+    slotTop?: ReactNode;
+    slotTopClassName?: string;
+    slotTopStyle?: CSSProperties;
+    /**
+     * 底部插槽
+     */
+    slotBottom?: ReactNode;
+    slotBottomClassName?: string;
+    slotBottomStyle?: CSSProperties;
+    __designMode?: boolean;
+}
+/**
+ * 数据项基础类型
+ * @description 建议数据源中的每一项都包含这些字段
+ */
+export interface TabDataItem {
+    /**
+     * 唯一标识
+     * @description 必填，用于区分不同的 TabItem
+     */
+    key: string;
+    /**
+     * 标签文本
+     */
+    label?: string;
+    /**
+     * 图标
+     */
+    icon?: ReactNode;
+    /**
+     * 徽章配置
+     */
+    badge?: {
+        count?: number;
+        dot?: boolean;
+        text?: string;
+    };
+    /**
+     * 子级数据（多级嵌套）
+     * @description 用于多级导航场景，具体渲染逻辑由 Card 组件实现
+     */
+    children?: TabDataItem[];
+    /**
+     * 是否禁用
+     */
+    disabled?: boolean;
+    /**
+     * 其他自定义字段
+     */
+    [key: string]: any;
+}

package/lib/components/PisellTabbar/PisellTabbar.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import './PisellTabbar.less';
+import { PisellTabbarProps } from './types';
+/**
+ * PisellTabbar - 多层级 Tabbar 组件
+ *
+ * 支持最多 3 层级的 Tab 导航，每层级可独立展开/收起
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <PisellTabbar
+ *   dataSource={categoryData}
+ *   value={[1, 10, 100]}
+ *   onChange={(value) => console.log('当前选中:', value)}
+ * />
+ * ```
+ */
+declare const PisellTabbar: React.FC<PisellTabbarProps>;
+export default PisellTabbar;

package/lib/components/PisellTabbar/constants.d.ts

@@ -0,0 +1,47 @@
+import { TabbarLevelConfig, ExpandConfig, LevelType } from './types';
+/**
+ * 默认层级配置
+ */
+export declare const DEFAULT_LEVEL_CONFIG: Record<LevelType, TabbarLevelConfig>;
+/**
+ * 获取展开配置
+ */
+export declare const getExpandConfig: () => ExpandConfig;
+/**
+ * 默认数据项配置
+ */
+export declare const DEFAULT_ITEMS: {
+    all: {
+        id: string;
+        shop_id: number;
+        parent_id: number;
+        name: any;
+        slug: string;
+        icon: string;
+    };
+    search: {
+        id: string;
+        shop_id: number;
+        parent_id: number;
+        name: any;
+        text: any;
+        slug: string;
+        key: string;
+        icon: string;
+        customClick: boolean;
+    };
+    expand: {
+        id: string;
+        shop_id: number;
+        parent_id: number;
+        key: string;
+        icon: string;
+        name: string;
+        slug: string;
+        customClick: boolean;
+    };
+};
+/**
+ * 获取层级对应的添加项配置
+ */
+export declare const LEVEL_ADD_ITEMS: Record<LevelType, ('all' | 'search' | 'expand')[]>;

package/lib/components/PisellTabbar/hooks/useActiveKey.d.ts

@@ -0,0 +1,55 @@
+/**
+ * useActiveKey Hook 参数
+ */
+interface UseActiveKeyProps {
+    /** 初始激活的 key 数组（对应多层级） */
+    initialActiveKey?: (string | number)[];
+    /** key 变化回调 */
+    onChange?: (value: (string | number)[]) => void;
+}
+/**
+ * useActiveKey Hook 返回值
+ */
+interface UseActiveKeyReturn {
+    /** 当前激活的 key 数组 */
+    activeKey: (string | number)[];
+    /** 设置指定层级的激活 key */
+    setActiveKey: (level: number, key: string | number, cKey?: string | number) => void;
+    /** 获取指定层级的激活 key */
+    getActiveKey: (level: number) => string | number;
+    /** 内部设置方法（用于同步外部值） */
+    _setActiveKey: (value: (string | number)[]) => void;
+    /** 设置缓存key */
+    setCacheActiveKey: (val: (string | number)[]) => void;
+    /** 重置value为缓存key */
+    resetActiveKey: () => void;
+    /** 获取缓存key */
+    getCacheActiveKey: () => (string | number)[];
+}
+/**
+ * Tabbar 激活状态管理 Hook
+ *
+ * 用于管理多层级 Tabbar 的激活状态，支持级联选择
+ *
+ * @param props - Hook 配置参数
+ * @returns 激活状态和操作方法
+ *
+ * @example
+ * ```tsx
+ * const { activeKey, setActiveKey, getActiveKey } = useActiveKey({
+ *   initialActiveKey: [1, 10],
+ *   onChange: (value) => console.log('当前选中:', value)
+ * });
+ *
+ * // 设置第 0 层级的 key，并清除后续层级
+ * setActiveKey(0, '2');
+ *
+ * // 设置第 0 层级的 key，并同时设置第 1 层级
+ * setActiveKey(0, '2', '20');
+ *
+ * // 获取第 0 层级的 key
+ * const level0Key = getActiveKey(0);
+ * ```
+ */
+declare const useActiveKey: (props: UseActiveKeyProps) => UseActiveKeyReturn;
+export default useActiveKey;