@neurocle/synapse-react 0.0.0-stage → 0.3.0

package/skills/components/floating-panel/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: 'floating-panel'
+description: 'FloatingPanel — 사용자가 직접 위치를 정하는 창입니다. 끌어 옮기고, 크기를 바꾸고, 최소화할 수 있으며, 페이지 위를 덮지 않고 페이지 옆에 열려 있습니다. 포커스를 가두지 않고, 아무것도 inert(상호작용 불가) 상태로 만들지 않습니다. 다른 이름: floating panel, window, palette, inspector, tool window, floating dialog, 플로팅 패널, 떠 있는 패널, 창, 팔레트, 인스펙터, 도구 창.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/floating-panel.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/floating-panel.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# FloatingPanel
+
+> 사용자가 직접 위치를 정하는 창입니다. 끌어 옮기고, 크기를 바꾸고, 최소화할 수 있으며, 페이지 위를 덮지 않고 페이지 옆에 열려 있습니다. 포커스를 가두지 않고, 아무것도 inert(상호작용 불가) 상태로 만들지 않습니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `FloatingPanel`
+- 분류: `floating-and-overlay`
+- 수명 주기: `active`
+
+## 알려진 예외 — 사용 전에 확인
+
+이 컴포넌트는 아래 기준 2개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
+
+### WCAG 2.2 SC 2.1.1 키보드 (A)
+
+- 대상 part: `resizeTrigger`
+- 충족하지 못하는 것: 크기 조절 핸들은 포인터 전용이며 탭 순서에 없습니다. 키보드 사용자는 제품이 정한 크기와 최소화·최대화만 쓸 수 있습니다.
+- 의도한 이유: machine이 크기 조절에 키보드 경로를 제공하지 않으며, machine 밖에서 동작을 덧붙이지 않습니다.
+- 사용 시 유의점: 크기를 키워야만 보이는 콘텐츠를 두지 마세요. 기본 크기에서 모든 내용이 스크롤로 닿게 하고, 크기가 중요하면 최대화를 안내하세요.
+
+### Synapse 공유 레이어 스택 — 참여하지 않음
+
+- 충족하지 못하는 것: 자체 패널 스택을 유지하므로 `--layer-index`가 없고, 안쪽부터 닫히는 공유 순서에 참여하지 않습니다. 모달 Dialog 안에 열린 패널에서 Escape를 누르면 패널은 그대로 두고 Dialog가 닫힙니다.
+- 의도한 이유: `@zag-js/floating-panel`이 `@zag-js/dismissable`에 등록하지 않는 업스트림 구조입니다.
+- 사용 시 유의점: Dialog·Drawer 같은 모달 레이어 안에서 FloatingPanel을 열지 마세요. 패널에서 Escape를 누른 사용자는 패널이 아니라 뒤의 모달을 잃습니다.
+
+## Do
+
+> 사용자가 작업 옆에 두고 직접 배치하는 보조 보기에 쓰세요. 인스펙터, 속성 팔레트, 실시간 미리보기, 페이지 곳곳을 따라다니는 대화가 그렇습니다. 사용자가 패널과 페이지를 동시에 필요로 할 때, 패널이 놓일 자리가 레이아웃이 아니라 사용자가 정할 일일 때, 그리고 세션이 길어서 최소화와 복원이 버튼 두 개를 더 둘 가치가 있을 때 드래그와 크기 조절 핸들이 제값을 합니다.
+
+## Don't
+
+> 사용자가 반드시 응답해야 하는 것에는 쓰지 마세요. 포커스를 가두지 않고, 아무것도 inert(상호작용 불가) 상태로 만들지 않으며, 구석으로 끌려가 잊힌 채로 페이지가 그것 없이 계속 진행될 수 있습니다. 그런 경우는 Dialog입니다. 휴대폰에서도 쓰지 마세요. 사용자가 배치하는 창은 배치할 자리가 없고, 작은 화면에서 가장자리에 고정되는 답은 Drawer입니다. 크기 조절 핸들 뒤에 콘텐츠를 숨기지 마세요. 핸들은 포인터 전용이며 이 컴포넌트의 어떤 것도 키보드로 크기를 바꾸지 않습니다. 그리고 모달 Dialog 안에서 열면서 일반적인 닫힘 순서를 기대하지 마세요. 이 machine은 공유 레이어 스택에 없으므로 둘을 조율하는 것이 없고, Escape는 둘 중 하나를 고르지 않습니다.
+
+## Anti-patterns
+
+> Title 없이 렌더링하는 것. content의 aria-labelledby는 Title이 있든 없든 제목 id를 가리키므로, Title이 없는 패널은 대상 없는 참조를 지닌 이름 없는 대화상자로 안내되며, 여기에는 대신 쓸 `aria-label` prop도 없습니다. 두 번째 실수는 Positioner에 스타일을 주는 것입니다. machine이 위치, 크기, 쌓임 순서를 커스텀 속성으로 기록하므로, 레시피의 너비는 렌더링 때는 이기지만 사용자의 바로 다음 드래그에서 집니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `Dialog` (`dialog`)
+- `Drawer` (`drawer`)
+- `Popover` (`popover`)
+- `Splitter` (`splitter`)
+
+## 가져오기
+
+```tsx
+import { FloatingPanel } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 12개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<FloatingPanel.Root>
+  <FloatingPanel.Trigger />
+  <FloatingPanel.Positioner>
+    <FloatingPanel.Content>
+      <FloatingPanel.Header>
+        <FloatingPanel.DragTrigger>
+          <FloatingPanel.Title />
+        </FloatingPanel.DragTrigger>
+        <FloatingPanel.Control>
+          <FloatingPanel.StageTrigger />
+          <FloatingPanel.CloseTrigger />
+        </FloatingPanel.Control>
+      </FloatingPanel.Header>
+      <FloatingPanel.Body />
+      <FloatingPanel.ResizeTrigger />
+    </FloatingPanel.Content>
+  </FloatingPanel.Positioner>
+</FloatingPanel.Root>
+```
+
+- `FloatingPanel.Root`
+- `FloatingPanel.Trigger` — 최상위에 놓입니다
+- `FloatingPanel.Positioner` — 최상위에 놓입니다
+- `FloatingPanel.Content` — `Positioner` 안에 놓입니다
+- `FloatingPanel.Header` — `Content` 안에 놓입니다
+- `FloatingPanel.Body` — `Content` 안에 놓입니다
+- `FloatingPanel.Title` — `DragTrigger` 안, 또는 `Header` 안에 놓입니다
+- `FloatingPanel.ResizeTrigger` — `Content` 안에 놓입니다
+- `FloatingPanel.DragTrigger` — `Header` 안에 놓입니다
+- `FloatingPanel.StageTrigger` — `Control` 안에 놓입니다
+- `FloatingPanel.CloseTrigger` — `Control` 안, 또는 `Content` 안에 놓입니다
+- `FloatingPanel.Control` — `Header` 안에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 26개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `open` — `boolean`, 선택. 제어되는 열림 상태.
+- `defaultOpen` — `boolean`, 선택. 비제어 초기 열림 상태. `open`이 주어지면 무시됩니다.
+- `onOpenChange` — `(details: OpenChangeDetails) => void`, 선택. 제어 여부와 무관하게 패널이 열리거나 닫힐 때마다 알림을 받습니다.
+- `position` — `FloatingPanelPosition`, 선택. 제어되는 위치이며, 단위는 픽셀입니다.
+- `defaultPosition` — `FloatingPanelPosition`, 선택. 비제어 초기 위치. `position`이 주어지면 무시됩니다.
+- `onPositionChange` — `(details: FloatingPanelPositionChangeDetails) => void`, 선택. 패널이 드래그되는 동안 알림을 받습니다.
+- `onPositionChangeEnd` — `(details: FloatingPanelPositionChangeDetails) => void`, 선택. 드래그가 끝날 때 한 번 알림을 받습니다.
+- `dimensions` — `FloatingPanelDimensions`, 선택. 제어되는 너비와 높이이며, 단위는 픽셀입니다. Synapse에서 `size`는 공유 크기 척도를 뜻하므로, machine의 `size`를 `dimensions`라는 이름으로 받습니다.
+- `defaultDimensions` — `FloatingPanelDimensions`, 선택. 비제어 초기 너비와 높이. `dimensions`가 주어지면 무시됩니다.
+- `onDimensionsChange` — `(details: FloatingPanelDimensionsChangeDetails) => void`, 선택. 패널의 크기가 조절되는 동안 알림을 받습니다.
+- `onDimensionsChangeEnd` — `(details: FloatingPanelDimensionsChangeDetails) => void`, 선택. 크기 조절이 끝날 때 한 번 알림을 받습니다.
+- `minDimensions` — `FloatingPanelDimensions`, 선택. 패널을 줄일 수 있는 최소 크기.
+- `maxDimensions` — `FloatingPanelDimensions`, 선택. 패널을 키울 수 있는 최대 크기.
+- `onStageChange` — `(details: FloatingPanelStageChangeDetails) => void`, 선택. 패널이 최소화, 최대화되거나 원래대로 돌아올 때 알림을 받습니다.
+- `draggable` — `boolean`, 선택. 패널을 드래그할 수 있는지 여부. 기본값은 true입니다.
+- `resizable` — `boolean`, 선택. 패널의 크기를 조절할 수 있는지 여부. 기본값은 true입니다.
+- `lockAspectRatio` — `boolean`, 선택. 크기를 조절하는 동안 종횡비를 유지합니다.
+- `gridSize` — `number`, 선택. 드래그와 크기 조절을 픽셀 격자에 맞춥니다.
+- `allowOverflow` — `boolean`, 선택. 패널을 경계 밖으로 드래그할 수 있게 합니다. 기본값은 false입니다.
+- `persistRect` — `boolean`, 선택. 닫혀도 위치와 크기를 기억합니다.
+- `disabled` — `boolean`, 선택. 비활성화된 패널은 드래그되지도 크기가 조절되지도 않습니다.
+- `closeOnEscape` — `boolean`, 선택. Escape를 누르면 닫힙니다. 기본값은 false로, 넘기지 않으면 Escape로 닫히지 않습니다.
+- `restoreFocus` — `boolean`, 선택. 닫힐 때 포커스를 trigger로 되돌립니다. 기본값은 true입니다.
+- `translations` — `TranslationOverrides`, 선택. 이 FloatingPanel에만 적용되는 접근성 문자열이며, provider의 것보다 우선합니다.
+- `size` — `Size`, 선택. 하나의 공유 척도에서 옵니다. 패널의 너비와 높이가 아니라 header와 body의 여백, 글자 크기를 정합니다. 픽셀 크기는 `dimensions`로 정합니다.
+- `id` — `string`, 선택. 팩토리가 생성하는 식별자를 덮어씁니다. 서버와 클라이언트에서 동일합니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. size 축은 패널의 크롬, 즉 trigger, 헤더의 패딩, 제목의 글자, 컨트롤 아이콘, 본문의 안쪽 여백을 조절합니다. 패널의 너비와 높이는 일부러 건드리지 않습니다. 그것은 사용자가 끌어서 정하는 값인 `dimensions`이며, 이에 대한 의견을 가진 레시피는 렌더링 때는 이기고 다음 포인터 이동에서는 집니다.
+
+## 폼
+
+폼 참여: 아니요.
+
+> 폼에 제출하는 값이 없습니다. FloatingPanel 안의 폼은 사용처 자신의 `form` 요소이며 사용자적으로 폼에 참여합니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — Body는 제품이 넣는 것을 무엇이든 렌더링하며, 컬렉션과 달리 이 컴포넌트가 비어 있음을 감지할 데이터가 없습니다. 아무것도 없이 열린 패널도 사용자가 여전히 옮기고, 크기를 바꾸고, 닫을 수 있는 창이며, 이는 machine이 이미 설명하는 상태입니다.
+- `loading-state` — 아직 도착 중인 콘텐츠는 Body 안에서 제품 고유의 placeholder로 보여 줍니다. 여기에 part를 두는 것보다 그편이 낫습니다. 패널은 모달이 아니므로, 사용자가 이미 위치를 바꿀 수 있는 채워지는 중인 창이 막혀 있는 창보다 유용한 상태이고, placeholder의 모양은 그것이 대체할 콘텐츠에 속합니다.
+- `error-state` — 이 컴포넌트는 값을 보유하지 않고 스스로 어떤 작업도 수행하지 않으므로, 실패할 수 있는 동작이 없습니다. 경계를 벗어나게 될 드래그나 크기 조절은 거부되지 않고 경계 안으로 제한되며, 이것이 machine의 답이므로 보고할 상태가 필요 없습니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> 패널은 aria-labelledby를 통해 Title에서 이름을 얻습니다. 이 참조는 무조건 기록되므로, Title이 없는 패널은 가리킬 대상이 없는 참조를 지닌 채 이름이 없으며, Dialog와 달리 대신 쓸 `aria-label` prop도 없습니다. 단계 전환 버튼은 provider의 번역에서 이름을 얻고 패널마다 덮어쓸 수 있습니다. 닫기 버튼의 이름은 provider의 `floatingPanel.closeTrigger.label`에서 옵니다. `getCloseTriggerProps`는 machine의 `IntlTranslations`에 없는 리터럴로 `aria-label="Close Window"`를 기록하므로, 컴포넌트가 이 속성이 요소에 닿기 전에 번역된 문자열로 고칩니다. 이 값은 동작 영역에 남으므로, 제품은 `translations`로 바꾸거나 `aria-labelledby`로 버튼에 이름을 줍니다.
+
+### 포커스
+
+> 패널이 열리면 포커스가 content 요소 자체로 옮겨지고(그래서 content가 `tabindex=0`입니다), 닫히면 trigger로 돌아오며, 둘 다 machine이 처리합니다. 포커스는 갇히지 않고 뒤쪽 페이지는 살아 있고 스크롤할 수 있습니다. 이것이 이 컴포넌트를 대화상자가 아니라 패널로 만드는 점이며, 레이어가 aria-modal이 아닌 이유입니다. 크기 조절에는 키보드 경로가 없습니다. 핸들은 포인터 전용이고 컴포넌트의 다른 어떤 것도 패널의 크기를 바꾸지 않으므로, 키보드 사용자는 제품이 정한 크기와 최소화·최대화가 제공하는 것만 얻습니다. 검증 불가: 이 패키지는 레이아웃 엔진이나 포인터 없이 렌더링하므로, 드래그, 크기 조절, 경계 제한, 포커스 이동은 업스트림에서 검증되며 이 테스트 모음 어디에서도 검증되지 않습니다.
+
+### 공유 레이어 스택에 오르지 않음
+
+> `@zag-js/floating-panel`은 `@zag-js/dismissable`에 등록하지 않고 자체 패널 스택을 유지하므로, 패널의 content에는 `--layer-index`가 없고 공유 쌓임 순서와 닫힘 순서는 이를 보지 못합니다. Escape는 `closeOnEscape`를 넘겼을 때만 자체 스택에서 맨 위인 패널이 content에서 직접 처리합니다. 모달 Dialog 안에 열린 패널에서 Escape를 누르면 패널은 그대로 두고 Dialog가 닫힙니다. `packages/react/tests/matrix/registration.test.tsx`는 이를 `layerStack.registers: false`와 그 이유로 선언된 예외로 다룹니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 예. 패널을 옮기는 화살표 키는 동작 라이브러리의 방향 인식 키 맵으로 읽히므로, 오른쪽에서 왼쪽으로 쓰는 provider에서는 ArrowLeft와 ArrowRight가 뒤바뀝니다. 반면 positioner는 패널의 x를 여전히 물리 속성 `left`로 기록합니다. 따라서 RTL 제품에서 ArrowLeft를 누르면 패널이 오른쪽으로 움직입니다. 방향은 모든 part에도 기록됩니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 구조 메모
+
+### 크기 대신 치수
+
+> machine은 패널의 너비와 높이를 `size`라고 부르지만, Synapse의 `size`는 모든 컴포넌트가 제공하는 공유 다섯 단계 척도입니다. 두 의미가 이름을 공유할 수 없고 척도는 양보할 수 없으므로, 패널의 픽셀 크기는 `dimensions` / `defaultDimensions` / `onDimensionsChange`(그리고 `minDimensions`, `maxDimensions`)로 공개되며, 바로 이런 목적으로 존재하는 이음매에서 machine의 이름으로 변환됩니다. `dimensions`는 한 컴포넌트의 지역적 표기가 아니라 중앙 등록을 위해 보고된 어휘 추가입니다. 끌어서 크기를 바꾸는 이후의 모든 컴포넌트는 같은 단어를 써야 합니다.
+
+### 공유 레이어 스택에 오르지 않음
+
+> `@zag-js/floating-panel`은 `@zag-js/dismissable`에 등록하지 않고 자체 패널 스택을 유지하므로, 패널의 content에는 `--layer-index`가 없고 공유 쌓임 순서와 닫힘 순서는 이를 보지 못합니다. Escape는 자체 스택에서 맨 위일 때 content에서 직접 처리합니다. `packages/react/tests/matrix/registration.test.tsx`는 이를 예외가 아니라 실패하는 단언으로 기록하며, 덕분에 제품이 패널과 대화상자를 중첩해 보고 나서야 이를 발견하는 일이 없습니다.
+
+### 요소를 렌더링하지 않는 루트
+
+> machine에는 `root` anatomy part가 없으므로, FloatingPanel.Root는 동작 상태를 공개할 뿐 아무것도 렌더링하지 않습니다. trigger는 사용처가 작성한 자리에 머물고, 패널 자체는 사용자가 끄는 창을 잘라낼 수 있는 어떤 조상으로부터도 포털되어 빠져나갈 수 있습니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `persistent-panel`, `non-modal-layer`, `drag-to-move`, `drag-to-resize`, `minimize-maximize`, `translatable-strings`.
+- 다른 이름: `floating panel`, `window`, `palette`, `inspector`, `tool window`, `floating dialog`, `플로팅 패널`, `떠 있는 패널`, `창`, `팔레트`, `인스펙터`, `도구 창`.
+- 어휘 상태: `controlled`.

