@effing/canvas 0.42.0 → 0.44.0

package/README.md

@@ -87,7 +87,7 @@ Emoji characters are automatically rendered as images from CDNs. Supported style
 | `fluent`     | Microsoft Fluent Emoji (color) |
 | `fluentFlat` | Microsoft Fluent Emoji (flat)  |
 
-Pass `emoji: "none"` to disable emoji image rendering.
+An emoji is an emoji character ([UTS #51](https://www.unicode.org/reports/tr51/)), with or without U+FE0F (`🌍`, `❤`, `❤️`, `🕵`), a keycap (`1️⃣`), a flag (`🇧🇪`, `🏴󠁧󠁢󠁥󠁮󠁧󠁿`), a skin-tone sequence (`👍🏽`) or a ZWJ sequence of emoji (`👨‍👩‍👧`). Emoji characters are drawn as images even when Unicode presents them as text by default, except `©`, `®` and `™`, which stay text unless U+FE0F follows them, and digits, `#` and `*`, which stay text unless a keycap follows them, as browsers draw them; U+FE0E keeps any emoji character text. For text-default emoji in the Basic Multilingual Plane, such as `❤` or `☎`, this differs from browsers, which draw them as monochrome text through the system's fallback fonts: canvas has no such fallback, so an image beats a missing glyph. Text-default emoji outside it, such as `🕵` or `🏳`, are colour emoji in browsers too. Characters with no emoji form, such as `✓` or `●`, are text. Each emoji takes an inline box of 1em on its line, with its bottom 0.1em below the baseline, about where browsers draw an emoji glyph. Lines break around it as browsers break them around an emoji, so it stays with the punctuation next to it (`🎉!`, `(🎉)`). Pass `emoji: "none"` to disable emoji image rendering. An emoji drawn without an image — with `emoji: "none"`, one the style has no image for (the Fluent styles have no flags), or one whose image failed to load — is drawn as text, so it needs a font that covers it among the text's font families (every font given to `renderReactElement` is one), as do text symbols.
 
 ## Fit Text
 
@@ -104,7 +104,7 @@ const fontSize = findLargestUsableFontSize({
 });
 ```
 
-By default the text wraps to `maxWidth` and is fit into the `maxWidth` × `maxHeight` box. Pass `whiteSpace: "nowrap"` to fit the text on one line (per newline-separated paragraph) instead, where `maxWidth` constrains the full line width:
+By default the text wraps to `maxWidth` and is fit into the `maxWidth` × `maxHeight` box. Pass `whiteSpace: "nowrap"` to fit the text on one line instead (or `"pre"` for one line per newline-separated paragraph), where `maxWidth` constrains the full line width:
 
 ```typescript
 const fontSize = findLargestUsableFontSize({
@@ -116,7 +116,7 @@ const fontSize = findLargestUsableFontSize({
 });
 ```
 
-Supports optional `lineHeight` (`"normal"` or a numeric multiplier), `whiteSpace` (`"normal"` by default; `"nowrap"`/`"pre"` for one line per paragraph), `minFontSize` (default 1), and `maxFontSize` (default 1000).
+Supports optional `lineHeight` (`"normal"` or a numeric multiplier), `whiteSpace` (`"normal"` by default; `"nowrap"` for one line, `"pre"` for one line per paragraph), `minFontSize` (default 1), and `maxFontSize` (default 1000).
 
 ## Inline SVG
 
@@ -245,40 +245,51 @@ const png = canvas.encodeSync("png");
 
 ### Typography
 
-| Property                | Values / Notes                                                |
-| ----------------------- | ------------------------------------------------------------- |
-| `fontFamily`            | Font name (inherited)                                         |
-| `fontSize`              | Number or CSS length (inherited)                              |
-| `fontWeight`            | Numeric weight (inherited)                                    |
-| `fontStyle`             | `normal`, `italic` (inherited)                                |
-| `textAlign`             | `left`, `center`, `right`, `justify` (inherited)              |
-| `textDecoration`        | String (inherited)                                            |
-| `textTransform`         | `none`, `uppercase`, `lowercase`, `capitalize` (inherited)    |
-| `lineHeight`            | Number or string (inherited)                                  |
-| `letterSpacing`         | Number or CSS length (inherited)                              |
-| `whiteSpace`            | `normal`, `nowrap`, `pre`, `pre-wrap`, `pre-line` (inherited) |
-| `wordBreak`             | `normal`, `break-all`, `break-word`, `keep-all` (inherited)   |
-| `textOverflow`          | `clip`, `ellipsis` (inherited)                                |
-| `lineClamp`             | Number — max visible lines (adds ellipsis)                    |
-| `textBox`               | Shorthand for `textBoxTrim` and `textBoxEdge`                 |
-| `textBoxTrim`           | `none`, `trim-start`, `trim-end`, `trim-both` (inherited)     |
-| `textBoxEdge`           | e.g. `"cap alphabetic"` (inherited)                           |
-| `WebkitTextStroke`      | Shorthand, e.g. `"2px red"` (inherited)                       |
-| `WebkitTextStrokeWidth` | CSS length (inherited)                                        |
-| `WebkitTextStrokeColor` | Any CSS color (inherited)                                     |
+| Property                | Values / Notes                                                 |
+| ----------------------- | -------------------------------------------------------------- |
+| `fontFamily`            | Font name (inherited)                                          |
+| `fontSize`              | Number or CSS length (inherited)                               |
+| `fontWeight`            | Numeric weight (inherited)                                     |
+| `fontStyle`             | `normal`, `italic` (inherited)                                 |
+| `textAlign`             | `left`, `center`, `right`, `justify` (inherited)               |
+| `textDecoration`        | String (inherited)                                             |
+| `textTransform`         | `none`, `uppercase`, `lowercase`, `capitalize` (inherited)     |
+| `lineHeight`            | Number or string (inherited)⁴                                  |
+| `letterSpacing`         | Number or CSS length (inherited)                               |
+| `whiteSpace`            | `normal`, `nowrap`, `pre`, `pre-wrap`, `pre-line` (inherited)¹ |
+| `wordBreak`             | `normal`, `break-all`, `keep-all`, `break-word`² (inherited)   |
+| `overflowWrap`          | `normal`, `break-word`, `anywhere`² (inherited)                |
+| `textOverflow`          | `clip`, `ellipsis` (inherited)                                 |
+| `lineClamp`             | Number — max visible lines (adds ellipsis)³                    |
+| `textBox`               | Shorthand for `textBoxTrim` and `textBoxEdge`                  |
+| `textBoxTrim`           | `none`, `trim-start`, `trim-end`, `trim-both` (inherited)      |
+| `textBoxEdge`           | e.g. `"cap alphabetic"` (inherited)                            |
+| `WebkitTextStroke`      | Shorthand, e.g. `"2px red"` (inherited)                        |
+| `WebkitTextStrokeWidth` | CSS length (inherited)                                         |
+| `WebkitTextStrokeColor` | Any CSS color (inherited)                                      |
+
+¹ White space is processed as in CSS: under `normal`, `nowrap` and `pre-line`, a run of spaces and tabs collapses to one space, the spaces at the start and end of the text and around a newline are removed, and a newline becomes a space (`pre-line` keeps it as a line break). Adjacent strings, as `Hello {name}` gives, are one run of text, and each run of text between elements is laid out as a flex item of its own, as browsers lay out text in a flex container: a run of nothing but white space, such as `{" "}` between two elements, isn't rendered, and an element whose only text is empty or white space has no line box. Fragments, arrays and function components are unwrapped first, as the DOM has no trace of them. A `<br />` is a forced line break in the run of text around it, under every `whiteSpace` (`nowrap` included), as in browsers: the text either side of it is one item, in a row as in a column, and the spaces before and after it are removed where spaces collapse. A `<br />` between two elements is an item of one empty line. A line or paragraph separator (U+2028, U+2029) is a space with a break opportunity after it, as in browsers, `letterSpacing` included. `pre` and `pre-wrap` keep the spaces before a line break in the line's width and alignment, as browsers do; a tab is one space wide. A CRLF counts as one newline. Under `pre` and `pre-wrap`, a lone CR is drawn as nothing and doesn't break the line, as in browsers, but the letters either side of it don't kern or join; elsewhere it's a space.
+
+² A word wider than its line overflows it, as in CSS, unless `overflowWrap` is `break-word` or `anywhere` (or `wordBreak` the deprecated `break-word`): the word then starts a line of its own and is broken between grapheme clusters where that line is full. `anywhere` breaks as `break-word` does.
+
+³ The last line shown is its own text with an ellipsis after it, cut to fit, as in browsers. Canvas aligns the clamped line with its ellipsis, where browsers align its text alone and let the ellipsis overflow (hidden by `overflow: hidden`): right-aligned, `"ab\ncd"` clamped to one line is "ab…" at the right edge, where browsers show "ab" there.
+
+⁴ `normal` line boxes are sized as in Chrome on macOS: the font's hhea ascent, descent and line gap, each rounded to whole pixels, with the baseline at the rounded ascent plus half the line gap. They follow the first available font in `fontFamily` alone, where browsers also grow a line for a fallback font that draws some of its text.
 
 ### Effects
 
 | Property          | Values / Notes                                   |
 | ----------------- | ------------------------------------------------ |
-| `boxShadow`       | CSS box-shadow string                            |
-| `textShadow`      | CSS text-shadow string                           |
+| `boxShadow`       | CSS box-shadow list¹                             |
+| `textShadow`      | CSS text-shadow list¹ (inherited)                |
 | `transform`       | `translate`, `scale`, `rotate`, `skewX`, `skewY` |
 | `transformOrigin` | CSS transform-origin string                      |
 | `filter`          | CSS filter string                                |
 | `backdropFilter`  | CSS filter string applied to the backdrop        |
 | `clipPath`        | Basic shapes, `shape()`, geometry boxes, `none`  |
 
+¹ As in CSS: a comma-separated list of shadows, the first painted on top. A box shadow is `inset`, two to four lengths (x and y offsets, blur radius, spread) and a colour, in either order; a text shadow is two or three lengths (no spread or `inset`) and a colour. A shadow without a colour is cast in `currentColor`. A spread grows the shadow's shape (or, negative, shrinks it), and its corner radii with it; an `inset` shadow is cast inside the padding box, clipped to its rounded corners. Lengths are in px or any unit canvas resolves (`em`, `rem`, `vw`, `pt`, …; a bare number is read as px). An invalid value casts no shadow, as CSS ignores it.
+
 ### Image
 
 | Property    | Values / Notes                                   |

package/dist/index.d.ts

@@ -277,6 +277,7 @@ type ComputedStyle = {
     letterSpacing?: number | string;
     whiteSpace?: "normal" | "nowrap" | "pre" | "pre-wrap" | "pre-line";
     wordBreak?: "normal" | "break-all" | "break-word" | "keep-all";
+    overflowWrap?: "normal" | "break-word" | "anywhere";
     textOverflow?: "clip" | "ellipsis";
     lineClamp?: number;
     boxShadow?: string;
@@ -308,9 +309,10 @@ type FindLargestUsableFontSizeOptions = {
     /** Line height — `"normal"` uses font metrics, numeric values are CSS multipliers */
     lineHeight?: number | "normal";
     /**
-     * Whitespace handling, mirroring CSS. Use `"nowrap"` (or `"pre"`) to fit text
-     * on one line (per newline-separated paragraph) instead of wrapping to
-     * `maxWidth` (default: `"normal"`).
+     * Whitespace handling, as in CSS (default: `"normal"`). Use `"nowrap"` to
+     * fit the text on one line instead of wrapping to `maxWidth`, its newlines
+     * collapsing to spaces, or `"pre"` to fit each newline-separated paragraph
+     * on a line of its own.
      */
     whiteSpace?: ComputedStyle["whiteSpace"];
     /** Minimum font size to consider (default: 1) */
@@ -325,9 +327,9 @@ type FindLargestUsableFontSizeOptions = {
  * at each step. Returns `minFontSize` if even the smallest size overflows.
  *
  * By default text wraps to `maxWidth` and is fit into the `maxWidth` × `maxHeight`
- * box. Set `whiteSpace: "nowrap"` to fit the text on one line (per
- * newline-separated paragraph) instead, in which case `maxWidth` constrains the
- * full line width.
+ * box. Set `whiteSpace: "nowrap"` to fit the text on one line instead (or
+ * `"pre"` for one line per newline-separated paragraph), in which case
+ * `maxWidth` constrains the full line width.
  */
 declare function findLargestUsableFontSize(options: FindLargestUsableFontSizeOptions): number;