shkim4/HMDesign
Private
Public Access
1
0 Fork 0
Code Activity
Files
c7f29b01420491c461a558e35a7ca3d09b052dfe
HMDesign/docs/sw/sw-viewer-logo-document-menu-2026-10-21.md
T
shkim4 23d522c136 feat(sw): viewer header logo menu and file list; simplify SW Storybook 
SW Viewer Header (approved optional props, public export names unchanged at 170):
- SWViewerHeader: logoMenu, documents, activeDocumentId, onDocumentSelect,
  onDocumentOpen, documentOpenLabel; measured responsive toggles (full ->
  icons -> More) with the SWHeader More / file-list styling.
- SW AI guides, ExampleH, viewer/text-weight/theme-inheritance tests and the
  logo-document-menu tests with their QA record.

SW Storybook cleanup (Story IDs and test fixtures kept):
- Sidebar: Overview -> "SW Header" (first), 전체 Footer -> "SW Footer",
  Footer/Viewer responsive pages -> "Responsive More", Viewer content-variants
  -> "Settings Popup" (merges the settings popup page).
- Hidden by the verification tag (direct URL kept): Header Dropdown,
  Document Open, Interactive States, Document Dropdown, Hidden Sub Controls,
  Home Menu standalone; Footer tool groups / custom content / parts;
  SW/Theme; Viewer menu groups / item states / variable size / settings
  panel / Header + Dropdown.
- Removed demo UI: Overview size and callback output (demo data and
  selection only with &verification), Home Menu Figma node table and width
  demo, Header Responsive More reduced to 1440 / 768 / 390, Popup reopen
  button, property-panel comparison captions, Viewer context-menu demo
  (&verification only).
- Tests: storybook-inventory records the hidden and renamed Stories;
  overview / range-cross-browser / viewer open the demo controls with
  &verification; integrated-popup reloads the Story instead of the reopen
  button; dropdown-consolidation asserts Dropdown is hidden from the sidebar
  and still opens by its direct URL.
2026-10-21 14:52:46 +09:00

110 lines
16 KiB
Markdown
Raw Blame History

