@effing/canvas 0.42.0 → 0.43.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,27 +245,34 @@ 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 an item of its own, not a forced break inside a run of text: in a column it puts the text after it on the next line, but in a row (the default `flexDirection`) the text either side of it sits side by side, where browsers stack it. A line or paragraph separator (U+2028, U+2029) is a space with a break opportunity after it, as in browsers, but with `letterSpacing` it gets the spacing twice where browsers add it once. `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, and `pre` and `pre-wrap` drop a lone CR, which browsers draw as nothing.
+
+² 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. Under `whiteSpace: "pre"`, a clamped line that ends at a newline gets no ellipsis, where browsers add one. 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.
 
 ### Effects
 

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;