트리
깊이가 있는 목록(문서 · 폴더 · 채널 묶음)을 펴고 접으며 고르는 내비게이션입니다. APG Tree View 입니다.
행은 32(sm 28)이고 단계마다 16 들여씁니다. 들여쓰기 가이드(구조선)는 기본으로 켜져 있습니다. 하나를 고르면 사이드바 현재 항목과 같은 솟은 칸이 되고, 여러 개를 고르면 체크 하나로만 말합니다. 부모를 골라도 자식은 따로 남습니다. 부모의 가로줄은 '안에 고른 것이 있다'는 표시입니다.
- import
- import { Tree, type TreeNode } from "@uyoolabs/ui/nav";
- 쓰는 경우
- 문서 사이드바, 폴더 고르기 팝오버(sm), 이동 대상 고르기 대화상자처럼 단계가 있는 목록에 씁니다. 자식이 많으면 loadChildren 으로 펼칠 때 부릅니다.
- 쓰지 않는 경우
- 한 단계 목록(사이드바 섹션)에는 쓰지 않습니다. 열이 있는 자료는 표로 둡니다. 끌어 옮기기를 넣지 않습니다(옮기기는 '이동' 메뉴로). 선택을 파랑 면으로 칠하지 않습니다.
- 알림
- 가지를 다 불러오면 role=status 로 '회의록: 4개 항목' 을 한 번 알립니다. 여러 개 고르기에서는 선택 수가 바뀔 때 알립니다. 안내 줄(불러오는 중 · 비어 있음 · 오류)은 treeitem 이 아니라 포커스를 받지 않고, 오류 줄의 [다시 시도]만 Tab 순서에 들어옵니다.
- 비활성
- 포커스는 받습니다. 이유(disabledReason, 없으면 '권한이 없습니다')를 aria-describedby 와 툴팁으로 읽게 하고, 고르기 · 열기 · 펼치기는 막습니다.
문서 사이드바
single(기본). 누르면 고르고 onAction 으로 엽니다.
- 결제 개편
- 기획
- 요구사항 정의서
- 정산 표 설계
- 환불 정책 초안
- 회의록
- 외부 공유
- 인사 평가
- 온보딩
연 문서: calc
펼친 가지: pay, plan
여러 개 고르기 · sm
aria-multiselectable. Space 로 켜고 끄고, Shift+↓ 로 넓히고, ⌘A 로 보이는 항목을 모두 고릅니다.
- 결제 개편
- 기획
- 회의록
- 외부 공유
- 온보딩
고른 것: req
항목
TreeNode 의 꼴입니다.
가지는 children 이 있거나(빈 배열 포함) hasChildren 인 항목입니다. 펼칠 때 children 이 없으면 loadChildren(id) 을 부르고, 그동안 가지에 aria-busy 를 둡니다.
키보드
| 키 | 동작 |
|---|---|
| ↓↑ | 보이는 다음 · 이전 항목으로 갑니다. |
| → | 접힌 가지는 펼치고, 펼친 가지는 첫 자식으로 갑니다. 잎에서는 그대로입니다. |
| ← | 펼친 가지는 접고, 그 밖에는 부모로 갑니다. |
| HomeEnd | 첫 항목 · 보이는 마지막 항목으로 갑니다. |
| Enter | onAction(열기). single 이면 고르기도 합니다. href 행은 onAction 뒤 링크로 이동합니다(onAction 에서 preventDefault 로 막습니다). 한 · 일 입력 조합 중의 Enter 는 무시합니다. |
| Space | 고르기(single) · 켜고 끄기(multiple). |
| * | 같은 단계의 형제 가지를 모두 펼칩니다. |
| Shift+↓Shift+↑ | (multiple) 선택을 넓힙니다. |
| ⌘ACtrl+A | (multiple) 보이는 항목을 모두 고릅니다. |
| 글자 | 그 글자로 시작하는 다음 항목으로 갑니다. 이어 치면 이어 붙여 찾습니다. 조합 중인 키는 무시하고 확정 글자로 찾으며, 한글 자음만 치면 초성으로 찾습니다(ㅈ → 정산 표 설계). |
| Tab | 트리로 한 번에 들어옵니다(마지막으로 포커스한 항목 → 고른 항목 → 첫 항목). 다시 Tab 이면 트리 밖으로 나갑니다. |
props
소스의 타입과 JSDoc 에서 생성한 표입니다. 컴포넌트를 고치면 pnpm gen 으로 다시 만듭니다.
Tree
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| items필수 | TreeNode[] | — | |
| aria-label | string | — | 둘 중 하나는 반드시. 없으면 개발 중 경고 |
| aria-labelledby | string | — | |
| expanded | string[] | — | |
| defaultExpanded | string[] | — | |
| onExpandedChange | (ids: string[]) => void | — | |
| selectionMode | "single" | "multiple" | "none" | "single" | none 이면 고르지 않고 열기(onAction)만 |
| selected | string[] | — | |
| defaultSelected | string[] | — | |
| onSelectedChange | (ids: string[]) => void | — | |
| cascadeSelection | boolean | false | multiple 에서 부모를 켜고 끄면 불러온 자식까지 같이 켜고 끈다. 기본은 부모와 자식이 별개다(결정 #20). 권한 트리처럼 연쇄가 필요한 곳에서만 켠다 |
| onAction | (id: string, event: TreeActionEvent) => void | — | Enter · 클릭(문서 열기). single 에서는 선택과 함께 일어난다. href 행은 이것이 먼저 불리고, preventDefault 로 이동을 막는다 |
| loadChildren | (id: string) => Promise<TreeNode[]> | — | 펼칠 때 자식을 부른다. 그동안 가지에 aria-busy · '불러오는 중…' 줄, 실패하면 '불러오지 못했습니다 · 다시 시도' 줄 |
| size | "md" | "sm" | "md" | 32 · 28. 사이드바 안은 md(내비 항목과 같다), 팝오버 · 패널 안의 폴더 고르기는 sm |
| guides | boolean | true | 들여쓰기 가이드(line-strong 헤어라인). 단계가 깊으면 어느 가지인지 이 선이 말한다(결정 #20) |
| renderLabel | (node: TreeNode) => ReactNode | — | 이름 그리기를 바꾼다(검색 강조 등). 접근성 이름은 label 그대로 |
| lang | "ko" | "en" | "ja" | — | |
| labels | Partial<TreeLabels> | — | |
| className | string | — |