PageHeader

목적

PageHeader는 현재 작업 대상, 상위 맥락, 상태와 페이지의 주 행동을 한곳에 모은다. 사용자가 화면을 연 첫 순간에 어디에 있는지, 무엇을 할 수 있는지, 다음으로 어디로 갈지를 이해하게 한다.

선택 기준

• 독립적인 route 또는 주요 작업 화면의 시작에 사용한다.
• 작은 카드나 dialog 내부 제목에는 사용하지 않는다.
• 한 페이지에 하나만 두고 title은 해당 문서의 h1 역할을 한다.
• 목록에서 상세로 이동한 화면은 backAction을 사용해 이전 작업 맥락을 연결한다.

구조

1. icon: 드문 제품 또는 대상 식별 요소
2. backAction 또는 eyebrow: 상위 맥락. 둘을 함께 전달하면 backAction이 우선한다.
3. title: 현재 페이지의 h1
4. badge: title과 직접 관련된 짧은 상태
5. description: 이 화면의 목적
6. meta: 최근 저장, 버전, 소유자 같은 보조 맥락
7. actions: 주 행동 하나와 제한된 보조 행동

변형과 크기

• 별도 variant와 size prop은 없다.
• 좁은 화면에서는 정보와 actions가 세로로 쌓이고, 중간 이상 화면에서는 양쪽으로 정렬된다.
• title은 page-title 계층으로 고정된다.
• className과 표준 header 속성으로 배치를 확장할 수 있다.

상태와 동작

• backAction.disabled는 이동할 수 없는 동안 back button을 비활성화한다. 이유가 필요하면 인접 피드백을 제공한다.
• 비동기 주 행동은 actions에 전달한 Button이 pending 상태를 소유한다.
• data-page-title과 tabIndex={-1}이 있어 route 전환 후 제품이 h1에 programmatic focus를 보낼 수 있다.
• 페이지 상태가 바뀌어도 title 위치를 유지해 공간 기억을 보존한다.
• actions는 권한에 따라 숨기기만 하지 말고, 사용자가 기대할 행동이면 제한 이유와 요청 경로를 검토한다.

콘텐츠

• title은 메뉴 경로가 아니라 현재 대상 또는 작업을 말한다.
• description은 기능 목록보다 사용자가 이 화면에서 끝낼 일을 설명한다.
• eyebrow는 짧은 분류나 상위 객체 이름에 사용한다.
• meta는 핵심 상태를 대신하지 않는다. 중요한 실패나 미저장 상태는 텍스트와 구조로 더 명확히 표시한다.
• actions의 레이블은 결과를 말하고 가장 강한 Button은 하나만 둔다.

접근성

• semantic header와 하나의 h1을 제공한다.
• route 전환 후 title에 초점을 보내면 화면 변경을 키보드와 스크린 리더 사용자에게 알릴 수 있다.
• icon은 장식이면 aria-hidden으로 전달한다.
• badge와 meta는 색상 없이도 상태를 이해할 수 있는 텍스트를 포함한다.
• back button은 backAction.label을 눈에 보이게 표시한다.

좁은 화면과 긴 콘텐츠

• actions는 줄바꿈된다. 중요한 주 행동이 보조 행동 뒤로 밀리지 않게 전달 순서를 정한다.
• 긴 title은 줄바꿈하되 고유 식별자를 앞부분에 둔다.
• description은 최대 읽기 폭 안에서 줄바꿈된다.
• 좁은 화면에서 meta를 무조건 숨기지 말고 작업 판단에 필수인지 먼저 확인한다.
• action이 많으면 보조 행동을 menu로 모으고 주 행동만 유지한다.

공개 API

PageHeaderProps는 title을 제외한 React.HTMLAttributes<HTMLDivElement> 성격의 header 속성을 받는다.

예제

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

export function CurriculumHeader({ goBack }: { goBack: () => void }) {
  return (
    <PageHeader
      title="신규 입사자 온보딩"
      description="학습 순서와 질문을 검토하고 운영 기준본으로 발행해요."
      badge={<StatusPill tone="warning">검증 필요</StatusPill>}
      meta={<span>마지막 저장 3분 전</span>}
      backAction={{ label: '커리큘럼 목록', onClick: goBack }}
      actions={
        <>
          <Button variant="outline">미리보기</Button>
          <Button>초안 저장</Button>
        </>
      }
    />
  );
}

피해야 할 사용

• 한 route에 PageHeader 여러 개 배치
• title에 breadcrumb 전체 경로를 반복
• description에 기능과 정책을 장문으로 나열
• 동일한 강조의 주 행동을 여러 개 제공
• backAction과 eyebrow가 모두 보일 것이라고 가정
• 일반 페이지마다 브랜드 icon을 장식적으로 반복

관련 항목

• PageScaffold
• PageToolbar
• 목록에서 상세로
• 행동과 레이블