Ripl

A unified API for 2D graphics rendering in the browser with a focus towards...

Canvas
andrewcourtice/riplripl.rocks

README

Ripl


Ripl (pronounced ripple) is a library that provides a unified API for 2D graphics rendering (canvas & SVG) in the browser with a focus towards high performance and interactive data visualization.

Working with the canvas API can be notoriously difficult as it is designed to be very low-level. Alternatively, working with SVG is rather straightforward but not without its flaws. Because these paradigms differ widely in their implementations developers often have to choose one or the other at the outset of a project. Ripl alleviates the issue of choosing between these mediums by exposing a unified API and mimicking the DOM/CSSOM in as many ways possible to make it simple for developers to interact with. Switching between Canvas and SVG is as simple as changing 1 line of code.

Ripl also exposes a number of methods such as scales, geometry, interpolation, color, data joining and easing to assist with drawing (inspired by D3).

Features


- Unified API for drawing to different contexts
- Grouping and property inheritance
- Scene and renderer management
- Event bubbling, delegation and stop propagation (mimics the DOM as much as possible. Capture phase only)
- Powerful element querying (getElementById, getElementsByType, getElementsByClass) including CSS selector style querying via query and queryAll
- Element bounds detection with getBoundingBox
- Automatic interpolation for known property types (ie. can interpolate numbers, points, colors between RGB and Hex etc.)
- Point extrapolation for shape morphing (currently only supports regular polygons)
- High performance async animation including CSS-like keyframe animation support and custom interpolators
- Several built-in shape primitives such as arc, circle, rect, line, polyline, text, ellipse, and polygon
- Hoisted scenegraph to optimize render performance when using scenes. See performance
- Completely modular and tree-shakable. Only ship the features that you use.
- Strictly typed in TypeScript
- Zero runtime dependencies

Currently unsupported features are: gradients, transforms, clipping.

[!IMPORTANT]

Ripl is currently in the early stages of development and, as a result, not yet published to NPM.


Example


Here are a few proof-of-concept data-visualization examples created using Ripl:

Multi-Series Trend Chart (Bar/Line)


- Demo
- Source
  
  trend 1

Donut Chart with Hover Effects


- Demo
- Source
  
  donut

Usage


The following is a tour of Ripl's features starting from the most basic and progressively building towards more advanced concepts.

Render a Basic Element


Here's a basic example of rendering an element.

  1. ```typescript
  2. import {
  3.     createContext,
  4.     createCircle,
  5. } from '@ripl/core';

  7. // Create a context to render the content to
  8. // Ripl uses a canvas context by default
  9. const context = createContext('.mount-element');

  11. // Create an element
  12. const circle = createCircle({
  13.     fillStyle: 'rgb(30, 105, 120)',
  14.     lineWidth: 4,
  15.     cx: context.width / 2,
  16.     cy: context.height / 2,
  17.     radius: context.width / 3
  18. });

  20. // Render the element to the context
  21. circle.render(context);
  22. ```

Ripl has a number of built-in elements such as arc, circle, rect, line, polyline, text, ellipse, and polygon. See here for all available built-in elements.

Modify Element Properties


To modify an element simply change any of it's properties and re-render it.

  1. ```typescript
  2. import {
  3.     createContext,
  4.     createCircle,
  5. } from '@ripl/core';

  7. const context = createContext('.mount-element');
  8. const circle = createCircle({
  9.     fillStyle: 'rgb(30, 105, 120)',
  10.     lineWidth: 4,
  11.     cx: context.width / 2,
  12.     cy: context.height / 2,
  13.     radius: context.width / 3
  14. });

  16. function render() {
  17.     circle.render(context);
  18. }

  20. function update() {
  21.     circle.fillStyle = '#FF0000';
  22.     circle.cx = context.width / 3;
  23.     circle.cy = context.height / 3;

  25.     render();
  26. }
  27. ```