@pisell/materials 6.3.27 → 6.3.28

package/lib/components/PisellScrollView/hooks/useScrollState.d.ts

@@ -0,0 +1,13 @@
+import { RefObject } from 'react';
+import { ScrollEventData, PisellScrollViewProps } from '../types';
+/**
+ * 滚动状态管理 Hook
+ * @description 管理滚动容器的状态，包括滚动位置、溢出检测等
+ */
+export declare const useScrollState: ({ containerRef, overflow, }: {
+    containerRef: RefObject<HTMLElement>;
+    overflow: PisellScrollViewProps['overflow'];
+}) => {
+    scrollState: ScrollEventData;
+    updateScrollState: () => void;
+};

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

@@ -0,0 +1,3 @@
+import PisellScrollView from './PisellScrollView';
+export type { PisellScrollViewProps, PisellScrollViewRef } from './types';
+export default PisellScrollView;

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

@@ -0,0 +1,203 @@
+import React, { ReactNode, CSSProperties } from 'react';
+/**
+ * 滚动位置配置
+ */
+export interface ScrollPosition {
+    /** 竖向滚动位置（像素） */
+    scrollTop?: number;
+    /** 横向滚动位置（像素） */
+    scrollLeft?: number;
+    /** 滚动行为 */
+    behavior?: 'auto' | 'smooth';
+}
+/**
+ * 滚动到元素配置
+ */
+export interface ScrollToElementConfig {
+    /** 目标元素 ID */
+    targetId: string;
+    /** 对齐方式 */
+    align?: 'start' | 'center' | 'end' | 'nearest';
+    /** 滚动行为 */
+    behavior?: 'auto' | 'smooth';
+    /** 偏移量 */
+    offset?: number;
+}
+/**
+ * 滚动百分比配置
+ */
+export interface ScrollPercentage {
+    /** 竖向滚动百分比 (0-100) */
+    percentY?: number;
+    /** 横向滚动百分比 (0-100) */
+    percentX?: number;
+    /** 滚动行为 */
+    behavior?: 'auto' | 'smooth';
+}
+/**
+ * 滚动按钮配置
+ */
+export interface ScrollActionsConfig {
+    show?: boolean;
+    /** 按钮类型 */
+    type: "backTop" | "rArrows" | "lrArrows" | "tbArrows" | "custom";
+    style?: CSSProperties;
+    scrollDistance?: number;
+    /** 按钮配置 根据type不同，配置不同 */
+    config?: any;
+}
+/**
+ * 滚动事件数据
+ */
+export interface ScrollEventData {
+    /** 当前滚动位置 */
+    scrollTop: number;
+    scrollLeft: number;
+    /** 滚动百分比 */
+    percentY: number;
+    percentX: number;
+    /** 可滚动高度/宽度 */
+    scrollHeight: number;
+    scrollWidth: number;
+    /** 容器尺寸 */
+    clientHeight: number;
+    clientWidth: number;
+    /** 滚动方向 */
+    direction: 'up' | 'down' | 'left' | 'right' | null;
+    /** 是否滚动到顶部 */
+    isScrollToTop: boolean;
+    /** 是否滚动到底部 */
+    isScrollToBottom: boolean;
+    /** 是否滚动到左边 */
+    isScrollToLeft: boolean;
+    /** 是否滚动到右边 */
+    isScrollToRight: boolean;
+    /** 是否已经产生滚动条 */
+    isOverflows: boolean;
+}
+/**
+ * 视图监听配置
+ */
+export interface IntersectionConfig {
+    /** 是否启用视图监听 */
+    enabled?: boolean;
+    /** 交叉阈值 (0-1) */
+    threshold?: number | number[];
+    /** 根边距 */
+    rootMargin?: string;
+    /** 元素进入视图回调 */
+    onEnterViewport?: (entry: IntersectionObserverEntry, element: Element) => void;
+    /** 元素离开视图回调 */
+    onLeaveViewport?: (entry: IntersectionObserverEntry, element: Element) => void;
+    /** 可见度变化回调 */
+    onVisibilityChange?: (entry: IntersectionObserverEntry, element: Element) => void;
+    /** 需要监听的元素选择器 */
+    targetSelector?: string;
+}
+/**
+ * 吸附滚动配置
+ */
+export interface SnapScrollConfig {
+    /** 是否启用吸附滚动 */
+    enabled?: boolean;
+    /** 吸附类型 */
+    type?: 'mandatory' | 'proximity';
+    /** 吸附对齐方式 */
+    align?: 'start' | 'center' | 'end';
+    /** 吸附开始回调 */
+    onSnapStart?: (targetIndex: number, targetPosition: number) => void;
+    /** 吸附结束回调 */
+    onSnapEnd?: (currentIndex: number, currentPosition: number) => void;
+}
+/**
+ * PisellScrollView 组件 Props
+ */
+export interface PisellScrollViewProps {
+    /** 子元素 */
+    children?: ReactNode;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: CSSProperties;
+    /** 滚动方向 */
+    overflow?: 'auto' | 'scroll' | 'hidden' | 'x' | 'y' | 'both';
+    /** 滚动条样式 */
+    scrollbarStyle?: 'default' | 'thin' | 'minimal' | 'rounded' | 'overlay' | 'custom' | 'none';
+    /** 自定义滚动条类名（当 scrollbarStyle 为 'custom' 时使用） */
+    scrollbarClassName?: string;
+    /** 是否显示滚动按钮 */
+    showScrollButtons?: boolean;
+    /** 箭头操作 */
+    scrollActionsConfig?: ScrollActionsConfig;
+    /** 滚动时触发 */
+    onScroll?: (data: ScrollEventData) => void;
+    /** 开始滚动时触发 */
+    onScrollStart?: (data: ScrollEventData) => void;
+    /** 滚动结束时触发（防抖延迟，默认 150ms） */
+    onScrollEnd?: (data: ScrollEventData) => void;
+    /** 滚动结束防抖延迟时间（ms） */
+    scrollEndDelay?: number;
+    /** 到达顶部时触发 */
+    onReachTop?: (data: ScrollEventData) => void;
+    /** 到达底部时触发 */
+    onReachBottom?: (data: ScrollEventData) => void;
+    /** 到达左边时触发 */
+    onReachLeft?: (data: ScrollEventData) => void;
+    /** 到达右边时触发 */
+    onReachRight?: (data: ScrollEventData) => void;
+    /** 边界阈值（到达边界的像素阈值） */
+    reachThreshold?: number;
+    /** IntersectionObserver 配置 */
+    intersection?: IntersectionConfig;
+    /** 吸附滚动配置 */
+    snapScroll?: SnapScrollConfig;
+    /** 容器宽度 */
+    width?: number | string;
+    /** 容器高度 */
+    height?: number | string;
+    /** 最大宽度 */
+    maxWidth?: number | string;
+    /** 最大高度 */
+    maxHeight?: number | string;
+    /** 最小宽度 */
+    minWidth?: number | string;
+    /** 最小高度 */
+    minHeight?: number | string;
+    /** Ref 引用 */
+    ref?: React.Ref<PisellScrollViewRef>;
+    /** 设计模式 */
+    __designMode?: boolean;
+}
+/**
+ * 组件暴露的方法
+ */
+export interface PisellScrollViewRef {
+    /** 滚动到指定位置 */
+    scrollTo: (position: ScrollPosition) => void;
+    /** 滚动到指定元素 */
+    scrollToElement: (config: ScrollToElementConfig) => void;
+    /** 滚动到百分比位置 */
+    scrollToPercentage: (percentage: ScrollPercentage) => void;
+    /** 滚动到顶部 */
+    scrollToTop: (behavior?: 'auto' | 'smooth') => void;
+    /** 滚动到底部 */
+    scrollToBottom: (behavior?: 'auto' | 'smooth') => void;
+    /** 滚动到最左侧 */
+    scrollToLeft: (behavior?: 'auto' | 'smooth') => void;
+    /** 滚动到最右侧 */
+    scrollToRight: (behavior?: 'auto' | 'smooth') => void;
+    /** 获取当前滚动信息 */
+    getScrollData: () => ScrollEventData;
+    /** 获取滚动容器 DOM 元素 */
+    getScrollContainer: () => HTMLElement | null;
+    /** 滚动到指定吸附点（索引） */
+    scrollToSnapPoint: (index: number, behavior?: 'auto' | 'smooth') => void;
+    /** 获取所有吸附点位置 */
+    getSnapPoints: () => number[];
+    /** 获取当前吸附点索引 */
+    getCurrentSnapIndex: () => number;
+    /** 滚动到下一个吸附点 */
+    scrollToNextSnap: (behavior?: 'auto' | 'smooth') => void;
+    /** 滚动到上一个吸附点 */
+    scrollToPrevSnap: (behavior?: 'auto' | 'smooth') => void;
+}

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

