Docs

docs/system/components/page-header.md

Page Header

packages/ui/src/page-header.tsx

본문의 맨 위 한 줄이다. 헤더와 좌측 메뉴를 뺀 자리의 맨 위에 서며, 지금 보고 있는 화면이 무엇이고 그 화면이 어디에 있는지를 말한다. 탭과 동작 버튼의 자리도 함께 갖는다.

역할과 경계

  • 관리자 웹 화면의 머리다. 좌측 메뉴에서 고른 화면이 자기 이름과 경로를 이 자리에서 말한다. 최소 폭은 1024px이며 그보다 좁은 구간을 설계하지 않는다 — quality.md가 「관리자 웹은 lg까지만 대응한다」로 정해 둔 범위다.
  • PageHeader는 경로와 제목, 동작 버튼의 자리, 즐겨찾기 별과 설명 아이콘의 자리, 그리고 탭 줄을 놓는 자리를 소유한다. 그 안에 무엇이 서는지는 소유하지 않는다 — 동작 버튼은 ReactNode로 받고, 탭은 값과 이름만 받는다.
  • 상세 화면이 제목 아래 함께 보여 주는 값은 갖지 않는다. 소유자, 생성일, 식별자가 그런 값이다. 이 머리는 각 메뉴의 첫 화면이 공통으로 쓰는 자리이고, 그 값들은 화면마다 다른 대상의 속성이다.
  • 탭 줄 자체는 tabs.md가 소유한다. 이 머리는 그 줄을 어디에 놓는지와 줄 아래 선만 갖는다. Tabs가 그 선을 긋지 않기로 정해 두었고, 머리의 아래 경계선이 그 선이 된다.
  • 탭을 쓸 때는 쓰는 쪽이 Tabs로 이 머리와 본문을 함께 감싼다. 탭 줄과 그 탭이 여는 칸은 서로를 가리켜야 하는데 칸은 이 머리의 바깥에 있다. 같은 규칙을 tabs.md의 「역할과 경계」가 소유한다.
  • 나란히 선 동작 버튼 사이 간격은 interaction.md의 「나란히 선 버튼 사이」가 소유한다. 이 머리는 그 값을 자기 자리에 적용할 뿐이다.
  • 구성 요소를 부르는 이름은 vocabulary.md를 따른다. 경로는 업계에서 굳은 Breadcrumb 대신 Path로 부른다 — 코드의 property 이름이 path이고, 한 컴포넌트 안에서 두 이름을 섞지 않는다.

App Header와의 경계

둘을 한 컴포넌트에 담지 않는다. 둘 다 「화면의 위에 서서 그 화면의 이름을 말하는 줄」이지만 서는 자리와 높이의 규칙이 다르다.

Page Header App Header
서는 자리 관리자 웹 본문의 머리. 헤더와 좌측 메뉴를 뺀 자리의 맨 위 모바일 화면의 최상단 한 줄. 그 위에 아무것도 없다
높이 내용이 정한다. 탭 줄과 설명 아이콘, 동작 버튼이 화면마다 있고 없다 56px 한 값으로 고정한다
제목 24px. 화면의 이름이자 그 화면의 <h1> 16px. 한 줄에서 자른다
좌우 자리 오른쪽 하나뿐이고 동작 버튼이 선다 좌우 둘이고 성격이 같은 아이콘 자리다
경로 갖는다 갖지 않는다. 뒤로 가는 길이 그 역할을 한다
스크롤 자리에 머문다. 아래 선은 모양이 정한다 붙을 수 있고 본문이 아래로 들어가면 선이 나타난다

높이가 둘을 가르는 자리다. App Header가 높이를 내용에 맡기지 않는 것은 설명 줄이 있는 화면과 없는 화면을 오갈 때 그 줄이 늘었다 줄면 아래 본문이 위아래로 밀리기 때문이다. Page Header는 반대로 탭 줄과 동작 버튼이 화면마다 달라 한 값으로 묶을 수 없고, 화면을 오가도 본문이 밀리지 않는 자리에 있다.

