Documentation / @ripl/core

@ripl/core

Core rendering library for Ripl — a unified API for 2D graphics rendering (Canvas & SVG) in the browser.

Installation

npm install @ripl/core

Features

• Unified rendering API — One API surface for both Canvas and SVG contexts
• Built-in elements — Arc, circle, rect, line, polyline, polygon, ellipse, path, text, and image
• Scene management — Scenegraph with grouping, property inheritance, and element querying
• Animation — High-performance async transitions with CSS-like keyframe support and custom interpolators
• Event system — Event bubbling, delegation, and stop propagation (mimics the DOM)
• Scales — Continuous, discrete, and time scales for data mapping
• Color — Color parsing, interpolation, and conversion (RGB, HSL, Hex)
• Math — Geometry utilities, vector operations, and easing functions
• Zero dependencies — Fully self-contained
• Tree-shakable — Only ship what you use

Usage

import {
    createCircle,
    createContext,
    createRenderer,
    createScene,
} from '@ripl/web';

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

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

const scene = createScene({
    children: [circle],
});

const renderer = createRenderer(scene, {
    autoStart: true,
    autoStop: true,
});

await renderer.transition(circle, {
    duration: 1000,
    state: {
        radius: 100,
        fill: '#FF0000',
    },
});

Switching to SVG

Replace the createContext import with @ripl/svg — everything else stays the same:

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

Documentation

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

License

MIT

Namespaces

Namespace	Description
interpolateAny	Fallback interpolator factory that snaps from the first value to the second at the halfway point.
interpolateBorderRadius	Interpolator factory that transitions between two border-radius values (single number or four-corner tuple).
interpolateColor	Interpolator factory that smoothly transitions between two CSS color strings by interpolating their RGBA channels.
interpolateDate	Interpolator factory that interpolates between two Date instances by lerping their timestamps.
interpolateGradient	Interpolator factory that transitions between two CSS gradient strings by interpolating their stops, angles, and positions.
interpolateNumber	Interpolator factory that linearly interpolates between two numbers.
interpolatePoints	Interpolator factory that transitions between two point arrays, extrapolating additional points where set lengths differ.
interpolateRotation	Interpolator factory that transitions between two rotation values (numbers in radians or strings like "90deg").
interpolateTransformOrigin	Interpolator factory that transitions between two transform-origin values (numbers or percentage strings).

Classes

Class	Description
Arc	An arc or annular sector shape supporting inner radius and pad angle.
Box	An axis-aligned bounding box defined by its four edges.
Circle	A circle shape rendered at a center point with a given radius.
ColorParseError	Error thrown when a color string cannot be parsed in the expected format.
Context	Abstract rendering context providing a unified API for Canvas and SVG, with state management and coordinate scaling.
ContextPath	A virtual path element used to record drawing commands; subclassed by Canvas and SVG implementations.
ContextText	A virtual text element capturing position, content, and optional path-based text layout.
Disposer	Abstract base class that manages disposable resources, supporting keyed retention and bulk disposal.
Element	The base renderable element with state management, event handling, interpolation, transform support, and context rendering.
Ellipse	An ellipse shape rendered at a center point with separate x/y radii, rotation, and angle range.
Event	An event object carrying type, data, target reference, and propagation control.
EventBus	A typed pub/sub event system with parent-chain bubbling, disposable subscriptions, and self-filtering.
Group	A container element that manages child elements, providing scenegraph traversal, CSS-like querying, and composite bounding boxes.
ImageElement	An image element that draws a CanvasImageSource at a given position and optional size.
Line	A straight line segment between two points.
Path	A general-purpose shape rendered by a user-supplied path renderer callback.
Polygon	A regular polygon shape with a configurable number of sides.
Polyline	A multi-point line shape supporting various curve interpolation algorithms.
Rect	A rectangle shape with optional rounded corners via border radius.
Renderer	Drives the animation loop via requestAnimationFrame, managing per-element transitions and rendering the scene each frame.
Scene	The top-level group bound to a rendering context, maintaining a hoisted flat buffer for O(n) rendering.
Shape	Abstract base class for renderable shapes, extending Element with a type-constrained constructor.
Shape2D	A concrete 2D shape with path management, automatic fill/stroke rendering, clipping support, and path-based hit testing.
Task	A cancellable promise with AbortController integration, supporting abort callbacks and chaining.
TaskAbortError	Error thrown when a task is aborted, carrying the abort reason.
Text	A text element that renders string or numeric content, with optional path-based text layout.
Transition	A Task-based animation that drives a callback over time with easing, looping, and abort support.

