단계
순서가 있는 3~7단계의 한 가지 일에서 끝난 단계 · 지금 단계 · 다음 단계를 보입니다.
표지는 높이 사다리를 그대로 씁니다. 끝난 단계는 채운 칸(primary), 지금 단계는 솟은 칸 + primary 고리, 다음 단계는 파인 칸입니다. 오류는 느낌표 + 한 문장, 건너뜀은 빼기 + 점선입니다. 상태는 모양 · 굵기 · 이름 뒤 숨긴 글자로 함께 말하고, 이음선은 실선(지나옴) · 헤어라인(아직)으로 가릅니다.
- import
- import { Step, Stepper, StepperCompact } from "@uyoolabs/ui/ui";
- 쓰는 경우
- 워크스페이스 · 프로젝트 만들기, 결제 설정, 데이터 가져오기처럼 순서가 있는 3~7단계에 씁니다. 끝난 단계로 돌아가 고칠 수 있으면 그 단계를 링크(asChild)로 둡니다.
- 쓰지 않는 경우
- 2단계 이하(폼 하나로), 순서 없는 영역(Tabs 로), 진행률 대신으로 쓰지 않습니다. 이름 없이 숫자만 두지 않습니다. 지금 · 다음 단계를 링크로 만들지 않습니다(건너뛰어 앞으로 가지 않습니다). 끝난 단계에 ok(초록)를 쓰지 않습니다 — ok 는 상태의 뜻입니다.
- 알림 · 포커스
- Stepper 는 바뀐 단계를 알리지 않습니다. 단계가 바뀌면 앱이 새 단계의 제목으로 포커스를 옮깁니다(아래 예).
가로
기본. 단계 폭은 고르게 나누고 마지막 단계는 내용 폭입니다.
- 워크스페이스 정보, 끝남우유랩스 · 한국어
- 멤버 초대, 건너뜀나중에 초대합니다
- 결제 정보, 지금 단계카드 또는 계좌
- 가져오기 (선택), 다음
- 확인, 다음
오류
느낌표 표지 + 무엇이 틀렸는지 한 문장(description 이 없으면 개발 중 경고).
- 워크스페이스 정보, 끝남
- 멤버 초대, 끝남3명
- 결제 정보, 오류카드가 거절되었습니다
- 가져오기 (선택), 다음
- 확인, 다음
세로
단계가 길거나 지금 단계 안에 폼을 펼칠 때.
- 프로젝트 이름, 끝남3분기 로드맵
- 저장소 연결, 지금 단계코드와 작업을 잇습니다
(지금 단계의 폼이 여기에 섭니다)
- 권한 (선택), 다음누가 볼 수 있는지 정합니다
- 확인, 다음
좁은 화면
StepperCompact. 글자('결제 정보 · 3/5 단계')가 정보 전부이고 칸 막대는 장식입니다.
단계가 바뀔 때
앱이 새 단계 제목으로 포커스를 옮깁니다.
화면 낭독기 사용자는 새 제목을 듣고 그 단계의 폼으로 이어 갑니다. Stepper 의 aria-current 만 바뀌어서는 알 수 없습니다.
키보드
| 키 | 동작 |
|---|---|
| Tab | 링크 단계(끝난 단계)만 차례로 갑니다. 다른 단계는 탭 정지가 아닙니다. |
| Enter | 링크 단계로 이동합니다(링크 기본 동작). |
props
소스의 타입과 JSDoc 에서 생성한 표입니다. 컴포넌트를 고치면 pnpm gen 으로 다시 만듭니다.
Stepper
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| orientation | "horizontal" | "vertical" | "horizontal" | 기본 horizontal. 단계가 길거나 지금 단계 안에 폼을 펼치면 vertical |
| label | string | — | ol 의 접근성 이름. 없으면 labels.label |
| lang | "ko" | "en" | "ja" | — | |
| labels | Partial<StepperLabels> | — | |
| className | string | — | |
| children필수 | ReactNode | — | <Step> 들. 순서대로 번호가 붙는다 |
Step
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| status필수 | "done" | "current" | "upcoming" | "error" | "skipped" | — | |
| optional | boolean | — | 이름 옆 '(선택)' |
| description | ReactNode | — | 이름 아래 한 줄. status="error" 면 무엇이 틀렸는지 한 문장(필수, 없으면 개발 중 경고) |
| content | ReactNode | — | 세로일 때 지금 단계 안에 펼치는 내용(폼 등) |
| asChild | boolean | — | 링크 단계: <Step asChild status="done"><Link href="…">이름</Link></Step>. 자식 링크 요소가 표지 · 이름을 감싼다. 끝난 단계(와 오류 단계)에만 둔다. 지금 · 다음 단계로 건너뛰어 가지 않는다 |
| number | number | — | 표지 숫자. 없으면 Stepper 가 순서대로 매긴다 |
| lang | "ko" | "en" | "ja" | — | Stepper 가 넘긴다. 따로 쓸 때만 준다 |
| labels | Partial<StepperLabels> | — | |
| children필수 | ReactNode | — | 이름 |
StepperCompact
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| current필수 | number | — | 1부터 |
| total필수 | number | — | |
| name필수 | ReactNode | — | 지금 단계 이름 |
| statuses | StepStatus[] | — | 각 칸의 상태. 없으면 current 앞은 done, 뒤는 upcoming |
| error | ReactNode | — | 지금 단계가 오류일 때 한 문장 |
| next | ReactNode | — | 다음 단계 이름. 글자면 labels.next 로 감싼다('다음: 가져오기') |
| label | string | — | nav 의 접근성 이름. 없으면 labels.label |
| lang | "ko" | "en" | "ja" | — | |
| labels | Partial<StepperLabels> | — | |
| className | string | — |