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

package/skills/components/field/SKILL.md

@@ -1,133 +0,0 @@
----
-name: 'field'
-description: 'Field — 레이블, 도움말, 오류 메시지, 필수 표시를 안쪽 컨트롤 하나에 묶는 틀입니다. 레이블과 설명의 접근성 연결, 그리고 오류·필수·비활성·읽기 전용 상태를 컨트롤마다가 아니라 Field에서 한 번에 줍니다. 다른 이름: field, form field, form control, label, helper text, error message, required indicator, 필드, 폼 필드, 입력 필드 레이블, 도움말, 오류 메시지, 필수 표시.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/field.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/field.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# Field
-
-> 레이블, 도움말, 오류 메시지, 필수 표시를 안쪽 컨트롤 하나에 묶는 틀입니다. 레이블과 설명의 접근성 연결, 그리고 오류·필수·비활성·읽기 전용 상태를 컨트롤마다가 아니라 Field에서 한 번에 줍니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `Field`
-- 분류: `form-controls`
-- 수명 주기: `active`
-
-## Do
-
-> 레이블이나 도움말, 오류 메시지가 붙는 폼 컨트롤 하나를 감쌀 때 쓰세요 — Input, Textarea, Select, NumberInput 같은 모든 폼 컨트롤이 Field의 상태와 연결을 이어받습니다. 검증 결과는 Field의 `invalid`와 Field.ErrorText 한 곳에서 알리면, 컨트롤의 aria-invalid와 aria-describedby가 함께 따라옵니다. 도움말, 오류, 글자 수는 컨트롤 아래 한 줄에 놓입니다 — `invalid`인 동안 오류가 도움말 자리를 대신하고, `showCount`를 켜면 안쪽 텍스트 입력의 글자 수가 같은 줄 오른쪽에 붙습니다.
-
-## Don't
-
-> 여러 컨트롤을 한 제목 아래 묶을 때는 Fieldset을 쓰세요 — 체크박스 여러 개처럼 묶음 전체에 붙는 이름과 오류는 컨트롤 하나의 Field가 표현하지 못합니다. 레이블이 화면에 필요 없는 검색창 같은 단독 입력은 Field 없이 컨트롤에 aria-label을 주세요.
-
-## Anti-patterns
-
-> 오류 문구를 Field.ErrorText 밖의 일반 텍스트로 그리는 것. 보이기는 하지만 컨트롤의 aria-describedby에 연결되지 않아, 스크린 리더 사용자는 무엇이 틀렸는지 듣지 못한 채 aria-invalid만 듣게 됩니다. Field 안에서 컨트롤의 Label part를 Field.Label과 함께 쓰는 것도 같은 부류입니다(Checkbox와 Switch는 제외).
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-26).
-
-## 관련 컴포넌트
-
-- `Fieldset` (`fieldset`)
-- `Input` (`input`)
-- `Textarea` (`textarea`)
-
-## 가져오기
-
-```tsx
-import { Field } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 5개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<Field.Root>
-  <Field.Label>
-    <Field.RequiredIndicator />
-  </Field.Label>
-  <Field.HelperText />
-  <Field.ErrorText />
-</Field.Root>
-```
-
-- `Field.Root` — 최상위에 놓입니다
-- `Field.Label` — `Root` 안에 놓입니다
-- `Field.RequiredIndicator` — `Label` 안, 또는 `Root` 안에 놓입니다
-- `Field.HelperText` — `Root` 안에 놓입니다
-- `Field.ErrorText` — `Root` 안에 놓입니다
-
-### part가 렌더링하고 소유하는 요소
-
-- `characterCount`, `Field.Root`가 렌더링합니다 — `showCount`일 때 Field가 안쪽 텍스트 입력의 글자 수를 세어 메시지 줄 오른쪽에 그리는 요소입니다. 무엇을 보일지는 Field가 DOM에서 직접 재어 정하므로 사용처가 조합할 것이 없고, part로 두면 사용처가 빠뜨리거나 컨트롤과 다른 위치에 두어 설명 연결이 어긋날 수 있어 일부러 part로 두지 않았습니다.
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 6개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
-
-### 선택
-
-- `invalid` — `boolean`, 선택. 안쪽 컨트롤이 물려받는 오류 상태. `true`이면 `Field.ErrorText`가 나타나고 컨트롤에 `aria-invalid`가 붙습니다.
-- `required` — `boolean`, 선택. 안쪽 컨트롤이 물려받는 필수 상태. `Field.RequiredIndicator`가 나타납니다.
-- `disabled` — `boolean`, 선택. 안쪽 컨트롤이 물려받는 비활성 상태.
-- `readOnly` — `boolean`, 선택. 안쪽 컨트롤이 물려받는 읽기 전용 상태.
-- `id` — `string`, 선택. 레이블, 설명, 오류와 컨트롤을 잇는 식별자들의 바탕. 서버와 클라이언트에서 같습니다.
-- `showCount` — `boolean`, 선택. 안쪽 텍스트 입력의 글자 수를 메시지 줄 오른쪽에 보여 줍니다. 입력에 `maxLength`가 있으면 "12 / 280"처럼 한도와 함께 보이고, 한도에 가까워지면 남은 글자 수를 스크린 리더에 알립니다.
-
-## 폼
-
-폼 참여: 아니요.
-
-> Field 자신은 값을 제출하지 않습니다. 제출은 안쪽 컨트롤이 자신의 `name`으로 하며, Field는 그 컨트롤에 필수·비활성·읽기 전용 상태를 물려줄 뿐입니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `size-axis` — Field는 레이블과 설명을 컨트롤 둘레에 놓을 뿐 스스로 그리는 컨트롤이 없습니다. 크기는 안쪽 컨트롤이 자신의 `size`로 정하며, Field가 척도를 따로 가지면 같은 필드 안에서 두 크기가 서로 어긋날 수 있습니다.
-- `empty-state` — Field는 값이나 컬렉션을 갖지 않습니다. 비어 있는 것은 안쪽 컨트롤의 값이며, 그 상태는 컨트롤이 보여 줍니다.
-- `loading-state` — Field는 아무것도 불러오지 않습니다. 컨트롤이 쓸 데이터를 기다리는 동안의 표시는 그 컨트롤이나 주변 화면의 몫이며, 그동안 입력을 막아야 한다면 `disabled`를 줍니다.
-- `error-state` — `error` 상태 part는 사용처가 소유한 작업이 실패했음을 알리는 자리인데, Field에는 그런 작업이 없습니다. 입력값이 검증을 통과하지 못한 것은 작업의 실패가 아니라 값의 상태이며, 그것은 `invalid`와 ErrorText part가 컨트롤의 aria-describedby에 연결된 채로 표현합니다. 두 가지를 한 part에 겹치면 저장 실패와 형식 오류가 같은 문구 자리를 두고 다투게 됩니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 컨트롤의 이름은 Field.Label에서 옵니다. Field 안에서는 컨트롤 자신의 Label part 대신 Field.Label을 쓰세요 — 둘을 함께 두면 같은 id를 가진 요소가 둘이 되어 개발 모드에서 경고합니다. Checkbox와 Switch만 예외로, 옆의 문구가 곧 그 컨트롤의 이름이므로 자신의 Label을 쓰고 Field.Label은 제목 역할만 합니다.
-
-### 포커스
-
-> 포커스를 받는 요소가 없습니다. 레이블을 누르면 htmlFor로 이어진 입력으로 브라우저가 포커스를 옮기고, 버튼 trigger 컨트롤이면 trigger로 포커스만 옮깁니다(열지 않습니다).
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `form-field-layout`, `inline-alert`.
-- 다른 이름: `field`, `form field`, `form control`, `label`, `helper text`, `error message`, `required indicator`, `필드`, `폼 필드`, `입력 필드 레이블`, `도움말`, `오류 메시지`, `필수 표시`.
-- 어휘 상태: `controlled`.

