데이터 / doc-viz
DocViz
인쇄 문서(.axe-doc)용 서버 SVG 데이터 비주얼 5종.
01 · Specimen
먼저 보고, 그다음 계약을 읽습니다
인쇄 문서(.axe-doc)용 서버 SVG 데이터 비주얼 5종.
Workbench 불러오는 중…
Component intent의도와 경계 읽기
DocFigure(caption/note 래퍼) · DocBarChart(grouped bar) · DocLineChart(line, dashed·markers) · DocDonut(pathLength=100 도넛) · DocDiagram(수동 grid 투자구조도)로 구성된 컴포넌트군. 전부 sync 순수 함수이며 "use client" 가 없어 RSC 와 client island 양쪽에서 렌더된다(JS 0, 서버 SVG). 화면 대시보드 차트가 아니라 IC 메모·계약서 같은 종이 문서 전용 — 화면 차트는 chart/Chart.tsx(recharts)로 경계를 나눈다. resolved-spec 규약: 축 ticks·표시 문자열(₩60억, 15.8%)은 호출자가 미리 계산해 넘기며 함수 prop 은 받지 않는다. markup·수식이 _viz.html.jinja 매크로와 1:1 파리티(golden fixtures 로 검증).
02 · Use
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
DocBarChart (grouped bar)
import { DocBarChart } from "@axe/ui";<DocBarChart title="분기별 매출 (억원)" caption="그림 1. 분기 실적" labels={["1Q", "2Q", "3Q", "4Q"]} series={[ { label: "2024", values: [12, 18, 15, 22] }, { label: "2025", values: [16, 21, 19, 28] }, ]} ticks={[0, 10, 20, 30]}/>DocLineChart (실적 실선 + 전망 파선)
import { DocLineChart, niceTicks } from "@axe/ui";<DocLineChart title="AUM 추이 (억원)" labels={["1월", "2월", "3월", "4월"]} series={[ { label: "실적", values: [40, 44, 47, 52], markers: true }, { label: "전망", values: [52, 55, 58, 61], dashed: true }, ]} ticks={niceTicks(61)}/>DocDonut (지분 구성)
import { DocDonut } from "@axe/ui";<DocDonut title="지분 구성" slices={[ { label: "AXE", value: 15.8, display: "15.8%" }, { label: "창업자", value: 60, display: "60.0%" }, { label: "기타", value: 24.2, display: "24.2%" }, ]} center={{ value: "15.8%", label: "AXE 지분" }}/>DocDiagram (투자 구조)
import { DocDiagram } from "@axe/ui";<DocDiagram title="투자 구조" cols={2} nodes={[ { id: "fund", label: "AXE 2호 펀드", kind: "fund", col: 0, row: 0 }, { id: "spc", label: "투자목적 SPC", kind: "spc", col: 1, row: 0 }, { id: "target", label: "타겟社", kind: "target", col: 0, row: 1 }, ]} edges={[ { from: "fund", to: "spc", label: "출자", kind: "flow" }, { from: "spc", to: "target", label: "지분 30%", kind: "new" }, ]}/>DocFigure (wide 래퍼 + note)
import { DocFigure, DocBarChart } from "@axe/ui";<DocFigure caption="그림 1. 분기 실적" note="단위: 억원 · 감사 전 수치" wide> <DocBarChart title="분기별 매출" labels={["1Q", "2Q", "3Q", "4Q"]} series={[{ label: "매출", values: [12, 18, 15, 22] }]} ticks={[0, 10, 20, 30]} /></DocFigure>03 · React
Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
title | string | 필수 | — | (공통) SVG <title> — 데이터 요약문(스크린리더 대체 텍스트). |
id | string | — | — | (공통) 미지정 시 useId 기반 안전 id(safeAutoId) 자동 생성. |
caption | string | — | — | (공통) figcaption(.axe-doc-viz__caption). |
width | number | — | — | (공통) viewBox 폭. 기본 bar/line 482, donut 231, diagram 은 grid 산출. |
height | number | — | — | (공통) viewBox 높이. 기본 bar/line 200, donut 170, diagram 은 grid 산출. |
srTable | boolean | — | true | (공통) 동일 데이터 스크린리더 표(.axe-doc__sr) 동봉. 인쇄에선 display:none. |
labels | string[] | 필수 | — | (Bar/Line) x 카테고리 라벨. |
series | DocBarSeries[] | DocLineSeries[] | 필수 | — | (Bar/Line) 시리즈 ≤6. DocLineSeries 는 dashed?·markers? 추가. |
ticks | number[] | 필수 | — | (Bar/Line) 축 눈금(resolved). 첫=축 최소, 마지막=축 최대. niceTicks 로 전처리 가능. |
tickLabels | string[] | — | — | (Bar/Line) 눈금 표시 문자열. 미지정 시 ticks 문자열화. |
valueLabels | string[][] | — | — | (Bar) 막대 위 표시 문자열 [series][category] — 포맷 함수 대체. |
slices | DocDonutSlice[] | 필수 | — | (Donut) { label, value, display? }. 마지막 슬라이스가 잔여로 합계 오차 흡수. |
center | { value: string; label?: string } | — | — | (Donut) 중앙 강조 — value + 선택 label. |
nodes | DocDiagramNode[] | 필수 | — | (Diagram) { id, label, sub?, kind?, col, row }. kind = corp|fund|spc|person|target(형태 구분). |
edges | DocDiagramEdge[] | 필수 | — | (Diagram) { from, to, label?, sub?, kind?, fromSide?, toSide?, offset? }. kind = equity|new|old|flow. |
cols | number | 필수 | — | (Diagram) 그리드 열 수. |
colW | number | — | 150 | (Diagram) 셀 폭(노드 120×44 가 중앙). |
rowH | number | — | 86 | (Diagram) 셀 높이. |
note | string | — | — | (Figure) 표/그림 밖 각주 한 줄(.axe-doc__tnotes). |
wide | boolean | — | — | (Figure) landscape 2-col 탈출(.axe-doc-viz--wide = column-span:all). |
children | React.ReactNode | 필수 | — | (Figure) 래핑 대상(표·차트 2-up 등). |
04 · Any stack
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-doc-viz | stable | 모든 doc-viz figure 의 루트(break-inside:avoid). |
.axe-doc-viz--bar | stable | DocBarChart 변형(루트). --line·--donut 은 series 색 채널 동형. DocDiagram 루트는 --diagram(4번째 변형)이나 스타일은 __node/__edge 가 담당(전용 --diagram CSS 규칙 없음). |
.axe-doc-viz--wide | stable | landscape 2-col 탈출(column-span:all) — DocFigure wide. |
.axe-doc-viz__caption | stable | figcaption 라벨. |
.axe-doc-viz__svg | stable | 차트 <svg>(role=img). |
.axe-doc-viz__series | stable | SVG 시리즈 그룹. --1~--6 색 사다리 + --dashed(line 예측)로 currentColor 채널. |
.axe-doc-viz__key | stable | 범례 항목. --1~--6 이 series 와 같은 색 토큰 공유. |
.axe-doc-viz__legend | stable | SVG 밖 HTML 범례 ul(스크린리더·한글 줄바꿈). |
.axe-doc-viz__slice | stable | DocDonut 슬라이스 circle(stroke-dasharray 백분율). |
.axe-doc-viz__donut-value | stable | 도넛 중앙 강조 값. --donut-label 은 보조 라벨. |
.axe-doc-viz__grid | internal | 격자선 g(축·눈금·라벨과 함께 드로잉 세부). |
.axe-doc-viz__value | internal | 막대 위 값 텍스트(드로잉 세부). |
.axe-doc-diagram__node | stable | 다이어그램 노드 박스. --fund|spc|person|target 이 테두리 형태 구분. |
.axe-doc-diagram__node-label | stable | 노드 라벨 텍스트(--node-sub = 보조). |
.axe-doc-diagram__edge | stable | 엣지 그룹. --new(accent)·--old(파선)·--flow(점선)가 이중 부호. |
.axe-doc-diagram__edge-label | stable | 엣지 라벨 텍스트(halo, --edge-sub = 보조). |
.axe-doc-diagram__edge-arrow | internal | 화살촉 marker path(marker 자체에 edge 클래스 부여, 드로잉 세부). |
.axe-doc__sr | stable | 동일 데이터 스크린리더 표(off-screen, 인쇄 display:none). |
.axe-doc__tnotes | stable | DocFigure note 각주 리스트. |
05 · Inclusive
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
ARIA
각 차트 <svg> = role=img + aria-labelledby → <title>(title prop 필수, 데이터 요약문). srTable(기본 true) 이 동일 수치를 off-screen <table>(.axe-doc__sr, scope 지정)로 동봉해 스크린리더가 실제 값에 접근한다.
Notes
색맹·흑백 복사 안전을 위한 이중 부호: 노드 kind 는 색이 아닌 테두리 형태, edge old 는 파선, line 예측 시리즈는 dashed. 범례는 SVG 밖 HTML ul 로 두어 낭독 순서·한글 줄바꿈을 보장. 상호작용 없는 정적 인쇄 그래픽이라 키보드 처리는 없음.
06 · Judgment