Interfaces

Interface	Description
ArcState	State interface for an arc element, defining center, angles, radii, pad angle, and border radius.
BandScale	A band scale that divides a continuous range into uniform bands for categorical data, exposing bandwidth and step.
BaseState	The full set of visual state properties inherited by every renderable element.
CircleState	State interface for a circle element, defining center coordinates and radius.
ColorParser	A color parser that can test, parse, and serialise a specific color format.
ConicGradient	A parsed conic gradient with angle, position, color stops, and optional repeating flag.
ContextElement	Minimal interface for context-level elements (paths, text) identified by a unique id.
ContextEventMap	Event map for a rendering context, including resize and pointer events.
ContextOptions	Options for constructing a rendering context.
DivergingScaleOptions	Options for a diverging scale, adding a midpoint to the base linear scale options.
ElementEventMap	Event map for elements, extending the base event map with lifecycle and interaction events.
ElementValidationResult	The result of validating an element, with a severity type and descriptive message.
EllipseState	State interface for an ellipse element, defining center, radii, rotation, and angle range.
FactoryOptions	Platform-specific function implementations injected at runtime.
GradientColorStop	A single color stop within a gradient, consisting of a CSS color and an optional offset position.
GroupOptions	Options for constructing a group, extending element options with an optional initial set of children.
ImageState	State interface for an image element, defining position, optional size, and image source.
LinearGradient	A parsed linear gradient with angle, color stops, and optional repeating flag.
LinearScaleOptions	Options shared by linear-based scales (continuous, logarithmic, power, etc.).
LineState	State interface for a line element, defining start and end coordinates.
LogarithmicScaleOptions	Options for a logarithmic scale, adding a configurable base to the base linear scale options.
PathState	State interface for a path element, defining bounding position and dimensions.
PolygonState	State interface for a regular polygon element, defining center, radius, and number of sides.
PolylineState	State interface for a polyline element, defining points and an optional curve renderer.
PowerScaleOptions	Options for a power scale, adding a configurable exponent to the base linear scale options.
RadialGradient	A parsed radial gradient with shape, position, color stops, and optional repeating flag.
RectState	State interface for a rectangle element, defining position, dimensions, and optional border radius.
RenderElement	Minimal interface for any element that can be rendered and hit-tested by a context.
RenderElementIntersectionOptions	Options for render element intersection testing.
RendererDebugOptions	Options for enabling debug overlays on the renderer.
RendererEventMap	Event map for the renderer, with start, stop, and per-frame tick events.
RendererOptions	Configuration for the renderer, controlling auto-start/stop behaviour and debug overlays.
RendererTransition	Internal representation of an active transition managed by the renderer.
RendererTransitionOptions	Options for scheduling a transition on one or more elements via the renderer.
Scale	A callable scale with domain, range, inverse mapping, tick generation, and inclusion testing.
ScaleBindingOptions	Low-level options for constructing a scale, providing conversion, inversion, inclusion, and tick generation callbacks.
SceneEventMap	Event map for the scene, adding a resize event to the standard element events.
SceneOptions	Options for constructing a scene, extending group options with an optional auto-render-on-resize flag.
StringInterpolatorTag	A tagged template result capturing the static fragments and dynamic numeric arguments.
TextState	State interface for a text element, defining position, content, and optional path-based text layout.
TransitionOptions	Configuration for a transition animation.

Type Aliases