package/skills/components/hover-card/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: 'hover-card'
+description: 'HoverCard — 포인터가 링크 위에 머물면 나타나고 포인터가 그 안으로 옮겨 가는 동안 유지되는 미리보기입니다. 사용자가 이것 없이도 이미 닿을 수 있는 목적지를 보강하는 역할을 합니다. 다른 이름: hover card, preview card, link preview, profile card, peek, hovercard, 호버 카드, 미리보기 카드, 링크 미리보기, 프로필 카드, 마우스 오버 카드.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/hover-card.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/hover-card.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# HoverCard
+
+> 포인터가 링크 위에 머물면 나타나고 포인터가 그 안으로 옮겨 가는 동안 유지되는 미리보기입니다. 사용자가 이것 없이도 이미 닿을 수 있는 목적지를 보강하는 역할을 합니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `HoverCard`
+- 분류: `floating-and-overlay`
+- 수명 주기: `active`
+
+## 알려진 예외 — 사용 전에 확인
+
+이 컴포넌트는 아래 기준 2개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
+
+### WCAG 2.2 SC 2.1.1 키보드 (A)
+
+- 충족하지 못하는 것: 카드 안으로 포커스가 들어가는 경로가 없고, trigger에서 포커스가 벗어나면 카드가 닫힙니다. 카드 안의 링크·버튼은 키보드로 닿을 수 없습니다.
+- 의도한 이유: HoverCard는 미리보기 전용이라는 machine의 설계입니다. 조작할 콘텐츠는 Popover가 맡습니다.
+- 사용 시 유의점: 카드 안에 링크·버튼 같은 조작 요소를 두지 마세요. 필요하면 Popover를 쓰세요.
+
+### WCAG 2.2 SC 1.4.13 hover 또는 포커스 시 콘텐츠 (AA)
+
+- 충족하지 못하는 것: 탭(터치)으로는 열리지 않으며, 접근성 트리에서 trigger와 카드를 잇는 관계(`aria-describedby`, `aria-expanded`, `aria-controls`)가 없습니다. 스크린 리더와 터치 사용자는 카드를 만나지 못합니다.
+- 의도한 이유: trigger가 `a`인 이유는 탭하면 이동하게 하기 위해서이며, 카드는 링크 대상의 미리보기일 뿐입니다.
+- 사용 시 유의점: 카드가 어떤 정보의 유일한 사본이 되지 않게 하세요. 같은 내용은 링크 대상 페이지에도 있어야 합니다.
+
+## Do
+
+> 링크가 이미 이끄는 대상의 미리보기에 쓰세요. 어떤 사람이 누구인지, 문서에 무엇이 들어 있는지, 참조된 티켓이 무엇을 말하는지를 포인터가 링크 위에 머물 때 보여 주고, 포인터를 카드 안으로 옮겨 닿을 수 있게 합니다. 미리보기가 사용자가 되돌아와야 했을 이동을 덜어 줄 때, 그리고 그 안의 모든 것이 목적지에서도 제공될 때에만 제자리를 얻습니다. Arrow part는 위치만으로는 카드가 어느 trigger에서 열렸는지 알기 어려울 때만 넣으세요. 대개 카드는 trigger 바로 옆에 놓여 위치만으로 trigger와 이어지고, 그때 테두리와 그림자가 있는 표면에 화살표는 모서리 하나를 더할 뿐입니다.
+
+## Don't
+
+> 다른 어디에도 없는 것을 넣지 마세요. 터치로는 열리지 않고, 접근성 트리에서 trigger와 연결되지 않으며, 키보드 사용자는 탭으로 들어갈 수 없습니다. 그래서 마우스를 쓰지 않는 사람에게 그 콘텐츠는 세 가지 경로 모두에서 닿을 수 없습니다. 버튼이나 목적지가 아닌 것을 감싸지 마세요. 그러면 hover를 대신하는 탭이 갈 곳이 없어지고, 패턴은 자신을 정당화하던 경로를 잃습니다. 컨트롤을 설명하는 문구에는 쓰지 마세요. 그것은 Tooltip이며, 적어도 둘 사이에 `aria-describedby`를 연결합니다. 그리고 컨트롤을 넣지 마세요. trigger가 포커스를 잃자마자 카드가 닫히므로, 안의 버튼은 클릭만 할 수 있을 뿐 결코 포커스로 닿을 수 없습니다.
+
+## Anti-patterns
+
+> 카드를 미리보기가 아니라 콘텐츠로 다루는 것. 머무는 포인터를 뺀 모든 경로는 카드가 아니라 목적지에 닿고, 컴포넌트는 보조 기술에 카드의 존재를 전혀 알리지 않습니다. 그래서 hover할 때만 나타나는 세부 정보는 대부분의 사용자가 거기 있다는 것조차 알지 못하는 정보가 되며, 카드 자체에 대한 어떤 테스트도 그 사실을 드러내지 못합니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `Tooltip` (`tooltip`)
+- `Popover` (`popover`)
+- `Dialog` (`dialog`)
+- `Avatar` (`avatar`)
+
+## 가져오기
+
+```tsx
+import { HoverCard } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 6개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<HoverCard.Root>
+  <HoverCard.Trigger />
+  <HoverCard.Positioner>
+    <HoverCard.Content>
+      <HoverCard.Arrow>
+        <HoverCard.ArrowTip />
+      </HoverCard.Arrow>
+    </HoverCard.Content>
+  </HoverCard.Positioner>
+</HoverCard.Root>
+```
+
+- `HoverCard.Root`
+- `HoverCard.Arrow` — `Content` 안에 놓입니다
+- `HoverCard.ArrowTip` — `Arrow` 안에 놓입니다
+- `HoverCard.Trigger` — 최상위에 놓입니다
+- `HoverCard.Positioner` — 최상위에 놓입니다
+- `HoverCard.Content` — `Positioner` 안에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 12개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `open` — `boolean`, 선택. 제어되는 열림 상태.
+- `defaultOpen` — `boolean`, 선택. 비제어 초기 열림 상태. `open`이 주어지면 무시됩니다.
+- `onOpenChange` — `(details: OpenChangeDetails) => void`, 선택. 제어 여부와 무관하게 카드가 열리거나 닫힐 때마다 알림을 받습니다.
+- `triggerValue` — `string | null`, 선택. 여러 trigger 가운데 지금 카드를 소유한 trigger. HoverCard 하나가 링크 목록 전체를 담당할 수 있습니다: 각 `HoverCard.Trigger`가 `value`를 받고, 콘텐츠는 그중 이 값에 해당하는 trigger를 기준으로 배치됩니다. trigger가 하나뿐인 카드에는 이 prop이 전혀 필요 없습니다.
+- `defaultTriggerValue` — `string | null`, 선택. 비제어 초기 소유 trigger.
+- `onTriggerValueChange` — `(details: HoverCardTriggerValueChangeDetails) => void`, 선택. 소유 trigger가 바뀔 때 알림을 받습니다.
+- `positioning` — `HoverCardPositioning`, 선택. 떠 있는 레이어가 놓이는 위치.
+- `openDelay` — `number`, 선택. 열리기까지 포인터가 trigger 위에 머물러야 하는 밀리초. 기본값은 700입니다.
+- `closeDelay` — `number`, 선택. 포인터가 떠난 뒤 닫히기까지의 밀리초. 기본값은 300입니다.
+- `disabled` — `boolean`, 선택. 비활성화된 HoverCard는 열리지 않습니다.
+- `size` — `Size`, 선택. 하나의 공유 척도에서 옵니다. 모든 컴포넌트가 그렇듯 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 생성하는 식별자를 덮어씁니다. 서버와 클라이언트에서 동일합니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. size 축은 trigger의 글자와 최소 높이, 카드의 패딩과 글자, 화살표의 크기를 조절합니다. 카드의 너비는 정하지 않습니다. content는 모든 크기에서 `surface.overlayMax`에서 멈추는데, 미리보기의 너비는 척도의 한 단계가 아니라 미리보기 자체의 너비이기 때문입니다.
+
+## 폼
+
+폼 참여: 아니요.
+
+> 폼에 제출하는 값이 없습니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 카드는 제품이 넣은 미리보기를 보여 줄 뿐 컬렉션을 소유하지 않습니다. 미리 보여 줄 것이 없는 링크는 애초에 HoverCard로 감싸지 마세요. 그 판단은 이 컴포넌트에 닿기 전에 내려집니다. hover하면 열리는 빈 카드는 카드가 없는 것보다 나쁩니다. 아무 말도 하지 않으면서 읽기를 방해하기 때문입니다.
+- `loading-state` — 포인터가 도착할 때 가져오는 미리보기가 일반적인 경우이며, 제품 고유의 placeholder는 Content 안에서 앞으로 될 미리보기의 모양을 취할 수 있습니다. 여기에 part를 두면 열림 지연 뒤에 번쩍 나타났다가 교체되는데, 이는 그냥 채워지는 카드보다 읽기에 나쁩니다.
+- `error-state` — 이 컴포넌트는 아무것도 가져오지 않고 값을 보유하지 않으므로, 실패할 수 있는 작업이 없습니다. 불러오지 못한 미리보기는 제품이 처리할 일이며, 정직한 처리는 대개 카드를 보여 주지 않는 것입니다. 링크는 여전히 동작하고, 이 패턴이 기대는 경로는 처음부터 그것이었습니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> trigger의 이름은 제품이 작성한 링크 텍스트입니다. 카드 자체는 접근 가능한 이름이 없고 trigger에서 참조되지도 않는데, machine이 어느 방향으로도 연결을 내보내지 않기 때문입니다. 이 컴포넌트의 어떤 문자열도 동작 라이브러리에서 오지 않습니다. `@zag-js/hover-card`는 `translations`를 받지 않고 아무것도 하드코딩하지 않으므로, 여기에는 제품이 바꿀 수 없는 것이 없습니다.
+
+### 포커스
+
+> 포커스는 결코 카드 안으로 옮겨지지 않습니다. content는 `tabindex=-1`이고, 컴포넌트의 어떤 것도 그곳으로 포커스를 옮기지 않으며, machine은 포인터가 카드 안에 없을 때 trigger의 blur에서 카드를 닫습니다. 그래서 카드가 열려 있는 동안 content 안의 포커스 가능한 요소에는 키보드로 닿을 수 없습니다. 이 제약이 Hover Card를 패널이 아니라 미리보기로 만들며, 컨트롤이 대신 Popover에 있어야 하는 이유입니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 예. 배치는 논리적입니다. `bottom-start`는 provider의 방향에 맞춰 해석되므로, 같은 카드가 영어 인터페이스와 아랍어 인터페이스에서 링크의 서로 반대쪽에 놓입니다. 방향은 모든 part에도 기록됩니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 구조 메모
+
+### trigger와 카드 사이에 의미 연결이 없음
+
+> machine은 content에 역할을 두지 않고 trigger에 aria-describedby, aria-expanded, aria-controls를 두지 않으므로, 접근성 트리에서 둘을 잇는 것이 없습니다. 카드는 링크에 대한 시각적 보강이며, 이 항목은 이상적인 컴포넌트를 묘사하는 대신 그 사실을 밝힙니다. 카드의 콘텐츠는 결코 어떤 것의 유일한 사본이어서는 안 됩니다.
+
+### 요소를 렌더링하지 않는 루트
+
+> Hover Card machine에는 `root` anatomy part가 없으므로, HoverCard.Root는 동작 상태를 공개할 뿐 아무것도 렌더링하지 않습니다. trigger는 자신이 속한 문장 안에 인라인으로 머물고, Positioner와 Content는 그것을 잘라낼 조상으로부터 포털되어 빠져나갈 수 있습니다.
+
+### 링크인 trigger
+
+> `Trigger`는 `a`로 선언되며, 이 요소 선택은 스타일 취향이 아니라 바로 터치 경로입니다. machine은 `pointerType === 'touch'`일 때 `onPointerEnter`와 `onPointerLeave`에서 일찍 반환하므로 탭으로는 카드가 열리지 않습니다. 링크를 탭하면 카드가 미리 보여 주던 대상으로 이동하며, 이것이 hover로 동작하는 컴포넌트가 hover 포인터가 없는 사용자에게 제공해야 하는 대등한 경로입니다. 버튼 trigger라면 터치 경로가 아예 없습니다. machine은 탭을 무시하고 버튼은 어디로도 가지 않습니다. 검증 불가: 이 패키지의 테스트 환경에는 터치 포인터가 없으므로, 탭 경로는 테스트 모음이 실행하는 것이 아니라 machine 소스에 대한 추론입니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `hover-preview`, `hover-disclosure`, `progressive-disclosure`, `non-modal-layer`, `floating-layer`, `translatable-strings`.
+- 다른 이름: `hover card`, `preview card`, `link preview`, `profile card`, `peek`, `hovercard`, `호버 카드`, `미리보기 카드`, `링크 미리보기`, `프로필 카드`, `마우스 오버 카드`.
+- 어휘 상태: `controlled`.

