Skip to content

Latest commit

 

History

History
504 lines (352 loc) · 21.7 KB

README.md

File metadata and controls

504 lines (352 loc) · 21.7 KB
Raw

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
  • 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

Property Values Status
color rgba(), rgb(), #rrggbb, #rgb, #rgba ✅‍ Works
direction ltr, rtl ✅‍ Works
font-‍family ✅‍ Works
font-‍size em, px, smaller etc, small etc, cm etc ✅‍ Works
font-‍stretch condensed etc ✅‍ Works
font-‍style normal, italic, oblique ✅‍ Works
font-‍variant 🚧‍ Planned
font-‍weight normal, bolder, lighter light, bold, 100-900 ✅‍ Works
letter-‍spacing 🚧‍ Planned
line-‍height normal, px, em, %, number ✅‍ Works
tab-‍size 🚧‍ Planned
text-‍align start, end, left, right, center ✅‍ Works
text-‍decoration 🚧‍ Planned
unicode-‍bidi 🚧‍ Planned
vertical-‍align baseline, middle, sub, super, text-top, text-bottom, %, px etc, top, bottom ✅‍ Works
white-‍space normal, nowrap, pre, pre-wrap, pre-line ✅‍ Works
word-‍break
overflow-‍wrap,word-‍wrap		 break-word, normal
anywhere, normal		 ✅‍ Works

Block formatting

Property Values Status
clear left, right, both, none ✅‍ Works
float left, right, none ✅‍ Works
writing-‍mode horizontal-tb, vertical-lr, vertical-rl 🏗 Partially done1

1Implemented for BFCs but not IFCs yet

Boxes and positioning

Property Values Status
background-‍clip border-box, content-box, padding-box ✅‍ Works
background-‍color rgba(), rgb(), #rrggbb, #rgb, #rgba ✅‍ Works
border-‍color rgba(), rgb(), #rrggbb, #rgb, #rgba ✅‍ Works
border-‍style solid, none ✅‍ Works
border-‍width em, px, cm etc ✅‍ Works
top, right, bottom, left em, px, %, cm etc ✅‍ Works
box-‍sizing border-box, content-box ✅‍ Works
display block ✅‍ Works
display inline ✅‍ Works
display inline-block ✅‍ Works
display flow-root ✅‍ Works
display none ✅‍ Works
display table 🚧‍ Planned
height em, px, %, cm etc, auto ✅‍ Works
margin em, px, %, cm etc, auto ✅‍ Works
max-height, max-width,
min-height, min-width		 em, px, %, cm etc, auto 🚧‍ Planned
padding em, px, %, cm etc ✅‍ Works
position absolute 🚧‍ Planned
position fixed 🚧‍ Planned
position relative ✅‍ Works
transform 🚧‍ Planned
overflow hidden, visible ✅‍ Works
width em, px, %, cm etc, auto ✅‍ Works
z-index number, auto ✅‍ Works
zoom number, % ✅‍ Works

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.
// It is only async when you don't pass an ArrayBuffer
await flow.registerFont(new URL('fonts/Roboto-Regular.ttf', import.meta.url));
await flow.registerFont(new URL('fonts/Roboto-Bold.ttf', import.meta.url));

// 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 rootElement = 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);
flow.renderToCanvas(rootElement, canvas);

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

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

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/with-parse.js';
import {createCanvas} from 'canvas';
import fs from 'node:fs';

await flow.registerFont(new URL('fonts/Roboto-Regular.ttf', import.meta.url));
await flow.registerFont(new URL('fonts/Roboto-Bold.ttf', import.meta.url));

