graphein 0.19.0 → 0.20.0

package/dist/analyze/insights.js

@@ -0,0 +1,293 @@
+import { CHART_DEFINITIONS, chartTypesWhere } from "../spec/chartDefinitions.js";
+import { accessor, toNumber, toKey, inferType } from "../util/data.js";
+import { prettyDate } from "../format/index.js";
+import { aggregateValues } from "../pivot/index.js";
+import { pearsonCorrelation, tukeyFences } from "../util/math.js";
+const FLAT_EPSILON = 1e-9;
+function num(v) {
+  const n = toNumber(v);
+  return Number.isFinite(n) ? n : null;
+}
+function computeSeriesInsights(values, labels, key = "", raws) {
+  const pts = [];
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    if (Number.isFinite(v)) pts.push({ label: labels[i] ?? String(i), value: v, index: i, raw: raws?.[i] });
+  }
+  if (pts.length === 0) return null;
+  let min = pts[0];
+  let max = pts[0];
+  let sum = 0;
+  for (const p of pts) {
+    if (p.value < min.value) min = p;
+    if (p.value > max.value) max = p;
+    sum += p.value;
+  }
+  const first = pts[0];
+  const last = pts[pts.length - 1];
+  const mean = sum / pts.length;
+  const netChange = last.value - first.value;
+  const pctChange = first.value !== 0 ? netChange / Math.abs(first.value) : null;
+  const range = max.value - min.value;
+  const flatBand = Math.max(Math.abs(range) * 1e-6, FLAT_EPSILON);
+  const direction = netChange > flatBand ? "up" : netChange < -flatBand ? "down" : "flat";
+  let biggestJump = null;
+  for (let i = 1; i < pts.length; i++) {
+    const delta = pts[i].value - pts[i - 1].value;
+    if (biggestJump === null || Math.abs(delta) > Math.abs(biggestJump.delta)) {
+      biggestJump = { from: pts[i - 1], to: pts[i], delta };
+    }
+  }
+  let outliers = [];
+  const fences = tukeyFences(pts.map((p) => p.value));
+  if (fences) outliers = pts.filter((p) => p.value < fences.lo || p.value > fences.hi);
+  return { key, count: pts.length, first, last, min, max, mean, sum, netChange, pctChange, direction, biggestJump, outliers };
+}
+function fieldTitle(f) {
+  if (!f) return void 0;
+  return f.title ?? f.field;
+}
+function resolveValueRef(ref, data) {
+  if (ref == null) return null;
+  if (typeof ref === "number") return Number.isFinite(ref) ? ref : null;
+  return aggregateValues(data.map(accessor(ref.field)), ref.aggregate ?? "sum");
+}
+const SERIES_TYPES = chartTypesWhere((definition) => definition.insightFamily === "series");
+const CATEGORY_TYPES = chartTypesWhere((definition) => definition.insightFamily === "category");
+const VALUE_TYPES = chartTypesWhere((definition) => definition.insightFamily === "value");
+function rowsOf(spec) {
+  return Array.isArray(spec.data) ? spec.data : [];
+}
+function encodingOf(spec) {
+  return spec.encoding;
+}
+function analyzeValueSpec(spec, rows, base) {
+  const s = spec;
+  const value = resolveValueRef(s.value, rows);
+  if (value === null) return null;
+  const target = resolveValueRef(s.target, rows);
+  const toTarget = target === null ? null : value - target;
+  const pctOfTarget = target ? value / target : null;
+  return {
+    ...base,
+    family: "value",
+    measureFormat: s.format,
+    measureLabel: s.label,
+    value: { value, target, toTarget, pctOfTarget }
+  };
+}
+function analyzeHistogramSpec(rows, enc, base) {
+  const xf = enc?.x;
+  if (!xf) return null;
+  const values = [];
+  const read = accessor(xf.field);
+  for (const d of rows) {
+    const v = num(read(d));
+    if (v !== null) values.push(v);
+  }
+  const dist = computeSeriesInsights(values, values.map(String), xf.field);
+  if (!dist) return null;
+  return {
+    ...base,
+    family: "distribution",
+    measureField: xf.field,
+    measureFormat: xf.format,
+    measureLabel: fieldTitle(xf),
+    distribution: dist
+  };
+}
+function analyzeScatterSpec(rows, enc, base) {
+  const xf = enc?.x;
+  const yf = enc?.y;
+  if (!xf || !yf) return null;
+  const readX = accessor(xf.field);
+  const readY = accessor(yf.field);
+  const xs = [];
+  const ys = [];
+  for (const d of rows) {
+    const x = num(readX(d));
+    const y = num(readY(d));
+    if (x !== null && y !== null) {
+      xs.push(x);
+      ys.push(y);
+    }
+  }
+  if (xs.length === 0) return null;
+  const xExtent = [Math.min(...xs), Math.max(...xs)];
+  const yExtent = [Math.min(...ys), Math.max(...ys)];
+  return {
+    ...base,
+    family: "scatter",
+    measureField: yf.field,
+    measureFormat: yf.format,
+    measureLabel: fieldTitle(yf),
+    categoryField: xf.field,
+    scatter: { count: xs.length, xExtent, yExtent, correlation: pearsonCorrelation(xs, ys) }
+  };
+}
+function analyzeCategory(rows, categoryField, measureField, aggregate = true) {
+  const readCat = accessor(categoryField);
+  const readVal = accessor(measureField);
+  if (!aggregate) {
+    const points = [];
+    const counts = /* @__PURE__ */ new Map();
+    const duplicates = [];
+    for (const d of rows) {
+      const v = num(readVal(d));
+      if (v === null) continue;
+      const raw = readCat(d);
+      const label = toKey(raw);
+      const seen = counts.get(label) ?? 0;
+      if (seen === 1) duplicates.push(label);
+      counts.set(label, seen + 1);
+      points.push({ label, value: v, index: points.length, raw });
+    }
+    if (points.length === 0) return null;
+    let top2 = points[0];
+    let bottom2 = points[0];
+    let total2 = 0;
+    for (const point of points) {
+      total2 += point.value;
+      if (point.value > top2.value) top2 = point;
+      if (point.value < bottom2.value) bottom2 = point;
+    }
+    return {
+      count: points.length,
+      total: total2,
+      top: top2,
+      bottom: bottom2,
+      topShare: total2 > 0 ? top2.value / total2 : 0,
+      ...duplicates.length ? { duplicateCategories: duplicates } : {}
+    };
+  }
+  const totals = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const d of rows) {
+    const v = num(readVal(d));
+    if (v === null) continue;
+    const k = toKey(readCat(d));
+    if (!totals.has(k)) order.push(k);
+    totals.set(k, (totals.get(k) ?? 0) + v);
+  }
+  if (order.length === 0) return null;
+  let total = 0;
+  let top = { label: order[0], value: totals.get(order[0]) ?? 0, index: 0, raw: order[0] };
+  let bottom = { ...top };
+  order.forEach((k, i) => {
+    const value = totals.get(k) ?? 0;
+    total += value;
+    if (value > top.value) top = { label: k, value, index: i, raw: k };
+    if (value < bottom.value) bottom = { label: k, value, index: i, raw: k };
+  });
+  return { count: order.length, total, top, bottom, topShare: total > 0 ? top.value / total : 0 };
+}
+function xLabel(x) {
+  return x instanceof Date ? prettyDate(x) : toKey(x);
+}
+function analyzeSeriesFamily(rows, xField, yField, seriesField) {
+  const readX = accessor(xField);
+  const readY = accessor(yField);
+  const readS = seriesField ? accessor(seriesField) : null;
+  const groups = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const d of rows) {
+    const y = num(readY(d));
+    if (y === null) continue;
+    const key = readS ? toKey(readS(d)) : "";
+    let g = groups.get(key);
+    if (!g) {
+      g = { values: [], labels: [], raws: [] };
+      groups.set(key, g);
+      order.push(key);
+    }
+    const x = readX(d);
+    g.values.push(y);
+    g.labels.push(xLabel(x));
+    g.raws.push(x);
+  }
+  const out = [];
+  for (const key of order) {
+    const g = groups.get(key);
+    const si = computeSeriesInsights(g.values, g.labels, key, g.raws);
+    if (si) out.push(si);
+  }
+  return out;
+}
+function analyzeCategorySpec(spec, rows, enc, base) {
+  const categoryDefinition = CHART_DEFINITIONS[spec.type].categoryInsight;
+  const barIsCategory = spec.type === "bar" && !enc?.series;
+  const cfg = categoryDefinition ? {
+    cat: enc?.[categoryDefinition.category],
+    measure: enc?.[categoryDefinition.measure]
+  } : { cat: enc?.x, measure: enc?.y };
+  if (!cfg.cat || !cfg.measure) return null;
+  const category = analyzeCategory(rows, cfg.cat.field, cfg.measure.field, !barIsCategory);
+  if (!category) return null;
+  return {
+    ...base,
+    family: "category",
+    categoryField: cfg.cat.field,
+    categoryType: inferType(rows, cfg.cat.field),
+    measureField: cfg.measure.field,
+    measureFormat: cfg.measure.format,
+    measureLabel: fieldTitle(cfg.measure),
+    category
+  };
+}
+function analyzeSeriesSpec(spec, rows, enc, base) {
+  const xf = spec.type === "waterfall" ? enc?.stage : enc?.x;
+  const yf = spec.type === "waterfall" ? enc?.value : enc?.y;
+  if (!xf || !yf) return null;
+  const series = analyzeSeriesFamily(rows, xf.field, yf.field, enc?.series?.field);
+  if (series.length === 0) return null;
+  const result = {
+    ...base,
+    family: "series",
+    categoryField: xf.field,
+    categoryType: inferType(rows, xf.field),
+    measureField: yf.field,
+    measureFormat: yf.format,
+    measureLabel: fieldTitle(yf),
+    series
+  };
+  if (series.length > 1) {
+    let leader = series[0];
+    let mover = series[0];
+    for (const s of series) {
+      if (s.last.value > leader.last.value) leader = s;
+      if (Math.abs(s.netChange) > Math.abs(mover.netChange)) mover = s;
+    }
+    result.leader = { key: leader.key, value: leader.last.value };
+    result.biggestMover = { key: mover.key, delta: mover.netChange };
+  }
+  return result;
+}
+function analyzeChart(spec) {
+  const rows = rowsOf(spec);
+  const type = spec.type;
+  const base = { type, rowCount: rows.length };
+  if (rows.length === 0 && !VALUE_TYPES.has(type)) return null;
+  if (VALUE_TYPES.has(type)) {
+    return analyzeValueSpec(spec, rows, base);
+  }
+  const enc = encodingOf(spec);
+  if (type === "histogram") {
+    return analyzeHistogramSpec(rows, enc, base);
+  }
+  if (type === "scatter") {
+    return analyzeScatterSpec(rows, enc, base);
+  }
+  const barIsCategory = type === "bar" && !enc?.series;
+  if (CATEGORY_TYPES.has(type) || barIsCategory) {
+    return analyzeCategorySpec(spec, rows, enc, base);
+  }
+  if (SERIES_TYPES.has(type) || type === "bar") {
+    return analyzeSeriesSpec(spec, rows, enc, base);
+  }
+  return null;
+}
+export {
+  analyzeChart,
+  computeSeriesInsights
+};
+//# sourceMappingURL=insights.js.map

