@neurocle/synapse-react 0.0.0-bootstrap → 0.0.0-stage

package/skills/components/tooltip/SKILL.md

@@ -1,188 +0,0 @@
----
-name: 'tooltip'
-description: 'Tooltip — 포인터가 머물러 있거나 키보드가 포커스한 컨트롤에 대한 짧은 설명이며, `aria-describedby`로 연결되고 사용자가 상호작용할 수 있는 것은 아무것도 담지 않습니다. 다른 이름: tooltip, hint, hover text, title text, balloon help, popup hint, 툴팁, 말풍선 도움말, 힌트, 마우스오버 설명.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/tooltip.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/tooltip.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# Tooltip
-
-> 포인터가 머물러 있거나 키보드가 포커스한 컨트롤에 대한 짧은 설명이며, `aria-describedby`로 연결되고 사용자가 상호작용할 수 있는 것은 아무것도 담지 않습니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `Tooltip`
-- 분류: `floating-and-overlay`
-- 수명 주기: `active`
-
-## 알려진 예외 — 사용 전에 확인
-
-이 컴포넌트는 아래 기준 2개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
-
-### WCAG 2.2 SC 1.4.13 hover 또는 포커스 시 콘텐츠 (AA)
-
-- 충족하지 못하는 것: 터치로는 열리지 않습니다. machine이 터치 포인터에서 일찍 반환하고, 탭은 focus-visible을 만들지 않습니다.
-- 의도한 이유: machine의 설계이며, machine 밖에서 탭 핸들러를 덧붙이지 않습니다.
-- 사용 시 유의점: 툴팁에 꼭 필요한 정보를 두지 마세요. trigger를 조작하는 데 필요한 내용은 trigger의 이름이나 주변 콘텐츠에 있어야 합니다. 탭으로 보여 줘야 하면 `open`을 직접 제어하거나 Popover를 쓰세요.
-
-### Synapse 공유 레이어 스택 — 참여하지 않음
-
-- 충족하지 못하는 것: `--layer-index`가 없고 공유 쌓임 순서에 참여하지 않습니다. 자체 캡처링 keydown으로 Escape를 처리하며, Dialog 안에 있으면 한 번의 Escape가 툴팁과 Dialog를 함께 닫습니다.
-- 의도한 이유: `@zag-js/tooltip`이 `@zag-js/dismissable`에 등록하지 않는 업스트림 구조입니다.
-- 사용 시 유의점: Dialog·Drawer 안의 trigger에 툴팁을 달면, 툴팁이 열린 상태에서 Escape를 누른 사용자는 모달까지 닫힙니다. 모달 안에서는 툴팁 대신 보이는 설명 텍스트를 우선하세요.
-
-## Do
-
-> 사용자가 이미 가리키고 있거나 방금 Tab으로 이동한 컨트롤에 대한 짧은 보충 설명에 쓰세요 — 툴바 아이콘이 이름 이상으로 하는 일, 표 안의 숫자가 뜻하는 것, 어떤 단축키가 동작을 실행하는지처럼 말입니다. 텍스트가 부가적일 때에만 정확히 알맞은 컨트롤입니다. 누가 툴팁을 보든 보지 않든 trigger는 똑같이 동작하며, 이것이 터치에서의 동작을 받아들일 수 있게 만듭니다.
-
-## Don't
-
-> 컨트롤의 유일한 레이블을 툴팁에 넣지 마세요. 툴팁은 터치로 열리지 않고 이름이 아니라 설명을 제공하므로, 의미가 여기에만 있는 아이콘 버튼은 모든 터치 사용자에게 레이블이 없고 모든 스크린 리더 사용자에게 이름 없이 알려집니다. 링크, 버튼, 닫기 컨트롤 같은 상호작용 가능한 것을 안에 넣지 마세요. 포커스는 콘텐츠에 결코 들어가지 않고 포인터는 기본적으로 그 위를 지나가 버리기 때문입니다. 그런 콘텐츠는 클릭으로 열리고 도달할 수 있는 Popover에 속합니다. 사용자가 의도적으로 불러내야 할 수 있는 것에도 쓰지 마세요. 휴대폰에서는 그럴 수 없기 때문입니다. 그리고 검증 오류를 설명하는 데도 쓰지 마세요. 메시지는 hover 없이도 알려지는 필드 쪽에 있어야 합니다.
-
-## Anti-patterns
-
-> 툴팁을 아이콘 버튼의 접근 가능한 이름으로 쓰는 것. 툴팁은 aria-describedby로 연결되므로, 스크린 리더는 이름 없는 버튼을 먼저 알리고 설명은 그다음에 알립니다 — 그것도 툴팁이 마침 열려 있는 동안에만 말입니다. 이름은 버튼 자체의 aria-label이나 시각적으로 숨긴 텍스트를 통해 버튼에 있어야 합니다. 그러면 툴팁은 원래 존재 이유인 추가 문장을 자유롭게 전달하고, 같은 버튼이 터치에서 빈 사각형이 되는 일도 사라집니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
-
-## 관련 컴포넌트
-
-- `Popover` (`popover`)
-- `HoverCard` (`hover-card`)
-- `Dialog` (`dialog`)
-- `Toast` (`toast`)
-
-## 가져오기
-
-```tsx
-import { Tooltip } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 6개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<Tooltip.Root>
-  <Tooltip.Trigger />
-  <Tooltip.Positioner>
-    <Tooltip.Content>
-      <Tooltip.Arrow>
-        <Tooltip.ArrowTip />
-      </Tooltip.Arrow>
-    </Tooltip.Content>
-  </Tooltip.Positioner>
-</Tooltip.Root>
-```
-
-- `Tooltip.Root`
-- `Tooltip.Trigger` — 최상위에 놓입니다
-- `Tooltip.Arrow` — `Content` 안에 놓입니다
-- `Tooltip.ArrowTip` — `Arrow` 안에 놓입니다
-- `Tooltip.Positioner` — 최상위에 놓입니다
-- `Tooltip.Content` — `Positioner` 안에 놓입니다
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 19개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
-
-### 선택
-
-- `open` — `boolean`, 선택. 제어되는 열림 상태.
-- `defaultOpen` — `boolean`, 선택. 비제어 모드의 초기 열림 상태. `open`을 주면 무시됩니다.
-- `onOpenChange` — `(details: OpenChangeDetails) => void`, 선택. 제어 여부와 무관하게 툴팁이 열리거나 닫힐 때마다 호출됩니다.
-- `triggerValue` — `string | null`, 선택. 여러 trigger 가운데 지금 툴팁을 차지한 것이 무엇인지 나타냅니다. Tooltip 하나가 여러 trigger를 함께 맡을 수 있습니다. 각 `Tooltip.Trigger`가 `value`를 받고, 이 값이 내용의 위치 기준이 되는 trigger입니다. trigger가 하나뿐인 Tooltip에는 필요 없습니다.
-- `defaultTriggerValue` — `string | null`, 선택. 비제어 모드에서 처음 툴팁을 차지하는 trigger.
-- `onTriggerValueChange` — `(details: TooltipTriggerValueChangeDetails) => void`, 선택. 툴팁을 차지한 trigger가 바뀔 때 호출됩니다.
-- `positioning` — `TooltipPositioning`, 선택. 떠 있는 레이어가 놓이는 위치.
-- `openDelay` — `number`, 선택. 포인터가 trigger 위에 머물러야 열리기까지의 시간(밀리초).
-- `closeDelay` — `number`, 선택. 포인터가 벗어난 뒤 닫히기까지의 시간(밀리초).
-- `interactive` — `boolean`, 선택. 포인터가 내용 안에 있는 동안 툴팁을 계속 열어 둡니다. 기본값은 true입니다.
-- `disabled` — `boolean`, 선택. 비활성화된 Tooltip은 열리지 않습니다.
-- `closeOnEscape` — `boolean`, 선택. Escape로 닫습니다. 기본값은 true입니다.
-- `closeOnClick` — `boolean`, 선택. trigger를 클릭하면 닫습니다. 기본값은 true입니다.
-- `closeOnPointerDown` — `boolean`, 선택. trigger에서 포인터가 눌리면 닫습니다. 기본값은 true입니다.
-- `closeOnScroll` — `boolean`, 선택. 페이지가 스크롤되면 닫습니다.
-- `'aria-label'` — `string`, 선택. 툴팁의 텍스트가 곧 trigger의 이름일 때, 그 trigger의 접근성 이름입니다. DOM 속성이 아니라 machine prop입니다. 어느 요소가 이 값을 지니는지는 machine이 정합니다.
-- `translations` — `TranslationOverrides`, 선택. 이 Tooltip에만 적용되는 접근성 문자열로, provider의 값보다 우선합니다.
-- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
-- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
-
-## Variants
-
-- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. 크기 축은 trigger의 최소 높이와 인라인 패딩, 툴팁의 패딩과 글자 스타일, 그리고 화살표의 크기를 조절합니다. 툴팁의 너비는 정하지 않습니다. 콘텐츠는 모든 크기에서 `surface.overlayMax`에서 멈춥니다. 툴팁은 그 한 문장만큼의 너비를 가지며, 단계별 너비를 두면 짧은 툴팁들이 들쭉날쭉해지기 때문입니다.
-
-## 폼
-
-폼 참여: 아니요.
-
-> 폼에 제출하는 값이 없습니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `empty-state` — 텍스트가 없는 툴팁은 렌더링되지 말았어야 할 툴팁입니다. trigger는 자기 이름을 그대로 가지며 컨트롤에서 빠진 것은 없습니다. 이 컴포넌트가 비어 있음을 감지할 컬렉션도 없고, hover 시 나타나는 빈 떠 있는 레이어는 깜빡임일 뿐입니다.
-- `loading-state` — 준비되지 않은 설명은 사용자에게 약속해서는 안 되는 설명입니다. 열림 지연이 지나면 레이어는 설계상 즉시 나타나며, 문장이 들어갈 자리의 스피너는 이 컴포넌트가 보여 주려고 존재하는 유일한 것을, 읽는 데 걸리는 시간보다 짧게 차지할 뿐입니다.
-- `error-state` — 이 컴포넌트는 값을 가지지도 작업을 수행하지도 않으므로 실패할 일이 없습니다. 오류 상태인 컨트롤에 달린 툴팁도 그 상태에 대해 아무것도 알리지 않습니다. 메시지는 aria-invalid와 필드 자체의 텍스트가 이미 전달하고 있는 컨트롤 쪽에 있어야 합니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 툴팁은 이름을 제공하지 않습니다 — aria-describedby를 통해 설명할 뿐이며, trigger는 자체 콘텐츠가 주는 이름을 그대로 유지합니다. machine에서 오는 문자열도 없습니다. `@zag-js/tooltip`은 `translations`를 받지 않고 아무것도 하드코딩하지 않습니다. `aria-label`은 machine prop으로 받아들여지며, 보이는 텍스트를 대신하는 설명이 됩니다. machine이 `role="tooltip"`과 콘텐츠의 id를 제거하고, 컴포넌트는 그 id 아래에 레이블을 담은 시각적으로 숨긴 `role="tooltip"` 요소를 렌더링하므로 trigger의 aria-describedby는 여전히 해석됩니다. 이것이 trigger의 이름이 되는 일은 결코 없습니다. 아이콘 버튼에 이름을 붙이려는 제품은 버튼에 이름을 붙이고, 툴팁에는 추가로 할 말을 맡기세요.
-
-### 포커스
-
-> 포커스는 툴팁 안으로 결코 이동하지 않고 콘텐츠는 포커스할 수 없습니다 — `aria-describedby`가 바로 그것을 위한 것이며, 툴팁이 상호작용 가능한 것을 담아서는 안 되는 이유입니다. trigger에서 블러되면 닫히고, `interactive`는 포인터 아래에서만 열린 상태를 유지할 뿐 포커스 아래에서는 결코 그렇지 않습니다. 검증 불가: 이 패키지의 테스트 환경에는 터치 포인터도 focus-visible 휴리스틱도 없으므로, "탭하면 열리지 않습니다"도 "키보드 포커스하면 열립니다"도 이 테스트 묶음에서 검증되지 않습니다.
-
-### 공유 레이어 스택에 오르지 않음
-
-> `@zag-js/tooltip`은 `@zag-js/dismissable`에 등록하는 대신 자체 캡처링 document keydown으로 닫히므로, 콘텐츠에 `--layer-index`가 없고 공유 스택도 이를 보지 못합니다. 그 Escape에서 `stopPropagation`을 호출하지만, 해제 가능 레이어도 같은 document에 캡처로 리스너를 걸기 때문에 이벤트를 막지 못합니다. 그래서 Dialog 안의 툴팁에서 누른 Escape는 툴팁과 Dialog를 함께 닫습니다. `packages/react/tests/matrix/registration.test.tsx`는 이를 `layerStack.registers: false`와 그 이유로 선언된 예외로 다룹니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 예. 배치는 논리적입니다. `bottom-start`는 provider의 방향에 따라 해석되므로, 같은 툴팁이 영어 인터페이스와 아랍어 인터페이스에서 trigger의 반대편에 놓입니다. 방향은 모든 part에도 기록됩니다.
-- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-
-## 구조 메모
-
-### 공유 레이어 스택에 오르지 않음
-
-> `@zag-js/tooltip`은 `@zag-js/dismissable`에 등록하는 대신 자체 캡처링 document keydown으로 닫히므로, 콘텐츠에 `--layer-index`가 없고 공유 스택도 이를 보지 못합니다. 그 Escape에서 `stopPropagation`을 호출하므로 툴팁을 닫아도 그것을 둘러싼 대화상자까지 닫히지는 않습니다 — 등록이 아니라 리스너로 도달한 올바른 순서입니다. `packages/react/tests/matrix/registration.test.tsx`는 이 공백을 예외가 아니라 실패하는 단언으로 기록합니다.
-
-### 터치 경로 없음
-
-> machine은 `pointerType === 'touch'`일 때 `onPointerMove`와 `onPointerOver`에서 일찍 반환하고, `onFocus`는 `isFocusVisible()`일 때만 여는데 탭은 이를 만들어 내지 않습니다. 따라서 툴팁은 machine의 설계상 터치로 열리지 않으며, machine 밖에서 만들어 낸 동작은 전면 금지이므로 Synapse는 자체 탭 핸들러를 추가하지 않습니다. 그 결과가 Tooltip을 쓰는 제품이 받아들이는 계약입니다. 사용자가 trigger를 조작하는 데 알아야 할 것은 무엇이든 trigger 자체의 이름이나 인접한 콘텐츠에 있어야 합니다. 탭해서 보여 주기가 정말 필요한 제품은 `open`을 직접 제어하거나, 클릭으로, 따라서 탭으로도 열리는 Popover를 쓰세요.
-
-### 요소를 렌더링하지 않는 루트
-
-> 툴팁 machine에는 `root` anatomy part가 없으므로 Tooltip.Root는 동작 상태를 게시할 뿐 아무것도 렌더링하지 않습니다. trigger는 사용처가 작성한 자리 — 보통 툴바 안이나 필드 옆 — 에 머물고, Positioner와 Content는 자신을 잘라 낼 조상 요소 밖으로 포털될 수 있습니다.
-
-### 선언되는 trigger 요소
-
-> machine은 trigger를 BUTTON 노멀라이저로 정규화하지만 `type="button"`을 내보내지 않으므로, 팩토리의 요소 추론이 이를 알아보지 못하고 `div`로 남겨 둡니다 — 키보드가 닿을 수 없는 요소이며, 이 컴포넌트가 보장하는 유일한 경로를 닫아 버립니다. 그래서 요소를 machine 자체의 노멀라이저를 근거로 명시적으로 선언하며, 이 선언이 중복이라며 제거되면 `tooltip.test.tsx`가 실패합니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `describe-a-control`, `non-interactive-overlay`, `floating-layer`, `translatable-strings`.
-- 다른 이름: `tooltip`, `hint`, `hover text`, `title text`, `balloon help`, `popup hint`, `툴팁`, `말풍선 도움말`, `힌트`, `마우스오버 설명`.
-- 어휘 상태: `controlled`.

