Docs

docs/system/components/side-navigation.md

Side Navigation

packages/ui/src/side-navigation.tsx

관리자 웹 왼쪽에서 화면 높이를 다 쓰는 메뉴다. 지금 어느 화면에 있는지 알리고 다른 화면으로 옮기며, 검색과 즐겨찾기, 묶음·항목·하위 항목 3단계를 갖고 접을 수 있다.

역할과 경계

  • 관리자 웹의 좌측 메뉴다. 최소 폭은 1024px이며 그보다 좁은 구간을 설계하지 않는다 — quality.md가 「관리자 웹은 lg까지만 대응한다」로 정해 둔 범위다. 태블릿과 모바일 구간이 없으므로 좁은 폭에서 서랍으로 갈아타는 길도 갖지 않는다.
  • SideNavigation은 레일의 자리와 폭, 단계마다의 줄 높이와 여백, 검색 입력, 즐겨찾기 묶음, 접고 펴는 동작을 소유한다. 메뉴의 내용은 소유하지 않는다 — 어떤 묶음에 어떤 항목이 쌓이는지는 그 시스템이 정하므로 groups로 받는다.
  • 어느 줄을 고른 상태인지도 소유하지 않는다. 어느 화면에 있는지는 라우팅이 소유하므로 value를 넘긴 쪽이 다음 값을 정한다. 눌러도 onValueChange만 부르고 표시는 그대로다.
  • 레일 오른쪽의 본문 열은 SideNavigationInset이 갖고, 접힘 상태와 색은 SideNavigationProvider가 내려 준다. 셋을 함께 쓴다. 하나만 세우면 색도 접힘 상태도 없이 선다.
  • 관리자 웹의 맨 위 한 줄은 Admin Header가 담당하며 아직 초안이다. 그 헤더는 이 레일의 오른쪽에서 시작한다 — 가로 전체에 두면 흰 헤더와 짙은 레일이 맞붙어 한 화면이 위아래로 잘려 보인다.
  • 검색 입력은 공용 input.md를 그대로 쓴다. 이 컴포넌트가 정하는 것은 그 입력이 서는 자리와 레일 위에서 쓰는 색뿐이다.
  • 하위 항목을 여는 화살표의 방향 규칙은 interaction.md의 「여닫는 화살표」가 소유한다.
  • 본문의 머리는 page-header.md가 담당한다. 이 레일이 가리키는 화면의 이름과 경로는 그쪽이 말한다.

Bottom Navigation과의 경계

둘 다 「지금 어느 화면에 있는지 알리고 다른 화면으로 옮기는」 자리이지만 합치지 않는다. 다섯 가지가 다르다.

Bottom Navigation Side Navigation
쓰는 화면 모바일 관리자 웹(PC)
자리와 방향 화면 맨 아래 가로 한 줄 화면 왼쪽 세로 한 열
단계 한 층 세 층(묶음 · 항목 · 하위 항목)
항목 수 셋부터 다섯까지, 넘기면 오류 상한이 없다
갖지 않는 것 검색 · 즐겨찾기 · 접기 —

항목 수에 상한을 두지 않는 것이 가장 큰 차이다. bottom-navigation.md는 「375px 화면에서 다섯이면 항목마다 75px」이라 여섯부터 라벨이 들어갈 폭이 없어 상한을 두고 넘기면 오류를 낸다. 이쪽은 항목이 폭을 나눠 갖지 않고 세로로 쌓이므로 수가 늘어도 줄의 모양이 달라지지 않는다. 넘치는 것은 목록이 자기 안에서 스크롤한다. 지금 쓰는 메뉴만 묶음 여덟에 항목 서른둘이고, 거기에 상한을 두면 메뉴가 하나 늘 때마다 컴포넌트를 고쳐야 한다.

나머지 넷은 자리에서 따라온다. 모바일의 한 줄은 제품 전체를 가르는 최상위 화면으로만 옮기므로 단계가 하나고 검색할 것이 없다. 관리자 웹의 세로 열은 서른 넘는 화면을 담으므로 단계와 검색이 필요하고, 자주 가는 화면을 위로 올려 두는 즐겨찾기와 본문을 넓히는 접기가 함께 선다.