Anatomy

  1. Root: 머리 전체를 감싸며 모양(variant)과 좌우 여백, 아래 경계선을 소유한다.
  2. Path: 첫 화면부터 지금 화면까지의 경로다. 제목보다 먼저 읽히고 제목보다 작고 옅다. 마지막 항목이 지금 보고 있는 화면이다.
  3. Title: 화면의 이름이며 <h1>이다. 한 화면에 하나다.
  4. Actions (Optional): 제목 오른쪽에 서는 동작 버튼의 자리다. 경로와 제목 두 줄 전체와 나란히 서고 그 높이의 가운데에 놓인다.
  5. Tabs (Optional): 화면 안을 가르는 탭 줄이다. 머리의 아래쪽에 서고 밑줄이 아래 경계선과 겹친다.

별과 설명 아이콘은 번호를 갖지 않는다. 별은 Title에 딸린 표시이고 설명 아이콘은 Path에 딸린 표시이므로, 저마다 그 요소의 자리 안에 선다.

Properties

  • path: 필수다. 첫 화면부터 지금 화면까지의 경로이며 마지막 항목이 지금 보고 있는 화면이다. 어느 항목도 링크가 아니다 — 까닭은 아래 Guidelines의 「경로는 링크가 아니다」가 갖는다.
  • title: 필수다. 화면의 이름이며 <h1>으로 선다.
  • titleId: 제목에 걸 id다. 표처럼 이름이 필요한 요소가 aria-labelledby로 이 제목을 가리킬 때 쓴다. 넘기지 않으면 id가 붙지 않는다. 쓰는 법은 아래 Guidelines의 「제목을 다른 요소의 이름으로 쓰기」가 갖는다.
  • variant (Style): surface | ghost, 기본값 surface. surface는 흰 바탕을 깔고 아래를 선으로 끊는다. ghost는 바탕과 선을 모두 걷는다. 고르는 기준은 아래 Guidelines의 「모양 고르기」가 갖는다.
    • ghost라는 값 이름이 Button의 ghost와 뜻이 겹친다. 저쪽은 배경이 없는 버튼이고 이쪽은 면과 선이 없는 머리다. 이름을 고치지 않은 것은 채움 스타일의 값 이름이 저장소에서 셋으로 갈려 있어 한 컴포넌트만 먼저 고치면 갈림이 넷이 되기 때문이다. 미룬 결정은 docs/process/open-questions.md의 「채움 스타일 값 이름」이 갖는다.
  • tabs: { value, label }[]. 넘기지 않으면 탭 줄이 서지 않는다. 넘기면 머리의 아래 여백이 사라진다 — 탭의 밑줄이 아래 경계선 자리에 겹쳐 앉아야 하기 때문이다.
  • actions: ReactNode. 넘기지 않으면 그 자리를 그리지 않고 제목이 그 자리까지 쓴다. 버튼을 감싸지 않고 Fragment로 그대로 넘긴다 — 사이 간격은 이 자리가 갖는다.
  • favorite: false | true. 넘기지 않으면 별이 서지 않는다. false를 넘기는 것과 넘기지 않는 것이 다르다 — false는 「담겨 있지 않다」이고 넘기지 않는 것은 「담는 자리가 아니다」다.
  • onFavoriteChange: 별을 눌렀을 때 다음 값으로 부른다.
  • description: ReactNode. 넘기지 않으면 경로 끝에 설명 아이콘이 서지 않는다. 넘긴 글은 아직 어디에도 그려지지 않는다 — 아래 「현재 정의하지 않은 항목」이 그것을 갖는다.
  • State: 없다. 이 머리는 자기 상태를 갖지 않는다. 별의 켜짐과 꺼짐은 favorite이 쥐는 값이고 켜진 탭은 Tabs가 쥔다.

Guidelines

