@chartbuddy.io/embed 1.7.52

package/LICENSE

@@ -0,0 +1,56 @@
+ChartBuddy Embed — Proprietary Evaluation License (TEST PUBLISH ONLY)
+
+Copyright (c) ChartBuddy. All rights reserved.
+
+IMPORTANT: This is a temporary evaluation package intended only for short-lived
+testing (including Claude artifact tests). It may be unpublished without notice.
+These terms are intentionally restrictive. Do not rely on this package for any
+production or commercial use.
+
+1. Ownership. This software (the "Software"), including the @chartbuddy.io/embed
+   package and the ChartBuddy editor engine it contains, is the proprietary and
+   confidential property of ChartBuddy. No title to or ownership of the Software
+   is transferred to you.
+
+2. Grant. ChartBuddy grants you a limited, non-exclusive, non-transferable,
+   revocable, royalty-free license to load and run the Software solely for
+   internal evaluation and testing of ChartBuddy's embed integration (including
+   loading it from an npm CDN such as unpkg or jsDelivr inside a test page or
+   Claude artifact). This license automatically terminates when ChartBuddy
+   unpublishes the package, revokes this grant, or ends the evaluation.
+
+3. No other rights. Except for the narrow evaluation grant in §2, you receive
+   NO rights under copyright, patent, trademark, trade secret, or otherwise.
+   Without limiting the foregoing, you may NOT (and nothing in these terms
+   permits you to):
+   (a) use the Software in any production, commercial, client-facing, or
+       end-user application or service;
+   (b) redistribute, republish, resell, sublicense, host, mirror, rent, lease,
+       or otherwise make the Software available to any third party as a
+       standalone file, package, CDN, or hosted service;
+   (c) modify, adapt, translate, or create derivative works of the Software;
+   (d) reverse engineer, decompile, or disassemble the Software except to the
+       extent such restriction is prohibited by law;
+   (e) remove or alter any proprietary notices;
+   (f) use the Software to build, train, benchmark, or operate any product or
+       service that competes with ChartBuddy;
+   (g) claim any affiliation with, endorsement by, or partnership with ChartBuddy
+       based on possession or use of this evaluation package.
+
+4. Third-party components. The Software bundles third-party libraries that are
+   subject to their own license terms, including d3 (ISC), DOMPurify
+   (Apache-2.0 / MPL-2.0), Tippy.js (MIT), and dom-to-image-more (MIT). Your use
+   of those components is governed by their respective licenses. This package
+   does not include Handsontable, HyperFormula, or other spreadsheet components.
+
+5. No warranty; limitation of liability. THE SOFTWARE IS PROVIDED "AS IS",
+   WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. TO THE MAXIMUM EXTENT
+   PERMITTED BY LAW, CHARTBUDDY SHALL NOT BE LIABLE FOR ANY DAMAGES ARISING
+   FROM THE USE OF THE SOFTWARE.
+
+6. Termination. This license terminates immediately upon any breach, upon
+   unpublish of the package, or upon written notice from ChartBuddy. Upon
+   termination you must cease all use and destroy all copies in your control,
+   except copies you are required to retain by law.
+
+For licensing inquiries, contact: legal@chartbuddy.io

package/README.md

