@chartbuddy.io/embed 1.7.52

package/chartbuddy-embed.api.mjs

@@ -0,0 +1,64 @@
+/**
+ * @chartbuddy.io/embed — ChartBuddy Insights (NOT Chart.js / Recharts).
+ * This file is the readable package-root stub (unpkg / exports["."]).
+ * Default is view-only (hover ChartBuddy ball: Download / Drag to slide /
+ * Export / Edit). Pass editable: true for the full editor. Ball → Done exits.
+ *
+ * Exports:
+ *   new Insight(target, options?) → Insight
+ *   validateChartData(chartData, options?) → { valid, issues, errors, warnings }
+ *   assertValidChartData / formatValidationIssues / ChartDataValidationError
+ *   getInsights() / snapshotInsights({ png? })
+ *   clearPersistedChart(instanceId?)
+ *   version: string
+ * Agent hook: window.__CHARTBUDDY_INSIGHTS__ (keyed by instanceId)
+ *
+ * Minimal example (view mode, data-in, no account / chart ID):
+ *   import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed';
+ *   const insight = new Insight('#chart', {
+ *     instanceId: 'revenue',
+ *     chartData: {
+ *       chartType: 'clusteredBar',
+ *       isDataTransposed: true,
+ *       seriesData: [['','Q1','Q2'],['Revenue',100,112],['Costs',60,66]],
+ *     },
+ *   });
+ *   await insight.ready;
+ *   // Agent observe: await insight.toPngBase64() / insight.getChartData()
+ *   // Full editor: new Insight('#chart', { editable: true, chartData: … })
+ *   // Leave edit: insight.exitEditMode() or ball → Done
+ *
+ * Check before you mount (agent generate → check → repair loop):
+ *   const { valid, errors } = validateChartData(candidate);
+ *   // errors[i] = { path, code, message, expected?, received?, allowed?, suggestion? }
+ *   // codes: unknown-chart-type | wrong-type | out-of-range | not-in-enum |
+ *   //        series-data-shape | ragged-series-data | foreign-option-bag |
+ *   //        empty-patch | not-an-object   (branch on code, never on message)
+ *
+ * Framework bindings (each ships its own types):
+ *   React 18/19 : import { InsightChart, useInsight } from '@chartbuddy.io/embed/react'
+ *   Vue 3       : import { InsightChart, useInsight } from '@chartbuddy.io/embed/vue'
+ *   Angular etc : import '@chartbuddy.io/embed/element'  → <chartbuddy-insight>
+ *
+ * Docs (fetch next if needed):
+ *   https://unpkg.com/@chartbuddy.io/embed/llms.txt
+ *   https://cb-acc.xyz/llms.txt
+ *   https://cb-acc.xyz/embed/api
+ *   https://unpkg.com/@chartbuddy.io/embed/README.md
+ *
+ * Implementation: re-exports the self-contained single-file build (no assetBase).
+ */
+export {
+  Insight,
+  clearPersistedChart,
+  getInsights,
+  snapshotInsights,
+  CHARTBUDDY_INSIGHTS_GLOBAL,
+  version,
+  validateChartData,
+  assertValidChartData,
+  formatValidationIssues,
+  ChartDataValidationError,
+} from './chartbuddy-embed.single.mjs';
+
+export { default } from './chartbuddy-embed.single.mjs';

package/chartbuddy-embed.d.ts

