# Component registry (`@atom`)

`poc/design-system/implement` 를 [shadcn 레지스트리 형식](https://ui.shadcn.com/docs/registry)의 JSON 으로 만든 것입니다.
다른 프로젝트에서 `shadcn add` 로 컴포넌트 소스와 ATOM CSS 를 복사해 설치할 수 있습니다.

```
registry/
├── registry.json               인덱스: 아이템 43개의 메타데이터 + 파일 경로 (내용 없음)
├── r/<name>.json               설치용 아이템: 파일 내용 포함 (shadcn add 가 읽는 파일)
└── scripts/
    ├── build-registry.mjs      생성 스크립트
    └── serve.mjs               로컬 HTTP 서버 (http://localhost:8766/r/{name}.json)
```

## 생성

`implement/src` 나 `components/*.md` 를 고친 뒤 다시 생성합니다. 생성물은 직접 수정하지 않습니다.

```bash
node poc/design-system/registry/scripts/build-registry.mjs
# 배포 주소를 homepage 에 넣으려면
REGISTRY_URL=https://ui.example.com node poc/design-system/registry/scripts/build-registry.mjs
```

각 필드는 아래에서 가져옵니다.

- **의존성 자동 계산:** `registryDependencies` 는 소스의 import 문을 분석해서 만듭니다. 없는 파일을 import 하면 생성이 실패합니다.
- **설명:** 컴포넌트는 `components/<name>.md` 의 첫 문단(= 원본 `meta.description`)을 씁니다. lib 와 내부 파일은 맨 위 주석의 첫 줄을 씁니다.
- **분류 · 메타:** `categories`, `meta.kind` · `status` · `specSource` · `hidden` 은 원본 `03_ASSET_GUIDE/registry.json` 의 `assets.<name>` 에서 가져옵니다.
  - category 값: `action-input` · `selection` · `display` · `feedback` · `navigation` · `overlay`
- **파트:** `meta.parts` 는 implement 의 `scripts/build-docs-data.mjs` 결과(compound 파트 목록)를 씁니다.
- **완결성 검사:** 원본 asset 28개가 모두 구현되었는지, 스텁(파트 0개)이 없는지 확인합니다. 하나라도 빠지면 생성이 실패합니다.
- **npm 의존성:** 외부 npm 의존성이 없어 `dependencies` 는 비어 있습니다. react, react-dom 은 peer 의존성이라 넣지 않습니다.

## 아이템

| 종류 | 아이템 | type · 설치 위치 |
|---|---|---|
| 토큰 | `tokens` | `registry:file`: `styles/atom/tokens.css`, `styles/atom/base.css`, `styles/fixes.css` |
| 컴포넌트 (28) | `accordion` `autocomplete` `badge` `button` `chart` `checkbox` `chip` `date-input` `dialog` `field` `grid` `input-button` `multi-select` `pagination` `radio` `section-title` `select` `shape-map` `splitter` `statistic` `switch` `tabs` `text-input` `time-chip` `time-input` `toast` `tooltip` `tree` | `registry:ui` → `components/ui/*.tsx`<br>+ `registry:file` → `styles/atom/elements/*.css` |
| 내부 | `icons` `shape-map-data` | `registry:ui` → `components/ui/*` |
| 유틸 (11) | `lib-bem` `lib-cn` `lib-context` `lib-date` `lib-field-context` `lib-pagination-window` `lib-slot` `lib-time` `lib-use-anchored-position` `lib-use-controllable-state` `lib-use-dismiss` | `registry:lib` → `components/lib/*` |
| 묶음 | `all` | `registry:item`: 토큰 + 컴포넌트 전체 + 전체 CSS 진입점 `styles/atom-ui.css` |

**스타일은 Tailwind 가 아니라 ATOM 엘리먼트 CSS 입니다.** 그래서 컴포넌트 아이템은 tsx 와 함께 두 종류의 CSS 를 싣습니다.

- 자기 CSS
- 원본 `requiresStylesheets` 에 있는 CSS. 예를 들어 `select` 는 `field.css` 를, `grid` 는 `button` · `multi-select` · `pagination` · `select` · `text-input` 의 CSS 를 함께 싣습니다.

여러 아이템이 같은 CSS 를 실어도 설치 위치가 같고 내용도 같아서 문제가 없습니다.

설치 위치는 implement 의 상대 경로 구조를 그대로 유지합니다. `components/ui/x.tsx` 가 `../lib/x` 를 import 하고, `styles/atom-ui.css` 가 `./atom/*` · `./fixes.css` 를 import 합니다. 그래서 설치할 때 경로를 고치지 않아도 됩니다.

```json
{
  "name": "select",
  "type": "registry:ui",
  "registryDependencies": ["@atom/tokens", "@atom/icons", "@atom/lib-bem", "@atom/lib-cn", "..."],
  "files": [
    { "path": "poc/design-system/implement/src/components/select.tsx", "type": "registry:ui", "target": "components/ui/select.tsx" },
    { "path": "poc/design-system/implement/src/styles/atom/elements/field.css", "type": "registry:file", "target": "styles/atom/elements/field.css" },
    { "path": "poc/design-system/implement/src/styles/atom/elements/select.css", "type": "registry:file", "target": "styles/atom/elements/select.css" }
  ],
  "categories": ["selection"],
  "meta": { "version": "0.1.0", "kind": "element", "status": "stable", "specSource": "measured", "parts": ["Select"], "docs": "poc/design-system/components/select.md" }
}
```

## 설치해서 쓰기

1. `r/` 폴더를 정적 파일로 배포합니다. 로컬에서는 `node poc/design-system/registry/scripts/serve.mjs` 로 띄웁니다.
2. 설치할 프로젝트의 `components.json` 에 네임스페이스를 등록합니다.

```json
{
  "registries": { "@atom": "http://localhost:8766/r/{name}.json" }
}
```

3. 컴포넌트를 설치합니다.

```bash
npx shadcn add @atom/select   # 의존성(tokens, icons, lib-*)과 select.css · field.css 도 함께 설치
npx shadcn add @atom/all      # 전체
```

4. 전역 CSS 에 스타일을 추가합니다.

```css
/* @atom/all 로 설치했을 때 */
@import "./styles/atom-ui.css";

/* 일부만 설치했을 때: 순서를 지킵니다 */
@import "./styles/atom/tokens.css";
@import "./styles/atom/base.css";
@import "./styles/atom/elements/select.css";
@import "./styles/atom/elements/field.css";
@import "./styles/fixes.css"; /* 맨 마지막 */
```

### 주의

- **import 가 없는 파일은 맨 위 설명 주석이 빠진 채로 설치됩니다.** 해당 파일은 `lib/bem.ts` · `date.ts` · `time.ts` · `pagination-window.ts`, `shape-map-data.ts` 입니다. shadcn CLI 의 동작이고, 코드는 동일합니다.
- **사내 네트워크에서 `self-signed certificate` 에러가 나면** `NODE_OPTIONS=--use-system-ca npx shadcn add ...` 로 실행합니다.
- 이 레지스트리는 Tailwind 를 쓰지 않으므로 `components.json` 의 `tailwind.cssVariables` 설정에 영향을 받지 않습니다.

## 검증 내역

- 생성 시 검사를 통과했습니다.
  - 원본 asset 28개가 모두 구현됨
  - 스텁 없음
  - 모든 `registryDependencies` 가 존재함
  - 모든 파일 내용이 비어 있지 않음
- `poc/design-system/ui-schema` 에 로컬 HTTP 로 띄워 `npx shadcn add @atom/all` 로 실제 설치했습니다.
  - 설치된 tsx · lib · CSS 가 implement 원본과 같습니다(위 주석 5건 제외).
  - 그 앱에서 카탈로그 생성(파트 60개), 타입 검사, 빌드에 사용했습니다(`ui-schema/README.md`).