HMDesign/packages/sw

@hm-design/sw

0.2.0 통합 개선(2026-10-19): 패키지에 포함된 AI 안내 ai/AI_USAGE.md·카탈로그가 공개 API의 기준입니다. 추가: SWPopup / SWPopupSection / SWPopupRow(속성창 외형 + children 자유 콘텐츠, 여러 Popup Escape 스택, Popup 안 Dropdown 고정 Overlay), SWHeaderPropertyPanel의 children·title·autoFocus와 선택형 selection/properties/groups, SWToolButton / SWToolGroup(기존 글자 토글·pill·파일명 면 재사용), SWHeader의 documentOpenPlacement(로고 오른쪽 Open, 실측 기반 More 이동)·leading, hiddenControls의 documentNew·documentOpen·layerFreeze·layerLock, showNew/showOpen/showFreeze/showLock. 모두 선택 Props이며 기존 화면은 그대로입니다. 빌드는 줄바꿈 정규화로 재현 가능하고 dist/build-info.json에 출처 Commit·도구 버전을 남깁니다. 검증 기록: 저장소 docs/sw/sw-integrated-improvement-2026-10-19.md.

로고 클릭 메뉴(2026-10-19): SWHomeMenu / SWHomeMenuSection / SWHomeMenuItem / SWRecentFiles(Figma 26:10591 2단 Header 메뉴, 최근파일 하위 패널)와 SWHeader의 homeMenu·homeMenuOpen·defaultHomeMenuOpen·onHomeMenuOpenChange. 기본 숨김 → 로고 클릭 열기 → 다시 클릭 닫기, 위치는 Header DOM 측정. homeMenu가 있으면 로고 클릭은 onHomeClick을 호출하지 않습니다. 모두 선택 Props이며 주지 않으면 기존 화면 그대로입니다(카탈로그 5절, 예제 G). 검증 기록: 저장소 docs/sw/sw-home-menu-integration-2026-10-19.md.

현재 기준 색인(2026-10-19 1차 정리): 아래 날짜별 안내는 작성 당시 기록입니다. 현재 기준은 사용 가이드, 디자인 명세 상단 색인, 속성 필드 13개 검증 기록, 게이지·속성Bar 후속 4건 기록·Firefox 게이지 기록입니다. Storybook은 SW / Header 33개 Story이며 전체 목록과 2차 검토 대상은 1차 정리 보고에 있습니다.

3차 구현(2026-10-16): hiddenControls(로고 외 모든 구성요소 개별 제거, 로고 필수), menuOrder(레이어·색상·선/문자/치수스타일 순서), 속성창 shapeContent Slot, 속성창 4상태 개별·비교 Story를 추가했습니다. 미지정 시 기존 디자인과 같습니다. 사용법, 3차 검증 기록.

후속 구현(2026-10-16): 속성Bar(SWHeaderPropertyBar), 메뉴 단위 controls allowlist, Colorize 원본 Default/Hover를 추가했습니다. 상세 pill의 미사용 Stroke 선언·변수는 원본에서 제거했습니다. 사용법, 새 검증 기록을 따릅니다. 이전 설명과 PASS 로그는 보존합니다.

최신 추가 구현(2026-10-16): 상세 5개 Hover·색상 기준 필수 선택·목록 Hover/Selected 통일·데이터 기반 속성창·K 가이드 반복을 제공합니다. 아래 추가 연결과 현재 검증 보고를 따릅니다. 아래의 이전 Hover 없음·일반 자기 색 Stroke 설명은 추가 기준으로 대체됩니다.

HM Design System의 SW(설치형·도면 SW) 전용 React 컴포넌트 패키지입니다. @hm-design/ui와 독립적으로 빌드·배포·사용하며 서로 의존하지 않습니다.

현재 포함: SW Header (Figma rj6wpsfk24lOWvWiVRAANP node 26:8944 header_green), SWTheme.

import { SWHeader } from "@hm-design/sw"
import "@hm-design/sw/styles.css"

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

• 로고는 확정 디자인이 아닙니다. 로고 영역 배치는 공통이고 로고 이미지는 각 SW 프로그램이 logoSrc 또는 logo로 전달합니다. 패키지에는 로고가 없으며, 전달하지 않으면 로고 없이 표시됩니다.