Type Alias	Description
BandScaleOptions	-
BaseElementState	Base state interface for all elements. All visual properties are optional at the element level.
BorderRadius	Four-corner border radius represented as [topLeft, topRight, bottomRight, bottomLeft].
ColorHSL	An HSL color represented as a three-element tuple.
ColorHSLA	An HSLA color represented as a four-element tuple.
ColorHSV	An HSV color represented as a three-element tuple.
ColorHSVA	An HSVA color represented as a four-element tuple.
ColorRGBA	An RGBA color represented as a four-element tuple of channel values.
ColorSpace	Supported color space identifiers.
Direction	Text direction for the rendering context.
Ease	An easing function that maps a linear progress value (0–1) to an eased output value.
ElementInterpolationKeyFrame	A single keyframe in a multi-step interpolation, with an optional offset (0–1) and a target value.
ElementInterpolationState	Partial state where each property can be a target value, keyframe array, or interpolator function.
ElementInterpolationStateValue	An interpolation target: a direct value, an array of keyframes, or a custom interpolator function.
ElementInterpolators	A map of interpolator factories keyed by state property, used to override default interpolation behaviour.
ElementIntersectionOptions	Options for element intersection (hit) testing.
ElementOptions	Options for constructing an element, combining an optional id, CSS classes, data, pointer events, and initial state.
ElementPointerEvents	Controls which pointer events an element responds to during hit testing.
ElementValidationType	Severity level of an element validation result.
EventHandler	A callable event handler function with optional subscription options.
EventMap	Base event map interface; all custom event maps should extend this.
EventOptions	Options for emitting an event, controlling bubbling and attached data.
EventSubscriptionOptions	Options for subscribing to an event, such as filtering to self-targeted events only.
FillRule	Fill rule algorithm used to determine if a point is inside a path.
FontKerning	Font kerning mode for the rendering context.
Gradient	Union of all supported gradient types.
GradientType	-
Interpolator	A function that interpolates between two values based on a normalised position (0–1).
InterpolatorFactory	A factory that creates an interpolator between two values of the same type, with a test predicate for type matching.
LineCap	Line cap style for stroke endpoints.
LineJoin	Line join style for stroke corners.
MeasureTextOptions	Options for measuring text dimensions.
PathPoint	A sampled point on an SVG path with position and tangent angle.
PathRenderer	A callback that draws custom geometry onto a ContextPath using the element's state.
Point	A 2D point represented as an [x, y] tuple.
PolylineRenderer	Built-in polyline curve interpolation algorithm names.
PolylineRenderFunc	A function that renders a polyline curve onto a path from an array of points.
PredicatedFunction	A callable with a test method used to determine whether the factory can handle a given value.
RenderElementPointerEvents	Controls which pointer events a render element responds to during hit testing.
RendererTransitionDirection	Alias for the transition playback direction within the renderer.
RendererTransitionOptionsArg	Transition options can be a static object or a per-element factory function.
Rotation	Rotation value — a numeric radian value or a string with deg/rad suffix.
ScaleMethod	A function that maps a value from one space to another.
Shape2DOptions	Options for a 2D shape, adding automatic fill/stroke and clipping controls.
StringInterpolationFormatter	Optional formatter applied to each interpolated numeric value before insertion into the output string.
StringInterpolationSet	A pair of tagged template results representing the start and end states for string interpolation.
TaskAbortCallback	Callback invoked when a task is aborted, receiving the abort reason.
TaskExecutor	Executor function for a task, providing resolve, reject, abort registration, and the underlying AbortController.
TaskReject	Callback to reject a task with an optional reason.
TaskResolve	Callback to resolve a task with a value or promise.
TextAlignment	Horizontal text alignment relative to the drawing position.
TextBaseline	Vertical text baseline used when rendering text.
TextOptions	Options for creating a text element within the context.
TransformOrigin	Transform origin value — a numeric pixel offset or a percentage string.
TransitionCallback	Callback invoked on each animation frame with the current eased time value (0–1).
TransitionDirection	The playback direction of a transition.
TransitionLoopMode	Controls whether a transition loops: true restarts from the beginning, 'alternate' ping-pongs direction each iteration.

Variables