모양 고르기

  • 본문이 머리 바로 아래에서 통째로 스크롤되는 화면에는 surface를 쓴다. 아래 선이 스크롤되는 자리와 고정된 자리를 가른다.
  • 본문이 카드 몇 장으로 나뉜 화면에는 ghost를 쓴다. 끊을 자리가 이미 카드의 경계로 있어서 머리의 선까지 더하면 가로선이 두 겹으로 겹친다.
  • 모양을 고르는 기준은 머리가 아니라 그 아래 본문의 모양이다. 머리만 보고 고르면 같은 화면에서 선이 두 번 그어진다.
  • ghost를 쓰는 화면은 본문의 위쪽 여백을 좁게 둔다. 머리가 면을 갖지 않으므로 머리의 아래 여백과 본문의 위 여백이 그대로 이어져 한 덩이로 벌어진다.

경로는 링크가 아니다

  • 마지막 항목은 누를 곳이 아니다. 지금 보고 있는 화면이므로 눌러서 갈 자리가 없다. aria-current="page"로 그 사실을 알린다.
  • 앞선 항목들도 링크로 세우지 않는다. 갈 주소가 아직 없다. 링크로 세우면 눌러도 아무 일이 없는 자리가 눌리는 것처럼 보이고, 포인터와 색이 그 약속을 먼저 한다.
  • 앞 항목을 열 때는 그 항목이 가리키는 화면이 실제로 있는지를 먼저 본다. 좌측 메뉴의 묶음 이름은 화면이 아니라 묶음이므로 열 자리가 없는 경우가 있다. 열기로 하면 링크가 되는 항목과 되지 않는 항목이 한 줄에 섞이는 것을 어떻게 알릴지 함께 정한다.
  • 경로의 이름은 좌측 메뉴의 묶음 이름을 그대로 쓴다. 헤더에서 들어오는 화면처럼 좌측 메뉴와 맞물리지 않는 자리는 그 화면이 속한 묶음을 적는다.
  • 마지막 항목과 title을 같게 둔다. 다르면 경로가 가리키는 자리와 제목이 말하는 자리가 갈린다.

제목 줄의 네 갈래

저장소에서 제목 줄을 가진 화면은 28곳이고, 그 가운데 26곳의 <h1>이 text-2xl font-semibold text-oe-foreground-primary를 글자 그대로 들고 있다. 제목의 단계는 이미 한 값으로 정해져 있다. 이 머리가 새로 정한 값이 아니라 그 값을 그대로 들고 행간과 자간만 더 적는다.

갈리는 것은 제목이 아니라 그 줄의 구조이며 네 갈래다.

갈래 곳 이 API가 받는가
제목만 4 받는다. path에 한 항목만 넘기면 경로 줄이 그 이름 하나로 선다
제목 + 아래 설명 5 받지 못한다. description은 경로 끝의 아이콘으로만 서고 제목 아래에 줄로 서지 않는다
제목 + 오른쪽 동작 5 받는다. actions가 그 자리다
경로 + 제목(+ 탭·동작·별·설명) 3 이 컴포넌트가 그 갈래다
  • 앞의 세 갈래를 이 컴포넌트로 갈아타는 일은 하지 않았다. 경로가 없는 화면에 경로를 만들어 붙이는 일이 되므로 화면마다 그 화면이 어느 묶음에 속하는지를 먼저 정해야 한다.
  • 둘째 갈래를 받으려면 제목 아래 설명 줄을 Property로 열어야 한다. 지금 description이 그 자리가 아니라는 것을 먼저 읽어야 하므로, 열 때는 이름을 가른다.

제목을 다른 요소의 이름으로 쓰기

  • 표처럼 이름이 필요한 요소가 이 머리의 제목을 가리킬 때 titleId로 id를 준다. table.md의 「표에 이름 붙이기」가 그 기본 길을 aria-labelledby로 정해 두었다.
  • 화면 코드가 <h1>에 직접 id를 적는 길을 두지 않았다. 화면마다 손으로 적으면 같은 id가 두 번 서는 날이 온다. 값은 화면이 정하되 그 값을 머리에 넘긴다.
  • 값은 화면의 상수로 한 자리에 둔다. 제목을 그리는 쪽과 그 이름을 가리키는 쪽이 서로를 import 하지 않으므로, 둘이 함께 읽는 자리가 그 값을 갖는다.