@@ -0,0 +1,155 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import PisellSteps from './PisellSteps';
+/**
+ * PisellSteps 步骤条组件
+ *
+ * 基于 Ant Design Steps 组件进行二次封装和增强
+ * 支持多种展示样式、布局方式和丰富的交互功能
+ */
+declare const meta: Meta<typeof PisellSteps>;
+export default meta;
+declare type Story = StoryObj<typeof PisellSteps>;
+/**
+ * 基础用法 - 默认步骤条
+ */
+export declare const Default: Story;
+/**
+ * 非受控模式
+ * @description 使用 defaultCurrent 设置初始步骤
+ */
+export declare const Uncontrolled: Story;
+/**
+ * 垂直方向
+ */
+export declare const Vertical: Story;
+/**
+ * 点状步骤条
+ * @description 通过 progressDot 属性启用点状样式
+ */
+export declare const Dot: Story;
+/**
+ * 自定义点状渲染
+ * @description 使用函数自定义点状图标的渲染
+ */
+export declare const CustomProgressDot: Story;
+/**
+ * 导航步骤条
+ */
+export declare const Navigation: Story;
+/**
+ * 小尺寸
+ */
+export declare const Small: Story;
+/**
+ * 大尺寸
+ */
+export declare const Large: Story;
+/**
+ * 标签垂直布局
+ * @description 标签在图标下方显示
+ */
+export declare const LabelVertical: Story;
+/**
+ * 错误状态
+ */
+export declare const ErrorStatus: Story;
+/**
+ * 自定义步骤状态
+ * @description 每个步骤可以单独设置状态
+ */
+export declare const CustomStatus: Story;
+/**
+ * 可点击步骤
+ */
+export declare const Clickable: Story;
+/**
+ * 禁止点击已完成步骤
+ * @description 设置 allowClickFinished 为 false
+ */
+export declare const DisallowClickFinished: Story;
+/**
+ * 禁用特定步骤
+ * @description 通过 disabled 属性禁用某个步骤
+ */
+export declare const DisabledStep: Story;
+/**
+ * 自定义图标
+ */
+export declare const CustomIcon: Story;
+/**
+ * 完成图标
+ */
+export declare const FinishIcon: Story;
+/**
+ * 栅格布局
+ * @description 启用栅格布局，自定义列数
+ */
+export declare const GridLayout: Story;
+/**
+ * 自定义图标与文本间距
+ * @description 通过 itemGap 属性自定义间距
+ */
+export declare const CustomItemGap: Story;
+/**
+ * 移动端 - 完整模式
+ * @description 移动端显示完整步骤条
+ */
+export declare const MobileModeFull: Story;
+/**
+ * 移动端 - 当前步骤模式
+ * @description 只显示当前步骤信息
+ */
+export declare const MobileModeCurrent: Story;
+/**
+ * 移动端 - 自动模式
+ * @description 根据屏幕宽度自动切换显示模式
+ */
+export declare const MobileModeAuto: Story;
+/**
+ * 自定义移动端断点
+ * @description 通过 mobileBreakpoint 自定义断点宽度
+ */
+export declare const CustomMobileBreakpoint: Story;
+/**
+ * 自定义起始索引
+ * @description 通过 initial 设置起始步骤索引
+ */
+export declare const InitialIndex: Story;
+/**
+ * 隐藏特定步骤
+ * @description 通过 hidden 属性动态隐藏步骤
+ */
+export declare const HiddenStep: Story;
+/**
+ * 带子标题
+ * @description 步骤可以包含子标题
+ */
+export declare const WithSubTitle: Story;
+/**
+ * 响应式步骤条
+ * @description 开启响应式后会自动调整布局
+ */
+export declare const Responsive: Story;
+/**
+ * 完整功能演示
+ * @description 展示多种功能的组合使用
+ */
+export declare const FullFeature: Story;
+/**
+ * 多步骤流程
+ * @description 更多步骤的场景
+ */
+export declare const ManySteps: Story;
+/**
+ * 购物流程示例
+ * @description 模拟真实的购物流程
+ */
+export declare const ShoppingFlow: Story;
+/**
+ * 交互测试 - 点击步骤
+ */
+export declare const InteractionTest: Story;
+/**
+ * 交互测试 - 验证组件渲染
+ */
+export declare const RenderTest: Story;

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

