@pisell/materials 3.3.77 → 3.3.79

package/es/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/es/components/PisellSteps/hooks/index.js

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

package/es/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/es/components/PisellSteps/hooks/useAnchor.js

@@ -0,0 +1,60 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * 锚链接功能 Hook
+ * 当开启锚链接时，自动滚动到当前步骤对应的锚点
+ * 
+ * @param currentStep - 当前步骤索引
+ * @param enableAnchor - 是否启用锚链接
+ * @param anchorContainer - 锚链接容器选择器或元素
+ */
+export function useAnchor(currentStep, enableAnchor, anchorContainer) {
+  var previousStepRef = useRef(currentStep);
+  useEffect(function () {
+    // SSR 环境下不执行
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      return;
+    }
+
+    // 未启用锚链接，直接返回
+    if (!enableAnchor) {
+      return;
+    }
+
+    // 步骤未发生变化，直接返回
+    if (previousStepRef.current === currentStep) {
+      return;
+    }
+
+    // 更新上一步记录
+    previousStepRef.current = currentStep;
+
+    // 查找锚点元素
+    var anchorId = "pisell-steps-anchor-".concat(currentStep);
+    var anchorElement = document.getElementById(anchorId);
+    if (!anchorElement) {
+      return;
+    }
+
+    // 获取滚动容器
+    var scrollContainer = window;
+    if (anchorContainer) {
+      if (typeof anchorContainer === 'string') {
+        var container = document.querySelector(anchorContainer);
+        if (container instanceof HTMLElement) {
+          scrollContainer = container;
+        }
+      } else if (anchorContainer instanceof HTMLElement) {
+        scrollContainer = anchorContainer;
+      }
+    }
+
+    // 滚动到锚点
+    var scrollOptions = {
+      behavior: 'smooth',
+      block: 'start',
+      inline: 'nearest'
+    };
+    anchorElement.scrollIntoView(scrollOptions);
+  }, [currentStep, enableAnchor, anchorContainer]);
+}

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

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

package/es/components/PisellSteps/hooks/useResponsive.js

@@ -0,0 +1,43 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+import { useEffect, useState } from 'react';
+
+/**
+ * 响应式监听 Hook
+ * 监听窗口大小变化，返回当前是否为移动端
+ * 
+ * @param breakpoint - 断点宽度（默认 768px）
+ * @returns 是否为移动端
+ */
+export function useResponsive() {
+  var breakpoint = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 768;
+  var _useState = useState(typeof window !== 'undefined' ? window.innerWidth < breakpoint : false),
+    _useState2 = _slicedToArray(_useState, 2),
+    isMobile = _useState2[0],
+    setIsMobile = _useState2[1];
+  useEffect(function () {
+    // 服务端渲染时不执行
+    if (typeof window === 'undefined') {
+      return;
+    }
+    var handleResize = function handleResize() {
+      setIsMobile(window.innerWidth < breakpoint);
+    };
+
+    // 添加监听器
+    window.addEventListener('resize', handleResize);
+
+    // 初始化检查
+    handleResize();
+
+    // 清理监听器
+    return function () {
+      window.removeEventListener('resize', handleResize);
+    };
+  }, [breakpoint]);
+  return isMobile;
+}

package/es/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/es/components/PisellSteps/hooks/useStepClick.js

@@ -0,0 +1,35 @@
+import { useCallback } from 'react';
+import { isStepClickable } from "../utils";
+
+/**
+ * 处理步骤点击逻辑的 Hook
+ * 
+ * @param currentStep - 当前步骤索引
+ * @param clickable - 是否允许点击步骤切换
+ * @param allowClickFinished - 是否允许点击已完成的步骤
+ * @param onStepChange - 步骤变更回调函数
+ * @returns 步骤点击处理函数
+ */
+export function useStepClick(currentStep, clickable, allowClickFinished, onStepChange) {
+  var handleStepClick = useCallback(function (index, item) {
+    // 检查是否禁用
+    if (item.disabled) {
+      return;
+    }
+
+    // 检查是否可点击
+    if (!clickable) {
+      return;
+    }
+
+    // 检查步骤状态是否允许点击
+    var canClick = isStepClickable(index, currentStep, item.status || 'wait', clickable, allowClickFinished);
+    if (!canClick) {
+      return;
+    }
+
+    // 触发步骤变更
+    onStepChange(index);
+  }, [currentStep, clickable, allowClickFinished, onStepChange]);
+  return handleStepClick;
+}

package/es/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/es/components/PisellSteps/hooks/useStepsState.js