한 제품에서 둘을 함께 쓰는 화면은 없다. 모바일 화면에 이 레일을 세우지 않고, 관리자 웹에 아래 줄을 두지 않는다.

Anatomy

  1. Provider: 레일과 본문 열을 가로로 세우고, 접힘 상태와 아홉 색을 내려 준다. 눈에 보이는 면을 갖지 않는다.
  2. Rail: 레일 하나다. 화면 왼쪽에 붙어 높이를 다 쓰고 폭 240px을 갖는다.
  3. Top band: 맨 위 56px의 빈 띠다. Toggle이 그 자리를 쓰므로 비워 둔다.
  4. Search: 메뉴를 찾는 입력 하나다. 공용 Input의 Filled를 쓴다.
  5. Group: 1depth 묶음이다. Group label과 그 아래 Item들을 갖는다. 접히지 않는다.
  6. Group label: 묶음의 이름이다. 페이지가 아니므로 누를 수 없다.
  7. Item: 2depth 줄이다. 아이콘과 이름을 갖고, 하위 목록이 있으면 누르는 줄이 아니라 여닫는 줄이 된다.
  8. Sub item: 3depth 줄이다. 아이콘을 갖지 않는다.
  9. Favorites: 선택 요소다. 사용자가 담은 화면들이며 정해진 묶음보다 위에 선다. 비어 있으면 그 묶음이 서지 않는다.
  10. Edge toggle: 레일 오른쪽 모서리의 가는 선이다. 가리키면 드러나고 누르면 여닫는다.
  11. Toggle: 레일을 여닫는 button이다. 화면 왼쪽 맨 위 한 자리를 지키며 레일 바깥에 선다.
  12. Inset: 레일 오른쪽의 본문 열이다. 헤더와 화면의 본문이 이 안에서 위아래로 나뉜다.

Properties

  • groups: 필수다. 1depth 묶음의 배열이며 수에 상한이 없다.
  • groups[].title: 묶음의 이름이다.
  • groups[].items: 그 묶음의 2depth 줄들이다.
  • groups[].items[].title: 줄의 이름이다.
  • groups[].items[].icon: 줄 앞에 서는 아이콘이다. ReactNode로 받고 크기는 줄이 정한다.
  • groups[].items[].items: 3depth 줄들이다. 넘기면 그 줄은 고를 수 없고 하위 목록을 여닫는 줄이 된다.
  • favorites: 즐겨찾기에 담은 화면들이다. 넘기지 않거나 비면 그 묶음이 서지 않는다.
  • showItemIcons: false | true, 기본값 false. 즐겨찾기와 2depth 줄 앞에 아이콘을 그린다. 3depth는 어느 쪽이든 그리지 않는다.
  • value: 지금 고른 줄의 값이다. 넘기지 않으면 고른 줄이 없다. 값의 꼴은 아래 「고른 줄의 값」이 적는다.
  • onValueChange: 줄을 눌렀을 때 그 줄의 값으로 부른다.
  • searchValue·onSearchValueChange: 검색 입력에 적힌 글이다. 넘기지 않으면 컴포넌트가 들고 있는다.
  • SideNavigationProvider.palette: 레일의 아홉 색이다. 주지 않은 칸은 oe 토큰으로 채운다. 아래 「색을 값으로 받는다」가 아홉이 무엇인지와 까닭을 적는다.
  • SideNavigationProvider.defaultOpen: 처음에 펼쳐져 있을지다. 기본은 펼친 쪽이다.
  • SideNavigationProvider.open·onOpenChange: 접힘 상태를 밖에서 쥘 때 쓴다.
  • SideNavigationToggle.tooltip: button을 Tooltip으로 감싸는 자리다. 넘기지 않으면 이름을 aria-label만 갖는다. 까닭은 아래 「Tooltip을 쓰는 쪽에서 받는다」가 적는다.
  • State: Selected, Unselected, Hover, Pressed, Focus, Expanded, Collapsed

Guidelines

