@ai-matrx/rich-content 0.2.4 → 0.2.6

package/dist/display/blocks/chart/chart-spec.js

@@ -0,0 +1,128 @@
+import { soleFence } from "@ai-matrx/content-ir/source";
+const CHART_PALETTE = [
+  "#6366F1",
+  // indigo
+  "#059669",
+  // emerald
+  "#D97706",
+  // amber
+  "#E11D48",
+  // rose
+  "#0EA5E9",
+  // sky
+  "#7C3AED",
+  // violet
+  "#0D9488",
+  // teal
+  "#DB2777",
+  // pink
+  "#65A30D",
+  // lime
+  "#F59E0B"
+  // amber-light
+];
+const TYPE_SYNONYMS = {
+  bar: "bar",
+  column: "bar",
+  bars: "bar",
+  histogram: "bar",
+  line: "line",
+  lines: "line",
+  spline: "line",
+  area: "area",
+  areas: "area",
+  pie: "pie",
+  donut: "pie",
+  doughnut: "pie",
+  scatter: "scatter",
+  point: "scatter",
+  bubble: "scatter"
+};
+const X_KEYS = ["x", "xkey", "xKey", "category", "name", "label", "axis"];
+const Y_KEYS = ["y", "ykeys", "yKeys", "series", "values", "value"];
+const PIE_LABEL_KEYS = ["label", "name", "category", "key", "x"];
+const PIE_VALUE_KEYS = ["value", "y", "count", "amount", "total"];
+function tolerantParse(raw) {
+  let s = raw.trim();
+  const fenced = soleFence(s);
+  if (fenced && ["", "json", "chart"].includes(fenced.lang.toLowerCase())) s = fenced.body.trim();
+  try {
+    return JSON.parse(s);
+  } catch {
+    try {
+      return JSON.parse(s.replace(/,(\s*[}\]])/g, "$1"));
+    } catch {
+      return void 0;
+    }
+  }
+}
+function firstKey(obj, candidates) {
+  const keys = Object.keys(obj);
+  for (const c of candidates) {
+    const hit = keys.find((k) => k.toLowerCase() === c.toLowerCase());
+    if (hit) return hit;
+  }
+  return void 0;
+}
+function isNumericLike(v) {
+  return typeof v === "number" || typeof v === "string" && v.trim() !== "" && !isNaN(Number(v));
+}
+function parseChartSpec(raw) {
+  const obj = tolerantParse(raw);
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    return { error: "Chart needs a JSON object with a `type` and `data`." };
+  }
+  const o = obj;
+  const rawType = String(o.type ?? o.chartType ?? "bar").toLowerCase().trim();
+  const type = TYPE_SYNONYMS[rawType] ?? TYPE_SYNONYMS[rawType.split(/\s+/)[0]] ?? "bar";
+  const title = typeof o.title === "string" ? o.title : void 0;
+  const data = Array.isArray(o.data) ? o.data.filter((r) => r && typeof r === "object") : [];
+  if (data.length === 0) {
+    return { error: "Chart `data` must be a non-empty array of objects." };
+  }
+  const rows = data;
+  const sample = rows[0];
+  if (type === "pie") {
+    const labelKey = firstKey(sample, PIE_LABEL_KEYS) ?? Object.keys(sample).find((k) => typeof sample[k] === "string");
+    const valueKey = firstKey(sample, PIE_VALUE_KEYS) ?? Object.keys(sample).find((k) => isNumericLike(sample[k]));
+    if (!labelKey || !valueKey) {
+      return { error: "Pie `data` items need a label and a numeric value (e.g. {label, value})." };
+    }
+    const normalized2 = rows.map((r) => ({ ...r, [valueKey]: Number(r[valueKey]) }));
+    return { type, title, xKey: labelKey, series: [], data: normalized2, pie: { labelKey, valueKey }, stacked: false };
+  }
+  const explicitX = typeof o.x === "string" ? o.x : typeof o.xKey === "string" ? o.xKey : void 0;
+  const xKey = explicitX ?? firstKey(sample, X_KEYS) ?? Object.keys(sample).find((k) => typeof sample[k] === "string") ?? Object.keys(sample)[0];
+  let yKeys = [];
+  const explicitY = o.y ?? o.yKeys ?? o.series;
+  if (Array.isArray(explicitY)) {
+    yKeys = explicitY.map((s) => typeof s === "string" ? s : typeof s === "object" && s ? String(s.key ?? "") : "").filter(Boolean);
+  } else if (typeof explicitY === "string") {
+    yKeys = [explicitY];
+  }
+  if (yKeys.length === 0) {
+    yKeys = Object.keys(sample).filter((k) => k !== xKey && isNumericLike(sample[k]));
+  }
+  if (yKeys.length === 0) {
+    return { error: "Chart `data` rows need at least one numeric field to plot." };
+  }
+  const seriesMeta = Array.isArray(o.series) ? o.series : [];
+  const series = yKeys.map((key, i) => {
+    const meta = seriesMeta.find((m) => m && typeof m === "object" && m.key === key);
+    return {
+      key,
+      label: typeof meta?.label === "string" ? meta.label : key,
+      color: typeof meta?.color === "string" ? meta.color : CHART_PALETTE[i % CHART_PALETTE.length]
+    };
+  });
+  const normalized = rows.map((r) => {
+    const out = { ...r };
+    for (const s of series) if (isNumericLike(out[s.key])) out[s.key] = Number(out[s.key]);
+    return out;
+  });
+  return { type, title, xKey, series, data: normalized, stacked: Boolean(o.stacked), pie: void 0 };
+}
+export {
+  CHART_PALETTE,
+  parseChartSpec
+};

