@opendata-ai/openchart-core 8.8.0 → 8.9.1

package/dist/index.js

@@ -1,3 +1,121 @@
+// src/helpers/edit-transactions.ts
+function isContainer(value) {
+  return Array.isArray(value) || value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function clone(value) {
+  if (Array.isArray(value)) return value.map(clone);
+  if (!isContainer(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, clone(child)]));
+}
+function tokens(path) {
+  if (!path.startsWith("/")) throw new Error("Expected a non-root JSON Pointer beginning with /.");
+  return path.slice(1).split("/").map((token) => {
+    if (/~(?:[^01]|$)/.test(token)) throw new Error("Invalid JSON Pointer escape.");
+    const decoded = token.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (["__proto__", "prototype", "constructor"].includes(decoded)) {
+      throw new Error("Unsafe property in edit path.");
+    }
+    return decoded;
+  });
+}
+function pointer(parts) {
+  return `/${parts.map((part) => part.replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+}
+function keyAt(parent, token, insert = false) {
+  if (!Array.isArray(parent)) return token;
+  if (insert && token === "-") return parent.length;
+  if (!/^(0|[1-9]\d*)$/.test(token)) throw new Error("Expected an array index.");
+  const index = Number(token);
+  if (!Number.isSafeInteger(index) || index > parent.length || !insert && index === parent.length) {
+    throw new Error("Array index is out of bounds.");
+  }
+  return index;
+}
+function read(parent, key) {
+  return parent[key];
+}
+function checkExpectation(root, parts, expected) {
+  if (!expected) return;
+  let end = -1;
+  for (let i = 0; i + 1 < parts.length; i++) {
+    if (parts[i] === "annotations" && /^(0|[1-9]\d*)$/.test(parts[i + 1])) end = i + 2;
+  }
+  if (end === -1) throw new Error("Annotation precondition requires an annotation path.");
+  let target = root;
+  for (const part of parts.slice(0, end)) {
+    if (!isContainer(target)) throw new Error("Annotation target no longer exists.");
+    const key = keyAt(target, part);
+    if (!Object.hasOwn(target, key)) throw new Error("Annotation target no longer exists.");
+    target = read(target, key);
+  }
+  if (!isContainer(target) || Array.isArray(target))
+    throw new Error("Annotation target is invalid.");
+  for (const field of ["id", "type", "text"]) {
+    if (Object.hasOwn(expected, field) && target[field] !== expected[field]) {
+      throw new Error(`Annotation ${field} changed; discard the stale edit.`);
+    }
+  }
+}
+function applyEditTransaction(spec, tx) {
+  const result = clone(spec);
+  const inverse = [];
+  for (const [opIndex, op] of tx.ops.entries()) {
+    try {
+      if (!["set", "add", "remove"].includes(op.op)) throw new Error("Unknown edit operation.");
+      if (op.op !== "remove" && !Object.hasOwn(op, "value"))
+        throw new Error("Edit value is missing.");
+      const parts = tokens(op.path);
+      checkExpectation(result, parts, op.expect);
+      let parent = result;
+      const created = [];
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (!isContainer(parent)) throw new Error("Cannot traverse a primitive or non-JSON value.");
+        const key2 = keyAt(parent, parts[i]);
+        if (!Object.hasOwn(parent, key2)) {
+          if (op.op !== "add" || Array.isArray(parent))
+            throw new Error("Intermediate container is missing.");
+          parent[key2] = /^(0|[1-9]\d*|-)$/.test(parts[i + 1]) ? [] : {};
+          created.push(pointer(parts.slice(0, i + 1)));
+        }
+        parent = read(parent, key2);
+      }
+      if (!isContainer(parent)) throw new Error("Edit parent is not a JSON container.");
+      const key = keyAt(parent, parts.at(-1), op.op === "add");
+      const exists = Object.hasOwn(parent, key);
+      const old = read(parent, key);
+      const path = pointer([...parts.slice(0, -1), String(key)]);
+      let undo;
+      if (op.op === "remove") {
+        if (!exists) throw new Error("Edit target no longer exists.");
+        if (Array.isArray(parent)) parent.splice(Number(key), 1);
+        else delete parent[key];
+        undo = { op: "add", path, value: old };
+      } else if (op.op === "add" && Array.isArray(parent)) {
+        parent.splice(Number(key), 0, clone(op.value));
+        undo = { op: "remove", path };
+      } else {
+        parent[key] = clone(op.value);
+        undo = exists ? { op: "set", path, value: old } : { op: "remove", path };
+      }
+      inverse.unshift(undo, ...created.reverse().map((path2) => ({ op: "remove", path: path2 })));
+    } catch (error) {
+      return {
+        ok: false,
+        error: {
+          opIndex,
+          path: op.path,
+          reason: error instanceof Error ? error.message : String(error)
+        }
+      };
+    }
+  }
+  return {
+    ok: true,
+    spec: result,
+    inverse: { ...tx.revision !== void 0 ? { revision: tx.revision } : {}, ops: inverse }
+  };
+}
+
 // src/types/encoding.ts
 function required(...types) {
   return { required: true, allowedTypes: types };
@@ -521,6 +639,13 @@ var CSS_TOKENS = [
   { name: "--oc-source-size", light: "11px" },
   { name: "--oc-source-weight", light: "400" },
   { name: "--oc-body-size", light: "13px" },
+  { name: "--oc-annotation-label", light: "#333333", dark: "#d1d5db" },
+  { name: "--oc-annotation-muted", light: "#6b7280", dark: "#9ca3af" },
+  { name: "--oc-annotation-leader", light: "#8f8f8f", dark: "#9aa0a6" },
+  { name: "--oc-annotation-rule", light: "#666666", dark: "#666666" },
+  { name: "--oc-annotation-range-fill", light: "#000000", dark: "#000000" },
+  { name: "--oc-annotation-marker-fill", light: "#ffffff", dark: "#0a0a0a" },
+  { name: "--oc-annotation-plate", light: "#ffffff", dark: "#0a0a0a" },
   { name: "--oc-eyebrow-size", light: "11px" },
   { name: "--oc-eyebrow-weight", light: "500" },
   { name: "--oc-eyebrow-tracking", light: "0.08em" },
@@ -1439,6 +1564,13 @@ var DEFAULT_THEME = {
     axis: "#71717a",
     annotationFill: "rgba(0,0,0,0.04)",
     annotationText: "#71717a",
+    annotationLabel: "#333333",
+    annotationMuted: "#6b7280",
+    annotationLeader: "#8f8f8f",
+    annotationRule: "#666666",
+    annotationRangeFill: "#000000",
+    annotationMarkerFill: "#ffffff",
+    annotationPlate: "#ffffff",
     positive: "#15803d",
     negative: "#dc2626"
   },
@@ -1605,6 +1737,13 @@ function adaptTheme(theme) {
       axis: darkAxis,
       annotationFill: pairs?.["colors.annotationFill"] ? pairs["colors.annotationFill"].dark : overridden(theme.colors.annotationFill, light.annotationFill, "rgba(255,255,255,0.06)"),
       annotationText: pairs?.["colors.annotationText"] ? pairs["colors.annotationText"].dark : overridden(theme.colors.annotationText, light.annotationText, darkMuted),
+      annotationLabel: pairs?.["colors.annotationLabel"]?.dark ?? overridden(theme.colors.annotationLabel, light.annotationLabel, "#d1d5db"),
+      annotationMuted: pairs?.["colors.annotationMuted"]?.dark ?? overridden(theme.colors.annotationMuted, light.annotationMuted, "#9ca3af"),
+      annotationLeader: pairs?.["colors.annotationLeader"]?.dark ?? overridden(theme.colors.annotationLeader, light.annotationLeader, "#9aa0a6"),
+      annotationRule: pairs?.["colors.annotationRule"]?.dark ?? overridden(theme.colors.annotationRule, light.annotationRule, "#666666"),
+      annotationRangeFill: pairs?.["colors.annotationRangeFill"]?.dark ?? overridden(theme.colors.annotationRangeFill, light.annotationRangeFill, "#000000"),
+      annotationMarkerFill: pairs?.["colors.annotationMarkerFill"]?.dark ?? overridden(theme.colors.annotationMarkerFill, light.annotationMarkerFill, "#0a0a0a"),
+      annotationPlate: pairs?.["colors.annotationPlate"]?.dark ?? overridden(theme.colors.annotationPlate, light.annotationPlate, "#0a0a0a"),
       categorical,
       categoricalFill,
       hairline: darkHairline,
@@ -1656,6 +1795,11 @@ function adaptForLightLineStroke(color) {
   return c.formatHex();
 }
 
+// src/theme/merge.ts
+function mergeThemeConfig(base, override) {
+  return override ? { ...base, ...override } : base;
+}
+
 // src/theme/presets.ts
 var editorial = {};
 var essay = {
@@ -1771,6 +1915,23 @@ var terminal = {
   borderRadius: 4,
   seriesStrategy: "accent-neutral"
 };
+var clarity = {
+  colors: {
+    background: { light: "#ffffff", dark: "#09090b" },
+    axis: { light: "#52525b", dark: "#a1a1aa" }
+  },
+  fonts: { sizes: { title: 26, subtitle: 14, body: 13, small: 12, axisTick: 12 } },
+  chrome: {
+    eyebrow: { color: { light: "#0f766e", dark: "#5eead4" } },
+    source: { fontSize: 12 },
+    footer: { fontSize: 12 }
+  },
+  spacing: { chromeToChart: 16, chartToFooter: 12 }
+};
+var legacyEditorial = {
+  fonts: { sizes: { title: 26, subtitle: 14, body: 13, small: 11, axisTick: 11 } },
+  spacing: { padding: 20, chromeGap: 6, chromeToChart: 8, chartToFooter: 8 }
+};
 
 // src/theme/resolve.ts
 function deepMerge(target, source) {
@@ -1809,6 +1970,20 @@ function themeConfigToPartial(config) {
         colors.annotationFill = resolveTokenLight(config.colors.annotationFill);
       if (config.colors.annotationText)
         colors.annotationText = resolveTokenLight(config.colors.annotationText);
+      if (config.colors.annotationLabel)
+        colors.annotationLabel = resolveTokenLight(config.colors.annotationLabel);
+      if (config.colors.annotationMuted)
+        colors.annotationMuted = resolveTokenLight(config.colors.annotationMuted);
+      if (config.colors.annotationLeader)
+        colors.annotationLeader = resolveTokenLight(config.colors.annotationLeader);
+      if (config.colors.annotationRule)
+        colors.annotationRule = resolveTokenLight(config.colors.annotationRule);
+      if (config.colors.annotationRangeFill)
+        colors.annotationRangeFill = resolveTokenLight(config.colors.annotationRangeFill);
+      if (config.colors.annotationMarkerFill)
+        colors.annotationMarkerFill = resolveTokenLight(config.colors.annotationMarkerFill);
+      if (config.colors.annotationPlate)
+        colors.annotationPlate = resolveTokenLight(config.colors.annotationPlate);
       if (config.colors.positive) colors.positive = resolveTokenLight(config.colors.positive);
       if (config.colors.negative) colors.negative = resolveTokenLight(config.colors.negative);
     }
@@ -1883,6 +2058,13 @@ function collectTokenPairs(config) {
       "axis",
       "annotationFill",
       "annotationText",
+      "annotationLabel",
+      "annotationMuted",
+      "annotationLeader",
+      "annotationRule",
+      "annotationRangeFill",
+      "annotationMarkerFill",
+      "annotationPlate",
       "positive",
       "negative"
     ];
@@ -1983,6 +2165,22 @@ function resolveTheme(userTheme, base = DEFAULT_THEME) {
   const dark = isDarkBackground(merged.colors.background);
   if (dark) {
     merged = adaptChromeForDarkBg(merged, merged.colors.text);
+    const authoredColors = userTheme?.colors && !Array.isArray(userTheme.colors) ? userTheme.colors : {};
+    for (const key of [
+      "annotationLabel",
+      "annotationMuted",
+      "annotationLeader",
+      "annotationRule",
+      "annotationRangeFill",
+      "annotationMarkerFill",
+      "annotationPlate"
+    ]) {
+      if (authoredColors[key] === void 0)
+        merged.colors[key] = cssTokenDefault(
+          `--oc-${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`,
+          "dark"
+        );
+    }
   }
   return {
     ...merged,
@@ -2067,9 +2265,20 @@ function estimateLineCount(text, style, maxWidth, measureText, maxLines) {
 }
 var FOOTNOTE_LINE_HEIGHT = 1.3;
 var FOOTNOTE_BAND_GAP = 4;
-function footnoteBandHeight(count, theme) {
-  if (count <= 0) return 0;
-  return count * theme.fonts.sizes.small * FOOTNOTE_LINE_HEIGHT + FOOTNOTE_BAND_GAP;
+function computeNoteBandHeight(input, theme) {
+  if (typeof input !== "number" && input.noteBandHeight !== void 0) return input.noteBandHeight;
+  const count = typeof input === "number" ? input : (input.footnotes?.reduce((sum, note) => sum + (note.lines?.length ?? 1), 0) ?? 0) + (input.seriesSummary?.reduce((sum, entry) => sum + entry.lines.length, 0) ?? 0);
+  return count <= 0 ? 0 : count * theme.fonts.sizes.small * FOOTNOTE_LINE_HEIGHT + FOOTNOTE_BAND_GAP;
+}
+var warnedFootnoteBandHeight = false;
+function footnoteBandHeight(input, theme) {
+  if (!warnedFootnoteBandHeight) {
+    warnedFootnoteBandHeight = true;
+    console.warn(
+      "[openchart] footnoteBandHeight is deprecated; read layout.chrome.noteBandHeight."
+    );
+  }
+  return computeNoteBandHeight(input, theme);
 }
 function computeChrome(chrome, theme, width, measureText, chromeMode = "full", padding, watermark = true, bottomLegendHeight = 0, crampedTitle = false) {
   if (!chrome || chromeMode === "hidden") {
@@ -2583,6 +2792,10 @@ function buildD3Formatter(formatStr) {
 }
 function formatPercent(value, options) {
   const fraction = options?.fraction ?? true;
+  const percent = fraction ? value * 100 : value;
+  if (Number.isFinite(percent) && percent !== 0 && Math.abs(percent) < 0.1) {
+    return percent < 0 ? `>${FORMAT_PERCENT_RAW(-0.1)}%` : `<${FORMAT_PERCENT_RAW(0.1)}%`;
+  }
   if (fraction) {
     return FORMAT_PERCENT_FRACTION(value);
   }
@@ -2918,6 +3131,19 @@ function formatValue(value) {
 }
 
 // src/helpers/spec-builders.ts
+var warnedBuilderOptions = /* @__PURE__ */ new Set();
+function warnBuilderOption(key, message) {
+  if (warnedBuilderOptions.has(key)) return;
+  warnedBuilderOptions.add(key);
+  console.warn(`[openchart] ${message}`);
+}
+function warnDarkMode(options) {
+  if (options?.darkMode !== void 0)
+    warnBuilderOption(
+      "darkMode",
+      "Builder darkMode is deprecated and has no effect; use the mount option."
+    );
+}
 var ISO_DATE_RE = /^\d{4}(-\d{2}(-\d{2}(T\d{2}(:\d{2}(:\d{2})?)?)?)?)?$/;
 function inferFieldType(data, field) {
   const sampleSize = Math.min(data.length, 20);
@@ -2962,12 +3188,12 @@ function buildEncoding(channels, options, data) {
   return encoding;
 }
 function buildChartSpec(mark, data, encoding, options) {
+  warnDarkMode(options);
   const spec = { mark, data, encoding };
   if (options?.chrome) spec.chrome = options.chrome;
   if (options?.annotations) spec.annotations = options.annotations;
   if (options?.responsive !== void 0) spec.responsive = options.responsive;
   if (options?.theme) spec.theme = options.theme;
-  if (options?.darkMode) spec.darkMode = options.darkMode;
   return spec;
 }
 function lineChart(data, x, y, options) {
@@ -3031,6 +3257,9 @@ function scatterChart(data, x, y, options) {
   return buildChartSpec("point", data, encoding, options);
 }
 function dataTable(data, options) {
+  warnDarkMode(options);
+  if (options?.compact !== void 0)
+    warnBuilderOption("compact", "dataTable compact is deprecated; use density.");
   let columns = options?.columns;
   if (!columns && data.length > 0) {
     columns = Object.keys(data[0]).map((key) => {
@@ -3051,15 +3280,16 @@ function dataTable(data, options) {
   if (options?.rowKey) spec.rowKey = options.rowKey;
   if (options?.chrome) spec.chrome = options.chrome;
   if (options?.theme) spec.theme = options.theme;
-  if (options?.darkMode) spec.darkMode = options.darkMode;
   if (options?.search !== void 0) spec.search = options.search;
   if (options?.pagination !== void 0) spec.pagination = options.pagination;
   if (options?.stickyFirstColumn !== void 0) spec.stickyFirstColumn = options.stickyFirstColumn;
-  if (options?.compact !== void 0) spec.compact = options.compact;
+  if (options?.density !== void 0) spec.density = options.density;
+  else if (options?.compact !== void 0) spec.density = options.compact ? "condensed" : "regular";
   if (options?.responsive !== void 0) spec.responsive = options.responsive;
   return spec;
 }
 function tileMap(data, options) {
+  warnDarkMode(options);
   return {
     type: "tilemap",
     data,
@@ -3069,7 +3299,6 @@ function tileMap(data, options) {
     ...options?.chrome && { chrome: options.chrome },
     ...options?.legend && { legend: options.legend },
     ...options?.theme && { theme: options.theme },
-    ...options?.darkMode && { darkMode: options.darkMode },
     ...options?.watermark !== void 0 && { watermark: options.watermark },
     ...options?.animation && { animation: options.animation },
     ...options?.valueFormat && { valueFormat: options.valueFormat }
@@ -3089,6 +3318,104 @@ function deepMergeSpec(target, source) {
   }
   return result;
 }
+
+// src/helpers/annotation-source.ts
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+function annotationSource(spec) {
+  const root = object(spec);
+  if (Array.isArray(root?.annotations))
+    return { annotations: root.annotations, path: "/annotations" };
+  function firstLeaf(node, path) {
+    if (Array.isArray(node?.layer)) {
+      for (const [index, child] of node.layer.entries()) {
+        const result = firstLeaf(object(child), `${path}/layer/${index}`);
+        if (result) return result;
+      }
+    } else if (node && "mark" in node) {
+      return {
+        annotations: Array.isArray(node.annotations) ? node.annotations : [],
+        path: `${path}/annotations`
+      };
+    }
+  }
+  return firstLeaf(root, "") ?? { annotations: [], path: "/annotations" };
+}
+
+// src/motion/sample.ts
+var MOTION_REST_THRESHOLD = 1e-3;
+var MAX_SPRING_DURATION = 1200;
+var FLUID_SPRING = {
+  stiffness: 320,
+  damping: 36,
+  mass: 1
+};
+function springState(timeMs, config) {
+  const stiffness = config.stiffness ?? FLUID_SPRING.stiffness;
+  const mass = config.mass ?? FLUID_SPRING.mass;
+  const rootStiffness = Math.sqrt(stiffness);
+  const rootMass = Math.sqrt(mass);
+  const omega = rootStiffness / rootMass;
+  const damping = config.damping ?? FLUID_SPRING.damping;
+  const zeta = Math.max(1, damping / rootStiffness / rootMass / 2);
+  const t = Math.max(0, timeMs) / 1e3;
+  let remaining;
+  let velocity;
+  if (zeta - 1 < 1e-4) {
+    const scaledTime = omega * t;
+    const decay = Math.exp(-scaledTime);
+    remaining = decay === 0 ? 0 : (1 + scaledTime) * decay;
+    velocity = decay === 0 ? 0 : omega * (scaledTime * decay);
+  } else {
+    const inverseZeta = 1 / zeta;
+    const q = damping / 2 * (1 + Math.sqrt(1 - inverseZeta * inverseZeta));
+    const slow = -stiffness / q;
+    const fast = -q / mass;
+    const ratio = slow / fast;
+    const slowDecay = Math.exp(slow * t);
+    const fastDecay = Math.exp(fast * t);
+    if (slowDecay === 0) {
+      remaining = 0;
+      velocity = 0;
+    } else {
+      remaining = (slowDecay - ratio * fastDecay) / (1 - ratio);
+      velocity = -slow * ((slowDecay - fastDecay) / (1 - ratio));
+    }
+  }
+  return {
+    position: Math.min(1, Math.max(0, 1 - remaining)),
+    velocity,
+    settled: remaining <= MOTION_REST_THRESHOLD && Math.abs(velocity) <= MOTION_REST_THRESHOLD
+  };
+}
+function springDuration(config) {
+  for (const name of ["stiffness", "damping", "mass"]) {
+    const value = config[name];
+    if (value === void 0) continue;
+    if (!Number.isFinite(value) || value <= 0)
+      throw new Error(`spring.${name} must be finite and positive`);
+  }
+  for (let ms = 1; ms < MAX_SPRING_DURATION; ms++) {
+    if (springState(ms, config).settled) return ms;
+  }
+  return MAX_SPRING_DURATION;
+}
+function sampleMotion(phase, elapsedMs) {
+  if (phase.duration <= 0 || elapsedMs >= phase.duration) {
+    return { position: 1, velocity: 0, settled: true };
+  }
+  if (elapsedMs <= 0) return { position: 0, velocity: 0, settled: false };
+  if (phase.spring) return springState(elapsedMs, phase.spring);
+  const t = elapsedMs / phase.duration;
+  const power = phase.ease === "snappy" ? 5 : 3;
+  return {
+    position: 1 - (1 - t) ** power,
+    velocity: power * (1 - t) ** (power - 1) * 1e3 / phase.duration,
+    settled: false
+  };
+}
+function motionCSS(phase) {
+  return `linear(${Array.from({ length: 101 }, (_, i) => sampleMotion(phase, i * phase.duration / 100).position.toFixed(6)).join(",")})`;
+}
 export {
   ACHROMATIC_RAMP,
   AXIS_TITLE_GAP,
@@ -3112,6 +3439,7 @@ export {
   DEFAULT_THEME,
   DIVERGING_PALETTES,
   EXTENDED_OFFSET_STRATEGIES,
+  FLUID_SPRING,
   FOOTNOTE_LINE_HEIGHT,
   GRAPH_ENCODING_RULES,
   HEIGHT_CRAMPED_MAX,
@@ -3130,7 +3458,9 @@ export {
   MAX_LEFT_LABEL_FRACTION_DEFAULT,
   MAX_LEFT_LABEL_FRACTION_MEDIUM,
   MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  MAX_SPRING_DURATION,
   MAX_SR_TABLE_ROWS,
+  MOTION_REST_THRESHOLD,
   NARROW_VIEWPORT_MAX,
   OFFSET_STRATEGIES,
   SEQUENTIAL_PALETTES,
@@ -3147,6 +3477,8 @@ export {
   adaptColorForDarkMode,
   adaptForLightLineStroke,
   adaptTheme,
+  annotationSource,
+  applyEditTransaction,
   areaChart,
   axisTitleOffset,
   barChart,
@@ -3155,10 +3487,12 @@ export {
   buildD3Formatter,
   buildTemporalFormatter,
   checkPaletteDistinguishability,
+  clarity,
   columnChart,
   computeChrome,
   computeFieldFormatContext,
   computeLabelBounds,
+  computeNoteBandHeight,
   computeXAxisExtentFromLabels,
   contrastRatio,
   cssTokenDefault,
@@ -3208,9 +3542,12 @@ export {
   isTileMapSpec,
   isValueDef,
   isYearContext,
+  legacyEditorial,
   lineChart,
   maxRotatedLabelWidth,
   meetsAA,
+  mergeThemeConfig,
+  motionCSS,
   overlapArea,
   pickLabelColor,
   pieChart,
@@ -3222,8 +3559,10 @@ export {
   resolveNumberFormatter,
   resolveSchemeName,
   resolveTheme,
+  sampleMotion,
   scatterChart,
   simulateColorBlindness,
+  springDuration,
   terminal,
   textAscent,
   tileMap,