@altano/satori-fit-text 0.0.1

package/README.md

@@ -0,0 +1,52 @@
+# satori-fit-text
+
+Uses [Satori](https://github.com/vercel/satori) to calculate the largest text font size that will fit a bounding box.
+
+## Installation
+
+```sh
+# Using NPM
+npm install @altano/satori-fit-text
+# Using Yarn
+yarn add @altano/satori-fit-text
+# Using PNPM
+pnpm add @altano/satori-fit-text
+```
+
+## Example Usage
+
+```ts
+import { findLargestUsableFontSize, type Font } from "@altano/satori-fit-text";
+
+async function getInter(): Promise<Font> {
+  const interSemiBoldBuffer = await fetch(`https://rsms.me/inter/font-files/Inter-SemiBold.woff`).then((res) => res.arrayBuffer());
+
+  const font = {
+    name: "Inter",
+    data: interSemiBoldBuffer,
+    weight: 600,
+  };
+}
+
+const largestUsableFontSize = await findLargestUsableFontSize({
+  lineHeight: 1,
+  font: await getFont(),
+  text: "Some text I want to be as big as possible",
+  maxWidth: 1136,
+  maxHeight: 429,
+});
+
+console.log(largestUsableFontSize);
+```
+
+## Potential Uses
+
+Because this measures the maximum font size using Satori, the ideal use of this library is to determine the largest possible font size in something like an [Open Graph card](https://ogp.me/). If you dynamically generate Open Graph cards with text (e.g. the title of your blog post) you may want the text to fill the card's area as best as possible without overflowing. This library can help you achieve that.
+
+## Implementation
+
+The library tries various font sizes until it finds the ideal one that works. Each iteration is tested by generating an SVG with Satori. The SVG dimensions are found using [SVG.js])(https://svgjs.dev/docs/3.0/).
+
+## Performance
+
+The font size search is a binary search between 1 and 1000 with `O(log maxFontSize-minFontSize)` runtime, or a default of `O(log 1000)`. You can restrict the search space (by reducing the difference between `minFontSize` or `maxFontSize`) to reduce the number of guesses and improve performance.

package/dist/TextMeasurer.d.ts

@@ -0,0 +1,12 @@
+import type { Font } from "./types";
+export declare class TextMeasurer {
+    #private;
+    private text;
+    private font;
+    private maxWidth;
+    private maxHeight;
+    private lineHeight;
+    constructor(text: string, font: Font, maxWidth: number, maxHeight: number, lineHeight: number | "normal");
+    doesSizeFit(fontSize: number): Promise<boolean>;
+}
+//# sourceMappingURL=TextMeasurer.d.ts.map

package/dist/fitText.d.ts

@@ -0,0 +1,43 @@
+import type { Font } from "./types";
+export type FindOptions = {
+    /**
+     * The text you want to fit
+     */
+    text: string;
+    /**
+     * The font of your text. Options are the same as [those taken by
+     * Satori](https://github.com/vercel/satori#fonts), but only one font and not
+     * an array of fonts is accepted here.
+     */
+    font: Font;
+    /**
+     * The max width the text must be contained in
+     */
+    maxWidth: number;
+    /**
+     * The max height the text must be contained in
+     */
+    maxHeight: number;
+    /**
+     * Optional: the CSS line height factor to use, e.g. 1.1
+     */
+    lineHeight?: number | "normal";
+    /**
+     * The minimum font size that should be returned, even if smaller fonts fit
+     */
+    minFontSize?: number;
+    /**
+     * The maximum font size that should be returned, even if larger fonts fit
+     */
+    maxFontSize?: number;
+    /**
+     * The maximum number of font sizes to try before giving up. Defaults to 1000.
+     */
+    maxTries?: number;
+};
+/**
+ * Given text, dimensions, and some options, returns the largest font size that
+ * would keep the text contained within the dimensions.
+ */
+export declare function findLargestUsableFontSize({ text, font, maxWidth, maxHeight, lineHeight, minFontSize, maxFontSize, maxTries, }: FindOptions): Promise<number>;
+//# sourceMappingURL=fitText.d.ts.map

package/dist/getSatoriFriendlyVNode.d.ts

@@ -0,0 +1,4 @@
+import { html as htmlToVNode } from "satori-html";
+export type VNode = ReturnType<typeof htmlToVNode>;
+export default function getSatoriFriendlyVNode(html: string): VNode;
+//# sourceMappingURL=getSatoriFriendlyVNode.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./fitText";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,129 @@
+// src/TextMeasurer.ts
+import { SVG, registerWindow } from "@svgdotjs/svg.js";
+import satori from "satori";
+
+// src/getSatoriFriendlyVNode.ts
+import { html as htmlToVNode } from "satori-html";
+import he from "he";
+function walkJsxTree(vnode, callback) {
+  callback(vnode);
+  const { children } = vnode.props;
+  if (children == null || typeof children === "string") {
+    return;
+  } else if (Array.isArray(children)) {
+    children.forEach((child) => walkJsxTree(child, callback));
+  } else {
+    walkJsxTree(children, callback);
+  }
+}
+function patchJsxTreeForSatori(vnode) {
+  walkJsxTree(vnode, (vnode2) => {
+    const { style } = vnode2.props;
+    if (style != null && typeof style["lineHeight"] === "string" && style["lineHeight"] != "") {
+      const num = Number(style["lineHeight"]);
+      if (!isNaN(num)) {
+        style["lineHeight"] = num;
+      }
+    }
+  });
+}
+function getSatoriFriendlyVNode(html) {
+  const htmlWithDecodedHtmlEntities = he.decode(html);
+  const vnode = htmlToVNode(htmlWithDecodedHtmlEntities);
+  patchJsxTreeForSatori(vnode);
+  return vnode;
+}
+
+// src/TextMeasurer.ts
+import { createSVGWindow } from "svgdom";
+var TextMeasurer = class {
+  constructor(text, font, maxWidth, maxHeight, lineHeight) {
+    this.text = text;
+    this.font = font;
+    this.maxWidth = maxWidth;
+    this.maxHeight = maxHeight;
+    this.lineHeight = lineHeight;
+    const window = createSVGWindow();
+    const document = window.document;
+    registerWindow(window, document);
+    this.#canvas = SVG(document.documentElement);
+  }
+  #canvas;
+  async doesSizeFit(fontSize) {
+    await this.#setFontSize(fontSize);
+    const { width, height } = this.#canvas.bbox();
+    return width <= this.maxWidth && height <= this.maxHeight;
+  }
+  async #generateSvg(fontSize) {
+    const html = `
+      <div style="
+        margin: 0;
+        padding: 0;
+        font-size: ${fontSize}px;
+        max-width: ${this.maxWidth}px;
+        line-height: ${this.lineHeight};
+        border: solid red 1px;
+      ">
+        ${this.text}
+      </div>
+    `.trim();
+    const vnode = getSatoriFriendlyVNode(html);
+    return satori(vnode, {
+      fonts: [
+        {
+          name: this.font.name,
+          data: this.font.data
+        }
+      ],
+      width: this.maxWidth * 2,
+      height: this.maxHeight * 2
+    });
+  }
+  async #setFontSize(fontSize) {
+    const svgText = await this.#generateSvg(fontSize);
+    this.#canvas.clear();
+    this.#canvas.svg(svgText);
+  }
+};
+
+// src/fitText.ts
+async function findLargestUsableFontSize({
+  text,
+  font,
+  maxWidth,
+  maxHeight,
+  lineHeight = "normal",
+  minFontSize = 1,
+  maxFontSize = 1e3,
+  maxTries = 1e3
+}) {
+  if (maxTries < 2) {
+    throw new Error("`maxTries` must be >= 2");
+  }
+  const textMeasurer = new TextMeasurer(
+    text,
+    font,
+    maxWidth,
+    maxHeight,
+    lineHeight
+  );
+  for (let tries = 1, lower = minFontSize, upper = maxFontSize; tries < maxTries; ++tries) {
+    const searchCutoffThreshold = Math.min(1, lower);
+    if (upper - lower <= searchCutoffThreshold) {
+      return Math.floor(lower);
+    }
+    const sizeCandidate = Math.floor(lower + (upper - lower) / 2);
+    const doesFit = await textMeasurer.doesSizeFit(sizeCandidate);
+    if (doesFit) {
+      lower = sizeCandidate;
+    } else {
+      upper = sizeCandidate;
+    }
+  }
+  throw new Error(
+    `Could not find a valid font size in ${maxTries - 1} attempts. Giving up. Please try again after constraining the search space, e.g. by restricting the min/max font size difference.`
+  );
+}
+export {
+  findLargestUsableFontSize
+};

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+import type { Font as SatoriFont } from "satori";
+export type Font = SatoriFont;
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@altano/satori-fit-text",
+  "version": "0.0.1",
+  "description": "Fit text to a bounding box in Node or the browser",
+  "type": "module",
+  "sideEffects": false,
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": {
+    "name": "Alan Norbauer",
+    "email": "altano@gmail.com",
+    "url": "https://alan.norbauer.com"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/altano/npm-packages",
+    "directory": "packages/satori-fit-text"
+  },
+  "homepage": "https://github.com/altano/npm-packages/tree/main/packages/satori-fit-text",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@svgdotjs/svg.js": "^3.2.0",
+    "he": "^1.2.0",
+    "satori": "^0.10.3",
+    "satori-html": "^0.3.2",
+    "svgdom": "^0.1.14"
+  },
+  "devDependencies": {
+    "@resvg/resvg-js": "^2.4.1",
+    "@types/he": "^1.2.0",
+    "@types/jest-image-snapshot": "^6.2.0",
+    "@types/react": "^18.2.21",
+    "@types/react-dom": "^18.2.7",
+    "@vitest/coverage-v8": "^0.34.3",
+    "@vitest/ui": "^0.30.1",
+    "jest-image-snapshot": "^6.2.0",
+    "npm-run-all": "^4.1.5",
+    "react": "^18",
+    "react-dom": "^18",
+    "tsup": "^7.2.0",
+    "typescript": "^5.1.6",
+    "vite": "^4.4.9",
+    "vitest": "^0.34.3",
+    "@altano/assets": "^0.0.0",
+    "@altano/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:types": "tsc --emitDeclarationOnly --declaration",
+    "dev": "tsup --watch",
+    "lint": "eslint src/**/*.ts*",
+    "lint:timing": "TIMING=1 eslint src/**/*.ts*",
+    "lint:fix": "TIMING=1 eslint src/**/*.ts* --fix",
+    "format": "prettier --write src",
+    "clean": "rm -rf .turbo && rm -rf .tsbuildinfo && rm -rf node_modules && rm -rf dist",
+    "test": "run-s test:unit test:benchmark",
+    "test:unit": "vitest --run",
+    "test:benchmark": "vitest --run bench",
+    "test:watch": "vitest tests/"
+  }
+}