HMDesign/docs/sw/sw-header-home-menu-responsive-2026-10-19.md

# SW Header 홈 메뉴 통합 · 실측 More (2026-10-19)

> 브랜치 `feature/sw-home-menu`(기준 `c542bdc`, 작업 전 미커밋 `packages/sw/src/theme/sw-viewer.css` 3줄 보존). **Commit·Push 하지 않았습니다(승인 대기).**
> 검증: Storybook 개발 서버(포트 6025, 6024는 다른 세션이 사용 중)와 Claude 내장 브라우저(Chromium). 이 PC에는 기존 `*.browser.mjs`가 쓰는 Playwright 런타임이 없어 그 스크립트는 실행하지 않았습니다.

## 1. 요청과 결과

| 요청 | 결과 |
|---|---|
| `SW / Home Menu` 기능·디자인을 `SW / Header`로 통합 | `SW / Header` → `Home Menu`(`sw-header--home-menu`) 한 페이지에 로고 클릭 열기/닫기·이벤트 기록, 헤더 폭 조절, Figma 26:10591 비교, Default/Hover/Active, 최근파일 하위 패널, 속성창·SWPopup·Escape 통합. `Overview` 로고도 같은 홈 메뉴를 엶 |
| 홈 버튼 클릭 → 열림, 다시 클릭 → 닫힘 | 기존 `SWHeader homeMenu` 동작 그대로(코드 변경 없음). 5개 섹션·15개 타일·Hover·하위 패널 유지 |
| SW 일반 모드 전용 | `SWViewer*` 코드·Story 변경 없음. 뷰어 Story에 홈 메뉴 0개 |
| 반응형 더보기: 실제 사용 가능한 공간 기준, 넓어지면 원위치, 순서·기능 유지 | `SWHeader` 실측 More 추가(아래 §2). Breakpoint는 그대로 |
| 메뉴 열고 닫을 때 헤더 요소 위치·폭 유지 | 측정에서 positioned 층(Dropdown·홈 메뉴·More 목록·Tooltip) 제외. 열기/닫기 전후 좌표 동일 확인 |
| `SW / Home Menu` 사이드바 제거, 컴포넌트·Export·스타일·AI 지침 유지 | Story 파일을 `sw-header-home-menu.stories.tsx`로 옮기고 title `SW/Header`. `SWHomeMenu`·`SWRecentFiles`·Export·`sw-home-menu.css`(패키지)·AI 지침 삭제 없음 |

## 2. 실측 More 동작

- 기존 Breakpoint(1800 / 1180 / 1080 / 900 / 640 / 520)를 먼저 적용하고, 그 위에서 객체 수정 영역의 실제 남은 공간을 측정합니다.
- 측정: Layout Effect 안에서 `data-measuring`을 잠깐 붙여(그려지지 않음) 영역 안 요소가 줄거나 늘지 않고 auto margin이 0인 상태의 in-flow 폭을 읽습니다. 구성형 파일명은 최소 96px로 계산합니다.
- 이동 순서: Open(로고 오른쪽) → 선·문자·치수스타일 → 그리기모드 → 속성 블록 → 색상 → (구성형) 인쇄·K. 같은 단계는 오른쪽부터. 대표 칸은 이동하지 않습니다.
- 복귀: 옮긴 직후 생긴 공간을 한 번 측정해 두고 그만큼 공간이 생기면 역순으로 복귀. 기본 구성은 아무것도 옮기지 않으면 기존 CSS 전용 배치를 그대로 씁니다.
- 공개 API 변경 없음(추가 Prop 없음). 내부 상태·`data-squeezed` 속성·CSS만 추가.

## 3. 변경 파일

| 파일 | 내용 |
|---|---|
| `packages/sw/src/components/sw-header/SWHeader.tsx` | 실측 More(측정 함수·이동 순서·상태·Layout Effect), Open 이동 판정을 같은 측정으로 통일 |
| `packages/sw/src/theme/sw.css` | `data-measuring` 측정 규칙, 옮겨진 그리기모드·속성 블록 자리 보정 |
| `src/sw/sw-home-menu.stories.tsx` → `src/sw/sw-header-home-menu.stories.tsx` | title `SW/Header`, 대표 Story `Home Menu`, 나머지 `verification` 태그(`sw-header--home-menu-*`) |
| `src/sw/sw-header.stories.tsx` | `Overview`에 홈 메뉴 연결, `Responsive More`에 "실제 사용 가능한 공간 기준" 섹션 |
| `src/sw/sw-header-overview.tsx` | 선택 `homeMenuSections` Prop |
| `src/sw/sw-home-menu.css`, `src/sw/sw-stories.css` | Story 전용 폭 조절 컨트롤 배치 |
| `packages/sw/tests/home-menu-integration.browser.mjs`, `packages/sw/tests/storybook-inventory.mjs` | 새 Story ID·제목 기대값, 이동 ID 표 |
| `docs/sw/sw-header-design-spec.md` §12.1, `docs/sw/sw-header-usage.md`, `packages/sw/README.md`, `packages/sw/ai/DESIGN_RULES.md` §7, `packages/sw/ai/COMPONENT_CATALOG.md` | 실측 More·Storybook 위치 |

보존: `packages/sw/src/theme/sw-viewer.css`의 작업 전 미커밋 변경(`.hm-sw-viewer-menu-root { display: contents; }`)은 손대지 않았습니다. 과거 검증 보고서는 수정하지 않았습니다.