package/dist/analyze/insights.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/analyze/insights.ts"],
+  "sourcesContent": ["/**\n * Data insight analysis \u2014 the pure analytical core behind self-explaining charts.\n *\n * Given a {@link ChartSpec} (spec + its `data`), {@link analyzeChart} derives a\n * structured, dependency-free set of facts about what the numbers *say*: the\n * trend and net change of a series, the largest/smallest category and its share,\n * outliers, scatter correlation, a value vs. its target. Two consumers build on\n * it without re-deriving anything:\n *   - {@link summarize} turns insights into a deterministic plain-English summary\n *     (doubles as alt-text \u2014 no LLM).\n *   - auto-insight annotations turn the same `PointRef`s into on-chart callouts.\n *\n * The analysis is a pure function of the spec; it reads rows as-is (charts plot\n * rows in data order, so first/last reflect data order) and never mutates input.\n */\n\nimport type { ChartSpec, ChartType, Encoding, FieldDef, ValueRef } from '../spec/types';\nimport { CHART_DEFINITIONS, chartTypesWhere } from '../spec/chartDefinitions';\nimport type { Datum, FieldType } from '../types';\nimport { accessor, toNumber, toKey, inferType } from '../util/data';\nimport { prettyDate } from '../format';\nimport { aggregateValues } from '../pivot';\nimport { pearsonCorrelation, tukeyFences } from '../util/math';\n\n/** A single salient point in a series: its value, its x-label, and row index. */\nexport interface PointRef {\n  /** The x-axis label for this point (formatted as a string). */\n  label: string;\n  /** The numeric value at this point. */\n  value: number;\n  /** Index of the originating row within its series. */\n  index: number;\n  /**\n   * The raw x-axis domain value (a `Date`, string, or number) for this point,\n   * suitable for mapping back to a pixel via a chart's x-scale. Undefined when\n   * the analysis had no x channel (e.g. a raw distribution).\n   */\n  raw?: unknown;\n}\n\n/** Trend + spread facts for one ordered numeric series. */\nexport interface SeriesInsights {\n  /** Series name (`''` for a single, unsplit series). */\n  key: string;\n  /** Number of points. */\n  count: number;\n  first: PointRef;\n  last: PointRef;\n  min: PointRef;\n  max: PointRef;\n  /** Arithmetic mean of the values. */\n  mean: number;\n  /** Sum of the values. */\n  sum: number;\n  /** `last - first`. */\n  netChange: number;\n  /** `(last - first) / |first|`, or `null` when `first` is 0. */\n  pctChange: number | null;\n  /** Overall direction of travel from first to last. */\n  direction: 'up' | 'down' | 'flat';\n  /** The largest single step between consecutive points (by absolute delta). */\n  biggestJump: { from: PointRef; to: PointRef; delta: number } | null;\n  /** Points beyond the 1.5\u00D7IQR Tukey fences (empty when none). */\n  outliers: PointRef[];\n}\n\n/** Part-to-whole facts for a categorical measure. */\nexport interface CategoryInsights {\n  /** Number of categories. */\n  count: number;\n  /** Sum of the measure across all categories. */\n  total: number;\n  /** The largest category. */\n  top: PointRef;\n  /** The smallest category. */\n  bottom: PointRef;\n  /** `top.value / total` (0..1), or 0 when the total is not positive. */\n  topShare: number;\n  /** Repeated category labels in row-preserving charts. */\n  duplicateCategories?: string[];\n}\n\n/** Relationship facts for an x/y point cloud. */\nexport interface ScatterInsights {\n  count: number;\n  xExtent: [number, number];\n  yExtent: [number, number];\n  /** Pearson correlation coefficient (\u22121..1), or `null` when undefined. */\n  correlation: number | null;\n}\n\n/** A single value measured against an optional target. */\nexport interface ValueInsights {\n  value: number;\n  target: number | null;\n  /** `value - target`, or `null` when there is no target. */\n  toTarget: number | null;\n  /** `value / target`, or `null` when there is no (non-zero) target. */\n  pctOfTarget: number | null;\n}\n\nexport type InsightFamily = 'series' | 'category' | 'scatter' | 'value' | 'distribution';\n\n/** The structured insight payload for a chart (see {@link analyzeChart}). */\nexport interface ChartInsights {\n  type: ChartType;\n  family: InsightFamily;\n  /** Rows backing the chart. */\n  rowCount: number;\n  /** The measure field name (y / value / theta), when there is one. */\n  measureField?: string;\n  /** The measure's number-format hint (for downstream formatting). */\n  measureFormat?: string;\n  /** Display title for the measure (field title or field name). */\n  measureLabel?: string;\n  /** The category / x field name, when there is one. */\n  categoryField?: string;\n  /** Inferred type of the x / category field. */\n  categoryType?: FieldType;\n  /** Per-series trend facts (family `series`). */\n  series?: SeriesInsights[];\n  /** Highest-ending series (multi-series only). */\n  leader?: { key: string; value: number };\n  /** The series that moved most from first\u2192last (multi-series only). */\n  biggestMover?: { key: string; delta: number };\n  /** Part-to-whole facts (family `category`). */\n  category?: CategoryInsights;\n  /** Point-cloud facts (family `scatter`). */\n  scatter?: ScatterInsights;\n  /** Single value vs. target (family `value`). */\n  value?: ValueInsights;\n  /** Distribution of one measure (family `distribution`, e.g. histogram). */\n  distribution?: SeriesInsights;\n}\n\nconst FLAT_EPSILON = 1e-9;\n\nfunction num(v: unknown): number | null {\n  const n = toNumber(v);\n  return Number.isFinite(n) ? n : null;\n}\n\n/**\n * Compute trend + spread insights for a parallel `values`/`labels` series.\n * Returns `null` when there are no finite values.\n */\nexport function computeSeriesInsights(\n  values: readonly number[],\n  labels: readonly string[],\n  key = '',\n  raws?: readonly unknown[],\n): SeriesInsights | null {\n  const pts: PointRef[] = [];\n  for (let i = 0; i < values.length; i++) {\n    const v = values[i];\n    if (Number.isFinite(v)) pts.push({ label: labels[i] ?? String(i), value: v, index: i, raw: raws?.[i] });\n  }\n  if (pts.length === 0) return null;\n\n  let min = pts[0];\n  let max = pts[0];\n  let sum = 0;\n  for (const p of pts) {\n    if (p.value < min.value) min = p;\n    if (p.value > max.value) max = p;\n    sum += p.value;\n  }\n  const first = pts[0];\n  const last = pts[pts.length - 1];\n  const mean = sum / pts.length;\n  const netChange = last.value - first.value;\n  const pctChange = first.value !== 0 ? netChange / Math.abs(first.value) : null;\n\n  const range = max.value - min.value;\n  const flatBand = Math.max(Math.abs(range) * 1e-6, FLAT_EPSILON);\n  const direction: SeriesInsights['direction'] =\n    netChange > flatBand ? 'up' : netChange < -flatBand ? 'down' : 'flat';\n\n  let biggestJump: SeriesInsights['biggestJump'] = null;\n  for (let i = 1; i < pts.length; i++) {\n    const delta = pts[i].value - pts[i - 1].value;\n    if (biggestJump === null || Math.abs(delta) > Math.abs(biggestJump.delta)) {\n      biggestJump = { from: pts[i - 1], to: pts[i], delta };\n    }\n  }\n\n  let outliers: PointRef[] = [];\n  const fences = tukeyFences(pts.map((p) => p.value));\n  if (fences) outliers = pts.filter((p) => p.value < fences.lo || p.value > fences.hi);\n\n  return { key, count: pts.length, first, last, min, max, mean, sum, netChange, pctChange, direction, biggestJump, outliers };\n}\n\nfunction fieldTitle(f: FieldDef | undefined): string | undefined {\n  if (!f) return undefined;\n  return f.title ?? f.field;\n}\n\n/** Resolve a literal-or-aggregated ValueRef over the data (kpi/gauge/bullet). */\nfunction resolveValueRef(ref: ValueRef | undefined, data: readonly Datum[]): number | null {\n  if (ref == null) return null;\n  if (typeof ref === 'number') return Number.isFinite(ref) ? ref : null;\n  return aggregateValues(data.map(accessor(ref.field)), ref.aggregate ?? 'sum');\n}\n\nconst SERIES_TYPES = chartTypesWhere((definition) => definition.insightFamily === 'series');\nconst CATEGORY_TYPES = chartTypesWhere((definition) => definition.insightFamily === 'category');\nconst VALUE_TYPES = chartTypesWhere((definition) => definition.insightFamily === 'value');\n\n/** Read the rows of a spec as a typed array (empty when absent). */\nfunction rowsOf(spec: ChartSpec): Datum[] {\n  return Array.isArray(spec.data) ? (spec.data as Datum[]) : [];\n}\n\nfunction encodingOf(spec: ChartSpec): Encoding | undefined {\n  return (spec as { encoding?: Encoding }).encoding;\n}\n\nfunction analyzeValueSpec(\n  spec: ChartSpec,\n  rows: readonly Datum[],\n  base: Pick<ChartInsights, 'type' | 'rowCount'>,\n): ChartInsights | null {\n  const s = spec as { value: ValueRef; target?: ValueRef; format?: string; label?: string };\n  const value = resolveValueRef(s.value, rows);\n  if (value === null) return null;\n  const target = resolveValueRef(s.target, rows);\n  const toTarget = target === null ? null : value - target;\n  const pctOfTarget = target ? value / target : null;\n  return {\n    ...base,\n    family: 'value',\n    measureFormat: s.format,\n    measureLabel: s.label,\n    value: { value, target, toTarget, pctOfTarget },\n  };\n}\n\nfunction analyzeHistogramSpec(\n  rows: readonly Datum[],\n  enc: Encoding | undefined,\n  base: Pick<ChartInsights, 'type' | 'rowCount'>,\n): ChartInsights | null {\n  const xf = enc?.x;\n  if (!xf) return null;\n  const values: number[] = [];\n  const read = accessor(xf.field);\n  for (const d of rows) {\n    const v = num(read(d));\n    if (v !== null) values.push(v);\n  }\n  const dist = computeSeriesInsights(values, values.map(String), xf.field);\n  if (!dist) return null;\n  return {\n    ...base,\n    family: 'distribution',\n    measureField: xf.field,\n    measureFormat: xf.format,\n    measureLabel: fieldTitle(xf),\n    distribution: dist,\n  };\n}\n\nfunction analyzeScatterSpec(\n  rows: readonly Datum[],\n  enc: Encoding | undefined,\n  base: Pick<ChartInsights, 'type' | 'rowCount'>,\n): ChartInsights | null {\n  const xf = enc?.x;\n  const yf = enc?.y;\n  if (!xf || !yf) return null;\n  const readX = accessor(xf.field);\n  const readY = accessor(yf.field);\n  const xs: number[] = [];\n  const ys: number[] = [];\n  for (const d of rows) {\n    const x = num(readX(d));\n    const y = num(readY(d));\n    if (x !== null && y !== null) {\n      xs.push(x);\n      ys.push(y);\n    }\n  }\n  if (xs.length === 0) return null;\n  const xExtent: [number, number] = [Math.min(...xs), Math.max(...xs)];\n  const yExtent: [number, number] = [Math.min(...ys), Math.max(...ys)];\n  return {\n    ...base,\n    family: 'scatter',\n    measureField: yf.field,\n    measureFormat: yf.format,\n    measureLabel: fieldTitle(yf),\n    categoryField: xf.field,\n    scatter: { count: xs.length, xExtent, yExtent, correlation: pearsonCorrelation(xs, ys) },\n  };\n}\n\n/** Build a categorical (top/bottom/total) insight. Aggregating charts sum by category; bars preserve rows. */\nfunction analyzeCategory(\n  rows: readonly Datum[],\n  categoryField: string,\n  measureField: string,\n  aggregate = true,\n): CategoryInsights | null {\n  const readCat = accessor(categoryField);\n  const readVal = accessor(measureField);\n  if (!aggregate) {\n    const points: PointRef[] = [];\n    const counts = new Map<string, number>();\n    const duplicates: string[] = [];\n    for (const d of rows) {\n      const v = num(readVal(d));\n      if (v === null) continue;\n      const raw = readCat(d);\n      const label = toKey(raw);\n      const seen = counts.get(label) ?? 0;\n      if (seen === 1) duplicates.push(label);\n      counts.set(label, seen + 1);\n      points.push({ label, value: v, index: points.length, raw });\n    }\n    if (points.length === 0) return null;\n    let top = points[0];\n    let bottom = points[0];\n    let total = 0;\n    for (const point of points) {\n      total += point.value;\n      if (point.value > top.value) top = point;\n      if (point.value < bottom.value) bottom = point;\n    }\n    return {\n      count: points.length,\n      total,\n      top,\n      bottom,\n      topShare: total > 0 ? top.value / total : 0,\n      ...(duplicates.length ? { duplicateCategories: duplicates } : {}),\n    };\n  }\n\n  const totals = new Map<string, number>();\n  const order: string[] = [];\n  for (const d of rows) {\n    const v = num(readVal(d));\n    if (v === null) continue;\n    const k = toKey(readCat(d));\n    if (!totals.has(k)) order.push(k);\n    totals.set(k, (totals.get(k) ?? 0) + v);\n  }\n  if (order.length === 0) return null;\n  let total = 0;\n  let top: PointRef = { label: order[0], value: totals.get(order[0]) ?? 0, index: 0, raw: order[0] };\n  let bottom: PointRef = { ...top };\n  order.forEach((k, i) => {\n    const value = totals.get(k) ?? 0;\n    total += value;\n    if (value > top.value) top = { label: k, value, index: i, raw: k };\n    if (value < bottom.value) bottom = { label: k, value, index: i, raw: k };\n  });\n  return { count: order.length, total, top, bottom, topShare: total > 0 ? top.value / total : 0 };\n}\n\n/** A human-facing x label for a series point. `Date`s become a readable date\n *  (not the raw epoch `toKey` would yield); strings/numbers pass through `toKey`\n *  so categorical and string-temporal (`\"2024-01\"`) axes are unchanged. */\nfunction xLabel(x: unknown): string {\n  return x instanceof Date ? prettyDate(x) : toKey(x);\n}\n\n/** Group rows into ordered numeric series for the `series` families. */\nfunction analyzeSeriesFamily(\n  rows: readonly Datum[],\n  xField: string,\n  yField: string,\n  seriesField: string | undefined,\n): SeriesInsights[] {\n  const readX = accessor(xField);\n  const readY = accessor(yField);\n  const readS = seriesField ? accessor(seriesField) : null;\n  const groups = new Map<string, { values: number[]; labels: string[]; raws: unknown[] }>();\n  const order: string[] = [];\n  for (const d of rows) {\n    const y = num(readY(d));\n    if (y === null) continue;\n    const key = readS ? toKey(readS(d)) : '';\n    let g = groups.get(key);\n    if (!g) {\n      g = { values: [], labels: [], raws: [] };\n      groups.set(key, g);\n      order.push(key);\n    }\n    const x = readX(d);\n    g.values.push(y);\n    g.labels.push(xLabel(x));\n    g.raws.push(x);\n  }\n  const out: SeriesInsights[] = [];\n  for (const key of order) {\n    const g = groups.get(key)!;\n    const si = computeSeriesInsights(g.values, g.labels, key, g.raws);\n    if (si) out.push(si);\n  }\n  return out;\n}\n\nfunction analyzeCategorySpec(\n  spec: ChartSpec,\n  rows: readonly Datum[],\n  enc: Encoding | undefined,\n  base: Pick<ChartInsights, 'type' | 'rowCount'>,\n): ChartInsights | null {\n  const categoryDefinition = CHART_DEFINITIONS[spec.type].categoryInsight;\n  const barIsCategory = spec.type === 'bar' && !enc?.series;\n  const cfg = categoryDefinition\n    ? {\n        cat: (enc as Record<string, FieldDef | undefined> | undefined)?.[categoryDefinition.category],\n        measure: (enc as Record<string, FieldDef | undefined> | undefined)?.[categoryDefinition.measure],\n      }\n    : { cat: enc?.x, measure: enc?.y };\n  if (!cfg.cat || !cfg.measure) return null;\n  const category = analyzeCategory(rows, cfg.cat.field, cfg.measure.field, !barIsCategory);\n  if (!category) return null;\n  return {\n    ...base,\n    family: 'category',\n    categoryField: cfg.cat.field,\n    categoryType: inferType(rows, cfg.cat.field),\n    measureField: cfg.measure.field,\n    measureFormat: cfg.measure.format,\n    measureLabel: fieldTitle(cfg.measure),\n    category,\n  };\n}\n\nfunction analyzeSeriesSpec(\n  spec: ChartSpec,\n  rows: readonly Datum[],\n  enc: Encoding | undefined,\n  base: Pick<ChartInsights, 'type' | 'rowCount'>,\n): ChartInsights | null {\n  const xf = spec.type === 'waterfall' ? enc?.stage : enc?.x;\n  const yf = spec.type === 'waterfall' ? enc?.value : enc?.y;\n  if (!xf || !yf) return null;\n  const series = analyzeSeriesFamily(rows, xf.field, yf.field, enc?.series?.field);\n  if (series.length === 0) return null;\n  const result: ChartInsights = {\n    ...base,\n    family: 'series',\n    categoryField: xf.field,\n    categoryType: inferType(rows, xf.field),\n    measureField: yf.field,\n    measureFormat: yf.format,\n    measureLabel: fieldTitle(yf),\n    series,\n  };\n  if (series.length > 1) {\n    let leader = series[0];\n    let mover = series[0];\n    for (const s of series) {\n      if (s.last.value > leader.last.value) leader = s;\n      if (Math.abs(s.netChange) > Math.abs(mover.netChange)) mover = s;\n    }\n    result.leader = { key: leader.key, value: leader.last.value };\n    result.biggestMover = { key: mover.key, delta: mover.netChange };\n  }\n  return result;\n}\n\n/**\n * Derive structured insights from a chart spec, or `null` when the chart type\n * carries no summarizable trend (e.g. table, matrix, sankey, maps).\n */\nexport function analyzeChart(spec: ChartSpec): ChartInsights | null {\n  const rows = rowsOf(spec);\n  const type = spec.type;\n  const base: Pick<ChartInsights, 'type' | 'rowCount'> = { type, rowCount: rows.length };\n  if (rows.length === 0 && !VALUE_TYPES.has(type)) return null;\n\n  // --- value family: kpi / gauge / bullet ---\n  if (VALUE_TYPES.has(type)) {\n    return analyzeValueSpec(spec, rows, base);\n  }\n\n  const enc = encodingOf(spec);\n\n  // --- distribution: histogram (raw values binned by the chart) ---\n  if (type === 'histogram') {\n    return analyzeHistogramSpec(rows, enc, base);\n  }\n\n  // --- scatter ---\n  if (type === 'scatter') {\n    return analyzeScatterSpec(rows, enc, base);\n  }\n\n  // --- category family: pie / funnel / treemap, or bar without a series split ---\n  const barIsCategory = type === 'bar' && !enc?.series;\n  if (CATEGORY_TYPES.has(type) || barIsCategory) {\n    return analyzeCategorySpec(spec, rows, enc, base);\n  }\n\n  // --- series family: line / area / slope / waterfall, and grouped bar ---\n  if (SERIES_TYPES.has(type) || type === 'bar') {\n    return analyzeSeriesSpec(spec, rows, enc, base);\n  }\n\n  return null;\n}\n"],
+  "mappings": "AAiBA,SAAS,mBAAmB,uBAAuB;AAEnD,SAAS,UAAU,UAAU,OAAO,iBAAiB;AACrD,SAAS,kBAAkB;AAC3B,SAAS,uBAAuB;AAChC,SAAS,oBAAoB,mBAAmB;AAiHhD,MAAM,eAAe;AAErB,SAAS,IAAI,GAA2B;AACtC,QAAM,IAAI,SAAS,CAAC;AACpB,SAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAClC;AAMO,SAAS,sBACd,QACA,QACA,MAAM,IACN,MACuB;AACvB,QAAM,MAAkB,CAAC;AACzB,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAM,IAAI,OAAO,CAAC;AAClB,QAAI,OAAO,SAAS,CAAC,EAAG,KAAI,KAAK,EAAE,OAAO,OAAO,CAAC,KAAK,OAAO,CAAC,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,OAAO,CAAC,EAAE,CAAC;AAAA,EACxG;AACA,MAAI,IAAI,WAAW,EAAG,QAAO;AAE7B,MAAI,MAAM,IAAI,CAAC;AACf,MAAI,MAAM,IAAI,CAAC;AACf,MAAI,MAAM;AACV,aAAW,KAAK,KAAK;AACnB,QAAI,EAAE,QAAQ,IAAI,MAAO,OAAM;AAC/B,QAAI,EAAE,QAAQ,IAAI,MAAO,OAAM;AAC/B,WAAO,EAAE;AAAA,EACX;AACA,QAAM,QAAQ,IAAI,CAAC;AACnB,QAAM,OAAO,IAAI,IAAI,SAAS,CAAC;AAC/B,QAAM,OAAO,MAAM,IAAI;AACvB,QAAM,YAAY,KAAK,QAAQ,MAAM;AACrC,QAAM,YAAY,MAAM,UAAU,IAAI,YAAY,KAAK,IAAI,MAAM,KAAK,IAAI;AAE1E,QAAM,QAAQ,IAAI,QAAQ,IAAI;AAC9B,QAAM,WAAW,KAAK,IAAI,KAAK,IAAI,KAAK,IAAI,MAAM,YAAY;AAC9D,QAAM,YACJ,YAAY,WAAW,OAAO,YAAY,CAAC,WAAW,SAAS;AAEjE,MAAI,cAA6C;AACjD,WAAS,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;AACnC,UAAM,QAAQ,IAAI,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC,EAAE;AACxC,QAAI,gBAAgB,QAAQ,KAAK,IAAI,KAAK,IAAI,KAAK,IAAI,YAAY,KAAK,GAAG;AACzE,oBAAc,EAAE,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,MAAM;AAAA,IACtD;AAAA,EACF;AAEA,MAAI,WAAuB,CAAC;AAC5B,QAAM,SAAS,YAAY,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC;AAClD,MAAI,OAAQ,YAAW,IAAI,OAAO,CAAC,MAAM,EAAE,QAAQ,OAAO,MAAM,EAAE,QAAQ,OAAO,EAAE;AAEnF,SAAO,EAAE,KAAK,OAAO,IAAI,QAAQ,OAAO,MAAM,KAAK,KAAK,MAAM,KAAK,WAAW,WAAW,WAAW,aAAa,SAAS;AAC5H;AAEA,SAAS,WAAW,GAA6C;AAC/D,MAAI,CAAC,EAAG,QAAO;AACf,SAAO,EAAE,SAAS,EAAE;AACtB;AAGA,SAAS,gBAAgB,KAA2B,MAAuC;AACzF,MAAI,OAAO,KAAM,QAAO;AACxB,MAAI,OAAO,QAAQ,SAAU,QAAO,OAAO,SAAS,GAAG,IAAI,MAAM;AACjE,SAAO,gBAAgB,KAAK,IAAI,SAAS,IAAI,KAAK,CAAC,GAAG,IAAI,aAAa,KAAK;AAC9E;AAEA,MAAM,eAAe,gBAAgB,CAAC,eAAe,WAAW,kBAAkB,QAAQ;AAC1F,MAAM,iBAAiB,gBAAgB,CAAC,eAAe,WAAW,kBAAkB,UAAU;AAC9F,MAAM,cAAc,gBAAgB,CAAC,eAAe,WAAW,kBAAkB,OAAO;AAGxF,SAAS,OAAO,MAA0B;AACxC,SAAO,MAAM,QAAQ,KAAK,IAAI,IAAK,KAAK,OAAmB,CAAC;AAC9D;AAEA,SAAS,WAAW,MAAuC;AACzD,SAAQ,KAAiC;AAC3C;AAEA,SAAS,iBACP,MACA,MACA,MACsB;AACtB,QAAM,IAAI;AACV,QAAM,QAAQ,gBAAgB,EAAE,OAAO,IAAI;AAC3C,MAAI,UAAU,KAAM,QAAO;AAC3B,QAAM,SAAS,gBAAgB,EAAE,QAAQ,IAAI;AAC7C,QAAM,WAAW,WAAW,OAAO,OAAO,QAAQ;AAClD,QAAM,cAAc,SAAS,QAAQ,SAAS;AAC9C,SAAO;AAAA,IACL,GAAG;AAAA,IACH,QAAQ;AAAA,IACR,eAAe,EAAE;AAAA,IACjB,cAAc,EAAE;AAAA,IAChB,OAAO,EAAE,OAAO,QAAQ,UAAU,YAAY;AAAA,EAChD;AACF;AAEA,SAAS,qBACP,MACA,KACA,MACsB;AACtB,QAAM,KAAK,KAAK;AAChB,MAAI,CAAC,GAAI,QAAO;AAChB,QAAM,SAAmB,CAAC;AAC1B,QAAM,OAAO,SAAS,GAAG,KAAK;AAC9B,aAAW,KAAK,MAAM;AACpB,UAAM,IAAI,IAAI,KAAK,CAAC,CAAC;AACrB,QAAI,MAAM,KAAM,QAAO,KAAK,CAAC;AAAA,EAC/B;AACA,QAAM,OAAO,sBAAsB,QAAQ,OAAO,IAAI,MAAM,GAAG,GAAG,KAAK;AACvE,MAAI,CAAC,KAAM,QAAO;AAClB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,QAAQ;AAAA,IACR,cAAc,GAAG;AAAA,IACjB,eAAe,GAAG;AAAA,IAClB,cAAc,WAAW,EAAE;AAAA,IAC3B,cAAc;AAAA,EAChB;AACF;AAEA,SAAS,mBACP,MACA,KACA,MACsB;AACtB,QAAM,KAAK,KAAK;AAChB,QAAM,KAAK,KAAK;AAChB,MAAI,CAAC,MAAM,CAAC,GAAI,QAAO;AACvB,QAAM,QAAQ,SAAS,GAAG,KAAK;AAC/B,QAAM,QAAQ,SAAS,GAAG,KAAK;AAC/B,QAAM,KAAe,CAAC;AACtB,QAAM,KAAe,CAAC;AACtB,aAAW,KAAK,MAAM;AACpB,UAAM,IAAI,IAAI,MAAM,CAAC,CAAC;AACtB,UAAM,IAAI,IAAI,MAAM,CAAC,CAAC;AACtB,QAAI,MAAM,QAAQ,MAAM,MAAM;AAC5B,SAAG,KAAK,CAAC;AACT,SAAG,KAAK,CAAC;AAAA,IACX;AAAA,EACF;AACA,MAAI,GAAG,WAAW,EAAG,QAAO;AAC5B,QAAM,UAA4B,CAAC,KAAK,IAAI,GAAG,EAAE,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC;AACnE,QAAM,UAA4B,CAAC,KAAK,IAAI,GAAG,EAAE,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC;AACnE,SAAO;AAAA,IACL,GAAG;AAAA,IACH,QAAQ;AAAA,IACR,cAAc,GAAG;AAAA,IACjB,eAAe,GAAG;AAAA,IAClB,cAAc,WAAW,EAAE;AAAA,IAC3B,eAAe,GAAG;AAAA,IAClB,SAAS,EAAE,OAAO,GAAG,QAAQ,SAAS,SAAS,aAAa,mBAAmB,IAAI,EAAE,EAAE;AAAA,EACzF;AACF;AAGA,SAAS,gBACP,MACA,eACA,cACA,YAAY,MACa;AACzB,QAAM,UAAU,SAAS,aAAa;AACtC,QAAM,UAAU,SAAS,YAAY;AACrC,MAAI,CAAC,WAAW;AACd,UAAM,SAAqB,CAAC;AAC5B,UAAM,SAAS,oBAAI,IAAoB;AACvC,UAAM,aAAuB,CAAC;AAC9B,eAAW,KAAK,MAAM;AACpB,YAAM,IAAI,IAAI,QAAQ,CAAC,CAAC;AACxB,UAAI,MAAM,KAAM;AAChB,YAAM,MAAM,QAAQ,CAAC;AACrB,YAAM,QAAQ,MAAM,GAAG;AACvB,YAAM,OAAO,OAAO,IAAI,KAAK,KAAK;AAClC,UAAI,SAAS,EAAG,YAAW,KAAK,KAAK;AACrC,aAAO,IAAI,OAAO,OAAO,CAAC;AAC1B,aAAO,KAAK,EAAE,OAAO,OAAO,GAAG,OAAO,OAAO,QAAQ,IAAI,CAAC;AAAA,IAC5D;AACA,QAAI,OAAO,WAAW,EAAG,QAAO;AAChC,QAAIA,OAAM,OAAO,CAAC;AAClB,QAAIC,UAAS,OAAO,CAAC;AACrB,QAAIC,SAAQ;AACZ,eAAW,SAAS,QAAQ;AAC1B,MAAAA,UAAS,MAAM;AACf,UAAI,MAAM,QAAQF,KAAI,MAAO,CAAAA,OAAM;AACnC,UAAI,MAAM,QAAQC,QAAO,MAAO,CAAAA,UAAS;AAAA,IAC3C;AACA,WAAO;AAAA,MACL,OAAO,OAAO;AAAA,MACd,OAAAC;AAAA,MACA,KAAAF;AAAA,MACA,QAAAC;AAAA,MACA,UAAUC,SAAQ,IAAIF,KAAI,QAAQE,SAAQ;AAAA,MAC1C,GAAI,WAAW,SAAS,EAAE,qBAAqB,WAAW,IAAI,CAAC;AAAA,IACjE;AAAA,EACF;AAEA,QAAM,SAAS,oBAAI,IAAoB;AACvC,QAAM,QAAkB,CAAC;AACzB,aAAW,KAAK,MAAM;AACpB,UAAM,IAAI,IAAI,QAAQ,CAAC,CAAC;AACxB,QAAI,MAAM,KAAM;AAChB,UAAM,IAAI,MAAM,QAAQ,CAAC,CAAC;AAC1B,QAAI,CAAC,OAAO,IAAI,CAAC,EAAG,OAAM,KAAK,CAAC;AAChC,WAAO,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,CAAC;AAAA,EACxC;AACA,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,MAAI,QAAQ;AACZ,MAAI,MAAgB,EAAE,OAAO,MAAM,CAAC,GAAG,OAAO,OAAO,IAAI,MAAM,CAAC,CAAC,KAAK,GAAG,OAAO,GAAG,KAAK,MAAM,CAAC,EAAE;AACjG,MAAI,SAAmB,EAAE,GAAG,IAAI;AAChC,QAAM,QAAQ,CAAC,GAAG,MAAM;AACtB,UAAM,QAAQ,OAAO,IAAI,CAAC,KAAK;AAC/B,aAAS;AACT,QAAI,QAAQ,IAAI,MAAO,OAAM,EAAE,OAAO,GAAG,OAAO,OAAO,GAAG,KAAK,EAAE;AACjE,QAAI,QAAQ,OAAO,MAAO,UAAS,EAAE,OAAO,GAAG,OAAO,OAAO,GAAG,KAAK,EAAE;AAAA,EACzE,CAAC;AACD,SAAO,EAAE,OAAO,MAAM,QAAQ,OAAO,KAAK,QAAQ,UAAU,QAAQ,IAAI,IAAI,QAAQ,QAAQ,EAAE;AAChG;AAKA,SAAS,OAAO,GAAoB;AAClC,SAAO,aAAa,OAAO,WAAW,CAAC,IAAI,MAAM,CAAC;AACpD;AAGA,SAAS,oBACP,MACA,QACA,QACA,aACkB;AAClB,QAAM,QAAQ,SAAS,MAAM;AAC7B,QAAM,QAAQ,SAAS,MAAM;AAC7B,QAAM,QAAQ,cAAc,SAAS,WAAW,IAAI;AACpD,QAAM,SAAS,oBAAI,IAAqE;AACxF,QAAM,QAAkB,CAAC;AACzB,aAAW,KAAK,MAAM;AACpB,UAAM,IAAI,IAAI,MAAM,CAAC,CAAC;AACtB,QAAI,MAAM,KAAM;AAChB,UAAM,MAAM,QAAQ,MAAM,MAAM,CAAC,CAAC,IAAI;AACtC,QAAI,IAAI,OAAO,IAAI,GAAG;AACtB,QAAI,CAAC,GAAG;AACN,UAAI,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,GAAG,MAAM,CAAC,EAAE;AACvC,aAAO,IAAI,KAAK,CAAC;AACjB,YAAM,KAAK,GAAG;AAAA,IAChB;AACA,UAAM,IAAI,MAAM,CAAC;AACjB,MAAE,OAAO,KAAK,CAAC;AACf,MAAE,OAAO,KAAK,OAAO,CAAC,CAAC;AACvB,MAAE,KAAK,KAAK,CAAC;AAAA,EACf;AACA,QAAM,MAAwB,CAAC;AAC/B,aAAW,OAAO,OAAO;AACvB,UAAM,IAAI,OAAO,IAAI,GAAG;AACxB,UAAM,KAAK,sBAAsB,EAAE,QAAQ,EAAE,QAAQ,KAAK,EAAE,IAAI;AAChE,QAAI,GAAI,KAAI,KAAK,EAAE;AAAA,EACrB;AACA,SAAO;AACT;AAEA,SAAS,oBACP,MACA,MACA,KACA,MACsB;AACtB,QAAM,qBAAqB,kBAAkB,KAAK,IAAI,EAAE;AACxD,QAAM,gBAAgB,KAAK,SAAS,SAAS,CAAC,KAAK;AACnD,QAAM,MAAM,qBACR;AAAA,IACE,KAAM,MAA2D,mBAAmB,QAAQ;AAAA,IAC5F,SAAU,MAA2D,mBAAmB,OAAO;AAAA,EACjG,IACA,EAAE,KAAK,KAAK,GAAG,SAAS,KAAK,EAAE;AACnC,MAAI,CAAC,IAAI,OAAO,CAAC,IAAI,QAAS,QAAO;AACrC,QAAM,WAAW,gBAAgB,MAAM,IAAI,IAAI,OAAO,IAAI,QAAQ,OAAO,CAAC,aAAa;AACvF,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,QAAQ;AAAA,IACR,eAAe,IAAI,IAAI;AAAA,IACvB,cAAc,UAAU,MAAM,IAAI,IAAI,KAAK;AAAA,IAC3C,cAAc,IAAI,QAAQ;AAAA,IAC1B,eAAe,IAAI,QAAQ;AAAA,IAC3B,cAAc,WAAW,IAAI,OAAO;AAAA,IACpC;AAAA,EACF;AACF;AAEA,SAAS,kBACP,MACA,MACA,KACA,MACsB;AACtB,QAAM,KAAK,KAAK,SAAS,cAAc,KAAK,QAAQ,KAAK;AACzD,QAAM,KAAK,KAAK,SAAS,cAAc,KAAK,QAAQ,KAAK;AACzD,MAAI,CAAC,MAAM,CAAC,GAAI,QAAO;AACvB,QAAM,SAAS,oBAAoB,MAAM,GAAG,OAAO,GAAG,OAAO,KAAK,QAAQ,KAAK;AAC/E,MAAI,OAAO,WAAW,EAAG,QAAO;AAChC,QAAM,SAAwB;AAAA,IAC5B,GAAG;AAAA,IACH,QAAQ;AAAA,IACR,eAAe,GAAG;AAAA,IAClB,cAAc,UAAU,MAAM,GAAG,KAAK;AAAA,IACtC,cAAc,GAAG;AAAA,IACjB,eAAe,GAAG;AAAA,IAClB,cAAc,WAAW,EAAE;AAAA,IAC3B;AAAA,EACF;AACA,MAAI,OAAO,SAAS,GAAG;AACrB,QAAI,SAAS,OAAO,CAAC;AACrB,QAAI,QAAQ,OAAO,CAAC;AACpB,eAAW,KAAK,QAAQ;AACtB,UAAI,EAAE,KAAK,QAAQ,OAAO,KAAK,MAAO,UAAS;AAC/C,UAAI,KAAK,IAAI,EAAE,SAAS,IAAI,KAAK,IAAI,MAAM,SAAS,EAAG,SAAQ;AAAA,IACjE;AACA,WAAO,SAAS,EAAE,KAAK,OAAO,KAAK,OAAO,OAAO,KAAK,MAAM;AAC5D,WAAO,eAAe,EAAE,KAAK,MAAM,KAAK,OAAO,MAAM,UAAU;AAAA,EACjE;AACA,SAAO;AACT;AAMO,SAAS,aAAa,MAAuC;AAClE,QAAM,OAAO,OAAO,IAAI;AACxB,QAAM,OAAO,KAAK;AAClB,QAAM,OAAiD,EAAE,MAAM,UAAU,KAAK,OAAO;AACrF,MAAI,KAAK,WAAW,KAAK,CAAC,YAAY,IAAI,IAAI,EAAG,QAAO;AAGxD,MAAI,YAAY,IAAI,IAAI,GAAG;AACzB,WAAO,iBAAiB,MAAM,MAAM,IAAI;AAAA,EAC1C;AAEA,QAAM,MAAM,WAAW,IAAI;AAG3B,MAAI,SAAS,aAAa;AACxB,WAAO,qBAAqB,MAAM,KAAK,IAAI;AAAA,EAC7C;AAGA,MAAI,SAAS,WAAW;AACtB,WAAO,mBAAmB,MAAM,KAAK,IAAI;AAAA,EAC3C;AAGA,QAAM,gBAAgB,SAAS,SAAS,CAAC,KAAK;AAC9C,MAAI,eAAe,IAAI,IAAI,KAAK,eAAe;AAC7C,WAAO,oBAAoB,MAAM,MAAM,KAAK,IAAI;AAAA,EAClD;AAGA,MAAI,aAAa,IAAI,IAAI,KAAK,SAAS,OAAO;AAC5C,WAAO,kBAAkB,MAAM,MAAM,KAAK,IAAI;AAAA,EAChD;AAEA,SAAO;AACT;",
+  "names": ["top", "bottom", "total"]
+}

