Dropflow is a CSS layout engine created to explore the reaches of the foundational CSS standards (that is: inlines, blocks, floats, positioning and eventually tables, but not flexbox or grid). It has a high quality text layout implementation and is capable of displaying many of the languages of the world. You can use it to generate PDFs or images on the backend with Node and node-canvas or render rich, wrapped text to a canvas in the browser.

Features

Supports over 30 properties including complex ones like float
Bidirectional and RTL text
Hyperscript (h()) API with styles as objects in addition to accepting HTML and CSS
Any OpenType/TrueType buffer can (and must) be registered
JPEG, BMP, PNG, and GIF <img>s supported (backend support may differ)
Font fallbacks at the grapheme level
Colored diacritics
Desirable line breaking (e.g. carries starting padding to the next line)
Optimized shaping
Inherited and cascaded styles are never calculated twice
Handles as many CSS layout edge cases as I can find
Fully typed
Lots of tests
Fast

Supported CSS rules

Following are rules that work or will work soon. Shorthand properties are not listed. If you see all components of a shorthand (for example, border-style, border-width, border-color) then the shorthand is assumed to be supported (for example border).

Inline formatting

Block formatting

<sup>1</sup>Implemented for BFCs but not IFCs yet

Boxes and positioning

Usage

Dropflow works off of a DOM with inherited and calculated styles, the same way that browsers do. You create the DOM with the familiar h() function, and specify styles as plain objects.

import * as flow from 'dropflow';
import {createCanvas} from 'canvas';
import fs from 'node:fs';

// Register fonts before layout. This is a required step.
const roboto1 = new flow.FontFace('Roboto', new URL('file:///Roboto-Regular.ttf'), {weight: 400});
const roboto2 = new flow.FontFace('Roboto', new URL('file:///Roboto-Bold.ttf'), {weight: 700});
flow.fonts.add(roboto1).add(roboto2);

// Always create styles at the top-level of your module if you can.
const divStyle = flow.style({
  backgroundColor: {r: 28, g: 10, b: 0, a: 1},
  textAlign: 'center',
  color: {r: 179, g: 200, b: 144, a: 1}
});

// Since we're creating styles directly, colors are numbers
const spanStyle = flow.style({
  color: {r: 115, g: 169, b: 173, a: 1},
  fontWeight: 700
});

// Create a DOM
const el = flow.dom(
  flow.h('div', {style: divStyle}, [
    'Hello, ',
    flow.h('span', {style: spanStyle}, ['World!'])
  ])
);

// Layout and paint into the entire canvas (see also renderToCanvasContext)
const canvas = createCanvas(250, 50);
await flow.renderToCanvas(el, canvas);

// Save your image
fs.writeFileSync(new URL('file:///hello.png'), canvas.toBuffer());

Hello world against a dark background, with "world" bolded and colored differently

</div>

HTML

This API is only recommended if performance is not a concern, or for learning purposes. Parsing adds extra time (though it is fast thanks to @fb55) and increases bundle size significantly.

import * as flow from 'dropflow';
import parse from 'dropflow/parse.js';
import {createCanvas} from 'canvas';
import fs from 'node:fs';

const roboto1 = new flow.FontFace('Roboto', new URL('file:///Roboto-Regular.ttf'), {weight: 400});
const roboto2 = new flow.FontFace('Roboto', new URL('file:///Roboto-Bold.ttf'), {weight: 700});
flow.fonts.add(roboto1).add(roboto2);

const el = parse(`
  <div style="background-color: #1c0a00; color: #b3c890; text-align: center;">
    Hello, <span style="color: #73a9ad; font-weight: bold;">World!</span>
  </div>
`);

const canvas = createCanvas(250, 50);
flow.renderToCanvas(el, canvas);

canvas.createPNGStream().pipe(fs.createWriteStream(new URL('hello.png', import.meta.url)));

Performance characteristics

Performance is a top goal and is second only to correctness. Run the performance examples in the examples directory to see the numbers for yourself.

8 paragraphs with several inline spans of different fonts can be turned from HTML to image in 9ms on a 2019 MacBook Pro and 13ms on a 2012 MacBook Pro (perf-1.ts)
The Little Prince (over 500 paragraphs) can be turned from HTML to image in under 160ms on a 2019 MacBook Pro and under 250ms on a 2012 MacBook Pro (perf-2.ts)
A 10-letter word can be generated and laid out (not painted) in under 25µs on a 2019 MacBook Pro and under 50µs on a 2012 MacBook Pro (perf-3.ts)

The fastest performance can be achieved by using the hyperscript API, which creates a DOM directly and skips the typical HTML and CSS parsing steps. Take care to re-use style objects to get the most benefits. Reflows at different widths are faster than recreating the layout tree.

API

The first two steps are:

Register fonts
Create a DOM via the Hyperscript or Parse API

Then, you can either render the DOM into a canvas using its size as the viewport:

Render DOM to canvas

Or, you can use the lower-level functions to retain the layout, in case you want to reflow at a different size, choose not to paint (for example if the layout isn't visible) or get intrinsics:

Load dependent resources
Create a layout for the DOM
Reflow the layout
Paint the layout to a target like HTML5 canvas

Fonts

The first step in a dropflow program is to register fonts to be selected by the CSS font properties. Dropflow does not search system fonts, so you must construct a FontFace and add it at least once. The font registration API implements a subset of the CSS Font Loading API and adds one non-standard method, loadSync.

file:/// URLs will load() synchronously

Dropflow

Install / Use

README