메뉴 내용을 바깥에서 받기

  • 묶음과 항목의 이름은 그 시스템이 정한다. 컴포넌트에 메뉴를 담지 않는다.
  • 메뉴의 내용은 제품의 자료이므로 제품 저장소에 둔다. 지금 쓰는 메뉴는 apps/sandbox/src/components/candidates/admin-menu.ts에 있고 packages/ui로 올리지 않았다.
  • 1depth는 페이지가 아니라 묶음이다. 누를 수 있는 1depth가 필요하면 하위를 두지 않은 2depth 줄 하나로 세운다.
  • 하위 목록을 가진 2depth 줄은 여닫는 것이 전부다. 그 줄과 그 안의 3depth가 동시에 켜지면 어느 화면을 보고 있는지 둘로 갈린다.

고른 줄을 밖에서 쥐기

  • 어느 화면에 있는지는 라우팅이 소유한다. 눌린 것을 컴포넌트가 기억하게 두면 주소와 화면이 어긋난다.
  • 실제 경로가 붙기 전까지는 쓰는 쪽이 누른 것을 기억해 두고, 경로가 붙으면 주소에서 읽는 값으로 바꾼다.
  • 한 번에 한 줄만 고른다. 둘을 켜 두면 위치 표시가 아니라 여러 개를 고르는 도구로 읽힌다.

즐겨찾기 담기

  • 담는 것은 경로가 아니라 화면 하나이므로 이름은 경로의 마지막 항목을 쓴다.
  • 담긴 것이 어느 묶음에서 왔든 즐겨찾기 안에서는 한 층으로 나란히 선다.
  • 하나도 담지 않은 동안에는 묶음을 그리지 않는다. 이름만 남은 빈 묶음이 서면 담을 수 있다는 것이 아니라 비어 있다는 것만 전한다.

접기

  • 접고 펴는 자리는 셋이다 — 화면 왼쪽 맨 위의 Toggle, 레일 오른쪽 모서리의 Edge toggle, 그리고 Cmd/Ctrl + B. 셋 다 같은 상태를 바꾸고 같은 문구를 쓴다.
  • Toggle은 화면에 하나만 둔다. 레일 안과 헤더 안에 따로 두면 접을 때 하나가 사라지고 다른 하나가 생겨서, 유지되는 것이 아니라 새로 만들어지는 것처럼 보인다.
  • 레일이 서 있는지 아닌지가 화면에 그대로 드러나므로 Toggle은 눌림 상태를 따로 말하지 않는다. 그래서 toggle-button.md가 아니라 보통 button이다.

Tooltip을 쓰는 쪽에서 받는다

  • Toggle은 글자가 없는 아이콘 button이라 이름을 Tooltip과 접근 가능한 이름이 함께 갖는다.
  • 저장소에 공용 Tooltip이 아직 없다. 화면 후보의 Tooltip을 packages/ui가 가져오면 공용 컴포넌트가 화면 후보에 기대게 되므로, 감싸는 일을 쓰는 쪽에 넘기고 이름만 함께 준다.
  • 쓰는 쪽은 받은 이름을 그대로 Tooltip에 넣는다. Tooltip과 aria-label이 갈리면 낭독기로 듣는 사람과 보는 사람이 다른 말을 듣는다.
  • 공용 Tooltip이 생기면 이 Property를 걷고 컴포넌트가 직접 감싼다.

Specification

폭 240px

폭은 240px 한 값이다. 메뉴 이름 가운데 가장 긴 「업무관리 사용자별」이 2depth 줄의 좌우 여백 16px 안에서 91px을 남기므로 글자가 잘리지 않는다. 받은 코드의 256px에서 줄인 값이며, 줄인 16px은 본문 폭으로 간다.

폭을 Property로 열지 않는다. 관리자 웹의 본문은 최소 폭 1024px에서 레일을 뺀 자리를 쓰므로, 레일이 화면마다 다른 폭을 가지면 본문의 최소 폭도 화면마다 달라진다. 값은 --oe-side-navigation-width 변수 하나가 갖고 레일과 그 폭을 대신 차지하는 빈 자리가 그 하나를 함께 읽는다.