package/skills/components/fieldset/SKILL.md

@@ -1,123 +0,0 @@
----
-name: 'fieldset'
-description: 'Fieldset — 관련된 여러 컨트롤을 제목(legend) 하나 아래 묶는 네이티브 `<fieldset>`입니다. 묶음 전체의 도움말과 오류를 aria-describedby로 연결하고, `disabled` 하나로 안쪽의 모든 컨트롤을 비활성화합니다. 다른 이름: fieldset, legend, group, form group, checkbox group, 필드셋, 그룹, 폼 그룹, 체크박스 묶음, 범례.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/fieldset.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/fieldset.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# Fieldset
-
-> 관련된 여러 컨트롤을 제목(legend) 하나 아래 묶는 네이티브 `<fieldset>`입니다. 묶음 전체의 도움말과 오류를 aria-describedby로 연결하고, `disabled` 하나로 안쪽의 모든 컨트롤을 비활성화합니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `Fieldset`
-- 분류: `form-controls`
-- 수명 주기: `active`
-
-## Do
-
-> 하나의 질문에 답하는 여러 컨트롤을 묶을 때 쓰세요 — 알림 채널을 고르는 체크박스들, 주소를 이루는 여러 입력처럼. 묶음 전체에 붙는 설명과 오류(예: '하나 이상 고르세요')는 Fieldset.HelperText와 Fieldset.ErrorText에 두세요.
-
-## Don't
-
-> 컨트롤이 하나뿐이면 Field를 쓰세요. RadioGroup은 스스로 radiogroup 역할과 레이블을 가지므로 Fieldset으로 한 번 더 감싸지 마세요 — 그룹 안의 그룹이 되어 이름이 두 번 읽힙니다.
-
-## Anti-patterns
-
-> Legend 없이 Fieldset을 쓰는 것. 이름 없는 그룹은 스크린 리더에게 경계만 알리고 무엇의 묶음인지는 알리지 못합니다. 시각적인 테두리가 필요해서 Fieldset을 고르는 것도 잘못입니다 — Fieldset은 테두리를 그리지 않으며, 의미상 묶음이 아닌 곳에 쓰면 불필요한 그룹이 생깁니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-26).
-
-## 관련 컴포넌트
-
-- `Field` (`field`)
-- `Checkbox` (`checkbox`)
-- `Switch` (`switch`)
-
-## 가져오기
-
-```tsx
-import { Fieldset } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 4개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<Fieldset.Root>
-  <Fieldset.Legend />
-  <Fieldset.HelperText />
-  <Fieldset.ErrorText />
-</Fieldset.Root>
-```
-
-- `Fieldset.Root` — 최상위에 놓입니다
-- `Fieldset.Legend` — `Root` 안에 놓입니다
-- `Fieldset.HelperText` — `Root` 안에 놓입니다
-- `Fieldset.ErrorText` — `Root` 안에 놓입니다
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 3개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
-
-### 선택
-
-- `invalid` — `boolean`, 선택. 묶음 전체의 오류 상태. `true`이면 `Fieldset.ErrorText`가 나타납니다.
-- `disabled` — `boolean`, 선택. 네이티브 `<fieldset disabled>`로 안쪽의 모든 컨트롤을 한 번에 비활성화합니다.
-- `id` — `string`, 선택. 설명과 오류 문구의 식별자 바탕. 서버와 클라이언트에서 같습니다.
-
-## 폼
-
-폼 참여: 아니요.
-
-> Fieldset 자신은 값을 제출하지 않습니다. 다만 네이티브 `<fieldset disabled>`이므로 안쪽 컨트롤은 비활성화되는 동안 폼 제출에서도 빠집니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `size-axis` — Fieldset은 컨트롤을 묶는 구조일 뿐 스스로 그리는 컨트롤이 없습니다. 크기는 안쪽 컨트롤들이 각자의 `size`로 정합니다.
-- `empty-state` — Fieldset은 값을 갖지 않습니다. 묶을 컨트롤이 없으면 Fieldset 자체를 렌더링하지 않습니다.
-- `loading-state` — Fieldset은 아무것도 불러오지 않습니다. 불러오는 동안 묶음 전체를 막아야 한다면 `disabled`가 그 일을 한 번에 합니다.
-- `error-state` — `error` 상태 part는 사용처가 소유한 작업이 실패했음을 알리는 자리인데, Fieldset에는 그런 작업이 없습니다. 묶음 전체의 값이 검증을 통과하지 못한 것은 `invalid`와 ErrorText part가 묶음의 aria-describedby에 연결된 채로 표현하며, 저장 같은 작업의 실패는 그 작업을 일으킨 화면이 알립니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 묶음의 이름은 Legend에서 옵니다. 스크린 리더는 안쪽 컨트롤로 들어갈 때 이 이름을 함께 읽어 줍니다.
-
-### 포커스
-
-> 포커스를 받지 않습니다. `disabled`이면 브라우저가 안쪽의 네이티브 컨트롤을 탭 순서에서 빼고, 네이티브 `<fieldset disabled>`를 따르는 Zag machine들도 비활성 상태가 됩니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `control-group`, `form-field-layout`.
-- 다른 이름: `fieldset`, `legend`, `group`, `form group`, `checkbox group`, `필드셋`, `그룹`, `폼 그룹`, `체크박스 묶음`, `범례`.
-- 어휘 상태: `controlled`.

