shkim4andClaude Opus 5.5
e27385e0f0
- Ship an AI guide in the package (ai/: usage rules, component catalog, design rules, composition patterns) via package.json files. - Add examples A-D that import only public exports: default header, viewer header, feature header, and a consumer-side search extension that reuses SWHeaderInput and the public SW tokens. - Add SW-only checks: docs/API consistency, tarball consumer project (React 19 + TS + Vite typecheck/build) and a browser check (27/27). - No runtime source or public API change; README gains a pointer section. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
83 lines
5.3 KiB
Markdown
83 lines
5.3 KiB
Markdown
# SW 조합 패턴
|
|
|
|
모든 패턴은 공개 Export만 사용합니다. 전체 코드는 [examples/](./examples)에 있으며, 설치된 패키지에서 꺼낸 그대로 독립 React 19 + TypeScript + Vite 프로젝트의 `tsc`·Production Build·브라우저 검증을 통과했습니다(2026-10-19).
|
|
|
|
## 0. 어떤 패턴을 고를까
|
|
|
|
| 요청 | 패턴 |
|
|
|---|---|
|
|
| 기존 SW Header 전체(일부 부품 제거·메뉴 순서 변경 포함) | 1. 완성형 |
|
|
| 기존 컨트롤 일부만, 다른 배치·순서 | 2. 조합 Header |
|
|
| 기존 Dropdown을 툴바·패널 등 다른 곳에 | 3. 개별 컨트롤 |
|
|
| 패키지에 없는 기능 | 4. 확장(소비 프로젝트 신규 컴포넌트) |
|
|
|
|
## 1. 완성형 SW Header — [ExampleA-DefaultHeader.tsx](./examples/ExampleA-DefaultHeader.tsx)
|
|
|
|
```tsx
|
|
<SWHeader documentTitle={name} documents={documents} layers={layers} colors={colors} onClose={close} />
|
|
```
|
|
|
|
- 부품 제거: `hiddenControls={["print", "popupGuide"]}`(로고는 항상 표시, `"home"`은 정적 로고).
|
|
- 메뉴 순서: `menuOrder={["color", "layer"]}`(5개 메뉴끼리, 누락분은 기본 순서로 뒤에).
|
|
- 객체 영역 전체를 직접 나열: `controls={[{ id: "document" }, { id: "layer" }, { id: "print" }]}`.
|
|
- 추가 도구: `tools={<MyTool />}`(객체 영역 메뉴 뒤). 새 도구는 아래 4의 규칙을 따른다.
|
|
- 이 경우에만 반응형 More가 동작합니다.
|
|
|
|
## 2. 조합 Header (간소화·기능 중심)
|
|
|
|
`<SWTheme>`을 Header 막대로 쓰고, 막대·면 배치 CSS는 소비 프로젝트가 작성합니다([example-layout.css](./examples/example-layout.css)). 이 CSS는 `--hm-sw-header-*` 토큰만 읽고 `hm-sw-*` class를 건드리지 않습니다.
|
|
|
|
```tsx
|
|
<SWTheme className="app-sw-bar"> {/* 49px, #060606, flex, gap 2px */}
|
|
<SWHeaderHome logoAlt="뷰어" onClick={goHome} /> {/* 80px, 다음 파일 면과 겹침 */}
|
|
<SWHeaderDocumentTitle title={name} documents={documents} onDocumentSelect={open} />
|
|
<div className="app-sw-surface"> {/* 객체 수정 면 토큰 */}
|
|
<SWHeaderLayerMenu value={layer} layers={layers} onLayerSelect={selectLayer} />
|
|
<SWHeaderColorMenu value={color} colors={colors} onColorSelect={selectColor} />
|
|
</div>
|
|
<div className="app-sw-window"> {/* 창 영역 면 토큰 */}
|
|
<SWHeaderActions showPrint={false} onPopupGuide={showGuide} />
|
|
</div>
|
|
</SWTheme>
|
|
```
|
|
|
|
- 간소화 Viewer: [ExampleB-ViewerHeader.tsx](./examples/ExampleB-ViewerHeader.tsx) — 로고 → 파일 → 레이어 → 색상 → K.
|
|
- 기능 중심: [ExampleC-FeatureHeader.tsx](./examples/ExampleC-FeatureHeader.tsx) — 파일 → 선 → 문자 → 치수스타일 → 인쇄.
|
|
- 순서는 JSX 순서입니다(DOM·Tab 순서 동일). CSS `order`로 바꾸지 않습니다.
|
|
- 로고 없이 파일 면이 처음이면 왼쪽 테두리가 없으므로 wrapper에 1px 테두리를 둡니다(예제 C `app-sw-file-edge`).
|
|
- K만/인쇄만: `SWHeaderActions`의 `showPrint={false}` / `showPopupGuide={false}`.
|
|
- 창 제어: `<SWHeaderWindowControls onWindowMoveStart={startDrag} onMinimize={min} onClose={close} />`(창 영역 면 안).
|
|
- 조합 Header에는 반응형 More가 없습니다. 좁은 화면이 필요하면 완성형을 쓰거나 표시할 컨트롤을 줄입니다.
|
|
|
|
## 3. 기존 Dropdown을 다른 레이아웃에서
|
|
|
|
```tsx
|
|
<SWTheme className="app-toolbar">
|
|
<SWHeaderLineStyleMenu value={lineStyle} lineTypes={lineTypes} lineWeights={lineWeights} onLineTypeSelect={setType} />
|
|
</SWTheme>
|
|
```
|
|
|
|
- Dropdown은 필드 바로 아래에 열리고 뷰포트 안으로 좌우 보정됩니다. 부모에 `overflow: hidden`을 두지 않습니다.
|
|
- Controlled가 필요하면 `open` / `onOpenChange`를 함께 줍니다.
|
|
- Dropdown이 필요 없고 호스트가 자체 팝업을 열면 `SWHeaderLayerControl` 등 필드 버튼만 씁니다.
|
|
|
|
## 4. 확장 — 없는 컨트롤 새로 만들기 — [SWSearchControl.tsx](./examples/SWSearchControl.tsx), [ExampleD-SearchExtension.tsx](./examples/ExampleD-SearchExtension.tsx)
|
|
|
|
요청 예: "레이어와 색상은 기존 SW 컴포넌트, 검색 버튼은 SW 디자인으로 새로."
|
|
|
|
1. 카탈로그 검색: 검색 컴포넌트 없음(MISSING).
|
|
2. 조합 검토: 텍스트 입력·확정·취소·IME는 `SWHeaderInput`으로 충족 → 재사용. 필드 면과 검색 아이콘 버튼은 공개 컴포넌트가 없음 → 신규.
|
|
3. 신규 부분은 **소비 프로젝트**에 작성: 38px 속성 필드 면, 12px 라벨, gradient Hover 링, 아이콘 버튼은 글자색 Hover `#FFC600`. 모든 값은 토큰([sw-search-control.css](./examples/sw-search-control.css)).
|
|
4. 기존 컨트롤과 같은 면(`app-sw-surface`)에 나란히 배치.
|
|
5. 검증: 레이어 필드와 높이·위치·테두리·radius·배경·그림자·라벨 크기 일치, Hover 링, Enter 확정 → `onSearch`, Escape 복원.
|
|
|
|
새 컨트롤은 패키지 공식 컴포넌트로 자동 등록하지 않습니다. 여러 프로젝트에서 반복되면 SW 패키지 승격을 별도로 검토합니다.
|
|
|
|
## 5. 하지 말 것
|
|
|
|
- `hm-sw-*` class를 소비 코드에 쓰거나 CSS로 덮어쓰기
|
|
- `dist` 구현·`styles.css` 블록 복사로 같은 컴포넌트 재작성
|
|
- `@hm-design/sw/dist/...`·`src/...` 내부 경로 Import
|
|
- 문서에 없는 Props 추측, 새 색·크기 값 도입
|
|
- 같은 화면에 `SWHeader`와 조합 Header를 겹쳐 두 개의 Header 만들기
|