# @hm-design/sw

HM Design System의 SW(설치형·도면 SW) 전용 React 컴포넌트 패키지입니다(0.2.0). `@hm-design/ui`와 독립적으로 빌드·배포·사용하며 서로 의존하지 않습니다. 공개 API의 기준은 패키지에 포함된 [ai/COMPONENT_CATALOG.md](./ai/COMPONENT_CATALOG.md)와 `dist/index.d.ts`입니다. 이 README는 요약입니다.

## 설치·Import

```tsx
import { SWHeader } from "@hm-design/sw"
import "@hm-design/sw/styles.css" // 앱 진입점에서 한 번

<SWHeader documentTitle="C0020101-006-평면및종단면도(06)" logoSrc={productLogo} logoAlt="제품명" onClose={closeWindow} />
```

- 진입점은 `@hm-design/sw`(JS·타입)와 `@hm-design/sw/styles.css` 두 개뿐입니다. `dist/components/...` 같은 내부 경로는 공개 API가 아닙니다.
- Peer: `react`, `react-dom` `^19.0.0`. 런타임 dependency는 없고, SVG·PNG 자산은 JS에 data URI로 포함됩니다. CSS는 자동 import되지 않으며 전역 선택자(`html`, `body`, `*`)를 쓰지 않습니다.
- `@hm-design/sw`는 npm Registry로 배포하지 않습니다. 소비 프로젝트는 HMDesign 저장소(`https://gitea.hmac.kr/shkim4/HMDesign.git`)를 Git Submodule + npm Workspace로 연결합니다. `npm pack`으로 만든 tarball 설치는 검증용 대안입니다.
- 패키지 내용: `dist/`(`index.js`·`index.d.ts`·`styles.css`·`build-info.json` — 출처 Commit·도구 버전), `ai/`(AI 코딩 도구용 안내·예제), `README.md`, `package.json`.

## 글꼴·테마

- SW 기본 글꼴은 **Noto Sans KR**입니다(`--hm-sw-header-font-family: "Noto Sans KR", "Malgun Gothic", "Apple SD Gothic Neo", sans-serif`, 2026-10-20 확정, Figma의 Dotum은 의도적으로 대체). 패키지는 글꼴 파일을 포함하지 않으므로 앱이 Noto Sans KR 400 / 500 / 700을 로드합니다.
- Weight(400 / 700 적용 범위)는 사용자 확정값입니다. 상세는 [ai/AI_USAGE.md](./ai/AI_USAGE.md) §2, [ai/DESIGN_RULES.md](./ai/DESIGN_RULES.md) §3.
- `SWHeader` 밖에서 하위 컴포넌트를 쓰면 `<SWTheme>`로 감쌉니다. `SWViewerHeader`·`SWViewerMenu`·`SWViewerPanel`·`SWFooter`·`SWFooterCommandLine`은 자기 루트에 SW 범위를 가집니다.
- 토큰(`--hm-sw-*`) 변경은 가장 바깥 SW 범위(`<SWTheme style>`) 한 곳에서 합니다. Light/Dark 분기는 없습니다. 방법은 [ai/AI_USAGE.md](./ai/AI_USAGE.md) §3.1, 예제 [ExampleJ-Theme.tsx](./ai/examples/ExampleJ-Theme.tsx).

## SW 모드

한 화면에는 하나의 모드만 씁니다(Header 하나). 모드 선택 기준은 [ai/AI_USAGE.md](./ai/AI_USAGE.md) §0입니다.

| 모드 | 용도 | 컴포넌트 |
|---|---|---|
| SW 일반 모드 | 도면 **편집** SW 상단·하단(Figma 이지빔-SW `26:8944`, 49px Header) | `SWHeader`·개별 컨트롤, `SWPopup`, `SWToolButton`/`SWToolGroup`, 로고 클릭 메뉴, `SWFooter` |
| SW 뷰어 모드 | 도면 **보기** 화면 상단(참고 DWG/DXF 뷰어 실측, 52px Header) | `SWViewerHeader`, `SWViewerMenu`, `SWViewerPanel`과 패널 컨트롤 |