Variable	Description
CONTEXT_OPERATIONS	Maps element state properties to their corresponding context setter functions.
easeInCubic	Cubic ease-in — accelerates from zero velocity.
easeInOutCubic	Cubic ease-in-out — accelerates then decelerates.
easeInOutQuad	Quadratic ease-in-out — accelerates then decelerates.
easeInOutQuart	Quartic ease-in-out — accelerates then decelerates.
easeInOutQuint	Quintic ease-in-out — accelerates then decelerates.
easeInQuad	Quadratic ease-in — accelerates from zero velocity.
easeInQuart	Quartic ease-in — accelerates from zero velocity.
easeInQuint	Quintic ease-in — accelerates from zero velocity.
easeLinear	Linear easing — no acceleration or deceleration.
easeOutCubic	Cubic ease-out — decelerates to zero velocity.
easeOutQuad	Quadratic ease-out — decelerates to zero velocity.
easeOutQuart	Quartic ease-out — decelerates to zero velocity.
easeOutQuint	Quintic ease-out — decelerates to zero velocity.
factory	Global platform factory instance. Call factory.set(...) to provide environment-specific implementations.
interpolateAny	Fallback interpolator factory that snaps from the first value to the second at the halfway point.
interpolateBorderRadius	Interpolator factory that transitions between two border-radius values (single number or four-corner tuple).
interpolateColor	Interpolator factory that smoothly transitions between two CSS color strings by interpolating their RGBA channels.
interpolateDate	Interpolator factory that interpolates between two Date instances by lerping their timestamps.
interpolateGradient	Interpolator factory that transitions between two CSS gradient strings by interpolating their stops, angles, and positions.
interpolateImage	Interpolator factory that cross-fades between two image sources using an offscreen canvas.
interpolateNumber	Interpolator factory that linearly interpolates between two numbers.
interpolatePoints	Interpolator factory that transitions between two point arrays, extrapolating additional points where set lengths differ.
interpolateRotation	Interpolator factory that transitions between two rotation values (numbers in radians or strings like "90deg").
interpolateTransformOrigin	Interpolator factory that transitions between two transform-origin values (numbers or percentage strings).
TAU	Full circle in radians (2π).
TRACKED_EVENTS	DOM event types that are tracked and forwarded to elements for hit testing and interaction.
TRANSFORM_DEFAULTS	Default numeric values for transform properties (translate, scale, rotation, transform-origin).
TRANSFORM_INTERPOLATORS	Interpolator factories for transform-related properties that require special interpolation (rotation, transform-origin).

Functions

