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

package/skills/components/combobox/SKILL.md

@@ -1,218 +0,0 @@
----
-name: 'combobox'
-description: 'Combobox — 사용자가 입력하는 대로 컬렉션을 좁히고 일치 항목을 떠 있는 목록으로 제시하는 텍스트 필드. 컴포넌트는 결코 필터링하지 않습니다. 사용처가 좁혀진 컬렉션을 전달하며, 컴포넌트는 키보드 도달, 타입어헤드, 알려지는 위치를 현재 화면에 있는 행이 아니라 컬렉션 전체를 기준으로 처리합니다. 다른 이름: combobox, autocomplete, typeahead, search select, filterable dropdown, lookup field, 콤보박스, 자동완성, 검색 셀렉트, 자동완성 입력.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/combobox.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/combobox.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# Combobox
-
-> 사용자가 입력하는 대로 컬렉션을 좁히고 일치 항목을 떠 있는 목록으로 제시하는 텍스트 필드. 컴포넌트는 결코 필터링하지 않습니다. 사용처가 좁혀진 컬렉션을 전달하며, 컴포넌트는 키보드 도달, 타입어헤드, 알려지는 위치를 현재 화면에 있는 행이 아니라 컬렉션 전체를 기준으로 처리합니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `Combobox`
-- 분류: `collection-data-entry`
-- 수명 주기: `active`
-
-## 알려진 예외 — 사용 전에 확인
-
-이 컴포넌트는 아래 기준 2개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
-
-### WCAG 2.2 SC 1.4.11 비텍스트 대비 (AA)
-
-- 대상 part: `item`
-- 충족하지 못하는 것: Combobox의 강조된 항목은 `secondary.default` 배경만으로 표시되며, overlay 배경 대비 1.16:1(밝은 테마), 1.46:1(어두운 테마)로 3:1에 못 미칩니다. 포인터와 키보드 모두 링을 그리지 않습니다.
-- 의도한 이유: 모든 강조 행에 링을 그리면 시스템의 다른 어떤 hover보다 무겁게 보였습니다. 포커스는 목록에 머물고 강조된 항목은 `aria-activedescendant`로 보조 기술에 전달되며, 선택된 항목은 파란 글자와 체크 표시로 따로 구분됩니다. `contrast-pairs.json`에 `highlight` 용도로 기록되어 있습니다.
-- 사용 시 유의점: 저시력 사용자에게 강조 위치가 잘 보이지 않을 수 있습니다. 접근성 감사 대상 제품이라면 이 예외를 감사 문서에 포함하세요. 항목을 직접 그릴 때는 선택 상태의 글자색과 체크 표시를 지워 강조와 선택을 같은 모양으로 만들지 마세요.
-
-### HTML 폼 제출 — 알려진 결함
-
-- 충족하지 못하는 것: 숨겨진 필드 없이 보이는 입력의 텍스트가 제출됩니다. 단일 선택이면 항목의 value가 아니라 label이 제출되고, `multiple`이면 빈 문자열이 제출됩니다.
-- 의도한 이유: machine이 숨겨진 입력을 제공하지 않고 `selectionBehavior`가 입력 텍스트를 label로 채우는 업스트림 동작입니다. 제출 값을 바꾸는 우회를 두지 않고 그대로 기록합니다.
-- 사용 시 유의점: label과 value가 다르거나 `multiple`을 쓰면 `onValueChange`로 값을 받아 제품의 필드에 직접 넣어 제출하세요. 폼 제출만 믿고 서버에서 value를 기대하지 마세요.
-
-## Do
-
-> 훑어보기에는 너무 큰 집합에서의 선택으로, 입력이 사용자가 원하는 항목에 도달하는 방법인 경우 — 고객, 국가, 저장소, 태그. 키 입력마다 집합을 가져오는 경우에도 맞는 컨트롤입니다. `loading`과 `empty`는 컴포넌트가 시점을 정하고 제품이 문구를 쓰는 part이므로, 느린 검색은 빈 목록을 보여주는 대신 느리다고 말해줍니다. 집합에 없는 값도 정당할 때 — 이미 연락처일 수도 아닐 수도 있는 이메일 주소처럼 — `allowCustomValue`를 쓰세요.
-
-## Don't
-
-> 사용자가 입력할 필요가 없을 때는 쓰지 마세요. Select는 같은 컬렉션을 trigger 뒤에 보여주고 키 입력이 들지 않으며, 컬렉션이 여섯 항목뿐인 Combobox는 사용자가 그냥 읽을 수 있었던 것 위에 얹은 검색 필드일 뿐입니다. 여러 개의 자유 텍스트 항목을 수집하는 데 쓰지 마세요 — 그것은 각 항목을 하나의 문자열이 아니라 제거 가능한 토큰으로 유지하는 TagsInput입니다. label과 value가 다를 때 폼 참여 노트를 먼저 읽지 않고 폼 필드로 쓰지 마세요. input은 자기 텍스트, 즉 label을 제출합니다. 그리고 내비게이션에 쓰지 마세요. listbox는 행을 현재 값이 있는 선택지로 알리는데, 하나를 고르면 다른 곳으로 이동해 버린다면 그것은 거짓이 됩니다.
-
-## Anti-patterns
-
-> 컬렉션을 좁히는 대신 렌더링 루프 안에서 필터링하는 것 — JSX에서 `collection.items.filter(...)`를 map하는 식입니다. machine의 탐색, 타입어헤드, 알려지는 위치는 모두 컬렉션을 읽으므로, 렌더링 시점에만 필터링된 목록은 키보드가 화면에 없는 항목을 돌아다니게 하고 `aria-setsize`가 필터링되지 않은 전체 개수를 보고하게 만듭니다. `collection.withItems(...)`는 기존 컬렉션을 건드리지 않고 새 컬렉션을 반환하며, 같은 일을 올바르게 하는 지원 방식이 이것입니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
-
-## 관련 컴포넌트
-
-- `Select` (`select`)
-- `Listbox` (`listbox`)
-- `TagsInput` (`tags-input`)
-- `CascadeSelect` (`cascade-select`)
-- `Menu` (`menu`)
-
-## 가져오기
-
-```tsx
-import { Combobox } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 16개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<Combobox.Root>
-  <Combobox.Control>
-    <Combobox.ClearTrigger />
-    <Combobox.Input />
-    <Combobox.Trigger />
-  </Combobox.Control>
-  <Combobox.Label />
-  <Combobox.Positioner>
-    <Combobox.Content>
-      <Combobox.List>
-        <Combobox.ItemGroup>
-          <Combobox.Item>
-            <Combobox.ItemIndicator />
-            <Combobox.ItemText />
-          </Combobox.Item>
-          <Combobox.ItemGroupLabel />
-        </Combobox.ItemGroup>
-      </Combobox.List>
-      <Combobox.Empty />
-      <Combobox.Loading />
-    </Combobox.Content>
-  </Combobox.Positioner>
-</Combobox.Root>
-```
-
-- `Combobox.Root` — 최상위에 놓입니다
-- `Combobox.ClearTrigger` — `Control` 안에 놓입니다
-- `Combobox.Content` — `Positioner` 안에 놓입니다
-- `Combobox.Control` — `Root` 안에 놓입니다
-- `Combobox.Input` — `Control` 안에 놓입니다
-- `Combobox.Item` — `ItemGroup` 안, 또는 `List` 안에 놓입니다
-- `Combobox.ItemGroup` — `List` 안에 놓입니다
-- `Combobox.ItemGroupLabel` — `ItemGroup` 안에 놓입니다
-- `Combobox.ItemIndicator` — `Item` 안에 놓입니다
-- `Combobox.ItemText` — `Item` 안에 놓입니다
-- `Combobox.Label` — `Root` 안에 놓입니다
-- `Combobox.List` — `Content` 안에 놓입니다
-- `Combobox.Positioner` — `Root` 안에 놓입니다
-- `Combobox.Trigger` — `Control` 안에 놓입니다
-- `Combobox.Empty` — `Content` 안, 또는 `List` 안에 놓입니다
-- `Combobox.Loading` — `Content` 안, 또는 `List` 안에 놓입니다
-
-### Synapse가 더하는 part
-
-- `Combobox.Empty` — Combobox는 컬렉션이 필터링된 컬렉션인 컴포넌트이므로, '항목 없음'은 비어 있는 극단적인 경우가 아니라 정상적이고 빈번한 상태입니다 — 쿼리가 아무것과도 일치하지 않을 때 아무것도 렌더링하지 않는 목록은 로드에 실패한 목록과 구별할 수 없습니다. 컴포넌트는 `empty`를 `collection.size === 0`으로부터 판단하므로 사용처가 이를 명시할 필요가 없습니다. 문구는 사용처가 작성하는데, "No results found"를 소유하는 디자인 시스템은 그 문구를 사용처가 출시하는 모든 언어로 번역하는 일까지 떠안게 되기 때문입니다.
-- `Combobox.Loading` — 컬렉션이 아니라 `loading` prop으로 판단합니다. 요청이 진행 중인지는 제품만 아는 사실이기 때문입니다. `empty`보다 우선합니다(공통 우선순위는 error, loading, empty 순입니다). 결과가 아직 도착하지 않아 비어 있는 컬렉션은 결과가 없는 컬렉션이 아니며, 요청 도중에 "일치 항목 없음"을 알리는 것이 바로 이 part가 막기 위해 존재하는 잘못된 답입니다.
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 34개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-### 필수
-
-- `collection` — `SynapseCollection<TItem>`, 필수. 제시할 컬렉션이며, `createCollection`으로 만듭니다. 필터링은 사용처의 몫입니다: 질의가 바뀌는 대로 컬렉션을 좁히고 — `withItems`는 새 컬렉션을 돌려주고 이것은 건드리지 않습니다 — 그 결과를 넘기면 됩니다. 컴포넌트는 사용처를 대신해 필터링하지 않는데, 일치가 "~로 시작"인지 "~를 포함"인지 "퍼지"인지 "서버가 말한 대로"인지 알 수 없기 때문입니다.
-
-### 선택
-
-- `value` — `readonly string[]`, 선택. 제어되는 선택.
-- `defaultValue` — `readonly string[]`, 선택. 비제어 초기 선택. `value`가 주어지면 무시됩니다.
-- `onValueChange` — `(details: ComboboxValueChangeDetails) => void`, 선택. 제어 여부와 무관하게 선택이 바뀔 때마다 알림을 받습니다.
-- `inputValue` — `string`, 선택. 제어되는 필드 안의 텍스트. 선택된 것을 뜻하는 `value`와는 별개입니다.
-- `defaultInputValue` — `string`, 선택. 비제어 초기 필드 텍스트.
-- `onInputValueChange` — `(details: ComboboxInputValueChangeDetails) => void`, 선택. 텍스트가 바뀔 때 알림을 받습니다 — 사용처가 컬렉션을 다시 거르는 지점입니다.
-- `highlightedValue` — `string | null`, 선택. 제어되는 하이라이트 아이템 — `aria-activedescendant`가 가리키는 대상입니다.
-- `defaultHighlightedValue` — `string | null`, 선택. 비제어 초기 하이라이트 아이템.
-- `onHighlightChange` — `(details: ComboboxHighlightChangeDetails) => void`, 선택. 하이라이트가 움직일 때 알림을 받으며, 한 번도 렌더된 적 없는 아이템으로 갈 때도 받습니다.
-- `open` — `boolean`, 선택. 제어되는 목록의 열림 상태.
-- `defaultOpen` — `boolean`, 선택. 비제어 초기 열림 상태.
-- `onOpenChange` — `(details: { open: boolean; }) => void`, 선택. 목록이 열리거나 닫힐 때마다 알림을 받습니다.
-- `loading` — `boolean`, 선택. 요청이 진행 중입니다. 이 컴포넌트가 스스로 답할 수 없는 유일한 상태 part 사실입니다. `Combobox.Loading`을 움직이며, `Combobox.Empty`보다 우선합니다 — 결과가 아직 도착하지 않아 비어 있는 컬렉션은 결과가 없는 컬렉션이 아닙니다.
-- `multiple` — `boolean`, 선택. 둘 이상을 선택할 수 있게 합니다.
-- `allowCustomValue` — `boolean`, 선택. 어떤 아이템과도 일치하지 않는 텍스트도 값으로 받아들입니다.
-- `closeOnSelect` — `boolean`, 선택. 선택하면 목록을 닫습니다. 단일 선택 Combobox에서는 기본값이 true입니다.
-- `inputBehavior` — `ComboboxInputBehavior`, 선택. 필터링 말고도 타이핑이 무엇을 하는지. 기본값은 `none`입니다.
-- `selectionBehavior` — `ComboboxSelectionBehavior`, 선택. 선택하면 필드의 텍스트가 어떻게 되는지. 기본값은 `replace`입니다.
-- `openOnClick` — `boolean`, 선택. 필드를 클릭하면 목록을 엽니다.
-- `openOnChange` — `boolean`, 선택. 텍스트가 바뀌는 즉시 목록을 엽니다. 기본값은 true입니다.
-- `loopFocus` — `boolean`, 선택. 키보드 이동이 양 끝을 넘어가면 반대편으로 이어집니다.
-- `placeholder` — `string`, 선택. 필드의 placeholder 텍스트.
-- `positioning` — `ComboboxPositioning`, 선택. 목록이 놓이는 위치.
-- `name` — `string`, 선택. 폼 필드 이름. 이것이 없으면 컨트롤은 아무것도 제출하지 않습니다.
-- `form` — `string`, 선택. 폼 바깥에 렌더된 Combobox를 id로 폼과 연결합니다.
-- `disabled` — `boolean`, 선택. 비활성화된 Combobox는 제출되지 않고 반응하지도 않습니다.
-- `readOnly` — `boolean`, 선택. 읽기 전용 Combobox는 값을 제출하지만 바꿀 수는 없습니다.
-- `invalid` — `boolean`, 선택. 보조 기술에 `aria-invalid`로 알려집니다.
-- `required` — `boolean`, 선택. 제약 검증: 폼이 제출되려면 무언가가 선택되어 있어야 합니다.
-- `autoFocus` — `boolean`, 선택. 마운트될 때 포커스를 필드 안으로 옮깁니다.
-- `translations` — `TranslationOverrides`, 선택. 이 Combobox에만 적용되는 접근성 문자열이며, provider의 것보다 우선합니다.
-- `size` — `Size`, 선택. 하나의 공유 척도에서 옵니다. 모든 컴포넌트가 그렇듯 기본값은 `md`입니다.
-- `id` — `string`, 선택. 팩토리가 생성하는 식별자를 덮어씁니다. 서버와 클라이언트에서 동일합니다.
-
-## Variants
-
-- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. size 축은 컨트롤과 각 행의 최소 높이와 텍스트 스타일, 그리고 두 trigger의 아이콘 크기를 정합니다. 행 높이를 직접 정하지는 않습니다. 윈도가 알지 못하는 무언가에 높이가 좌우되는 행은 거짓말하는 스크롤바가 되므로, 레시피는 최솟값만 정하고 나머지는 콘텐츠가 결정하게 합니다.
-
-## 폼
-
-폼 참여: 예.
-
-- `input`으로 제출합니다.
-- 제출 값은 `value`에서 옵니다.
-- 항목은 사용처가 아무것도 설정하지 않았을 때 제출되는 값을 기록하지 않습니다.
-
-> 숨겨진 필드는 없습니다. `name`, `form`, `required`, `disabled`는 눈에 보이는 `role="combobox"` input에 적용되므로, 폼이 제출하는 것은 바로 그 입력의 텍스트입니다. 단일 Combobox에서 machine의 기본 `selectionBehavior`는 `replace`이며, 이는 텍스트를 선택된 항목의 label로 설정합니다 — 따라서 제출되는 문자열은 항목의 value가 아니라 label이며, label과 value가 다른 제품은 `onValueChange`를 읽어 value를 직접 제출해야 합니다. `multiple`이면 machine이 `selectionBehavior`를 `clear`로 바꾸므로 필드는 빈 문자열을 제출하고, 선택은 사용처 자신의 상태를 통해서만 폼에 전달됩니다. 이것은 업스트림의 형태이며, 서버에서 뒤늦게 발견되는 대신 여기에 기록해 둡니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `error-state` — Combobox는 이 상태가 보고할 실패를 낳는 요청을 수행하지 않습니다. 사용처가 가져오고 필터링하므로 요청이 실패했음을 아는 것은 사용처뿐이며 — 그 사실을 말할 자리는 컴포넌트가 자기 일정대로 열고 닫는 목록 안이 아니라 필드 옆입니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 필드는 machine이 내보내는 `htmlFor`를 통해 Label part로 이름이 붙습니다. trigger와 clear trigger의 이름은 provider의 `combobox.trigger.label`과 `combobox.clearTrigger.label`에서 오며 `machineTranslations`를 거쳐 전달됩니다 — 그렇지 않으면 machine이 "Toggle suggestions"와 "Clear value"를 동작이 가장 나중에 적용되는 접근성 영역에 하드코딩하므로, Synapse가 제품이 바꿀 수 없는 이름을 허용하더라도 사용처가 prop을 넘겨 둘 중 어느 것도 덮어쓸 수 없게 됩니다.
-
-### 포커스
-
-> DOM 포커스는 결코 input을 떠나지 않습니다. 하이라이트된 행은 aria-activedescendant로 가리키며, 덕분에 목록이 아래에서 움직이는 동안에도 사용자가 계속 입력할 수 있습니다 — 고정된 행이 중요한 이유도 이것입니다. 그 속성이 가리키는 id는 작성자가 우연히 시험해 본 위치만이 아니라 모든 스크롤 위치에서 존재해야 합니다.
-
-### 알려 주는 위치
-
-> aria-posinset과 aria-setsize는 컬렉션 자체의 `positionOf`에서 오므로, 컬렉션 전체와 그 안에서의 절대적·그룹 상대적 위치를 나타냅니다. 둘 다 렌더링 루프에서 세지 않습니다. 렌더링 루프에서 세는 것은 윈도잉된 목록이 만 개짜리 컬렉션 위의 스무 행짜리 윈도에서 세 번째 행을 "3 of 20"로 알리게 되는 전형적인 경로입니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 예. 목록의 배치는 논리적이므로 `bottom-start`는 provider의 텍스트 방향을 따릅니다. 타입어헤드와 보이는 레이블은 사용처의 컬렉션이 담은 그대로이며, 이는 해당 로케일의 것입니다. trigger와 clear trigger의 이름은 provider의 번역에서 옵니다.
-- 컬렉션 윈도잉: 예. 사용처가 자신의 children을 제공하지 않으면 `List`는 언제나 `resolveWindow`의 행을 렌더링합니다. 윈도잉은 올바른 동작을 얻기 위해 사용처가 선택해야 하는 옵션이 결코 아닙니다. 그 덕분에 키보드 도달, 타입어헤드, 알려지는 개수가 모두 렌더링된 윈도가 아니라 컬렉션 전체를 나타냅니다 — 그리고 활성 행은 범위 밖에 있어도 DOM에 고정되므로 `aria-activedescendant`가 존재하지 않는 id를 가리키는 일이 없습니다. Combobox는 이 고정이 가장 절실한 경우입니다. 입력할 때마다 컬렉션이 좁혀지고 machine이 첫 번째 일치 항목을 하이라이트하므로 하이라이트가 끊임없이 움직이며, activedescendant가 허공을 가리키는 컴포넌트는 정확히 사용되는 동안 조용히 쓸 수 없게 됩니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `type-to-filter`, `choose-from-list`, `custom-value`, `single-select`, `multi-select`, `windowed-collection`, `form-value`, `floating-layer`, `readonly-display`, `translatable-strings`.
-- 다른 이름: `combobox`, `autocomplete`, `typeahead`, `search select`, `filterable dropdown`, `lookup field`, `콤보박스`, `자동완성`, `검색 셀렉트`, `자동완성 입력`.
-- 어휘 상태: `controlled`.

