WorkflowBar

목적

WorkflowBar는 저장, 검증, 승인, 발행처럼 순서가 있는 작업에서 현재 상태와 다음 행동 하나를 함께 보여준다. 사용자가 여러 가능한 행동을 다시 해석하지 않고 학습이나 운영의 한 고리를 끝낸 뒤 다음 단계로 이어지게 한다.

선택 기준

• 명확한 상태 전이와 다음 행동이 있는 workflow에 사용한다.
• 서로 독립적인 여러 행동을 모아 놓는 일반 toolbar로 사용하지 않는다.
• 화면의 단순 저장 버튼 하나만 필요하면 PageHeader actions 또는 form action 영역을 사용한다.
• 자동으로 진행되어 사용자의 결정이 필요 없는 background 작업에는 상태 summary를 우선한다.

구조

1. title: 현재 workflow 단계 또는 판단 대상
2. status: 선택적 StatusPill
3. description: 현재 상태의 의미와 다음 단계 조건
4. secondaryActions: 되돌리기, 미리보기 등 낮은 우선순위 행동
5. primaryAction: 지금 가장 적절한 다음 행동 하나

변형과 크기

• statusTone: success, warning, destructive, info, neutral, primary
• 별도 size prop은 없다.
• 작은 화면에서는 행동이 세로로 배치되고 주 행동이 시각적으로 먼저 읽히는 순서를 유지한다.
• 큰 화면에서는 상태 설명과 행동이 양쪽으로 정렬된다.

상태와 동작

• primaryAction.pending 동안 주 버튼이 비활성화된다.
• pendingLabel이 있으면 처리 중 레이블로 바뀐다. 없으면 기존 label을 유지한다.
• primaryAction.disabled일 때 description 또는 인접 오류 목록에서 이유와 해결 조건을 설명한다.
• 상태 전이는 소비 제품이 소유한다. WorkflowBar는 backend 상태를 추론하지 않는다.
• 실패 후 가능한 다음 행동이 재시도라면 primaryAction을 재시도로 바꾸고, 원인 확인은 secondary action으로 제공할 수 있다.
• 같은 primary action을 페이지 다른 위치에 중복하지 않는다.

콘텐츠

• title은 발행 준비, 검증 결과처럼 현재 단계의 목적을 말한다.
• description은 완료된 것, 남은 조건, 다음 행동의 결과를 짧게 설명한다.
• primary label은 실행이 아니라 검증 실행, 운영 기준본 발행처럼 결과를 말한다.
• pending label은 같은 동사를 유지해 검증 중…, 발행 중…처럼 쓴다.
• status는 오류보다 검증 실패, 발행 대기처럼 대상과 상태를 함께 쓴다.

접근성

• section에 ariaLabel을 제공해 workflow 상태 영역임을 설명한다. 기본 영어 값을 제품 맥락에 맞는 한국어로 바꾼다.
• 상태는 StatusPill의 텍스트로 전달한다.
• pending 상태가 중요한 비동기 작업이면 별도 status/live region에서 진행 사실과 결과를 알린다. 버튼 레이블 변경만 유일한 알림으로 두지 않는다.
• secondary action의 키보드 순서는 시각적 순서와 일치해야 한다.
• disabled 이유를 tooltip에만 숨기지 않는다.

좁은 화면과 긴 콘텐츠

• 작은 화면에서 secondaryActions와 primary action이 세로로 분리된다.
• secondary action이 많으면 menu로 모으고 다음 단계 하나만 명확히 유지한다.
• 긴 description은 조건을 여러 문장으로 나열하지 말고 가장 가까운 blocker를 먼저 설명한다.
• 주 행동은 최소 폭을 가지지만 지나치게 긴 레이블은 workflow 용어를 다시 정리한다.

공개 API

WorkflowBarProps

WorkflowAction

예제

import { Button, WorkflowBar } from '@classum/dot-design-system/ui';

type PublishWorkflowProps = {
  pending: boolean;
  runValidation: () => void;
};

export function PublishWorkflow({ pending, runValidation }: PublishWorkflowProps) {
  return (
    <WorkflowBar
      ariaLabel="커리큘럼 발행 상태"
      title="발행 전 검증"
      status="검증 필요"
      statusTone="warning"
      description="질문 순서와 비어 있는 기준 답안을 확인한 뒤 발행할 수 있어요."
      secondaryActions={<Button variant="ghost">미리보기</Button>}
      primaryAction={{
        label: '검증 실행',
        pendingLabel: '검증 중…',
        pending,
        onClick: runValidation,
      }}
    />
  );
}

피해야 할 사용

• 관련 없는 버튼을 모두 모은 toolbar로 사용
• primaryAction을 두 개 이상 흉내 내기 위해 secondaryActions에 강한 버튼 추가
• disabled 이유를 설명하지 않음
• backend 상태와 다른 낙관적 status를 확정적으로 표시
• pending 중에도 중복 실행을 허용
• 같은 행동을 PageHeader와 WorkflowBar에 반복

관련 항목

• StatusPill
• 다단계 작업
• 비동기 작업
• 행동과 레이블