Function	Description
arePointsEqual	Tests whether two points have identical coordinates.
clamp	Constrains a value to the inclusive range between lower and upper bounds.
computeTransitionTime	Computes the eased time value for a transition given elapsed time, duration, easing function, and direction.
createArc	Factory function that creates a new Arc instance.
createCircle	Factory function that creates a new Circle instance.
createElement	Factory function that creates a new Element instance.
createEllipse	Factory function that creates a new Ellipse instance.
createFrameBuffer	Creates a debounced requestAnimationFrame wrapper that cancels any pending frame before scheduling a new one.
createGroup	Factory function that creates a new Group instance.
createImage	Factory function that creates a new ImageElement instance.
createLine	Factory function that creates a new Line instance.
createNumericIncludesMethod	Creates an includes predicate that tests whether a value falls within the numeric domain.
createPath	Factory function that creates a new Path instance.
createPolygon	Factory function that creates a new Polygon instance.
createPolyline	Factory function that creates a new Polyline instance.
createRect	Factory function that creates a new Rect instance.
createRenderer	Factory function that creates a new Renderer bound to the given scene.
createScale	Assembles a Scale object from explicit conversion, inversion, and tick functions.
createScene	Factory function that creates a new Scene instance from a context, selector, or element.
createShape	Factory function that creates a new Shape2D instance.
createText	Factory function that creates a new Text instance.
degreesToRadians	Converts degrees to radians.
elementIsArc	Type guard that checks whether a value is an Arc instance.
elementIsCircle	Type guard that checks whether a value is a Circle instance.
elementIsEllipse	Type guard that checks whether a value is an Ellipse instance.
elementIsImage	Type guard that checks whether a value is an ImageElement instance.
elementIsLine	Type guard that checks whether a value is a Line instance.
elementIsPath	Type guard that checks whether a value is a Path instance.
elementIsPolygon	Type guard that checks whether a value is a Polygon instance.
elementIsPolyline	Type guard that checks whether a value is a Polyline instance.
elementIsRect	Type guard that checks whether a value is a Rect instance.
elementIsShape	Type guard that checks whether a value is a Shape instance.
elementIsText	Type guard that checks whether a value is a Text instance.
fractional	Returns the fractional part of a number (e.g. fractional(3.7) → 0.7).
getColorParser	Finds the first color parser whose pattern matches the given color string.
getContainingBox	Computes the smallest axis-aligned bounding box that contains all boxes extracted from the array.
getEuclideanDistance	Computes the Euclidean distance from two points.
getExtent	Computes the [min, max] extent of an array using the given numeric accessor.
getLinearScaleMethod	Creates a linear mapping function from a numeric domain to a numeric range, with optional clamping and tick-padding.
getLinearTicks	Generates an array of evenly spaced, "nice" tick values across the domain.
getMidpoint	Returns the midpoint between two points.
getPathLength	Computes the total length of an SVG path from its d attribute string.
getPolygonPoints	Generates the vertex points of a regular polygon centred at (cx, cy) with the given radius and number of sides.
getThetaPoint	Returns the point at a given angle and distance from an optional centre.
getTotal	Sums all numeric values extracted from an array via the accessor.
getWaypoint	Returns a point along the line segment between two points at the given normalised position (0–1).
hslToRGBA	Converts HSLA values to an RGBA tuple.
hsvToRGBA	Converts HSVA values to an RGBA tuple.
interpolateCirclePoint	Creates an interpolator that traces a point around a circle of the given centre and radius.
interpolatePath	Creates an interpolator that progressively reveals a path from start to end as position advances from 0 to 1.
interpolatePolygonPoint	Creates an interpolator that traces a point around the vertices of a regular polygon.
interpolateString	Creates a string interpolator by interpolating between numeric values embedded in tagged template literals.
interpolateWaypoint	Creates an interpolator that returns the point along a polyline at the given normalised position.
isGradientString	Tests whether a string looks like a CSS gradient (starts with a recognised gradient function name).
isGroup	Type guard that checks whether a value is a Group instance.
isPointInBox	Tests whether a point lies within the given bounding box (inclusive).
max	Returns the maximum of the provided numbers.
maxOf	Returns the maximum numeric value extracted from an array via the accessor.
measureText	Measures the dimensions of a text string using an optional font and context override.
min	Returns the minimum of the provided numbers.
minOf	Returns the minimum numeric value extracted from an array via the accessor.
normaliseBorderRadius	Normalises a border radius value into a four-corner tuple, expanding a single number to all corners.
padDomain	Expands a numeric domain to "nice" tick-aligned boundaries and returns [min, max, step].
parseColor	Parses any supported color string into an RGBA tuple, or returns undefined if no parser matches.
parseGradient	Parses a CSS gradient string (linear, radial, or conic) into a structured Gradient object, or returns undefined if the string is not a recognised gradient.
parseHEX	Parses a hexadecimal color string (e.g. #ff0000 or #ff000080) into an RGBA tuple.
parseHSL	Parses an hsl() color string into an RGBA tuple.
parseHSLA	Parses an hsla() color string into an RGBA tuple.
parseHSV	Parses an hsv() color string into an RGBA tuple.
parseHSVA	Parses an hsva() color string into an RGBA tuple.
parseRGB	Parses an rgb() color string into an RGBA tuple with alpha set to 1.
parseRGBA	Parses an rgba() color string into an RGBA tuple.
polylineBasisRenderer	Creates a cubic B-spline polyline renderer.
polylineBumpXRenderer	Creates a bump-X polyline renderer using horizontal midpoint bezier curves.
polylineBumpYRenderer	Creates a bump-Y polyline renderer using vertical midpoint bezier curves.
polylineCardinalRenderer	Creates a cardinal spline polyline renderer with configurable tension.
polylineCatmullRomRenderer	Creates a Catmull-Rom spline polyline renderer with configurable alpha.
polylineLinearRenderer	Creates a linear (straight segment) polyline renderer.
polylineMonotoneXRenderer	Creates a monotone-X polyline renderer preserving monotonicity along the x-axis.
polylineMonotoneYRenderer	Creates a monotone-Y polyline renderer preserving monotonicity along the y-axis.
polylineNaturalRenderer	Creates a natural cubic spline polyline renderer with second-derivative continuity.
polylineSplineRenderer	Creates a spline polyline renderer with configurable tension.
polylineStepAfterRenderer	Creates a step-after polyline renderer where the vertical transition occurs at the end of each segment.
polylineStepBeforeRenderer	Creates a step-before polyline renderer where the vertical transition occurs at the start of each segment.
polylineStepRenderer	Creates a step polyline renderer with midpoint horizontal transitions.
query	Returns the first element matching a CSS-like selector, or undefined if none match.
queryAll	Queries all elements matching a CSS-like selector across the given element(s) and their descendants.
radiansToDegrees	Converts radians to degrees.
resolveRotation	Resolves a rotation value (number, degrees string, or radians string) to radians.
resolveTransformOrigin	Resolves a transform-origin value (number or percentage string) to a pixel offset relative to the given dimension.
rgbaToHSL	Converts RGBA channel values to an HSLA tuple.
rgbaToHSV	Converts RGBA channel values to an HSVA tuple.
rgbChannelToHEX	Converts a single RGB channel value (0–255) to a two-character hexadecimal string.
samplePathPoint	Samples a point and tangent angle at the given distance along an SVG path.
scaleBand	Creates a band scale that maps discrete domain values to evenly spaced bands within the range.
scaleContinuous	Creates a continuous linear scale that maps a numeric domain to a numeric range.
scaleDiscrete	Creates a discrete (ordinal) scale that maps domain values to corresponding range values by index.
scaleDiverging	Creates a diverging scale that maps values below and above a midpoint to separate sub-ranges.
scaleLog	-
scaleLogarithmic	Creates a logarithmic scale that maps a numeric domain to a range using a log transformation.
scalePower	Creates a power scale that maps a numeric domain to a range using an exponential transformation.
scaleQuantile	Creates a quantile scale that divides a sorted numeric domain into quantiles mapped to discrete range values.
scaleQuantize	Creates a quantize scale that divides a continuous numeric domain into uniform segments mapped to discrete range values.
scaleSqrt	Shortcut for a power scale with exponent 0.5 (square root).
scaleThreshold	Creates a threshold scale that maps numeric values to range values based on a set of threshold breakpoints.
scaleTime	Creates a time scale that maps a Date domain to a numeric range using linear interpolation of timestamps.
serialiseGradient	Serialises a structured Gradient object back into a CSS gradient string.
serialiseHEX	Serialises RGBA channel values into a hexadecimal color string (e.g. #ff0000).
serialiseHSL	Serialises RGBA channel values into an hsl() color string.
serialiseHSLA	Serialises RGBA channel values into an hsla() color string.
serialiseHSV	Serialises RGBA channel values into an hsv() color string.
serialiseHSVA	Serialises RGBA channel values into an hsva() color string.
serialiseRGB	Serialises RGBA channel values into an rgb() color string.
serialiseRGBA	Serialises RGBA channel values into an rgba() color string.
setColorAlpha	Returns a new color string with the alpha channel replaced by the given value.
transition	Creates and starts a frame-driven transition that invokes the callback with the eased time on each animation frame.
typeIsContext	Type guard that checks whether a value is a Context instance.
typeIsElement	Type guard that checks whether a value is an Element instance.
typeIsPoint	Type guard that checks whether a value is a Point (a two-element array).