package/skills/components/date-input/SKILL.md

@@ -1,157 +0,0 @@
----
-name: 'date-input'
-description: 'DateInput — 자유 텍스트가 아니라 일, 월, 연도 세그먼트를 따로 두어 만든 날짜 필드이므로, 컴포넌트가 잘못 해석할 여지가 없습니다. 세그먼트는 provider의 로케일이 정한 순서로 나타나며, 사용처가 설정하고 읽는 값과 폼이 제출하는 값은 언제나 ISO 날짜입니다. 다른 이름: date input, date field, date entry, segmented date, dob field, datetime input, 날짜 입력, 날짜 필드, 생년월일 입력, 날짜 세그먼트 입력.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/date-input.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/date-input.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# DateInput
-
-> 자유 텍스트가 아니라 일, 월, 연도 세그먼트를 따로 두어 만든 날짜 필드이므로, 컴포넌트가 잘못 해석할 여지가 없습니다. 세그먼트는 provider의 로케일이 정한 순서로 나타나며, 사용처가 설정하고 읽는 값과 폼이 제출하는 값은 언제나 ISO 날짜입니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `DateInput`
-- 분류: `collection-data-entry`
-- 수명 주기: `active`
-
-## Do
-
-> 사용자가 알고 있어 그냥 입력하면 되는 모든 날짜 — 생년월일, 청구일, 만료일, 마감일. 날짜가 오늘에서 멀거나 정확히 알려져 있을 때는 언제나 달력보다 나은 컨트롤입니다. 월 그리드로 1974년에 도달하려면 십여 번의 조작이 필요하지만 입력하면 세 번이면 됩니다. 시간이 중요하면 `granularity`를 `minute`이나 `second`로 올리며, AM/PM 세그먼트가 나타날지는 로케일의 시계 관례가 결정합니다.
-
-## Don't
-
-> 사용자가 달력을 봐야 고를 수 있을 때 — 화요일 고르기, 주말 피하기, 월말 찾기 — 는 쓰지 마세요. 그것은 DatePicker이며, DatePicker는 어차피 이 필드를 자신의 텍스트 부분으로 조합합니다. 연도만 또는 월만 입력받는 데 쓰지 마세요. 세그먼트가 하나뿐인 세그먼트 필드는 키보드가 더 나쁜 NumberInput일 뿐입니다. "편의"를 위해 자유 텍스트 필드에 연결하지 마세요. 파싱된 문자열은 이 컴포넌트가 표현 불가능하게 만들려고 존재하는 바로 그 실패이며, 그럴듯하고 형식도 올바르지만 한 달이 어긋난 날짜를 만들어내면서도 화면에는 아무 흔적도 남기지 않습니다. 그리고 직접 작성한 코드에서 `valueAsString`을 제출하지 마세요 — ISO를 건네주는 `onValueChange`를 읽으세요.
-
-## Anti-patterns
-
-> machine 자신의 값이 경계를 넘어가게 두는 것. 그 값은 `@internationalized/date`의 `DateValue[]` — Synapse가 공개 계약에서 배제하는 업스트림 타입 — 이고, `valueAsString`은 로케일에 맞춰 형식화된 텍스트입니다. 그래서 숨겨진 input을 보정해야 했고, 변경 콜백을 `valueAsString`이 아니라 `details.value`로부터 만듭니다. `valueAsString`을 그대로 전달하면 타입 검사를 통과하고 `en-US`에서는 올바르게 보이지만, 영국의 사용처와 미국의 사용처에 서로 다른 날을 뜻하는 `03/04/2026`을 건네게 됩니다. 이제 제어 경로와 네이티브 제출 경로가 일치하며, 단지 형식이 아니라 그 일치가 바로 보장되는 속성입니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
-
-## 관련 컴포넌트
-
-- `DatePicker` (`date-picker`)
-- `NumberInput` (`number-input`)
-- `PinInput` (`pin-input`)
-- `Editable` (`editable`)
-
-## 가져오기
-
-```tsx
-import { DateInput } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 6개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<DateInput.Root>
-  <DateInput.Label />
-  <DateInput.Control>
-    <DateInput.SegmentGroup>
-      <DateInput.Segment />
-    </DateInput.SegmentGroup>
-  </DateInput.Control>
-  <DateInput.HiddenInput />
-</DateInput.Root>
-```
-
-- `DateInput.Root` — 최상위에 놓입니다
-- `DateInput.Label` — `Root` 안에 놓입니다
-- `DateInput.Control` — `Root` 안에 놓입니다
-- `DateInput.SegmentGroup` — `Control` 안에 놓입니다
-- `DateInput.Segment` — `SegmentGroup` 안에 놓입니다
-- `DateInput.HiddenInput` — `Root` 안에 놓입니다
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 23개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
-
-### 선택
-
-- `value` — `readonly string[]`, 선택. 제어되는 값이며, ISO 날짜입니다 — `['2026-09-20']`.
-- `defaultValue` — `readonly string[]`, 선택. 비제어 초기 값. `value`가 주어지면 무시됩니다.
-- `onValueChange` — `(details: DateInputValueChangeDetails) => void`, 선택. 제어 여부와 무관하게 값이 바뀔 때마다 알림을 받습니다.
-- `onFocusChange` — `(details: DateInputFocusChangeDetails) => void`, 선택. 키보드가 날짜 사이를 오갈 때 알림을 받습니다.
-- `min` — `string`, 선택. 받아들이는 가장 이른 날짜이며, ISO 날짜입니다.
-- `max` — `string`, 선택. 받아들이는 가장 늦은 날짜이며, ISO 날짜입니다.
-- `isDateUnavailable` — `(date: Date) => boolean`, 선택. 필드 전체를 비활성화하지 않고 특정 날짜만 거부합니다.
-- `selectionMode` — `DateInputSelectionMode`, 선택. 필드가 날짜를 몇 개나 쥐는지. 기본값은 `single`입니다.
-- `granularity` — `DateInputGranularity`, 선택. 필드가 시점의 어디까지를 편집하는지. 기본값은 `day`입니다.
-- `hourCycle` — `12 | 24`, 선택. 12시간제인지 24시간제인지. 기본값은 로캘의 방식을 따릅니다.
-- `shouldForceLeadingZeros` — `boolean`, 선택. 일과 월을 두 자리로 채웁니다. 기본값은 로캘의 관행을 따릅니다.
-- `timeZone` — `string`, 선택. 날짜를 해석할 때 쓰는 시간대.
-- `hideTimeZone` — `boolean`, 선택. 정밀도에 시각이 포함될 때 시간대 세그먼트를 숨깁니다.
-- `locale` — `string`, 선택. 이 필드에 한해 provider의 로캘을 덮어씁니다. 한 페이지에 정말로 여러 로캘이 섞이는 드문 제품을 위한 것입니다. 설정하지 않고 두면 애플리케이션 전체가 `SynapseProvider`의 로캘을 따라서, 모든 필드가 같은 규칙으로 날짜를 쓰고 해석합니다.
-- `name` — `string`, 선택. 폼 필드 이름. 이것이 없으면 컨트롤은 아무것도 제출하지 않습니다.
-- `form` — `string`, 선택. 폼 바깥에 렌더된 DateInput을 id로 폼과 연결합니다.
-- `disabled` — `boolean`, 선택. 비활성화된 DateInput은 제출되지 않고 반응하지도 않습니다.
-- `readOnly` — `boolean`, 선택. 읽기 전용 DateInput은 값을 제출하지만 바꿀 수는 없습니다.
-- `invalid` — `boolean`, 선택. 보조 기술에 `aria-invalid`로 알려집니다.
-- `required` — `boolean`, 선택. 제약 검증: 폼이 제출되려면 날짜가 있어야 합니다.
-- `translations` — `TranslationOverrides`, 선택. 이 DateInput에만 적용되는 접근성 문자열이며, provider의 것보다 우선합니다.
-- `size` — `Size`, 선택. 하나의 공유 척도에서 옵니다. 모든 컴포넌트가 그렇듯 기본값은 `md`입니다.
-- `id` — `string`, 선택. 팩토리가 생성하는 식별자를 덮어씁니다. 서버와 클라이언트에서 동일합니다.
-
-## Variants
-
-- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. size 축은 컨트롤의 최소 높이와 각 세그먼트의 높이, 텍스트 스타일을 정합니다. 필드의 너비는 정하지 않습니다. 세그먼트가 몇 개이고 각각 얼마나 넓은지는 로케일과 granularity가 정하므로, 크기 이름에 고정된 필드는 `yyyy年mm月dd日`을 잘라내거나 `mm/dd` 뒤에 빈 공간을 남기게 됩니다.
-
-## 폼
-
-폼 참여: 예.
-
-- `input`으로 제출합니다.
-- 제출 값은 `value`에서 옵니다.
-- 항목은 사용처가 아무것도 설정하지 않았을 때 제출되는 값을 기록하지 않습니다.
-
-> `hiddenInput`은 anatomy part이므로 팩토리가 machine 자신의 getter로 이를 만들고 — 그런 다음 바로잡습니다. machine은 제출 값을 `valueAsString`으로 설정하는데, 이는 로케일에 맞춰 형식화된 텍스트입니다. `03/04/2026`을 받은 서버는 3월인지 4월인지 알 수 없으며, 값은 관련된 모두가 같은 로케일을 공유하는 동안에만 올바르게 왕복합니다. `amendBehaviorProps`는 그 prop 하나만 api 자신의 값에서 도출한 ISO 날짜로 대체하고 getter 출력의 나머지는 그대로 둡니다. `meta.amendedParts`가 `HiddenInput`을 명시하므로 이 보정은 묻혀 있지 않고 찾아볼 수 있습니다. 설정되지 않은 필드는 machine의 getter와 똑같이 빈 문자열을 제출하므로, 입력된 적 없는 날짜가 `undefined`라는 단어로 도착하지 않습니다. `range`나 `multiple` 필드는 날짜마다 `name[0]`, `name[1]`로 이름 붙은 숨겨진 input을 하나씩 렌더링하며, 각각은 그 input이 실제로 제출하는 날짜로부터 보정됩니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `empty-state` — 값이 없는 DateInput은 비어 있는 것이 아닙니다 — 세그먼트별 placeholder `mm`, `dd`, `yyyy`를 보여주는 필드이며, 이것이 사용자에게 무엇을 어떤 순서로 입력할지 알려줍니다. 그것이 곧 채워지지 않은 상태이며, 그 옆에서 "날짜 없음"을 알리는 영역은 이미 화면에 있는 것을 다시 설명할 뿐입니다.
-- `loading-state` — 여기서는 아무것도 가져오지 않습니다. 필드는 제품이 이미 가진 값을 편집하므로, 아직 도착하지 않은 날짜는 비활성화된 컨트롤에 주변 폼이 그리는 스켈레톤을 더한 것입니다 — 이 시스템의 다른 모든 단일 값 컨트롤이 내놓는 것과 같은 답입니다.
-- `error-state` — 유효하지 않음은 옆에 붙는 영역이 아니라 컨트롤의 상태입니다. `invalid`는 모든 세그먼트의 aria-invalid로 알려지며, `min`/`max` 밖이거나 `isDateUnavailable`이 거부한 날짜는 이미 세그먼트 자체의 spinbutton 범위로 도달할 수 없습니다. 그 이유를 설명하는 메시지는 그 안의 모든 컨트롤에 대한 레이블, 힌트, 유효성 검사 문구를 소유하는 주변 필드에 속합니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 필드는 machine이 내보내는 id를 통해 Label로 이름이 붙고, 각 세그먼트는 자기 부분에 대한 aria-label로 스스로 이름을 붙입니다 — machine이 "Year", "Month" 등을 영어로 하드코딩하므로, 보정을 통해 provider의 `dateInput.segment.*` 키에서 가져옵니다. `machineTranslations: null`이어도 공백이 하나 남습니다. machine의 유일한 번역 항목은 세그먼트별 문자열의 객체인 `placeholder(locale)`이고 그 대부분은 로케일에서 도출되지만, `AM/PM`, `era`, `timeZone`, `weekday` placeholder는 업스트림 영어로 남아 있으며, `dateInput.segment.placeholder` 키는 객체를 전달할 수 있는 이음매를 기다리고 있습니다.
-
-### 포커스
-
-> 각 세그먼트는 따로 포커스를 받을 수 있으며, 이것이 이 컴포넌트 설계의 구조적인 절반입니다. 사용자는 날짜를 입력하는 것이 아니라 도착하기 전에 의미가 정해진 필드를 채우므로, `03/04/2026`이 두 가지를 뜻할 수 없습니다. Label을 클릭하면 숨겨진 input이 아니라 첫 번째 세그먼트에 포커스가 갑니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 예. 로케일 요구 사항은 바로 이 컴포넌트를 위해 쓰였습니다. 세그먼트 순서는 provider의 로케일을 따릅니다 — `Intl.DateTimeFormat.formatToParts`가 이를 결정하므로, 아무도 설정하지 않아도 `ja-JP`는 연-월-일, `en-GB`는 일-월-연 순서가 됩니다 — 반면 제출 값은 언제나 ISO 날짜입니다. 로케일은 `useMachineProps` 안의 `useLocale()`에서 오며 결코 브라우저에서 오지 않습니다. 팩토리는 `dir`는 자동으로 제공하지만 `locale`은 제공하지 않으므로, 그 한 줄이 없다면 provider에 `locale="de-DE"`를 설정한 제품이 미국식 날짜 필드를 받게 되고, 기본 로케일을 쓰는 모든 개발자에게는 그것이 올바르게 보일 것입니다. `locale` prop은 필드 하나에 대해 이를 덮어쓰며, 이는 기본값이 아니라 문서화된 예외입니다.
-- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `date-entry`, `segmented-input`, `date-range`, `date-time-granularity`, `iso-date-value`, `locale-formatting`, `form-value`, `readonly-display`, `translatable-strings`.
-- 다른 이름: `date input`, `date field`, `date entry`, `segmented date`, `dob field`, `datetime input`, `날짜 입력`, `날짜 필드`, `생년월일 입력`, `날짜 세그먼트 입력`.
-- 어휘 상태: `controlled`.

