@leviosa-ai/detail-page-editor 0.1.0

package/lib/detail-page/canvas-menu.ts

@@ -0,0 +1,182 @@
+/**
+ * 캔버스 우클릭 메뉴의 항목 구성과 동작. UI와 떼어 놓아 규칙만 테스트한다.
+ *
+ * 스톡 편집기는 ``canvas/canvas/context-menu``에 자기 메뉴를 갖고 있지만 ``page.js``가
+ * ``contextmenu``를 한 번도 안 단다 — 스톡 ``<Workspace>``가 달던 것이고, 우리는 그
+ * ``<Workspace>``를 갈아치웠다. 스톡 메뉴를 되살리지 않는 이유는 두 가지다.
+ *
+ * 1. 블루프린트 팝오버라 캔버스 위 다른 오버레이(전부 Tailwind)와 안 맞는다.
+ * 2. 항목이 모자란다. 그룹/해제가 없고, ``useCopyStyle``을 import 해 놓고 실제로는
+ *    쓰지 않는다(죽은 코드). 우리 문서는 대부분이 그룹이라 그룹 해제가 꼭 필요하다.
+ */
+
+import { groupAction } from "./group-action";
+import {
+  applyFormat,
+  canCopyFormat,
+  canPasteFormat,
+  copyFormat,
+  heldFormat,
+  holdFormat,
+} from "./format-painter";
+import { canMoveZ, moveZ, zOrderOf, type ZOrderElement } from "./z-order";
+
+export type CanvasMenuAction =
+  | "duplicate"
+  | "delete"
+  | "lock"
+  | "unlock"
+  | "copyFormat"
+  | "pasteFormat"
+  | "front"
+  | "forward"
+  | "backward"
+  | "back"
+  | "group"
+  | "ungroup";
+
+export type CanvasMenuItem = {
+  action: CanvasMenuAction;
+  disabled: boolean;
+  /** 이 항목 **위에** 구분선을 긋는다. */
+  separated?: boolean;
+};
+
+export type MenuElement = ZOrderElement & {
+  type?: string;
+  locked?: boolean;
+  clone?: (attrs?: Record<string, unknown>, opts?: { skipSelect?: boolean }) => unknown;
+  set?: (props: Record<string, unknown>) => void;
+};
+
+export type CanvasMenuStore = {
+  selectedElements?: MenuElement[];
+  selectedElementsIds?: string[];
+  pages?: Array<{ id: string; children?: Array<{ id: string; type?: string }> }>;
+  deleteElements?: (ids: string[]) => void;
+  groupElements?: (ids: string[]) => void;
+  ungroupElements?: (ids: string[]) => void;
+  history?: { startTransaction?: () => void; endTransaction?: () => void };
+};
+
+/** 선택 요소가 전부 잠겨 있는가 — 메뉴에 잠금 대신 잠금 해제를 띄운다. */
+export function allLocked(els: ReadonlyArray<MenuElement>): boolean {
+  return els.length > 0 && els.every((el) => el.locked === true);
+}
+
+/**
+ * 지금 선택에 대해 띄울 항목들. 선택이 없으면 빈 배열 = 메뉴를 아예 안 연다.
+ *
+ * 순서는 z-order를 **단일 선택일 때만** 낸다. 여럿을 한꺼번에 "앞으로" 보내면 서로의
+ * 상대 순서가 어떻게 되어야 하는지가 모호하고, 우측 패널도 같은 이유로 단일 전용이다.
+ */
+export function canvasMenuItems(store: CanvasMenuStore): CanvasMenuItem[] {
+  const els = store.selectedElements ?? [];
+  if (els.length === 0) return [];
+
+  const locked = allLocked(els);
+  const anyLocked = els.some((el) => el.locked === true);
+  const single = els.length === 1 ? els[0] : null;
+  const order = single ? zOrderOf(single) : null;
+  const group = groupAction(store, false);
+  const ungroup = groupAction(store, true);
+
+  const items: CanvasMenuItem[] = [
+    // 잠긴 요소를 복제하면 잠긴 사본이 생겨 만질 수도 지울 수도 없다.
+    { action: "duplicate", disabled: anyLocked },
+    { action: locked ? "unlock" : "lock", disabled: false },
+    { action: "delete", disabled: anyLocked },
+    // 서식은 하나에서 떠서 여럿에 먹인다 — 복사는 단일 선택일 때만.
+    { action: "copyFormat", disabled: !single || !canCopyFormat(single), separated: true },
+    {
+      action: "pasteFormat",
+      disabled: anyLocked || !canPasteFormat(heldFormat(), els),
+    },
+    { action: "front", disabled: !canMoveZ(order, "front"), separated: true },
+    { action: "forward", disabled: !canMoveZ(order, "forward") },
+    { action: "backward", disabled: !canMoveZ(order, "backward") },
+    { action: "back", disabled: !canMoveZ(order, "back") },
+  ];
+
+  // 그룹/해제는 해당될 때만 낸다 — 늘 회색으로 떠 있으면 메뉴만 길어진다.
+  if (group?.kind === "group") {
+    items.push({ action: "group", disabled: false, separated: true });
+  }
+  if (ungroup?.kind === "ungroup") {
+    items.push({
+      action: "ungroup",
+      disabled: false,
+      separated: group?.kind !== "group",
+    });
+  }
+  return items;
+}
+
+/**
+ * 한 항목을 실행한다.
+ *
+ * 여러 요소를 한 번에 만지는 동작(복제·잠금)은 히스토리 트랜잭션으로 묶는다. 안 묶으면
+ * ⌘Z를 선택 개수만큼 눌러야 원래대로 돌아간다.
+ */
+export function runCanvasMenuAction(
+  store: CanvasMenuStore,
+  action: CanvasMenuAction,
+): void {
+  const els = store.selectedElements ?? [];
+  if (els.length === 0) return;
+  const ids = els.map((el) => el.id);
+
+  const inTransaction = (fn: () => void) => {
+    store.history?.startTransaction?.();
+    try {
+      fn();
+    } finally {
+      store.history?.endTransaction?.();
+    }
+  };
+
+  switch (action) {
+    case "duplicate":
+      // clone()은 항상 요소의 **페이지**에 추가한다(node-model: e.page.addElement).
+      // 그룹 자식의 x/y도 페이지 좌표라, 그룹 안 도형을 복제하면 제자리에 사본이
+      // 생기고 최상위로 나온다 — 그룹을 오염시키지 않는 편이 낫다.
+      inTransaction(() => {
+        for (const el of els) el.clone?.({}, { skipSelect: true });
+      });
+      return;
+    case "delete":
+      store.deleteElements?.(ids);
+      return;
+    case "copyFormat":
+      if (els.length === 1) holdFormat(copyFormat(els[0]));
+      return;
+    case "pasteFormat": {
+      const copied = heldFormat();
+      // 여럿에 한 번에 먹일 때 ⌘Z 한 번으로 전부 돌아가게 묶는다.
+      if (copied) inTransaction(() => applyFormat(copied, els));
+      return;
+    }
+    case "lock":
+    case "unlock":
+      inTransaction(() => {
+        for (const el of els) el.set?.({ locked: action === "lock" });
+      });
+      return;
+    case "front":
+    case "forward":
+    case "backward":
+    case "back":
+      if (els.length === 1) moveZ(els[0], action);
+      return;
+    case "group": {
+      const plan = groupAction(store, false);
+      if (plan?.kind === "group") store.groupElements?.(plan.ids);
+      return;
+    }
+    case "ungroup": {
+      const plan = groupAction(store, true);
+      if (plan?.kind === "ungroup") store.ungroupElements?.(plan.ids);
+      return;
+    }
+  }
+}