package/skills/components/tour/SKILL.md

@@ -1,158 +0,0 @@
----
-name: 'tour'
-description: 'Tour — 안내형 둘러보기입니다. 각 단계가 페이지의 실제 요소에 고정된 단계들의 흐름이며, 백드롭에 스포트라이트 구멍을 내고 제목, 설명, 단계별 푸터 버튼을 담은 카드를 보여 줍니다. 트리에서가 아니라 핸들러에서 `useTour()` 컨트롤러를 통해 시작합니다. 다른 이름: tour, product tour, onboarding tour, walkthrough, coach marks, guided tips, 투어, 제품 투어, 온보딩 가이드, 기능 안내, 코치 마크.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/tour.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/tour.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# Tour
-
-> 안내형 둘러보기입니다. 각 단계가 페이지의 실제 요소에 고정된 단계들의 흐름이며, 백드롭에 스포트라이트 구멍을 내고 제목, 설명, 단계별 푸터 버튼을 담은 카드를 보여 줍니다. 트리에서가 아니라 핸들러에서 `useTour()` 컨트롤러를 통해 시작합니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `Tour`
-- 분류: `floating-and-overlay`
-- 수명 주기: `active`
-
-## Do
-
-> 정말 발견하기 어려운 것을 소개하는 짧은 흐름에 쓰세요 — 새 작업 공간, 새로 설계된 에디터, 클릭 두 번 뒤에 숨은 기능처럼 말입니다. 각 단계는 `target()`으로 실제 요소를 지정하며, 스포트라이트가 그 요소를 도려내고 카드가 그 요소에 고정됩니다. 대상이 없는 단계는 가운데 정렬된 대화상자가 되며, 이는 시작과 마무리 인사에 알맞은 모양입니다. `useTour()`에서 시작하세요. 투어를 실행할지는 이 사용자가 이미 투어를 보았는지 아는 이펙트나 핸들러에서 결정되기 때문입니다.
-
-## Don't
-
-> 설명이 필요한 인터페이스를 설명하는 데 쓰지 마세요 — 투어는 설계 문제 위에 덧댄 패치이며, 사용자는 읽기도 전에 닫아 버립니다. 하나의 컨트롤에 고정된 단일 팁에도 쓰지 마세요. 그것은 Popover나 Tooltip이며, 둘 다 페이지를 어둡게 하거나 포커스를 가두지 않습니다. 긴 투어를 만들지 마세요. 투어는 모달이라 제품을 막으므로, 세 번째 이후의 단계는 대부분의 사용자가 건너뛸 단계입니다. 그리고 코드로 닫을 계획을 세우지 마세요 — `antiPatterns`를 참고하세요. 컨트롤러에는 `dismiss`가 없습니다.
-
-## Anti-patterns
-
-> `useTour()`가 투어를 닫거나 건너뛸 것이라고 기대하는 것. 컨트롤러의 명령은 machine의 api가 제공하는 동사 — `start`, `next`, `prev`, `setStep`, `setSteps`, `addStep`, `removeStep`, `updateStep` — 와 정확히 같으며, machine에 없는 동작을 지어내는 컨트롤러는 전면 금지이므로 `defineController`는 정의 시점에 그 밖의 것을 노출하기를 거부합니다. 닫기와 건너뛰기는 단계 자체의 푸터 버튼이 수행하는 단계 액션과 닫기 trigger part로만 존재합니다. 따라서 코드에서 투어를 닫는 방법은 `onStatusChange`와 사용처 자체의 상태이며, 그 공백은 이 컴포넌트가 아니라 업스트림의 것입니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
-
-## 관련 컴포넌트
-
-- `Popover` (`popover`)
-- `Dialog` (`dialog`)
-- `Tooltip` (`tooltip`)
-- `Steps` (`steps`)
-- `HoverCard` (`hover-card`)
-
-## 가져오기
-
-```tsx
-import { Tour } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 12개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<Tour.Root>
-  <Tour.Positioner>
-    <Tour.Content>
-      <Tour.ActionTrigger />
-      <Tour.CloseTrigger />
-      <Tour.ProgressText />
-      <Tour.Title />
-      <Tour.Description />
-      <Tour.Arrow>
-        <Tour.ArrowTip />
-      </Tour.Arrow>
-    </Tour.Content>
-  </Tour.Positioner>
-  <Tour.Backdrop />
-  <Tour.Spotlight />
-</Tour.Root>
-```
-
-- `Tour.Root`
-- `Tour.Content` — `Positioner` 안에 놓입니다
-- `Tour.ActionTrigger` — `Content` 안에 놓입니다
-- `Tour.CloseTrigger` — `Content` 안에 놓입니다
-- `Tour.ProgressText` — `Content` 안에 놓입니다
-- `Tour.Title` — `Content` 안에 놓입니다
-- `Tour.Description` — `Content` 안에 놓입니다
-- `Tour.Positioner` — 최상위에 놓입니다
-- `Tour.Arrow` — `Content` 안에 놓입니다
-- `Tour.ArrowTip` — `Arrow` 안에 놓입니다
-- `Tour.Backdrop` — 최상위에 놓입니다
-- `Tour.Spotlight` — 최상위에 놓입니다
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 14개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
-
-### 선택
-
-- `steps` — `readonly TourStep[]`, 선택. 단계들을 순서대로 담습니다.
-- `stepId` — `string | null`, 선택. 지금 보이는 단계의 id. 투어가 돌고 있지 않은 동안에는 `null`입니다.
-- `onStepChange` — `(details: TourStepChangeDetails) => void`, 선택. 투어가 다른 단계로 옮겨 갈 때마다 호출됩니다.
-- `onStepsChange` — `(details: TourStepsChangeDetails) => void`, 선택. 단계 목록 자체가 바뀔 때마다 호출됩니다.
-- `onStatusChange` — `(details: TourStatusChangeDetails) => void`, 선택. 투어가 시작되거나, 끝나거나, 건너뛰어지거나, 닫힐 때 호출됩니다.
-- `keyboardNavigation` — `boolean`, 선택. 화살표 키로 단계 사이를 오갑니다. 기본값은 true입니다.
-- `preventInteraction` — `boolean`, 선택. 투어 뒤 페이지와의 상호작용을 막습니다.
-- `spotlightOffset` — `{ x?: number; y?: number; }`, 선택. 대상과 스포트라이트 가장자리 사이의 여백(픽셀).
-- `spotlightRadius` — `number`, 선택. 스포트라이트 모서리의 반지름(픽셀).
-- `closeOnEscape` — `boolean`, 선택. Escape로 닫습니다. 기본값은 true입니다.
-- `closeOnInteractOutside` — `boolean`, 선택. 바깥에서 포인터가 눌리면 닫습니다. 기본값은 true입니다.
-- `translations` — `TranslationOverrides`, 선택. 이 Tour에만 적용되는 접근성 문자열로, provider의 값보다 우선합니다.
-- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
-- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
-
-## Variants
-
-- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. 크기 축은 단계 카드의 크기 — 패딩과 내부 간격, 제목과 설명의 글자 스타일, 푸터 버튼의 높이, 닫기 아이콘 — 를 정합니다. 스포트라이트의 크기는 정하지 않습니다. 스포트라이트는 하이라이트된 요소 자체의 사각형에 `spotlightOffset`을 더해 런타임에 측정한 것이며, 어떤 티셔츠 사이즈도 이를 대신할 수 없습니다.
-
-## 폼
-
-폼 참여: 아니요.
-
-> 폼에 제출하는 값이 없습니다. 투어는 페이지 위에 이어지는 알림의 흐름이며, 투어가 남기는 것은 사용자가 이를 보았다는 제품 자체의 기록입니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `empty-state` — 단계가 없는 투어는 시작되지 않습니다. `status`는 `started`가 아니라 `not-found`가 되고 아무것도 렌더링되지 않으며, 빈 영역이 나타날 표면도 없습니다 — 빈 둘러보기는 제품이 제공하지 말았어야 할 투어이며, 이는 이 컴포넌트 이전에 내려지는 결정입니다.
-- `loading-state` — machine이 이미 이 상태를 가지고 있고 더 잘 이름 붙였습니다. `wait` 타입의 단계는 제품 자체의 이펙트가 진행을 호출할 때까지 투어를 붙잡아 두며, 이것이 둘러보기에서 "무언가를 기다리는 중"의 실제 모습입니다 — 준비되는 것은 투어가 아니라 페이지입니다. 단계 카드 안의 로딩 영역은 같은 멈춤을 표현하는 두 번째이자 더 약한 방식이 될 뿐입니다.
-- `error-state` — Tour는 실패할 수 있는 요청을 수행하지 않습니다. 유일한 실패 — `target()`이 아무것도 반환하지 않는 단계 — 는 `onStatusChange`를 통해 `not-found` 상태로 알려지므로, 제품이 그 단계를 건너뛸지 투어를 중단할지 결정합니다. 이를 카드 안에 넣으면 아무것도 가리키지 않는 스포트라이트 옆에 오류를 렌더링하게 됩니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 카드는 aria-labelledby를 통해 Title로 이름이 붙고 Description으로 설명됩니다. 네 가지 정적 machine 문자열 — next, previous, skip, close — 은 `machineTranslations`에 의해 provider를 거칩니다. 진행 텍스트는 예외이며, 이 컴포넌트에 `useMachineProps` 이음매가 존재하는 유일한 이유입니다. `translations.progressText`는 `{current, total}`을 받는 함수인데, `machineTranslations`는 이를 표현할 수 없고 일반 문자열을 넘기면 예외를 던지므로, 네 문자열과 나란히 따로 해석됩니다. machine의 `current`는 0부터 시작하고 투어 시작 전에는 -1이므로 범위를 제한하고 오프셋을 더합니다. 그래서 첫 단계는 1단계이며, 시작하지 않은 투어는 "0 of 5"를 렌더링하지 않습니다.
-
-### 포커스
-
-> 콘텐츠는 tabIndex -1인 aria-modal alertdialog이므로, 단계가 열리면 포커스가 카드 안으로 이동해 그곳에 머무릅니다. 뒤의 페이지는 Tab으로 닿을 수 없고, `preventInteraction`은 포인터로도 닿을 수 없게 합니다. 검증 불가: 투어는 실제 요소의 사각형을 기준으로 위치를 정하는데 테스트 환경에는 레이아웃 엔진이 없으므로, 배치, 스포트라이트의 기하, 단계 간 포커스 이동은 여기의 어떤 테스트로도 검증되지 않습니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 예. 키보드가 좌우 반전됩니다. 콘텐츠 자체의 핸들러가 provider의 `dir`을 읽어 오른쪽에서 왼쪽으로 쓰는 provider에서는 ArrowRight와 ArrowLeft를 바꾸므로, "다음"은 항상 사용자가 이미 읽어 나가는 방향입니다. 네 버튼의 이름은 provider의 번역에서 오고, 진행 텍스트는 `tour.progressText.position`으로 만들어지므로 "1 of 5"는 machine에 박힌 영어 문자열이 아니라 제품이 제공하는 패턴입니다.
-- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `guided-tour`, `spotlight`, `feature-announcement`, `imperative-control`, `dismiss-on-outside-click`, `translatable-strings`.
-- 다른 이름: `tour`, `product tour`, `onboarding tour`, `walkthrough`, `coach marks`, `guided tips`, `투어`, `제품 투어`, `온보딩 가이드`, `기능 안내`, `코치 마크`.
-- 어휘 상태: `controlled`.

