분할 패널
목록 · 상세, 편집 · 미리보기, 채널 · 대화 · 스레드처럼 둘(셋까지)을 함께 보는 화면에서 칸의 폭을 끌거나 키보드로 정합니다.
손잡이는 쉴 때 헤어라인 1px 하나입니다. 손을 올리면 선이 2px 로 굵어지고 작은 키캡이 나타나며, 잡으면 primary 선 + 키캡이 두께만큼 가라앉고 앞 칸의 폭(px)이 뜹니다. 끌기 · 접기 · 저장은 react-resizable-panels 가 하고(W3 결정 #17), 손잡이 모양 · 이름 · 키보드는 이 컴포넌트가 맞춥니다. 이 서브패스만 react-resizable-panels 를 peer 로 가져옵니다.
- import
- import { SplitPanel, SplitPane, SplitHandle } from "@uyoolabs/ui/split";
- 쓰는 경우
- lg(1024) 이상에서 두 칸 이상을 나란히 보며 폭을 사람이 정해야 할 때 씁니다. 칸마다 최소 · 최대를 주고, 끝 칸(상세 · 대화)은 maxSize 를 100% 로 둬 이웃 칸이 접힐 자리를 줍니다.
- 쓰지 않는 경우
- lg 미만에서 쓰지 않습니다(collapseBelow 의 data-narrow 를 받아 한 칸 + 뒤로 가기로 바꿉니다). 칸 경계 전체에 포커스 링을 두르지 않습니다. 넷 이상의 칸으로 나누지 않습니다. 고정 폭이면 되는 사이드바에 쓰지 않습니다(AppShell).
- 값
- sizes · defaultSizes · onSizeChange · onSizeCommit 은 % 이고 합이 100 입니다. 접힌 칸은 0 입니다. 끄는 동안은 onSizeChange, 놓았을 때와 키보드 한 번에 onSizeCommit 을 한 번 부릅니다. 창 크기가 바뀌면 px 최소값을 지키도록 다시 나눕니다.
- 접근성
- APG Window Splitter. 손잡이는 role=separator · aria-valuenow(앞 칸 %) · aria-controls(앞 칸) 이고, 칸은 label 을 이름으로 갖는 영역(region)입니다. 끄는 동안의 폭 표시는 시각 전용입니다.
두 칸 · 접힘
목록 · 상세. 앞 칸 최소 240 · 최대 60%, 접을 수 있음.
세 칸 · 위아래
손잡이마다 앞 칸의 이름으로 읽힙니다.
키보드
| 키 | 동작 |
|---|---|
| ←→ | 앞 칸을 8px 줄이고 늘립니다(위아래 칸은 ↑ ↓). |
| Shift+←Shift+→ | 10% 씩 옮깁니다. |
| HomeEnd | 앞 칸을 최소 · 최대로 옮깁니다. 닿으면 손잡이 점이 진해집니다. |
| Enter | 접을 수 있는 칸(collapsible)을 접고 · 다시 폅니다. 펴면 이전 크기로 돌아갑니다. 한 · 일 입력을 조합하는 중이면 무시합니다. |
| F6Shift+F6 | 칸 사이로 포커스를 옮깁니다. 마지막 칸에서는 앱 셸의 영역 이동(사이드바 · 상단 바 · 본문)으로 넘어갑니다. |
props
소스의 타입과 JSDoc 에서 생성한 표입니다. 컴포넌트를 고치면 pnpm gen 으로 다시 만듭니다.
SplitPanel
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| direction | "horizontal" | "vertical" | "horizontal" | 칸이 놓이는 방향. horizontal = 좌우 칸(손잡이는 세로선), vertical = 위아래 칸 |
| sizes | number[] | — | 제어: 칸마다 %(합 100), 자식 SplitPane 순서. 접힌 칸은 0. 값이 바뀌면 그 크기로 옮긴다 |
| defaultSizes | number[] | — | 비제어 첫 값(%). 없으면 칸을 고르게 나눈다 |
| onSizeChange | (sizes: number[]) => void | — | 끄는 동안(포인터가 움직일 때마다) 부른다 |
| onSizeCommit | (sizes: number[]) => void | — | 놓았을 때 · 키보드로 한 번 옮겼을 때 한 번 부른다. 서버 저장은 여기서 한다 |
| storageKey | string | — | 주면 이 키로 localStorage 에 크기를 저장하고 다음 방문에 되살린다(W3 결정 #17) |
| collapseBelow | number | — | 이 폭(px, 위아래 칸은 높이) 아래에서는 손잡이를 숨기고 data-narrow 를 단다. 앱이 한 칸으로 바꾸는 신호 |
| lang | "ko" | "en" | "ja" | — | |
| labels | Partial<SplitPanelLabels> | — | |
| className | string | — | |
| children필수 | ReactNode | — | SplitPane · SplitHandle 을 번갈아 직접 자식으로 둔다(Fragment 로 감싸지 않는다) |
SplitPane
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| id필수 | string | — | 손잡이의 aria-controls 이자 저장 열쇠. 화면 안에서 하나여야 한다 |
| minSize | PaneSize | 240 | 숫자는 px, "30%" 는 비율 |
| maxSize | PaneSize | "60%" | 숫자는 px, "60%" 는 비율 |
| collapsible | boolean | false | 손잡이에서 Enter 로 0 까지 접힌다. 접히면 가장자리에 [펼치기] 단추가 선다 |
| label필수 | string | — | 칸 이름. 영역(region)의 이름 · 손잡이 이름(labels.resize) · 펼치기 단추 이름에 쓴다 |
| className | string | — | |
| children | ReactNode | — |
SplitHandle
| prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
| label | string | — | 접근성 이름. 없으면 labels.resize(앞 칸 label) |
| className | string | — |