HMDesign/packages/sw/ai/COMPONENT_CATALOG.md

@hm-design/sw 컴포넌트 카탈로그

기준: @hm-design/sw 0.1.0, dist/index.d.ts 공개 Export(2026-10-19). 모든 Import는 from "@hm-design/sw"이며 CSS는 @hm-design/sw/styles.css 한 개입니다. 이 표에 없는 이름은 공개 API가 아닙니다.

• 단독 사용: SWHeader 밖에서는 <SWTheme> 안에 둡니다(토큰·글꼴·버튼 초기화).
• 상태 소유: 값은 Props, 사용자 행동은 Callback입니다. 컴포넌트는 CAD 데이터를 바꾸지 않습니다. 호스트가 Callback을 받아 Props를 갱신합니다.
• 열림 상태: Dropdown은 open / onOpenChange(Controlled)를 주지 않으면 내부 상태로 동작합니다.
• 공통 키보드: Click·Enter·Space 열기/닫기(Hover로는 열리지 않음), ArrowDown 열고 첫(현재) 항목 Focus, Arrow 이동, Escape·바깥 클릭·Tab 이탈 닫기(Escape는 Trigger로 Focus 복귀).
• 검증 표시: ✅ = 2026-10-19 독립 소비 프로젝트(Tarball 설치)에서 브라우저 검증, ◻ = 이번 소비 검증 범위 밖(기존 Storybook 검증 기록만 있음).

1. 완성형 템플릿

SWHeader ✅

SW 공식 기준 Header(Figma 26:8944, 1920 × 49). 로고 · 파일 · 객체 수정 영역(그리기모드, 레이어/색상/선/문자/치수스타일, 상세보기) · 창 영역(인쇄·K, 창 이동, 최소화, 종료)과 반응형 More, 속성Bar, 속성창을 포함합니다.

구분	Props / Callback
필수	documentTitle: string
구성	hiddenControls?: SWHeaderHideableControlId[](로고 외 부품 제거, home 제거 시 정적 로고), menuOrder?: SWHeaderMenuId[](5개 메뉴끼리 순서), controls?: SWHeaderControlConfig[](객체 영역 전체 allowlist·순서·label)
로고	logo?: ReactNode, logoSrc?: string, logoAlt?: string, onHomeClick
파일	documents, activeDocumentId, documentMenuOpen, onDocumentMenuOpenChange, onDocumentSelect, onDocumentClose, onDocumentNew, onDocumentOpen, onDocumentClick, documentIcon, documentNewLabel, documentOpenLabel
레이어	layer, layers, activeLayerId, layerMenuOpen, onLayerMenuOpenChange, onLayerSelect, onLayerVisibilityChange, onLayerFreezeChange, onLayerLockChange, onLayerDetail, onLayerOpen
색상	color, colors, userColors, colorMode, colorMenuOpen, onColorMenuOpenChange, onColorSelect, onColorModeChange, onColorInput, onColorPick, onColorDetail, onColorOpen
선스타일	lineStyle, lineTypes, lineWeights, activeLineTypeId, activeLineWeightId, lineStyleMenuOpen, onLineStyleMenuOpenChange, onLineTypeSelect, onLineWeightSelect, onLineWeightValueChange, onLineScaleChange, onLineStyleDetail, onLineStyleOpen
문자/치수	textStyle, textStyles, activeTextStyleId, textStyleMenuOpen, onTextStyleMenuOpenChange, onTextStyleSelect, onTextStyleDetail, onTextStyleOpen / dimensionStyle, dimensionStyles, activeDimensionStyleId, dimensionStyleMenuOpen, onDimensionStyleMenuOpenChange, onDimensionStyleSelect, onDimensionStyleDetail, onDimensionStyleOpen
상세	propertyBar, propertyBarOpen, defaultPropertyBarOpen, onPropertyBarOpenChange, onPropertyBarToggle, propertyPanel, propertyPanelOpen, onPropertyPanelOpenChange, onPropertyPanelToggle
창	onPrint, onPopupGuide, onWindowMoveStart(PointerEvent), onMinimize, onClose
기타	activeMenu, disabled(창 버튼 제외), drawingModeLabel, tools?: ReactNode(객체 영역 메뉴 뒤), <header> HTML 속성·ref