## 공개 컴포넌트 (요약)

| 영역 | 컴포넌트 | 안내 |
|---|---|---|
| 완성형 Header | `SWHeader`(문서·레이어·색상·선/문자/치수스타일 Dropdown, 속성Bar·속성창, 반응형 More, `controls`·`hiddenControls`·`menuOrder`·`documentOpenPlacement`·`leading`·`tools`) | 카탈로그 §1 |
| 개별 컨트롤 | `SWHeaderHome`, `SWHeaderDocumentTitle`, `SWHeaderLayerMenu`, `SWHeaderColorMenu`, `SWHeaderLineStyleMenu`, `SWHeaderTextStyleMenu`, `SWHeaderDimensionStyleMenu`, `SWHeaderInput`, `SWHeaderProperties`, `SWHeaderPropertyBar`, `SWHeaderPropertyPanel`, `SWHeaderActions`, `SWHeaderWindowControls` 등 | 카탈로그 §2 |
| Popup | `SWPopup`(속성창 프레임 + 자유 `children`) + `SWPopupSection` / `SWPopupRow`, 레이어·색상·선스타일 행 `SWPopupPropertyRow`, 게이지바 `SWSlider`(`appearance` `"panel"` / `"property"`), 선택 목록 `SWSelect`. SWHeader 필드 Dropdown은 Header 전용이라 Popup에 넣지 않습니다 | 카탈로그 §3 |
| 도구 막대 | `SWToolButton`(`text`·`pill`·`document`), `SWToolGroup`(`selection="single"` = Model/Layout 탭) | 카탈로그 §4 |
| 로고 클릭 메뉴 | `SWHeader`의 `homeMenu` + `SWHomeMenu` / `SWHomeMenuSection` / `SWHomeMenuItem` / `SWRecentFiles` / `useSWHomeMenuClose`(일반 모드 전용) | 카탈로그 §5 |
| 뷰어 모드 | `SWViewerHeader`, `SWViewerHeaderButton`, `SWViewerMenu`, `SWViewerIcon`, `SWViewerPanel`, `SWViewerSection`, `SWViewerField`, `SWViewerSwitch`, `SWViewerSlider`, `SWViewerInput`, `SWViewerButton`, `SWViewerBadge`, `SWViewerHint`, `SWViewerStatus` | 카탈로그 §9, [ai/VIEWER.md](./ai/VIEWER.md) |
| Footer | `SWFooter`, `SWFooterLayoutTabs`, `SWFooterCommandLine`과 부품 `SWFooterSideButton`·`SWFooterAuxGroup`·`SWFooterAuxButton`·`SWFooterToolButton`·`SWFooterAddSlot`·`SWFooterGuide`·`SWFooterMenu`(일반 모드 전용) | 카탈로그 §10, [ai/FOOTER.md](./ai/FOOTER.md) |
| 테마 | `SWTheme` | 위 "글꼴·테마" |

로고·파일 처리·도면 렌더링·명령 실행은 각 프로그램이 Props와 Callback으로 담당합니다. 패키지에는 로고·메뉴 항목·명령이 없습니다.

## AI 코딩 도구용 안내

다른 프로젝트의 AI 코딩 도구는 설치된 패키지의 `ai/` 폴더를 먼저 읽습니다: [AI_GUIDE.md](./ai/AI_GUIDE.md)(HMDesign 공통 진입점) → [AI_USAGE.md](./ai/AI_USAGE.md)(모드 선택·작업 순서·Import 규칙) → [COMPONENT_CATALOG.md](./ai/COMPONENT_CATALOG.md)(공개 API) → [DESIGN_RULES.md](./ai/DESIGN_RULES.md)(토큰·상태) → [COMPOSITION_PATTERNS.md](./ai/COMPOSITION_PATTERNS.md)(조합) → [VIEWER.md](./ai/VIEWER.md)·[FOOTER.md](./ai/FOOTER.md) → [examples/](./ai/examples)(공개 API만 쓰는 예제 A~J. B·F 파일명의 "Viewer"는 과거 이름이며 일반 모드 예제, 뷰어 모드는 H).