• 파일명을 클릭하면 문서 Dropdown(Figma 26:10662)이 열립니다. 목록은 documents, 선택·New·Open은 Callback으로 각 프로그램이 연결합니다(documents 미전달 시 Dropdown 없음).

• 레이어 필드를 클릭하면 레이어 Dropdown(Figma 26:10940, 갈색 목록·주황 행 Hover)이 열립니다. 목록은 layers(id, name, color, visible, frozen, locked, disabled), 현재 레이어는 activeLayerId이며 선택은 onLayerSelect, 전구·눈꽃·자물쇠는 onLayerVisibilityChange / onLayerFreezeChange / onLayerLockChange, 하단 버튼은 onLayerDetail로 각 프로그램이 연결합니다. 아이콘은 데이터만 반영하며 실제 표시·동결·잠금은 호스트가 처리합니다(layers 미전달 시 기존 필드 버튼). 확정 매핑: 전구 컬러 visible=true·회색 false, 눈꽃 컬러 frozen=false·회색 true, 자물쇠 컬러 locked=false·회색 true이며 클릭 시 각 boolean의 반전값을 전달합니다(명세 §5.2, 검증 기록).

• Hover는 Figma 홈 버튼의 노란 gradient 1px 테두리를 SW Header의 테두리 있는 버튼에 공통 적용합니다(디자인 명세 §11.1).

• 창 이동 Hover Motion은 GIF의 경로를 유지하고 후속 사용자 요청으로 1.64 → 1.4초로 단축했습니다. 커서 상승 → 약 444ms 문구 등장 → 오른쪽 위로 이동 → 약 888ms부터 512ms 유지 → 반복입니다. 기존 SVG·줄무늬·Tooltip·onWindowMoveStart·Drag 중 정지·Reduced Motion·88px/24px/숨김 정책은 유지합니다. 실제 창 이동은 호스트 책임이며 사용 가이드 §10.2, 현재 검증 기록을 따릅니다.

• 그룹 필드 Hover는 텍스트와 선/폰트/치수 미리보기를 #FFC600으로 표시합니다. 기존 Gradient Border·검정 외곽선·색상 견본·레이어 상태·Disabled/Selected 정책을 유지하며 상세보기는 기존 텍스트 전용 Hover 그대로입니다(명세 §11.5).

• 색상·선스타일·문자스타일·치수스타일 Dropdown(2026-10-16, Figma 26:10986 / 26:11036 / 26:12666 / 26:12659 / 26:11104 / 26:10702 / 26:11181 / 26:11215): colors·userColors·colorMode, lineTypes·lineWeights, textStyles, dimensionStyles를 주면 각 필드가 Dropdown이 됩니다(주지 않으면 기존 버튼). 모든 항목은 id 기반 배열 Props이며 추가·삭제·이름/값 변경·재정렬에 소스 수정이 필요 없습니다. 선택·입력은 onColorSelect / onColorModeChange / onColorInput / onColorPick, onLineTypeSelect / onLineWeightSelect / onLineWeightValueChange / onLineScaleChange, onTextStyleSelect, onDimensionStyleSelect, 하단 … 상세는 on*Detail로 각 프로그램이 연결합니다(상세 팝업은 미제공). Dropdown 안 독립 버튼은 Hover 효과가 없고 목록 행·Input은 Figma Hover를 유지합니다(이후 2026-10-16 추가 수정: ByLayer/ByBlock·… 상세 버튼은 Figma Hover 적용, 색상 추출은 Colorize Hover, 색상 칩은 Hover 없음)(명세 §5.3, 사용 가이드 §7).

  <SWHeader
    documentTitle={fileName}
    color={color} colors={palette} userColors={userColors} colorMode={colorMode}
    onColorSelect={option => applyColor(option)} onColorModeChange={setColorMode} onColorInput={({ hex }) => applyHex(hex)}
    lineStyle={lineStyle} lineTypes={lineTypes} lineWeights={lineWeights}
    onLineTypeSelect={type => setLineStyle(s => ({ ...s, name: type.name }))}
    textStyle={textStyle} textStyles={textStyles} onTextStyleSelect={style => setTextStyle(style)}
    dimensionStyle={dimensionStyle} dimensionStyles={dimensionStyles} onDimensionStyleSelect={style => setDimensionStyle(style)}
  />
  