# SW Viewer Header — 로고 파일 열기 메뉴 · 파일명 샘플 목록 · 반응형 (2026-10-21)
기준: `main` 46119ea (미커밋 작업). 승인 범위: `SWViewerHeader` optional Props `logoMenu`, `documents`, `activeDocumentId`, `onDocumentSelect` 추가.
## 1. 동작
| 클릭 대상 | 표시 | 재사용 |
|---|---|---|
| Viewer 로고 | 로고 아래 파일 열기 메뉴(Open) | `SWHeaderMore`(SWHeader 반응형 `...` 메뉴) — 같은 면·행·Hover·Escape·바깥 클릭·ArrowUp/Down |
| 파일명 | 파일명 아래 샘플 문서 목록 | `SWHeaderDocumentTitle`(SWHeader 파일명 목록) `showNew={false}` `showOpen={false}` |
| 메뉴의 Open | 기존 파일 열기 명령(`onSelect` → `onCommand({ id: "open", itemId: "open" })`) | — |
| 샘플 항목 | `onDocumentSelect` → 프로그램이 불러오고 `documentTitle`·`activeDocumentId` 갱신 | — |
- 로고 메뉴와 파일명 목록은 하나의 상태(`openMenu`)로 제어해 동시에 열리지 않습니다(포인터·키보드 모두).
- 로고 메뉴: `title`과 보이는 항목이 모두 있을 때만 타이틀 + 구분선, `title`이 없으면 항목만, 보이는 항목이 없으면 메뉴·버튼을 만들지 않고 기존 로고(`onHomeClick`)로 둡니다. `logoMenu`는 `onHomeClick`보다 우선합니다.
- 로고 버튼: `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`, ArrowDown = 첫 항목 Focus, 선택·Escape 후 로고로 Focus 복귀.
- `SWHeaderMore`(내부, 미공개)에 `renderTrigger`·`title`·`label`·`open`/`onOpenChange`·`align`·`className`을 추가했습니다. 기본값은 기존 `...` 버튼 동작 그대로이며, ArrowDown 열기·선택 후 Focus 복귀는 `renderTrigger`를 쓸 때만 적용합니다.
## 2. 반응형 (최종: 실제 가용 폭 기준 3단계, 2026-10-21)
- 고정 Breakpoint 대신 `SWViewerHeader`가 Header 행의 남는 폭을 측정합니다(SWHeader의 measured More와 같은 방식: `data-measuring` 상태에서 각 부분을 자연 폭으로 두고 한 번 측정, 그리지 않음). 파일명은 글자 폭까지만 계산해 짧은 파일명이면 메뉴가 더 오래 유지됩니다.
- ① 공간 충분: 아이콘+텍스트(1440·1100에서 전체 보기·레이어·설정·속성 모두 표시) → ② 부족: `icon`+`iconOnlyBelow` 항목(전체 보기·레이어·설정·속성)을 한 번에 아이콘만(라벨은 Tooltip·접근성 이름) → ③ 더 부족: `collapseBelow` 항목을 하나씩 More로(값이 큰 것, 같으면 오른쪽 먼저: 어두운 배경 → 2.5D → 전체 보기 → 도면 공간). 넓어지면 역순 복귀. 각 단계가 확보한 폭을 기록해 그 폭이 다시 생길 때만 되돌려 경계에서 깜빡이지 않습니다.
- Storybook 기본 구성 실측 경계(파일명 `C0060202-001-평면및종단면도.dwg`): 1080px 이상 기본, 1070px 아이콘만, 810px 이하 More. 380px까지 가로 넘침 없음. 줄일 때와 늘릴 때 같은 폭의 상태가 같습니다. 짧은 파일명(`simple.dxf`)에서는 경계가 더 좁은 폭으로 이동합니다.
- `collapseBelow`·`iconOnlyBelow` Props 형식은 그대로이고 숫자는 순서만 정합니다. `types.ts`의 두 Props 설명("Header width (px) below which…")은 공개 선언 파일 변경을 피하려고 이번에 고치지 않았습니다(`SWViewerHeader`·VIEWER.md에 실제 동작 기재). API 기준 갱신 작업 때 함께 고치는 것을 권합니다.
- 1180px 미만 간격 2px, 560px 미만 상태 글자 숨김은 메뉴 이동이 아닌 CSS container 규칙으로 그대로 둡니다.
## 2a. 레이어 · 위치 · 스타일 (2026-10-21)
- 파일명 목록이 로고를 가리던 원인: 패널 위 표시를 위해 파일명 요소를 z-index 60으로 올려 로고 면(z-index 2) 위로 파일명 칸이 그려졌습니다. SWHeader는 로고(2) > 파일명(1) 순서를 유지합니다. 수정: 내부 순서를 SWHeader와 같게 되돌리고, 메뉴가 열린 동안만 Header 전체를 기존 뷰어 Dropdown 층(SWViewerMenu, 60)으로 올립니다(닫히면 층 없음).
- 로고 메뉴: Header 컨테이너 기준(`top: calc(100% + 1px)`, `left: 0`)으로 Header 하단 경계에 바로 붙고 로고 왼쪽에 맞춤. 크기·간격·글자·구분선은 `SWViewerMenu`(상단 메뉴 + Dropdown)와 같게, 색(면 #0e3d2f·Border·글자·Hover)은 유지.
- 파일명 목록: SWHeader 파일명 목록과 같은 모양 그대로(스타일 변경 없음).
## 3. 공개 API
- Export 170개 유지, 기존 Props 변경·삭제 없음.
- `public-api.check.mjs`: 6/7 PASS. FAIL 1건은 `components/sw-viewer/SWViewerHeader.d.ts` 해시 변경으로, 승인된 optional Props 추가에 따른 예상 차이입니다. 새로 노출된 내부 선언 파일은 없습니다. 승인 JSON·기준 Commit은 수정하지 않았습니다(별도 API 기준 갱신 작업).
## 4. 검증
- `packages/sw/tests/viewer-logo-document-menu.browser.mjs` 42/42 PASS (증거 `docs/sw/viewer-logo-document-menu-qa/`).
- `packages/sw/tests/viewer.browser.mjs` 70/70 PASS (참고 뷰어 비교 단계는 참고 URL 없이 생략). 제거된 샘플·파일 열기 버튼 대상 검사를 새 구조에 맞게 수정했습니다.
- 이 checkout의 `node_modules`에 workspace 링크(`@hm-design/sw` 등)와 `orgchart` 의존성이 없어 루트 `tsc -b`, `build-storybook`은 기존 환경 문제로 실패합니다. Storybook 실행을 위해 `node_modules/@hm-design/sw` → `packages/sw` Junction만 추가했습니다(git 무시 대상).
## 5. 환경 복구 후 재검증 (2026-10-21)
- 원인: `node_modules`가 2026-10-12에 설치된 뒤 Pull로 `package-lock.json`에 workspace 링크 3개(`@hm-design/sw`·`org-chart`·`org-chart-react`)와 `orgchart` 6.0.0 등 13개 패키지가 추가되었으나 `npm install`이 다시 실행되지 않았습니다(설치본에만 있는 패키지·버전 차이 없음).
- 복구: `npm install`(제자리, `npm ci` 아님). npm이 lockfile의 `org-chart-react` `peerDependencies` 키 순서만 바꿔 설치 직전 백업(=HEAD와 동일)으로 되돌렸습니다. `package.json`·lockfile 변경 없음, Git 상태 설치 전과 동일.
- `npm run typecheck`(루트 `tsc -b` + 전체 workspace) PASS, `build:packages` PASS, `build-storybook` PASS.
- Public API: 6/7, FAIL은 `SWViewerHeader.d.ts`뿐. HEAD(46119ea)로 별도 build한 선언 해시가 승인 해시와 같고, 현재와의 차이는 승인된 optional Props 4개, 이미 공개된 `SWHeaderDocument` type import, `document` Prop 설명 한 문장뿐입니다.
| 검사 (storybook-static) | 결과 | 비고 |
|---|---|---|
| viewer-logo-document-menu | 42/42 | |
| viewer-logo-document-menu-firefox (Firefox 158, BiDi) | 30/30 | 증거 `viewer-logo-document-menu-qa/firefox/` |
| viewer | 70/70 | |
| keyboard-dismiss / header-composition / home-menu-integration | 22/22 / 161/161 / 23/23 | |
| integrated-improvement / hover-stability(chromium) / storybook-simplification / footer-popup-viewer-refinement | 90/90 / 201/201 / 9/9 / 47/47 | |
| overview / dropdown-consolidation / storybook-unused-removal | 53/54 / 227/228 / 92/93 | FAIL은 모두 source guard: 승인 목록 밖 변경 파일로 이번 작업 파일만 표시 |
| text-weight | 실패(중단) → 수정 후 아래 §6 | 제거된 `파일 열기`·`샘플` 버튼과 `.hm-sw-viewer-header__document-name`을 찾는 기존 단언 |
| theme-inheritance | 실패(중단) → 수정 후 아래 §6 | Viewer Header 첫 `aria-haspopup="menu"`를 SWViewerMenu(샘플)로 가정, 지금은 로고 메뉴 |
| followup-four | 실패(중단) | 기존 문제: 5faa1f1에서 삭제된 `sw-header--property-bar` Story를 엶 |
## 6. text-weight · theme-inheritance 갱신 (2026-10-21, 사용자 승인)
- **text-weight:** Header의 Bold 대상(파일명·레이어·설정·속성·Model/Layout = 14px 700 + 1.3px 외곽선)은 그대로 단언하고, 제거된 `파일 열기`·`샘플`·`전체 보기`가 Header 라벨에 없음을 확인합니다. 로고 메뉴 Open 행과 샘플 목록 행은 같은 실행에서 SWHeader `...` 메뉴(400, 외곽선 없음)와 SWHeader 파일명 목록(14px 700 + 1.3px 외곽선)을 기준으로 측정해 굵기·크기·글꼴·외곽선이 같아야 PASS입니다. 로고 메뉴 타이틀은 700(외곽선 없음). Hover 시 글자 위치·크기·굵기 유지 검사를 Open 행·파일명·샘플 행·레이어·Layout에 적용합니다.
- **theme-inheritance:** 기존 Dropdown 글꼴 상속 검사를 로고 메뉴와 파일명 버튼·샘플 목록으로 옮겼습니다(기본 Noto Sans KR / 뷰어 테마 Dotum). 추가로 두 메뉴의 배경·글자·Border·Hover 색이 기본에서는 SWHeader 토큰 값과 같고, 가장 바깥 SW 범위에 설정한 색 토큰이 두 메뉴까지 상속되는지 확인합니다(검사 중에만 설정 후 제거). 로고 메뉴 면 `#0e3d2f`는 SWHeader `...` 메뉴의 고정값이라 그 값과 비교합니다. 전체 Story 회귀(새 상속 구조 = 기존 구조) 검사는 그대로입니다.
- **발견·수정한 결함:** theme-inheritance의 뷰어 테마 화면(레이어 패널이 로고 아래에 열린 상태)에서 로고 메뉴가 SWViewerPanel 제목 줄 아래에 깔려 Open을 누를 수 없었습니다. 두 메뉴의 바깥 요소가 z-index 2·1의 쌓임 맥락 안에 있었기 때문입니다. `sw-viewer.css`에 메뉴가 열린 동안만 그 바깥 요소를 기존 뷰어 Dropdown 층(SWViewerMenu, 60)으로 올리는 규칙 한 개를 추가했습니다(닫히면 원래 값). Chromium·Firefox 테스트에 패널 위 표시 검사를 추가했습니다.
| 재실행 (수정 후 storybook-static) | 결과 |
|---|---|
| text-weight / theme-inheritance(회귀 67/67 포함) | 51/51 / 28/28 |
| viewer-logo-document-menu / Firefox 158 | 46/46 / 31/31 |
| viewer / keyboard-dismiss / header-composition / home-menu-integration | 70/70 / 22/22 / 161/161 / 23/23 |
| integrated-improvement / hover-stability / storybook-simplification / footer-popup-viewer-refinement | 90/90 / 201/201 / 9/9 / 47/47 |
| overview / dropdown-consolidation / storybook-unused-removal | 53/54 / 227/228 / 92/93 — source guard만 FAIL(이번 작업 파일 4개) |
| `npm run typecheck`, `build-storybook`, Public API | PASS, PASS, 6/7(`SWViewerHeader.d.ts` 승인 Props 차이만) |
## 7. 반응형 · 레이어 · 로고 메뉴 스타일 재검증 (2026-10-21, 최종 소스)
이번 실행(영향 범위만): `npm run typecheck` PASS, `build-storybook` PASS, `check:ai-docs` PASS, Public API 6/7(`SWViewerHeader.d.ts`만: 승인 Props + 설명 주석).
| 검사 | 결과 |
|---|---|
| viewer-logo-document-menu (Chromium, 폭 Sweep·경계·파일명 길이·열린 상태 Resize·로고 하단 정렬·로고 가림 픽셀·SWViewerMenu 비교 포함) | 58/58 |
| viewer-logo-document-menu-firefox (Firefox 158) | 34/34 |
| viewer / text-weight / theme-inheritance(회귀 67/67 포함) | 70/70 / 52/52 / 28/28 |
이번에 재실행하지 않음(이번 라운드에서 `SWHeaderMore`·`sw.css` 등 SW Header 공통 소스 변경 없음, 직전 결과 유지): keyboard-dismiss 22/22, header-composition 161/161, home-menu-integration 23/23, integrated-improvement 90/90, hover-stability 201/201, storybook-simplification 9/9, footer-popup-viewer-refinement 47/47, overview 53/54·dropdown-consolidation 227/228·storybook-unused-removal 92/93(source guard만 FAIL).
## 8. 로고 메뉴 구성 · 파일명 Open · 최소 너비 · Dropdown 면 통일 (2026-10-21)
- 로고 메뉴: 타이틀 `파일` + 아이콘 `파일 열기`(Storybook fixture). 타이틀과 목록은 한 그룹이라 구분선 없음(`SWHeaderMore`가 타이틀 아래 구분선을 그리지 않음). `logoMenu`는 한 그룹 구조라 그룹 사이 구분선이 생길 경우가 없습니다(여러 그룹은 `SWViewerMenu`의 label·separator 데이터로 표현).
- 파일명 목록: `SWHeaderDocumentTitle`의 `showOpen` 재사용, 목록 아래 SWHeader와 같은 Open(+ New 없음). 목록 외곽 너비 ≥ max(파일명 버튼 외곽 너비, SWHeader 312px), 긴 항목이면 넓어짐(CSS `min-width`·`width: max-content`만). 실측 버튼→목록: 1440 359.5→361.5, 1100 274.5→312, 860 214.5→312, 520/400 140→312, 열린 채 Resize·짧은 파일명도 조건 유지.
- 두 파일 열기 진입점은 같은 `openFile` 핸들러(로고 항목 `onSelect`, 목록 `onDocumentOpen`). 목록 Open은 `onCommand({ id: "open", itemId: "document" })`도 보냄.
- Dropdown 면 통일: 기준 520px More 실측값(면 rgb(245,240,229), Border 1px rgb(137,116,69), 반경 4px, 그림자 0 0 12px rgba(0,0,0,.2), 글자 rgb(10,34,29) Noto Sans KR 14/20 400, 행 36px·좌우 12px·간격 8px, Hover rgba(189,223,212,.45)/rgb(18,51,40), 타이틀 rgb(110,103,89) 12/18 500, 구분선 1px rgb(148,136,113))을 기존 `--hm-sw-viewer-more-*`·`--hm-sw-viewer-menu-*` 토큰으로 로고 메뉴에 적용, Header 메뉴 버튼 Dropdown은 `surface="beige"`. 파일명 목록과 단독 `SWViewerMenu`(우클릭)는 제외.
- 공개 API 추가(보고): `logoMenu.items[].icon?`, `onDocumentOpen?`, `documentOpenLabel?`(모두 Optional, `SWViewerHeader.d.ts` 안, Export 170 유지). 아이콘·Open 핸들러를 넘길 기존 Props가 없어 추가했습니다.
- 검증(최종 소스): typecheck·build-storybook·check:ai-docs PASS, Public API 6/7(`SWViewerHeader.d.ts`만), viewer-logo-document-menu 63/63, Firefox 36/36, viewer 70/70, theme-inheritance 27/27(고정 면 검사 → 토큰 검사로 대체), 이전 실행(같은 라운드 SWHeaderMore 변경 후): text-weight 52/52, keyboard-dismiss 22/22, header-composition 161/161, integrated-improvement 90/90.
## 9. Dropdown 색 최종 (2026-10-21)
- 기준: 일반 SWHeader의 `...` 메뉴(`.hm-sw-header__more-menu`). 로고 메뉴(같은 컴포넌트)는 Viewer 색 재정의를 제거해 sw.css 색을 그대로 사용하고, Header 메뉴 버튼 Dropdown·More(SWViewerMenu, Header 안)는 Viewer 범위 CSS로 같은 값을 칠합니다: 면 #0e3d2f·그림자 0 4px 12px rgba(0,0,0,.5)(sw.css 고정값), Border `--hm-sw-header-object-border-color`, 글자 `--hm-sw-header-text-color`(#f6f4f2), 보조 글자 같은 색 80%, Hover `--hm-sw-header-hover`(rgba(255,255,255,.08), 글자 유지), 구분선 `--hm-sw-header-document-menu-divider-color`. 크기·간격·글자 크기는 SWViewerMenu 그대로. 파일명 목록·단독 SWViewerMenu는 제외.
- 검증(이번 실행): build-storybook, viewer-logo-document-menu 63/63(More·Dropdown·로고 메뉴 색 = 같은 실행에서 측정한 SWHeader `...` 메뉴), Firefox 36/36, viewer 70/70, theme-inheritance 28/28. 재사용: typecheck(직전 CSS 외 소스 변경 없음), text-weight 52/52, keyboard-dismiss 22/22, header-composition 161/161, integrated-improvement 90/90, Public API 6/7(`SWViewerHeader.d.ts`만).
## 10. 파일 열기 버튼으로 변경 (2026-10-21)
- 로고 클릭 메뉴 대신 로고 오른쪽 파일 열기 버튼: SWHeader `documentOpenPlacement="header"`와 같은 `SWToolButton appearance="document"` 면 + 폴더 아이콘(테두리·배경 없음, 사용자 요청) + `documentOpenLabel`. 기존 `onDocumentOpen`·`documentOpenLabel` 재사용(목록 아래 Open → Header 버튼). 공간이 부족하면 측정 2단계에서 라벨만 숨김(Tooltip·접근성 이름 `파일 열기`), More로 이동하지 않음.
- 파일명 목록: Open·+ New 없음(`showOpen={false}`), 최소 너비 조건 유지. 파일명 영역 컨테이너(`.hm-sw-viewer-header__document`)는 Open 버튼 뒤에서 왼쪽 padding 0, 파일명 버튼(`.hm-sw-header__document-button`) padding은 변경하지 않음(사용자 결정).
- 로고 메뉴: 뷰어 화면·Story·AI 예시에서 사용 중단. `logoMenu` Prop과 `SWHeaderMore` 확장(제목·아이콘·외부 트리거)은 공개·승인된 API라 코드 유지 — API 기준 갱신 작업에서 삭제(또는 유지) 결정 필요.
- 검증: viewer-logo-document-menu 47/47, Firefox 23/23, viewer 70/70, text-weight 50/50, theme-inheritance 25/25, check:ai-docs PASS.
View Git Blame Copy Permalink