Table과 Chart 보기 상세

Chart는 별도 데이터 파일을 만드는 도구가 아니다. Markdown 표 또는 지원되는 구조 표를 원본으로 삼아, 같은 셀을 Table에서는 확인·수정하고 Chart에서는 비교·추세·구성으로 읽는다. 이 페이지의 모든 예제는 chart-lab fixture에서 열 수 있다.

이 장에서 검증하는 것

1. 빠른 성공 경로

1. Release metrics fixture를 Binder에 복사한다.
2. 파일을 Source로 열어 표가 하나의 Markdown pipe table인지 확인한다.
3. 보기 선택기에서 Table을 열어 행 수와 열 이름을 확인한다.
4. 같은 문서에서 Chart를 연다. 숫자 열이 있는 표마다 chart card가 나타난다.
5. card를 선택하고 정보 패널에서 유형, X, 값을 확인한다.
6. 값 스타일에서 series 색·축·누적을 바꾸고 저장 상태를 확인한다.
7. 인사이트 / 오버레이에서 기준선 또는 선형 추세선을 켠다.
8. Source로 돌아가 한 셀을 수정한 뒤 Table과 Chart의 표시값이 함께 바뀌는지 확인한다.
9. Hugo 미리보기에서 정적 차트와 bounded notice를 확인한다.

이 경로는 “차트가 그려졌다”로 끝나지 않는다. 마지막에 원문, projection profile intent, Desktop projection, Hugo materialization 네 층의 결과를 대조해야 한다.

2. Chart 입력 문법

2.1 최소 pipe table

첫 번째 행은 헤더, 두 번째 행은 Markdown separator, 그 다음이 본문이다. 첫 열을 범주 또는 X 값으로 두고, 뒤에 비교할 숫자 열을 둔다.

# Release metrics

| 릴리스 | 문서 | 이미지 | 영상 |
| :--- | ---: | ---: | ---: |
| Alpha | 6 | 3 | 0 |
| Beta | 12 | 9 | 2 |
| RC | 18 | 14 | 4 |
| 1.0 | 24 | 22 | 7 |

• 헤더는 비어 있지 않고 서로 다른 이름을 가져야 한다.
• X 값은 각 본문 행에서 비어 있지 않아야 한다.
• 선택한 값 열의 모든 셀은 숫자로 읽혀야 한다.
• 같은 X 값은 자동 집계되지 않는다. 반복되는 범주는 별도 행으로 그려진다.
• 표가 여러 개면 Chart는 표별 card를 만들며 한 card가 문서 전체의 dataset을 합치지 않는다.

2.2 숫자로 읽히는 값

Chart parser는 앞뒤 공백을 제거하고 쉼표를 제거한 뒤 숫자를 해석한다.

금액·퍼센트·단위를 표시해야 한다면 원문에 숫자 열과 표시용 설명을 분리한다. 1,200 KRW를 하나의 값 셀로 쓰면 Chart 값으로 저장되지 않는다.

2.3 구조 표

지원되는 structure-heading table도 Chart 후보가 될 수 있다. 이 경우 원본은 H2/H3 또는 구조 표 projection이며, Chart profile은 그 구조의 table block을 가리킨다. 구조 표의 행을 복사해 별도 Chart Markdown을 만드는 것은 권장하지 않는다. 구조 표 계약과 Chart 계약이 충돌하면 원본 구조 표를 먼저 고치고 Chart를 다시 선택한다.

3. Table에서 원문을 확인하기

Chart보다 먼저 Table을 열면 실패 원인을 빠르게 좁힐 수 있다.

1. 보기 선택기에서 Table을 선택한다.
2. 헤더 행의 열 이름이 중복되지 않았는지 확인한다.
3. X 후보가 실제 범주 순서인지 확인한다.
4. 숫자로 비교할 열에 설명 문자열·단위·빈 셀이 없는지 확인한다.
5. 셀을 수정하고 Source에서 같은 pipe cell이 바뀌는지 확인한다.
6. Chart로 전환해 새 값이 반영되는지 확인한다.

Table의 정렬·필터·freeze·hidden 상태는 표현 편의다. 원문 셀과 Chart profile의 source range가 자동으로 다른 원본이 되는 것은 아니다.

4. Chart card 읽기

Chart view는 qualifying table마다 card를 만든다.

• card 제목은 문서의 표 순서와 연결된다.
• 요약에는 행 수, X 열, 선택한 값 열이 표시된다.
• card를 선택하면 Chart info가 해당 table-bound intent를 편집한다.
• 화면에 보이는 tooltip·hover·legend 토글·zoom·brush는 세션 상태다. 공유 profile에 저장되지 않는다.
• card가 비거나 막히면 임의의 다른 표로 조용히 대체하지 않고 원본·열·값 진단을 표시한다.

5. Chart 유형 전체 목록

현재 Chart 유형 선택기와 projection 타입 계약에는 다음 15개가 있다.

Chart info의 적합도 메시지는 자동으로 profile을 바꾸지 않는다. 추천이 표시되면 추천 유형 적용을 명시적으로 눌러 저장한다. 행 수가 많으면 line/step-line/area, series가 6개 이상이면 heatmap이 첫 읽기로 추천될 수 있다. 반복 X는 자동 집계되지 않으므로 bar가 안전한 기본값이다.