@@ -0,0 +1,4 @@
+export { useStepsState } from './useStepsState';
+export { useStepClick } from './useStepClick';
+export { useAnchor } from './useAnchor';
+export { useResponsive } from './useResponsive';

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

@@ -0,0 +1,9 @@
+/**
+ * 锚链接功能 Hook
+ * 当开启锚链接时，自动滚动到当前步骤对应的锚点
+ *
+ * @param currentStep - 当前步骤索引
+ * @param enableAnchor - 是否启用锚链接
+ * @param anchorContainer - 锚链接容器选择器或元素
+ */
+export declare function useAnchor(currentStep: number, enableAnchor: boolean, anchorContainer?: string | HTMLElement): void;

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

@@ -0,0 +1,8 @@
+/**
+ * 响应式监听 Hook
+ * 监听窗口大小变化，返回当前是否为移动端
+ *
+ * @param breakpoint - 断点宽度（默认 768px）
+ * @returns 是否为移动端
+ */
+export declare function useResponsive(breakpoint?: number): boolean;

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

@@ -0,0 +1,11 @@
+import type { PisellStepItem } from '../types';
+/**
+ * 处理步骤点击逻辑的 Hook
+ *
+ * @param currentStep - 当前步骤索引
+ * @param clickable - 是否允许点击步骤切换
+ * @param allowClickFinished - 是否允许点击已完成的步骤
+ * @param onStepChange - 步骤变更回调函数
+ * @returns 步骤点击处理函数
+ */
+export declare function useStepClick(currentStep: number, clickable: boolean, allowClickFinished: boolean, onStepChange: (step: number) => void): (index: number, item: PisellStepItem) => void;

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