package/dist/display/blocks/chart/labels.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pie-slice label text for <ChartCanvas>'s recharts <Pie label={...}>.
+ *
+ * A SCREEN NEVER LIES. Recharts omits `percent` whenever it cannot compute
+ * one — an all-zero data set, a non-numeric `dataKey`, a slice rendered
+ * before the sum is known. The original label read
+ * `e.percent != null ? Math.round(e.percent * 100) : 0` and printed "0%",
+ * which tells the reader the slice is empty when the truth is that nobody
+ * knows its share. Unknown reads as the em-dash (the fleet convention set by
+ * `formatFileSize` in `@ai-matrx/kit/format`); a slice whose share is REALLY
+ * zero still prints "0%".
+ *
+ * Lives in its own module rather than inline so it can be tested without
+ * pulling recharts into the Jest module graph.
+ */
+export interface PieSliceLabelInput {
+    name?: string;
+    percent?: number;
+}
+export declare function pieSliceLabel(e: PieSliceLabelInput): string;

package/dist/display/blocks/chart/labels.js

@@ -0,0 +1,7 @@
+import { formatPercentFromFraction } from "@ai-matrx/kit/format";
+function pieSliceLabel(e) {
+  return `${e.name ?? ""} ${formatPercentFromFraction(e.percent)}`;
+}
+export {
+  pieSliceLabel
+};

package/dist/display/blocks/chart/table-chart.d.ts

@@ -0,0 +1,37 @@
+/**
+ * table-chart — turn a table an answer already shows (markdown table, CSV, TSV)
+ * into a ChartSpec for the ONE chart primitive (chart-spec + ChartCanvas).
+ * PURE: no recharts, no React — the "Chart this" button and the code-block
+ * "Chart this" action both call it, and it is unit-tested on its own.
+ *
+ * Auto-pick (what ChatGPT's analysis charts and Excel's "Recommended charts"
+ * do, reduced to the cases answers actually contain):
+ *   - no numeric column                     → not chartable (the button is absent)
+ *   - every column numeric                  → scatter (first column vs the rest)
+ *   - category column reads as time         → line
+ *   - one series, ≤ 8 rows, all ≥ 0, a share (%, "share", or sums to ~100) → pie
+ *   - otherwise                             → bar
+ * The reader can switch to any type the data can draw (`chartableTypes`).
+ */
+import { type ChartSpec, type ChartType } from "./chart-spec.js";
+export interface PlainTable {
+    headers: string[];
+    rows: string[][];
+}
+/** A table cell as a number, or null when it is not one. Never invents 0. */
+export declare function parseCellNumber(raw: unknown): number | null;
+/** The chart types this table can honestly draw, in menu order. */
+export declare function chartableTypes(table: PlainTable): ChartType[];
+/**
+ * Build the ChartSpec for a table. `requested` switches the type; a type the
+ * data cannot draw falls back to the auto-pick. Null = not chartable.
+ */
+export declare function tableToChartSpec(table: PlainTable, requested?: ChartType): ChartSpec | null;
+/**
+ * The sentence a chart owes its reader when it cannot show every row as asked:
+ * a pie over negative values (drawn as bars instead), or rows with no number
+ * (not plotted). Null when the chart shows everything.
+ */
+export declare function chartNotice(table: PlainTable, requested?: ChartType): string | null;
+/** RFC-4180-ish CSV / TSV → table. Null when the text is not a table. */
+export declare function parseDelimitedTable(text: string): PlainTable | null;

