Domphy

ChartEngine API

ChartEngine is the low-level class that chart() patch wraps. Use it directly when you need manual lifecycle control, resize observers, or multi-chart orchestration.

Basic usage

import { ChartEngine } from "@domphy/chart"
import type { ChartOption } from "@domphy/chart"

const container = document.getElementById("chart")!
container.style.position = "relative"

const engine = new ChartEngine(container)
await engine.init()

engine.setSize(600, 300)
engine.setOption({
  xAxis: { type: "category", data: ["A", "B", "C"] },
  yAxis: { type: "value" },
  series: [{ type: "bar", data: [10, 20, 15] }],
})

API reference

new ChartEngine(container)

Creates a chart engine bound to container. Does not start WebGL until init() is called.

const engine = new ChartEngine(container: HTMLElement)

engine.init()

Initializes the WebGL context, creates the canvas and SVG overlay layers. Returns a Promise<void>.

await engine.init()

Must be called before setSize() or setOption().

engine.setSize(width, height)

Sets the chart dimensions in pixels and resizes all internal layers.

engine.setSize(width: number, height: number): void

Call this after init() and whenever the container size changes.

engine.setOption(option)

Updates the chart with a new option object. Performs a full re-render.

engine.setOption(option: ChartOption): void

Subsequent calls replace the previous option entirely.

engine.destroy()

Tears down the WebGL context, removes all DOM elements, and releases memory.

engine.destroy(): void

Always call this when the chart is removed from the DOM.

With ResizeObserver

const engine = new ChartEngine(container)
await engine.init()

const observer = new ResizeObserver(([entry]) => {
  const { width, height } = entry.contentRect
  engine.setSize(width, height)
})
observer.observe(container)

engine.setOption(option)

// Cleanup:
observer.disconnect()
engine.destroy()

With Domphy lifecycle

Manual embedding inside _onMount / _onRemove:

import { ChartEngine } from "@domphy/chart"

const MyChart: DomphyElement<"div"> = {
  div: null,
  style: { width: "100%", height: "300px", position: "relative" },
  _onMount: async (node) => {
    const engine = new ChartEngine(node.domElement as HTMLElement)
    await engine.init()
    const { width, height } = node.domElement!.getBoundingClientRect()
    engine.setSize(width || 600, height || 300)
    engine.setOption({ series: [{ type: "line", data: [1, 2, 3] }] })
    node.setMetadata("engine", engine)
  },
  _onRemove: (node) => {
    (node.getMetadata("engine") as ChartEngine | undefined)?.destroy()
  },
}

Scale utilities

import {
  createLinearScale,
  createOrdinalScale,
  createTimeScale,
  createLogScale,
} from "@domphy/chart"

const scale = createLinearScale([0, 100], [0, 400])
scale(50)  // → 200

const ordinal = createOrdinalScale(["A", "B", "C"], [0, 300])
ordinal("B")  // → 150

These are lower-level utilities used internally by the chart engine, exposed for custom rendering or annotation overlays.