text-to-canvas 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 The format is inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v4.0.0
+
+- __Breaking:__ Support for [line breaks](./README.md#line-breaks). Breaking because of Words containing characters and one or more line breaks being treated as a single line break (any additional characters ignored).
+  - Also fixes a bug where line breaks were treated as space characters instead of breaking text to new lines.
+- When inferring whitespace (`inferWhitespace` option of `splitWords()`), generated space characters now inherit the format of the previous word.
+- New `DrawTextResults` exported type for the object returned by `drawText()` instead of relying on an inferred type which could too easily change without being noticed.
+- New `DrawTextConfig.textWrap: TextWrap` config option to control whether [text wraps](./README.md#text-wrapping) at the horizontal boundaries of the render box.
+  - Note that "clipping", spreadsheet-style, is a combination of `textWrap='none'` and `overflow=false` options.
+
+## v3.0.1
+
+- Fixed a bug where specifying any allowed property of `TextFormat.underline` or `TextFormat.strikethrough` as `undefined` was not resulting in the default behavior. `undefined` is treated as equivalent to the absence of the property.
+
 ## v3.0.0
 
 - __Breaking:__ The `RenderSpec.textBaseline` property type has changed from `CanvasTextBaseline` to `RenderTextBaseline` which is a narrowing of possible baselines used for actual rendering.

package/README.md

@@ -187,11 +187,12 @@ You can run this demo locally with `npm run node:demo`
 | `fontColor`       | `'black'`    | Base font color, same as css color. Examples: `blue`, `#00ff00`. |
 | `strokeColor`     | `'black'`    | Base stroke color, same as css color. Examples: `blue`, `#00ff00`. |
 | `strokeWidth`     | `0`          | Base stroke width. Positive number; `<=0` means none. Can be fractional. ⚠️ Word splitting does not take into account the stroke, which is applied on the __center__ of the edges of the text via the [strokeText()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/strokeText) Canvas API. Setting a thick stroke will cause it to bleed out of the text box. |
-| `justify`         | `false`      | Justify text if `true`, it will insert spaces between words when necessary. |
+| `justify`         | `false`      | Justify text if `true`. It will insert spaces between words when necessary. __Ignored__ if `textWrap != 'wrap'` |
 | `underline`       | `false`      | If the text or word should be underlined. Can also be an object with customization options like color, thickness, and offset. |
 | `strikethrough`   | `false`      | If the text or word should have a strikethrough. Can also be an object with customization options like color, thickness, and offset. |
 | `inferWhitespace` | `true`       | If whitespace in the text should be inferred. Only applies if the text given to `drawText()` is a `Word[]`. If the text is a `string`, this config setting is ignored. |
-| `overflow`        | `true`       | Allows the text to overflow out of the box if the box is too narrow/short to fit it all. `false` will clip the text to the box's boundaries. |
+| `overflow`        | `true`       | Allows the text to overflow out of the box if the box is too narrow/short to fit it all. `false` will clip the text to the box's boundaries. Use in conjunction with `textWrap='none'` to achieve a typical spreadsheet clipping effect. |
+| `textWrap`        | `'wrap'`     | Whether the text should wrap at supported newline characters (LF, LS, or PS) as well as at the box's horizontal boundaries in order to keep as much of the text visible, or extend beyond the horizontal boundaries of the box even if it doesn't fit. This is __separate__ from whether the text extending beyond the box's horizontal boundaries is visible (i.e. "clipped"). Use the `overflow` option to control clipping (e.g. `clip = textWrap='none' + overflow=false`. Other values: `'none'` (no wrapping other than at hard breaks using `\n` characters). |
 | `debug`           | `false`      | Draws the border and alignment lines of the text box for debugging purposes. |
 
 ## Functions
@@ -227,6 +228,25 @@ import {
 
 TypeScript integration should provide helpful JSDocs for every function and each of its parameters to further help with their use.
 
+## Line Breaks
+
+Newline characters (i.e. hard breaks) are supported in text and Words, but only the following characters are considered line breaks:
+
+- Line Feed (LF): `\n`
+- Line Separator (LS): `\u2028`
+- Paragraph Separator (PS): `\u2029`
+
+> 🔺 Any `Word` that has at least one line break character in it will be treated as a __single__ line break regardless of any other characters it contains, even if they are additional line breaks. If you generate your own `Word` array to provide to `splitWords()` or `drawText()`, make sure you separate all line breaks into separate words.
+
+## Text Wrapping
+
+Text wrapping is supported via the `DrawTextConfig.textWrap` config option. Two modes are supported:
+
+- `'wrap'`: (Default) Text wraps at the horizontal boundaries of the render box.
+- `'none'`: Text does not wrap and will either overflow past the horizontal boundaries of the render box, or if `overflow=false`, get __clipped__ at the boundaries.
+
+> 💡 To achieve spreadsheet-style clipping, use `textWrap='none'` and `overflow=false`.
+
 # Examples
 
 ## Web Worker and OffscreenCanvas

package/dist/text-to-canvas.cjs

@@ -27,6 +27,18 @@ const _formatMerge = (...sources) => {
       offset: 0
     }
   };
+  const targetSpecified = {
+    underline: {
+      color: false,
+      offset: false,
+      thickness: false
+    },
+    strikethrough: {
+      color: false,
+      offset: false,
+      thickness: false
+    }
+  };
   sources.forEach((source) => {
     if (source && typeof source === "object" && !Array.isArray(source)) {
       Object.entries(source).forEach(([sourceKey, sourceValue]) => {
@@ -37,25 +49,33 @@ const _formatMerge = (...sources) => {
                 target[sourceKey].color = "";
                 target[sourceKey].thickness = NaN;
                 target[sourceKey].offset = NaN;
+                targetSpecified[sourceKey].color = true;
+                targetSpecified[sourceKey].thickness = true;
+                targetSpecified[sourceKey].offset = true;
+              } else {
+                target[sourceKey].thickness = 0;
+                targetSpecified[sourceKey].thickness = true;
               }
             } else if (sourceValue && typeof sourceValue === "object" && !Array.isArray(sourceValue)) {
               const underStrikeSource = sourceValue;
               const underStrikeSourceKeys = Object.keys(
                 underStrikeSource
-              );
+              ).filter((k) => underStrikeSource[k] !== void 0);
               underStrikeSourceKeys.forEach((k) => {
-                if (underStrikeSource[k] !== void 0) {
-                  target[sourceKey][k] = underStrikeSource[k];
-                }
+                target[sourceKey][k] = underStrikeSource[k];
+                targetSpecified[sourceKey][k] = true;
               });
-              if (!underStrikeSourceKeys.includes("color")) {
+              if (!underStrikeSourceKeys.includes("color") && !targetSpecified[sourceKey].color) {
                 target[sourceKey].color = "";
+                targetSpecified[sourceKey].color = true;
               }
-              if (!underStrikeSourceKeys.includes("thickness")) {
+              if (!underStrikeSourceKeys.includes("thickness") && !targetSpecified[sourceKey].thickness) {
                 target[sourceKey].thickness = NaN;
+                targetSpecified[sourceKey].thickness = true;
               }
-              if (!underStrikeSourceKeys.includes("offset")) {
+              if (!underStrikeSourceKeys.includes("offset") && !targetSpecified[sourceKey].offset) {
                 target[sourceKey].offset = NaN;
+                targetSpecified[sourceKey].offset = true;
               }
             }
           } else {
@@ -72,32 +92,7 @@ const getTextFormat = (format, baseFormat) => {
     "underline",
     "strikethrough"
   ];
-  const fullBaseFormat = {
-    ...baseFormat
-  };
-  const fullFormat = {
-    ...format
-  };
-  underStrikeProps.forEach((prop) => {
-    [fullBaseFormat, fullFormat].forEach((obj) => {
-      if (obj[prop] !== void 0) {
-        if (obj[prop] === true) {
-          obj[prop] = {
-            thickness: NaN
-          };
-        } else if (obj[prop] === false) {
-          obj[prop] = {
-            thickness: 0
-          };
-        } else {
-          obj[prop] = {
-            ...obj[prop]
-          };
-        }
-      }
-    });
-  });
-  const result = _formatMerge(fullBaseFormat, fullFormat);
+  const result = _formatMerge(baseFormat, format);
   const fontSizeFactor = result.fontSize / 24;
   underStrikeProps.forEach((prop) => {
     if (result[prop].color === "") {
@@ -130,6 +125,21 @@ const getTextStyle = ({
 }) => {
   return `${fontStyle || ""} ${fontVariant || ""} ${fontWeight || ""} ${fontSize ?? DEFAULT_FONT_SIZE}px ${fontFamily || DEFAULT_FONT_FAMILY}`.trim();
 };
+const _lineBreaks = [
+  "\n",
+  // LF (line feed)
+  "\u2028",
+  // LS (line separator)
+  "\u2029"
+  // PS (paragraph separator)
+];
+const _lineBreakRE = new RegExp(`[${_lineBreaks.join("")}]`);
+const hasLineBreak = (text) => {
+  return _lineBreakRE.test(text);
+};
+const isLineBreak = (char) => {
+  return char.length === 1 && hasLineBreak(char);
+};
 const isWhitespace = (text) => {
   return !!text.match(/^\s+$/);
 };
@@ -234,15 +244,38 @@ const HAIR = " ";
 const SPACE = " ";
 let fontBoundingBoxSupported;
 const _getWordHash = (word) => {
-  return `${word.text}${word.format ? JSON.stringify(word.format) : ""}`;
+  return `${word.text}${word.format ? JSON.stringify(
+    Object.entries(word.format).map(([name, propValue]) => {
+      let value = propValue;
+      if ((name === "underline" || name === "strikethrough") && typeof propValue === "object") {
+        value = Object.entries(propValue);
+      }
+      return [name, value];
+    })
+  ) : ""}`;
 };
-const _splitIntoLines = (words, inferWhitespace = true) => {
+const _splitIntoHardLines = (words, inferWhitespace = true) => {
   const lines = [[]];
+  let prevLine;
+  let beforePrevLine;
   let wasWhitespace = false;
   words.forEach((word, wordIdx) => {
-    if (word.text.match(/^\n+$/)) {
-      for (let i = 0; i < word.text.length; i++) {
-        lines.push([]);
+    if (hasLineBreak(word.text)) {
+      lines.push([]);
+      prevLine = lines.at(-2);
+      beforePrevLine = lines.at(-3);
+      if (prevLine && prevLine.length < 1) {
+        const { format } = beforePrevLine?.at(-1) || {};
+        prevLine.push({
+          text: HAIR,
+          format: {
+            ...format,
+            // remove any underline/strikethrough so it doesn't render on a HAIR which is
+            //  technically not whitespace which would otherwise be skipped
+            underline: false,
+            strikethrough: false
+          }
+        });
       }
       wasWhitespace = true;
       return;
@@ -256,7 +289,13 @@ const _splitIntoLines = (words, inferWhitespace = true) => {
       return;
     }
     if (inferWhitespace && !wasWhitespace && wordIdx > 0) {
-      lines.at(-1)?.push({ text: SPACE });
+      lines.at(-1)?.push({
+        text: SPACE,
+        // inherit format of previous Word on on current line, if it has a format
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- because of TSC ridiculousness
+        // @ts-ignore -- ridiculous TSC won't recognize Array.at() is a method
+        format: lines.at(-1)?.at(-1)?.format
+      });
     }
     lines.at(-1)?.push(word);
     wasWhitespace = false;
@@ -427,6 +466,7 @@ const splitWords = ({
   justify,
   format: baseFormat,
   inferWhitespace = true,
+  textWrap = "wrap",
   ...positioning
   // rest of params are related to positioning
 }) => {
@@ -438,7 +478,7 @@ const splitWords = ({
     let splitPoint = 0;
     lineWords.every((word, idx) => {
       const wordWidth = _measureWord({ ctx, word, wordMap, baseTextFormat });
-      if (!force && lineWidth + wordWidth > boxWidth) {
+      if (!force && textWrap !== "none" && lineWidth + wordWidth > boxWidth) {
         if (idx === 0) {
           splitPoint = 1;
           lineWidth = wordWidth;
@@ -452,7 +492,7 @@ const splitWords = ({
     return { lineWidth, splitPoint };
   };
   ctx.save();
-  const hardLines = _splitIntoLines(
+  const hardLines = _splitIntoHardLines(
     trimLine(words).trimmedLine,
     inferWhitespace
   );
@@ -470,7 +510,7 @@ const splitWords = ({
   const wrappedLines = [];
   for (const hardLine of hardLines) {
     let { splitPoint } = measureLine(hardLine);
-    if (splitPoint >= hardLine.length) {
+    if (textWrap !== "wrap" || splitPoint >= hardLine.length) {
       wrappedLines.push(hardLine);
     } else {
       let softLine = hardLine.concat();
@@ -486,7 +526,7 @@ const splitWords = ({
       wrappedLines.push(softLine);
     }
   }
-  if (justify && wrappedLines.length > 1) {
+  if (textWrap === "wrap" && justify && wrappedLines.length > 1) {
     wrappedLines.forEach((wrappedLine, idx) => {
       if (idx < wrappedLines.length - 1) {
         const justifiedLine = justifyLine({
@@ -513,13 +553,16 @@ const textToWords = (text) => {
   let word = void 0;
   let wasWhitespace = false;
   Array.from(text.trim()).forEach((c) => {
+    if (c === "\r") {
+      return;
+    }
     const charIsWhitespace = isWhitespace(c);
-    if (charIsWhitespace && !wasWhitespace || !charIsWhitespace && wasWhitespace) {
+    if (charIsWhitespace && !wasWhitespace || !charIsWhitespace && wasWhitespace || charIsWhitespace && wasWhitespace) {
       wasWhitespace = charIsWhitespace;
       if (word) {
         words.push(word);
       }
-      word = { text: c };
+      word = { text: isLineBreak(c) ? "\n" : c };
     } else {
       if (!word) {
         word = { text: "" };
@@ -672,7 +715,8 @@ const drawText = (ctx, text, config) => {
     align: config.align,
     vAlign: config.vAlign,
     justify: config.justify,
-    format: baseFormat
+    format: baseFormat,
+    textWrap: config.textWrap
   });
   ctx.save();
   ctx.textAlign = textAlign;