ai-code-app/docs/components/stepper.md

Stepper

목적

여러 단계를 순서대로 표시하고 현재 진행 위치를 강조하는 stepper 컴포넌트입니다.

공통 설계 원칙

• 샘플(samples)을 제외한 컴포넌트에는 API 호출이나 화면 전용 로직을 직접 넣지 않습니다.
• 컴포넌트는 최대한 멍청하게 설계하고, 직관적인 props를 받아 직관적인 UI 동작만 수행합니다.
• 기능 처리와 비즈니스 로직은 src/features 또는 해당 화면 전용 패키지 레벨에서 담당합니다.
• 공통 컴포넌트는 여러 곳에서 재사용되므로, 수정 시에는 기존 동작을 바꾸지 않는 범위에서만 보완합니다.

구현 위치

src/components/stepper
├─ StepperUI.tsx
├─ index.ts
├─ types.ts
└─ samples/
   └─ BaseSample.tsx

특징

• 내부적으로 ProcessFlowUI를 재사용해 동일한 상태 표현과 스타일을 유지합니다.
• horizontal, vertical 두 방향을 지원합니다.
• currentStepKey만 넘겨도 현재 단계를 기준으로 완료/진행중/대기 상태를 계산합니다.
• 각 단계에 status를 직접 지정하면 수동 상태 제어도 가능합니다.
• compact, showConnector, statusLabels, statusIcons, statusStyles를 그대로 사용할 수 있습니다.

기본 예시

<Stepper
  steps={[
    { key: 'draft', label: '초안' },
    { key: 'review', label: '검토' },
    { key: 'done', label: '완료' },
  ]}
  currentStepKey="review"
/>

참고

• Stepper와 StepperUI를 함께 export하므로 둘 중 하나를 선택해 사용할 수 있습니다.
• ProcessFlowUI의 별칭 성격 컴포넌트이므로 동작 규칙과 스타일 계열은 동일합니다.
• 대표 샘플은 src/components/stepper/samples/BaseSample.tsx를 사용합니다.