package/skills/components/date-picker/SKILL.md

@@ -1,235 +0,0 @@
----
-name: 'date-picker'
-description: 'DatePicker — 달력을 여는 필드. 그리드, 요일 순서, 월 이름, 한 주의 첫날은 모두 애플리케이션의 로케일에서 오며, 사용처가 읽고 쓰는 값은 어떤 로케일에서든 ISO 날짜 문자열입니다. 다른 이름: date picker, calendar, datepicker, date field, day picker, 날짜 선택기, 데이트 피커, 달력, 캘린더.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/date-picker.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/date-picker.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# DatePicker
-
-> 달력을 여는 필드. 그리드, 요일 순서, 월 이름, 한 주의 첫날은 모두 애플리케이션의 로케일에서 오며, 사용처가 읽고 쓰는 값은 어떤 로케일에서든 ISO 날짜 문자열입니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `DatePicker`
-- 분류: `collection-data-entry`
-- 수명 주기: `active`
-
-## 알려진 예외 — 사용 전에 확인
-
-이 컴포넌트는 아래 기준 2개를 **의도적으로 충족하지 않습니다**. 기록된 결정이므로 고치려 들지 말고, 각 항목의 유의점을 지켜서 씁니다.
-
-### HTML 폼 제출 — 알려진 결함
-
-- 대상 part: `input`
-- 충족하지 못하는 것: ISO 날짜가 아니라 로케일에 맞춰 형식화된 표시 텍스트가 제출됩니다. `03/04/2026`은 3월 4일인지 4월 3일인지 알 수 없습니다. `form` prop도 없습니다.
-- 의도한 이유: machine이 숨겨진 입력을 제공하지 않아 보이는 필드가 표시이자 제출 값이며, 컴포넌트 안의 어떤 이음매도 둘을 분리할 수 없습니다. 우회하지 않고 기록합니다.
-- 사용 시 유의점: `onValueChange`로 값을 받아 ISO 문자열을 제품의 숨겨진 필드에 넣어 제출하세요. 제출된 텍스트를 서버에서 날짜로 파싱하지 마세요.
-
-### 알려진 결함 — 주 번호
-
-- 충족하지 못하는 것: 주 번호 열을 렌더링할 수 없고 `showWeekNumbers`는 공개 prop이 아닙니다.
-- 의도한 이유: 주 번호 셀의 getter가 하나의 anatomy 키로 세 종류의 셀을 내보내므로 part로 표현할 수 없습니다.
-- 사용 시 유의점: 주 번호가 필요한 달력은 이 컴포넌트로 만들 수 없습니다.
-
-## Do
-
-> 사용자가 맥락 속에서 봐야 하는 날짜 — 무슨 요일인지, 오늘에서 얼마나 떨어져 있는지, 근처에 무엇이 있는지에 따라 선택이 달라지는 경우. 그리드가 가치의 전부입니다. 예약, 일정, 마감일 선택기는 사용자가 숫자를 떠올리는 것이 아니라 한 달을 두고 따져보는 경우입니다. 대상 사용자가 여러 로케일에 걸쳐 있을 때도 맞는 컨트롤인데, 한 주의 첫날, 월 이름, 입력의 파싱이 모두 브라우저가 아니라 애플리케이션의 로케일을 따르기 때문입니다.
-
-## Don't
-
-> 사용자가 이미 알고 있어 그냥 입력하면 되는 날짜에는 쓰지 마세요. 생년월일은 숫자 세 개이며, 1989년에 닿으려고 사백 개월을 거슬러 넘기게 하는 것은 세그먼트 세 개짜리 필드보다 모든 면에서 나쁩니다 — 그것은 이 컴포넌트와 같은 ISO 계약을 공유하는 DateInput입니다. 월이나 연도만 고르는 데 쓰지 마세요. minView를 설정해 아무도 원하지 않는 날짜(day)를 묻는 대신 달력이 해당 그리드에서 멈추게 하세요. 값이 기간이나 반복일 때는 달력으로 표현할 수 없으므로 쓰지 말고, 현재로서는 이것을 유일한 폼 컨트롤로 의존하지 마세요. 제출되는 필드가 로케일 형식의 텍스트를 담으며, 이는 formParticipation에 기록되어 있습니다.
-
-## Anti-patterns
-
-> 브라우저의 로케일로 날짜를 형식화하거나 파싱하는 것. 모든 날짜 API의 기본값이고, 작성한 사람 눈에는 보이지 않으며, 그럴듯하고 형식도 올바르지만 한 달이 어긋난 날짜를 만들어냅니다 — `03/04/2026`은 영국에서는 4월 3일이고 미국에서는 3월 4일입니다. 두 번째 Anti-pattern은 첫 번째에서 이어집니다. 형식화된 문자열을 경계 너머로 넘기는 것입니다. 이 컴포넌트가 노출하는 모든 값은 ISO 날짜이므로, 사용처는 결코 달력 객체를 만들지 않으며 사용자가 우연히 본 텍스트를 보내지도 않습니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
-
-## 관련 컴포넌트
-
-- `DateInput` (`date-input`)
-- `Select` (`select`)
-- `Popover` (`popover`)
-- `Combobox` (`combobox`)
-
-## 가져오기
-
-```tsx
-import { DatePicker } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 24개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<DatePicker.Root>
-  <DatePicker.Control>
-    <DatePicker.ClearTrigger />
-    <DatePicker.Input />
-    <DatePicker.Trigger />
-  </DatePicker.Control>
-  <DatePicker.Label />
-  <DatePicker.Positioner>
-    <DatePicker.Content>
-      <DatePicker.PresetTrigger />
-      <DatePicker.RangeText />
-      <DatePicker.View>
-        <DatePicker.MonthSelect />
-        <DatePicker.Table>
-          <DatePicker.TableBody>
-            <DatePicker.TableRow>
-              <DatePicker.TableCell>
-                <DatePicker.TableCellTrigger />
-              </DatePicker.TableCell>
-              <DatePicker.TableHeader />
-            </DatePicker.TableRow>
-          </DatePicker.TableBody>
-          <DatePicker.TableHead />
-        </DatePicker.Table>
-        <DatePicker.ViewControl>
-          <DatePicker.NextTrigger />
-          <DatePicker.PrevTrigger />
-          <DatePicker.ViewTrigger />
-        </DatePicker.ViewControl>
-        <DatePicker.YearSelect />
-      </DatePicker.View>
-    </DatePicker.Content>
-  </DatePicker.Positioner>
-</DatePicker.Root>
-```
-
-- `DatePicker.Root` — 최상위에 놓입니다
-- `DatePicker.ClearTrigger` — `Control` 안에 놓입니다
-- `DatePicker.Content` — `Positioner` 안에 놓입니다
-- `DatePicker.Control` — `Root` 안에 놓입니다
-- `DatePicker.Input` — `Control` 안에 놓입니다
-- `DatePicker.Label` — `Root` 안에 놓입니다
-- `DatePicker.MonthSelect` — `View` 안에 놓입니다
-- `DatePicker.NextTrigger` — `ViewControl` 안에 놓입니다
-- `DatePicker.Positioner` — `Root` 안에 놓입니다
-- `DatePicker.PresetTrigger` — `Content` 안에 놓입니다
-- `DatePicker.PrevTrigger` — `ViewControl` 안에 놓입니다
-- `DatePicker.RangeText` — `Content` 안에 놓입니다
-- `DatePicker.Table` — `View` 안에 놓입니다
-- `DatePicker.TableBody` — `Table` 안에 놓입니다
-- `DatePicker.TableCell` — `TableRow` 안에 놓입니다
-- `DatePicker.TableCellTrigger` — `TableCell` 안에 놓입니다
-- `DatePicker.TableHead` — `Table` 안에 놓입니다
-- `DatePicker.TableHeader` — `TableRow` 안에 놓입니다
-- `DatePicker.TableRow` — `TableBody` 안, 또는 `TableHead` 안에 놓입니다
-- `DatePicker.Trigger` — `Control` 안에 놓입니다
-- `DatePicker.View` — `Content` 안에 놓입니다
-- `DatePicker.ViewControl` — `View` 안에 놓입니다
-- `DatePicker.ViewTrigger` — `ViewControl` 안에 놓입니다
-- `DatePicker.YearSelect` — `View` 안에 놓입니다
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 37개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
-
-### 선택
-
-- `value` — `readonly string[]`, 선택. 제어되는 값이며, ISO 날짜입니다 — `['2026-09-20']`.
-- `defaultValue` — `readonly string[]`, 선택. 비제어 초기 값. `value`가 주어지면 무시됩니다.
-- `onValueChange` — `(details: DatePickerValueChangeDetails) => void`, 선택. 제어 여부와 무관하게 값이 바뀔 때마다 알림을 받습니다.
-- `focusedValue` — `string`, 선택. 키보드가 올라가 있는, 제어되는 날짜이며 ISO 날짜입니다.
-- `defaultFocusedValue` — `string`, 선택. 비제어 초기 포커스 날짜.
-- `onFocusChange` — `(details: DatePickerFocusChangeDetails) => void`, 선택. 키보드가 날짜 사이를 오갈 때 알림을 받습니다.
-- `open` — `boolean`, 선택. 제어되는 달력의 열림 상태.
-- `defaultOpen` — `boolean`, 선택. 비제어 초기 열림 상태.
-- `onOpenChange` — `(details: OpenChangeDetails) => void`, 선택. 달력이 열리거나 닫힐 때마다 알림을 받습니다.
-- `view` — `DatePickerView`, 선택. 제어되는 격자 — 일, 월 또는 연입니다.
-- `defaultView` — `DatePickerView`, 선택. 비제어 초기 격자. 기본값은 `minView`입니다.
-- `onViewChange` — `(details: DatePickerViewChangeDetails) => void`, 선택. 격자가 바뀔 때 알림을 받습니다.
-- `minView` — `DatePickerView`, 선택. 선택할 수 있는 가장 성긴 격자. 기본값은 `day`입니다.
-- `maxView` — `DatePickerView`, 선택. 뷰 trigger가 올라갈 수 있는 가장 촘촘한 격자. 기본값은 `year`입니다.
-- `min` — `string`, 선택. 받아들이는 가장 이른 날짜이며, ISO 날짜입니다.
-- `max` — `string`, 선택. 받아들이는 가장 늦은 날짜이며, ISO 날짜입니다.
-- `isDateUnavailable` — `(date: string) => boolean`, 선택. 피커 전체를 비활성화하지 않고 특정 날짜만 거부합니다. 날짜는 `value`와 같은 모양인 ISO 문자열로 도착하므로, 사용처가 답하기 위해 달력 객체를 만들거나 들여다볼 일이 없습니다.
-- `selectionMode` — `DatePickerSelectionMode`, 선택. 피커가 날짜를 몇 개나 쥐는지. 기본값은 `single`입니다.
-- `maxSelectedDates` — `number`, 선택. `multiple` 선택의 개수 상한을 정합니다.
-- `fixedWeeks` — `boolean`, 선택. 언제나 여섯 주를 렌더해, 달마다 달력의 높이가 달라지지 않게 합니다.
-- `startOfWeek` — `number`, 선택. 격자가 어느 요일에서 시작하는지이며, `0`이 일요일입니다. 기본값은 로캘을 따릅니다.
-- `outsideDaySelectable` — `boolean`, 선택. 이웃한 달의 날짜도 그것이 보이는 격자에서 선택할 수 있게 합니다.
-- `closeOnSelect` — `boolean`, 선택. 선택하면 달력을 닫습니다. 기본값은 true입니다.
-- `openOnClick` — `boolean`, 선택. 필드를 클릭하면 달력을 엽니다.
-- `inline` — `boolean`, 선택. 달력을 제자리에 렌더해 언제나 열려 있게 합니다.
-- `positioning` — `DatePickerPositioning`, 선택. 달력이 놓이는 위치.
-- `timeZone` — `string`, 선택. 날짜를 해석할 때 쓰는 시간대. 기본값은 `UTC`입니다.
-- `placeholder` — `string`, 선택. 필드의 placeholder 텍스트. 기본값은 로캘의 날짜 형식입니다.
-- `locale` — `string`, 선택. 이 피커에 한해 provider의 로캘을 덮어씁니다. 한 페이지에 정말로 여러 로캘이 섞이는 드문 제품을 위한 것입니다. 설정하지 않고 두면 애플리케이션 전체가 `SynapseProvider`의 로캘을 따라서, 모든 피커가 같은 규칙으로 날짜를 쓰고 해석합니다.
-- `name` — `string`, 선택. 폼 필드 이름. 이것이 없으면 컨트롤은 아무것도 제출하지 않습니다.
-- `disabled` — `boolean`, 선택. 비활성화된 DatePicker는 제출되지 않고 반응하지도 않습니다.
-- `readOnly` — `boolean`, 선택. 읽기 전용 DatePicker는 값을 제출하지만 바꿀 수는 없습니다.
-- `invalid` — `boolean`, 선택. 보조 기술에 `aria-invalid`로 알려집니다.
-- `required` — `boolean`, 선택. 제약 검증: 폼이 제출되려면 날짜가 있어야 합니다.
-- `translations` — `TranslationOverrides`, 선택. 이 DatePicker에만 적용되는 접근성 문자열이며, provider의 것보다 우선합니다.
-- `size` — `Size`, 선택. 하나의 공유 척도에서 옵니다. 모든 컴포넌트가 그렇듯 기본값은 `md`입니다.
-- `id` — `string`, 선택. 팩토리가 생성하는 식별자를 덮어씁니다. 서버와 클라이언트에서 동일합니다.
-
-## Variants
-
-- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`.
-
-## 폼
-
-폼 참여: 예.
-
-- `input`으로 제출합니다.
-- 제출 값은 `value`에서 옵니다.
-- 항목은 사용처가 아무것도 설정하지 않았을 때 제출되는 값을 기록하지 않습니다.
-
-> 결함이며, 우회하지 않고 기록해 둡니다. `input` part가 machine의 `name`을 가지며 폼이 읽는 요소인데 — 그 값은 ISO 날짜가 아니라 사용자가 입력하고 읽는, 로케일에 맞춰 형식화된 날짜입니다. `03/04/2026`을 받은 서버는 4월 3일인지 3월 4일인지 알 수 없으며, 값은 관련된 모두가 같은 로케일을 공유하는 동안에만 올바르게 왕복합니다. DateInput도 같은 machine 결함을 겪었고 숨겨진 input에 `amendBehaviorProps`를 적용해 바로잡습니다. 이 machine은 숨겨진 input을 제공하지 않으므로, 보이는 필드가 표시이자 동시에 제출 값이며, 컴포넌트 안의 어떤 이음매도 둘을 분리할 수 없습니다. machine의 `syncInputElement` 이펙트가 변경될 때마다 `valueAsString`을 요소에 다시 기록하므로, 보정된 `defaultValue`는 첫 커밋까지만 살아남고 그 뒤에는 덮어써집니다. 해결책은 machine이 제공하는 숨겨진 input, 또는 팩토리가 렌더링할 수 있는 Synapse 소유의 숨겨진 input입니다. machine은 `form` prop도 선언하지 않으므로, DatePicker는 자신이 속한 폼과 함께 제출될 뿐 id로 폼과 연결될 수 없습니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `empty-state` — 달력은 결코 비어 있지 않습니다. 내용은 가져오는 것이 아니라 날짜와 로케일로부터 계산되므로, 모든 달에는 28일에서 31일이 있고 그리드에 보여줄 것이 없는 상태는 없습니다. 보이는 달 전체를 제외하는 `min`/`max` 범위라도 그 날들을 비활성화된 채로 렌더링합니다. 월 단위로 탐색하는 사용자는 자신이 어디에 도착했는지 봐야 하기 때문입니다.
-- `loading-state` — 이 컴포넌트에서 로드되는 것은 없습니다. 그리드, 월 이름, 요일 순서는 `Intl`과 provider가 제공하는 로케일에서 오며, 이들 모두 첫 렌더링에서 동기적으로 사용할 수 있으므로 DatePicker가 무언가를 기다리는 구간은 없습니다.
-- `error-state` — 거부된 날짜는 컨트롤의 `invalid`로 보고되고 `aria-invalid`로 알려지며, 제품이 받아들이지 않을 날짜는 `min`, `max`, `isDateUnavailable`로 제외되어 결코 선택될 수 없습니다. 둘 다 `error` 상태 part가 보고하는 것, 즉 사용처가 소유한 작업의 실패가 아닙니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 필드는 htmlFor를 통해 Label part에서 이름을 얻습니다. 달력, clear trigger, 두 select는 provider의 번역 가능한 세트에서 이름을 얻으며 피커별로 덮어쓸 수 있습니다. machine의 함수형 문자열은 함수형 `machineTranslations`를 거쳐 전달됩니다: `dayCell`(사용자가 누르는 모든 날의 이름), `trigger`, `prevTrigger`, `nextTrigger`. view trigger의 이름은 보이는 월이나 연도로 시작하도록 보정에서 다시 구성되고(WCAG 2.5.3), preset trigger의 machine 레이블은 버려져 보이는 텍스트가 이름이 되며, 콘텐츠와 그리드의 aria-roledescription은 `datePicker.content.roleDescription`과 `datePicker.table.*`에서 옵니다. `weekNumberCell`은 렌더링되지 않고, `placeholder`는 로케일에서 도출됩니다.
-
-### 포커스
-
-> 그리드 안에서는 로빙 tabindex를 씁니다. 정확히 하나의 셀 trigger만 탭 순서에 있고 화살표 키가 포커스와 그 tabindex를 함께 옮기므로, 키보드 사용자는 마흔두 개의 셀을 일일이 거치지 않고 한 번의 탭으로 달력에 들어갑니다. 그리드 자체는 tabindex=-1이며 키 처리를 소유합니다.
-
-### 선언된 부재
-
-> 주 번호 열은 렌더링되지 않습니다. `getWeekNumberCellProps`와 `getWeekNumberHeaderCellProps`는 둘 다 `tableCell` part의 속성을 다른 역할 — rowheader, 그리고 scope=col인 열 머리글 — 로 내보내며, 하나의 anatomy 키로는 세 종류의 셀을 담을 수 없습니다. 그래서 이 열은 `unrenderedGetters`에 선언되고 `showWeekNumbers`는 공개 prop이 아닙니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 예. 시스템의 어떤 컴포넌트보다도 그렇습니다. 로케일은 한 주가 무슨 요일에 시작하는지, 요일 열을 무엇이라 부르는지, 월을 무엇이라 부르는지, 월과 연도를 함께 어떻게 쓰는지, 필드가 사용자의 입력을 어떻게 형식화하고 파싱하는지, 그리고 — 방향을 통해 — 이전·다음 화살표가 어느 쪽을 가리키는지를 결정합니다. 로케일은 SynapseProvider에서 오며 결코 브라우저에서 오지 않습니다. 피커별 `locale` prop은 한 페이지에서 실제로 여러 로케일을 섞어 쓰는 제품을 위한 문서화된 예외입니다. 값은 의도적으로 이 모든 것 바깥에 있습니다. 양방향 모두 ISO 날짜 문자열이므로, 사용처가 저장하는 값은 페이지의 언어에 따라 바뀌지 않습니다.
-- 컬렉션 윈도잉: 아니요. 달력의 행은 컬렉션에서 가져오는 것이 아니라 보이는 달로부터 계산되며, 이 컴포넌트가 렌더링하는 가장 큰 그리드는 7칸짜리 6행입니다. 유일하게 긴 목록은 연도 선택이며, 이는 브라우저가 옵션을 스스로 가상화하는 네이티브 `select`입니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `pick-a-date`, `calendar-grid`, `date-range`, `iso-date-value`, `locale-formatting`, `locale-parsing`, `form-value`, `floating-layer`, `readonly-display`, `translatable-strings`.
-- 다른 이름: `date picker`, `calendar`, `datepicker`, `date field`, `day picker`, `날짜 선택기`, `데이트 피커`, `달력`, `캘린더`.
-- 어휘 상태: `controlled`.