자리와 높이

  • 레일은 화면 왼쪽에 고정되어 뷰포트 높이를 다 쓴다. 본문이 길어져 바깥 상자가 늘어나도 레일은 제자리를 지킨다.
  • 레일이 본문을 밀어내는 폭은 레일 자신이 아니라 같은 폭의 빈 자리가 차지한다. 접으면 그 자리가 0으로 줄고 레일이 자기 폭만큼 화면 왼쪽으로 밀려난다. 둘 다 200ms ease-linear로 움직이며 두 값은 언제나 같게 맞춘다 — 어긋나면 본문이 레일보다 먼저 또는 나중에 자리를 옮긴다.
  • 맨 위 56px은 비워 둔다. Toggle이 그 자리를 쓰고, 관리자 웹의 헤더도 같은 56px이라 어느 쪽에서나 그 줄의 한가운데 선다.
  • 목록만 스크롤한다. 위쪽 빈 띠와 검색은 제자리에 남는다. 스크롤 막대는 감춘다 — 브라우저 기본 막대가 레일 옆에 회색 띠로 얹혀 세 스타일 모두에서 어긋났다.
  • 목록 맨 아래에 24px을 비운다. 묶음마다 갖는 2px만으로는 끝까지 내렸을 때 마지막 줄이 레일 밑변에 붙어, 목록이 거기서 끝난 것인지 잘린 것인지 읽히지 않는다.

단계마다의 줄

단계 높이 글자 좌우 여백
Group label (1depth) 32px 13px font-normal, 자간 0.01em 16px
Item (2depth) · Favorites 36px 14px font-medium 16px, 화살표 쪽만 12px
Sub item (3depth) 32px 14px 16px
  • 줄 사이를 띄우지 않는다. 36px이라 줄끼리 붙어도 서로 눌리지 않는다.
  • 3depth는 2depth와 크기도 색도 같고 두께만 다르다. 1depth가 13px로 작아진 자리에서 3depth까지 어중간하게 줄이면 단계가 읽히지 않는다.
  • 1depth의 13px은 oe-label token이 소유한다. 자간 0.01em은 작은 글자가 뭉치지 않게 벌린 값이며 oe에 자간 token이 없어 Tailwind 값으로 둔다.
  • 하위 목록을 여는 줄만 오른쪽 여백이 12px이다. 아이콘은 그림 안쪽에 자기 여백을 품고 있어서 글자와 같은 16px을 주면 더 들어와 보인다.
  • 아이콘은 16px이며 크기를 줄이 정한다. 넘긴 쪽이 크기를 적게 두면 줄마다 값이 갈리고, 여닫는 화살표와 줄 앞 아이콘이 서로 다른 크기로 선다.
  • 묶음은 위로 20px, 아래로 2px을 갖는다. 아래가 좁은 것은 다음 묶음의 20px이 이어 받기 때문이다.

하위 목록

  • 처음에는 닫혀 있다. 열려 있으면 묶음 여덟이 한 화면에 다 펼쳐져 목록이 레일을 넘친다.
  • 어느 줄이 열려 있는지는 그 줄이 스스로 쥔다. 쓰는 쪽이 쥐면 줄 수만큼의 상태를 화면이 들게 된다.
  • 화살표는 글자 앞이 아니라 줄 끝에 둔다. 하위가 없는 형제와 글자 시작점이 어긋나지 않게 하기 위해서다.
  • 아래를 보는 화살표로 시작해 열리면 위로 돈다. 화살표가 가리키는 것은 하위 항목이 있는 방향이 아니라 눌렀을 때 내용이 펼쳐질 방향이다. 규칙은 interaction.md의 「여닫는 화살표」가 소유한다.
  • 하위 목록의 왼쪽에 2px 선을 긋는다. 양 끝이 둥글고 위아래로 6px씩 들어가 목록보다 짧다. border는 끝을 둥글게 만들 수 없어서 선을 따로 그린다.
  • 하위 목록은 왼쪽 14px에 안쪽 10px을 갖고 오른쪽은 2depth 줄과 같은 선에서 끝난다. 좌우가 같은 여백이면 하위 목록만 혼자 좁아 보인다. 안쪽 10px은 고른 줄의 바탕이 선에 닿지 않게 하는 값이다.

색을 값으로 받는다