package/lib/detail-page/chart/defaults.ts

@@ -0,0 +1,283 @@
+/**
+ * 기본 스펙과 **좌측 패널 프리셋 카탈로그**.
+ *
+ * 프리셋 룩은 범용 차트 라이브러리 기본값이 아니라 우리 템플릿이 실제로 쓰는 형태에서
+ * 뽑았다(가로 막대 + 라벨/값 한 줄 + 강조 항목 하나). 범용 차트 스타일은 상세페이지에
+ * 얹는 순간 바로 "AI티"가 난다 — 공용 도형 카탈로그를 템플릿에서 추출한 것과 같은 원칙.
+ */
+
+import type { ChartCard, ChartKind, ChartSpec, ChartStyle } from "./types";
+
+/** 폰트를 못 정했을 때. 편집기 캔버스가 쓰는 본문 폰트와 같다. */
+export const FALLBACK_CHART_FONT = "Pretendard";
+
+/**
+ * 기본 팔레트 — 무채색 램프.
+ *
+ * 알록달록한 기본 팔레트를 주면 사용자가 그대로 두고, 상세페이지 전체 톤이 깨진다.
+ * 흑연 램프는 어떤 브랜드 색과도 안 싸우고, 강조 색은 사용자가 하나만 고르면 된다.
+ */
+export const DEFAULT_CHART_PALETTE = ["#18181B", "#52525B", "#A1A1AA", "#D4D4D8"];
+
+export const DEFAULT_CHART_STYLE: ChartStyle = {
+  palette: DEFAULT_CHART_PALETTE,
+  mutedColor: "#D4D4D8",
+  trackColor: "#F4F4F5",
+  labelColor: "#3F3F46",
+  valueColor: "#18181B",
+  fontFamily: FALLBACK_CHART_FONT,
+  labelSize: 20,
+  valueSize: 22,
+  barSize: 16,
+  gap: 26,
+  labelGap: 12,
+  plotSize: 260,
+  cornerRadius: 8,
+  showTrack: true,
+};
+
+/** 새 차트를 놓을 때 들어가는 예시 데이터(사용자가 바로 갈아 끼울 것). */
+const SAMPLE = {
+  labels: ["본 제품", "일반 제품 A", "일반 제품 B"],
+  values: [92, 61, 45],
+};
+
+export type ChartSpecInit = {
+  kind?: ChartKind;
+  width: number;
+  fontFamily?: string;
+  style?: Partial<ChartStyle>;
+  options?: Partial<ChartSpec["options"]>;
+  data?: ChartSpec["data"];
+};
+
+/** 기본 스펙 한 벌. ``frame.height``는 렌더가 채우므로 0으로 시작한다. */
+export function createChartSpec({
+  kind = "bar-h",
+  width,
+  fontFamily,
+  style,
+  options,
+  data,
+}: ChartSpecInit): ChartSpec {
+  return {
+    v: 1,
+    kind,
+    frame: { width: Math.max(80, Math.round(width)), height: 0 },
+    data: data ?? {
+      labels: [...SAMPLE.labels],
+      series: [{ name: "값", values: [...SAMPLE.values] }],
+    },
+    options: {
+      max: "auto",
+      unit: "",
+      decimals: 0,
+      showValue: true,
+      sort: "none",
+      highlightIndex: 0,
+      ...options,
+    },
+    style: {
+      ...DEFAULT_CHART_STYLE,
+      fontFamily: fontFamily || FALLBACK_CHART_FONT,
+      ...style,
+    },
+  };
+}
+
+export type ChartPreset = {
+  id: string;
+  kind: ChartKind;
+  /** ``branding`` 네임스페이스의 라벨 키. */
+  labelKey: string;
+  style?: Partial<ChartStyle>;
+  options?: Partial<ChartSpec["options"]>;
+  /** 예시 데이터. 안 주면 ``SAMPLE``. 시리즈가 여럿이어야 뜻이 사는 종류만 채운다. */
+  data?: ChartSpec["data"];
+};
+
+/** 여러 줄 비교용 예시(꺾은선·누적). 한 줄짜리 샘플로는 범례가 안 뜬다. */
+const MULTI_SAMPLE: ChartSpec["data"] = {
+  labels: ["1주", "2주", "4주", "8주"],
+  series: [
+    { name: "본 제품", values: [42, 61, 78, 92] },
+    { name: "일반 제품", values: [40, 47, 53, 58] },
+  ],
+};
+
+/**
+ * 프리셋이 기본으로 까는 **흰 바탕**.
+ *
+ * 차트는 글자와 얇은 선으로 이루어져 있어서 바탕이 없으면 섹션 배경색을 그대로 탄다.
+ * 어두운 섹션에 놓는 순간 검은 글씨가 사라지고, 미리보기(흰 패널 위)와 결과가 달라진다.
+ * ``card``는 이미 있던 기구다 — 여기서는 테두리 없이 바탕과 안여백만 쓴다.
+ *
+ * 기본값(``DEFAULT_CHART_STYLE``)이 아니라 **프리셋에만** 건다. 기본값을 바꾸면 이미
+ * 문서에 박힌 차트들이 다시 그려질 때 같이 변한다.
+ */
+const CARD_PLAIN: ChartCard = {
+  fill: "#FFFFFF",
+  stroke: null,
+  width: 0,
+  radius: 8,
+  pad: 24,
+};
+
+/**
+ * 좌측 패널에 뜨는 프리셋.
+ *
+ * 종류당 하나가 아니라 "쓰임"당 하나다 — 같은 가로 막대라도 비교표(강조 있음)와
+ * 순위표(강조 없음, 정렬됨)는 다른 물건이다.
+ */
+const PRESETS: ChartPreset[] = [
+  {
+    id: "bar-h-compare",
+    kind: "bar-h",
+    labelKey: "detailPage.chart.presets.barHCompare",
+    options: { highlightIndex: 0 },
+  },
+  {
+    id: "bar-h-rank",
+    kind: "bar-h",
+    labelKey: "detailPage.chart.presets.barHRank",
+    options: { highlightIndex: null, sort: "desc" },
+    style: { showTrack: false, barSize: 22 },
+  },
+  {
+    id: "bar-h-percent",
+    kind: "bar-h",
+    labelKey: "detailPage.chart.presets.barHPercent",
+    options: { unit: "%", max: 100, highlightIndex: null },
+    style: { barSize: 12, cornerRadius: 6 },
+  },
+  {
+    id: "bar-v-compare",
+    kind: "bar-v",
+    labelKey: "detailPage.chart.presets.barVCompare",
+    options: { highlightIndex: 0 },
+  },
+  {
+    id: "bar-v-plain",
+    kind: "bar-v",
+    labelKey: "detailPage.chart.presets.barVPlain",
+    options: { highlightIndex: null },
+    style: { showTrack: false, barSize: 56, cornerRadius: 6 },
+  },
+  {
+    // 축 있는 막대그래프 — 브랜드 상세페이지가 실제로 쓰는 모양이다(기둥 밴드 ·
+    // 점선 눈금선 · 좌·하 축선 · 왼쪽 눈금 라벨 · 카드 프레임). 클라이언트 디자이너
+    // 요구사항 "도표의 경우 선을 명확하게 사용"이 여기 들어 있다.
+    //
+    // 지금 브랜드 템플릿은 이 모양을 손으로 계산한 통짜 SVG로 굽는다("1% = 6.5px"를
+    // 네 곳에 반영). 이 프리셋은 같은 그림을 resolved.max 하나에서 뽑으므로 수치를
+    // 고치면 막대·눈금선·눈금 라벨이 같이 따라간다.
+    id: "bar-v-axis",
+    kind: "bar-v",
+    labelKey: "detailPage.chart.presets.barVAxis",
+    options: { unit: "%", highlightIndex: null },
+    style: {
+      showTrack: false,
+      cornerRadius: 0,
+      barSize: 72,
+      plot: {
+        bands: "#F6F7F9",
+        grid: { count: 4, color: "#E3E5E8", dash: true },
+        axis: { color: "#1F2124", width: 1.4 },
+        ticks: { color: "#8A8F96", size: 14, unitCap: "(%)", gutter: 52 },
+      },
+      card: { fill: "#FFFFFF", stroke: "#E3E5E8", width: 1, radius: 4, pad: 26 },
+    },
+  },
+  {
+    id: "donut-share",
+    kind: "donut",
+    labelKey: "detailPage.chart.presets.donutShare",
+    options: { unit: "%", highlightIndex: 0 },
+    style: { showTrack: false },
+  },
+  {
+    id: "gauge-rate",
+    kind: "gauge",
+    labelKey: "detailPage.chart.presets.gaugeRate",
+    options: { unit: "%", max: 100, highlightIndex: 0 },
+  },
+  {
+    id: "line-trend",
+    kind: "line",
+    labelKey: "detailPage.chart.presets.lineTrend",
+    options: { highlightIndex: null },
+    style: { showTrack: false },
+  },
+  {
+    id: "stack-mix",
+    kind: "stack",
+    labelKey: "detailPage.chart.presets.stackMix",
+    options: { highlightIndex: null },
+    style: { showTrack: false },
+  },
+  {
+    // 값만 남긴 가로 막대 — 트랙도 강조도 없이 순위만 읽히면 되는 자리.
+    id: "bar-h-minimal",
+    kind: "bar-h",
+    labelKey: "detailPage.chart.presets.barHMinimal",
+    options: { highlightIndex: null, showValue: true },
+    style: { showTrack: false, barSize: 10, cornerRadius: 5, gap: 34 },
+  },
+  {
+    // 순위 세로 막대 — 내림차순으로 세워 1위가 왼쪽에 온다.
+    id: "bar-v-rank",
+    kind: "bar-v",
+    labelKey: "detailPage.chart.presets.barVRank",
+    options: { highlightIndex: 0, sort: "desc" },
+    style: { showTrack: false, barSize: 48, cornerRadius: 6 },
+  },
+  {
+    // 굵은 도넛 — 비중 하나를 크게 보여 준다(만족도·재구매율).
+    id: "donut-single",
+    kind: "donut",
+    labelKey: "detailPage.chart.presets.donutSingle",
+    options: { unit: "%", max: 100, highlightIndex: 0 },
+    style: { showTrack: true, plotSize: 300 },
+  },
+  {
+    // 점수 게이지 — 100점 만점 대신 단위를 "점"으로 둔다.
+    id: "gauge-score",
+    kind: "gauge",
+    labelKey: "detailPage.chart.presets.gaugeScore",
+    options: { unit: "점", max: 100, decimals: 0, highlightIndex: 0 },
+    style: { showTrack: true, barSize: 26 },
+  },
+  {
+    // 여러 줄 꺾은선 — 우리와 경쟁 제품을 같은 축에서 비교한다(범례가 붙는다).
+    id: "line-compare",
+    kind: "line",
+    labelKey: "detailPage.chart.presets.lineCompare",
+    options: { highlightIndex: null, showValue: false },
+    style: { showTrack: false, plotSize: 280 },
+    data: MULTI_SAMPLE,
+  },
+  {
+    // 100% 누적 — 구성비를 한 줄에 채운다(성분 비율·연령대 분포).
+    id: "stack-share",
+    kind: "stack",
+    labelKey: "detailPage.chart.presets.stackShare",
+    options: { unit: "%", max: 100, highlightIndex: null },
+    style: { showTrack: false, barSize: 34, cornerRadius: 4 },
+    data: {
+      labels: ["보습", "진정", "탄력"],
+      series: [
+        { name: "본 제품", values: [48, 32, 20] },
+        { name: "일반 제품", values: [30, 30, 40] },
+      ],
+    },
+  },
+];
+
+/**
+ * 좌측 패널이 읽는 최종 목록. 바탕을 안 정한 프리셋에는 흰 카드를 깐다 —
+ * 삽입 결과가 미리보기와 같아야 한다(미리보기는 흰 패널 위에서 그려진다).
+ */
+export const CHART_PRESETS: ChartPreset[] = PRESETS.map((preset) => ({
+  ...preset,
+  style: { card: CARD_PLAIN, ...preset.style },
+}));