즐겨찾기 별 두기

  • 별은 제목 옆에 붙는다. 오른쪽 동작 버튼과 달리 이 화면이 다루는 대상을 바꾸는 것이 아니라 화면 자체를 각자 담아 두는 표시다.
  • 이름은 켜짐과 꺼짐에서 같은 것을 쓴다. 지금 담겨 있는지는 aria-pressed가 이미 말하므로, 이름까지 바꾸면 상태와 누르면 일어날 일이 뒤섞인다.
  • 별은 저장을 거치지 않고 누른 즉시 반영한다. 담아 두는 표시는 고르는 값이 아니라 조작이다.

Specification

값은 page-header.tsx가 소유한다.

자리와 여백

  • 좌우 24px, 위 16px. 좌우는 관리자 웹 본문의 여백과 같은 값이다 — 머리와 본문의 시작점이 어긋나면 제목과 그 아래 내용이 다른 줄에서 시작한 것으로 보인다.
    • oe의 여백 토큰은 16px과 40px 둘뿐이라 이 값을 담은 것이 없다. 머리 혼자 쓰는 값이 아니라 관리자 웹 본문이 쓰는 값이므로, 토큰이 생기는 자리도 머리가 아니라 그 레이아웃이다.
  • 아래 여백은 탭이 있으면 0, 없으면 20px이다. 탭이 있을 때 0인 것이 규칙이다 — 탭의 밑줄이 아래 경계선 자리에 겹쳐 앉아야 하고, 여백이 남으면 밑줄이 선에서 그만큼 떠서 가로선이 두 줄로 보인다.
  • 높이를 고정하지 않는다. 설명 아이콘과 탭 줄, 동작 버튼이 화면마다 있고 없으므로 높이는 내용이 정한다.
  • 본문이 스크롤되어도 이 자리는 줄어들지 않는다.

경로

  • 글자 12px, 색은 oe-foreground-tertiary. 마지막 항목만 oe-foreground-secondary로 한 단계 진하다 — 지금 보고 있는 화면이라 경로 안에서 먼저 읽혀야 한다.
  • 항목 사이 4px. 꺾쇠는 14px이고 색은 oe-foreground-subtle로 경로 글자보다 한 단계 옅다. 구분 표시이고 읽을 글자가 아니므로 낭독기에 읽히지 않는다.
  • 꺾쇠와 그 뒤 글자가 한 항목으로 묶여 함께 줄을 넘는다. 묶지 않으면 꺾쇠만 줄 끝에 남는다.
  • aria-label="현재 위치"를 가진 <nav>에 <ol>로 선다. 마지막 항목만 aria-current="page"를 갖는다.

제목

  • 24px 글자가 32px 줄에 서고 자간을 한 단계 좁힌다. font-semibold에 색은 oe-foreground-primary다.
  • 경로 줄과 제목 줄 사이 6px.
  • 자리가 모자랄 때 줄어드는 것은 제목이다. 동작 버튼의 자리는 줄어들지 않는다.

별과 설명 아이콘

  • 별은 제목과의 사이 2px에 선다. 나란히 선 버튼 사이의 6px과 갈리는 것은 별이 버튼 묶음이 아니라 제목에 딸린 표시이기 때문이다. Toggle Button의 Ghost를 쓰고 켜지면 아이콘이 Fill로 바뀐다.
  • 설명 아이콘은 경로의 마지막 항목 바로 뒤에 선다. 지금 화면의 이름이 나오는 자리이고, 설명은 그 이름을 보충하는 글이기 때문이다.
  • 설명 아이콘의 글자색이 Button이 주는 값을 덮어쓴다. Ghost neutral이 주는 neutral-800 대신 경로 글자와 같은 oe-foreground-tertiary를 얹었다. 이 줄의 어느 것도 먼저 읽혀야 하는 것이 아니기 때문이며, 가리키면 Button이 가진 색으로 진해진다. 같은 성격의 아이콘 버튼이 몇 군데 더 나오면 Button에 그 단계를 둘지 판단한다 — 미룬 결정은 docs/process/open-questions.md가 갖는다.
  • 아이콘 버튼은 28px이고 경로 글자 줄은 16px이다. 넘치는 만큼을 위아래로 덜어 내어 줄 높이를 글자에 맞춘다 — 그러지 않으면 이 줄만 12px 높아져 제목이 함께 밀린다.

