# Splitter

한 축을 나눠 쓰는 패널들과 그 사이를 끌어 크기를 바꾸는 구분자입니다. shadcn/ui Resizable 을 기준으로 삼았습니다.

> 원본: `03_ASSET_GUIDE/catalog/splitter.js` · CSS: `03_ASSET_GUIDE/styles/elements/splitter.css`
> kind `component` · category `display` · status `stable` · specSource `measured`

> [!NOTE]
> **기준은 shadcn/ui `Resizable` 입니다**
> 이름·prop·단위 규칙을 [ui.shadcn.com/docs/components/resizable](https://ui.shadcn.com/docs/components/resizable)
> 과 그것이 감싸는 [react-resizable-panels](https://github.com/bvaughn/react-resizable-panels)
> 의 문서에서 확인해 옮겼습니다. `orientation` · `defaultSize` · `minSize` · `maxSize` ·
> `collapsible` · `collapsedSize` · `withHandle` · `disableDoubleClick` 과 "숫자는 픽셀,
> 단위 없는 문자열은 퍼센트" 규칙이 그쪽 계약 그대로입니다.
> 키보드 세부 동작은 그 문서에 명시되어 있지 않아 **WAI-ARIA window splitter 패턴**을
> 근거로 적었습니다. 라이브러리가 이와 같이 구현하는지는 확인하지 않았습니다.

> [!CAUTION]
> **이 저장소에는 리사이즈 로직이 없습니다**
> `splitter.css` 는 모양과 상태만 소유합니다. 실제로 끌어서 비율을 바꾸는 것은 구현하는 쪽이
> 붙이는 스크립트이고, 그 스크립트가 패널의 인라인 `flex-basis` 를 다시 씁니다.
> Grid 의 컬럼 너비 조절과 같은 구조입니다.
> (구현 `implement/src/components/splitter.tsx` 가 그 스크립트 — 포인터 드래그·키보드·접기 — 를 외부 라이브러리 없이 담당합니다.)

---

## 1. 구성

축을 정하는 **Group**, 그 축을 나눠 갖는 **Panel**, 사이에 놓여 끌 수 있는 **Separator**
셋입니다. Separator 는 패널 사이마다 하나씩 들어갑니다.

```
┌─────────────────┬┬──────────────────────────┐
│ ┌─────────────┐ ││ ┌──────────────────────┐ │
│ │   Panel A   │ ⣿│ │       Panel B        │ │
│ └─────────────┘ ││ └──────────────────────┘ │
└─────────────────┴┴──────────────────────────┘
 ①  ②  ③           ④⑤
```

| # | 요소 | 필수 | 클래스 | 설명 |
|---|---|---|---|---|
| ① | Group | 필수 | `atom-splitter` | 축(`orientation`)을 정하고 남는 공간을 패널에 나눠 줍니다. |
| ② | Panel | 필수 | `atom-splitter__panel` | 자기 몫을 차지합니다. 크기는 CSS 대신 인라인 `flex-basis` 로 지정합니다. |
| ③ | Content | 선택 | `atom-splitter__content` | 패널 안에서 따로 스크롤되는 상자입니다. 선택 사항입니다. |
| ④ | Separator | 필수 | `atom-splitter__separator` | 9px 히트 영역 안에 1px 선을 그립니다. 끄는 대상입니다. |
| ⑤ | Grip | 선택 | `atom-splitter__grip` | 끌 수 있다는 것을 보여주는 손잡이입니다. shadcn 의 `withHandle` 에 해당하고 선택 사항입니다. |

> [!WARNING]
> **크기는 스타일시트가 정하지 않습니다**
> 패널의 몫은 드래그할 때마다 스크립트가 인라인 `flex-basis` 로 다시 씁니다. `splitter.css`
> 가 폭을 함께 선언하면 첫 드래그에서 두 값이 충돌합니다.

---

## 2. 종류 / 크기

### Orientation

`horizontal` 은 패널이 좌우로 늘어서고 Separator 가 좌우로 움직입니다. `vertical` 은
위아래입니다. 선의 방향이 아닌 **패널이 나뉘는 방향**을 가리킵니다. shadcn 의
`orientation` 과 같은 기준입니다.

> [!NOTE]
> **`aria-orientation` 은 반대로 붙습니다**
> Separator 자체는 나뉘는 축과 직각으로 서 있습니다. 좌우로 나누는 Splitter 의 Separator 는
> 세로선이므로 `aria-orientation="vertical"` 입니다. WAI-ARIA `separator` 역할의 정의를
> 따른 것입니다.

### 패널 크기

shadcn 이 감싸는 react-resizable-panels 의 단위 규칙을 그대로 따릅니다. **숫자는 픽셀,
단위 없는 문자열은 퍼센트**이고 `px` · `%` · `em` · `rem` · `vh` · `vw` 를 명시할 수도
있습니다.

| prop | 기본값 | 뜻 |
| --- | --- | --- |
| `defaultSize` | auto | 처음 차지할 몫 |
| `minSize` | `0%` | 이보다 작아지지 않습니다 |
| `maxSize` | `100%` | 이보다 커지지 않습니다 |
| `collapsedSize` | `0%` | 접혔을 때의 몫 |

`minSize` 는 스타일시트가 아닌 리사이즈 로직이 지킵니다. CSS 쪽에서는 패널에
`min-width: 0` · `min-height: 0` 을 걸어 **내용보다 작아질 수 있게** 둡니다. 그러지
않으면 가장 넓은 자식이 그룹 전체의 최소 크기를 정합니다.

### Grip

Separator 가운데의 손잡이입니다. Grip 이 없으면 커서를 Separator 위에 올려야 위치를 알 수
있습니다. 두 패널의 경계가 분명하지 않으면 Grip 을 붙입니다.

| Grip | 설명 |
|---|---|
| 없음 | 선만. 나눌 수 있다는 걸 이미 아는 자리에서만 |
| 있음 | shadcn withHandle. 기본으로 이쪽을 쓴다 |

### State

끄는 동안의 `data-dragging`, 잠금 `data-disabled` 는 [3. 상태](#3-상태) 에 옮겼습니다.

### 접기

`collapsible` 패널은 `minSize` 아래로 끌리면 `collapsedSize` 까지 접힙니다. 접혀도
**Separator 는 남습니다.** 다시 펼칠 때 Separator 를 조작하기 때문입니다.

| 상태 | 설명 |
|---|---|
| 펼침 | collapsible 패널이 minSize 이상 |
| 접힘 | collapsedSize 로 줄고 Separator 는 남는다 (`data-collapsed`) |

> [!WARNING]
> **접힌 패널을 DOM 에서 빼지 않습니다**
> `data-collapsed` 는 몫을 0으로 만들고 내용만 감춥니다. 패널을 실제로 제거하면 Separator 의
> 순서가 밀리고, 다시 펼칠 수단도 사라집니다.

### 중첩

패널 안에 다른 축의 Splitter 를 넣어 두 축 레이아웃을 만듭니다. 안쪽 Group 은 바깥의
표면(배경·테두리·모서리)을 버려서 경계선이 겹쳐 보이지 않게 합니다.

### 클래스 계약

`styles/elements/splitter.css` 헤더와 원본 `registry.json` `css.blocks` 기준입니다. 클래스가 없는 값(—)은 기본 스타일 그대로입니다.

| Prop | 값 | 클래스 |
|---|---|---|
| `orientation` | `horizontal` · `vertical` | — · `--orientation_vertical` |

| Part | 클래스 |
|---|---|
| Panel | `atom-splitter__panel` |
| Separator | `atom-splitter__separator` (`role="separator"`) |
| Grip | `atom-splitter__grip` |
| Content | `atom-splitter__content` |

상태 선택자: `:hover` · `:focus-visible` · `[data-dragging]` · `[data-disabled]` · `[data-collapsed]`

중첩: `.atom-splitter__panel > .atom-splitter` 는 배경·테두리·모서리를 버립니다.

---

## 3. 상태

끄는 동안에는 Separator 에 `data-dragging` 이 붙어 선이 2px 로 굵어지고 브랜드 색이 됩니다.
같은 시점에 Group 에도 `data-dragging` 을 걸어 커서를 유지하고 글자 선택을 막습니다.
드래그 중에는 포인터가 9px 영역 밖으로 나가기 때문입니다.

| 대상 | 속성 | 결과 |
| --- | --- | --- |
| Separator | `data-dragging` | 선 2px + 브랜드 색, Grip 강조 |
| Group | `data-dragging` | 커서 유지, `user-select: none` |
| Separator | `data-disabled` | 이 구분자만 잠급니다 |
| Group | `data-disabled` | 전체를 잠급니다 — shadcn 의 `disabled` |

| State | 표현 | 선택자 |
|---|---|---|
| hover | 선 `--atom-fg-brand`, Grip `--atom-bg-layer-raised` | `.atom-splitter__separator:hover` |
| focus-visible | 2px 브랜드 링, offset -1px | `.atom-splitter__separator:focus-visible` |
| dragging | 선 2px + 브랜드 색 · 그룹 커서 유지 | `[data-dragging]` (Separator · Group) |
| disabled | 커서도 강조도 없다. Grip `opacity: 0.4` | `[data-disabled]` (Separator · Group) |
| collapsed | `flex-basis: 0`, Content 숨김 | `.atom-splitter__panel[data-collapsed]` |

---

## 4. Props

shadcn/ui `Resizable` 의 이름과 짝지으면 이렇습니다.

| 이 문서 | shadcn/ui | 클래스 |
| --- | --- | --- |
| Group | `ResizablePanelGroup` | `atom-splitter` |
| Panel | `ResizablePanel` | `atom-splitter__panel` |
| Separator | `ResizableHandle` | `atom-splitter__separator` |
| Grip | `withHandle` | `atom-splitter__grip` |

| Prop | Type | Default | 필수 | 설명 |
|---|---|---|---|---|
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | | 패널이 나뉘는 축입니다. Group 에 붙습니다. |
| `disabled` | `boolean` | `false` | | Group 에 주면 전체를, Separator 에 주면 그 하나를 잠급니다. |
| `defaultLayout` | `number[] \| string[]` | | | 처음 배치입니다. 저장해 둔 값을 넣으면 새로고침 뒤에도 유지됩니다. |
| `defaultSize` | `number \| string` | | | Panel 의 처음 몫입니다. 숫자는 px, 단위 없는 문자열은 %. |
| `minSize` | `number \| string` | `"0%"` | | Panel 의 최소 몫입니다. |
| `maxSize` | `number \| string` | `"100%"` | | Panel 의 최대 몫입니다. |
| `collapsible` | `boolean` | `false` | | `minSize` 아래로 끌리면 접히게 합니다. |
| `collapsedSize` | `number \| string` | `"0%"` | | 접혔을 때의 몫입니다. |
| `withHandle` | `boolean` | `false` | | Separator 가운데에 Grip 을 그립니다. |
| `disableDoubleClick` | `boolean` | `false` | | 더블클릭으로 기본 비율에 돌아가는 동작을 끕니다. |
| `onLayoutChange` | `(layout) => void` | | | 드래그하는 동안 포인터가 움직일 때마다 호출됩니다. |
| `onLayoutChanged` | `(layout) => void` | | | 드래그가 끝난 뒤 한 번 호출됩니다. 저장은 이쪽에서 합니다. |
| `onResize` | `(size) => void` | | | Panel 의 몫이 바뀔 때 호출됩니다. |

### Parts (compound)

| Part | 요소 | 설명 |
|---|---|---|
| `Splitter` | `<div class="atom-splitter">` | Group (`ResizablePanelGroup`). `orientation` · `disabled` · `defaultLayout` · `onLayoutChange` · `onLayoutChanged` 를 받습니다. `layout` 은 패널 순서대로의 몫(%) 배열입니다. |
| `Splitter.Panel` | `<div class="atom-splitter__panel">` | Panel (`ResizablePanel`). `defaultSize` · `minSize` · `maxSize` · `collapsible` · `collapsedSize` · `onResize` 를 받습니다. 몫은 인라인 `flex-basis` + `flex-grow: 0` 으로 쓰고, 마지막 패널은 남는 공간을 채웁니다. |
| `Splitter.Separator` | `<div class="atom-splitter__separator" role="separator">` | Separator (`ResizableHandle`). `withHandle` · `disabled` · `disableDoubleClick` 을 받습니다. 앞 패널을 `aria-controls` 로 가리키고 그 몫을 `aria-valuenow` 로 알립니다. |
| `Splitter.Content` | `<div class="atom-splitter__content">` | 패널 안에서 따로 스크롤되는 상자. 선택 사항입니다. |

---

## 5. Component tokens

| 대상 | 속성 | Token | Value |
|---|---|---|---|
| Group | background | `{color.bg.layer}` | |
| Group | border | `{color.border.subtle}` | inset 1px |
| Group | radius | `{radius.r2}` | 8px |
| Content | padding | `{space.x4}` | |
| Separator | 히트 영역 | — | 9px (선은 1px) |
| Separator 선 | background | `{color.border.subtle}` | |
| Separator 선 (hover · dragging) | background | `{color.fg.brand}` | dragging 은 2px |
| Grip | background | `{color.bg.neutral-weak}` | 11×22px (세로 22×11) |
| Grip (hover · dragging) | background | `{color.bg.layer-raised}` | |
| Grip | border | `{color.border.subtle}` | inset 1px |
| Grip | radius | `{radius.r1}` | |
| Focus ring | outline | `{color.fg.brand}` | 2px, offset -1px |
| 전환 | duration | `{duration.fast}` | |

```json
{
  "splitter": {
    "group": {
      "bg":     { "$type": "color", "$value": "{color.bg.layer}" },
      "border": { "$type": "color", "$value": "{color.border.subtle}" },
      "radius": { "$type": "dimension", "$value": "{radius.r2}" }
    },
    "content": {
      "padding": { "$type": "dimension", "$value": "{space.x4}" }
    },
    "separator": {
      "hit-area":    { "$type": "dimension", "$value": "9px" },
      "line":        { "$type": "color", "$value": "{color.border.subtle}" },
      "line-active": { "$type": "color", "$value": "{color.fg.brand}" },
      "line-width":  { "$type": "dimension", "$value": "1px" },
      "line-width-dragging": { "$type": "dimension", "$value": "2px" }
    },
    "grip": {
      "bg":        { "$type": "color", "$value": "{color.bg.neutral-weak}" },
      "bg-active": { "$type": "color", "$value": "{color.bg.layer-raised}" },
      "border":    { "$type": "color", "$value": "{color.border.subtle}" },
      "radius":    { "$type": "dimension", "$value": "{radius.r1}" },
      "width":     { "$type": "dimension", "$value": "11px" },
      "height":    { "$type": "dimension", "$value": "22px" }
    },
    "focus-ring": { "$type": "color", "$value": "{color.fg.brand}" },
    "transition": { "$type": "duration", "$value": "{duration.fast}" }
  }
}
```

---

## 6. 접근성

Separator 는 **값을 가진 컨트롤**입니다. WAI-ARIA 의 window splitter 패턴을
따릅니다.

- **역할** — `role="separator"` 와 `tabindex="0"`. 초점을 받지 못하면 키보드로 조작할 수
  없습니다.
- **방향** — `aria-orientation` 은 **선의 방향**입니다. 좌우로 나누는 Splitter 의 Separator 는
  `vertical` 입니다.
- **값** — 현재 비율을 `aria-valuenow`, 범위를 `aria-valuemin` · `aria-valuemax` 로 알립니다.
  값이 없으면 스크린리더는 얼마나 움직였는지 읽어줄 수 없습니다.
- **연결과 이름** — `aria-controls` 로 크기가 바뀌는 패널을 가리키고, `aria-label` 로 무엇을
  나누는 구분자인지 밝힙니다.
- **키보드** — 화살표 키로 조금씩, `Home` · `End` 로 최소·최대까지. `collapsible` 이면
  `Enter` 로 접고 폅니다.
- **되돌리기** — 더블클릭은 기본 비율로 되돌립니다(라이브러리의 `disableDoubleClick` 으로 끌 수
  있음). 키보드에도 같은 되돌리기를 주세요.
- **히트 영역** — 선보다 넓게. 이 파일은 9px 이고 그보다 좁으면 트랙패드로 집기 어렵습니다.
- **드래그 중** — Group 에 `user-select: none` 을 걸어 글자가 딸려 선택되지 않게 합니다.

**Specification › Accessibility**

- **역할** — `separator`. 값을 가진 컨트롤이므로 초점을 받아야 합니다.
- **키보드** — 화살표로 이동, `Home` · `End` 로 양 끝, `Enter` 로 접기/펴기.
- **스크린리더** — `aria-valuenow` / `min` / `max` 가 비율을, `aria-label` 이 무엇을 나누는지
  전달합니다.
- **대비** — 1px 선은 장식이고 조작 대상은 9px 히트 영역입니다. 초점 링이 실제 조작 범위를
  보여줍니다.

---

## 7. 사용 가이드

### 패널마다 최소 크기를 줍니다

`minSize` 가 없으면 패널이 실수로 몇 px 까지 줄어들 수 있고, 그 상태에서는 다시 넓힐
손잡이를 찾기 어렵습니다.

- ✅ **Do** 내용을 알아볼 수 있는 최소치를 `minSize` 로 잡습니다.
- ❌ **Don't** 0까지 줄어들게 두지 않습니다. 접어야 한다면 `collapsible` 을 쓰세요.

완전히 감추려면 0까지 끌리게 두지 말고 `collapsible` 을 켜세요.
접힘은 한 번에 일어나고 되돌리는 방법이 정해져 있습니다.

### 한 축에 둘, 많아야 셋

Separator 가 늘어날수록 하나를 옮길 때 나머지가 어떻게 따라올지 예측하기 어려워집니다.
셋을 넘으면 접기나 탭으로 묶습니다.

- ✅ **Do** 한 축은 둘로 나누고, 더 필요하면 중첩으로 축을 바꿉니다.
- ❌ **Don't** 한 줄에 구분자를 여러 개 늘어놓지 않습니다.

### 옮긴 크기는 기억합니다

사용자가 조정한 패널 크기는 저장해 새로고침 후에도 유지합니다. shadcn 이 감싸는
라이브러리는 `defaultLayout` 으로 저장한 배치를 복원합니다.

> [!NOTE]
> **저장 키는 용도 기준으로 정합니다**
> 같은 Splitter 라도 문서 편집기와 설정 화면은 필요한 배치가 다릅니다. 저장 키를 화면 경로
> 대신 그 Splitter 의 용도에 맞춰 두면 경로가 바뀌어도 배치가 유지됩니다.

### 다른 레이아웃과 구분하기

| 상황 | 쓸 컴포넌트 |
| --- | --- |
| 두 영역을 동시에 보면서 비율을 사용자가 정한다 | **Splitter** |
| 같은 층위의 내용을 하나씩 번갈아 본다 | [Tabs](./tabs.md) |
| 옆 영역이 보조이고 필요할 때만 열린다 | Side Panel |
| 경계만 그리면 되고 크기는 고정이다 | Divider |

> [!WARNING]
> **모바일 폭에서는 쓰지 않습니다**
> 좁은 화면에서는 나눌 폭이 부족하고, 터치로 9px 영역을 정확히 집기 어렵습니다. 브레이크포인트 아래에서는
> Splitter 를 풀고 [Tabs](./tabs.md) 나 세로 스택으로 바꾸세요.

### 관련 컴포넌트

- [Tabs](./tabs.md) — 동시에 보지 않고 번갈아 볼 때.
- [Grid](./grid.md) — 컬럼 하나의 폭만 끄는 경우. 같은 히트 영역 규칙을 씁니다.

---

## 8. 예시

```tsx
<Splitter onLayoutChanged={(layout) => save("nav-layout", layout)}>
  <Splitter.Panel id="nav-panel" defaultSize="30" minSize="15" maxSize="60" collapsible>
    <Splitter.Content>목록</Splitter.Content>
  </Splitter.Panel>
  <Splitter.Separator withHandle aria-label="탐색 영역 크기 조절" />
  <Splitter.Panel>
    <Splitter orientation="vertical">
      <Splitter.Panel defaultSize="60">
        <Splitter.Content>상세</Splitter.Content>
      </Splitter.Panel>
      <Splitter.Separator withHandle aria-label="로그 영역 크기 조절" />
      <Splitter.Panel>
        <Splitter.Content>로그</Splitter.Content>
      </Splitter.Panel>
    </Splitter>
  </Splitter.Panel>
</Splitter>
```

```html
<div class="atom-splitter" style="height: 320px">
  <!-- 몫은 리사이즈 로직이 인라인으로 다시 씁니다 -->
  <div class="atom-splitter__panel" style="flex-basis: 30%; flex-grow: 0">
    <div class="atom-splitter__content">목록</div>
  </div>

  <div class="atom-splitter__separator" role="separator" tabindex="0"
       aria-orientation="vertical" aria-label="탐색 영역 크기 조절"
       aria-controls="nav-panel" aria-valuenow="30"
       aria-valuemin="15" aria-valuemax="60">
    <span class="atom-splitter__grip">…</span>
  </div>

  <div class="atom-splitter__panel">
    <div class="atom-splitter__content">상세</div>
  </div>
</div>
```