package/dist/display/blocks/chart/table-chart.js

@@ -0,0 +1,231 @@
+import { CHART_PALETTE } from "./chart-spec.js";
+const SUFFIX = { k: 1e3, m: 1e6, b: 1e9, bn: 1e9, t: 1e12 };
+function parseCellNumber(raw) {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : null;
+  if (typeof raw !== "string") return null;
+  let s = raw.trim().replace(/^\*\*|\*\*$/g, "").replace(/^_|_$/g, "").trim();
+  if (!s) return null;
+  let negative = false;
+  if (/^\(.*\)$/.test(s)) {
+    negative = true;
+    s = s.slice(1, -1).trim();
+  }
+  s = s.replace(/^[$€£¥₹]\s*/, "").replace(/\s*(USD|EUR|GBP)$/i, "");
+  s = s.replace(/%$/, "");
+  const m = /^([-+]?)(\d{1,3}(?:,\d{3})+|\d+)?(\.\d+)?\s*(k|m|bn|b|t)?$/i.exec(s);
+  if (!m || !m[2] && !m[3]) return null;
+  const whole = (m[2] ?? "0").replace(/,/g, "");
+  let n = Number(`${whole}${m[3] ?? ""}`);
+  if (!Number.isFinite(n)) return null;
+  if (m[4]) n *= SUFFIX[m[4].toLowerCase()] ?? 1;
+  if (m[1] === "-") n = -n;
+  return negative ? -n : n;
+}
+function numericColumns(table) {
+  const out = [];
+  table.headers.forEach((_, col) => {
+    let filled = 0;
+    let numeric = 0;
+    for (const row of table.rows) {
+      const cell = row[col];
+      if (cell == null || String(cell).trim() === "" || /^[-—–]$/.test(String(cell).trim())) continue;
+      filled += 1;
+      if (parseCellNumber(cell) !== null) numeric += 1;
+    }
+    if (filled > 0 && numeric / filled >= 0.6) out.push(col);
+  });
+  return out;
+}
+const MONTHS = /^(jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?(\s+\d{2,4})?$/i;
+const TIME_HEADER = /^(year|month|date|day|week|quarter|period|time|fy|q)\b/i;
+function looksTemporal(header, values) {
+  if (TIME_HEADER.test(header.trim())) return true;
+  const vals = values.map((v) => String(v ?? "").trim()).filter(Boolean);
+  if (vals.length < 2) return false;
+  const temporal = vals.filter(
+    (v) => /^(19|20)\d{2}$/.test(v) || MONTHS.test(v) || /^q[1-4]\b/i.test(v) || /^\d{4}-\d{2}(-\d{2})?$/.test(v) || /^\d{1,2}\/\d{1,2}\/\d{2,4}$/.test(v)
+  );
+  return temporal.length / vals.length >= 0.8;
+}
+function shapeOf(table) {
+  if (!table.headers.length || !table.rows.length) return null;
+  let numeric = numericColumns(table);
+  const timeCol = numeric.find(
+    (i) => looksTemporal("", table.rows.map((r) => r[i]))
+  );
+  if (timeCol !== void 0 && numeric.length > 1) {
+    numeric = numeric.filter((i) => i !== timeCol);
+  }
+  if (numeric.length === 0) return null;
+  const categoryCol = timeCol !== void 0 && !numeric.includes(timeCol) ? timeCol : table.headers.findIndex((_, i) => !numeric.includes(i));
+  return {
+    categoryCol: categoryCol === -1 ? null : categoryCol,
+    valueCols: numeric
+  };
+}
+function chartableTypes(table) {
+  const shape = shapeOf(table);
+  if (!shape) return [];
+  const types = ["bar", "line", "area", "pie"];
+  if (shape.valueCols.length >= 2) types.push("scatter");
+  return types;
+}
+function autoPick(table, shape) {
+  if (shape.categoryCol === null) return shape.valueCols.length >= 2 ? "scatter" : "bar";
+  const catHeader = table.headers[shape.categoryCol] ?? "";
+  const catValues = table.rows.map((r) => r[shape.categoryCol]);
+  if (looksTemporal(catHeader, catValues)) return "line";
+  if (shape.valueCols.length === 1 && table.rows.length <= 8) {
+    const col = shape.valueCols[0];
+    const values = table.rows.map((r) => parseCellNumber(r[col]));
+    const allNonNeg = values.every((v) => v !== null && v >= 0);
+    const isShare = /share|percent|%|portion|split|mix/i.test(table.headers[col] ?? "") || table.rows.some((r) => /%\s*$/.test(String(r[col] ?? ""))) || Math.abs(values.reduce((a, v) => a + (v ?? 0), 0) - 100) <= 1;
+    if (allNonNeg && isShare) return "pie";
+  }
+  return "bar";
+}
+function tableToChartSpec(table, requested) {
+  const shape = shapeOf(table);
+  if (!shape) return null;
+  const allowed = chartableTypes(table);
+  let type = requested && allowed.includes(requested) ? requested : autoPick(table, shape);
+  if (type === "pie" && negativeRows(table, shape).length > 0) type = "bar";
+  const headers = table.headers.map((h, i) => h && h.trim() || `Column ${i + 1}`);
+  if (type === "scatter") {
+    const [xCol, ...yCols] = shape.valueCols;
+    const xKey = headers[xCol];
+    const data2 = table.rows.map((row) => {
+      const out = { [xKey]: parseCellNumber(row[xCol]) };
+      for (const c of yCols) out[headers[c]] = parseCellNumber(row[c]);
+      if (shape.categoryCol !== null) out[headers[shape.categoryCol]] = row[shape.categoryCol];
+      return out;
+    });
+    return {
+      type,
+      xKey,
+      series: yCols.map((c, i) => ({ key: headers[c], label: headers[c], color: CHART_PALETTE[i % CHART_PALETTE.length] })),
+      data: data2,
+      stacked: false
+    };
+  }
+  const catKey = shape.categoryCol !== null ? headers[shape.categoryCol] : "#";
+  const data = table.rows.map((row, i) => {
+    const out = {
+      [catKey]: shape.categoryCol !== null ? String(row[shape.categoryCol] ?? "").replace(/\*\*/g, "").trim() : String(i + 1)
+    };
+    for (const c of shape.valueCols) out[headers[c]] = parseCellNumber(row[c]);
+    return out;
+  });
+  if (type === "pie") {
+    const valueKey = headers[shape.valueCols[0]];
+    return {
+      type,
+      xKey: catKey,
+      series: [],
+      data: data.filter((d) => typeof d[valueKey] === "number" && d[valueKey] >= 0),
+      pie: { labelKey: catKey, valueKey },
+      stacked: false
+    };
+  }
+  return {
+    type,
+    xKey: catKey,
+    series: shape.valueCols.map((c, i) => ({
+      key: headers[c],
+      label: headers[c],
+      color: CHART_PALETTE[i % CHART_PALETTE.length]
+    })),
+    data,
+    stacked: false
+  };
+}
+function categoryLabel(table, shape, row, i) {
+  return shape.categoryCol !== null ? String(row[shape.categoryCol] ?? "").replace(/\*\*/g, "").trim() : `Row ${i + 1}`;
+}
+function negativeRows(table, shape) {
+  const col = shape.valueCols[0];
+  const out = [];
+  table.rows.forEach((row, i) => {
+    const v = parseCellNumber(row[col]);
+    if (v !== null && v < 0) out.push({ label: categoryLabel(table, shape, row, i), value: v });
+  });
+  return out;
+}
+function formatNumber(n) {
+  return n < 0 ? `\u2212${Math.abs(n)}` : String(n);
+}
+function chartNotice(table, requested) {
+  const shape = shapeOf(table);
+  if (!shape) return null;
+  const allowed = chartableTypes(table);
+  const wanted = requested && allowed.includes(requested) ? requested : autoPick(table, shape);
+  if (wanted === "pie") {
+    const neg = negativeRows(table, shape);
+    if (neg.length > 0) {
+      const list = neg.map((r) => `${r.label} ${formatNumber(r.value)}`).join(", ");
+      return `A pie can't show negative values (${list}), so this is drawn as bars.`;
+    }
+  }
+  const notes = [];
+  if (wanted === "pie" && shape.valueCols.length > 1) {
+    const shown = table.headers[shape.valueCols[0]] ?? "the first column";
+    const rest = shape.valueCols.slice(1).map((c) => table.headers[c]).join(", ");
+    notes.push(`A pie shows one column \u2014 this is ${shown}; ${rest} ${shape.valueCols.length > 2 ? "are" : "is"} not shown.`);
+  }
+  const missing = [];
+  table.rows.forEach((row, i) => {
+    if (shape.valueCols.every((c) => parseCellNumber(row[c]) === null)) {
+      missing.push(categoryLabel(table, shape, row, i));
+    }
+  });
+  if (missing.length === 1) notes.push(`1 row has no number and is not plotted (${missing[0]}).`);
+  else if (missing.length > 1) {
+    notes.push(`${missing.length} rows have no number and are not plotted (${missing.join(", ")}).`);
+  }
+  return notes.length > 0 ? notes.join(" ") : null;
+}
+function parseDelimitedTable(text) {
+  const src = text.replace(/\r\n?/g, "\n").trim();
+  if (!src) return null;
+  const firstLine = src.split("\n", 1)[0];
+  const delimiter = firstLine.includes("	") ? "	" : firstLine.includes(",") ? "," : firstLine.includes(";") ? ";" : null;
+  if (!delimiter) return null;
+  const records = [];
+  let row = [];
+  let cell = "";
+  let quoted = false;
+  for (let i = 0; i < src.length; i++) {
+    const ch = src[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (src[i + 1] === '"') {
+          cell += '"';
+          i++;
+        } else quoted = false;
+      } else cell += ch;
+    } else if (ch === '"' && cell === "") quoted = true;
+    else if (ch === delimiter) {
+      row.push(cell);
+      cell = "";
+    } else if (ch === "\n") {
+      row.push(cell);
+      records.push(row);
+      row = [];
+      cell = "";
+    } else cell += ch;
+  }
+  row.push(cell);
+  records.push(row);
+  const cleaned = records.filter((r) => r.some((c) => c.trim() !== ""));
+  if (cleaned.length < 2) return null;
+  const [headers, ...rows] = cleaned;
+  if (headers.length < 2) return null;
+  return { headers: headers.map((h) => h.trim()), rows: rows.map((r) => r.map((c) => c.trim())) };
+}
+export {
+  chartNotice,
+  chartableTypes,
+  parseCellNumber,
+  parseDelimitedTable,
+  tableToChartSpec
+};