동작 버튼

  • 경로와 제목 두 줄 전체와 나란히 서고 그 높이의 가운데에 놓인다. 제목 줄에만 맞추면 버튼 위로 경로 줄만큼이 빈자리로 남는다.
  • 버튼 사이 6px. 값과 까닭은 interaction.md의 「나란히 선 버튼 사이」가 소유한다.
  • 버튼의 크기 단계는 쓰는 화면이 정한다. 저장소에 쓰인 두 자리는 모두 Small이다.

모양

  • surface: oe-background-primary 면에 아래 1px oe-border-secondary.
  • ghost: 면과 선을 모두 두지 않는다.
  • 선을 켜고 끄는 것이 아니라 class 자체를 두고 뺀다. App Header가 선의 색만 바꾸는 것과 갈리는 것은, 그쪽은 한 화면 안에서 스크롤에 따라 바뀌어 1px이 생기고 사라지면 본문이 움직이기 때문이고, 이쪽은 화면마다 한 번 정해져 바뀌지 않기 때문이다.

탭 줄

  • 제목 줄 아래 16px에 선다. 모양은 Tabs의 underline이고 줄 아래 선은 머리의 아래 경계선이다.
  • ghost에서도 탭을 둘 수 있으나 그때는 줄 아래 선이 없다. 밑줄만 공중에 뜨므로 탭을 쓰는 머리는 surface로 둔다.

현재 정의하지 않은 항목

  • description의 글이 어디에도 그려지지 않는다. 아이콘만 세우고 누르면 펼쳐지는 자리를 붙이지 않았다. 저장소에 팝오버 컴포넌트가 없어서다 — 글을 띄워 보이는 자산이 아직 없다. 붙일 때는 펼쳐지는 자리가 Tooltip인지 Popover인지, 포인터로 열리는지 눌러서 열리는지, 키보드로 닫는 길을 함께 정해야 한다. 남은 일은 docs/process/open-questions.md의 「Page Header의 설명이 아직 그려지지 않는다」가 갖는다.
  • 세 단계 이상의 경로. 저장소에 쓰인 경로는 모두 두 단계다. 세 단계 이상에서 줄이 넘칠 때 접을지 가운데를 줄일지, 접는다면 무엇을 남길지를 정하지 않았다. 지금은 넘친 항목이 다음 줄로 내려간다.
  • 앱 화면에서 쓸 수 있는지. 관리자 웹 화면에서만 쓰고 있으며 앱 화면의 기준을 따로 보지 않았다. 앱은 모바일 뷰가 기준이라 좌우 24px과 제목 24px이 그대로 맞는지, 최상단의 App Header와 이 머리가 한 화면에 함께 설 자리가 있는지를 먼저 정해야 한다.
  • 제목 아래 설명 줄. 위 「제목 줄의 네 갈래」의 둘째 갈래를 받지 못한다. 열 때는 description과 이름을 가른다.
  • 스크롤에 따라 붙는 머리. 이 머리는 자리에 머문다. 본문이 길어질 때 제목과 탭 줄이 위에 붙어 남을지는 정하지 않았다 — 붙이기로 하면 그때 선이 생기고 사라지는 문제가 App Header와 같은 꼴로 돌아온다.
  • 동작 버튼이 많을 때. 지금은 버튼이 늘어나면 제목이 먼저 줄어든다. 몇 개를 넘으면 더보기로 접을지, 접는다면 어느 버튼을 남길지를 정하지 않았다.