package/lib/detail-page/chart/format.ts

@@ -0,0 +1,66 @@
+/**
+ * 차트 값의 **문자열 ↔ 숫자** 변환.
+ *
+ * 사용자는 값을 엑셀에서 붙여넣거나 손으로 친다. "1,234", "45%", "0.9ms", "  12 "
+ * 같은 것들이 그대로 들어오므로, 읽을 때는 관용적으로 흡수하고 쓸 때는 스펙의
+ * 단위·소수점 규칙 하나로만 찍는다(그래야 라벨이 제각각이 되지 않는다).
+ */
+
+/**
+ * 사람이 쓴 값 문자열을 숫자로. 못 읽으면 ``null``(= 값 없음, 0이 아니다).
+ *
+ * 천단위 콤마는 버리고, 단위 접미사·앞뒤 공백·통화기호도 떼어낸다. 소수점 콤마
+ * ("1,5")는 **지원하지 않는다** — 천단위 콤마와 구분할 방법이 없고, 한국어 상세페이지
+ * 맥락에서는 천단위 쪽이 압도적으로 흔하다.
+ */
+export function parseChartNumber(input: unknown): number | null {
+  if (typeof input === "number") return Number.isFinite(input) ? input : null;
+  if (typeof input !== "string") return null;
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  // 부호 + 숫자 + (천단위 콤마) + 소수부만 남긴다. 앞뒤에 붙은 단위/기호는 버린다.
+  const match = trimmed.match(/-?\d[\d,]*(?:\.\d+)?/);
+  if (!match) return null;
+  const parsed = Number(match[0].replace(/,/g, ""));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export type FormatOptions = {
+  decimals?: number;
+  unit?: string;
+  /** 천단위 구분. 기본 켬 — 상세페이지 수치는 대개 크다. */
+  grouping?: boolean;
+};
+
+/** 값 + 단위. ``null``이면 빈 문자열(칸을 비워 두는 게 0으로 거짓말하는 것보다 낫다). */
+export function formatChartValue(
+  value: number | null,
+  { decimals = 0, unit = "", grouping = true }: FormatOptions = {},
+): string {
+  if (value === null || !Number.isFinite(value)) return "";
+  const places = Math.max(0, Math.min(6, Math.round(decimals)));
+  const fixed = value.toFixed(places);
+  if (!grouping) return `${fixed}${unit}`;
+  const [whole, fraction] = fixed.split(".");
+  const sign = whole.startsWith("-") ? "-" : "";
+  const digits = sign ? whole.slice(1) : whole;
+  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return `${sign}${grouped}${fraction ? `.${fraction}` : ""}${unit}`;
+}
+
+/**
+ * 데이터에서 소수 자릿수를 추론한다(붙여넣기 직후 기본값 잡기용).
+ *
+ * 하나라도 소수를 쓰면 그 최대 자릿수를 따라간다. 2자리를 넘기면 차트 라벨이 길어져
+ * 읽기 어려우니 2에서 자른다.
+ */
+export function inferDecimals(values: ReadonlyArray<number | null>): number {
+  let most = 0;
+  for (const value of values) {
+    if (value === null || !Number.isFinite(value)) continue;
+    const text = String(value);
+    const dot = text.indexOf(".");
+    if (dot >= 0) most = Math.max(most, text.length - dot - 1);
+  }
+  return Math.min(2, most);
+}

package/lib/detail-page/chart/normalize.ts

@@ -0,0 +1,149 @@
+/**
+ * 스펙 → **렌더에 바로 쓸 수 있는 형태**로 고르는 단계.
+ *
+ * 여기서 지키는 규칙 하나: **데이터를 절대 잘라내지 않는다.** 종류마다 그릴 수 있는
+ * 시리즈 수가 다르지만(도넛은 하나뿐), 못 그리는 시리즈는 렌더에서 빼기만 하고
+ * ``spec.data``에는 그대로 남긴다. 그래야 막대 → 도넛 → 막대로 돌아왔을 때 잃었던
+ * 시리즈가 되살아난다. Canva가 "차트 종류를 바꿔도 데이터가 유지된다"고 말하는
+ * 부분이 정확히 이것이다.
+ */
+
+import type { ChartKind, ChartSeries, ChartSpec } from "./types";
+
+/** 종류별로 **그릴 수 있는** 시리즈 수. ``null``이면 제한 없음. */
+export const SERIES_LIMIT: Record<ChartKind, number | null> = {
+  "bar-h": 1,
+  "bar-v": 1,
+  donut: 1,
+  gauge: 1,
+  line: null,
+  stack: null,
+};
+
+export type ResolvedChart = {
+  /** 정렬이 적용된 뒤의 라벨. */
+  labels: string[];
+  /** 렌더에 실제로 쓰이는 시리즈(정렬 적용). */
+  series: ChartSeries[];
+  /** 축 최댓값(항상 > 0). */
+  max: number;
+  /**
+   * **정렬 후 위치로 옮긴** 강조 인덱스.
+   *
+   * ``options.highlightIndex``는 사용자가 표에서 고른 원본 행 번호다. 정렬을 켜면
+   * 그 행이 다른 자리로 가므로, 옮겨진 자리를 다시 계산해 두지 않으면 엉뚱한 막대가
+   * 강조된다.
+   */
+  highlightIndex: number | null;
+  /** 스펙에 남아 있지만 이 종류에서는 안 그려지는 시리즈 수. 0이면 알릴 것 없음. */
+  hiddenSeries: number;
+};
+
+/** 정렬 기준이 되는 시리즈(첫 번째)의 값. 없으면 전부 null. */
+function sortKeyValues(series: ChartSeries[], length: number): (number | null)[] {
+  const first = series[0]?.values ?? [];
+  return Array.from({ length }, (_, i) => first[i] ?? null);
+}
+
+/**
+ * 정렬된 인덱스 순서. ``null``은 항상 뒤로 보낸다 — 빈 칸이 큰 값 사이에 끼면
+ * 막대가 끊긴 것처럼 보인다.
+ */
+function orderOf(
+  values: (number | null)[],
+  sort: ChartSpec["options"]["sort"],
+): number[] {
+  const order = values.map((_, i) => i);
+  if (sort === "none") return order;
+  const dir = sort === "desc" ? -1 : 1;
+  return order.sort((a, b) => {
+    const va = values[a];
+    const vb = values[b];
+    if (va === null && vb === null) return a - b;
+    if (va === null) return 1;
+    if (vb === null) return -1;
+    if (va === vb) return a - b; // 동점이면 원래 순서 유지(안정 정렬)
+    return (va - vb) * dir;
+  });
+}
+
+/**
+ * 축 최댓값.
+ *
+ * ``"auto"``면 모든 시리즈의 최댓값. 값이 전부 0/음수/없음이면 1로 떨어진다 — 0으로
+ * 나눠 NaN 폭을 만드는 것보다 "전부 빈 막대"가 낫다. 누적(stack)은 항목별 합이 축을
+ * 정하므로 합으로 잰다.
+ */
+function resolveMax(
+  kind: ChartKind,
+  series: ChartSeries[],
+  labelCount: number,
+  max: ChartSpec["options"]["max"],
+): number {
+  if (typeof max === "number" && Number.isFinite(max) && max > 0) return max;
+  let found = 0;
+  if (kind === "stack") {
+    for (let i = 0; i < labelCount; i += 1) {
+      let sum = 0;
+      for (const s of series) sum += Math.max(0, s.values[i] ?? 0);
+      found = Math.max(found, sum);
+    }
+  } else {
+    for (const s of series) {
+      for (const value of s.values) {
+        if (value !== null && Number.isFinite(value)) found = Math.max(found, value);
+      }
+    }
+  }
+  return found > 0 ? found : 1;
+}
+
+/** 스펙을 렌더 가능한 형태로 고른다. */
+export function resolveChart(spec: ChartSpec): ResolvedChart {
+  const limit = SERIES_LIMIT[spec.kind];
+  const all = spec.data.series;
+  const visible = limit === null ? all : all.slice(0, limit);
+  const labelCount = spec.data.labels.length;
+
+  const order = orderOf(sortKeyValues(visible, labelCount), spec.options.sort);
+  const labels = order.map((i) => spec.data.labels[i] ?? "");
+  const series = visible.map((s) => ({
+    name: s.name,
+    values: order.map((i) => s.values[i] ?? null),
+  }));
+
+  const source = spec.options.highlightIndex;
+  const moved =
+    source === null || source === undefined ? -1 : order.indexOf(source);
+
+  return {
+    labels,
+    series,
+    max: resolveMax(spec.kind, series, labelCount, spec.options.max),
+    highlightIndex: moved >= 0 ? moved : null,
+    hiddenSeries: Math.max(0, all.length - visible.length),
+  };
+}
+
+/**
+ * 항목 색: 강조가 지정돼 있으면 그 항목만 팔레트 첫 색, 나머지는 muted.
+ *
+ * ``highlight``는 **정렬 후** 인덱스여야 한다(``resolveChart``가 옮겨 준 값).
+ */
+export function itemColor(
+  spec: ChartSpec,
+  index: number,
+  highlight: number | null,
+): string {
+  const { palette, mutedColor } = spec.style;
+  if (highlight !== null && highlight !== undefined) {
+    return index === highlight ? (palette[0] ?? mutedColor) : mutedColor;
+  }
+  return palette[index % Math.max(1, palette.length)] ?? mutedColor;
+}
+
+/** 0~1 비율. 축이 0이거나 값이 없으면 0. */
+export function ratioOf(value: number | null, max: number): number {
+  if (value === null || !Number.isFinite(value) || max <= 0) return 0;
+  return Math.max(0, Math.min(1, value / max));
+}