## Storybook (HMDesign 저장소)

SW Story는 40개입니다(`SW/Header` 20 · `SW/Footer` 6 · `SW/Popup` 3 · `SW/Viewer` 10 · `SW/Theme` 1, 2026-10-21 기준). 사이드바 기본 표시는 14개이고 나머지 26개는 `verification` 태그라 기본으로 숨겨지며 직접 URL·태그 필터로 엽니다.

- `SW/Header`: SW Header(`sw-header--overview`), Home Menu, Logo Slot, Responsive More (+ verification 16: Dropdown, Document Open, Hidden Sub Controls, Detail Buttons, Interactive States, Window Move Motion, Document Dropdown, K Guide, Home Menu 하위 8개)
- `SW/Footer`: SW Footer(`sw-footer--full-footer`), Responsive More (+ verification 4: 도구 그룹별 표시, Figma 디자인별 Variant, 도구 및 메뉴 변경 예제, 개별 부품)
- `SW/Popup`: Custom Content, Multiple Popups, Property Panel(Story ID `sw-header--property-panel-compare`)
- `SW/Viewer`: Viewer Header(기본 + 최소화·닫기 버전), Settings Popup(`sw-viewer--content-variants`), Responsive More, Logo (+ verification 6: Menu Groups, Item States, Header + Dropdown, Settings Popup(`sw-viewer--settings-panel`), Variable Size Popups, SWHeader vs Viewer Header(`sw-viewer--compare-with-sw-header`))
- `SW/Theme`: (verification 1: Theme Inheritance)

## 빌드 (HMDesign 저장소)

```bash
npm run build -w @hm-design/sw
npm run typecheck -w @hm-design/sw
```

`dist/styles.css`는 `src/theme/*.css`에서 만들어집니다. dist를 직접 편집하지 않습니다.

## 저장소 문서

아래 문서는 HMDesign 저장소에만 있고 npm 패키지에는 포함되지 않습니다(저장소 루트 기준 경로).

- 사용 가이드 `docs/sw/sw-header-usage.md`, 디자인 명세 `docs/sw/sw-header-design-spec.md`
- 뷰어 모드 기준 `docs/sw/sw-viewer-mode-2026-10-19.md`, Footer Figma 매핑 `docs/sw/sw-footer-figma-mapping-2026-10-20.md`
- 날짜별 구현·검증 기록 `docs/sw/*-YYYY-MM-DD.md`(작성 당시 기록이며, 현재 기준은 이 README와 `ai/` 문서)

## 변경 요약

- **2026-10-20:** `SWSlider`, `SWSelect`, `SWPopupPropertyRow` 추가(Popup 레이어·색상·선스타일 = 속성창 picker). `SWFooter*` 추가. SW 기본 글꼴 Noto Sans KR 확정, 같은 날의 Dotum 기본값 철회.
- **2026-10-19:** 0.2.0 통합 개선 — `SWPopup` / `SWPopupSection` / `SWPopupRow`, `SWToolButton` / `SWToolGroup`, `SWHeader`의 `documentOpenPlacement`·`leading`·`tools`, 실측 More. 로고 클릭 메뉴(`SWHomeMenu` 계열), 뷰어 모드(`SWViewer*`). AI 안내(`ai/`) 포함.
- **2026-10-16:** 색상·선/문자/치수스타일 Dropdown, 속성Bar·속성창(`SWHeaderPropertyBar`·`SWHeaderPropertyPanel`), `controls`·`hiddenControls`·`menuOrder`, K 가이드, 창 이동 Hover Motion(1.4초).