package/dist/analyze/recommend.d.ts

@@ -0,0 +1,40 @@
+import type { ChartSpec, ChartType } from '../spec/types.js';
+import type { Datum, Size } from '../types.js';
+import type { DataFinding, DatasetProfile, DetailedColumnProfile, EncodingProfile } from '../util/profile.js';
+export { profileColumns, profileData } from '../util/profile.js';
+export type { ColumnProfile, DataFinding, DatasetProfile, DetailedColumnProfile, EncodingProfile, NumericEvidence, ProfileEncoding, ProfileField, ProfileOptions, TemporalEvidence, TypeAmbiguity, } from '../util/profile.js';
+export interface RecommendationEvidence {
+    columns: DetailedColumnProfile[];
+    sampling: DatasetProfile['sampling'];
+    encoding?: EncodingProfile;
+    intent?: RecommendOptions['intent'];
+    targetSize?: Size;
+}
+export interface RecommendedChart {
+    spec: ChartSpec;
+    score: number;
+    rationale: string;
+    /** A valid candidate can still need an explicit meaning/field decision. */
+    status?: 'ready' | 'needs-decision';
+    findings?: DataFinding[];
+    evidence?: RecommendationEvidence;
+    alternatives?: ChartType[];
+}
+export interface RecommendOptions {
+    intent?: 'trend' | 'comparison' | 'distribution' | 'relationship' | 'composition';
+    maxResults?: number;
+    /** Layout guidance only; no data is filtered or grouped to fit this size. */
+    targetSize?: Size;
+}
+export interface RecommendationResult {
+    recommendations: RecommendedChart[];
+    profile: DatasetProfile;
+    findings: DataFinding[];
+    status: 'ready' | 'needs-decision' | 'no-candidate';
+}
+/** Return ranked valid candidates, without applying any proposed data decisions. */
+export declare function recommendChart(data: readonly Datum[], opts: RecommendOptions & {
+    detailed: true;
+}): RecommendationResult;
+export declare function recommendChart(data: readonly Datum[], opts?: RecommendOptions): RecommendedChart[];
+//# sourceMappingURL=recommend.d.ts.map

package/dist/analyze/recommend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend.d.ts","sourceRoot":"","sources":["../../src/analyze/recommend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAsB,MAAM,eAAe,CAAC;AAE9E,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,KAAK,EACK,WAAW,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EACnF,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EACV,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAClF,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,aAAa,GAChG,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACpC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,GAAG,aAAa,CAAC;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,gBAAgB,EAAE,CAAC;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,EAAE,OAAO,GAAG,gBAAgB,GAAG,cAAc,CAAC;CACrD;AA4tBD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAAG,oBAAoB,CAAC;AAC1H,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC"}