• 데이터 배열(layers, colors, lineTypes/lineWeights, textStyles, dimensionStyles, documents)을 주지 않으면 해당 필드는 Dropdown 없는 버튼입니다.
• 반응형(More·대표 필드 전환·창 영역 축소)은 SWHeader 안에서만 동작합니다(CSS container hm-sw-header).

<SWHeader documentTitle={name} logoSrc={logo} logoAlt="제품명" layers={layers} activeLayerId={id} onLayerSelect={l => setId(l.id)} onClose={closeWindow} />

2. 개별 컨트롤 (조합용)

컴포넌트	용도	주요 Props / Callback	크기(Figma)	상태	검증
SWTheme	단독 사용 범위(토큰·글꼴·초기화). 배치는 정하지 않음	div HTML 속성, className, style(토큰 override)	—	—	✅
SWHeaderHome	로고 슬롯 + 홈 버튼	logo, logoSrc, logoAlt, onClick, interactive(false = 정적 로고)	80 × 48, 로고 슬롯 32 × 17, 오른쪽 −17px로 다음 파일 면과 겹침	Hover 배경 교체, Focus	✅
SWHeaderDocumentTitle	파일명 + 문서 Dropdown(+ New / Open)	title(필수), documents, activeDocumentId, menuOpen, onMenuOpenChange, onDocumentSelect, onDocumentClose, onNew, onOpen, onClick, documentIcon, newLabel, openLabel, label	높이 48, 폭 190–310(반응형 clamp), 메뉴 310	텍스트만 Hover #FFC600, 열림 화살표 회전	✅
SWHeaderLayerMenu	레이어 필드 + Dropdown	value(필수), layers(필수), activeLayerId, open, onOpenChange, onClick, selected, disabled, onLayerSelect, onVisibilityChange, onFreezeChange, onLockChange, onDetail, label	필드 234 × 38, 메뉴 234	Hover 링, Selected, Expanded, 행 Hover	✅
SWHeaderColorMenu	색상 필드 + Dropdown(ByLayer/ByBlock, 팔레트, 사용자 색, 추출, RGB 입력)	value, colors(필수), userColors, mode, open, onOpenChange, onClick, selected, disabled, onColorSelect, onModeChange, onColorInput, onPick, onDetail, label	필드 192 × 38	칩 선택 시 열림 유지	✅
SWHeaderLineStyleMenu	선스타일 필드 + 3열 Dropdown	value, lineTypes, lineWeights, activeLineTypeId, activeLineWeightId, open, onOpenChange, onClick, selected, disabled, onLineTypeSelect, onLineWeightSelect, onLineWeightValueChange, onScaleChange, onDetail, label	필드 284 × 38, 열 182·142·142(필드 중앙 정렬)	열별 선택, 열림 유지	✅
SWHeaderTextStyleMenu	문자스타일 필드 + 목록	value, textStyles(필수), activeTextStyleId, onTextStyleSelect, open, onOpenChange, onClick, selected, disabled, onDetail, label	필드 164 × 38	선택 시 닫힘	✅
SWHeaderDimensionStyleMenu	치수스타일 필드 + 목록	value, dimensionStyles(필수), activeDimensionStyleId, onDimensionStyleSelect, 열림·onDetail·label 동일	필드 164 × 38	선택 시 닫힘	✅
SWHeaderLayerControl · SWHeaderColorControl · SWHeaderLineStyle · SWHeaderTextStyle · SWHeaderDimensionStyle	Dropdown 없는 필드 버튼(호스트가 자체 팝업을 열 때)	value(필수), label, selected, disabled, onClick, expanded, controls, buttonRef / SWHeaderLayerControl은 state(표시·동결·잠금)	위 필드 크기와 같음	Hover 링, Selected	◻
SWHeaderActions	인쇄·K 버튼 pill	onPrint, onPopupGuide, disabled, showPrint, showPopupGuide(하나만 남기면 pill이 축소)	pill 85 × 42(버튼 40 × 38)	아이콘 Hover, Hover 링, K 가이드 미리보기(반복 Motion, Reduced Motion 정적)	✅
SWHeaderWindowControls	창 이동·최소화·종료	onWindowMoveStart, onMinimize, onClose, showWindowMove, showMinimize, showClose	이동 88 × 48, 버튼 32 × 48	창 이동 Hover Motion 1.4s, 종료 Hover 자산	◻
SWHeaderProperties	상세보기 / 속성Bar · 속성창 토글	barOpen, panelOpen, panelId, disabled, onBarToggle, onPanelToggle, showCaption, showBar, showPanel	157 × 38	텍스트 Hover #FFC600	◻
SWHeaderPropertyBar	28px 속성 편집 띠	selection, properties, onPropertyChange, readOnly, disabled, div 속성	높이 28, 콘텐츠 폭	Input 상태	◻
SWHeaderPropertyPanel	속성창(13개 필드 타입, 그룹, 형상 Slot)	selection, properties, groups, onPropertyChange, menus, expandedGroupIds/defaultExpandedGroupIds/onExpandedGroupsChange, toolActive/onToolActiveChange, toolLabel, onOverviewClick, shapeContent, onClose, id, anchorRef, style	고정 위치 Overlay(Portal·Dim 없음)	4가지 선택 상태	◻
SWHeaderInput	수정 가능한 SW Input	value(필수), onValueChange, onCommit(Enter·Blur, 유효 + 변경 시), onCancel(Escape 복원), valueType(text/number), parse, readOnly, disabled, commitOnUnmount, input 속성	58 × 20 기준, Hover/편집 24px	Default/Hover/편집/ReadOnly/Disabled, IME 조합 중 Enter 무시	✅
parseSWHeaderColor · parseSWHeaderNumber	Input 검증 도우미	r,g,b / #rrggbb, 숫자(min, max)	—	—	◻
SWHeaderLinePreview · swHeaderLinePatterns	70 × 2 선 미리보기, CENTER/HIDDEN 패턴	pattern?: number[]	70 × 2	—	◻(패턴 상수만 예제 데이터에서 사용)