package/skills/components/file-upload/SKILL.md

@@ -1,184 +0,0 @@
----
-name: 'file-upload'
-description: 'FileUpload — 드롭존, 파일 선택기, 선택된 파일 목록으로 이루어지며, 파일마다 형식, 크기, 개수로 검증합니다. 이 컴포넌트는 파일을 받아들일 뿐 업로드하지 않습니다. 이 경계가 어떤 상태를 컴포넌트가 소유하고 어떤 상태가 주변 제품에 속하는지를 가릅니다. 다른 이름: file upload, dropzone, file picker, attach files, drag and drop upload, uploader, 파일 업로드, 파일 첨부, 드롭존, 파일 선택, 드래그 앤 드롭 업로드, 업로더.'
-metadata:
-  package: '@neurocle/synapse-react'
-  packageVersion: '0.3.0'
-  registryEntry: 'packages/registry/data/components/file-upload.json'
-  registryStructuralVersion: '0.3.0'
-  lifecycle: 'active'
-  generator: 'packages/react/src/skills/generate.ts'
----
-
-<!--
-생성된 파일 — 손으로 고치지 않습니다.
-
-Source:     packages/registry/data/components/file-upload.json (항목 구조 0.3.0)
-Generator:  packages/react/src/skills/generate.ts
-Regenerate: npx nx run react:skills:generate
-
-아래에서 이 컴포넌트에 대해 말하는 모든 문장은 그 항목의 필드입니다. 여기서 고친 내용은 다음
-재생성 때 지워지고, 손으로 설명한 컴포넌트는 아무것도 실패하지 않은 채 설명과 어긋납니다.
-대신 항목을 고칩니다.
--->
-
-# FileUpload
-
-> 드롭존, 파일 선택기, 선택된 파일 목록으로 이루어지며, 파일마다 형식, 크기, 개수로 검증합니다. 이 컴포넌트는 파일을 받아들일 뿐 업로드하지 않습니다. 이 경계가 어떤 상태를 컴포넌트가 소유하고 어떤 상태가 주변 제품에 속하는지를 가릅니다.
-
-`@neurocle/synapse-react` 0.3.0에서 생성했습니다. 설치된 버전이 이 버전이 아니면, 이 페이지의 어떤 내용보다 설치된 패키지 안에 함께 배포된 Registry를 우선합니다.
-
-- 패키지: `@neurocle/synapse-react`
-- 내보내기: `FileUpload`
-- 분류: `collection-data-entry`
-- 수명 주기: `active`
-
-## Do
-
-> 사용자가 제품에 파일을 건네는 모든 곳에 쓰세요. 아바타, 첨부 파일, 일괄 가져오기, 문서가 그렇습니다. 파일 목록을 직접 렌더링하지 말고 item part들을 조합하세요. `ItemName`, `ItemSizeText`, `ItemPreviewImage`는 각각 파일을 getter 인자로 받아 스스로 내용을 채우며, 썸네일의 `alt`와 삭제 버튼의 이름은 파일마다 만들어집니다. 파일 목록에서 똑같은 이름의 버튼 다섯 개로 가장 자주 출시되는 부분이 바로 이것입니다.
-
-## Don't
-
-> 업로드 진행 표시기로 쓰지 마세요. 이 컴포넌트는 파일을 받아들이는 데서 멈추며, `loading`과 `error`는 제품이 자신의 요청에서 설정하는 prop입니다. 그러니 파일별 백분율 막대는 item 옆의 Progress이지 여기서 기대할 것이 아닙니다. `accept`, `maxFileSize`, `validate`를 보안 경계로 믿지 마세요. 사용자가 우회할 수 있는 브라우저 쪽 편의 기능일 뿐이며, 서버가 다시 검사해야 합니다. 그리고 사용자가 붙여 넣어도 되는 작은 값 하나에는 쓰지 마세요. 이미지 URL을 주기 위한 파일 선택기는 한 번이면 될 상호작용을 세 번으로 만듭니다.
-
-## Anti-patterns
-
-> 거부된 파일을 업로드 오류로 다루거나 그 반대로 다루는 것. machine은 스스로 파일을 거부하고 `onFileReject`와 거부된 `ItemGroup`으로 알리는데, 이는 사용자가 다른 파일을 골라 대응할 수 있는 검증 결과입니다. `FileUpload.Error`는 제품이 완료하지 못한 요청을 위한 것이며 `assertive`로 알립니다. 거부를 오류 영역으로 보내면 사용자가 목록에서 볼 수 있는 일로 사용자를 방해하게 되고, 실패한 업로드를 목록으로 보내면 아무 안내 없이 남습니다.
-
-Registry는 이 컴포넌트의 안내를 `reviewed`로 기록합니다(검토일 2026-09-22).
-
-## 관련 컴포넌트
-
-- `ImageCropper` (`image-cropper`)
-- `Progress` (`progress`)
-- `Avatar` (`avatar`)
-- `Clipboard` (`clipboard`)
-
-## 가져오기
-
-```tsx
-import { FileUpload } from '@neurocle/synapse-react'
-```
-
-## Anatomy
-
-React 네임스페이스가 노출하는 part 14개를 항목의 `parts.containment`가 기록한 대로 조합했습니다. 한 part가 놓일 수 있는 정당한 자리가 둘 이상이면 스니펫은 첫 번째를 쓰고, 아래 목록이 나머지를 알려 줍니다.
-
-```tsx
-<FileUpload.Root>
-  <FileUpload.Dropzone />
-  <FileUpload.ItemGroup>
-    <FileUpload.Item>
-      <FileUpload.ItemDeleteTrigger />
-      <FileUpload.ItemName />
-      <FileUpload.ItemPreview>
-        <FileUpload.ItemPreviewImage />
-      </FileUpload.ItemPreview>
-      <FileUpload.ItemSizeText />
-    </FileUpload.Item>
-  </FileUpload.ItemGroup>
-  <FileUpload.Label />
-  <FileUpload.Trigger />
-  <FileUpload.ClearTrigger />
-  <FileUpload.Loading />
-  <FileUpload.Error />
-</FileUpload.Root>
-```
-
-- `FileUpload.Root` — 최상위에 놓입니다
-- `FileUpload.Dropzone` — `Root` 안에 놓입니다
-- `FileUpload.Item` — `ItemGroup` 안에 놓입니다
-- `FileUpload.ItemDeleteTrigger` — `Item` 안에 놓입니다
-- `FileUpload.ItemGroup` — `Root` 안에 놓입니다
-- `FileUpload.ItemName` — `Item` 안에 놓입니다
-- `FileUpload.ItemPreview` — `Item` 안에 놓입니다
-- `FileUpload.ItemPreviewImage` — `ItemPreview` 안에 놓입니다
-- `FileUpload.ItemSizeText` — `Item` 안에 놓입니다
-- `FileUpload.Label` — `Root` 안에 놓입니다
-- `FileUpload.Trigger` — `Root` 안에 놓입니다
-- `FileUpload.ClearTrigger` — `Root` 안에 놓입니다
-- `FileUpload.Loading` — `Root` 안에 놓입니다
-- `FileUpload.Error` — `Root` 안에 놓입니다
-
-### Synapse가 더하는 part
-
-- `FileUpload.Loading` — machine이 아니라 `loading` prop으로 답합니다. machine은 `transforming`을 알지만, 파일을 업로드하는 요청은 사용처의 것이므로 요청이 진행 중인지 아는 쪽은 사용처뿐입니다. 그래도 그 사실이 part에 무엇을 뜻하는지는 컴포넌트가 소유합니다. 언제 렌더링되는지, 무엇으로 안내하는지, 그리고 다른 무엇보다 우선하지는 않지만 `error`에는 밀린다는 점이 그렇습니다.
-- `FileUpload.Error` — `error` prop으로 답하며 `loading`보다 우선합니다. 실패한 요청은 대기 중인 요청이 아닙니다. `polite`로 알리는 `loading`과 달리 `assertive`로(role=alert) 알리는데, 업로드 실패는 사용자를 방해할 만한 일이기 때문입니다. machine은 `rejectedFiles`를 보유하고 `onFileReject`로 알리지만, 거부는 이 컴포넌트가 받지 않은 파일이고 이 part는 제품이 완료하지 못한 업로드를 위한 것입니다. 둘의 문구는 모두 사용처가 정합니다.
-
-### part가 렌더링하고 소유하는 요소
-
-- `hiddenInput`, `FileUpload.Root`가 렌더링합니다 — 실제 `<input type="file">`이며, 브라우저의 파일 선택기가 열리는 요소이자 폼이 제출하는 요소입니다. 일부러 part로 만들지 않았습니다. 사용처가 이것을 옮기거나 생략할 수 있다면 파일을 고를 수 없는 파일 업로드가 되고, anatomy 키가 없는 part는 이 Registry의 part 검사를 통과하지 못합니다. Root는 팩토리의 렌더링 탈출구를 통해 이것을 렌더링하므로 `data-synapse-form-field` 표식도 붙일 수 있으며, 폼 하네스와 SSR 하네스는 이 표식으로 그것을 찾습니다.
-
-## Props
-
-빌드가 방출하는 선언에서 도출한 prop 26개. 선언에는 기본값을 둘 자리가 없으므로 prop 기록에는 기본값이 없습니다. 기본값이 있다면 그 prop의 설명에 적혀 있습니다.
-
-모든 prop이 선택입니다. 아무것도 넘기지 않으면 컴포넌트는 비제어로 동작합니다.
-
-### 선택
-
-- `acceptedFiles` — `readonly File[]`, 선택. 제어되는 수락된 파일.
-- `defaultAcceptedFiles` — `readonly File[]`, 선택. 비제어 초기 파일. `acceptedFiles`가 주어지면 무시됩니다.
-- `onFileChange` — `(details: FileUploadChangeDetails) => void`, 선택. 쥐고 있는 파일이 바뀔 때마다 알림을 받으며, 수락이든 거부든 마찬가지입니다.
-- `onFileAccept` — `(details: FileUploadAcceptDetails) => void`, 선택. 파일이 수락될 때 알림을 받습니다.
-- `onFileReject` — `(details: FileUploadRejectDetails) => void`, 선택. 파일이 거부될 때 각각의 이유와 함께 알림을 받습니다.
-- `loading` — `boolean`, 선택. 업로드가 진행 중입니다. 컴포넌트는 파일을 받아들이고 업로드는 사용처가 하므로, 이 사실은 사용처만 압니다. `FileUpload.Loading`을 움직입니다.
-- `error` — `boolean`, 선택. 업로드가 실패했습니다. `FileUpload.Error`를 움직이며, `loading`보다 우선합니다 — 실패한 요청은 대기 중인 요청이 아닙니다. 문구는 사용처의 몫이며, 이 컴포넌트는 문구를 싣지 않습니다.
-- `accept` — `string | readonly string[] | Record<string, readonly string[]>`, 선택. 선택기가 무엇을 제시하는지이며, MIME 타입이나 확장자로 줍니다.
-- `maxFiles` — `number`, 선택. 쥘 수 있는 파일의 최대 개수. 기본값은 1입니다.
-- `maxFileSize` — `number`, 선택. 파일 하나의 최대 크기이며, 단위는 바이트입니다.
-- `minFileSize` — `number`, 선택. 파일 하나의 최소 크기이며, 단위는 바이트입니다.
-- `validate` — `(file: File) => readonly FileUploadRejectReason[] | null`, 선택. 파일이 수락되기 전에 거부합니다. 이유를 돌려주거나, 수락하려면 null을 돌려줍니다.
-- `transformFiles` — `(files: readonly File[]) => Promise<readonly File[]>`, 선택. 들어오는 파일을 다시 씁니다 — 이를테면 압축하거나 이름을 바꿉니다.
-- `directory` — `boolean`, 선택. 파일뿐 아니라 끌어다 놓은 디렉터리도 받아들입니다.
-- `capture` — `'user' | 'environment'`, 선택. 모바일 선택기가 어느 카메라를 여는지.
-- `allowDrop` — `boolean`, 선택. 끌어다 놓기를 허용합니다. 기본값은 true입니다.
-- `preventDocumentDrop` — `boolean`, 선택. 페이지의 다른 곳에 파일을 떨어뜨렸을 때 페이지가 이동해 버리는 것을 막습니다.
-- `name` — `string`, 선택. 폼 필드 이름. 이것이 없으면 컨트롤은 아무것도 제출하지 않습니다.
-- `disabled` — `boolean`, 선택. 비활성화된 FileUpload는 제출되지 않고 반응하지도 않습니다.
-- `readOnly` — `boolean`, 선택. 읽기 전용 FileUpload는 가진 파일을 보여 주지만 더 받아들이지는 않습니다.
-- `invalid` — `boolean`, 선택. 보조 기술에 `aria-invalid`로 알려집니다.
-- `required` — `boolean`, 선택. 제약 검증: 폼이 제출되려면 파일이 있어야 합니다.
-- `locale` — `string`, 선택. 파일 크기를 표기할 때 쓰는 로캘. 기본값은 provider의 로캘입니다.
-- `translations` — `TranslationOverrides`, 선택. 이 FileUpload에만 적용되는 접근성 문자열이며, provider의 것보다 우선합니다.
-- `size` — `Size`, 선택. 하나의 공유 척도에서 옵니다. 모든 컴포넌트가 그렇듯 기본값은 `md`입니다.
-- `id` — `string`, 선택. 팩토리가 생성하는 식별자를 덮어씁니다. 서버와 클라이언트에서 동일합니다.
-
-## Variants
-
-- `size` — `xs`, `sm`, `md`, `lg`, `xl`. 기본값은 `md`. size 축은 드롭존과 파일 목록 전반의 글자 스타일, trigger의 최소 높이, 삭제 버튼과 지우기 버튼의 아이콘을 정합니다. 드롭존의 면적은 정하지 않습니다. 드롭 대상의 크기는 그 상자를 주는 레이아웃에 속하며, 다섯 단계 척도는 제품이 그것을 넣은 자리와 충돌하게 됩니다.
-
-## 폼
-
-폼 참여: 예.
-
-- `input`으로 제출합니다.
-- 제출 값은 `acceptedFiles`에서 옵니다.
-- 항목은 사용처가 아무것도 설정하지 않았을 때 제출되는 값을 기록하지 않습니다.
-
-> Root가 소유하는 숨겨진 `<input type="file">`이 제출되는 요소입니다. `name`, `form`, `required`, `accept`, `capture`, `webkitdirectory`, `multiple`(`maxFiles`가 1보다 크면 설정됨)을 지니므로, 사용처에 자바스크립트가 없어도 일반 폼 POST가 파일을 보냅니다. 드롭존과 trigger가 접근 가능한 인터페이스이므로 이 입력은 `aria-hidden`이고 `tabIndex=-1`입니다. `disabled`와 `readOnly`는 둘 다 이 입력을 비활성화하므로, 읽기 전용 FileUpload는 파일을 보여 주되 새로운 것을 제출하지 않습니다.
-
-## 이 컴포넌트에 일부러 없는 것
-
-- `empty-state` — 파일이 없는 FileUpload는 빈 상태가 아닙니다. 드롭존이 이미 페이지에서 사용자에게 무엇을 할지 알려 주고 있으므로, 같은 말을 하는 두 번째 영역은 아직 하지 않았다는 사실을 두 번 알려 줄 뿐입니다. 선택된 파일 목록은 그저 행이 없을 뿐입니다.
-
-## 접근성
-
-### 접근 가능한 이름
-
-> 드롭존은 provider의 `fileUpload.dropzone.label`에서 이름을 얻습니다. 파일별 문자열 두 개, 곧 썸네일의 `alt`와 삭제 버튼의 이름은 machine이 파일을 넘겨 호출하는 함수여서 `machineTranslations`로 표현할 수 없으므로, 정적 문자열과 나란히 `useMachineProps`에서 해석됩니다(`../machine-translations.ts` 참고). 이 이음매가 있기에 이 문자열들을 덮어쓸 수 있습니다. 이것이 없으면 둘 다 접근성 영역 안에 업스트림 영어로 실려 나가고, 사용처는 prop을 넘겨 덮어쓸 수 없습니다.
-
-### 포커스
-
-> 어떤 것도 스스로 포커스를 옮기지 않습니다. 파일을 골라도 포커스는 원래 자리에 남고, 파일을 삭제하면 포커스는 방금 DOM에서 제거된 버튼에 남습니다. 사용자가 한 행씩 지워 나가는 목록에서는 알아 둘 만한 실제 공백이며, 이 컴포넌트는 현재 이를 메우지 않습니다.
-
-## 로케일과 컬렉션
-
-- 로케일 의존: 예. 모든 파일의 크기는 해석된 로케일을 쓰는 machine의 `getFileSize`로 서식화됩니다. 독일어 제품이 `1.2 MB`를 렌더링해서는 안 되기 때문이며, 로케일은 `locale` prop이 이 필드에서 덮어쓰지 않는 한 provider의 것입니다. 드롭존의 접근 가능한 이름은 provider의 `fileUpload.dropzone.label`에서 오고, 각 썸네일의 `alt`와 각 삭제 버튼의 이름은 `fileUpload.item.preview`와 `fileUpload.deleteTrigger.label`로 파일마다 만들어집니다.
-- 컬렉션 윈도잉: 아니요. 항목은 이를 이유 없이 사실로만 기록합니다.
-
-## 기능 용어와 다른 이름
-
-- 다루는 기능: `file-picker`, `drag-and-drop-files`, `file-validation`, `file-list`, `image-preview`, `directory-upload`, `form-value`, `locale-formatting`, `readonly-display`, `translatable-strings`.
-- 다른 이름: `file upload`, `dropzone`, `file picker`, `attach files`, `drag and drop upload`, `uploader`, `파일 업로드`, `파일 첨부`, `드롭존`, `파일 선택`, `드래그 앤 드롭 업로드`, `업로더`.
-- 어휘 상태: `controlled`.