6. Chart info에서 설정하기

6.1 제목

제목 섹션에서 다음을 조정한다.

• 위치: 숨김, 상단, 하단, 인라인
• 정렬: 자동, 왼쪽, 가운데, 오른쪽
• 강조: 굵게, 밑줄, 강조색, 크게

이 설정은 Chart view의 제목 표현인 features.chart.projection.style에 저장된다. chart card 목록, 선택된 chart id, 복사한 셀, source range를 이 namespace에 넣지 않는다.

6.2 유형과 데이터 결속

차트 섹션의 유형은 15개 후보 중 하나를 선택한다. 데이터 섹션은 다음을 보여 준다.

• X: 원본 헤더에서 하나만 선택
• 값: 숫자로 읽을 series를 하나 이상 선택
• 표·행·열·series 개수
• 전체 값 셀 수와 숫자·빈 셀·비수치 셀 수
• 최소값·최대값과 해당 X/series
• source line과 source range

전체 표가 source range면 현재 table body 전체를 읽는다. 저장된 직사각형 범위가 있으면 header/body와 시작·끝 행·열을 함께 보여 준다. profile에는 좌표만 남고 셀 값 복사본은 남지 않는다.

6.3 값 스타일

값 스타일에서 각 series별로 다음 renderer-neutral 설정을 저장한다.

• 색: 자동 또는 series-1부터 series-8까지의 색 token
• 축: 기본 또는 보조
• 누적: 끔 또는 그룹

색 token은 Desktop ECharts, Slide, Hugo adapter가 각자의 출력으로 변환한다. ECharts option JSON이나 CSS를 profile에 직접 넣지 않는다. 현재 source series 이름이 바뀌면 intent가 drift할 수 있으므로 열 이름을 고친 뒤 다시 저장한다.

6.4 인사이트 / 오버레이

기준선은 축 기반 유형에서 숫자 값과 선택적 라벨을 저장한다. 선형 추세선은 cartesian 숫자 유형에서만 활성화되며 선택한 series 하나에 method: linear intent를 저장한다.

• pie·donut·radar·heatmap처럼 축 기반 선이 없는 유형에서 기준선은 비활성화될 수 있다.
• 지원되지 않는 유형에서 추세선을 켜려고 하지 않는다.
• 자유형 주석, 드래그 핸들, callout, 다중 비선형 trend method는 이 Chart 계약의 저장 기능이 아니다.
• 정적 SVG는 오버레이 metadata를 전달할 수 있지만 Desktop과 완전한 시각 동등성을 주장하지 않는다.

7. 데이터 진단과 복구

7.1 정상 상태

정상 표에서는 다음이 모두 참이다.

• numericValueCells = totalValueCells
• missingValueCells = 0
• nonNumericValueCells = 0
• X 값이 모든 행에서 존재한다.
• 선택한 series가 하나 이상이다.

Chart info는 “값 셀 N/N개를 숫자로 읽었습니다”와 최소·최대 범위를 표시한다.

7.2 빈 셀

Formula and missing data fixture의 정제 행처럼 선택한 series의 값이 비어 있으면 빈 셀로 진단된다. 저장된 table-bound projection은 안전하게 invalid 상태가 될 수 있다.

복구 방법:

1. 첫 이슈 N번째 줄 열기를 눌러 원문으로 이동한다.
2. 실제로 값이 없는지 확인한다.
3. 숫자를 넣거나 해당 series를 값 선택에서 제외한다.
4. Table에서 다시 확인한 뒤 Chart로 돌아온다.

빈 값을 0으로 바꾸는 것은 의미가 다르다. 값이 “없음”인지 “0”인지 결정한 뒤 수정한다.

7.3 비수치 셀

pending, 12%, 1,200 KRW는 숫자 parser를 통과하지 않는다. 문장을 숫자로 추측해 Chart를 그리지 않는다. 단위가 필요하면 숫자와 단위 열을 분리하고, 상태값은 별도 설명 열로 둔다.

7.4 반복 X

동일한 X 라벨은 자동 합계·평균되지 않는다. 예를 들어 Beta가 두 행이면 두 개의 Beta 행으로 그려진다. 집계가 필요하면 Calc/Table에서 집계 결과를 원문 표로 만든 뒤 Chart를 다시 선택한다.

7.5 원본 결속이 깨진 경우

저장된 intent가 참조하는 block, X 열, series 열이 사라지거나 중복되면 다음 상태가 표시될 수 있다.

• 원본 표를 찾을 수 없음
• X 또는 값 열이 없음
• 열 이름이 중복되어 어느 열인지 확정할 수 없음
• 값 열에 빈 셀 또는 비수치 셀이 있음

이때 임의의 후보 열로 자동 재결속하지 않는다. 헤더·표 위치를 복구하거나, 원본 표에서 X와 값을 다시 선택해 explicit save한다. 저장은 최신 source snapshot과 stale-source guard를 통과해야 한다.

8. Source of truth와 저장 경계