@@ -0,0 +1,9 @@
+/**
+ * 管理步骤条状态的 Hook（支持受控和非受控模式）
+ *
+ * @param current - 受控模式下的当前步骤
+ * @param defaultCurrent - 非受控模式下的默认当前步骤
+ * @param onChange - 步骤变更回调函数
+ * @returns [currentStep, setCurrentStep] - 当前步骤和设置步骤的函数
+ */
+export declare function useStepsState(current?: number, defaultCurrent?: number, onChange?: (current: number) => void): [number, (value: number) => void];

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

@@ -0,0 +1,3 @@
+import PisellSteps from './PisellSteps';
+export type { PisellStepsProps, PisellStepItem, StepStatus, StepDirection, StepSize } from './types';
+export default PisellSteps;

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

@@ -0,0 +1,257 @@
+import type { StepsProps, StepProps } from 'antd';
+import type { CSSProperties, ReactNode } from 'react';
+import type { ScrollActionsConfig } from '../PisellScrollView/types';
+/**
+ * 步骤状态类型
+ */
+export declare type StepStatus = 'wait' | 'process' | 'finish' | 'error';
+/**
+ * 步骤条方向
+ */
+export declare type StepDirection = 'horizontal' | 'vertical';
+/**
+ * 步骤条尺寸
+ */
+export declare type StepSize = 'small' | 'default' | 'large';
+/**
+ * 标签放置位置
+ */
+export declare type StepLabelPlacement = 'horizontal' | 'vertical';
+/**
+ * 单个步骤项配置
+ */
+export interface PisellStepItem extends Omit<StepProps, 'status' | 'onClick'> {
+    /**
+     * 步骤标题
+     */
+    title?: ReactNode;
+    /**
+     * 步骤副标题
+     */
+    subTitle?: ReactNode;
+    /**
+     * 步骤描述
+     */
+    description?: ReactNode;
+    /**
+     * 步骤状态
+     * @default 'wait'
+     */
+    status?: StepStatus;
+    /**
+     * 步骤图标
+     */
+    icon?: ReactNode;
+    /**
+     * 是否禁用点击
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 是否隐藏该步骤（用于动态步骤）
+     * @default false
+     */
+    hidden?: boolean;
+    /**
+     * 步骤点击回调
+     */
+    onClick?: () => void;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * 额外的数据（可用于业务扩展）
+     */
+    extra?: Record<string, any>;
+}
+/**
+ * PisellSteps 组件 Props
+ */
+export interface PisellStepsProps extends Omit<StepsProps, 'items' | 'onChange' | 'current' | 'status' | 'size' | 'direction'> {
+    /**
+     * 步骤条类型（直接使用 antd 的 type）
+     * @description 'default' - 默认样式，'navigation' - 导航样式
+     * @description dot 模式通过 progressDot 属性来控制，不需要单独的 type
+     * @default 'default'
+     */
+    type?: StepsProps['type'];
+    /**
+     * 当前步骤（受控模式）
+     */
+    current?: number;
+    /**
+     * 默认当前步骤（非受控模式）
+     * @default 0
+     */
+    defaultCurrent?: number;
+    /**
+     * 步骤条方向
+     * @default 'horizontal'
+     */
+    direction?: StepDirection;
+    /**
+     * 步骤条尺寸
+     * @default 'default'
+     */
+    size?: StepSize;
+    /**
+     * 当前步骤的状态
+     * @default 'process'
+     */
+    status?: StepStatus;
+    /**
+     * 起始步骤索引
+     * @default 0
+     */
+    initial?: number;
+    /**
+     * 步骤数据配置
+     */
+    items?: PisellStepItem[];
+    /**
+     * 标签文本位置（标识区和文本区的布局方式）
+     * @description 'horizontal' - 文本在图标右侧（水平布局），'vertical' - 文本在图标下方（垂直布局）
+     * @description 仅在 direction='horizontal' 时生效
+     * @default 'horizontal'
+     */
+    labelPlacement?: StepLabelPlacement;
+    /**
+     * 是否开启响应式
+     * @default true
+     */
+    responsive?: boolean;
+    /**
+     * 步骤变更回调
+     */
+    onChange?: (current: number) => void;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * 点状步骤条是否显示点（也可以传入自定义渲染函数）
+     * @default false
+     */
+    progressDot?: boolean | ((dot: ReactNode, info: {
+        index: number;
+        status: StepStatus;
+        title?: ReactNode;
+        description?: ReactNode;
+    }) => ReactNode);
+    /**
+     * 是否允许点击步骤切换
+     * @default false
+     */
+    clickable?: boolean;
+    /**
+     * 是否允许点击已完成的步骤
+     * @default true
+     */
+    allowClickFinished?: boolean;
+    /**
+     * 是否开启栅格布局
+     * @default false
+     */
+    gridLayout?: boolean;
+    /**
+     * 栅格列数（仅在 gridLayout=true 时有效）
+     */
+    gridColumns?: number;
+    /**
+     * 标识区和文本区的间距（单位：px）
+     * @description 控制图标和文本之间的间距
+     */
+    itemGap?: number;
+    /**
+     * 是否开启锚链接
+     * @default false
+     */
+    enableAnchor?: boolean;
+    /**
+     * 锚链接容器选择器（仅在 enableAnchor=true 时有效）
+     */
+    anchorContainer?: string | HTMLElement;
+    /**
+     * 移动端显示模式
+     * - 'full': 显示完整步骤条（默认）
+     * - 'current': 只显示当前步骤信息
+     * - 'auto': 自动根据屏幕宽度切换（<744px 时显示当前步骤）
+     * @default 'full'
+     */
+    mobileMode?: 'full' | 'current' | 'auto';
+    /**
+     * 移动端断点宽度（单位：px）
+     * @default 744
+     */
+    mobileBreakpoint?: number;
+    /**
+     * 是否启用横向滚动模式
+     * @description 当步骤条宽度不足时，启用横向滚动并显示左右箭头按钮
+     * @default false
+     */
+    enableScrollMode?: boolean;
+    /**
+     * 滚动箭头配置
+     * @description 配置滚动箭头的显示类型和滚动距离
+     */
+    scrollActionsConfig?: ScrollActionsConfig;
+    /**
+     * 设计模式标识（低代码引擎使用）
+     */
+    __designMode?: 'design' | 'preview';
+    /**
+     * 组件唯一标识（低代码引擎使用）
+     */
+    __id?: string;
+    /**
+     * 其他扩展配置
+     */
+    other?: Record<string, any>;
+}
+/**
+ * 步骤点击事件参数
+ */
+export interface StepClickInfo {
+    /**
+     * 步骤索引
+     */
+    index: number;
+    /**
+     * 步骤配置
+     */
+    item: PisellStepItem;
+    /**
+     * 步骤状态
+     */
+    status: StepStatus;
+    /**
+     * 是否可点击
+     */
+    clickable: boolean;
+}
+/**
+ * 步骤变更事件参数
+ */
+export interface StepChangeInfo {
+    /**
+     * 当前步骤索引
+     */
+    current: number;
+    /**
+     * 上一个步骤索引
+     */
+    previous: number;
+    /**
+     * 步骤变更方向
+     */
+    direction: 'forward' | 'backward';
+}