package/skills/components/tree-view/SKILL.md

@@ -1,180 +0,0 @@
----
-name: 'tree-view'
-description: 'TreeView — 사용자가 펼치고, 선택하고, 체크할 수 있는 계층 구조입니다 — 파일 트리, 카테고리 계층, 목록으로 읽는 조직도처럼 말입니다. 중첩 마크업이 아니라 트리 컬렉션으로 구동되며, 행이 윈도잉되므로 깊이와 너비가 늘어나도 요소 수는 같습니다. 다른 이름: tree, tree view, file tree, folder tree, hierarchy, explorer, 트리, 트리 뷰, 파일 트리, 폴더 트리, 계층 구조 목록.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/tree-view.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/tree-view.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# TreeView
-
-> 사용자가 펼치고, 선택하고, 체크할 수 있는 계층 구조입니다 — 파일 트리, 카테고리 계층, 목록으로 읽는 조직도처럼 말입니다. 중첩 마크업이 아니라 트리 컬렉션으로 구동되며, 행이 윈도잉되므로 깊이와 너비가 늘어나도 요소 수는 같습니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `TreeView`
-- 분류: `collection-data-entry`
-- 수명 주기: `active`
-
-## Do
-
-> 데이터의 형태 자체가 핵심인 경우에 쓰세요 — 파일 시스템, 카테고리 계층, 권한 트리, 사용자가 자기 위치를 유지해야 하는 내비게이션 개요처럼 말입니다. 사용자가 무엇인지뿐 아니라 어디에 있는지도 봐야 하고, 구조 전체를 읽기보다 일부를 열고 닫을 때 선택하세요. 체크 축은 선택과 분리되어 있으므로, 선택기는 노드 하나를 하이라이트하면서 여러 노드를 체크하게 할 수 있습니다.
-
-## Don't
-
-> 제목이 있는 평탄한 목록에는 쓰지 마세요 — 그룹 항목을 쓴 Listbox가 그것을 더 명확하게 알리고, 사용자가 펼칠 필요도 없습니다. 두세 단계 깊이에 항상 위에서 아래로 탐색되는 계층에서 값 하나를 고르는 데도 쓰지 마세요. CascadeSelect는 한 번에 한 단계씩 보여 주며 조작이 더 빠릅니다. 사이트 내비게이션으로도 쓰지 마세요. 트리는 행을 현재 값을 가진 선택 가능한 노드로 알리는데, 하나를 활성화하면 다른 페이지로 이동한다면 그것은 거짓이며, 그 행들이 실제로 무엇인지 말해 주는 것은 NavigationMenu나 Toc입니다. 그리고 데이터가 마침 중첩되어 있다는 이유만으로 선택하지 마세요 — 사용자가 중첩을 볼 필요가 전혀 없다면, 그것을 조작하게 만들지 마세요.
-
-## Anti-patterns
-
-> 중첩 마크업을 얻으려고 노드를 직접 렌더링하는 것. 사용처의 children은 윈도잉된 기본 렌더링을 대체하므로, 행은 루프가 렌더링한 것 그대로가 됩니다. aria-setsize는 형제 수가 아니라 그 루프의 길이가 되고, 고정된 포커스 노드는 사라지며, 이 machine은 요소를 id로 찾아 포커스하므로 포커스가 렌더링된 범위를 벗어나는 순간 화살표 키가 아무것도 움직이지 못합니다. 작성자가 시험해 보는 스크롤 위치에서는 이 중 어느 것도 드러나지 않습니다. 다른 하나는 레시피에서 단계별 들여쓰기를 계산하는 것입니다. machine이 이미 각 노드의 깊이를 행에 기록하며, 단계마다 규칙을 두면 규칙보다 깊은 첫 트리에서 들여쓰기가 조용히 멈춥니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
-
-## 관련 컴포넌트
-
-- `CascadeSelect` (`cascade-select`)
-- `Listbox` (`listbox`)
-- `Accordion` (`accordion`)
-- `NavigationMenu` (`navigation-menu`)
-- `Toc` (`toc`)
-
-## 가져오기
-
-```tsx
-import { TreeView } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 15개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<TreeView.Root>
-  <TreeView.Label />
-  <TreeView.Tree>
-    <TreeView.Branch>
-      <TreeView.BranchContent>
-        <TreeView.BranchIndentGuide />
-      </TreeView.BranchContent>
-      <TreeView.BranchControl>
-        <TreeView.BranchIndicator />
-        <TreeView.BranchText />
-      </TreeView.BranchControl>
-      <TreeView.BranchTrigger />
-    </TreeView.Branch>
-    <TreeView.Item>
-      <TreeView.ItemIndicator />
-      <TreeView.ItemText />
-      <TreeView.NodeCheckbox />
-      <TreeView.NodeRenameInput />
-    </TreeView.Item>
-  </TreeView.Tree>
-</TreeView.Root>
-```
-
-- `TreeView.Root` — 최상위에 놓입니다
-- `TreeView.Branch` — `Tree` 안에 놓입니다
-- `TreeView.BranchContent` — `Branch` 안에 놓입니다
-- `TreeView.BranchControl` — `Branch` 안에 놓입니다
-- `TreeView.BranchIndentGuide` — `BranchContent` 안에 놓입니다
-- `TreeView.BranchIndicator` — `BranchControl` 안에 놓입니다
-- `TreeView.BranchText` — `BranchControl` 안에 놓입니다
-- `TreeView.BranchTrigger` — `Branch` 안에 놓입니다
-- `TreeView.Item` — `Tree` 안, 또는 `BranchContent` 안에 놓입니다
-- `TreeView.ItemIndicator` — `Item` 안에 놓입니다
-- `TreeView.ItemText` — `Item` 안에 놓입니다
-- `TreeView.Label` — `Root` 안에 놓입니다
-- `TreeView.NodeCheckbox` — `Item` 안에 놓입니다
-- `TreeView.NodeRenameInput` — `Item` 안에 놓입니다
-- `TreeView.Tree` — `Root` 안에 놓입니다
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 23개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-### 필수
-
-- `collection` — `SynapseTreeCollection<TNode>`, 필수. `createTreeCollection`으로 만든 트리. 윈도잉은 이것을 바꾸지 않습니다.
-
-### 선택
-
-- `value` — `readonly string[]`, 선택. 제어되는 선택입니다. 두 선택 모드 어느 쪽에서든 배열입니다. 하나짜리 선택도 여전히 선택이기 때문입니다. `selectionMode`에 따라 타입이 달라지는 prop은 어떤 사용처도 타입을 맞춰 쓸 수 없는 prop입니다.
-- `defaultValue` — `readonly string[]`, 선택. 비제어 모드의 초기 선택. `value`를 주면 무시됩니다.
-- `onValueChange` — `(details: TreeViewValueChangeDetails) => void`, 선택. 제어 여부와 무관하게 선택이 바뀔 때마다 호출됩니다.
-- `open` — `readonly string[]`, 선택. 펼쳐진 가지들이며 제어 모드입니다.
-- `defaultOpen` — `readonly string[]`, 선택. 비제어 모드의 초기 펼침 상태. `open`을 주면 무시됩니다.
-- `onOpenChange` — `(details: TreeViewOpenChangeDetails) => void`, 선택. 가지가 펼쳐지거나 접힐 때마다 호출됩니다.
-- `checkedValue` — `readonly string[]`, 선택. 체크된 노드들이며 제어 모드입니다. `NodeCheckbox` part를 움직입니다.
-- `defaultCheckedValue` — `readonly string[]`, 선택. 비제어 모드의 초기 체크 집합. `checkedValue`를 주면 무시됩니다.
-- `onCheckedValueChange` — `(details: TreeViewCheckedValueChangeDetails) => void`, 선택. 노드가 체크되거나 풀릴 때마다 호출됩니다. 가지의 3상태로 바뀌는 경우도 포함합니다.
-- `focusedValue` — `string | null`, 선택. 제어되는 포커스 노드. 로빙 tabindex가 올라가 있는 대상입니다.
-- `defaultFocusedValue` — `string | null`, 선택. 비제어 모드에서 처음 포커스되는 노드. 기본값은 처음 보이는 노드입니다.
-- `onFocusChange` — `(details: TreeViewFocusChangeDetails) => void`, 선택. 포커스가 옮겨 갈 때 호출됩니다. 한 번도 렌더된 적 없는 노드로 갈 때도 포함합니다.
-- `selectionMode` — `TreeViewSelectionMode`, 선택. 몇 개의 노드까지 선택할 수 있는지. 기본값은 `single`입니다.
-- `expandOnClick` — `boolean`, 선택. 가지의 컨트롤을 클릭하면 선택과 함께 펼치기도 합니다. 기본값은 true입니다.
-- `typeahead` — `boolean`, 선택. 몇 글자를 입력해 해당 노드로 건너뜁니다. 기본값은 true입니다.
-- `canRename` — `(node: TNode, indexPath: readonly number[]) => boolean`, 선택. 노드의 이름을 제자리에서 바꿀 수 있는지 정하며, 이것이 `NodeRenameInput`에 닿을 수 있게 해 주는 조건입니다. 이 값이 없으면 machine은 F2를 아예 무시하므로, 이름 바꾸기 입력은 렌더되고도 영영 감춰진 채로 있습니다. 불리언이 아니라 술어인 이유는 "어느 노드인가"가 제품이 답할 몫이기 때문입니다. 파일 트리는 파일의 이름은 바꾸되 그 위의 읽기 전용 폴더는 바꾸지 않습니다.
-- `onRenameStart` — `(details: TreeViewRenameDetails) => void`, 선택. 이름 바꾸기가 시작될 때 호출됩니다. 제품이 무엇을 고치는 중인지 기록할 수 있게 합니다.
-- `onBeforeRename` — `(details: TreeViewRenameCompleteDetails) => boolean`, 선택. 새 레이블을 거절하려면 false를 반환합니다. 이름 중복이나 허용되지 않는 문자 같은 경우입니다.
-- `onRenameComplete` — `(details: TreeViewRenameCompleteDetails) => void`, 선택. 이름 바꾸기가 받아들여졌을 때 호출됩니다. 컬렉션을 갱신하는 것은 사용처의 몫입니다.
-- `translations` — `TranslationOverrides`, 선택. 이 TreeView에만 적용되는 접근성 문자열로, provider의 값보다 우선합니다.
-- `size` — `Size`, 선택. 하나뿐인 공용 척도를 따릅니다. 모든 컴포넌트와 마찬가지로 기본값은 `md`입니다.
-- `id` — `string`, 선택. 팩토리가 만드는 식별자를 덮어씁니다. 서버와 클라이언트에서 같은 값으로 유지됩니다.
-
-## Variants
-
-- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. 크기 축은 각 행의 최소 높이와 글자 스타일, 펼침·선택 아이콘, 노드 체크박스, 이름 변경 필드를 정합니다. 들여쓰기는 정하지 않습니다. 단계별 들여쓰기는 machine이 각 행에 기록하는 깊이로부터 계산됩니다. 트리는 자신이 얼마나 깊어질지 모르고, 다섯 단계 척도는 범위가 사용처의 데이터에 달린 질문에 답할 수 없기 때문입니다.
-
-## 폼
-
-폼 참여: 아니요.
-
-> machine은 `name`, `form`, `required`, `invalid`를 받지 않고 숨겨진 요소도 없습니다. 트리의 선택이나 체크된 집합이 폼에 필요한 제품은 `onValueChange`나 `onCheckedValueChange`를 읽어 자체 필드를 작성합니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `empty-state` — TreeView는 넘겨받은 컬렉션을 보여 줄 뿐 스스로 아무것도 좁히지 않으므로, 사용자가 작업하는 도중에 비어 있는 상태로 바뀌는 일이 없습니다 — 사용자가 입력할수록 컬렉션이 줄어들어 비어 있음 자체가 새 소식이 되는 Combobox와 다릅니다. 노드가 없는 트리는 주변 뷰가 대신 채우는 빈 페이지 영역이며, 자식이 없는 접힌 브랜치는 빈 트리가 아니라 브랜치입니다.
-- `loading-state` — 트리에서 로딩은 컴포넌트 단위가 아니라 브랜치 단위이며, machine이 이미 그것이 일어나는 곳에서 알립니다. 펼쳐지는 브랜치는 브랜치, 컨트롤, 텍스트, 인디케이터에 `aria-busy`와 `data-loading`을 가집니다. 컴포넌트 수준의 영역은 노드 하나에 관한 요청을 트리 전체의 상태로 설명하게 되며, 이는 마크업에 이미 있는 답보다 못합니다.
-- `error-state` — 이 컴포넌트가 소유하면서 실패할 수 있는 작업이 없습니다. 요청을 수행하지 않고 `invalid` prop도 받지 않습니다 — 트리는 폼 컨트롤이 아니라 탐색·선택 표면입니다 — 그리고 자식을 불러오지 못한 브랜치는 사용처의 요청이 실패한 것이므로, 요청을 시작한 쪽이 트리 옆에서 알립니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 트리는 aria-labelledby를 통해 Label part로 이름이 붙고, 없으면 provider의 `treeView.tree.label`로 대체됩니다. 모든 행은 자신의 텍스트로 이름이 붙습니다. machine이 하드코딩하는 두 문자열은 제품이 바꿀 수 없는 영어로 출시되는 대신 provider의 번역 세트로 연결되며, Synapse는 모든 컴포넌트에 이를 요구합니다. BranchTrigger에는 이름이 필요 없습니다. 그것이 속한 행이 이미 키보드로 펼쳐지므로 보조 기술에서 숨겨지기 때문입니다.
-
-### 포커스
-
-> aria-activedescendant가 아니라 로빙 tabindex입니다. 정확히 하나의 행만 탭 가능하며, machine은 다음 행의 요소를 id로 찾아 실제 DOM 포커스를 그곳으로 옮깁니다. 이 때문에 윈도우 고정이 스크린 리더 사용자뿐 아니라 모든 사용자에게 핵심 역할을 합니다 — 렌더링된 적 없는 요소를 겨냥한 포커스 호출은 아무 일도 하지 않고 아무것도 알리지 않습니다. 브랜치에서 포커스 가능한 요소는 브랜치 자체가 아니라 BranchControl입니다. machine이 노드의 id, tabindex, 키보드 핸들러의 대상을 컨트롤에 주기 때문입니다.
-
-### 알려 주는 위치
-
-> aria-posinset과 aria-setsize는 형제 기준이고 — 브랜치 안에서 "item 2 of 3" — aria-level은 깊이이며, 스크린 리더가 트리에서 읽어 주는 것이 바로 이것입니다. 이 값들은 컬렉션의 `positionOf`에서 오는데, 이 함수는 펼침 상태를 볼 수 없으므로 보이는 노드 수를 실수로 알릴 수도 없습니다. 컬렉션 전체나 윈도우 안에서의 위치를 알리면, 올바르게 보이는 마크업이 존재하지 않는 구조를 설명하게 됩니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 예. 팩토리가 provider의 `dir`을 machine에 전달하고, machine은 이를 root, tree, 모든 행에 내보내며, 들여쓰기는 `paddingInlineStart`이므로 오른쪽에서 왼쪽으로 쓰는 트리는 오른쪽에서부터 들여씁니다. machine은 화살표 키를 방향과 함께 `getEventKey`로 읽으므로, ArrowLeft는 접고 ArrowRight는 펼치는 동작이 항상 같은 쪽을 가리키지 않고 읽는 방향을 따릅니다. 타입어헤드는 사용처가 제공하는 노드 레이블, 즉 로케일의 레이블과 매칭됩니다. machine이 그렇지 않으면 하드코딩했을 두 문자열 — 트리 자체의 `aria-label`과 이름 변경 필드의 레이블 — 은 `treeView.tree.label`과 `treeView.nodeRenameInput.label`에 매핑되므로, 제품은 provider별로 또는 TreeView별로 둘 중 어느 것이든 재정의할 수 있습니다.
-- 컬렉션 윈도잉: 예. 사용처가 children을 주지 않으면 `Tree`는 평탄화된 보이는 순서 위에서 `resolveWindow`의 행을 렌더링합니다. 올바른 동작은 결코 사용처가 선택해야 켜지는 것이 아닙니다. 행은 `aria-level`을 가진 평탄한 구조입니다. 윈도우는 보통 조상이 렌더링되지 않은 조각을 렌더링하는데, 중첩된 `role="group"` 마크업은 그 조상이 모두 있어야 하기 때문입니다. 알려지는 개수는 형제 기준이며 렌더링 루프가 아니라 컬렉션의 `positionOf`에서 옵니다. 키보드는 컬렉션 전체에 닿으며, 여기에는 메커니즘 하나가 아니라 두 개가 필요합니다. 이 machine은 aria-activedescendant로 가리키는 대신 실제 tabindex를 옮겨 다니기 때문입니다. 포커스된 노드는 DOM에 고정되며 범위 밖으로 벗어나면 잘려 보이지 않게 되므로, 로빙 포커스에는 항상 머물 요소가 있습니다. 그리고 machine은 그 요소 자체의 focus 이벤트에서만 `focusedValue`를 기록하므로, machine이 이제 막 도달하려는 노드 — Home, End, 타입어헤드 — 는 결코 고정될 수 없습니다. 렌더링되지 않았으니 포커스될 수 없고, 포커스되지 않으니 포커스를 보고하지도 않습니다. 업스트림의 `scrollToIndexFn`이 이 문제를 해결합니다. 윈도우에 보이는 인덱스를 넘기고 포커스 호출을 한 프레임 미루며, 윈도우는 그 프레임 동안 해당 인덱스를 포함하도록 범위를 옮깁니다. 범위는 커지는 것이 아니라 이동하므로, 십만 개 노드의 반대쪽 끝에 도달해도 여전히 윈도우 하나만 렌더링됩니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `hierarchy-display`, `choose-from-hierarchy`, `expand-collapse`, `windowed-collection`, `multi-select`, `extended-selection`, `tri-state-checkbox`, `edit-in-place`, `typeahead`, `translatable-strings`.
-- 다른 이름: `tree`, `tree view`, `file tree`, `folder tree`, `hierarchy`, `explorer`, `트리`, `트리 뷰`, `파일 트리`, `폴더 트리`, `계층 구조 목록`.
-- 어휘 상태: `controlled`.