## 4. 검증

| 항목 | 결과 | 방법 |
|---|---|---|
| SW typecheck / 앱 `tsc -b` / SW build | PASS | `npm run typecheck -w @hm-design/sw`, `npx tsc -b`, `npm run build -w @hm-design/sw` |
| AI 문서 | PASS / 32/32 | `npm run check:ai-docs`, `node packages/sw/tests/ai-docs.check.mjs` |
| Storybook 메뉴 | PASS | `index.json`: SW title = Header·Popup·Viewer(`SW/Home Menu` 없음), `sw-header--home-menu` 표시, 홈 메뉴 하위 14개 `verification` |
| 기존 Header Story 배치 회귀 | PASS(기본 구성 변화 없음) | 작업 전 dist로 기록한 요소 좌표·폭과 비교: Overview·Interactive States·Logo Slot·Document Dropdown·Responsive More(19폭)·K Guide·Hidden Sub Controls 동일. 차이는 `Document Open`(§5)뿐 |
| 이동한 홈 메뉴 Story 배치 | PASS 18/18 | 옛 `sw-home-menu--*`와 새 `sw-header--home-menu-*` 6개 × 1920/1280/768 좌표 동일(메뉴 x·폭 포함) |
| 홈 메뉴 열기/닫기 | PASS | 로고 클릭 → 메뉴 1·섹션 5·타일 15·`aria-expanded=true`·Focus 메뉴 안, 재클릭 → 닫힘, `onHomeClick` 미호출, 열기/닫기 전후 Header 좌표 동일. `Overview`에서도 열기/닫기 확인 |
| Hover·하위 패널·Escape | PASS | 실제 포인터 Hover 시 라벨 `#FF5C00`, 최근파일 → 하위 패널·outline 강조, Escape 1회 패널만 닫힘, 2회 메뉴 닫힘·로고로 Focus |
| 좁은 화면 더보기 · 폭 변경 재배치 | PASS | `Responsive More` 실측 섹션(로고 오른쪽 버튼 2개 + 도구 1개): 1920→390 축소 시 치수 → 문자 → 그리기모드 → 속성 블록 → 색상 순 이동, 겹침·가로 스크롤 0(520까지), 390→1920 확대 시 역순 복귀, 추가 요소 끄면 기본 CSS 배치로 복귀 |
| 더보기 안 메뉴 선택 · 팝업 | PASS | 1180: More 목록 = 선/문자/치수스타일·속성Bar·속성창(순서 유지). 속성창 → 팝업(`role=dialog`) 열림·Focus 안, Escape 닫힘·More로 Focus 복귀. 선스타일 → 대표 칸·Dropdown 열림·Focus, 레이어는 More로 |
| 헤더 요소 위치·폭 유지 | PASS | More 열기, 속성창 열기/닫기, 홈 메뉴, 레이어 Dropdown, 문서 Dropdown 각각 전후 좌표 동일 |
| SW 뷰어 모드 영향 | PASS | 뷰어 코드·Story diff 없음, `SW/Viewer` 3개 Story 렌더 오류 0·홈 메뉴 0 |
| Storybook production build | PASS | `npm run build-storybook`(인덱스 358개, SW title = Header·Popup·Viewer, `SW/Header` 27개) |

참고: 내장 브라우저 창이 숨겨진 상태라 ResizeObserver가 프레임이 그려질 때만 실행됩니다. 폭 변경 검증은 각 단계마다 화면 프레임을 갱신한 뒤 측정했습니다.

## 5. 의도된 배치 변화 (`Document Open` Story)

로고 오른쪽 Open을 쓰는 기본 구성은 작업 전 아래 폭에서 실제로 겹쳤습니다(기존 판정이 `scrollWidth`만 봐서 감지 못함). 이제 Open(필요하면 메뉴 1개)이 More로 이동합니다.

| 프레임 | 작업 전 | 작업 후 |
|---|---|---|
| 1800 | 치수스타일이 속성 블록과 겹침 | Open·치수스타일 → More |
| 1180 / 1080 | 색상이 More와 겹침 | Open → More |
| 900 | 색상이 More와 3px 겹침 | Open → More |
| 640 | 레이어가 More와 겹침 | Open → More |
| 구성형 768 | Open이 More에 있음 | Open 표시(파일명 200px ≥ 최소 96px) |

## 6. NOT VERIFIED · 한계

- 기존 Playwright 스크립트(`home-menu-integration.browser.mjs` 등): 이 PC에 런타임 없음. ID만 갱신했고 실행하지 않았습니다.
- Firefox·Safari, 실제 소비 앱(`HMDesignSwTest`) 재검증, 픽셀 단위 스크린샷 비교(좌표·폭 비교로 대신함).
- 호스트 요소(`leading`·`tools`)는 More로 옮기지 않습니다. 390px에 로고 오른쪽 버튼 2개 + 도구를 함께 넣으면 대표 필드가 0까지 줄고 도구와 More가 겹칩니다(옮길 메뉴가 더 없음).
- 기존 동작 관찰(이번 변경과 무관, 수정하지 않음): 홈 메뉴에서 Escape로 닫을 때 Story 기록에 `onHomeMenuOpenChange(false, escape)`·`onActiveChange([])`가 2회씩 남습니다. 이전 Story(`sw-header--home-menu-header-composition`, 구 `sw-home-menu--header-composition`)에서도 같습니다.