@effing/canvas 0.19.3 → 0.20.1

package/README.md

@@ -69,7 +69,7 @@ JSX → Yoga layout → Skia canvas → PNG
 2. **Skia** draws each node to a canvas context (backgrounds, borders, text, images, SVG, gradients)
 3. **Encode** the canvas to PNG or JPEG via `canvas.encode()` or `canvas.encodeSync()`
 
-Canvas dimensions are taken from the context itself (`ctx.canvas.width` / `ctx.canvas.height`), so there are no `width`/`height` options — just create a canvas at the size you need.
+Canvas dimensions default to `ctx.canvas.width` / `ctx.canvas.height`, but you can override them with the `width` and `height` options. This is useful for HiDPI rendering where the canvas is larger than the logical layout size.
 
 ### Font Loading
 
@@ -123,6 +123,114 @@ renderLottieFrame(ctx, anim, 0); // render frame 0
 const png = canvas.encodeSync("png");
 ```
 
+## Supported CSS Properties
+
+### Layout
+
+| Property                         | Values / Notes                                      |
+| -------------------------------- | --------------------------------------------------- |
+| `display`                        | `flex`, `none`                                      |
+| `position`                       | `relative`, `absolute`                              |
+| `top`, `right`, `bottom`, `left` | Length, percentage                                  |
+| `overflow`                       | `visible`, `hidden` (also `overflowX`, `overflowY`) |
+
+### Flexbox
+
+| Property              | Values / Notes                                                                      |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `flexDirection`       | `row`, `column`, `row-reverse`, `column-reverse`                                    |
+| `flexWrap`            | `nowrap`, `wrap`, `wrap-reverse`                                                    |
+| `justifyContent`      | `flex-start`, `flex-end`, `center`, `space-between`, `space-around`, `space-evenly` |
+| `alignItems`          | `flex-start`, `flex-end`, `center`, `stretch`, `baseline`                           |
+| `alignSelf`           | `auto`, `flex-start`, `flex-end`, `center`, `stretch`, `baseline`                   |
+| `alignContent`        | `flex-start`, `flex-end`, `center`, `stretch`, `space-between`, `space-around`      |
+| `flex`                | Shorthand for `flexGrow`, `flexShrink`, `flexBasis`                                 |
+| `flexGrow`            | Number                                                                              |
+| `flexShrink`          | Number                                                                              |
+| `flexBasis`           | Length, percentage                                                                  |
+| `gap`                 | Shorthand for `rowGap`, `columnGap`                                                 |
+| `rowGap`, `columnGap` | Number                                                                              |
+
+### Dimensions
+
+| Property                | Values / Notes     |
+| ----------------------- | ------------------ |
+| `width`, `height`       | Length, percentage |
+| `minWidth`, `minHeight` | Length, percentage |
+| `maxWidth`, `maxHeight` | Length, percentage |
+
+### Spacing
+
+| Property                                                     | Values / Notes                          |
+| ------------------------------------------------------------ | --------------------------------------- |
+| `margin`                                                     | Shorthand (1–4 values), supports `auto` |
+| `marginTop`, `marginRight`, `marginBottom`, `marginLeft`     | Length, percentage, `auto`              |
+| `padding`                                                    | Shorthand (1–4 values)                  |
+| `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` | Length, percentage                      |
+
+### Border
+
+| Property                                                 | Values / Notes                      |
+| -------------------------------------------------------- | ----------------------------------- |
+| `border`                                                 | Shorthand, e.g. `"1px solid black"` |
+| `borderTop`, `borderRight`, `borderBottom`, `borderLeft` | Per-side shorthand                  |
+| `borderWidth`, `borderColor`, `borderStyle`              | Shorthand (1–4 values)              |
+| `border{Top,Right,Bottom,Left}{Width,Color,Style}`       | Per-side longhands                  |
+| `borderRadius`                                           | Shorthand (1–4 values)              |
+| `border{TopLeft,TopRight,BottomRight,BottomLeft}Radius`  | Per-corner longhands                |
+
+### Color & Background
+
+| Property          | Values / Notes                                     |
+| ----------------- | -------------------------------------------------- |
+| `color`           | Any CSS color (inherited)                          |
+| `backgroundColor` | Any CSS color                                      |
+| `opacity`         | Number (0–1)                                       |
+| `background`      | Shorthand → `backgroundColor` or `backgroundImage` |
+| `backgroundImage` | `linear-gradient()`, `radial-gradient()`, `url()`  |
+| `backgroundSize`  | `cover`, `contain`, length, percentage             |
+
+### 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)                           |
+
+### Effects
+
+| Property          | Values / Notes                                   |
+| ----------------- | ------------------------------------------------ |
+| `boxShadow`       | CSS box-shadow string                            |
+| `textShadow`      | CSS text-shadow string                           |
+| `transform`       | `translate`, `scale`, `rotate`, `skewX`, `skewY` |
+| `transformOrigin` | CSS transform-origin string                      |
+| `filter`          | CSS filter string                                |
+
+### Image
+
+| Property    | Values / Notes                                   |
+| ----------- | ------------------------------------------------ |
+| `objectFit` | `contain`, `cover`, `fill`, `none`, `scale-down` |
+
+### Units
+
+`px`, `em`, `rem`, `%`, `vw`, `vh`, `vmin`, `vmax`, `pt`, `pc`, `in`, `cm`, `mm`
+
 ## API Overview
 
 ### `createCanvas(width, height)`
@@ -176,11 +284,13 @@ function renderLottieFrame(
 
 ### Options
 
-| Option  | Type                   | Required | Description                              |
-| ------- | ---------------------- | -------- | ---------------------------------------- |
-| `fonts` | `FontData[]`           | Yes      | Font data for text rendering             |
-| `debug` | `boolean`              | No       | Draw layout bounding boxes for debugging |
-| `emoji` | `EmojiStyle \| "none"` | No       | Emoji style (default: `"twemoji"`)       |
+| Option   | Type                   | Required | Description                                           |
+| -------- | ---------------------- | -------- | ----------------------------------------------------- |
+| `fonts`  | `FontData[]`           | Yes      | Font data for text rendering                          |
+| `width`  | `number`               | No       | Layout width override (default: `ctx.canvas.width`)   |
+| `height` | `number`               | No       | Layout height override (default: `ctx.canvas.height`) |
+| `debug`  | `boolean`              | No       | Draw layout bounding boxes for debugging              |
+| `emoji`  | `EmojiStyle \| "none"` | No       | Emoji style (default: `"twemoji"`)                    |
 
 ### Types
 
@@ -276,6 +386,25 @@ await renderReactElement(ctx, <MyComponent />, {
 });
 ```
 
