palantir/typesettable

:triangular_ruler: A typesetting library for SVG and Canvas

Typesettable

:warning_sign: Deprecation notice (January 2023)

This library is mostly deprecated and its build tooling is very outdated. If you need to make changes to this library, you will need to fix some of the build infrastructure to get it working in a modern testing & deployment environment.

Overview

Typesettable is a library for measuring, wrapping, and writing text on Canvas, SVG, and HTML.

Canvas and HTML support some rudimentary wrapping, but SVG does not support any. Furthermore, developers often want wrapped text to auto-hyphenate and truncate with ellipses when overflowing the bounding box. Typesettable aims to make this entire process easier.

Typesettable works with native browser APIs and has no external dependencies.

Features

• Measurers efficiently measure the size of a piece of text, taking into account the font styles affecting that text.
• Wrappers calculate how best to fit text into a given space, based on results from the Measurer.
• Writers layout and write text based on specified options such as wrapping, alignment, rotation, and shearing.
• SvgContext, CanvasContext, and HtmlContext implement factories for the IRuler and IPen objects, which encapsulate the functionality for measuring and writing text in SVG, Canvas, and HTML elements.

Installation

npm install --save typesettable

Usage

Example Two Liner

import { Typesetter } from "typesettable";

const typesetter = Typesetter.svg(document.querySelector("svg"));
typesetter.write("Hello World!", 200, 200);

Example SVG, Canvas, & HTML

Use typesetters with both SVG and Canvas elements:

import { Typesetter } from "typesettable";

// A typesetter for SVG elements
const svgTypesetter = Typesetter.svg(document.querySelector("svg"));

// A typesetter for Canvas elements
const canvasTypesetter = Typesetter.canvas(document.querySelector("canvas").getContext("2d"));

// A typesetter for HTML elements
const htmlTypesetter = Typesetter.html(document.querySelector("div.text-container"));

// The dimensions into which the text will be wrapped and truncated
const width = 300;
const height = 50;

// Options for alignment, etc.
const writeOptions = {
  xAlign: "left",
  yAlign: "top",
  textRotation: 0,
  textShear: 0,
};

// Write the text to the elements
svgTypesetter.write("Hello SVG!", width, height, writeOptions);
canvasTypesetter.write("Hello Canvas!", width, height, writeOptions);
htmlTypesetter.write("Hello HTML!", width, height, writeOptions);

Example Shared Cache

If you are typesetting multiple strings of text with the same font style, maintain a cache of Measurer results to improve performance.

Your HTML might look like:

<svg>
  <g class="section-one"></g>
  <g class="section-two" transform="translate(120 0)"></g>
</svg>

To share text measurements between writer, you can use the simple Typesetter interface, which already uses a shared CacheMeasurer. Or, you can compose the components manually like so:

import { CacheMeasurer, SvgContext, Wrapper, Writer } from "typesettable";

const svg = document.querySelector("svg");
const context = new SvgContext(svg);
const measurer = new CacheMeasurer(context);
const wrapper = new Wrapper();
const writer = new Writer(measurer, context, wrapper);
const writeOptions = { xAlign: "center" };

writer.write(
  "This text is in the first section",
  100, 400, writeOptions,
  svg.querySelector("g.section-one")
);

writer.write(
  "This text is in the second section",
  100, 200, writeOptions,
  svg.querySelector("g.section-two")
);

API Docs

See the docs for more detailed examples.

typesettable's Issues

Make wrapper optional in writer constructor.

investigate need for addClipPath in writer

addClipPath adds significant time to writer.write (in some cases dominating the time taken) because it calls getBBox(). See what the goal of it is and if we can reduce the number of times getBBox() is called

[Measurer] Measurer is not angle-aware

The issue with palantir/plottable#1526 was that svg-typewriter's measurer did not have a concept of rotated text, so it was necessary to measure text in a non-rotated state, and then convert back and forth based on the angle.

Auto adjust font size

Introduce functionality on writer that instead of putting ellipsis when text does not fit, try to adjust font size.

Need to check if setting font directly on <text> node will override CSS style.

Updating styles in the middle of text

I have text that needs to be laid out on a canvas rectangle. The text looks like this:

"Lorem ipsum [i]dolor[/i] sit [b]amet[/b] ..."

The final render should process italic and bold directives accordingly. I already have the tokenization logic for it. My current logic switches the canvas rendering context's font attribute accordingly whenever it encounters a token, and skips the token. Reference code:

https://github.com/HearthSim/Sunwell/blob/50efa7d5b9b800836f3871f856783b61f78858a4/src/Components/BodyText.ts#L194-L211

With typesettable, the write() directive is not style-aware, so I have to give it a batch of text that is all the same style, then update the style, then give it the next batch, etc.
If I do that, I suspect typesettable will lose the ability to control the entire layout. I'm not even sure I can do that in a way that doesn't end up looking weird.

