@effing/canvas 0.23.2 → 0.24.0

package/README.md

@@ -93,6 +93,23 @@ Emoji characters are automatically rendered as images from CDNs. Supported style
 
 Pass `emoji: "none"` to disable emoji image rendering.
 
+## Fit Text
+
+Find the largest font size that keeps text within a bounding box, using binary search over the built-in text layout engine:
+
+```typescript
+import { findLargestUsableFontSize } from "@effing/canvas";
+
+const fontSize = findLargestUsableFontSize({
+  text: "Hello World",
+  font,
+  maxWidth: 500,
+  maxHeight: 100,
+});
+```
+
+Supports optional `lineHeight` (`"normal"` or a numeric multiplier), `minFontSize` (default 1), and `maxFontSize` (default 1000).
+
 ## Lottie Animations
 
 Render individual frames of Lottie animations to a canvas:
@@ -265,6 +282,30 @@ function renderLottieFrame(
 ): void;
 ```
 
+### `findLargestUsableFontSize(options)`
+
+Find the largest integer font size that keeps text within the given bounds. Uses binary search with the built-in text layout engine — no external dependencies needed.
+
+```typescript
+function findLargestUsableFontSize(
+  options: FindLargestUsableFontSizeOptions,
+): number;
+```
+
+```typescript
+import { findLargestUsableFontSize } from "@effing/canvas";
+
+const fontSize = findLargestUsableFontSize({
+  text: "Hello World",
+  font,
+  maxWidth: 500,
+  maxHeight: 100,
+  lineHeight: "normal", // optional (default: "normal")
+  minFontSize: 1, // optional (default: 1)
+  maxFontSize: 200, // optional (default: 1000)
+});
+```
+
 ### Font Helpers
 
 - `registerFont(font)` — Register a font from a `FontData` buffer (idempotent)

package/dist/index.d.ts

@@ -133,6 +133,33 @@ declare function registerFontFromPath(path: string, nameAlias?: string): void;
  */
 declare function registeredFamilies(): string[];
 
+/**
+ * Options for {@link findLargestUsableFontSize}.
+ */
+type FindLargestUsableFontSizeOptions = {
+    /** The text to fit */
+    text: string;
+    /** Font data to use for measurement */
+    font: FontData;
+    /** Maximum width in pixels */
+    maxWidth: number;
+    /** Maximum height in pixels */
+    maxHeight: number;
+    /** Line height — `"normal"` uses font metrics, numeric values are CSS multipliers */
+    lineHeight?: number | "normal";
+    /** Minimum font size to consider (default: 1) */
+    minFontSize?: number;
+    /** Maximum font size to consider (default: 1000) */
+    maxFontSize?: number;
+};
+/**
+ * Find the largest integer font size that keeps text within the given bounds.
+ *
+ * Uses binary search over integer font sizes, measuring with {@link layoutText}
+ * at each step. Returns `minFontSize` if even the smallest size overflows.
+ */
+declare function findLargestUsableFontSize(options: FindLargestUsableFontSizeOptions): number;
+
 declare function createCanvas(width: number, height: number): _napi_rs_canvas.Canvas;
 
-export { type EmojiStyle, type FontData, type RenderReactElementOptions, createCanvas, loadLottie, registerFont, registerFontFromPath, registeredFamilies, renderLottieFrame, renderReactElement };
+export { type EmojiStyle, type FindLargestUsableFontSizeOptions, type FontData, type RenderReactElementOptions, createCanvas, findLargestUsableFontSize, loadLottie, registerFont, registerFontFromPath, registeredFamilies, renderLottieFrame, renderReactElement };

package/dist/index.js

@@ -3660,6 +3660,41 @@ async function renderReactElement(ctx, element, options) {
   );
 }
 
+// src/fit-text.ts
+function findLargestUsableFontSize(options) {
+  const {
+    text,
+    font,
+    maxWidth,
+    maxHeight,
+    lineHeight = "normal",
+    minFontSize = 1,
+    maxFontSize = 1e3
+  } = options;
+  registerFont(font);
+  let lo = minFontSize;
+  let hi = maxFontSize;
+  let best = minFontSize;
+  while (lo <= hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    const style = {
+      fontSize: mid,
+      fontFamily: font.name,
+      fontWeight: font.weight,
+      fontStyle: font.style,
+      lineHeight: lineHeight === "normal" ? void 0 : lineHeight
+    };
+    const result = layoutText(text, style, maxWidth);
+    if (result.width <= maxWidth && result.height <= maxHeight) {
+      best = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return best;
+}
+
 // src/index.ts
 function createCanvas3(width, height) {
   const canvas = _createCanvas(width, height);
@@ -3673,6 +3708,7 @@ export {
   Image,
   LottieAnimation,
   createCanvas3 as createCanvas,
+  findLargestUsableFontSize,
   loadImage3 as loadImage,
   loadLottie,
   registerFont,