@@ -0,0 +1,66 @@
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+import { useState, useCallback, useEffect, useRef } from 'react';
+
+/**
+ * 管理步骤条状态的 Hook（支持受控和非受控模式）
+ * 
+ * @param current - 受控模式下的当前步骤
+ * @param defaultCurrent - 非受控模式下的默认当前步骤
+ * @param onChange - 步骤变更回调函数
+ * @returns [currentStep, setCurrentStep] - 当前步骤和设置步骤的函数
+ */
+export function useStepsState(current) {
+  var defaultCurrent = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+  var onChange = arguments.length > 2 ? arguments[2] : undefined;
+  // 确保 defaultCurrent 是有效的数字
+  var safeDefaultCurrent = typeof defaultCurrent === 'number' && !isNaN(defaultCurrent) && defaultCurrent >= 0 ? defaultCurrent : 0;
+
+  // 确保 current 是有效的数字（如果提供）
+  var safeCurrent = current !== undefined && typeof current === 'number' && !isNaN(current) && current >= 0 ? current : undefined;
+
+  // 内部状态（非受控模式使用）
+  var _useState = useState(safeDefaultCurrent),
+    _useState2 = _slicedToArray(_useState, 2),
+    innerCurrent = _useState2[0],
+    setInnerCurrent = _useState2[1];
+
+  // 记录上一次的步骤，用于判断变更方向
+  var previousCurrentRef = useRef(safeDefaultCurrent);
+
+  // 判断是否为受控模式
+  var isControlled = safeCurrent !== undefined;
+
+  // 当前步骤值
+  var currentStep = isControlled ? safeCurrent : innerCurrent;
+
+  // 设置步骤的函数
+  var setCurrentStep = useCallback(function (value) {
+    var previousCurrent = previousCurrentRef.current;
+
+    // 非受控模式下更新内部状态
+    if (!isControlled) {
+      setInnerCurrent(value);
+    }
+
+    // 触发 onChange 回调
+    if (onChange && value !== previousCurrent) {
+      onChange(value);
+    }
+
+    // 更新上一次步骤记录
+    previousCurrentRef.current = value;
+  }, [isControlled, onChange]);
+
+  // 受控模式下，同步更新 previousCurrentRef
+  useEffect(function () {
+    if (isControlled && safeCurrent !== undefined) {
+      previousCurrentRef.current = safeCurrent;
+    }
+  }, [safeCurrent, isControlled]);
+  return [currentStep, setCurrentStep];
+}

package/es/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/es/components/PisellSteps/index.js

@@ -0,0 +1,2 @@
+import PisellSteps from "./PisellSteps";
+export default PisellSteps;

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

package/es/components/PisellSteps/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,54 @@
+import type { StepStatus } from '../types';
+/**
+ * 计算当前步骤的进度百分比
+ *
+ * @param current - 当前步骤索引
+ * @param total - 总步骤数
+ * @returns 进度百分比（0-100）
+ */
+export declare function calculateProgress(current: number, total: number): number;
+/**
+ * 判断步骤是否可点击
+ *
+ * @param index - 步骤索引
+ * @param current - 当前步骤索引
+ * @param status - 步骤状态
+ * @param clickable - 全局是否可点击
+ * @param allowClickFinished - 是否允许点击已完成步骤
+ * @returns 是否可点击
+ */
+export declare function isStepClickable(index: number, current: number, status: StepStatus, clickable: boolean, allowClickFinished: boolean): boolean;
+/**
+ * 获取步骤状态
+ *
+ * @param index - 步骤索引
+ * @param current - 当前步骤索引
+ * @param customStatus - 自定义状态（优先级最高）
+ * @returns 步骤状态
+ */
+export declare function getStepStatus(index: number, current: number, customStatus?: StepStatus): StepStatus;
+/**
+ * 合并步骤类名
+ *
+ * @param baseClass - 基础类名
+ * @param status - 步骤状态
+ * @param customClass - 自定义类名
+ * @returns 合并后的类名
+ */
+export declare function mergeStepClassName(baseClass: string, status: StepStatus, customClass?: string): string;
+/**
+ * 判断步骤变更方向
+ *
+ * @param from - 原步骤索引
+ * @param to - 目标步骤索引
+ * @returns 变更方向
+ */
+export declare function getChangeDirection(from: number, to: number): 'forward' | 'backward';
+/**
+ * 验证步骤索引是否有效
+ *
+ * @param index - 步骤索引
+ * @param total - 总步骤数
+ * @returns 是否有效
+ */
+export declare function isValidStepIndex(index: number, total: number): boolean;