아홉 색을 palette로 받고 packages/tokens에 두지 않는다.

칸 칠하는 자리 주지 않았을 때
background 레일의 바탕 oe-background-primary
foreground 고르지 않은 줄의 글자 oe-foreground-primary
border 레일의 오른쪽 선과 하위 목록의 왼쪽 선 oe-border-secondary
hoverBackground 줄 위에 마우스를 얹었을 때와 누르는 동안의 면 oe-interaction-hover-subtle
hoverForeground 그때의 글자 oe-foreground-primary
selectedBackground 고른 줄의 면 oe-background-secondary
selectedForeground 고른 줄의 글자 oe-foreground-primary
searchBackground 검색 입력의 면 oe-background-secondary
groupForeground 묶음 이름의 글자 줄 글자의 70%

까닭은 셋이다.

이 시스템은 다크 모드를 제공하지 않는다. 그래서 짙은 바탕은 테마가 아니라 스타일의 선택이며, 테마에 따라 뒤집히는 token 대신 고정된 값을 받는다. 지금 관리자 웹은 짙은 브랜드 색·밝은 브랜드 색·회색조 세 스타일을 갖고 그 가운데 어느 것을 쓸지는 제품의 환경설정이 정한다. 한 값이 모든 서비스에서 같지 않으므로 packages/tokens가 가질 수 없다.

packages/ui의 컴포넌트가 앱의 globals.css에 기대지 않는다. 전에는 이 아홉이 --nav-*라는 이름으로 sandbox와 Studio 두 앱의 globals.css에 같은 내용으로 복제되어 있었고, 그 매핑이 없는 앱에서는 레일이 투명하게 칠해졌다. 이름 매핑은 packages/ui/src/styles.css로 옮겼고 값은 Property로 받는다. message-bubble.md의 --oe-message-*도 같은 꼴로 그 파일이 갖는다.

한 칸만 바꿀 수 있어야 한다. 아홉을 다 받아야 하는 Property로 두면 색 하나를 바꾸려는 쓰는 쪽이 나머지 여덟을 옮겨 적게 된다. 주지 않은 칸은 컴포넌트가 oe 토큰으로 채운다.

groupForeground만 토큰이 아니라 줄 글자에서 덜어 쓴 값이다. 줄 글자에서 한 단계 물러선 색이어야 하는데 palette가 줄 글자를 바꾸면 묶음 이름도 함께 따라가야 하므로 고정된 단계를 둘 수 없다. 그 자리에 놓일 token이 정해지기 전까지 이렇게 둔다.

고른 줄의 색

고른 줄은 brand가 아니라 중립으로 알린다.

interaction.md의 「선택 상태와 Hover·Pressed」가 「면을 칠해 선택을 알리는 요소는 중립으로 알린다 … 목록 행이 여기 든다」로 적고 「brand는 그 밖에 실행과 Focus에만 쓴다」로 좁힌다. 메뉴 줄은 경계가 없는 목록 행이므로 선 색이 아니라 면을 채워 알린다. 고른 줄에 brand를 쓰면 Focus ring과 같은 색조가 되어 고른 것과 커서가 놓인 것이 색으로 갈리지 않는다. bottom-navigation.md와 tabs.md도 같은 까닭으로 중립을 쓴다.

중립 안에서 Hover와 갈라 놓는 것이 함께 필요하다. 받은 코드가 brand를 고른 까닭이 「회색 바탕이 hover와 같은 색이라 가리키고 있는 줄과 고른 줄이 구분되지 않았다」였으므로, 같은 값을 두 번 쓰지 않는 사다리로 푼다.

  • Hover와 Pressed: oe-interaction-hover-subtle
  • 고른 줄의 면: 그보다 진한 oe-background-secondary
  • 고른 줄의 글자: 가장 진한 중립인 oe-foreground-primary

마지막 값은 bottom-navigation.md가 같은 까닭으로 고른 것과 같다.

선택된 상태에는 Hover와 Pressed 하이라이트를 중첩하지 않는다. 고른 줄 위에서 포인터를 움직이거나 누르는 동안에도 선택 배경을 유지한다. 회색조를 덧입히면 선택 색이 흐려져 무엇이 선택되어 있는지 알기 어려워진다.