@@ -0,0 +1,488 @@
+/**
+ * @chartbuddy.io/embed — type declarations.
+ *
+ * ChartBuddy creates **Insights**. Default is view-only (headless draw +
+ * ChartBuddy hover ball). Pass `editable: true` for the full interactive
+ * editor. In edit mode, ball → **Done** (or `exitEditMode()`) returns to view.
+ * Spreadsheet is not included in this package.
+ */
+
+/**
+ * Chart type unions, generated from the ChartBuddy chart schema registry.
+ * Do not restate the chart type list here — edit the registry and regenerate.
+ */
+export type {
+  ChartType,
+  ChartTypeAlias,
+  ChartTypeInput,
+  ChartTypeOptionBag,
+  ChartTypeSeriesLayout,
+} from './chart-schema.js';
+
+import type { ChartType, ChartTypeInput } from './chart-schema.js';
+
+/** A single spreadsheet cell. `null` marks an intentionally empty cell. */
+export type ChartCell = string | number | boolean | null;
+
+/**
+ * The raw 2D data grid. The required layout depends on `chartType` — see
+ * `ChartTypeSeriesLayout` and the `seriesData` section of llms.txt.
+ */
+export type SeriesData = ChartCell[][];
+
+/**
+ * Fields common to every chart type.
+ *
+ * Stays open (`[key: string]: unknown`) because a config may legitimately carry
+ * keys a given build does not know about; ChartBuddy migrates shapes on load.
+ */
+export interface ChartDataCommon {
+  id?: string;
+  /** App version this config was last migrated to. */
+  version?: string;
+  title?: TextElement;
+  subtitle?: TextElement;
+  footnote?: TextElement;
+  /** When true (default), `seriesData` rows are series. */
+  isDataTransposed?: boolean;
+  canvas?: { width: number; height: number };
+  orientation?: 'vertical' | 'horizontal';
+  axes?: Record<string, Record<string, unknown>>;
+  annotations?: Record<string, unknown>;
+  legend?: {
+    visible?: boolean;
+    /** The chart's color palette. */
+    colors?: string[];
+    position?: string;
+    [key: string]: unknown;
+  };
+  backgroundColor?: string;
+  seriesLabels?: Record<string, unknown>;
+  multilines?: unknown[];
+  [key: string]: unknown;
+}
+
+/** Title / subtitle / footnote / axis title. `text` accepts inline HTML. */
+export interface TextElement {
+  id?: string;
+  visible?: boolean;
+  text?: string;
+  fontFamily?: string;
+  fontSize?: number;
+  fontColor?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Chart data you PASS IN (`new Insight()` / `setChartData()`).
+ *
+ * Partial configs are merged over ChartBuddy's defaults, so only the fields you
+ * care about are required. Aliases (`donut`, `bubble`) are accepted and
+ * normalized. An unknown `chartType` is a type error here and throws at runtime.
+ */
+export interface ChartDataInput extends ChartDataCommon {
+  chartType?: ChartTypeInput;
+  seriesData?: SeriesData;
+  /** Bar options (`clusteredBar`, `stackedBar`, `stackedBar100`). */
+  bar?: Record<string, unknown>;
+  line?: Record<string, unknown>;
+  /** Shared by `area` and `area100`. */
+  area?: Record<string, unknown>;
+  /** Shared by `scatter` and the `bubble` alias. */
+  scatter?: Record<string, unknown>;
+  /** Shared by `pie` and the `donut` alias (`innerRadiusRatio`). */
+  pie?: Record<string, unknown>;
+  waterfall?: Record<string, unknown>;
+  mekko?: Record<string, unknown>;
+  /** Bar Mekko options, e.g. `{ sort: 'heightDesc' }`. */
+  barMekko?: Record<string, unknown>;
+  combo?: Record<string, unknown>;
+}
+
+/**
+ * A resolved chart config — what `getChartData()` returns.
+ *
+ * `chartType` is always canonical (aliases already normalized) and `seriesData`
+ * is always present. Safe to round-trip straight back into `setChartData()`.
+ */
+export interface ChartData extends ChartDataInput {
+  chartType: ChartType;
+  seriesData: SeriesData;
+}
+
+export type EmbedMode = 'view' | 'edit';
+
+/** Events an Insight can emit. Handlers are typed per event. */
+export type InsightEventMap = {
+  /** Fired once when the insight finishes booting (view or edit). */
+  ready: [];
+  /** Fired whenever the insight switches between view and edit. */
+  mode: [EmbedMode];
+  /**
+   * Fired after a meaningful config change — programmatic `setChartData` /
+   * `setData` / `update`, live edits in edit mode, or Done.
+   */
+  change: [ChartData | null];
+};
+
+export type InsightEvent = keyof InsightEventMap;
+export type InsightEventHandler<E extends InsightEvent> = (...args: InsightEventMap[E]) => void;
+
+/** Options for PNG export helpers (`toPngBlob` / `toPngBase64` / `downloadPng`). */
+export interface PngOptions {
+  /**
+   * Pixel scale multiplier (same as the download pipeline). Default 4.
+   */
+  scale?: number;
+  /**
+   * CSS color baked under the chart in the PNG (e.g. `#ffffff`).
+   * Export strips the live SVG background for Slides-friendly transparency.
+   * - `toPngBlob` / `toPngBase64` default: `#ffffff`
+   * - `downloadPng` default: transparent
+   * - Pass `null` or `'transparent'` for a transparent PNG
+   */
+  background?: string | null;
+}
+
+export interface InsightOptions {
+  /**
+   * Chart data to open with. A partial config is merged over ChartBuddy's
+   * defaults; a full config (e.g. the JSON from "Export Config") is used as-is.
+   * Omit to open the default starter chart.
+   */
+  chartData?: ChartDataInput;
+  /**
+   * Where to fetch the editor engine/assets from (multi-file loader only).
+   * Defaults to the directory this loader was served from. Ignored by the
+   * single-file build (`chartbuddy-embed.single.mjs` / `@chartbuddy.io/embed/single`).
+   * Must end with `/`.
+   */
+  assetBase?: string;
+  /**
+   * When true, open the full interactive editor. When false (default), open
+   * view-only with the ChartBuddy hover ball (Download / Export / Edit).
+   */
+  editable?: boolean;
+  /**
+   * Show the built-in Reset / Import / Export strip. Only applies when
+   * `editable: true`. Default false.
+   */
+  toolbar?: boolean;
+  /**
+   * Persist this insight's config under a unique per-instance localStorage key.
+   * Default false. With a stable `instanceId`, edits survive reload
+   * (checkpointed on Done / `exitEditMode`).
+   */
+  persist?: boolean;
+  /**
+   * Stable, developer-controlled id for this mount. Used for localStorage keys,
+   * `data-cb-instance`, and `getInsights()` / `window.__CHARTBUDDY_INSIGHTS__`.
+   * When omitted, a random UUID is generated (breaks persist across reloads).
+   * Allowed chars: letters, digits, `_`, `.`, `:`, `-`.
+   */
+  instanceId?: string;
+  /**
+   * Customize where/how the editor's chrome mounts — e.g. keep the
+   * formatting toolbar inside your own widget instead of floating over the
+   * whole viewport. See {@link EmbedHostOverrides}.
+   */
+  host?: EmbedHostOverrides;
+}
+
+/**
+ * Optional host hooks for customizing editor chrome placement/behavior.
+ * All fields are optional — anything you don't override keeps the built-in
+ * default (a full-viewport overlay for the formatting toolbar, default
+ * positioning, and a no-op for background drags).
+ */
+export interface EmbedHostOverrides {
+  /**
+   * Where to mount the formatting toolbar that appears when a chart element
+   * is selected. Return a CSS selector or an `Element`. Defaults to a
+   * per-instance full-viewport overlay.
+   */
+  getToolbarContainer?: () => string | Element | null;
+  /**
+   * Override the default toolbar positioning logic (called after the
+   * toolbar is appended into the container from `getToolbarContainer`).
+   * @param toolbarNode The rendered toolbar DOM element.
+   * @param targetNode The chart element that was selected (if any).
+   */
+  positionToolbar?: (toolbarNode: HTMLElement, targetNode: HTMLElement | null) => void;
+  /**
+   * Called when the user starts dragging on non-interactive chart
+   * background. Use this to let the host move/drag its own outer widget
+   * chrome instead (the engine will not move anything itself).
+   */
+  startDragging?: (event: MouseEvent) => void;
+}
+
+/**
+ * A ChartBuddy Insight — view-only chart or full editor in a host element.
+ *
+ * Default is view-only. Pass `editable: true` for the full editor.
+ * In edit mode, the hover ball offers **Done** to return to view.
+ *
+ * Safe to construct multiple times in one document. For Claude / strict CSP,
+ * import from `chartbuddy-embed.single.mjs` (or `@chartbuddy.io/embed/single`)
+ * so the engine does not fetch sibling scripts.
+ */
+export declare class Insight {
+  constructor(target: string | HTMLElement, options?: InsightOptions);
+
+  /** The container element the insight was mounted into. */
+  readonly container: HTMLElement;
+  /** The asset base the engine was loaded from. */
+  readonly assetBase: string;
+  /** Unique id for this instance (stable when `options.instanceId` is set). */
+  readonly instanceId: string;
+  /** Id of the chart container element for this instance. */
+  readonly chartContainerId: string;
+  /** Current mode (`view` by default, `edit` after Edit or `editable: true`). */
+  readonly mode: EmbedMode;
+  /** Promise that resolves when the insight has finished booting (or rejected). */
+  readonly ready: Promise<void>;
+  /**
+   * Live ChartBuddy engine instance (`any` — internals are unstable). Prefer
+   * `getChartData` / `setChartData` / export helpers instead of touching this.
+   */
+  readonly chart: any | null;
+
+  /** Claim keyboard / interaction focus for this chart (edit mode). */
+  focus(): void;
+  /**
+   * Update the live chart with a full or partial config.
+   *
+   * Passing only `seriesData` refreshes the data while keeping the current chart
+   * type and formatting. Nested `axes` / `annotations` patches are deep-merged.
+   * `chartType` is optional — omit it to keep the current type.
+   */
+  setChartData(chartData: ChartDataInput): void;
+  /**
+   * Refresh only the data grid. Keeps chart type and formatting.
+   * Chart.js equivalent of assigning `chart.data` then calling `update()`.
+   */
+  setData(seriesData: SeriesData): void;
+  /**
+   * Apply a partial patch and redraw. With no argument, redraws without
+   * changing config (Chart.js `chart.update()`).
+   */
+  update(patch?: ChartDataInput): void;
+  /** Snapshot of the current chart config (`cd`). */
+  getChartData(): ChartData | null;
+  /**
+   * Subscribe to a lifecycle event. Returns an unsubscribe function.
+   * Events: `ready`, `mode` (view ↔ edit), `change` (after meaningful edits).
+   */
+  on<E extends InsightEvent>(event: E, handler: InsightEventHandler<E>): () => void;
+  /** Remove a previously registered handler. */
+  off<E extends InsightEvent>(event: E, handler: InsightEventHandler<E>): void;
+  /** True when the chart has changed since boot / last Done checkpoint. */
+  isDirty(): boolean;
+  /** Monotonic edit counter — increments on every meaningful change. */
+  getRevision(): number;
+  /**
+   * PNG bytes as a Blob (no browser download). Prefer this or `toPngBase64`
+   * for agent / CDP loops — `downloadPng` only triggers a Save dialog.
+   */
+  toPngBlob(options?: PngOptions): Promise<Blob>;
+  /**
+   * PNG as raw base64 (no `data:` prefix). For agent observation / writing files.
+   */
+  toPngBase64(options?: PngOptions): Promise<string>;
+  /** Download a PNG of the current chart (human Save dialog). */
+  downloadPng(options?: PngOptions): Promise<void>;
+  /** Open the drag-to-export widget (multi-scale PNG you can drag into slides etc.). */
+  dragExport(): Promise<void>;
+  /** Download the current chart config as JSON. */
+  exportConfig(): void;
+  /** Switch from view mode to the full interactive editor (no-op if already editing). */
+  enterEditMode(): Promise<void>;
+  /**
+   * Leave edit mode and return to view-only (no-op if already in view).
+   * When `persist: true`, checkpoints `chartData` to localStorage first.
+   */
+  exitEditMode(): Promise<void>;
+  /** Tear down listeners, persistence, overlay, and DOM shell. */
+  destroy(): void;
+}
+
+/**
+ * Clear persisted insight chart config.
+ * @param instanceId When set, clears that embed instance's keys only.
+ *                   When omitted, clears the legacy shared webapp key.
+ */
+export function clearPersistedChart(instanceId?: string): void;
+
+/**
+ * Live Insights on this page, keyed by `instanceId`.
+ * Also mirrored at `window.__CHARTBUDDY_INSIGHTS__` for agent CDP hooks.
+ */
+export function getInsights(): Record<string, Insight>;
+
+export interface InsightSnapshotEntry {
+  chartData: ChartData | null;
+  /** Present only when `png: true`. */
+  pngBase64?: string;
+}
+
+export interface InsightsSnapshot {
+  schemaVersion: 1;
+  version: string;
+  charts: Record<string, InsightSnapshotEntry>;
+}
+
+/**
+ * Agent-oriented snapshot of every registered Insight.
+ * Config-only by default (`png` is opt-in — multi-chart PNG payloads are large).
+ */
+export function snapshotInsights(options?: {
+  png?: boolean;
+  scale?: number;
+  /** Passed through to `toPngBase64` when `png: true`. Default `#ffffff`. */
+  background?: string | null;
+}): Promise<InsightsSnapshot>;
+
+/** Documented agent hook name (`window.__CHARTBUDDY_INSIGHTS__`). */
+export const CHARTBUDDY_INSIGHTS_GLOBAL: '__CHARTBUDDY_INSIGHTS__';
+
+/* ------------------------------------------------------------------ *
+ * Validation
+ *
+ * `new Insight()`, `setChartData()`, `setData()`, and `update()` all validate
+ * their input and throw `ChartDataValidationError` on an error-severity problem.
+ * The same checks are exported so you can validate a candidate config first —
+ * useful when an LLM authored it and you want a generate → check → repair loop
+ * without mounting anything.
+ * ------------------------------------------------------------------ */
+
+/** Stable, machine-readable classification of a validation problem. */
+export type ValidationIssueCode =
+  /** The value is not a chart-data object at all. */
+  | 'not-an-object'
+  /** `chartType` is not a known type or alias. `allowed` lists every legal value. */
+  | 'unknown-chart-type'
+  /** Neither `chartType` nor `seriesData` was supplied. */
+  | 'empty-patch'
+  /** A known field holds the wrong JavaScript type. */
+  | 'wrong-type'
+  /** A numeric field is outside its documented range. */
+  | 'out-of-range'
+  /** A string field is outside its documented set of values. */
+  | 'not-in-enum'
+  /** `seriesData` is not a usable 2D grid for this chart type. */
+  | 'series-data-shape'
+  /** `seriesData` rows have unequal lengths. Warning — the renderer pads. */
+  | 'ragged-series-data'
+  /** An option bag belongs to a different chart type. */
+  | 'foreign-option-bag';
+
+/** Errors reject at the API boundary; warnings are logged and the call proceeds. */
+export type ValidationSeverity = 'error' | 'warning';
+
+/**
+ * One problem found in a chart-data object.
+ *
+ * `code` and `path` are the stable part of this contract — branch on `code`,
+ * repair the value at `path`. `message` is for humans and may be reworded in
+ * any release, so do not parse it.
+ */
+export interface ValidationIssue {
+  /** Dotted/bracketed path to the offending value, e.g. `pie.innerRadiusRatio`. */
+  readonly path: string;
+  readonly code: ValidationIssueCode;
+  readonly message: string;
+  readonly severity: ValidationSeverity;
+  /** What the schema wanted, e.g. `'number'`, `'integer'`, `'>= 0'`, `'2D array'`. */
+  readonly expected?: string;
+  /** What arrived, as a type name or short literal, e.g. `'string'`, `'1.5'`. */
+  readonly received?: string;
+  /** For `not-in-enum` / `unknown-chart-type`: the full set of legal values. */
+  readonly allowed?: readonly string[];
+  /** Nearest legal value, when one is close enough to be a likely typo fix. */
+  readonly suggestion?: string;
+}
+
+export interface ValidationResult {
+  /** True when there are no `error`-severity issues. Warnings do not invalidate. */
+  readonly valid: boolean;
+  /** Every issue found, errors and warnings together, in document order. */
+  readonly issues: readonly ValidationIssue[];
+  /** The `error`-severity subset — what makes `valid` false. */
+  readonly errors: readonly ValidationIssue[];
+  /** The `warning`-severity subset — rendered anyway, but probably a bug. */
+  readonly warnings: readonly ValidationIssue[];
+}
+
+export interface ValidateChartDataOptions {
+  /**
+   * Which form the input is in.
+   * - `patch`    — a hand-authored partial config; a foreign option bag is an issue.
+   * - `resolved` — a full snapshot (e.g. from `getChartData()`); every bag expected.
+   * - `auto`     — infer from whether every option bag is present (default).
+   */
+  readonly form?: 'patch' | 'resolved' | 'auto';
+  /**
+   * Require at least one of `chartType` / `seriesData`. Default true.
+   * Turn off when validating a styling-only patch.
+   */
+  readonly requireSomething?: boolean;
+  /** Stop after this many issues, so messages stay readable. Default 20. */
+  readonly maxIssues?: number;
+}
+
+/**
+ * Check a chart-data object against the schema. Never throws.
+ *
+ * @example
+ * const { valid, errors } = validateChartData(candidate);
+ * if (!valid) return repair(errors);   // branch on error.code, fix error.path
+ * new Insight('#chart', { chartData: candidate });
+ */
+export function validateChartData(
+  chartData: unknown,
+  options?: ValidateChartDataOptions,
+): ValidationResult;
+
+/**
+ * Thrown by `new Insight()`, `setChartData()`, `setData()`, and `update()` when
+ * the input has error-severity problems. Carries the structured issues.
+ */
+export class ChartDataValidationError extends Error {
+  readonly name: 'ChartDataValidationError';
+  /** Error-severity issues only — the reasons this threw. */
+  readonly errors: readonly ValidationIssue[];
+  /** Warnings found in the same pass. Already logged; did not cause the throw. */
+  readonly warnings: readonly ValidationIssue[];
+  /** Errors and warnings together. */
+  readonly issues: readonly ValidationIssue[];
+  toJSON(): { name: string; message: string; issues: readonly ValidationIssue[] };
+}
+
+/**
+ * Validate and throw `ChartDataValidationError` on any error-severity issue.
+ * Warnings are logged to the console instead. This is what the Insight API calls.
+ */
+export function assertValidChartData(
+  chartData: unknown,
+  context?: string,
+  options?: ValidateChartDataOptions,
+): void;
+
+/** Render issues as one human-readable multi-line message. */
+export function formatValidationIssues(
+  issues: readonly ValidationIssue[],
+  context?: string,
+): string;
+
+/** The ChartBuddy engine version this package ships. */
+export const version: string;
+
+declare const _default: {
+  Insight: typeof Insight;
+  clearPersistedChart: typeof clearPersistedChart;
+  getInsights: typeof getInsights;
+  snapshotInsights: typeof snapshotInsights;
+  validateChartData: typeof validateChartData;
+};
+export default _default;