package/dist/display/blocks/common/BlockHeaderWrapper.d.ts

@@ -0,0 +1,56 @@
+import React, { ReactNode } from "react";
+import { LucideIcon } from "lucide-react";
+import { MenuItem } from "../../../host/app-bindings.js";
+import type { CanvasContentType } from "../../../utils/lifted/canvasContent.js";
+export interface BlockHeaderWrapperProps {
+    icon: LucideIcon;
+    iconClassName?: string;
+    title: string;
+    description?: string;
+    controls?: ReactNode;
+    children: ReactNode;
+    canvasType?: CanvasContentType;
+    canvasData?: unknown;
+    canvasMetadata?: Record<string, unknown>;
+    taskId?: string;
+    /**
+     * The exact data object to export as JSON.
+     * When provided, a Download button (desktop) / menu item (mobile) appears.
+     */
+    exportData?: unknown;
+    /** Filename without extension. Defaults to "export". */
+    exportFilename?: string;
+    /**
+     * Called with the parsed JSON object when the user picks a valid JSON file.
+     * The block is responsible for validating/applying the new data.
+     */
+    onDataImport?: (data: unknown) => void;
+    /**
+     * Extra buttons rendered on desktop alongside the standard action buttons.
+     * On mobile these are hidden — use extraMenuItems to expose them in the menu.
+     */
+    extraActions?: ReactNode;
+    /**
+     * Extra items injected into the mobile AdvancedMenu (and ignored on desktop,
+     * where extraActions handles the same actions visually).
+     */
+    extraMenuItems?: MenuItem[];
+    /** Tailwind gradient classes for the header card background */
+    headerGradient?: string;
+    /** Tailwind border class for the header card */
+    headerBorder?: string;
+    /** Classes applied to the import/export/fullscreen buttons */
+    actionButtonClassName?: string;
+    /** Classes applied to the canvas button */
+    canvasButtonClassName?: string;
+}
+/**
+ * BlockHeaderWrapper
+ *
+ * Reusable gradient header wrapper for chat markdown blocks.
+ *
+ * Desktop: individual icon buttons (Upload, Download, extra actions, Canvas, Fullscreen).
+ * Mobile:  a single MoreHorizontal trigger that opens an AdvancedMenu with all actions.
+ */
+declare const BlockHeaderWrapper: React.FC<BlockHeaderWrapperProps>;
+export default BlockHeaderWrapper;