Thoughts?

Writer should clean up before writing

If there is existing text element inside given selection Writer should clean this up.

Wrapper is doing some redundant measurments.

In case of adding ellipsis to single work, wrapper is doing some redundant measurements/computation.

Remove dependency on D3

Add animations

It should go to WriteOptions.

Text wraps differently between browsers

Solution is to use text-rendering: geometricPrecision. This ensures all the getBBox calculations are consistent across all browsers

Figure out why test fails on Linux/Chrome on Saucelabs

Specifically this test:

        it.skip("works on whitespaces in middle", function () {
            var baseResult = measurer.measure("a a");
            var result = measurer.measure("a   a");
            assert.equal(result.width, baseResult.width, "multiple whitespaces occupy same space");
            assert.equal(result.height, baseResult.height, "height is the same");
        });

docs point to wrong repo

The docs at e.g. http://palantir.github.io/svg-typewriter/docs/classes/svgtypewriter.writers.writer.html say:

"Defined in /Users/askrodzki/Work/svg-typewriter-page/src/writer.ts:40"

We should update that to point to the correct location.

Side note (the link points to "https://github.com/endrjuskr/svg-typewriter/blob/gh-pages/src/writer.ts#L40", although it correctly redirects to palantir/svg-typewriter)

Writer input sanitization

Using allowBreakingWords(false), large single words that can't be broken will be totally hidden

1. create a Wrapper
2. wrapper.allowBreakingWords(false)
3. wrap a single long word like "aaaaaaaaaaaaaaaaaa"

Expected:

long word gets broken to fit:
"aaaaaaaa
aaaaaaa"

actual:

long word gets completely removed from the text

Fade in, fade out animation

How to set X, Y coordinates

Is there a simple way to move/translate the whole wrapper?

Cannot find name 'SVGLocatable'

I get this error when using TypeScript version 2.2 or later:

 ./node_modules/typesettable/build/src/contexts/svg.d.ts:26:35
    TS2304: Cannot find name 'SVGLocatable'.

Hover-over title

For truncated text add <title> to show full text.

Always remove and append child in measurer

Vertical right writer alignment

center does not work.

add option for 45 degrees (or, optimally, other angles)

Probably also fixes #25

Writer test

Add assertion to writer test.

Annotated linesetter

Hello all. I'm a veteran type creature (among other things, I'm the guy who figured out Hobo's origins). I've been thinking about a lightweight annotated reader in JavaScript or Python that could dynamically render something like the following:

Note how leading is increased just enough to carry the annotations, and how the Chinese (or other language) annotation lines need to know precisely where their companion lines' words start and end. Trying to think about how to do this with HTML5 and CSS makes my head hurt. It's simply not practical to attempt H&J on these particles on the fly in HTML. This calls for linesetting logic that computes word escapements as we are writing them onto the device canvas.

I haven't used typesettable, but I wonder if you know if this is close to possible to do, and if it is close but not quite a cigar, whether there's interest in working together to get something like this done.

Measuring after wrapping?

Hi,

Is there a way to get bounding box of the result after text is wrapped? I think I can use the boundingBox of the svg group.. but isn't already measured?

Thank you!

Upgrade to d3 v4

Rotation by any angle

Improve test coverage

Right now is 85 and goal is ~92%.

Deprecate this library and move into Plottable directly

svg-typewriter being separate from plottable is causing us friction in iteration speed and build pains. We should just deprecate this library and move the code into Plottable directly

RTL support

Add support for RTL.

Intelligent wrapping for long words

To avoid situation that long wraps like that:
reallylongwo-
rd`
expose endpoint to specify what is min percentage of which should be wrapped to next line.

Measuring HtmlContext text with spaces is broken

var context = new HtmlContext(...);
var measurer = new CacheMeasurer(context);

measurer.measure("t"); // returns { width: 10, height: 17 }
measurer.measure(" "); // returns { width: -37, height: 35 }

This negative value then feeds up the chain for generic line/text measuring

The space measuring breaks because of the "useGuards" logic

ellipsis are added past the desired width

if you .write(text, width, ...) and text gets trimmed with ellipsis, the text will get truncated to just below width, but adding the ellipses will push it back past width again

Improve writer layout structure

Right now, we are generating too many g elements.

[Measurer] CachedCharacterMeasurer does not work properly

Given the string “27.2”, we compare the following:

• Sum of widths of individual characters: 35.233 (FF), 27.297 (Chrome)
• Width of string as a whole: 29.233 (FF), 27.25 (Chrome)

Should reevaluate whether there is a correct way of caching computations, or if this is something that cannot be done due to how fonts render on a computer.