@@ -0,0 +1,391 @@
+# ChartBuddy Embed API (`@chartbuddy.io/embed`)
+
+Create ChartBuddy **Insights** in any web page. **Default is view-only** (headless
+draw): hover the top-left ChartBuddy ball for **Download** (PNG), **Export
+config** (JSON), and **Edit** (full interactive editor). Pass `editable: true`
+to open the editor immediately. Spreadsheet is **not** included. No account or
+chart ID required: pass data via `chartData`.
+
+**Public API:** `Insight` (via `new Insight()`), `getInsights`, `snapshotInsights`,
+`clearPersistedChart`, `version`. Agent hook: `window.__CHARTBUDDY_INSIGHTS__`.
+
+> **LLMs / Claude:** every JS entry (package root, `.single.mjs`, multi loader)
+> opens with a comment header naming the exports and a minimal example. Also
+> fetch [`llms.txt`](./llms.txt) or
+> [https://cb-acc.xyz/llms.txt](https://cb-acc.xyz/llms.txt) /
+> [https://cb-acc.xyz/embed/api](https://cb-acc.xyz/embed/api).
+> Package root on unpkg resolves to a readable stub that re-exports the
+> single-file build.
+
+## Claude / strict CSP (recommended)
+
+```js
+import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed';
+// equivalent:
+// import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed/chartbuddy-embed.single.mjs';
+```
+
+```html
+<div id="chart" style="width:960px;height:560px"></div>
+<script type="module">
+  import { Insight } from 'https://unpkg.com/@chartbuddy.io/embed';
+
+  // Default: view-only + ChartBuddy hover ball
+  new Insight('#chart', {
+    instanceId: 'revenue', // stable id for agents + persist
+    persist: false,
+    chartData: {
+      chartType: 'clusteredBar',
+      isDataTransposed: true,
+      seriesData: [
+        ['', 'Q1', 'Q2', 'Q3', 'Q4'],
+        ['Revenue', 100, 112, 125, 140],
+        ['Costs', 60, 66, 70, 78],
+      ],
+      title: { visible: true, text: 'Revenue vs Costs' },
+      subtitle: { visible: false, text: '' },
+    },
+  });
+
+  // Full editor: new Insight('#chart', { editable: true, chartData: … })
+</script>
+```
+
+Do **not** pass `assetBase` on this path. Bundler: `import { Insight } from '@chartbuddy.io/embed'`.
+
+## Install / multi-file (normal websites)
+
+```bash
+npm install @chartbuddy.io/embed
+```
+
+Cache-friendly multi-file loader (siblings OK when CSP allows):
+
+```
+https://unpkg.com/@chartbuddy.io/embed/chartbuddy-embed.mjs
+```
+
+or `import { Insight } from '@chartbuddy.io/embed/multi'`.
+
+### With React
+
+Use the bundled bindings — they handle StrictMode's double mount, patch the live
+chart on data changes instead of remounting, and destroy on unmount.
+
+```jsx
+import { InsightChart } from '@chartbuddy.io/embed/react';
+
+export function ChartEmbed({ chartData }) {
+  return <InsightChart chartData={chartData} style={{ width: '100%', height: 560 }} />;
+}
+```
+
+`react` is an optional peer dependency (React 18 or 19). For imperative access to
+the instance:
+
+```jsx
+import { useInsight } from '@chartbuddy.io/embed/react';
+
+const { ref, insight, ready, error } = useInsight({ chartData, editable: true });
+// <div ref={ref} style={{ height: 400 }} />
+```
+
+`chartData` is compared by identity — memoize it if you build it inline.
+
+### With Vue 3
+
+```vue
+<script setup>
+import { InsightChart } from '@chartbuddy.io/embed/vue';
+</script>
+
+<template>
+  <InsightChart :chart-data="chartData" style="height: 400px" @change="onChange" />
+</template>
+```
+
+`vue` is an optional peer dependency. `useInsight()` is also exported for
+imperative access. Assign a new object to `chartData` to patch the chart —
+mutating in place is not detected.
+
+### With Angular (and Svelte / Solid / plain HTML)
+
+Angular uses the `<chartbuddy-insight>` custom element rather than a compiled
+Angular library, so ChartBuddy upgrades are not tied to your Angular major. No
+peer dependency.
+
+```ts
+import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import '@chartbuddy.io/embed/element';
+
+// template:
+// <chartbuddy-insight [chartData]="cd" instance-id="revenue"
+//                     style="display:block; height:400px"
+//                     (change)="onChange($event)"></chartbuddy-insight>
+```
+
+`chartData` must be set as a **property** (it is an object). Events are
+`CustomEvent`s — read `event.detail`. Full guide:
+<https://cb-acc.xyz/docs/guides/angular.html>
+
+## Usage (script tag / global)
+
+```html
+<script src="https://unpkg.com/@chartbuddy.io/embed/chartbuddy-embed.global.js"></script>
+<script>new ChartBuddyEmbed.Insight('#chart');</script>
+```
+
+Single-file IIFE: `chartbuddy-embed.single.global.js`.
+
+## API
+
+```ts
+new Insight(target: string | HTMLElement, options?: {
+  chartData?: object;   // ChartBuddy chart-data (cd) — see below
+  assetBase?: string;   // multi-file only; ignored by single-file
+  editable?: boolean;   // default false → view mode; true → full editor
+  toolbar?: boolean;    // edit mode only: Reset/Export/Import strip (default false)
+  persist?: boolean;    // per-instance localStorage (default false)
+}): {
+  container: HTMLElement;
+  assetBase: string;
+  instanceId: string;
+  chartContainerId: string;
+  mode: 'view' | 'edit';
+  ready: Promise<void>;
+  chart: any | null;
+  focus(): void;
+  setChartData(cd: object): void;   // partial OK — chartType optional
+  setData(seriesData: any[][]): void;
+  update(patch?: object): void;     // no arg = redraw only
+  getChartData(): object | null;
+  on(event: 'ready' | 'mode' | 'change', handler: Function): () => void;
+  off(event: 'ready' | 'mode' | 'change', handler: Function): void;
+  isDirty(): boolean;
+  getRevision(): number;
+  toPngBlob(options?: { scale?: number; background?: string | null }): Promise<Blob>;
+  toPngBase64(options?: { scale?: number; background?: string | null }): Promise<string>;
+  // Agent helpers default background to #ffffff; downloadPng defaults transparent
+  downloadPng(options?: { scale?: number; background?: string | null }): Promise<void>;
+  dragExport(): Promise<void>;
+  exportConfig(): void;
+  enterEditMode(): Promise<void>;  // view → edit
+  exitEditMode(): Promise<void>;   // edit → view (also ball → Done)
+  destroy(): void;
+};
+
+clearPersistedChart(instanceId?: string): void;
+getInsights(): Record<string, Insight>;
+snapshotInsights(options?: {
+  png?: boolean;
+  scale?: number;
+  background?: string | null;
+}): Promise<{ schemaVersion: 1; version: string; charts: Record<string, any> }>;
+version: string;
+```
+
+### View mode (default)
+
+- Headless chart draw (no formatting toolbar / selection chrome).
+- On hover: ChartBuddy ball (top-left) → **Download** PNG, **Drag to slide**, **Edit**.
+- `enterEditMode()` / ball **Edit** remounts the full editor with the current `chartData`.
+
+### Edit mode (`editable: true`)
+
+- Interactive ChartBuddy editor with formatting UI.
+- Leave via ball **Done** or `exitEditMode()` (returns to view with current config).
+- `toolbar: true` opts into the Reset / Import / Export strip (off by default).
+
+## chartData (`cd`) schema
+
+`options.chartData` is a ChartBuddy **chart-data** object. Partial objects are
+**merged over defaults** (nested `title` / `subtitle` / `legend` / `axes` /
+`canvas` / `footnote` are deep-merged).
+
+### Required
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `chartType` | `string` | See allowed values below |
+| `seriesData` | `array[]` | 2D grid (see layout) |
+
+### Recommended
+
+| Field | Type | Notes |
+|-------|------|--------|
+| `isDataTransposed` | `boolean` | Prefer `true` with the grid layout below |
+| `title` | text block | `{ visible, text }` — `text` may be plain or HTML |
+| `subtitle` | text block | Same shape; set `visible: false` to hide the default subtitle |
+| `footnote` | text block | Same shape |
+| `legend` | object | `{ visible, colors?: string[], … }` — series colors live in `legend.colors` |
+| `backgroundColor` | `string` | Default `"transparent"` |
+| `orientation` | `"vertical" \| "horizontal"` | Default `"vertical"` |
+
+### Allowed `chartType` values
+
+CHARTBUDDY:GENERATED-CHART-TYPES:BEGIN
+`area` · `area100` · `barMekko` · `clusteredBar` · `combo` · `line`
+`mekko` · `pie` · `scatter` · `stackedBar` · `stackedBar100` · `waterfall`
+
+Aliases: `bubble` → `scatter`, `donut` → `pie`.
+
+Beta: `barMekko`.
+CHARTBUDDY:GENERATED-CHART-TYPES:END
+
+### Validation
+
+Chart data is validated at the API boundary — both `new Insight({ chartData })`
+and `setChartData()` / `setData()` / `update()`. Invalid input **throws** with
+the path of every problem, so you get one actionable error instead of a blank
+chart:
+
+```js
+insight.setChartData({ chartType: 'pie', pie: { innerRadiusRatio: 5 } });
+// Error: [chartbuddy/embed] setChartData: invalid chart data — 1 problem:
+//   • pie.innerRadiusRatio: 5 is above the maximum of 1
+```
+
+What is checked: `chartType` (with a did-you-mean hint), field types, enums,
+numeric ranges, the `seriesData` grid (including the per-type row/column minimums
+listed above), and whether an option bag matches the chart type — `bar` options on
+a `pie` chart are rejected. Ragged `seriesData` (unequal row lengths) **warns**
+but does not throw. Duplicate `instanceId` values on the same page **throw**.
+
+Unknown keys are **never** an error, so a config written for a newer version still
+loads. `chart-schema.json` is the machine-readable form of the same rules, usable
+for your own validation or to constrain LLM structured output.
+
+#### Checking without mounting
+
+The same checks are exported. `validateChartData()` never throws and reports
+everything it found, which is what you want when a model authored the config:
+
+```js
+import { validateChartData } from '@chartbuddy.io/embed';
+
+const { valid, errors, warnings } = validateChartData(candidate);
+// errors[0] → {
+//   path: 'chartType',
+//   code: 'unknown-chart-type',
+//   severity: 'error',
+//   message: '"clusterdBar" is not a known chart type. Did you mean "clusteredBar"?',
+//   expected: 'a ChartType or alias',
+//   received: '"clusterdBar"',
+//   allowed: ['area', 'area100', 'barMekko', …],
+//   suggestion: 'clusteredBar',
+// }
+```
+
+`code` and `path` are the stable contract — branch on `code`, repair the value at
+`path`, and never parse `message`. Codes: `not-an-object`, `unknown-chart-type`,
+`empty-patch`, `wrong-type`, `out-of-range`, `not-in-enum`, `series-data-shape`,
+`ragged-series-data` (warning), `foreign-option-bag`.
+
+Throws carry the same objects:
+
+```js
+import { ChartDataValidationError } from '@chartbuddy.io/embed';
+
+try {
+  insight.setChartData(candidate);
+} catch (err) {
+  if (err instanceof ChartDataValidationError) console.log(err.errors);
+}
+```
+
+### Partial updates
+
+```js
+await insight.ready;
+insight.setData([['', 'Q1'], ['Revenue', 120]]);  // data only
+insight.update({ title: { text: 'FY26' } });       // any partial patch
+insight.update();                                  // redraw only
+```
+
+`setChartData` also accepts partials — `chartType` is not required.
+
+### Events
+
+```js
+insight.on('ready', () => { … });
+insight.on('mode', (mode) => { … });          // 'view' | 'edit'
+insight.on('change', (cd) => { … });          // after meaningful edits
+insight.isDirty();                            // true since boot / last Done
+insight.getRevision();                        // monotonic edit counter
+```
+
+### `seriesData` layout (recommended)
+
+With `isDataTransposed: true`, use **chart-native** rows-as-series:
+
+```js
+[
+  ['',        'Q1', 'Q2', 'Q3'],  // row 0: categories ( [0][0] usually "" )
+  ['Revenue', 100,  112,  125],  // each later row = one series
+  ['Costs',    60,   66,   70],
+]
+```
+
+**Pie** (category / value pairs):
+
+```js
+[
+  ['Category', 'Value'],
+  ['North', 45],
+  ['South', 30],
+  ['East', 25],
+]
+```
+
+**Scatter** (transpose not supported):
+
+```js
+[
+  ['', 'Metric X', 'Metric Y', 'Size', 'Group'],
+  ['Point 1', 10, 15, 8, 'A'],
+  ['Point 2', 20, 12, 5, 'B'],
+]
+```
+
+### Minimal example
+
+```js
+{
+  chartType: 'clusteredBar',
+  isDataTransposed: true,
+  seriesData: [
+    ['', 'Q1', 'Q2', 'Q3'],
+    ['Revenue', 100, 112, 125],
+  ],
+  title: { visible: true, text: 'Revenue' },
+  subtitle: { visible: false, text: '' },
+}
+```
+
+### Full config
+
+The richest, safest `cd` is a snapshot from a live editor via
+`insight.getChartData()` (or `insight.exportConfig()`) after `ready`. Pass that JSON back as `chartData`.
+
+Optional advanced fields (present on full exports): `canvas`, `axes`,
+`chartPositionPercentages`, `annotations`, `multilines`, type-specific blocks
+(`bar`, `line`, `area`, `pie`, `waterfall`, `mekko`, `combo`), `seriesLabels`.
+
+## How it works
+
+**Single-file:** d3 + DOMPurify + engine + CSS in one module — use for Claude.
+
+**Multi-file:** small loader pulls siblings (`webapp-entry.js`, vendors, CSS,
+worker). Use on sites you control.
+
+## Notes
+
+- **Multi-mount supported.** Construct `new Insight()` multiple times in one document.
+- **No spreadsheet** in this package.
+- Default view mode has no formatting toolbar; use Edit or `editable: true`.
+- Single-file uses main-thread label placement (no worker/wasm fetch).
+- Requires a browser (`document`, `localStorage`).
+
+## License
+
+Proprietary evaluation license — © ChartBuddy. See the bundled `LICENSE` file.

package/chart-schema.d.ts

@@ -0,0 +1,91 @@
+// GENERATED FILE — DO NOT EDIT.
+// Source of truth: src/ts/domains/chart/schema/{registry,fields}.ts
+// Regenerate: npm run generate-chart-schema
+
+/**
+ * Canonical chart types. The only values valid in a resolved `chartType`.
+ */
+export type ChartType =
+  /** Area Chart — Filled lines showing magnitude over an ordered domain. */
+  | 'area'
+  /** 100% Area Chart — Area chart normalized to 100% to show changing mix. */
+  | 'area100'
+  /** Bar Mekko (beta) — Bars whose width encodes one metric and height another; first data row sets widths. */
+  | 'barMekko'
+  /** Clustered Bar — Side-by-side bars comparing series within each category. */
+  | 'clusteredBar'
+  /** Combo Chart — Mixed bar and line series on shared or dual axes. */
+  | 'combo'
+  /** Line Chart — Trends over an ordered domain, one line per series. */
+  | 'line'
+  /** Marimekko — Variable-width stacked bars where both axes are percentages. */
+  | 'mekko'
+  /** Pie Chart — Share of a single total across categories. */
+  | 'pie'
+  /** Scatter Plot — Points positioned by two metrics, optionally sized and grouped. */
+  | 'scatter'
+  /** Stacked Bar — Bars stacked to show composition and category totals. */
+  | 'stackedBar'
+  /** 100% Stacked Bar — Stacked bars normalized to 100% to compare mix, not size. */
+  | 'stackedBar100'
+  /** Waterfall — Running total showing how contributions bridge two values. */
+  | 'waterfall';
+
+/**
+ * Accepted input aliases, normalized to a canonical type on the way in.
+ */
+export type ChartTypeAlias =
+  /** Alias for `scatter`. */
+  | 'bubble'
+  /** Alias for `pie`. */
+  | 'donut';
+
+/** Anything accepted as `chartType` input. */
+export type ChartTypeInput = ChartType | ChartTypeAlias;
+
+/** Which `chartData.<key>` option bag each chart type reads. */
+export interface ChartTypeOptionBag {
+  area: 'area';
+  area100: 'area';
+  barMekko: 'barMekko';
+  clusteredBar: 'bar';
+  combo: 'combo';
+  line: 'line';
+  mekko: 'mekko';
+  pie: 'pie';
+  scatter: 'scatter';
+  stackedBar: 'bar';
+  stackedBar100: 'bar';
+  waterfall: 'waterfall';
+}
+
+/**
+ * Required `seriesData` layout per chart type.
+ *
+ * - `area`: row 0 is the category header; each later row is one series
+ * - `area100`: row 0 is the category header; each later row is one series
+ * - `barMekko`: row 1 sizes the bars (never drawn); rows 2+ are stacked height segments
+ * - `clusteredBar`: row 0 is the category header; each later row is one series
+ * - `combo`: row 0 is the category header; each later row is one series
+ * - `line`: row 0 is the category header; each later row is one series
+ * - `mekko`: row 0 is the category header; each later row is one series
+ * - `pie`: two columns per row: [Category, Value]
+ * - `scatter`: row 0 names the metrics; each later row is one point
+ * - `stackedBar`: row 0 is the category header; each later row is one series
+ * - `stackedBar100`: row 0 is the category header; each later row is one series
+ * - `waterfall`: row 0 is the category header; each later row is one series
+ */
+export interface ChartTypeSeriesLayout {
+  area: 'seriesRows';
+  area100: 'seriesRows';
+  barMekko: 'widthRowThenHeightRows';
+  clusteredBar: 'seriesRows';
+  combo: 'seriesRows';
+  line: 'seriesRows';
+  mekko: 'seriesRows';
+  pie: 'categoryValue';
+  scatter: 'pointRows';
+  stackedBar: 'seriesRows';
+  stackedBar100: 'seriesRows';
+  waterfall: 'seriesRows';
+}