• 반응형 More: 좁은 헤더에서 더보기의 필드를 고르면 그 필드가 첫 칸(레이어 자리)에 표시되고 Dropdown이 바로 아래 열립니다. 레이어는 더보기에서 다시 고를 수 있으며, 전환은 UI 상태라 데이터 Callback을 호출하지 않습니다(명세 §5.4).

• Text Stroke: Figma에 Stroke가 있는 텍스트만 검정 외곽선(14·16px 1.3px, 12px 1px)을 표시합니다. 자기 색 0.3px Stroke는 2026-10-16 추가 수정으로 제거했습니다. 더보기·Tooltip·+ New/Open은 제외(명세 §6.1).

• SWHeaderInput: 레이어 상세 등 상세 영역에서 쓰는 수정 가능 Input(Figma 26:11656, Default / Hover / 편집, caret #E60403). value(확정값) · onValueChange(임시값) · onCommit(Enter·Focus 이동, 유효 + 변경 시) · onCancel(Escape) · valueType(text / number) · parse · readOnly · disabled(명세 §5.5).

• Peer: react, react-dom ^19.0.0. 런타임 dependency는 없습니다.

• 출력: dist/index.js(ESM, Figma SVG asset은 data URI로 포함, 임시 Figma URL 없음), dist/*.d.ts, dist/styles.css.

• CSS는 자동 import되지 않습니다. @hm-design/sw/styles.css를 한 번 import합니다.

• Registry에는 아직 게시하지 않았습니다. 설치·사용·Props는 사용 가이드, 디자인 기준은 디자인 명세를 따릅니다.

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

추가 연결: 속성창·K 가이드 (2026-10-16)

• SWHeaderPropertyPanel 및 property/group/selection 타입을 공개합니다. SWHeader.propertyPanel에 외부 데이터를 전달하면 기존 속성창 버튼·More와 연결됩니다.
• propertyPanelOpen/onPropertyPanelOpenChange로 Controlled 열림을 지원하며, 생략하면 내부 열림 상태를 사용합니다. 기존 onPropertyPanelToggle을 보존합니다.
• Text/Number/Select/Color/Slider/Computed, id 기반 동적 항목, 검증·확정·취소·외부 변경·ReadOnly/Disabled·그룹 펼침을 지원합니다. CAD 계산·선택·객체 변경은 호스트가 담당합니다.
• 상세 5개는 Figma 고정 크기와 Hover를 적용합니다. ByLayer/ByBlock은 정확히 하나가 표시되며, 기존 null 직접 색상 의미는 보존합니다. 레이어/선/문자/치수 목록은 Hover와 Selected 디자인이 같습니다.
• K는 기존 버튼을 재사용하고 원본 이미지 Pan/Zoom을 반복합니다. 640px 미만에서는 기존 More 항목에서도 같은 가이드를 표시합니다. Reduced Motion은 정적 이미지이며 기존 창 이동 1400ms는 유지합니다.
• 지정된 일반 text-stroke-width 선언·변수는 제거했고 검정 text-shadow와 상세 pill의 별도 Stroke는 보존했습니다(상세 pill Stroke도 아래 후속 5개 요구사항에서 제거됨).
• 사용 예시와 API는 가이드 추가 절, 디자인 값은 명세 추가 절을 확인하세요.
• 검증: 기존 17 + 신규 4 Story, 현재 실행 결과 및 NOT VERIFIED. 과거 로그는 보존합니다.

후속 5개 요구사항 API (2026-10-16)

• SWHeaderPropertyBar / SWHeaderPropertyBarProps를 공개합니다. propertyBar로 selection/properties/onPropertyChange와 readOnly/disabled를 전달합니다. 속성창과 SWHeaderProperty/Selection 데이터를 공유하며, propertyBarOpen/defaultPropertyBarOpen/onPropertyBarOpenChange는 별도의 표시 상태입니다. 최대 폭 1222·높이 28px이고 Header 49px 아래에 표시됩니다.
• SWHeaderControlId / SWHeaderControlConfig / SWHeader.controls는 메뉴 자체의 전체 allowlist입니다. undefined는 기존 기본 구성, []는 선택적 컨트롤 없음입니다. id/visible/label과 배열 순서로 제거·복원·변경·재배치하며 More도 동일 구성을 따릅니다. 내부 옵션 배열·선택값 Props는 그대로입니다.
• Text Stroke Story의 지정 원본 이미지 블록·전용 import를 제거했습니다. 원본 PNG와 다른 비교 Story는 보존합니다.
• 상세 span의 -webkit-text-stroke-width와 미사용 --hm-sw-header-solid-stroke-width를 src/theme/sw.css에서 제거했습니다. build는 이 원본에서 dist/styles.css를 만드므로 dist만 편집하지 않습니다. 검정 text-shadow·SVG Stroke·상세 Hover는 보존합니다.
• 색상 추출 버튼은 로컬 Figma Default/Hover SVG를 사용합니다(24px/18px). 기존 onColorPick은 그대로이며 Hover는 Callback을 실행하지 않습니다. 26:11338 돋보기 Overlay는 호스트 연동 대상입니다.
• Storybook은 기존 21개와 신규 Property Bar / Dynamic Controls / Colorize, 총 24개입니다. 최신 검증 기록을 참조하세요.

3차 API (2026-10-16)

• SWHeader.hiddenControls?: readonly SWHeaderHideableControlId[] — SWHeaderControlId + SWHeaderFrameControlId(home / windowMove / minimize / close). 로고는 항상 표시하며 home 제거 시 정적 로고입니다. 제거한 요소는 공간·Popup·Callback이 없습니다.
• SWHeader.menuOrder?: readonly SWHeaderMenuId[] — 5개 유사 메뉴끼리만 순서 변경. 지정 id 우선, 누락 id는 기본 순서로 뒤에, 중복·알 수 없는 id 무시. More 목록도 같은 순서입니다.
• SWHeaderPropertyPanelProps.shapeContent?: SWHeaderPropertyShapeContent — undefined Figma 원형, null/false 빈 208×208 영역, ReactNode 또는 (context: SWHeaderPropertyShapeContext) => ReactNode. SWHeader.propertyPanel로도 전달됩니다.
• 하위 공개 컴포넌트에 선택적 표시 Props 추가(기본 true): SWHeaderHome.interactive, SWHeaderProperties.showCaption/showBar/showPanel, SWHeaderActions.showPrint/showPopupGuide, SWHeaderWindowControls.showWindowMove/showMinimize/showClose.
• Storybook: 기존 24개 + Composition, Property Panel 개별 4개, 4개 비교, 형상 Slot = 31개.

속성 필드·게이지 (2026-10-19)

• 속성창 공통 행은 Figma 26:12388 ~ 26:12649의 Default / Hover / On을 따릅니다. 숫자는 편집 On(#0F0D0A), 레이어·선스타일·색상은 Dropdown On(#211D13)이며 하이퍼링크·재료는 Default·Hover만 있습니다.
• 추가 API(모두 선택): SWHeaderProperty.picker("layer" | "lineStyle" | "color" | false), SWHeaderProperty.decimals, SWHeaderPropertyPanelProps.menus(SWHeaderPropertyMenus). 필드 Dropdown은 Header Dropdown과 같은 목록 컴포넌트를 씁니다. 사용법, 검증 기록.
• 투명도 게이지는 빨강 채움 + 베이지 Track이며 Chrome·Firefox가 같은 그림을 씁니다(Firefox 게이지 기록).

AI 코딩 도구용 가이드 (2026-10-19)

다른 프로젝트에서 AI 코딩 도구가 이 패키지를 재사용·조합·확장할 때는 설치된 패키지의 ai/ 폴더를 먼저 읽습니다: AI_GUIDE.md(HMDesign 공통 진입점: Web / SW / OrgChart / 혼합 선택, 패키지 분리, 결과 보고. 모든 HMDesign 패키지에 같은 사본, 2026-10-19 추가) → AI_USAGE.md(작업 순서·Import 규칙) → COMPONENT_CATALOG.md(공개 API) → DESIGN_RULES.md(토큰·상태·Motion) → COMPOSITION_PATTERNS.md(조합 방법) → examples/(공개 API만 쓰는 예제 A~D). ai/는 npm 패키지(files)에 포함됩니다. 런타임 API는 바뀌지 않았습니다.