101 lines
9.0 KiB
Markdown
101 lines
9.0 KiB
Markdown
# Center Graphic (`@hm-design/center-graphic`)
|
||
|
||
CENTER 도메인(제목 · 정보 표기 · 노선/공간 · 시설물)의 현재 HM 구현 기준 문서. UI 컴포넌트 문서(`docs/components/`)와 별개이며 UI 규격을 근거로 쓰지 않는다. 공통 원칙은 `docs/guidelines/프로젝트-지침.md` §5.1을 따른다.
|
||
|
||
## 1. 상태
|
||
|
||
| 항목 | 내용 |
|
||
|---|---|
|
||
| 구현 상태 | ui-viz **CENTER Web Reference 구현을 TypeScript 패키지로 이식** (Title · Information · Spatial · Facility). 규격을 새로 만들거나 재해석하지 않았다 |
|
||
| 기준일 | 2026-10-02 |
|
||
| 패키지 | `packages/center-graphic` (`@hm-design/center-graphic`, `private: false`, compiled dist JS·타입·CSS export) |
|
||
| Storybook | 최상위 그룹 `Center Graphic` (`src/center/*.stories.tsx`). UI는 기존 `Components` 유지 |
|
||
| 의존 | `@hm-design/ui`에 의존하지 않음. peer는 `react`, `react-dom`뿐 |
|
||
|
||
## 2. 원본 근거
|
||
|
||
현재 Source of Truth는 이 문서, `packages/center-graphic/src/`와 `src/center/`의 대표 Story다. 아래 표는 초기 이식 당시 외부 ui_viz Reference의 출처 목록이며 ZIP 내부 경로가 아니다. 외부 자료는 ZIP에 포함되지 않고 실행에 필요하지 않으며 제공된 경우에만 참고한다.
|
||
|
||
| 파일 | 역할 |
|
||
|---|---|
|
||
| `docs/governance/center-domain.md` (§0.1, §1, §2.4, §5) | CENTER 색인, 상태 어휘, 미결(TBD/HOLD) registry |
|
||
| `docs/usage/center-usage.md` | CENTER 구성과 사용 순서, 승인 asset 위치 |
|
||
| `docs/visualization/README.md` | visualization owner 문서 목록 |
|
||
| `docs/foundation/center-typography.md` (family, 폰트 fallback 부분) | 글꼴 Noto Sans KR |
|
||
| `implementations/web/center/components/*.jsx, *.css` | Web Reference 구현 (이식 원본) |
|
||
| `implementations/web/assets/center/facility/` | Reference가 불러오는 runtime SVG 128개 |
|
||
| `assets/center/source/facility/` | 승인 Canonical Asset 128개 (runtime 사본과 바이트 비교용) |
|
||
| `implementations/web/storybook/center/*.stories.jsx`, `center-shared.jsx` | Story 구성 참고 |
|
||
|
||
외부 Reference가 제공된 경우의 참고 우선순위: owner 문서의 명시적 상태(`CONFIRMED_CANONICAL` / `CONFIRMED_BY_DESIGN` → `PLATFORM_MAPPING` → `Candidate`/`TBD`/`HOLD`) → 승인 asset → Web Reference 구현. `docs/visualization/*.md`는 이름에 `center-`가 없어도 CENTER owner 문서다.
|
||
|
||
**읽지 않은 것(검증 한계)**: owner 문서(`route.md`, `facility.md`, `spatial-map.md`, `spatial-section.md`, `center-title.md`, `center-information-*.md`, `center-scale.md`, `center-color.md` 등)의 본문 전체와 `_local/`, `generated/`, `verification/`. 이식은 Web Reference 구현의 동작·값을 그대로 가져온 것이며, 구현 값이 owner 문서의 각 절과 일치하는지를 절 단위로 다시 대조하지는 않았다.
|
||
|
||
문서 간 충돌: 읽은 범위에서 값 충돌은 발견하지 못했다. Reference 코드 주석이 말하는 `KNOWN_DEVIATION`(예: 구도·면도·이도 윤곽, 고속도로 노선명 높이)은 원본 그대로 보존된다.
|
||
|
||
## 3. 구현 목록
|
||
|
||
| 영역 | 컴포넌트 | 비고 |
|
||
|---|---|---|
|
||
| 배율 | `CenterRepresentation` | 제작 대상 7680×2160 = 1.00, 3840×2160 = 0.75 (`CONFIRMED_BY_DESIGN` 배율 쌍). 다른 크기는 `PREVIEW_ONLY` 1.00 |
|
||
| 제목 | `CenterTitle` | 유형 1–4 (`projectName`, `projectNameRoute`, `routeProjectName`, `routeProjectNameRoute`). HTML 텍스트 + CSS, Source SVG 미사용 |
|
||
| 정보 | `CenterInformationBox`(list / definition), `CenterInformationTable`, `CenterInformationEmphasis` | 팔레트 5종 `CENTER_INFORMATION_PALETTES`. chevron / arrow는 인라인 벡터 |
|
||
| 노선/공간 | `RouteLine`, `ProjectRoute`, `RouteNameBadge`, `RouteNumberBadge`, `DirectionBadge`, `AdministrativeLabel`, `NorthArrow`, `BoundaryLine`, `ProjectExtent` | 노선 분류 7종 `ROUTE_CLASSES`, 상태 `existing` / `underConstruction` / `planned`. SVG asset을 불러오지 않고 규칙으로 그림 |
|
||
| 시설물 | `TunnelFacility`, `LocalAssetFacility` + `FACILITY_CONFIGS`(bridge · intersection · junction · interchange), `RoadsideFacilityTag`, `CompactFacilityConnection` | 승인 SVG 128개를 **바이트 그대로** 사용. 좌·중·우 조각 중 중앙만 가로로 확장 |
|
||
|
||
구현하지 않은 것: 표시 배율 HOLD(Q2b·Q3) 화면, 통합 배치(`IntegratedPlacementScene`, `PREVIEW_ONLY`), `CenterCompositions` · Facility `Assets` Story, POI/Terrain Symbol(`symbol.md`, 구현 없음), 후보(Candidate) SVG 64종.
|
||
|
||
## 4. 규격
|
||
|
||
초기 수치와 규칙의 출처는 외부 ui-viz owner 문서다. 현재 HM 구현·검토는 포함된 코드·대표 Story와 이 문서를 기준으로 하며 외부 자료 접근을 전제로 하지 않는다. 구현에서 확인한 값:
|
||
|
||
- 시설물 총 너비(기준 이름): 터널 위치도 210 · 실사화 220 (Source reference total과 일치).
|
||
- 노선: 중심선 18u, 윤곽 중심선의 20%, 그림자 층 순서 Shadow → Outline → Primary Stroke(`CONFIRMED`).
|
||
- 글꼴: Noto Sans KR(Canonical). 폰트 파일 배포와 fallback 순서는 `PLATFORM_MAPPING`/`TBD`이며 이 패키지는 폰트를 포함하지 않는다.
|
||
- 상태: 노선만 상태(기본/공사중/계획)를 가진다. Facility는 정적이며 Selected/Hover가 없다.
|
||
|
||
## 5. Public API
|
||
|
||
```ts
|
||
import { CenterRepresentation, CenterTitle, CenterInformationBox, RouteLine, TunnelFacility, LocalAssetFacility, FACILITY_CONFIGS } from "@hm-design/center-graphic"
|
||
// Storybook 검수용 demo 페이지 (컴포넌트 API 아님)
|
||
import { CenterTitleReferenceDemo } from "@hm-design/center-graphic/reference"
|
||
```
|
||
|
||
전체 export 목록은 `packages/center-graphic/src/index.ts`. Reference 코드의 `className` 등 기존 prop은 그대로이며 타입만 추가했다(`CenterTitleComposition`, `RouteClassKey`, `FacilityConfig` 등).
|
||
|
||
## 6. Token / Style
|
||
|
||
- CENTER 전용 token은 별도 파일 없이 각 컴포넌트 CSS 안에 있다(`--cid-*`, `--csi-*`, `--tunnel-*` 등). UI의 `--hm-*` token을 쓰지 않는다.
|
||
- CSS는 컴포넌트가 import하므로 별도 theme.css entry를 만들지 않았다.
|
||
- `--center-font-family`: Reference CSS가 UI 쪽 `--font-family-base`를 참조하던 두 곳을 CENTER 전용 변수로 바꿨다(기본값 `'Noto Sans KR', 'Apple SD Gothic Neo', 'Malgun Gothic', sans-serif` — Title이 이미 쓰던 체인, FNT-03 승인 fallback). 독립성을 위한 유일한 CSS 변경이다.
|
||
- Reference **demo 프레임**(`.cid-demo__*`, `.center-title-reference__*`, `.center-representation__note`)은 `--color-fg-secondary` 등 외부 token을 읽는다. 그래픽 자체는 쓰지 않으며, Storybook은 `src/center/center-stories.css`에서 값을 공급한다.
|
||
|
||
## 7. Storybook
|
||
|
||
`Center Graphic` 그룹(기본 sidebar): `Overview`, `Title`, `Information`, `Spatial`, `Facility`(터널 · 교량 · 교차로 · 분기점 · 나들목 · 휴게소·졸음쉼터 · 연계 시설물), verification 숨김: Title `Playground`, Facility `직접 테스트 (터널)`. 제작 대상 해상도는 주소 `?centerResolution=3840x2160`으로 지정한다.
|
||
|
||
## 8. 미확정 / 보류 (원본 기준)
|
||
|
||
center-domain.md §5 registry를 따른다: 표시 배율 Q2b·Q3 `HOLD`, Facility §12.24 `OWNER_REVIEW`, Information 일부 `TBD`/`Candidate`, Title Resolution B `TBD`, 전체 layer order·collision `TBD`, 철도 윤곽 두께·line join `TBD`, `symbol.md` 정확한 기하·팔레트 `TBD`, 폰트 binary 승인 `TBD`. Storybook `Overview`에 상태 표가 있다. 이 구현은 위 항목을 확정하지 않는다.
|
||
|
||
## 9. 관련 파일
|
||
|
||
```
|
||
packages/center-graphic/src/index.ts, reference.ts, env.d.ts
|
||
packages/center-graphic/src/components/*.tsx, *.css (7개 컴포넌트)
|
||
packages/center-graphic/src/assets/facility/ (SVG 128)
|
||
src/center/*.stories.tsx, center-shared.tsx, center-stories.css
|
||
```
|
||
|
||
## 10. 검증 상태
|
||
|
||
- TypeScript: 루트 `npm run typecheck`(두 패키지 포함) 통과. `npm run build` 통과(루트 Demo는 center-graphic을 import하지 않는다).
|
||
- Storybook: 11개 Center story가 렌더되고 오류 없음. 11개 story의 `img` 전부 로드(깨진 이미지 0). 터널 기준 이름의 총 너비가 위치도 210 · 실사화 220으로 reference total과 일치. Title 유형 1–2, Spatial 노선 영역, Facility 터널 화면을 눈으로 확인.
|
||
- 승인 asset 바이트 일치: 패키지의 SVG 128개(batch 122 + 터널 6) 전부가 `assets/center/source/facility/` 승인 원본과 바이트 동일(상이 0, 누락 0).
|
||
- 미확인: 원본 Storybook과의 픽셀 단위 비교, owner 문서 절 단위 대조, 3840×2160(0.75) 화면, 교량·교차로·분기점·나들목·휴게소·연계 시설물·Information 화면의 눈 확인(렌더 오류와 이미지 로드만 확인), 접근성/긴 label 추가 검증.
|
||
|
||
## 내부 테스트 사용 범위 / License
|
||
|
||
CENTER Graphic은 현재 내부 테스트/검토 목적 범위에서 제공합니다. CENTER 자체 License는 미확정이며 외부 공개 또는 사외 배포 전 별도 License 확정이 필요합니다. 특정 오픈소스 License를 부여하지 않습니다.
|