HMDesign/packages/sw

@hm-design/sw

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

설치·Import

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 §2, ai/DESIGN_RULES.md §3.
• SWHeader 밖에서 하위 컴포넌트를 쓰면 <SWTheme>로 감쌉니다. SWViewerHeader·SWViewerMenu·SWViewerPanel·SWFooter·SWFooterCommandLine은 자기 루트에 SW 범위를 가집니다.
• 토큰(--hm-sw-*) 변경은 가장 바깥 SW 범위(<SWTheme style>) 한 곳에서 합니다. Light/Dark 분기는 없습니다. 방법은 ai/AI_USAGE.md §3.1, 예제 ExampleJ-Theme.tsx.

SW 모드

한 화면에는 하나의 모드만 씁니다(Header 하나). 모드 선택 기준은 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
Footer	SWFooter, SWFooterLayoutTabs, SWFooterCommandLine과 부품 SWFooterSideButton·SWFooterAuxGroup·SWFooterAuxButton·SWFooterToolButton·SWFooterAddSlot·SWFooterGuide·SWFooterMenu(일반 모드 전용)	카탈로그 §10, ai/FOOTER.md
테마	SWTheme	위 "글꼴·테마"

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

AI 코딩 도구용 안내

다른 프로젝트의 AI 코딩 도구는 설치된 패키지의 ai/ 폴더를 먼저 읽습니다: AI_GUIDE.md(HMDesign 공통 진입점) → AI_USAGE.md(모드 선택·작업 순서·Import 규칙) → COMPONENT_CATALOG.md(공개 API) → DESIGN_RULES.md(토큰·상태) → COMPOSITION_PATTERNS.md(조합) → VIEWER.md·FOOTER.md → 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 저장소)

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초).