Chart에는 네 층이 있다.

Chart는 standalone CSV/JSON dataset, 업로드한 데이터, cross-document query, raw ECharts/Vega/HTML/CSS option을 원본으로 삼지 않는다. 다른 문서의 표를 합치려면 먼저 Markdown 또는 지원되는 구조 표로 명시적 원본을 만든다.

9. 수식과 구조 표의 표시값

표 셀에 source-visible formula literal이 있으면 편집 시에는 그 literal이 보존된다. 읽기·발행 경계에서 지원되는 표시값을 materialize해 Chart, Slide, Hugo 입력으로 사용한다.

• Chart profile은 수식 그래프를 소유하지 않는다.
• 수식 literal과 표시값을 Table에서 먼저 확인한다.
• 표시값을 계산할 수 없으면 Chart를 추측하지 않고 데이터 진단 또는 blocked 상태를 표시한다.
• 직접 glif-calc dependency graph를 Chart series에 연결하는 것은 이 guide의 저장 계약이 아니다.

10. Desktop, Slide, Hugo의 차이

Desktop

Desktop은 ECharts adapter로 profile intent를 interactive card로 렌더링한다. tooltip, hover, legend toggle, zoom, brush는 세션에서만 동작한다. lazy mount와 exact/high-confidence table reconciliation으로 큰 문서의 불필요한 렌더링을 줄인다.

Slide

Slide는 generated static chart config를 소비한다. sourceBlock, sourceRange, X/series, 유형, 색 token, 제목 style을 유지하지만 Desktop 상호작용을 그대로 내보내는 것이 아니다.

Hugo

Hugo는 glif.chart.projection generated transport를 사용한다. 이는 Markdown의 두 번째 원본이 아니라 publish 시점의 source-derived config다.

• 최대 80행
• 최대 8 series
• 지원되는 15개 bounded 유형만 materialize
• profile이 없을 때만 auto-detect fallback
• row/series가 잘리면 정적 출력에 degrade metadata와 bounded notice를 남김
• Chart image/PNG/PDF artifact를 별도 파일로 자동 생성한다고 주장하지 않음

11. 접근성

Chart card는 표 번호·행 수·X·series·데이터 품질을 합친 접근성 label을 제공한다. 정보 패널의 숫자·빈 셀·비수치 셀 chip과 최소·최대 범위는 시각 차트만 보지 않고 데이터 shape를 확인하는 보조 경로다.

실무 체크:

• 차트만 보고 결론 내리지 말고 같은 table을 함께 제공한다.
• 색 token만으로 series를 구분하지 않는다. legend 이름과 source 열 이름을 유지한다.
• 긴 X 라벨은 horizontal-bar를 검토한다.
• heatmap·pie·radar는 정확한 수치 확인을 위해 Table을 병행한다.
• static publish에서는 source/degrade metadata와 bounded notice가 보이는지 확인한다.

전체 narrated insight summary와 golden accessibility parity는 별도 release-QA 대상이다. 이 페이지는 현재 구현된 card label·diagnostics·static metadata 범위만 보증한다.

12. 이미지·동영상으로 따라 하기

같은 원문, 다른 표현

두 이미지는 같은 fixture 문서를 Source와 Chart로 연 것이다. 숫자를 복사해 별도 차트를 만든 것이 아니라 같은 table block을 읽는다.

정보 패널과 데이터 진단

유형 전환과 원문 반영

영상은 Source → Chart → Chart info → 유형·series 변경 → Source 셀 수정 → Chart 재확인의 순서를 실제 앱에서 기록한다. 클릭 위치와 현재 선택 상태가 함께 표시되며, 결과는 fixture 원문 hash와 함께 evidence manifest에 기록한다.

13. Hugo 배포 전 체크리스트

• 모든 표에 고유한 헤더가 있다.
• X 셀이 비어 있지 않다.
• 선택한 값 열은 숫자만 포함한다.
• 반복 X를 자동 집계로 오해하지 않았다.
• Chart 유형이 데이터의 질문과 맞다.
• funnel은 하나의 series, 음수 금지 조건을 지킨다.
• series 색·축·누적 설정이 원문 단위와 맞다.
• 기준선·추세선이 유형에서 지원되는지 확인했다.
• Chart intent가 최신 원문을 가리키고 blocked/invalid 상태가 아니다.
• Hugo의 80행/8 series bounded 조건을 확인했다.
• 같은 원문 Table과 Chart 이미지를 함께 검토했다.
• 동영상 시나리오의 클릭·원문 변경·재확인을 재생했다.

14. 관련 문서와 실증 근거

• Chart lab fixture
• Table과 Chart 기능 비교
• Desktop과 Hugo 결과 비교
• 개발 정본: chart-projection-ceiling-roadmap.md, chart-workspace-contract.md, document-projection-profile-contract.md
• 검증 evidence: chart-evidence.json과 evidence-manifest.json

이 장의 feature IDs는 ED-01(원문 편집), ED-23(프로젝션 설정), PB-01(발행 materialization)이다. 예제·이미지·동영상은 세 ID가 모두 같은 source-backed Chart 흐름에서 실제로 통과했는지 함께 검증한다.