const rootElement = flow.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(rootElement, 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:

  1. Register fonts
  2. 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:

  1. Render DOM to canvas

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

  1. Generate a tree of layout boxes from the DOM
  2. Layout the box tree
  3. Paint the box tree to a target like canvas

Fonts

registerFont

async function registerFont(url: URL, options?: {paint: boolean}): Promise<void>;
async function registerFont(buffer: ArrayBuffer, url: URL, options?: {paint: boolean}): Promise<void>;

Registers a font to be selected by the font properties. Dropflow does not search system fonts, so you must do this with at least one font.

When a URL is passed, don't forget to await this. If an ArrayBuffer is passed, there is no need to await. In that function signature, the URL is only used to provide a unique name for the font.

The URL must always be unique.

In the browser, make sure the font is also loaded into page so that the paint backend can reference it with ctx.font. In node-canvas, you should either use registerFont from canvas for this font, or pass {paint: true} for options, which will try to load node-canvas and call its registerFont.

Note

This will soon be replaced with an API that looks more like the document.fonts API in the browser.

loadNotoFonts

async function loadNotoFonts(root: HTMLElement): Promise<URL[]>;

Fetches and registers subsetted Noto Sans fonts that, together, can display all characters in the document. The fonts are published by FontSource and hosted by jsDelivr. Nothing needs to be done with the return value, but you can use it to unregister the fonts.

For Latin, italic fonts are registered. For all scripts, one normal (400) weight and one bold (700) is registered.

Since dropflow cannot use system fonts, this is similar to having fallback fonts for many languages available on your operating system.

Note

While this will make the vast majority of text renderable, some scripts should be displayed with fonts made specifically for the language being displayed. For example, Chinese, Korean, and Japanese share common Unicode code points, but can render those characters differently. There is also a small cost to inspecting every character in the document. It is always better to use specific fonts when possible.

unregisterFont

function unregisterFont(url: URL): void;

Removes a font from the internal list so that it won't be picked by the font properties. This does not remove it from the paint target.

Hyperscript

The hyperscript API is the fastest way to generate a DOM. The DOM is composed of HTMLElements and TextNodes. The relevant properties of them are shown below. More supported properties are described in the [#dom-api](DOM API section).

style

function style(properties: DeclaredStyleProperties): DeclaredStyle;

Use the style function to create a style for passing to the attributes of an element later. DeclaredStyleProperties is defined in style.ts.

h

type HsChild = HTMLElement | string;

class HTMLElement {
  children: (HTMLElement | TextNode)[];
}

class TextNode {
  text: string;
}

interface HsData {
  style?: DeclaredStyle | DeclaredStyle[];
  attrs?: {[k: string]: string};
}

function h(tagName: string): HTMLElement;
function h(tagName: string, data: HsData): HTMLElement;
function h(tagName: string, children: HsChild[]): HTMLElement;
function h(tagName: string, text: string): HTMLElement;
function h(tagName: string, data: HsData, children: HsChild[] | string): HTMLElement;

Creates an HTMLElement. Use styles from the previous section. Currently the only attribute used is x-dropflow-log, which, when present on a paragraph, logs details about text shaping.

t

function t(text: string): TextNode;

Creates a TextNode. Normally you don't need to do this, just pass a string as an HsChild to flow.h. If you need to build a DOM breadth-first, such as in a custom parser, you can use this and mutate the text property on the returned value.

dom

type HsChild = HTMLElement | string;

function dom(el: HsChild | HsChild[]): HTMLElement

Calculates styles and wraps with <html> if the root tagName is not "html".

The entire h tree to render must be passed to this function before rendering.

Parse

This part of the API brings in a lot more code due to the size of the HTML and CSS parsers. Import it like so:

import flow from 'dropflow/with-parse.js';

Note that only the style HTML attribute is supported at this time. class does not work yet.

parse

function parse(str: string): HTMLElement;

Parses HTML. If you don't specify a root <html> element, content will be wrapped with one.

Render DOM to canvas

This is only for simple use cases. For more advanced usage continue on to the next section.

function renderToCanvas(rootElement: HTMLElement, canvas: Canvas): void;

Renders the whole layout to the canvas, using its width and height as the viewport size.

Generate

generate

function generate(rootElement: HTMLElement): BlockContainer

Generates a box tree for the element tree. Box trees roughly correspond to DOM trees, but usually have more boxes (like for anonymous text content between block-level elements (divs)) and sometimes fewer (like for display: none).

BlockContainer has a repr() method for logging the tree.

Hold on to the return value so you can lay it out many times in different sizes, paint it or don't paint it if it's off-screen, or get intrinsics to build a higher-level logical layout (for example, spreadsheet column or row size even if the content is off screen).

Layout

layout

function layout(root: BlockContainer, width = 640, height = 480);

Position boxes and split text into lines so the layout tree is ready to paint. Can be called over and over with a different viewport size.

In more detail, layout involves:

  • Margin collapsing for block boxes
  • Passing text to HarfBuzz, iterating font fallbacks, wrapping, reshaping depending on break points
  • Float placement and clearing
  • Positioning shaped text spans and backgrounds according to direction and text direction
  • Second and third pass layouts for intrinsics of float, inline-block, and absolutes
  • Post-layout positioning (position)

Paint

This step paints the layout to a target. Painting can be done as many times as needed (for example, every time you render your scene to the canvas).

Canvas and SVG are currently supported. If you need to paint to a new kind of surface, contributions are welcome. It is relatively easy to add a new paint target (see the PaintBackend interface in src/paint.ts).

There is also a toy HTML target that was used early on in development, and kept around for fun.

paintToCanvas

function paintToCanvas(root: BlockContainer, ctx: CanvasRenderingContext2D): void;

Paints the layout to a browser canvas, node-canvas, or similar standards-compliant context.

paintToSvg

function paintToSvg(root: BlockContainer): string;

Paints the layout to an SVG string, with @font-face rules referencing the URL you passed to registerFont.

paintToSvgElements

function paintToSvgElements(root: BlockContainer): string;

Similar to paintToSvg, but doesn't add <svg> or @font-face rules. Useful if you're painting inside of an already-existing SVG element.

paintToHtml

function paintToHtml(root: BlockContainer): string;

Paint to HTML! Yes, this API can actually be used to go from HTML to HTML. It generates a flat list of a bunch of absolutely positioned elements. Probably don't use this, but it can be useful in development and is amusing.

DOM API

The root HTMLElement you get from the Hyperscript and Parse APIs has methods you can use to find other HTMLElements in your tree. Like the browser's querySelector APIs, you can search by tag name, id attribute, or classes from the class attribute.

This allows you to get the render boxes associated with the element so you can do more sophisticated things like paint custom content or do hit detection.

query

class HTMLElement {
  query(selector: string): HTMLElement | null;
}

queryAll

class HTMLElement {
  queryAll(selector: string): HTMLElement[];
}

boxes

HTMLElements can have more than one render box, but will normally have just one. The two main types of boxes are BlockContainers (roughly <div>) and Inlines (roughly <span>s).

The only time you'll see more than one Box for an element is if the element has mixed inline and block content. In that case, the inline content gets wrapped with anonymous BlockContainers.

A BlockContainer is generated for absolutely positioned elements, floated elements, inline-blocks, and block-level elements. For those elements, you can use its contentArea, borderArea, and paddingArea.

Most of the time you can assume it's a BlockContainer:

const dom = flow.parse('<div id="d" style="width: 100px; height: 100px;"></div>');
const root = flow.generate(dom);
flow.layout(root, 200, 200);
const [box] = dom.query('#d')!.boxes as flow.BlockContainer[];
box.contentArea.width; // 100
box.contentArea.height; // 100

The supported interfaces of the classes follow:

class HTMLElement {
  boxes: Box[];
}
class Box {
  isInline(): this is Inline;
  isBlockContainer(): this is BlockContainer;
}
class BlockContainer extends Box {
  public borderArea: BoxArea;
  public paddingArea: BoxArea;
  public contentArea: BoxArea;
}
class Inline extends Box;
class BoxArea {
  public x: number;
  public y: number;
  public width: number;
  public height: number;
}

Other

staticLayoutContribution

function staticLayoutContribution(box: BlockContainer): number;

Returns the inline size in CSS pixels taken up by the layout, not including empty space after lines or the effect of any width properties. layout must be called before this.

The intended usage is this: after laying out text into a desired size, use staticLayoutContribution to get the size without any remaining empty space at the end of the lines, then layout again into that size to get a tightly fitting layout.

HarfBuzz

Glyph layout is performed by HarfBuzz compiled to WebAssembly. This allows for a level of correctness that isn't possible by using the measureText API to position spans of text. If you color the "V" in the text "AV" differently in Google Sheets, you will notice kerning is lost, and the letters appear further apart than they should be. That's because two measureText and fillText calls were made on the letters, so contextual glyph advances were lost. Dropflow uses HarfBuzz on more coarse shaping boundaries (not when color is changed) so that the font is more correctly supported.

HarfBuzz compiled to WebAssembly can achieve performance metrics similar to CanvasRenderingContext2D's measureText. It's not as fast as measureText, but it's not significantly slower (neither of them are the dominators in a text layout stack) and measureText has other correctness drawbacks. For example, a measureText-based text layout implementation must use a word cache to be quick, and this is what GSuite apps do. But a word cache is not able to support fonts with effects across spaces, and to support such a font would have to involve a binary search on the paragraph's break indices, which is far slower than passing the whole paragraph to HarfBuzz. Colored diacritics are not possible in any way with measureText either.

Shout-outs

dropflow doesn't have any package.json dependencies, but the work of many others made it possible. Javascript dependencies have been checked in and modified to varying degrees to fit this project, maintain focus, and rebel against dependency-of-dependency madness. Here are the projects I'm grateful for: