refactor(sw): simplify storybook navigation and examples

2026-10-20 13:17:15 +09:00
1 parent 47972c55ff
commit 2b0e1a2262
@@ -0,0 +1,71 @@
+[
+ {
+  "n": "direct URL render: 42 SW Stories, no error display / page error",
+  "ok": true,
+  "d": []
+ },
+ {
+  "n": "removed Home Menu IDs absent from index",
+  "ok": true
+ },
+ {
+  "n": "Popup › Property Panel: four states none/all/circle/expanded at 314 × 256/361/658/754",
+  "ok": true,
+  "d": [
+   [
+    "none",
+    314,
+    256
+   ],
+   [
+    "all",
+    314,
+    361
+   ],
+   [
+    "circle",
+    314,
+    658
+   ],
+   [
+    "expanded",
+    314,
+    754
+   ]
+  ]
+ },
+ {
+  "n": "sidebar SW order Header → Footer → Popup → Viewer → Theme",
+  "ok": true,
+  "d": [
+   "Header",
+   "Footer",
+   "Popup",
+   "Viewer",
+   "Theme"
+  ]
+ },
+ {
+  "n": "verification Stories not in sidebar",
+  "ok": true,
+  "d": []
+ },
+ {
+  "n": "Popup children order: Custom Content, Multiple Popups, Property Panel",
+  "ok": true,
+  "d": [
+   "sw-popup--custom-content",
+   "sw-popup--multiple-popups",
+   "sw-header--property-panel-compare"
+  ]
+ },
+ {
+  "n": "Property Panel listed once (under Popup only)",
+  "ok": true
+ },
+ {
+  "n": "sidebar link opens moved Story with same ID",
+  "ok": true,
+  "d": "http://127.0.0.1:4479/?path=/story/sw-header--property-panel-compare"
+ }
+]
@@ -0,0 +1,182 @@
+[
+ [
+  "sw-header",
+  "component",
+  "Header"
+ ],
+ [
+  "sw-header--composed-controls",
+  "story",
+  "Dropdown"
+ ],
+ [
+  "sw-header--home-menu",
+  "story",
+  "Home Menu"
+ ],
+ [
+  "sw-header--home-menu-standalone",
+  "story",
+  "Home Menu · 단독 사용 · 조합형"
+ ],
+ [
+  "sw-header--document-open",
+  "story",
+  "Document Open"
+ ],
+ [
+  "sw-header--hidden-sub-controls",
+  "story",
+  "Hidden Sub Controls"
+ ],
+ [
+  "sw-header--overview",
+  "story",
+  "Overview"
+ ],
+ [
+  "sw-header--interactive-states",
+  "story",
+  "Interactive States"
+ ],
+ [
+  "sw-header--logo-slot",
+  "story",
+  "Logo Slot"
+ ],
+ [
+  "sw-header--document-dropdown",
+  "story",
+  "Document Dropdown"
+ ],
+ [
+  "sw-header--responsive-more",
+  "story",
+  "Responsive More"
+ ],
+ [
+  "sw-footer",
+  "component",
+  "Footer"
+ ],
+ [
+  "sw-footer--default",
+  "story",
+  "기본 Footer"
+ ],
+ [
+  "sw-footer--full-footer",
+  "story",
+  "전체 Footer · 실제 조합"
+ ],
+ [
+  "sw-footer--tool-groups",
+  "story",
+  "도구 그룹별 표시"
+ ],
+ [
+  "sw-footer--states",
+  "story",
+  "Hover / Active / Selected / Disabled"
+ ],
+ [
+  "sw-footer--custom-content",
+  "story",
+  "도구 및 메뉴 변경 예제"
+ ],
+ [
+  "sw-footer--responsive",
+  "story",
+  "화면 폭 변화"
+ ],
+ [
+  "sw-footer--parts",
+  "story",
+  "개별 부품 (조합용)"
+ ],
+ [
+  "sw-popup",
+  "component",
+  "Popup"
+ ],
+ [
+  "sw-popup--custom-content",
+  "story",
+  "Custom Content"
+ ],
+ [
+  "sw-popup--multiple-popups",
+  "story",
+  "Multiple Popups"
+ ],
+ [
+  "sw-header--property-panel-compare",
+  "story",
+  "Property Panel · 4개 비교"
+ ],
+ [
+  "sw-viewer",
+  "component",
+  "Viewer"
+ ],
+ [
+  "sw-viewer--viewer-header",
+  "story",
+  "Viewer Header"
+ ],
+ [
+  "sw-viewer--menu-groups",
+  "story",
+  "Menu Groups"
+ ],
+ [
+  "sw-viewer--states",
+  "story",
+  "Item States"
+ ],
+ [
+  "sw-viewer--dropdowns",
+  "story",
+  "Header + Dropdown"
+ ],
+ [
+  "sw-viewer--settings-panel",
+  "story",
+  "Settings Popup"
+ ],
+ [
+  "sw-viewer--content-variants",
+  "story",
+  "Popup Content Variants"
+ ],
+ [
+  "sw-viewer--variable-size",
+  "story",
+  "Variable Size Popups"
+ ],
+ [
+  "sw-viewer--responsive",
+  "story",
+  "Responsive Widths"
+ ],
+ [
+  "sw-viewer--compare-with-sw-header",
+  "story",
+  "SWHeader vs Viewer Header"
+ ],
+ [
+  "sw-viewer--logo",
+  "story",
+  "Logo"
+ ],
+ [
+  "sw-theme",
+  "component",
+  "Theme"
+ ],
+ [
+  "sw-theme--theme-inheritance",
+  "story",
+  "Theme Inheritance"
+ ]
+]
@@ -455,7 +455,9 @@ Tooltip은 45 × 17px, 검정 80% 배경과 흰색 12px/400 글자입니다. Too
 npm run storybook
 ```

-현재(2026-10-19, 홈 메뉴 통합 후) `SW / Header`에는 27개 Story가 있습니다(사이드바 기본 표시 12개 + `verification` 태그 15개). 이전 시점의 Story 표는 [1차 정리 보고 §2](./sw-first-pass-cleanup-review-2026-10-19.md#2-storybook-전체-목록-및-분류), 홈 메뉴 통합 후 목록은 [홈 메뉴 통합·실측 More 보고](./sw-header-home-menu-responsive-2026-10-19.md)를 봅니다. 아래 문단은 Story를 추가한 시점별 설명입니다.
+> **현재 기준(2026-10-20 SW Storybook 간소화):** SW 메뉴 순서는 `Header → Footer → Popup → Viewer → Theme`입니다. `SW / Header`에는 20개 Story가 있습니다(사이드바 기본 표시 10개 + `verification` 태그 10개). `Property Panel · 4개 비교`는 사이드바에서 `SW / Popup` 아래로 옮겼고 ID(`sw-header--property-panel-compare`)는 그대로입니다. `Window Move Motion`·`K Guide`는 `verification` 태그로 숨겼고, `Home Menu · 단독 사용 · 조합형`은 개별 부품 예제로 사이드바에 표시합니다. 테스트·문서에서 쓰지 않던 Home Menu Figma 비교 Story 6개(`sw-header--home-menu-figma`, `-capture-active`, `-capture-outline`, `-capture-recent`, `-variants`, `-recent-files`)와 `Home Menu`의 Figma 스크린샷 비교 섹션은 제거했습니다. Figma 원본은 `docs/sw/figma-additional/screenshots/`에 있습니다. 상세: [SW Storybook 간소화 보고](./sw-storybook-simplification-2026-10-20.md). 아래는 작성 당시 기록입니다.
+
+(2026-10-19 기록) 홈 메뉴 통합 후 `SW / Header`에는 27개 Story가 있습니다(사이드바 기본 표시 12개 + `verification` 태그 15개). 이전 시점의 Story 표는 [1차 정리 보고 §2](./sw-first-pass-cleanup-review-2026-10-19.md#2-storybook-전체-목록-및-분류), 홈 메뉴 통합 후 목록은 [홈 메뉴 통합·실측 More 보고](./sw-header-home-menu-responsive-2026-10-19.md)를 봅니다. 아래 문단은 Story를 추가한 시점별 설명입니다.

 2026-10-19 홈 메뉴 통합: 기존 `SW / Home Menu` 메뉴는 사이드바에서 제거하고 `SW / Header`로 옮겼습니다. 사이드바에는 `Home Menu`(`sw-header--home-menu`: 로고 클릭 열기/닫기·이벤트 기록, 헤더 폭 조절, Figma 26:10591 비교, Default/Hover/Active, 최근파일 하위 패널, 속성창·SWPopup·Escape 통합) 하나만 표시합니다. Figma 비교 캔버스·Variant·데이터 변경·단독 사용·속성Bar 비교 등은 `sw-header--home-menu-*` ID의 `verification` 태그 Story로 남아 직접 URL과 사이드바 태그 필터로 엽니다. `Overview`의 로고도 같은 홈 메뉴를 엽니다. `Responsive More` 첫 섹션 "실제 사용 가능한 공간 기준"은 헤더 폭 Range와 로고 오른쪽 버튼·추가 도구·홈 메뉴 On/Off로 실측 More의 이동·복귀를 확인합니다. 홈 메뉴는 SW 일반 모드 전용이며 `SW / Viewer`에는 없습니다.

@@ -0,0 +1,70 @@
+# SW Storybook 메뉴·콘텐츠 간소화 (2026-10-20)
+
+범위: SW Storybook(`src/sw/*.stories.tsx`, `.storybook/preview.tsx` storySort) 정리만 합니다. SW 컴포넌트 소스, 공개 Props/Events, Token, Web(UI)·OrgChart는 변경하지 않았습니다. 기준 HEAD `47972c5`(`feature/sw-package`). Home Menu는 2026-10-19 결정대로 `SW / Header` 아래에 유지합니다.
+
+## 1. 메뉴 구조
+
+| | 변경 전 | 변경 후 |
+|---|---|---|
+| SW 순서 | Footer → Header → Popup → Theme → Viewer (알파벳) | **Header → Footer → Popup → Viewer → Theme** (`storySort`) |
+| SW/Header | 표시 12 + verification 15 | 표시 10 + verification 10 |
+| SW/Footer | 표시 8 | 표시 7 + verification 1 |
+| SW/Popup | 표시 2 | 표시 3 (`Property Panel · 4개 비교` 이동) |
+| SW/Viewer / SW/Theme | 10 / 1 | 변경 없음 |
+
+변경 후 사이드바 (`storybook-simplification-qa/sidebar.json`):
+
+- **Header:** Dropdown · Home Menu · Home Menu · 단독 사용 · 조합형 · Document Open · Hidden Sub Controls · Overview · Interactive States · Logo Slot · Document Dropdown · Responsive More
+- **Footer:** 기본 Footer · 전체 Footer · 실제 조합 · 도구 그룹별 표시 · Hover / Active / Selected / Disabled · 도구 및 메뉴 변경 예제 · 화면 폭 변화 · 개별 부품 (조합용)
+- **Popup:** Custom Content · Multiple Popups · Property Panel · 4개 비교
+- **Viewer:** Viewer Header · Menu Groups · Item States · Header + Dropdown · Settings Popup · Popup Content Variants · Variable Size Popups · Responsive Widths · SWHeader vs Viewer Header · Logo
+- **Theme:** Theme Inheritance
+
+## 2. 변경 내용
+
+| 구분 | Story (ID) | 처리 | 근거 |
+|---|---|---|---|
+| 이동 | `sw-header--property-panel-compare` | 사이드바만 `SW/Popup`으로 이동. 새 파일 `sw-property-panel.stories.tsx`(meta `id: "sw-header"`), 렌더 코드는 `sw-header.stories.tsx`의 `PropertyPanelComparePage`(excludeStories) 그대로 | 사용자 요청. ID·이름·4상태 화면 유지 |
+| 숨김 | `sw-header--window-move-motion` | `verification` 태그 | GIF 프레임 검증. 테스트 5개가 URL로 사용 |
+| 숨김 | `sw-header--k-guide` | `verification` 태그 | Overview와 같은 Header 화면. 테스트 3개가 URL로 사용 |
+| 숨김 | `sw-footer--figma-variants` | `verification` 태그 (삭제 안 함) | Figma 35노드 비교. [Footer Figma 매핑 문서](./sw-footer-figma-mapping-2026-10-20.md)가 참조하며 이를 대신할 자동 검증이 없음 |
+| 표시 | `sw-header--home-menu-standalone` | `verification` 태그 제거 | Header 없이 쓰는 개별 부품(SWHomeMenuSection / SWHomeMenuItem) 예제 |
+| 삭제 | `sw-header--home-menu-figma` | Story 삭제 | Figma 1:1 스크린샷 비교. 테스트·문서 참조 없음 |
+| 삭제 | `sw-header--home-menu-capture-active` / `-capture-outline` / `-capture-recent` | Story 삭제 | 비교 캔버스. 참조 없음 (`-capture-default`는 테스트가 사용하므로 유지) |
+| 삭제 | `sw-header--home-menu-variants` | Story 삭제 | `Home Menu`의 Default / Variant2 / Variant3 섹션과 중복 |
+| 삭제 | `sw-header--home-menu-recent-files` | Story 삭제 | `Home Menu`의 최근파일 섹션과 중복 + Figma 스크린샷 |
+| 섹션 정리 | `sw-header--home-menu` | "Figma 26:10591 비교" 섹션의 Figma 이미지를 빼고 "열림 (현재 폭)"으로 변경. 최근파일 섹션의 Figma 이미지 2개 제거 | 사용법 중심. 구현 화면은 그대로 |
+
+삭제한 파일 (`src/sw/assets/home-menu/`): `figma-26-10591.png`, `figma-662-67267.png`, `662-67331_recent-files.png`, `662-67471_file-preview-2depth.png`. 네 파일 모두 `docs/sw/figma-additional/screenshots/`의 원본(`26-10591_home-on.png`, `662-67267_home-on-popup-guide.png`, `662-67331_recent-files.png`, `662-67471_file-preview-2depth.png`)과 md5가 같은 복사본이며, 원본은 보존합니다. 사용하지 않게 된 Story CSS 2개(`sw-home-menu-story__figma-row`, `__figma-fit`)도 제거했습니다.
+
+## 3. 유지한 검증용 Story (verification, URL로 접근 가능)
+
+`sw-header--home-menu-capture-default` · `-header-composition` · `-integration` · `-capture-responsive` (home-menu-integration 테스트) · `-dynamic-data` (Props 데이터 변경 예제) · `-property-bar-check` · `-capture-property-bar` (속성Bar 차이 3건 **승인 대기**, [Home Menu 통합 보고](./sw-home-menu-integration-2026-10-19.md)) · `sw-header--detail-buttons` · `sw-header--window-move-motion` · `sw-header--k-guide` · `sw-footer--figma-variants`.
+
+## 4. Story ID
+
+- 367 → 361개. 삭제한 6개를 뺀 나머지 ID는 모두 유지되었습니다. 바뀐 항목은 tags 4개, title 1개(`property-panel-compare`: SW/Header → SW/Popup)뿐입니다.
+- SW 외 index 항목 319개(Web·OrgChart·Center Graphic·Theme 등)는 값과 순서가 바뀌지 않았습니다.
+- 삭제한 ID는 `packages/sw/tests/storybook-inventory.mjs`의 `retiredHomeMenuCompareIds`, 이동한 ID는 `movedToPopupIds`에 기록했습니다.
+
+## 5. 검증 (2026-10-20 실제 실행)
+
+| 항목 | 결과 |
+|---|---|
+| `npm run build-storybook` | PASS |
+| `npm run typecheck` | PASS |
+| `npm run check:ai-docs` | PASS |
+| `packages/sw/tests/storybook-simplification.browser.mjs` (신규) | **8/8 PASS**: SW Story 42개 직접 URL 렌더·오류 0, 삭제 ID 없음, Popup의 4상태 314 × 256/361/658/754, 사이드바 순서, 숨김 Story 미표시, Popup 순서, 중복 표시 없음, 이동 Story 링크 ID 유지 |
+| `home-menu-integration.browser.mjs` | 22/23. FAIL 1건(`without homeMenu: logo click…`)은 기준선 `47972c5`에서도 같은 결과로 실패하는 **기존 실패** |
+| `storybook-unused-removal.browser.mjs` | render 순회에 `movedToPopupIds`를 추가해서 Popup으로 옮긴 `property-panel-compare`도 검사합니다(신규 검사 1건 PASS). 검사 수 98 → 93: 의도적으로 삭제한 6개 render만 빠졌고, 나머지 검사 이름과 PASS/FAIL 상태는 기준선과 같습니다. FAIL 5건은 모두 기준선 `47972c5`에서도 실패하는 **기존 실패**(10-19 시점 inventory·source 스냅샷 비교)입니다. 그중 `byte-identical` 항목의 목록에는 이번에 의도적으로 수정한 export(`WindowMoveMotion`, `KGuide`, `PropertyPanelCompare`)가 추가로 들어 있습니다 |
+| `dropdown-consolidation.browser.mjs` | 기준선에서도 같은 inventory 스냅샷 FAIL 5건 (기존 실패). 변경 후에는 실행하지 않음 |
+| `followup-four`, `property-fields` | 실행 불가 (기존): 첫 단계에서 10-19에 retired된 `property-bar` / `property-fields` Story를 엶 |
+| SW Viewer·Footer·Theme 기능 회귀 | 재실행하지 않음. 컴포넌트·Story 렌더 코드가 바뀌지 않았고, 이번 직접 URL 렌더 검사로 대신함 |
+
+증거: [storybook-simplification-qa/](./storybook-simplification-qa/) (`result.json`, `sidebar.json`, `sidebar.png`, `popup-property-panel-compare.png`).
+
+## 6. 남은 개선 항목
+
+- Footer Story 이름만 한국어(`기본 Footer` 등)이고 다른 SW 메뉴는 영어입니다. 이름은 바뀌어도 ID가 유지되지만, Footer Figma 매핑 문서가 이름으로 참조하고 있어 이번에는 바꾸지 않았습니다.
+- SW Story는 모두 `controls: { disable: true }`라서 Controls와 Props를 대조할 Playground Story가 없습니다.
+- 과거 시점 스냅샷과 비교하는 테스트(`storybook-unused-removal`, `dropdown-consolidation`, `overview`, `detail-buttons`)와, retired Story를 여는 테스트(`followup-four`, `property-fields`)는 현재 상태 기준으로 다시 정리할 필요가 있습니다.