스타일을 고르면 이 셋은 그 스타일의 값으로 덮인다. 지금 쓰는 세 스타일은 모두 흰 알파나 검정 알파의 사다리이고 brand 단계를 쓰지 않는다 — 짙은 바탕 위에서 brand 색을 한 줄에만 두면 그 줄이 어느 화면인지 알리는 표시가 아니라 강조로 읽힌다.

Focus

경계가 없는 요소이므로 interaction.md의 유형 3을 쓰되, 줄의 네모 전체에 그린다. Bottom Navigation처럼 선택 표시 자리에만 그리지 않는 것은 줄이 가로로 길어 그 안에 따로 둘 표시가 없기 때문이다.

줄과 Toggle은 탭으로 닿는다. Edge toggle은 탭 순서에서 빠진다 — Toggle이 이미 같은 일로 순서 안에 있어서, 둘 다 들어오면 탭 한 번에 같은 일을 하는 자리가 두 번 걸린다.

갖지 않는 것

Disabled를 제공하지 않는다. 누를 수 없는 메뉴 줄은 그리지 않는다. Property를 남겨 두면 시각 표현이 정해지지 않은 상태를 쓰는 쪽이 넘길 수 있게 된다.

레일을 아이콘 폭으로 좁히는 모양을 두지 않는다. 접는 길은 화면 밖으로 밀어내는 하나다. 아이콘만 남기면 묶음 이름이 사라져 서른 넘는 항목을 아이콘으로만 가려야 하고, 그 아이콘들은 지금 이름 옆에 붙는 보조 표시로 고른 것이다.

좁은 폭에서 서랍으로 갈아타지 않는다. 관리자 웹은 lg까지만 대응하므로 그 구간이 설계된 상태가 아니다.

검색이 메뉴를 거르지 않는다. 입력은 글만 쥐고 목록은 그대로다. 아래 「현재 정의하지 않은 항목」이 그 사실을 함께 갖는다.

현재 정의하지 않은 항목

  • 검색어로 메뉴를 거르는 동작. 입력은 서지만 목록이 걸러지지 않는다. 붙일 때 정할 것은 셋이다 — 묶음 이름도 찾는 대상인지, 걸린 하위 항목이 든 묶음이 저절로 펴지는지, 하나도 걸리지 않았을 때 무엇이 서는지.
  • 접은 상태를 기억하는 일. 다시 열면 늘 펼쳐진 채로 시작한다. 받은 코드가 쿠키에 적기만 하고 읽는 자리가 없어서 그 코드를 걷었다. 어디에 기억할지(쿠키·localStorage·사용자 설정)와 서버에서 그린 첫 화면이 그 값을 알 수 있어야 하는지를 함께 정한다.
  • 누르는 동안의 면. 지금은 Hover와 같은 값을 쓴다. interaction.md는 Pressed를 Hover보다 한 단계 진한 oe-interaction-hover로 두는데, 그러려면 palette에 칸이 하나 더 필요하다. 스타일 셋이 모두 알파의 사다리라 그 한 단계를 어디에 끼울지 함께 정한다.
  • 고른 줄이 목록 밖에 있을 때. 주소로 바로 들어온 화면의 줄이 접힌 하위 목록 안에 있으면 그 목록이 저절로 펴지지 않고, 목록이 길어 화면 밖에 있으면 그 자리로 스크롤하지도 않는다. 실제 경로가 붙을 때 함께 정한다.
  • 즐겨찾기를 이 레일에서 담고 빼는 길. 지금은 담긴 목록만 받아 그린다. 담는 조작은 page-header.md의 별이 갖는다.
  • 줄에 알림 수를 붙이는 일. 받은 코드가 그 자리를 갖고 있었으나 쓰는 화면이 없어 걷었다. 필요해지면 notification-badge.md를 어디에 얹을지 정한다.
  • 항목 이름이 240px을 넘을 때. 지금 메뉴는 가장 긴 이름도 폭 안에 들어간다. 넘치면 줄이 잘라 내는데, 말줄임으로 알릴지 두 줄로 넘길지 정하지 않았다.