ai-code-app/docs/components/process-flow-ui.md

Process Flow UI

목적

Plan, Board, History 화면에서 공통으로 사용할 수 있는 단계형 진행 표시 컴포넌트입니다. 현재 단계, 완료 단계, 실패 단계, 다음 대기 단계를 한 번에 보여주며 가로/세로 배치와 compact 모드를 지원합니다.

폴더 구조

src/components/processFlow
├─ samples/
│  └─ BaseSample.tsx
├─ types/
│  ├─ index.ts
│  └─ process-flow.ts
├─ ProcessFlowUI.css
├─ ProcessFlowUI.tsx
└─ index.ts

기본 Props

type ProcessFlowStepStatus = 'complete' | 'current' | 'failed' | 'pending';

type ProcessFlowStep = {
  key: string;
  label: ReactNode;
  description?: ReactNode;
  status?: ProcessFlowStepStatus;
};

type ProcessFlowUIProps = {
  steps: ProcessFlowStep[];
  currentStepKey?: string;
  direction?: 'horizontal' | 'vertical';
  compact?: boolean;
  showConnector?: boolean;
  onStepClick?: (step: ProcessFlowStep, index: number) => void;
  statusIcons?: Partial<Record<ProcessFlowStepStatus, ReactNode>>;
  statusStyles?: Partial<Record<ProcessFlowStepStatus, Partial<ProcessFlowStatusAppearance>>>;
  statusLabels?: Partial<Record<ProcessFlowStepStatus, string>>;
};

동작 규칙

• step.status 가 있으면 해당 상태를 우선 사용합니다.
• step.status 가 없으면 currentStepKey 기준으로 이전 단계는 complete, 현재 단계는 current, 이후 단계는 pending 으로 계산합니다.
• direction="horizontal" 은 넓은 화면에서 단계 흐름을 한 줄로 보여주고, 모바일 폭에서는 자동으로 세로 스택으로 바뀝니다.
• direction="vertical" 은 긴 설명이나 운영 절차처럼 텍스트가 많은 흐름에 적합합니다.
• compact 는 카드 안쪽, 테이블 상세, 모바일 요약 영역처럼 밀도가 필요한 구간에 사용합니다.

기본 예시

import { ProcessFlowUI } from '@/components/processFlow';

const steps = [
  { key: 'created', label: '등록' },
  { key: 'working', label: '작업중' },
  { key: 'done', label: '작업완료' },
  { key: 'released', label: '릴리즈완료' },
  { key: 'completed', label: '완료' },
];

export function PlanStatusFlow() {
  return <ProcessFlowUI steps={steps} currentStepKey="working" />;
}

상태 확장 예시

import { CheckOutlined, SyncOutlined } from '@ant-design/icons';

<ProcessFlowUI
  steps={steps}
  currentStepKey="released"
  statusIcons={{
    complete: <CheckOutlined />,
    current: <SyncOutlined spin />,
  }}
  statusStyles={{
    current: {
      accent: '#7c3aed',
      accentSoft: 'rgba(124, 58, 237, 0.12)',
      border: 'rgba(124, 58, 237, 0.22)',
      background: 'linear-gradient(180deg, rgba(245, 243, 255, 0.98) 0%, rgba(237, 233, 254, 0.84) 100%)',
      text: '#4c1d95',
      connector: 'rgba(124, 58, 237, 0.28)',
    },
  }}
/>

적용 예시

• Plan 상세: 등록 -> 작업중 -> 작업완료 -> 릴리즈완료 -> 완료
• release/main 반영 대기 흐름 표시
• Board 자동화 접수 후 현재 진행 단계 요약

재사용 가이드

• 공통 운영 상태를 이미 문자열로 보유하고 있다면 화면 레이어에서 steps 와 currentStepKey 로만 변환해서 바로 사용할 수 있습니다.
• 상태 라벨이 운영 용어와 다르면 statusLabels 로 화면별 텍스트만 바꿉니다.
• 프로젝트 고유 색이나 아이콘이 필요하면 statusStyles, statusIcons 만 덮어쓰고 기본 레이아웃은 유지합니다.