text-to-canvas 1.2.1 → 3.0.0

package/CHANGELOG.md

@@ -2,8 +2,18 @@
 
 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).
+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).
+
+## 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.
+- Added new `TextFormat.underline` and `TextFormat.strikethrough` options ([#600](https://github.com/stefcameron/text-to-canvas/pull/600))
+  - Set to true to enable with all defaults, or specify an object with `{ color?, thickness?, offset? }` properties to have more customization.
+  - By default, the thickness and offset scale with the font size based on `24px` font size (which yields a `1px` thick line that is just beneath the text for underline and centered on the text for strikethrough). This simply seemed to be the best balance for the handful of fonts that were tested (all fonts currently available in the demo app). Tweak as needed for the font(s) you will use.
+
+## v2.0.0
+
+- __Breaking:__ Updated minimum supported of Node to `>=22` and builds now target `ES2022` at minimum.
 
 ## v1.2.1
 
@@ -12,7 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## v1.2.0
 
 - New `strokeColor` and `strokeWidth` text formatting options to control the outline of the text ([#292](https://github.com/stefcameron/text-to-canvas/issues/292)).
-    - Note that due to how the `strokeText()` and `measureText()` Canvas APIs work, the stroke is __not considered__ in text placement. Setting a large width will result in the stroke "bleeding" outside the text box.
+  - Note that due to how the `strokeText()` and `measureText()` Canvas APIs work, the stroke is __not considered__ in text placement. Setting a large width will result in the stroke "bleeding" outside the text box.
 
 ## v1.1.2
 

package/README.md

@@ -76,8 +76,8 @@ Use in Node is only supported to the extent that appropriate bundles are provide
 
 Two bundles are provided for this type of target:
 
-- `./dist/text-to-canvas.esm.min.js` (ESM, `import`, ES2020+)
-- `./dist/text-to-canvas.min.js` (CJS, `require()`, ES2019+)
+- `./dist/text-to-canvas.esm.min.js` (ESM, `import`, ES2022+)
+- `./dist/text-to-canvas.min.js` (CJS, `require()`, ES2022+)
 
 Used implicitly when using the library in a larger app bundled with a bundler like Webpack, Rollup, or Vite.
 
@@ -129,7 +129,7 @@ const { height } = drawText(...);
 
 One bundle is provided for this type of target:
 
-- `./dist/text-to-canvas.umd.min.js` (UMD, ES2019+)
+- `./dist/text-to-canvas.umd.min.js` (UMD, ES2022+)
 
 Used implicitly when loading the library directly in a browser:
 
@@ -148,8 +148,8 @@ Used implicitly when loading the library directly in a browser:
 
 Two bundles are provided for this type of target:
 
-- `./dist/text-to-canvas.mjs` (ESM/MJS, `import`, Node v20.11.1+)
-- `./dist/text-to-canvas.cjs` (CJS, `require()`, Node v20.11.1+)
+- `./dist/text-to-canvas.mjs` (ESM/MJS, `import`, Node v22+)
+- `./dist/text-to-canvas.cjs` (CJS, `require()`, Node v22+)
 
 > ⚠️ Other than the bundles, __Node is not formally supported by this library__, and neither is the `node-canvas` library used in the demo. Whatever "Node Canvas" library you use, make sure it supports the [HTMLCanvasElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement) API and it _should_ work.
 
@@ -188,6 +188,8 @@ You can run this demo locally with `npm run node:demo`
 | `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. |
+| `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. |
 | `debug`           | `false`      | Draws the border and alignment lines of the text box for debugging purposes. |

package/dist/text-to-canvas.cjs

@@ -6,22 +6,120 @@ const DEFAULT_FONT_COLOR = "black";
 const DEFAULT_STROKE_COLOR = DEFAULT_FONT_COLOR;
 const DEFAULT_STROKE_WIDTH = 0;
 const DEFAULT_STROKE_JOIN = "round";
-const getTextFormat = (format, baseFormat) => {
-  return Object.assign(
-    {},
-    {
-      fontFamily: DEFAULT_FONT_FAMILY,
-      fontSize: DEFAULT_FONT_SIZE,
-      fontWeight: "400",
-      fontStyle: "",
-      fontVariant: "",
-      fontColor: DEFAULT_FONT_COLOR,
-      strokeColor: DEFAULT_STROKE_COLOR,
-      strokeWidth: DEFAULT_STROKE_WIDTH
+const _formatMerge = (...sources) => {
+  const target = {
+    fontFamily: DEFAULT_FONT_FAMILY,
+    fontSize: DEFAULT_FONT_SIZE,
+    fontWeight: "400",
+    fontStyle: "",
+    fontVariant: "",
+    fontColor: DEFAULT_FONT_COLOR,
+    strokeColor: DEFAULT_STROKE_COLOR,
+    strokeWidth: DEFAULT_STROKE_WIDTH,
+    underline: {
+      color: DEFAULT_FONT_COLOR,
+      thickness: 0,
+      offset: 0
     },
-    baseFormat,
-    format
-  );
+    strikethrough: {
+      color: DEFAULT_FONT_COLOR,
+      thickness: 0,
+      offset: 0
+    }
+  };
+  sources.forEach((source) => {
+    if (source && typeof source === "object" && !Array.isArray(source)) {
+      Object.entries(source).forEach(([sourceKey, sourceValue]) => {
+        if (sourceValue !== void 0) {
+          if (sourceKey === "underline" || sourceKey === "strikethrough") {
+            if (typeof sourceValue === "boolean") {
+              if (sourceValue) {
+                target[sourceKey].color = "";
+                target[sourceKey].thickness = NaN;
+                target[sourceKey].offset = NaN;
+              }
+            } else if (sourceValue && typeof sourceValue === "object" && !Array.isArray(sourceValue)) {
+              const underStrikeSource = sourceValue;
+              const underStrikeSourceKeys = Object.keys(
+                underStrikeSource
+              );
+              underStrikeSourceKeys.forEach((k) => {
+                if (underStrikeSource[k] !== void 0) {
+                  target[sourceKey][k] = underStrikeSource[k];
+                }
+              });
+              if (!underStrikeSourceKeys.includes("color")) {
+                target[sourceKey].color = "";
+              }
+              if (!underStrikeSourceKeys.includes("thickness")) {
+                target[sourceKey].thickness = NaN;
+              }
+              if (!underStrikeSourceKeys.includes("offset")) {
+                target[sourceKey].offset = NaN;
+              }
+            }
+          } else {
+            target[sourceKey] = sourceValue;
+          }
+        }
+      });
+    }
+  });
+  return target;
+};
+const getTextFormat = (format, baseFormat) => {
+  const underStrikeProps = [
+    "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 fontSizeFactor = result.fontSize / 24;
+  underStrikeProps.forEach((prop) => {
+    if (result[prop].color === "") {
+      result[prop].color = result.fontColor;
+    }
+    if (Number.isNaN(result[prop].thickness)) {
+      result[prop].thickness = fontSizeFactor;
+    }
+    if (Number.isNaN(result[prop].offset)) {
+      if (result.fontFamily.startsWith("Roboto") || result.fontFamily.startsWith("Verdana")) {
+        result[prop].offset = -2;
+      } else if (result.fontFamily === "Inter" || result.fontFamily.startsWith("Montserrat")) {
+        result[prop].offset = -1;
+      } else if (result.fontFamily.startsWith("Comic Sans")) {
+        result[prop].offset = -5;
+      } else {
+        result[prop].offset = 0;
+      }
+      result[prop].offset *= fontSizeFactor;
+    }
+  });
+  return result;
 };
 const getTextStyle = ({
   fontFamily,
@@ -362,7 +460,7 @@ const splitWords = ({
     return {
       lines: [],
       textAlign: "center",
-      textBaseline: "middle",
+      textBaseline: "top",
       width: positioning.width,
       height: 0
     };
@@ -472,6 +570,72 @@ const getTextHeight = ({
 }) => {
   return _getHeight(ctx, text, style);
 };
+const _drawUnderline = ({
+  pw,
+  textBaseline,
+  baseFormat,
+  ctx
+}) => {
+  const lineWidth = pw.format?.underline.thickness ?? baseFormat.underline.thickness;
+  if (lineWidth <= 0) {
+    return;
+  }
+  ctx.save();
+  ctx.lineWidth = lineWidth;
+  ctx.strokeStyle = pw.format?.underline.color ?? baseFormat.underline.color;
+  let underlineY = pw.y;
+  switch (textBaseline) {
+    case "top":
+      underlineY += pw.height - (pw.word.metrics?.fontBoundingBoxDescent ?? 0);
+      break;
+    case "bottom":
+      underlineY -= (pw.word.metrics?.fontBoundingBoxDescent ?? 0) / 2;
+      break;
+    default: {
+      const never = textBaseline;
+      return never;
+    }
+  }
+  underlineY += pw.format?.underline.offset ?? baseFormat.underline.offset;
+  ctx.beginPath();
+  ctx.moveTo(pw.x, underlineY);
+  ctx.lineTo(pw.x + pw.width, underlineY);
+  ctx.stroke();
+  ctx.restore();
+};
+const _drawStrikethrough = ({
+  pw,
+  textBaseline,
+  baseFormat,
+  ctx
+}) => {
+  const lineWidth = pw.format?.strikethrough.thickness ?? baseFormat.strikethrough.thickness;
+  if (lineWidth <= 0) {
+    return;
+  }
+  ctx.save();
+  ctx.lineWidth = lineWidth;
+  ctx.strokeStyle = pw.format?.strikethrough.color ?? baseFormat.strikethrough.color;
+  let strikethroughY = pw.y;
+  switch (textBaseline) {
+    case "top":
+      strikethroughY += pw.height / 2;
+      break;
+    case "bottom":
+      strikethroughY -= pw.height / 2 - (pw.word.metrics?.fontBoundingBoxDescent ?? 0) / 3;
+      break;
+    default: {
+      const never = textBaseline;
+      return never;
+    }
+  }
+  strikethroughY += pw.format?.strikethrough.offset ?? baseFormat.strikethrough.offset;
+  ctx.beginPath();
+  ctx.moveTo(pw.x, strikethroughY);
+  ctx.lineTo(pw.x + pw.width, strikethroughY);
+  ctx.stroke();
+  ctx.restore();
+};
 const drawText = (ctx, text, config) => {
   const baseFormat = getTextFormat({
     fontFamily: config.fontFamily,
@@ -481,7 +645,9 @@ const drawText = (ctx, text, config) => {
     fontWeight: config.fontWeight,
     fontColor: config.fontColor,
     strokeColor: config.strokeColor,
-    strokeWidth: config.strokeWidth
+    strokeWidth: config.strokeWidth,
+    underline: config.underline,
+    strikethrough: config.strikethrough
   });
   const {
     width: boxWidth,
@@ -544,6 +710,8 @@ const drawText = (ctx, text, config) => {
           ctx.restore();
         }
       }
+      _drawUnderline({ pw, textBaseline, baseFormat, ctx });
+      _drawStrikethrough({ pw, textBaseline, baseFormat, ctx });
     });
   });
   if (config.debug) {