+### HiDPI Rendering
+
+For sharp output on high-DPI displays, you can create a larger canvas and use `width`/`height` overrides to keep layout at the logical size:
+
+```typescript
+const dpr = 2;
+const canvas = createCanvas(1080 * dpr, 1080 * dpr);
+const ctx = canvas.getContext("2d");
+ctx.scale(dpr, dpr);
+
+await renderReactElement(ctx, <MyComponent />, {
+  fonts,
+  width: 1080,
+  height: 1080,
+});
+
+const png = await canvas.encode("png");
+```
+
 ## Related Packages
 
 - [`@effing/tween`](../tween) — Step iteration and easing for frame generation

package/dist/index.d.ts

@@ -63,6 +63,10 @@ type FontData = {
 type RenderReactElementOptions = {
     /** Font data for text rendering */
     fonts: FontData[];
+    /** Layout width override. Defaults to `ctx.canvas.width`. */
+    width?: number;
+    /** Layout height override. Defaults to `ctx.canvas.height`. */
+    height?: number;
     /** Draw layout bounding boxes for debugging */
     debug?: boolean;
     /** Emoji style for rendering emoji characters as images. Defaults to "twemoji". Pass "none" to disable. */
@@ -72,12 +76,13 @@ type RenderReactElementOptions = {
 /**
  * Render a React element tree to a canvas context.
  *
- * Width and height are taken from the canvas itself (`ctx.canvas.width` /
- * `ctx.canvas.height`).
+ * Width and height default to `ctx.canvas.width` / `ctx.canvas.height` but
+ * can be overridden via `options.width` and `options.height`. This is useful
+ * for HiDPI rendering where the canvas is larger than the logical layout size.
  *
  * @param ctx - Canvas 2D rendering context to draw into
  * @param element - React element tree to render
- * @param options - Rendering options (fonts, debug mode)
+ * @param options - Rendering options (fonts, dimensions, debug mode)
  *
  * @example
  * ```tsx
@@ -90,6 +95,20 @@ type RenderReactElementOptions = {
  *
  * const png = canvas.encodeSync("png");
  * ```
+ *
+ * @example HiDPI rendering (2x)
+ * ```tsx
+ * const dpr = 2;
+ * const canvas = createCanvas(1080 * dpr, 1080 * dpr);
+ * const ctx = canvas.getContext("2d");
+ * ctx.scale(dpr, dpr);
+ *
+ * await renderReactElement(ctx, <MyComponent />, {
+ *   fonts: [myFont],
+ *   width: 1080,
+ *   height: 1080,
+ * });
+ * ```
  */
 declare function renderReactElement(ctx: SKRSContext2D, element: ReactNode, options: RenderReactElementOptions): Promise<void>;
 

package/dist/index.js

@@ -21,7 +21,7 @@ function renderLottieFrame(ctx, animation, frame) {
 }
 
 // src/jsx/draw/index.ts
-import { createCanvas as createCanvas2, loadImage as loadImage3 } from "@napi-rs/canvas";
+import { loadImage as loadImage3 } from "@napi-rs/canvas";
 
 // src/jsx/language.ts
 function isEmoji(char) {
@@ -303,6 +303,21 @@ function layoutText(text, style, maxWidth, ctx, emojiEnabled) {
       );
     }
   }
+  const lineClamp = style.lineClamp;
+  if (lineClamp && lineClamp > 0 && lines.length > lineClamp) {
+    const lastLineText = lines.slice(lineClamp - 1).join(" ");
+    lines.length = lineClamp;
+    lines[lineClamp - 1] = truncateWithEllipsis(
+      lastLineText,
+      maxWidth,
+      fontSize,
+      fontFamily,
+      fontWeight,
+      fontStyle,
+      ctx,
+      letterSpacing
+    );
+  }
   const segments = [];
   let totalHeight = 0;
   let maxLineWidth = 0;
@@ -490,7 +505,7 @@ function truncateWithEllipsis(text, maxWidth, fontSize, fontFamily, fontWeight,
     letterSpacing
   );
   const availWidth = maxWidth - ellipsisWidth;
-  for (let i = text.length - 1; i > 0; i--) {
+  for (let i = text.length; i > 0; i--) {
     const truncated = text.slice(0, i);
     const w = measureWord(
       truncated,
@@ -737,6 +752,37 @@ async function drawImage(ctx, src, x, y, width, height, style, preloadedImage) {
   }
 }
 
+// src/jsx/draw/offscreen.ts
+import { createCanvas as createCanvas2 } from "@napi-rs/canvas";
+var canvasPool = /* @__PURE__ */ new Map();
+function acquireOffscreen(w, h) {
+  const key = `${w}x${h}`;
+  const stack = canvasPool.get(key);
+  if (stack) {
+    while (stack.length > 0) {
+      const ref = stack.pop();
+      const canvas2 = ref.deref();
+      if (canvas2) {
+        const ctx = canvas2.getContext("2d");
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        ctx.clearRect(0, 0, w, h);
+        return [canvas2, ctx];
+      }
+    }
+  }
+  const canvas = createCanvas2(w, h);
+  return [canvas, canvas.getContext("2d")];
+}
+function releaseOffscreen(canvas) {
+  const key = `${canvas.width}x${canvas.height}`;
+  let stack = canvasPool.get(key);
+  if (!stack) {
+    stack = [];
+    canvasPool.set(key, stack);
+  }
+  stack.push(new WeakRef(canvas));
+}
+
 // src/jsx/draw/utils.ts
 function parseCSSLength(value, referenceSize) {
   if (value.endsWith("%")) return parseFloat(value) / 100 * referenceSize;
@@ -911,17 +957,19 @@ function mergeStyleIntoProps(props) {
 function collectDefs(children) {
   const clips = /* @__PURE__ */ new Map();
   const gradients = /* @__PURE__ */ new Map();
+  const masks = /* @__PURE__ */ new Map();
   for (const child of children) {
     if (child.type !== "defs") continue;
     for (const def of normalizeChildren(child)) {
       const id = def.props.id;
       if (!id) continue;
       if (def.type === "clipPath") clips.set(id, normalizeChildren(def));
+      else if (def.type === "mask") masks.set(id, normalizeChildren(def));
       else if (def.type === "radialGradient" || def.type === "linearGradient")
         gradients.set(id, def);
     }
   }
-  return { clips, gradients };
+  return { clips, gradients, masks };
 }
 function parseUrlRef(value) {
   if (typeof value !== "string") return void 0;
@@ -1211,13 +1259,23 @@ function buildPath(child, vbW, vbH) {
       return p;
     }
     case "rect": {
-      const rx = svgLength(props.x, vbW);
-      const ry = svgLength(props.y, vbH);
+      const x = svgLength(props.x, vbW);
+      const y = svgLength(props.y, vbH);
       const w = svgLength(props.width, vbW);
       const h = svgLength(props.height, vbH);
       if (w <= 0 || h <= 0) return void 0;
+      const rxRaw = svgLength(props.rx, vbW, -1);
+      const ryRaw = svgLength(props.ry, vbH, -1);
+      let rx = rxRaw >= 0 ? rxRaw : ryRaw >= 0 ? ryRaw : 0;
+      let ry = ryRaw >= 0 ? ryRaw : rx;
+      rx = Math.min(rx, w / 2);
+      ry = Math.min(ry, h / 2);
       const p = new Path2D();
-      p.rect(rx, ry, w, h);
+      if (rx > 0 || ry > 0) {
+        p.roundRect(x, y, w, h, [rx]);
+      } else {
+        p.rect(x, y, w, h);
+      }
       return p;
     }
     case "ellipse": {
@@ -1294,43 +1352,67 @@ function drawSvgContainer(ctx, node, x, y, width, height) {
 }
 var EMPTY_DEFS = {
   clips: /* @__PURE__ */ new Map(),
-  gradients: /* @__PURE__ */ new Map()
+  gradients: /* @__PURE__ */ new Map(),
+  masks: /* @__PURE__ */ new Map()
 };
 function drawSvgChild(ctx, child, inheritedFill, color, defs = EMPTY_DEFS, vbW = 0, vbH = 0) {
   const { type } = child;
   const props = mergeStyleIntoProps(child.props);
-  if (type === "defs" || type === "clipPath") return;
+  if (type === "defs" || type === "clipPath" || type === "mask") return;
   const clipRef = parseUrlRef(props.clipPath ?? props["clip-path"]);
   const clipShapes = clipRef ? defs.clips.get(clipRef) : void 0;
   const clipPath = clipShapes ? buildClipPath(clipShapes, vbW, vbH) : void 0;
+  const maskRef = parseUrlRef(props.mask);
+  const maskShapes = maskRef ? defs.masks.get(maskRef) : void 0;
   if (clipPath) ctx.save();
   if (clipPath) ctx.clip(clipPath);
+  let elemCanvas;
+  const targetCtx = maskShapes ? (() => {
+    const [c, cCtx] = acquireOffscreen(Math.ceil(vbW), Math.ceil(vbH));
+    elemCanvas = c;
+    return cCtx;
+  })() : ctx;
   switch (type) {
     case "path":
-      drawPath(ctx, props, inheritedFill, color, defs);
+      drawPath(targetCtx, props, inheritedFill, color, defs);
       break;
     case "circle":
-      drawCircle(ctx, props, inheritedFill, color, defs, vbW, vbH);
+      drawCircle(targetCtx, props, inheritedFill, color, defs, vbW, vbH);
       break;
     case "rect":
-      drawSvgRect(ctx, props, inheritedFill, color, defs, vbW, vbH);
+      drawSvgRect(targetCtx, props, inheritedFill, color, defs, vbW, vbH);
       break;
     case "line":
-      drawLine(ctx, props, color, defs, vbW, vbH);
+      drawLine(targetCtx, props, color, defs, vbW, vbH);
       break;
     case "ellipse":
-      drawEllipse(ctx, props, inheritedFill, color, defs, vbW, vbH);
+      drawEllipse(targetCtx, props, inheritedFill, color, defs, vbW, vbH);
       break;
     case "polygon":
-      drawPolygon(ctx, props, inheritedFill, color, defs);
+      drawPolygon(targetCtx, props, inheritedFill, color, defs);
       break;
     case "polyline":
-      drawPolyline(ctx, props, inheritedFill, color, defs);
+      drawPolyline(targetCtx, props, inheritedFill, color, defs);
       break;
     case "g":
-      drawGroup(ctx, child, inheritedFill, color, defs, vbW, vbH);
+      drawGroup(targetCtx, child, inheritedFill, color, defs, vbW, vbH);
       break;
   }
+  if (maskShapes && elemCanvas) {
+    const [maskCanvas, maskCtx] = acquireOffscreen(
+      Math.ceil(vbW),
+      Math.ceil(vbH)
+    );
+    for (const shape of maskShapes) {
+      drawSvgChild(maskCtx, shape, "white", "white", defs, vbW, vbH);
+    }
+    targetCtx.globalCompositeOperation = "destination-in";
+    targetCtx.drawImage(maskCanvas, 0, 0);
+    targetCtx.globalCompositeOperation = "source-over";
+    ctx.drawImage(elemCanvas, 0, 0);
+    releaseOffscreen(maskCanvas);
+    releaseOffscreen(elemCanvas);
+  }
   if (clipPath) ctx.restore();
 }
 function drawPath(ctx, props, inheritedFill, color, defs) {
@@ -1351,14 +1433,24 @@ function drawCircle(ctx, props, inheritedFill, color, defs, vbW = 0, vbH = 0) {
   applyFillAndStroke(ctx, props, path, inheritedFill, color, defs, bbox);
 }
 function drawSvgRect(ctx, props, inheritedFill, color, defs, vbW = 0, vbH = 0) {
-  const rx = svgLength(props.x, vbW);
-  const ry = svgLength(props.y, vbH);
+  const x = svgLength(props.x, vbW);
+  const y = svgLength(props.y, vbH);
   const w = svgLength(props.width, vbW);
   const h = svgLength(props.height, vbH);
   if (w <= 0 || h <= 0) return;
+  const rxRaw = svgLength(props.rx, vbW, -1);
+  const ryRaw = svgLength(props.ry, vbH, -1);
+  let rx = rxRaw >= 0 ? rxRaw : ryRaw >= 0 ? ryRaw : 0;
+  let ry = ryRaw >= 0 ? ryRaw : rx;
+  rx = Math.min(rx, w / 2);
+  ry = Math.min(ry, h / 2);
   const path = new Path2D();
-  path.rect(rx, ry, w, h);
-  const bbox = { x: rx, y: ry, width: w, height: h };
+  if (rx > 0 || ry > 0) {
+    path.roundRect(x, y, w, h, [rx]);
+  } else {
+    path.rect(x, y, w, h);
+  }
+  const bbox = { x, y, width: w, height: h };
   applyFillAndStroke(ctx, props, path, inheritedFill, color, defs, bbox);
 }
 function drawLine(ctx, props, color, defs, vbW = 0, vbH = 0) {
@@ -1761,34 +1853,6 @@ function drawTextDecoration(ctx, seg, offsetX, offsetY) {
 }
 
 // src/jsx/draw/index.ts
-var canvasPool = /* @__PURE__ */ new Map();
-function acquireOffscreen(w, h) {
-  const key = `${w}x${h}`;
-  const stack = canvasPool.get(key);
-  if (stack) {
-    while (stack.length > 0) {
-      const ref = stack.pop();
-      const canvas2 = ref.deref();
-      if (canvas2) {
-        const ctx = canvas2.getContext("2d");
-        ctx.setTransform(1, 0, 0, 1, 0, 0);
-        ctx.clearRect(0, 0, w, h);
-        return [canvas2, ctx];
-      }
-    }
-  }
-  const canvas = createCanvas2(w, h);
-  return [canvas, canvas.getContext("2d")];
-}
-function releaseOffscreen(canvas) {
-  const key = `${canvas.width}x${canvas.height}`;
-  let stack = canvasPool.get(key);
-  if (!stack) {
-    stack = [];
-    canvasPool.set(key, stack);
-  }
-  stack.push(new WeakRef(canvas));
-}
 async function drawNode(ctx, node, parentX, parentY, debug, emojiStyle) {
   const x = parentX + node.x;
   const y = parentY + node.y;
@@ -2363,6 +2427,7 @@ var INHERITABLE_PROPS = [
   "whiteSpace",
   "wordBreak",
   "textOverflow",
+  "lineClamp",
   "textBoxTrim",
   "textBoxEdge"
 ];
@@ -3021,8 +3086,8 @@ function hasElementChildren(children) {
 // src/jsx/index.ts
 async function renderReactElement(ctx, element, options) {
   ensureFontsRegistered(options.fonts);
-  const width = ctx.canvas.width;
-  const height = ctx.canvas.height;
+  const width = options.width ?? ctx.canvas.width;
+  const height = options.height ?? ctx.canvas.height;
   const emojiStyle = options.emoji === "none" ? void 0 : options.emoji ?? "twemoji";
   const fontFamilies = [...new Set(options.fonts.map((f) => f.name))];
   const layoutTree = await buildLayoutTree(