@pixxl-tools/canchart

Canvas-only chart core and React wrapper for Pixxl Chart.

@pixxl-tools/canchart owns chart specs, dataset transforms, normalization, scales, layout, geometry, canvas rendering, editing helpers, data exports, selection adapters, examples, and chart-specific CanvasDocument persona helpers. Shared canvas chrome belongs in @pixxl-tools/canvas/react.

Package status: pre-1.0 public package. APIs may change before 1.0.

Quick Start

import { createChartSpec } from "@pixxl-tools/canchart";
import { Chart } from "@pixxl-tools/canchart/react";

const spec = createChartSpec(
  [
    [0, 4],
    [1, 8],
    [2, 6],
  ],
  { mode: "line", title: "Revenue" },
);

export function RevenueChart() {
  return <Chart spec={spec} responsive tooltip interaction />;
}

CanvasDocument integration:

import {
  canvasDocumentToChartSpec,
  chartSpecToCanvasDocument,
} from "@pixxl-tools/canchart/document";

const document = chartSpecToCanvasDocument(spec);
const renderSpec = canvasDocumentToChartSpec(document);

Install/CSS

Install the package with shared canvas and React peers:

pnpm add @pixxl-tools/canchart @pixxl-tools/canvas react

@pixxl-tools/canchart can render directly to canvas without shared CSS. React/product chrome integrations should import shared canvas styles in the host app:

import "@pixxl-tools/canvas/styles.css";

Public API

• @pixxl-tools/canchart: root export for specs, normalization, scales, layout, geometry, renderer, editing, selection, workspace, docs, examples, data helpers, and CanvasDocument persona helpers.
• @pixxl-tools/canchart/react: React chart wrapper.
• @pixxl-tools/canchart/data: data table, CSV, and row helpers.
• @pixxl-tools/canchart/document: chartSpecToCanvasDocument and canvasDocumentToChartSpec.
• @pixxl-tools/canchart/rendering: canvas renderer, geometry, layout, and workspace helpers.
• @pixxl-tools/canchart/interaction: edit target and selection helpers.
• @pixxl-tools/canchart/examples: documented fixtures.

The package currently exposes broad modules from the root for compatibility. New code should treat these as grouped surfaces:

• Spec/model: types, normalize, examples, docs.
• Rendering: layout, geometry, canvas, workspace.
• App integration: react, editing, selection, selectionAdapter.
• Data utilities: data, scales.

Supports

• Canvas 2D renderer only. No SVG rendering path.
• <Chart /> wrapper with responsive canvas, tooltip, pan, zoom, and editable selection.
• Line, point, area, bar, horizontal bar, scatter, bubble, heatmap, candlestick, boxplot, range bar, waterfall, pie, donut, radar, funnel, and gauge.
• Numeric, time, category, log, and symlog axes.
• Mixed charts through per-series type.
• Dataset/encode with filter, sort, groupBy/aggregate, derive, and window transforms.
• Row helpers: createTimeSeriesSpec, createGroupedBarSpec, createPieSpec.
• Grouped and stacked bars, stack groups, stacked areas, thresholds, plot bands, overlay points, data labels, CSV export, and generated chart descriptions.

Model/Persistence

Cross-product storage uses CanvasDocument from @pixxl-tools/canvas. canchart exposes canchart persona helpers from the root export.

Canonical charts are semantic chart elements. Shared rows belong in resources.dataSources; callbacks, DOM nodes, and runtime Date objects are not persisted.

Examples

Runnable examples:

• examples/canchart/quickstart.ts: chart spec, data table, CSV, and CanvasDocument persistence.
• examples/canchart/index.ts: tested chart fixture registry.

Use createChartSpec for quick chart creation. Use @pixxl-tools/canchart/examples for tested fixture specs. Use @pixxl-tools/canchart/react for responsive React canvas.

• canchart/docs/api-reference.md for entrypoint groups.

Source Layout

• src/core: chart specs, types, layout, scales, and normalization.
• src/geometry: chart geometry creation, labels, hit testing, and coordinate mapping.
• src/rendering: Canvas 2D rendering primitives, layers, axes, legends, and renderer entrypoint.
• src/interaction: editing targets, selectable items, selection chrome, and spec paths.
• src/react: React wrapper, resize, canvas render, pointer, and tooltip helpers.
• src/data, src/document, src/examples, src/docs, and src/workspace: focused public adapters and fixtures.

Testing

Relevant checks:

pnpm test

Limits

• Canvas 2D renderer only; no SVG renderer.
• Root export remains broad for compatibility.
• Transformed data targets can be read-only when editing would make semantic transforms ambiguous.

Troubleshooting

• If chart renders empty, verify normalized data rows and active dataSourceRef.
• If editing misses a point/bar/slice, inspect edit targets from @pixxl-tools/canchart/interaction.
• If large data is slow, prefer normalized rows and sampling/decimation helpers before UI-level throttling.

Migration/Versioning

Use new subpaths for new code. Keep root imports working until a separate migration plan can remove broad compatibility exports.