package/skills/components/image-cropper/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: 'image-cropper'
+description: 'ImageCropper — 이미지 위의 자르기 사각형으로, 포인터, 핀치, 키보드로 옮기고 크기를 바꾸며, 선택적으로 비율 고정, 확대/축소, 회전, 좌우 반전을 제공합니다. 이 컴포넌트를 둘 가치는 키보드 경로에 있습니다. 선택 영역은 machine이 화살표 키로 조작하고 움직일 때마다 안내하는 슬라이더인데, 드래그 핸들러만으로 만든 자르기 도구는 이렇게 할 수 없습니다. 다른 이름: image cropper, crop tool, photo crop, avatar editor, image editor, crop box, 이미지 크로퍼, 이미지 자르기, 사진 자르기, 크롭 도구, 아바타 편집기.'
+metadata:
+  package: '@neurocle/synapse-react'
+  packageVersion: '0.3.0'
+  registryEntry: 'packages/registry/data/components/image-cropper.json'
+  registryStructuralVersion: '0.3.0'
+  lifecycle: 'active'
+  generator: 'packages/react/src/skills/generate.ts'
+---
+
+<!--
+생성된 파일 — 손으로 고치지 않습니다.
+
+Source:     packages/registry/data/components/image-cropper.json (항목 구조 0.3.0)
+Generator:  packages/react/src/skills/generate.ts
+Regenerate: npx nx run react:skills:generate
+
+아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
+재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
+대신 항목을 고칩니다.
+-->
+
+# ImageCropper
+
+> 이미지 위의 자르기 사각형으로, 포인터, 핀치, 키보드로 옮기고 크기를 바꾸며, 선택적으로 비율 고정, 확대/축소, 회전, 좌우 반전을 제공합니다. 이 컴포넌트를 둘 가치는 키보드 경로에 있습니다. 선택 영역은 machine이 화살표 키로 조작하고 움직일 때마다 안내하는 슬라이더인데, 드래그 핸들러만으로 만든 자르기 도구는 이렇게 할 수 없습니다.
+
+`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
+
+- 패키지: `@neurocle/synapse-react`
+- 내보내기: `ImageCropper`
+- 분류: `collection-data-entry`
+- 수명 주기: `active`
+
+## Do
+
+> 제품이 이미지 전체가 아니라 특정 영역을 필요로 할 때 쓰세요. 프로필 사진, 썸네일, 배너, 스캔한 문서가 그렇습니다. 결과물의 모양이 고정되어 있으면 `aspectRatio`를 설정해 레이아웃이 나중에 왜곡할 자르기 결과를 사용자가 만들지 못하게 하고, 틀은 제자리에 있고 그림이 그 안에서 움직여야 하는 아바타의 경우에는 `fixedCropArea`를 쓰세요. 저장 단계를 계획하기 전에 `formParticipation`을 읽어 보세요. 잘린 파일을 만드는 일은 현재로서는 여전히 `onCropChange`가 보고하는 사각형을 바탕으로 사용처가 직접 해야 합니다.
+
+## Don't
+
+> 대역폭을 위해 업로드된 파일의 크기를 줄이는 데 쓰지 마세요. 그것은 FileUpload의 `transformFiles`이며, 사용자에게 아무것도 요구하지 않고 실행됩니다. 범용 이미지 편집기로 쓰지 마세요. 여기에는 그리기도, 필터도, 레이어도 없으며, 할 수 없는 일로 가득한 툴바를 단 자르기 도구는 별도 편집기보다 못합니다. 자르기 영역을 계산할 수 있는 곳에도 쓰지 마세요. 고정된 정사각형 가운데 자르기에는 인터페이스가 전혀 필요 없습니다. 그리고 실제 상자를 줄 수 없을 때는 쓰지 마세요. 기하 정보를 viewport의 크기로 측정하므로, 높이가 0인 컨테이너 안의 자르기 도구는 아무도 보거나 확인할 수 없는 결과를 만듭니다.
+
+## Anti-patterns
+
+> 포인터 핸들러로 자르기를 만들고 Selection part를 건너뛰는 것. selection은 machine이 조작하는 `role="slider"`이며, aria-valuenow와 값 텍스트를 지니고, 화살표 키, Alt 크기 조절, 확대/축소가 동작하게 하는 바로 그 요소입니다. 스타일을 입힌 div로 렌더링한 자르기 사각형은 어떤 스크린샷에서도 똑같아 보이지만 마우스 없이는 전혀 쓸 수 없으며, 이 컴포넌트가 막으려고 존재하는 것이 바로 그 한 가지입니다.
+
+Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
+
+## 관련 컴포넌트
+
+- `FileUpload` (`file-upload`)
+- `Avatar` (`avatar`)
+- `Slider` (`slider`)
+- `SignaturePad` (`signature-pad`)
+
+## 가져오기
+
+```tsx
+import { ImageCropper } from '@neurocle/synapse-react'
+```
+
+## Anatomy
+
+React 네임스페이스가 노출하는 part 6개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
+
+```tsx
+<ImageCropper.Root>
+  <ImageCropper.Viewport>
+    <ImageCropper.Image />
+    <ImageCropper.Selection>
+      <ImageCropper.Handle />
+      <ImageCropper.Grid />
+    </ImageCropper.Selection>
+  </ImageCropper.Viewport>
+</ImageCropper.Root>
+```
+
+- `ImageCropper.Root` — 최상위에 놓입니다
+- `ImageCropper.Viewport` — `Root` 안에 놓입니다
+- `ImageCropper.Image` — `Viewport` 안에 놓입니다
+- `ImageCropper.Selection` — `Viewport` 안에 놓입니다
+- `ImageCropper.Handle` — `Selection` 안에 놓입니다
+- `ImageCropper.Grid` — `Selection` 안에 놓입니다
+
+## Props
+
+빌드가 방출하는 선언에서 도출한 prop 28개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
+
+모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
+
+### 선택
+
+- `initialCrop` — `ImageCropperRect`, 선택. 시작할 잘라내기 사각형. 기본값은 종횡비가 허용하는 가장 큰 사각형입니다.
+- `onCropChange` — `(details: ImageCropperCropChangeDetails) => void`, 선택. 잘라내기 영역이 움직이거나 크기가 바뀔 때 알림을 받습니다.
+- `aspectRatio` — `number`, 선택. 잘라내기 영역의 비율을 고정합니다 — 정사각형은 1, 영상은 16 / 9입니다.
+- `cropShape` — `ImageCropperShape`, 선택. 잘라내기 영역의 윤곽. 기본값은 `rect`입니다.
+- `fixedCropArea` — `boolean`, 선택. 잘라내기 영역을 고정하고, 그 아래의 이미지만 옮기고 확대·축소할 수 있게 둡니다.
+- `minWidth` — `number`, 선택. 잘라내기 영역의 최소 크기이며, 단위는 픽셀입니다.
+- `minHeight` — `number`, 선택. 잘라내기 영역의 최소 크기이며, 단위는 픽셀입니다.
+- `maxWidth` — `number`, 선택. 잘라내기 영역의 최대 크기이며, 단위는 픽셀입니다.
+- `maxHeight` — `number`, 선택. 잘라내기 영역의 최대 크기이며, 단위는 픽셀입니다.
+- `zoom` — `number`, 선택. 제어되는 확대 배율이며, 1이 이미지의 본래 크기입니다.
+- `defaultZoom` — `number`, 선택. 비제어 초기 확대 배율. `zoom`이 주어지면 무시됩니다.
+- `onZoomChange` — `(details: ImageCropperZoomChangeDetails) => void`, 선택. 확대 배율이 바뀔 때 알림을 받습니다.
+- `minZoom` — `number`, 선택. 허용되는 최소 확대 배율.
+- `maxZoom` — `number`, 선택. 허용되는 최대 확대 배율.
+- `zoomStep` — `number`, 선택. 확대 한 단계가 움직이는 폭.
+- `zoomSensitivity` — `number`, 선택. 휠이나 핀치 제스처가 얼마나 확대·축소하는지.
+- `rotation` — `number`, 선택. 제어되는 회전이며, 단위는 도입니다.
+- `defaultRotation` — `number`, 선택. 비제어 초기 회전.
+- `onRotationChange` — `(details: ImageCropperRotationChangeDetails) => void`, 선택. 회전이 바뀔 때 알림을 받습니다.
+- `flip` — `{ readonly horizontal: boolean; readonly vertical: boolean; }`, 선택. 제어되는 좌우/상하 반전.
+- `defaultFlip` — `{ readonly horizontal: boolean; readonly vertical: boolean; }`, 선택. 비제어 초기 반전.
+- `onFlipChange` — `(details: ImageCropperFlipChangeDetails) => void`, 선택. 반전이 바뀔 때 알림을 받습니다.
+- `nudgeStep` — `number`, 선택. 화살표 키 한 번이 잘라내기 영역을 옮기는 거리이며, 단위는 픽셀입니다.
+- `nudgeStepShift` — `number`, 선택. Shift-화살표가 잘라내기 영역을 옮기는 거리.
+- `nudgeStepCtrl` — `number`, 선택. Ctrl-화살표가 잘라내기 영역을 옮기는 거리.
+- `translations` — `TranslationOverrides`, 선택. 이 ImageCropper에만 적용되는 접근성 문자열이며, provider의 것보다 우선합니다.
+- `size` — `Size`, 선택. 하나의 공유 척도에서 옵니다. 모든 컴포넌트가 그렇듯 기본값은 `md`입니다.
+- `id` — `string`, 선택. 팩토리가 생성하는 식별자를 덮어씁니다. 서버와 클라이언트에서 동일합니다.
+
+## Variants
+
+- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. size 축은 크기 조절 그립 여덟 개의 크기를 정하고 root에 최소 높이를 줍니다. 이미지나 자르기 영역은 일부러 조절하지 않습니다. 자르기 도구의 크기는 레이아웃이 주는 상자에서 오고, 자르기 사각형은 `minWidth`/`maxWidth`를 통해 이미지 픽셀 단위로 측정되므로, 티셔츠 사이즈식 단계와는 정직하게 대응시킬 방법이 없습니다.
+
+## 폼
+
+폼 참여: 아니요.
+
+> 제출할 값이 없습니다. 자르기의 결과는 폼이 실어 나르는 문자열이 아니라 Blob이나 data URL입니다. 결과는 명령인 `getCroppedImage()`로 만들어지며, 명령에 대한 Synapse의 답은 타입이 지정된 컨트롤러를 반환하는 훅입니다. `useImageCropper()`가 그 훅이며 세 가지 동작을 노출합니다. 잘린 픽셀, 서버 쪽에서 자르는 제품을 위한 이미지 자체 픽셀 단위의 자르기 기하 정보, 그리고 초기화입니다. 제품은 자신의 저장 핸들러에서 이를 호출하고 결과를 자신의 필드에 넣어 자르기를 저장하며, 이는 폼이 담을 수 없는 값을 다루는 일반적인 방식입니다.
+
+## 이 컴포넌트에 일부러 없는 것
+
+- `empty-state` — 이미지가 없으면 자를 것이 없으므로, 이미지가 없는 제품은 자르기 도구를 렌더링하지 않습니다. 아직 존재하지 않는 값을 다루는 모든 컨트롤과 마찬가지로 그 판단은 이 컴포넌트에 닿기 전에 내려집니다. 빈 자르기 사각형은 사용자에게 보여 줄 의미가 있는 것이 아닙니다.
+- `loading-state` — machine이 이미 이를 보고하며, 별도 영역보다 더 잘합니다. 이미지가 로드되지 않은 동안 root는 `aria-busy`를 지니고, `aria-description`은 자르기 설명 대신 machine의 `previewLoading` 문자열이 되며, Image part는 그 위에 스켈레톤을 꾸밀 수 있도록 `data-ready`를 지닙니다. `loading` part를 두면 root의 라이브 영역이 이미 알리고 있는 사실을 두 번 안내하게 됩니다.
+- `error-state` — 이 컴포넌트는 요청을 수행하지 않습니다. 제품이 이미 제공한 이미지를 자를 뿐이므로, 로드에 실패한 이미지는 제품의 가져오기가 실패한 것이며 그 가져오기를 처리하는 곳에 속합니다. 실패할 수 있는 유일한 작업인 `getCroppedImage()`는 제품이 `useImageCropper()`를 통해 자신의 핸들러에서 호출하는 명령입니다. 그래서 실패는 자르기가 무엇을 위한 것인지 모르는 컴포넌트 안이 아니라, 호출이 일어난 곳에서 제품 고유의 문구로 드러납니다.
+
+## 접근성
+
+### 접근 가능한 이름
+
+> provider의 `imageCropper.root.label`에서 이름을 얻고, `imageCropper.root.roleDescription`이 스크린 리더에 이것이 어떤 종류인지 알립니다. 함수 값인 문자열 세 개, 곧 `previewDescription`, `selectionLabel`, 그리고 화살표 키를 누를 때마다 읽히는 `selectionValueText`는 함수 값 `machineTranslations`를 거쳐 `imageCropper.root.description`과 `imageCropper.selection.*`로 연결되므로, machine의 영어는 어떤 것도 스크린 리더에 닿지 않습니다.
+
+### 포커스
+
+> 포커스는 유일한 탭 정지 지점인 Selection에 놓이며, 이동, 크기 조절, 확대/축소 내내 그대로 머무릅니다. 여기서는 어떤 것도 스스로 포커스를 옮기지 않으며, 핸들은 일부러 포커스를 받지 않습니다. 사각형 하나를 둘러싼 탭 정지 지점 여덟 개는 거의 같은 것을 안내하는 슬라이더 여덟 개가 될 것이고, selection에서의 Alt+화살표가 한 곳에서 같은 일을 합니다.
+
+## 로케일과 컬렉션
+
+- 로케일 의존: 예. machine은 키 입력을 해석할 때 provider의 텍스트 방향을 읽으므로, ArrowLeft와 ArrowRight는 항상 x가 작아지는 쪽이 아니라 읽기 방향에 따라 자르기 영역을 옮깁니다. 접근성 문자열 여덟 개 중 다섯 개, 곧 root의 레이블과 역할 설명, 로딩 설명, 선택 영역의 역할 설명과 안내문은 provider의 번역에서 옵니다.
+- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
+
+## 기능 용어와 다른 이름
+
+- 다루는 기능: `crop-image`, `aspect-ratio-lock`, `zoom-and-pan`, `rotate-image`, `translatable-strings`.
+- 다른 이름: `image cropper`, `crop tool`, `photo crop`, `avatar editor`, `image editor`, `crop box`, `이미지 크로퍼`, `이미지 자르기`, `사진 자르기`, `크롭 도구`, `아바타 편집기`.
+- 어휘 상태: `controlled`.