3. 공개 타입

SWHeaderProps, 각 컴포넌트 *Props, SWThemeProps, SWHeaderMenuId, SWHeaderControlId, SWHeaderControlConfig, SWHeaderFrameControlId, SWHeaderHideableControlId, SWHeaderDocument, SWHeaderLayer, SWHeaderLayerValue, SWHeaderColorValue, SWHeaderColorOption, SWHeaderColorMode, SWHeaderColorInputValue, SWHeaderLineStyleValue, SWHeaderLineType, SWHeaderLineWeight, SWHeaderTextStyleValue, SWHeaderTextStyleOption, SWHeaderDimensionStyleValue, SWHeaderDimensionStyleOption, SWHeaderInputValueType, SWHeaderProperty, SWHeaderPropertyType, SWHeaderPropertyPicker, SWHeaderPropertyMenus, SWHeaderPropertyGroup, SWHeaderPropertySelection, SWHeaderPropertyShapeContent, SWHeaderPropertyShapeContext.

4. 공개하지 않은 것 (사용 금지)

SWHeaderMore, SWHeaderField/SWHeaderFieldText, SWHeaderKGuide, useSWHeaderDropdown, SWHeaderMenuDetail, SWHeaderColorChip, SWHeaderLayerRows, SWHeaderColorPanelBody, SWHeaderLineStyleColumns, 속성창 내부 Picker, useSWHeaderOverlay 등은 내부 구현입니다. 필요하면 공개 컴포넌트로 대체하거나, 부족한 API로 보고합니다.

5. 알려진 단독 사용 제약

항목	내용	대응
반응형 More	SWHeader 전용. 조합 Header에서는 More·필드 이동이 없음	조합 Header의 폭은 소비 앱이 정함(필요 없는 컨트롤을 빼거나 가로 공간 확보)
SWHeaderDocumentTitle 왼쪽 테두리	앞의 로고와 겹치는 전제로 왼쪽 테두리가 없음	로고 없이 첫 칸이면 소비 레이아웃 wrapper에 1px 테두리(예제 C)
SWHeaderDocumentTitle 폭	clamp(190px, 100cqw − 1610px, 310px); Header 밖에서는 cqw가 뷰포트 기준	flex 부모 안에 둔다. 1920 뷰포트에서 310px
창 영역 배경	배경·테두리는 SWHeader의 창 영역에 있음	소비 레이아웃이 토큰으로 표면 작성(예제 B·C)
Dropdown 위치	SWHeader 안이면 헤더, 밖이면 뷰포트 안으로 좌우 보정	부모에 overflow: hidden을 두지 않는다