Documentation / @ripl/canvas

@ripl/canvas

Canvas 2D rendering context for Ripl — a unified API for drawing 2D graphics and data visualizations in the browser.

Installation

npm install @ripl/canvas

Most browser projects should install @ripl/web instead, which re-exports the core library together with this Canvas context and the browser platform bindings.

Overview

@ripl/canvas implements Ripl's Context abstraction on top of the native CanvasRenderingContext2D. Because every Ripl element renders through the shared Context API, the same drawing code runs unchanged on Canvas, SVG, or the Terminal.

Usage

import {
    createContext,
} from '@ripl/canvas';

import {
    createCircle,
} from '@ripl/core';

const context = createContext('.mount-element');

createCircle({
    fill: 'rgb(30, 105, 120)',
    cx: context.width / 2,
    cy: context.height / 2,
    radius: 50,
}).render(context);

Exporting

Every context can snapshot its current output via export():

const url = context.export().toURL(); // PNG object URL
const dataUrl = context.export().toString(); // PNG data URL
const image = await context.export().toImage(); // ImageData

Documentation

Full documentation and interactive demos are available at ripl.run.

License

MIT

Classes

Class	Description
CanvasContext	Canvas 2D rendering context implementation, mapping the unified API to CanvasRenderingContext2D.
CanvasPath	Canvas-specific path implementation backed by a native Path2D object.

Interfaces

Interface	Description
RescaleResult	Result of a canvas rescale operation containing the updated coordinate scales.

Type Aliases

Type Alias	Description
GradientBounds	Bounding rectangle used to resolve gradient coordinates.

Functions

Function	Description
applyCanvasFill	Fills a canvas path or text element, dispatching text-along-path when applicable.
applyCanvasStroke	Strokes a canvas path or text element, dispatching text-along-path when applicable.
canvasDrawImage	Draws an image onto a canvas context with optional width and height.
canvasIsPointInPath	Tests whether a point is inside the filled region of a canvas path.
canvasIsPointInStroke	Tests whether a point is on the stroked outline of a canvas path.
canvasMeasureText	Measures text dimensions using an optional font override.
createContext	Creates a Canvas 2D rendering context (a concrete Context) attached to the given DOM target.
getCanvasGradientBounds	Resolves gradient bounds from a bounding box or falls back to context dimensions.
renderTextAlongPath	Renders text character-by-character along a path using fill or stroke.
rescaleCanvas	Rescales a canvas element for the device pixel ratio and returns updated coordinate scales. Returns undefined if no rescale was needed.
setCanvasFill	Sets the fill style on a native canvas context, resolving gradient strings when applicable.
setCanvasStroke	Sets the stroke style on a native canvas context, resolving gradient strings when applicable.
toCanvasGradient	Converts a parsed gradient definition into a native CanvasGradient within the given bounds.