@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/steps/index.tsx

@@ -0,0 +1,500 @@
+/**
+ * 步骤条 Steps
+ *
+ * 引导用户按流程完成任务的导航条，展示当前所处步骤。
+ * 支持三种形态：circle（圆圈带数字）、dot（小圆点）、arrow（箭头色带）。
+ *
+ * @when
+ * - 任务需分多步完成且步骤间有先后顺序
+ * - 需要清晰展示当前进度和各步骤状态
+ * - 配合表单向导、创建流程等场景
+ */
+
+import * as React from 'react';
+import { Check, X } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type StepStatus = 'wait' | 'process' | 'finish' | 'error' | 'disabled';
+
+export interface StepItem {
+  /** 步骤标题（必填）。 */
+  title: React.ReactNode;
+  /** 步骤描述。 */
+  description?: React.ReactNode;
+  /** 自定义状态（覆盖 current 推导）。disabled 不响应点击。 */
+  status?: StepStatus;
+  /** 自定义图标（覆盖默认数字/勾选/错误，仅 circle 形态生效）。 */
+  icon?: React.ReactNode;
+}
+
+export interface StepsProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** 步骤列表。 */
+  items: StepItem[];
+  /** 当前步骤（0-based）。current 之前为 finish，当前为 process，之后为 wait。 @default 0 */
+  current?: number;
+  /** 当前步骤的状态。 @default "process" */
+  status?: 'process' | 'error';
+  /** 步骤点形态。arrow 为箭头色带，circle 为圆圈带数字，dot 为小圆点。 @default "circle" */
+  shape?: 'circle' | 'dot' | 'arrow';
+  /** 排列方向（arrow 形态仅支持 horizontal）。 @default "horizontal" */
+  direction?: 'horizontal' | 'vertical';
+  /** 标签放置方向（circle/dot 生效）。vertical 标签在指示器下方，horizontal 标签在右侧。 @default "vertical" */
+  labelPlacement?: 'horizontal' | 'vertical';
+  /** 尺寸。 @default "default" */
+  size?: 'sm' | 'default';
+  /** 步骤点击回调。传入后各步骤可点击。 */
+  onChange?: (index: number) => void;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+function deriveStatus(
+  index: number,
+  current: number,
+  topStatus: 'process' | 'error',
+  itemStatus?: StepStatus,
+): StepStatus {
+  if (itemStatus) return itemStatus;
+  if (index < current) return 'finish';
+  if (index === current) return topStatus;
+  return 'wait';
+}
+
+const circleStyles: Record<StepStatus, string> = {
+  wait: 'border-border bg-background text-muted-foreground',
+  process: 'border-primary bg-primary text-primary-foreground shadow-sm',
+  finish: 'border-primary bg-primary text-primary-foreground',
+  error: 'border-destructive bg-destructive text-destructive-foreground',
+  disabled: 'border-border bg-muted text-muted-foreground opacity-60',
+};
+
+const dotShapeStyles: Record<StepStatus, string> = {
+  wait: 'border-border bg-background',
+  process: 'border-primary bg-primary shadow-sm',
+  finish: 'border-primary bg-background',
+  error: 'border-destructive bg-destructive',
+  disabled: 'border-border bg-muted opacity-60',
+};
+
+const lineStyles: Record<StepStatus, string> = {
+  wait: 'bg-border',
+  process: 'bg-border',
+  finish: 'bg-primary',
+  error: 'bg-border',
+  disabled: 'bg-border opacity-60',
+};
+
+const titleStyles: Record<StepStatus, string> = {
+  wait: 'text-muted-foreground',
+  process: 'text-foreground font-medium',
+  finish: 'text-foreground',
+  error: 'text-destructive font-medium',
+  disabled: 'text-muted-foreground opacity-60',
+};
+
+const arrowStyles: Record<StepStatus, string> = {
+  wait: 'bg-muted text-muted-foreground',
+  process: 'bg-primary text-primary-foreground',
+  finish: 'bg-primary/10 text-primary',
+  error: 'bg-destructive/10 text-destructive',
+  disabled: 'bg-muted text-muted-foreground opacity-60',
+};
+
+// ─── Arrow Shape ─────────────────────────────────────────────────────────────
+
+const ArrowSteps = React.forwardRef<
+  HTMLDivElement,
+  Omit<StepsProps, 'shape' | 'direction' | 'labelPlacement'> & {
+    current: number;
+    status: 'process' | 'error';
+  }
+>(({ items, current, status, size, onChange, className, ...props }, ref) => {
+  const h = size === 'sm' ? 'h-8' : 'h-10';
+  // 45° 等腰三角形箭头：NOTCH = 高度的一半。h-10 (40px) → 20px；h-8 (32px) → 16px。
+  const NOTCH = size === 'sm' ? 16 : 20;
+
+  const buildClipPath = (
+    isFirst: boolean,
+    isLast: boolean,
+  ): string | undefined => {
+    if (isFirst && isLast) return undefined;
+    if (isFirst) {
+      return `polygon(0% 0%, calc(100% - ${NOTCH}px) 0%, 100% 50%, calc(100% - ${NOTCH}px) 100%, 0% 100%)`;
+    }
+    if (isLast) {
+      return `polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%, ${NOTCH}px 50%)`;
+    }
+    return `polygon(0% 0%, calc(100% - ${NOTCH}px) 0%, 100% 50%, calc(100% - ${NOTCH}px) 100%, 0% 100%, ${NOTCH}px 50%)`;
+  };
+
+  return (
+    <div
+      ref={ref}
+      data-slot="steps"
+      className={cn('flex flex-row', className)}
+      {...props}
+    >
+      {items.map((item, i) => {
+        const s = deriveStatus(i, current, status, item.status);
+        const isFirst = i === 0;
+        const isLast = i === items.length - 1;
+        const isDisabled = s === 'disabled';
+        const clickable = !!onChange && !isDisabled;
+        const clipPath = buildClipPath(isFirst, isLast);
+
+        return (
+          <button
+            key={i}
+            type="button"
+            tabIndex={clickable ? 0 : -1}
+            onClick={clickable ? () => onChange!(i) : undefined}
+            aria-disabled={isDisabled || undefined}
+            style={{
+              ...(clipPath ? { clipPath } : {}),
+              // 除首个外，后续 step 用 negative margin 贴合上个尖角，保留 4px 视觉间距
+              ...(isFirst ? {} : { marginLeft: -(NOTCH - 4) }),
+            }}
+            className={cn(
+              'flex flex-1 items-center justify-center text-xs font-medium transition-colors',
+              h,
+              arrowStyles[s],
+              isFirst && 'rounded-l-md',
+              isLast && 'rounded-r-md',
+              !isFirst && 'pl-4',
+              !isLast && 'pr-4',
+              isDisabled && 'pointer-events-none',
+              clickable && 'cursor-pointer hover:opacity-90',
+            )}
+          >
+            <span className="truncate px-2">{item.title}</span>
+          </button>
+        );
+      })}
+    </div>
+  );
+});
+ArrowSteps.displayName = 'ArrowSteps';
+
+// ─── Circle / Dot Shapes ─────────────────────────────────────────────────────
+
+function CircleDotSteps({
+  items,
+  current,
+  status,
+  shape,
+  direction,
+  labelPlacement,
+  size,
+  onChange,
+  className,
+  forwardedRef,
+  ...props
+}: Omit<StepsProps, 'shape'> & {
+  shape: 'circle' | 'dot';
+  current: number;
+  status: 'process' | 'error';
+  direction: 'horizontal' | 'vertical';
+  labelPlacement: 'horizontal' | 'vertical';
+  forwardedRef?: React.Ref<HTMLDivElement>;
+}) {
+  const isVertical = direction === 'vertical';
+  const isLabelHorizontal = labelPlacement === 'horizontal';
+  const isDot = shape === 'dot';
+  // “vertical labelPlacement (标签在下方) + horizontal direction”是需要 absolute 定位的默认模式
+  const isStackedHorizontal = !isVertical && !isLabelHorizontal;
+
+  // 调粗尺寸：Circle 24px / Dot 12px；sm Circle 20px / Dot 10px。
+  const indicatorPx = isDot
+    ? size === 'sm'
+      ? 10
+      : 12
+    : size === 'sm'
+    ? 20
+    : 24;
+  const indicatorSizeClass = isDot
+    ? size === 'sm'
+      ? 'size-2.5'
+      : 'size-3'
+    : size === 'sm'
+    ? 'size-5 text-xs'
+    : 'size-6 text-xs';
+  const iconSize = size === 'sm' ? 'size-3' : 'size-3.5';
+
+  // Circle 标题加粗 14px；Dot 标题 text-xs
+  const titleClass = isDot
+    ? 'text-xs'
+    : size === 'sm'
+    ? 'text-xs font-medium'
+    : 'text-sm font-medium';
+
+  // 参考 cloud-design / @alifd/next 实现：absolute 定位 + 固定 96px 宽度，让 label 中心精准对齐 indicator 中心。
+  const LABEL_WIDTH = size === 'sm' ? 80 : 96;
+  const LABEL_GAP = 8; // indicator 下方与 label 顶部距离
+  // 首尾 label 水平溝出量：(LABEL_WIDTH - indicator) / 2。容器 paddingX 取该值让首尾 label 刚好贴合容器边界。
+  const labelOverflowPx = (LABEL_WIDTH - indicatorPx) / 2;
+  // 预留 label 高度（title text-sm/xs ~ 20/16px + gap 2 + description text-xs ~16px）
+  const stackedPaddingBottom = isDot
+    ? size === 'sm'
+      ? 56
+      : 64
+    : size === 'sm'
+    ? 64
+    : 72;
+
+  // horizontal labelPlacement 模式下，title 与 indicator 水平居中需的 paddingTop
+  const titlePtForHorizontalLabel = isDot
+    ? '0px'
+    : size === 'sm'
+    ? '2px'
+    : '4px';
+
+  // vertical direction 下 step 容器 paddingTop：让下个 step 的 indicator 与上个 line 末端保持 8px 间距（与 gap-2 对称）。
+  // 整个 step 容器一起下移，indicator 与 title 顶端对齐关系不变。
+
+  return (
+    <div
+      ref={forwardedRef}
+      data-slot="steps"
+      className={cn(
+        'flex',
+        isVertical ? 'flex-col gap-0' : 'flex-row items-start gap-0',
+        className,
+      )}
+      style={
+        isStackedHorizontal
+          ? {
+              // 首尾 label 不渢出容器边界：容器左右各预留 (LABEL_WIDTH - indicator) / 2
+              paddingLeft: labelOverflowPx,
+              paddingRight: labelOverflowPx,
+            }
+          : undefined
+      }
+      {...props}
+    >
+      {items.map((item, i) => {
+        const s = deriveStatus(i, current, status, item.status);
+        const isLast = i === items.length - 1;
+        const isDisabled = s === 'disabled';
+        const clickable = !!onChange && !isDisabled;
+
+        // Icon only for circle shape
+        const icon = isDot
+          ? null
+          : item.icon ??
+            (s === 'finish' ? (
+              <Check className={iconSize} />
+            ) : s === 'error' ? (
+              <X className={iconSize} />
+            ) : (
+              i + 1
+            ));
+
+        const indicatorBtn = (
+          <button
+            type="button"
+            tabIndex={clickable ? 0 : -1}
+            onClick={clickable ? () => onChange!(i) : undefined}
+            className={cn(
+              'flex shrink-0 items-center justify-center rounded-full border border-border transition-colors',
+              isDot
+                ? cn(indicatorSizeClass, dotShapeStyles[s])
+                : cn(
+                    indicatorSizeClass,
+                    'font-medium tabular-nums',
+                    circleStyles[s],
+                  ),
+              clickable && 'cursor-pointer hover:opacity-80',
+            )}
+          >
+            {icon}
+          </button>
+        );
+
+        const lineEl =
+          !isLast && !isLabelHorizontal ? (
+            <div
+              className={cn(
+                'transition-colors',
+                lineStyles[s],
+                isVertical ? 'min-h-8 w-0.5 flex-1' : 'mx-2 h-0.5 flex-1',
+              )}
+            />
+          ) : null;
+
+        // horizontal labelPlacement 模式下，line 在 label 右侧横向伸展到下个 step
+        const horizontalLabelLineEl =
+          !isVertical && isLabelHorizontal && !isLast ? (
+            <div
+              className={cn(
+                'mx-2 h-0.5 flex-1 transition-colors',
+                lineStyles[s],
+              )}
+            />
+          ) : null;
+
+        // 分支 1：stacked horizontal（label 在 indicator 下方）——absolute 定位
+        if (isStackedHorizontal) {
+          // 参考 cloud-design 实现：前 n-1 个 step 平均分享 (100% - indicator) 宽度，最后一个仅占 indicator 宽。
+          // 这样总宽仍为 100%，且首尾 step 的 indicator 位置能让 absolute label 在容器 paddingX 补偿下刚好不渢出。
+          const itemWidth =
+            items.length === 1
+              ? `${indicatorPx}px`
+              : isLast
+              ? `${indicatorPx}px`
+              : `calc((100% - ${indicatorPx}px) / ${items.length - 1})`;
+          return (
+            <div
+              key={i}
+              aria-disabled={isDisabled || undefined}
+              className={cn(
+                'relative flex flex-col',
+                isDisabled && 'pointer-events-none',
+              )}
+              style={{
+                width: itemWidth,
+                flex: 'none',
+                paddingBottom: stackedPaddingBottom,
+              }}
+            >
+              {/* indicator + line 行 */}
+              <div
+                className="flex w-full items-center"
+                style={{ height: indicatorPx }}
+              >
+                {indicatorBtn}
+                {lineEl}
+              </div>
+              {/* label 块：absolute，固定宽，水平居中于 indicator */}
+              <div
+                className="absolute flex flex-col gap-0.5 text-center"
+                style={{
+                  top: indicatorPx + LABEL_GAP,
+                  left: indicatorPx / 2 - LABEL_WIDTH / 2,
+                  width: LABEL_WIDTH,
+                }}
+              >
+                <div className={cn(titleClass, titleStyles[s])}>
+                  {item.title}
+                </div>
+                {item.description && (
+                  <div className="text-xs text-muted-foreground">
+                    {item.description}
+                  </div>
+                )}
+              </div>
+            </div>
+          );
+        }
+
+        // 分支 2：horizontal labelPlacement（label 在 indicator 右侧）或 vertical direction
+        // horizontal label 下：前 n-1 个 step flex-1（line 擑开剩余），最后一个 flex-none（仅占 indicator+label 宽），这样总宽全充，最后一个 step 贴右。
+        return (
+          <div
+            key={i}
+            aria-disabled={isDisabled || undefined}
+            className={cn(
+              'flex',
+              isVertical
+                ? 'flex-1 flex-row gap-3 pt-2'
+                : isLast
+                ? 'flex-row items-center gap-2'
+                : 'flex-1 flex-row items-center gap-2',
+              isDisabled && 'pointer-events-none',
+            )}
+          >
+            <div
+              className={cn(
+                'flex items-center',
+                isVertical ? 'flex-col gap-2' : 'flex-row gap-0',
+              )}
+            >
+              {indicatorBtn}
+              {lineEl}
+            </div>
+            <div
+              className={cn(
+                'flex flex-col gap-0.5',
+                isVertical && 'flex-1 pb-6',
+                !isVertical && 'shrink-0',
+              )}
+              style={
+                !isVertical && isLabelHorizontal
+                  ? {
+                      paddingTop: titlePtForHorizontalLabel,
+                      maxWidth: LABEL_WIDTH,
+                    }
+                  : undefined
+              }
+            >
+              <div className={cn(titleClass, titleStyles[s])}>{item.title}</div>
+              {item.description && (
+                <div className="text-xs text-muted-foreground">
+                  {item.description}
+                </div>
+              )}
+            </div>
+            {horizontalLabelLineEl}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// ─── Steps ──────────────────────────────────────────────────────────────────
+
+const Steps = React.forwardRef<HTMLDivElement, StepsProps>(
+  (
+    {
+      items,
+      current = 0,
+      status = 'process',
+      shape = 'circle',
+      direction = 'horizontal',
+      labelPlacement = 'vertical',
+      size = 'default',
+      onChange,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    if (shape === 'arrow') {
+      return (
+        <ArrowSteps
+          ref={ref}
+          items={items}
+          current={current}
+          status={status}
+          size={size}
+          onChange={onChange}
+          className={className}
+          {...props}
+        />
+      );
+    }
+
+    return (
+      <CircleDotSteps
+        items={items}
+        current={current}
+        status={status}
+        shape={shape}
+        direction={direction}
+        labelPlacement={labelPlacement}
+        size={size}
+        onChange={onChange}
+        className={className}
+        forwardedRef={ref}
+        {...props}
+      />
+    );
+  },
+);
+Steps.displayName = 'Steps';
+
+export { Steps };