fix: draw SVG frame labels without text measurement

Frame labels were baked into exports as measured, ellipsis-truncated text
elements, which made `exportToSvg` depend on a canvas (through the render
environment) for the only text it ever measures.

- add `getFrameLabel` (element package): a measurement-free label spec --
  position, font, color, arithmetic height, the frame's width as max width
- SVG: draw labels from the spec in the frame branch, full title clipped to
  the frame's width; extract `appendSvgTextLines` so text elements and
  labels produce identical markup
- canvas: unchanged output (measured, truncated text elements), now built
  from the same spec
- fit label boxes into the SVG export bounds explicitly (`extraBounds`)
- test: SVG export of a named frame succeeds with a render environment
  whose `createCanvas` throws and creates no canvas through `document`

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
dwelleandClaude Fable 5.1 authored and Mark Tolmacs committed 2026-09-15 11:24:31 +00:00
1 parent d8f9bff52e
commit 295e7d88b5
6 files changed
+335 -103

No files matched your search

+61
View File
@@ -0,0 +1,61 @@
import { FONT_FAMILY, FRAME_STYLE } from "@excalidraw/common";
import { getFrameLikeTitle } from "./frame";
import { getTextHeight, normalizeText } from "./textMeasurements";
import type {
ExcalidrawFrameLikeElement,
ExcalidrawTextElement,
} from "./types";
/**
* A frame's name as drawn on export. While editing, the name is a DOM overlay
* (`text-overflow: ellipsis` at the frame's width -- see `App.renderFrameNames`);
* on export each renderer draws it from this spec.
*
* Everything here is arithmetic: no text is measured, so a renderer can draw
* labels without a canvas (the SVG exporter does). There is deliberately no
* `width`: the label is left-aligned at the frame's left edge and never wider
* than the frame, so its width can't affect layout. A renderer that needs it
* (canvas, for the ellipsis) measures it itself.
*/
export type FrameLabel = {
/** left edge (the frame's) */
x: number;
/** top edge: `FRAME_STYLE.nameOffsetY` above the frame, less the label's height */
y: number;
/** the label must not overflow this (the frame's width) */
maxWidth: number;
height: number;
text: string;
fontFamily: ExcalidrawTextElement["fontFamily"];
fontSize: number;
lineHeight: ExcalidrawTextElement["lineHeight"];
/** unfiltered -- renderers apply the dark-mode filter as for any text */
color: string;
};
export const getFrameLabel = (
frame: ExcalidrawFrameLikeElement,
{ exportWithDarkMode }: { exportWithDarkMode: boolean },
): FrameLabel => {
const text = normalizeText(getFrameLikeTitle(frame));
const fontSize = FRAME_STYLE.nameFontSize;
const lineHeight =
FRAME_STYLE.nameLineHeight as ExcalidrawTextElement["lineHeight"];
const height = getTextHeight(text, fontSize, lineHeight);
return {
x: frame.x,
y: frame.y - FRAME_STYLE.nameOffsetY - height,
maxWidth: frame.width,
height,
text,
fontFamily: FONT_FAMILY.Helvetica,
fontSize,
lineHeight,
color: exportWithDarkMode
? FRAME_STYLE.nameColorDarkTheme
: FRAME_STYLE.nameColorLightTheme,
};
};
+1
View File
@@ -77,6 +77,7 @@ export * from "./flowchart";
export * from "./arrows/focus";
export * from "./fractionalIndex";
export * from "./frame";
export * from "./frameLabel";
export * from "./groups";
export * from "./heading";
export * from "./image";
+140 -44
View File
@@ -33,7 +33,7 @@ import {
isTextElement,
} from "@excalidraw/element";
import { getContainingFrame } from "@excalidraw/element";
import { getContainingFrame, getFrameLabel } from "@excalidraw/element";
import { getCornerRadius, isPathALoop } from "@excalidraw/element";
@@ -48,6 +48,8 @@ import { getElementAbsoluteCoords } from "@excalidraw/element";
import type {
ExcalidrawElement,
ExcalidrawFrameLikeElement,
ExcalidrawTextElement,
ExcalidrawTextElementWithContainer,
NonDeletedExcalidrawElement,
} from "@excalidraw/element/types";
@@ -94,6 +96,116 @@ const maybeWrapNodesInFrameClipPath = (
return null;
};
/**
* Appends one `<text>` per line, laid out the way the canvas renderer lays
* text out (alphabetic baseline, per-font vertical offset). Shared by text
* elements and frame labels so both come out identical.
*/
const appendSvgTextLines = (
parent: SVGElement,
{
text,
width,
textAlign,
fontFamily,
fontSize,
lineHeight,
fill,
}: {
text: string;
width: number;
textAlign: ExcalidrawTextElement["textAlign"];
fontFamily: ExcalidrawTextElement["fontFamily"];
fontSize: ExcalidrawTextElement["fontSize"];
lineHeight: ExcalidrawTextElement["lineHeight"];
fill: string;
},
) => {
const doc = parent.ownerDocument;
const lines = text.replace(/\r\n?/g, "\n").split("\n");
const lineHeightPx = getLineHeightInPx(fontSize, lineHeight);
const horizontalOffset =
textAlign === "center" ? width / 2 : textAlign === "right" ? width : 0;
const verticalOffset = getVerticalOffset(fontFamily, fontSize, lineHeightPx);
const direction = isRTL(text) ? "rtl" : "ltr";
const textAnchor =
textAlign === "center"
? "middle"
: textAlign === "right" || direction === "rtl"
? "end"
: "start";
for (let i = 0; i < lines.length; i++) {
const node = doc.createElementNS(SVG_NS, "text");
node.textContent = lines[i];
node.setAttribute("x", `${horizontalOffset}`);
node.setAttribute("y", `${i * lineHeightPx + verticalOffset}`);
node.setAttribute("font-family", getFontFamilyString({ fontFamily }));
node.setAttribute("font-size", `${fontSize}px`);
node.setAttribute("fill", fill);
node.setAttribute("text-anchor", textAnchor);
node.setAttribute("style", "white-space: pre;");
node.setAttribute("direction", direction);
node.setAttribute("dominant-baseline", "alphabetic");
parent.appendChild(node);
}
};
/**
* Frame labels are DOM overlays while editing (`text-overflow: ellipsis` at
* the frame's width). Canvas export bakes them in as measured, truncated text
* elements; here the full title is emitted and clipped to the frame's width
* instead. Nothing is measured, so SVG export needs no canvas: the label's
* height is arithmetic and, being left-aligned, its width never affects
* layout. The full title also stays in the document (searchable, selectable).
*/
const renderFrameLabelToSvg = (
frame: ExcalidrawFrameLikeElement,
svgRoot: SVGElement,
offsetX: number,
offsetY: number,
renderConfig: SVGRenderConfig,
) => {
const doc = svgRoot.ownerDocument;
const label = getFrameLabel(frame, {
exportWithDarkMode: renderConfig.exportWithDarkMode,
});
const node = doc.createElementNS(SVG_NS, "g");
node.setAttribute(
"transform",
`translate(${label.x - frame.x + offsetX} ${label.y - frame.y + offsetY})`,
);
// clips horizontally only: the canvas renderer never clips glyphs
// vertically, and tall fallback glyphs (emoji, CJK) can overshoot the line
// box, so the rect is padded by a label's height above and below
const clipId = `${frame.id}-label`;
const clipPath = doc.createElementNS(SVG_NS, "clipPath");
clipPath.setAttribute("id", clipId);
const clipRect = doc.createElementNS(SVG_NS, "rect");
clipRect.setAttribute("x", "0");
clipRect.setAttribute("y", `${-label.height}`);
clipRect.setAttribute("width", `${label.maxWidth}`);
clipRect.setAttribute("height", `${label.height * 3}`);
clipPath.appendChild(clipRect);
node.appendChild(clipPath);
const textGroup = doc.createElementNS(SVG_NS, "g");
textGroup.setAttribute("clip-path", `url(#${clipId})`);
appendSvgTextLines(textGroup, {
text: label.text,
width: label.maxWidth,
textAlign: "left",
fontFamily: label.fontFamily,
fontSize: label.fontSize,
lineHeight: label.lineHeight,
fill: applyDarkModeFilter(label.color, renderConfig.theme === THEME.DARK),
});
node.appendChild(textGroup);
return node;
};
const renderElementToSvg = (
element: Readonly<NonDeletedExcalidrawElement>,
elementsMap: RenderableElementsMap,
@@ -742,6 +854,21 @@ const renderElementToSvg = (
// frames are not rendered and only acts as a container
case "frame":
case "magicframe": {
if (
renderConfig.frameRendering.enabled &&
renderConfig.frameRendering.name
) {
addToRoot(
renderFrameLabelToSvg(
element,
svgRoot,
offsetX,
offsetY,
renderConfig,
),
element,
);
}
if (
renderConfig.frameRendering.enabled &&
renderConfig.frameRendering.outline
@@ -789,49 +916,18 @@ const renderElementToSvg = (
offsetY || 0
}) rotate(${degree} ${cx} ${cy})`,
);
const lines = element.text.replace(/\r\n?/g, "\n").split("\n");
const lineHeightPx = getLineHeightInPx(
element.fontSize,
element.lineHeight,
);
const horizontalOffset =
element.textAlign === "center"
? element.width / 2
: element.textAlign === "right"
? element.width
: 0;
const verticalOffset = getVerticalOffset(
element.fontFamily,
element.fontSize,
lineHeightPx,
);
const direction = isRTL(element.text) ? "rtl" : "ltr";
const textAnchor =
element.textAlign === "center"
? "middle"
: element.textAlign === "right" || direction === "rtl"
? "end"
: "start";
for (let i = 0; i < lines.length; i++) {
const text = svgRoot.ownerDocument.createElementNS(SVG_NS, "text");
text.textContent = lines[i];
text.setAttribute("x", `${horizontalOffset}`);
text.setAttribute("y", `${i * lineHeightPx + verticalOffset}`);
text.setAttribute("font-family", getFontFamilyString(element));
text.setAttribute("font-size", `${element.fontSize}px`);
text.setAttribute(
"fill",
applyDarkModeFilter(
element.strokeColor,
renderConfig.theme === THEME.DARK,
),
);
text.setAttribute("text-anchor", textAnchor);
text.setAttribute("style", "white-space: pre;");
text.setAttribute("direction", direction);
text.setAttribute("dominant-baseline", "alphabetic");
node.appendChild(text);
}
appendSvgTextLines(node, {
text: element.text,
width: element.width,
textAlign: element.textAlign,
fontFamily: element.fontFamily,
fontSize: element.fontSize,
lineHeight: element.lineHeight,
fill: applyDarkModeFilter(
element.strokeColor,
renderConfig.theme === THEME.DARK,
),
});
const g = maybeWrapNodesInFrameClipPath(
element,
+62 -56
View File
@@ -3,7 +3,6 @@ import rough from "roughjs/bin/rough";
import {
DEFAULT_EXPORT_PADDING,
FRAME_STYLE,
FONT_FAMILY,
SVG_NS,
THEME,
MIME_TYPES,
@@ -30,15 +29,12 @@ import { isFrameLikeElement } from "@excalidraw/element";
import {
getElementsOverlappingFrame,
getFrameLikeElements,
getFrameLikeTitle,
getRootElements,
} from "@excalidraw/element";
import { syncInvalidIndices } from "@excalidraw/element";
import { type Mutable } from "@excalidraw/common/utility-types";
import { newTextElement } from "@excalidraw/element";
import { newTextElement, getFrameLabel } from "@excalidraw/element";
import type { Bounds } from "@excalidraw/common";
@@ -101,10 +97,11 @@ const truncateText = (
};
/**
* When exporting frames, we need to render frame labels which are currently
* being rendered in DOM when editing. Adding the labels as regular text
* elements seems like a simple hack. In the future we'll want to move to
* proper canvas rendering, even within editor (instead of DOM).
* Frame labels are DOM overlays while editing. For canvas export we bake them
* in as text elements, measured and ellipsis-truncated to the frame's width
* (the SVG renderer draws them itself, without measuring -- see
* `renderFrameLabelToSvg`). In the future we'll want to move to proper canvas
* rendering, even within editor (instead of DOM).
*/
const addFrameLabelsAsTextElements = (
elements: readonly NonDeletedExcalidrawElement[],
@@ -115,29 +112,21 @@ const addFrameLabelsAsTextElements = (
const nextElements: NonDeletedExcalidrawElement[] = [];
for (const element of elements) {
if (isFrameLikeElement(element)) {
let textElement: Mutable<NonDeleted<ExcalidrawTextElement>> =
newTextElement({
x: element.x,
y: element.y - FRAME_STYLE.nameOffsetY,
fontFamily: FONT_FAMILY.Helvetica,
fontSize: FRAME_STYLE.nameFontSize,
lineHeight:
FRAME_STYLE.nameLineHeight as ExcalidrawTextElement["lineHeight"],
strokeColor: opts.exportWithDarkMode
? FRAME_STYLE.nameColorDarkTheme
: FRAME_STYLE.nameColorLightTheme,
text: getFrameLikeTitle(element),
renderEnvironment: opts.renderEnvironment,
});
textElement.y -= textElement.height;
const label = getFrameLabel(element, opts);
const textElement = newTextElement({
x: label.x,
y: label.y,
fontFamily: label.fontFamily,
fontSize: label.fontSize,
lineHeight: label.lineHeight,
strokeColor: label.color,
text: label.text,
renderEnvironment: opts.renderEnvironment,
});
textElement = truncateText(
textElement,
element.width,
opts.renderEnvironment,
nextElements.push(
truncateText(textElement, label.maxWidth, opts.renderEnvironment),
);
nextElements.push(textElement);
}
nextElements.push(element);
}
@@ -158,37 +147,26 @@ const getFrameRenderingConfig = (
};
};
/**
* The elements an export renders: when exporting a single frame, only what
* overlaps it (the renderer clips to the frame); otherwise the elements as
* supplied.
*/
const prepareElementsForRender = ({
elements,
exportingFrame,
frameRendering,
exportWithDarkMode,
renderEnvironment,
}: {
elements: readonly NonDeletedExcalidrawElement[];
exportingFrame: ExcalidrawFrameLikeElement | null | undefined;
frameRendering: AppState["frameRendering"];
exportWithDarkMode: AppState["exportWithDarkMode"];
renderEnvironment?: RenderEnvironment;
}) => {
let nextElements: readonly NonDeletedExcalidrawElement[];
if (exportingFrame) {
nextElements = getElementsOverlappingFrame(
return getElementsOverlappingFrame(
elements,
exportingFrame,
arrayToMap(elements),
);
} else if (frameRendering.enabled && frameRendering.name) {
nextElements = addFrameLabelsAsTextElements(elements, {
exportWithDarkMode,
renderEnvironment,
});
} else {
nextElements = elements;
}
return nextElements;
return elements;
};
export const exportToCanvas = async (
@@ -234,14 +212,19 @@ export const exportToCanvas = async (
frameRendering.clip = false;
}
const elementsForRender = prepareElementsForRender({
let elementsForRender = prepareElementsForRender({
elements,
exportingFrame,
exportWithDarkMode: appState.exportWithDarkMode,
frameRendering,
renderEnvironment,
});
// `getFrameRenderingConfig` turns names off when exporting a single frame
if (frameRendering.enabled && frameRendering.name) {
elementsForRender = addFrameLabelsAsTextElements(elementsForRender, {
exportWithDarkMode: appState.exportWithDarkMode,
renderEnvironment,
});
}
if (exportingFrame) {
exportPadding = 0;
}
@@ -362,18 +345,33 @@ export const exportToSvg = async (
const elementsForRender = prepareElementsForRender({
elements,
exportingFrame,
exportWithDarkMode,
frameRendering,
renderEnvironment: opts?.renderEnvironment,
});
if (exportingFrame) {
exportPadding = 0;
}
// frame labels sit above their frames and are drawn by the SVG renderer
// (see `renderFrameLabelToSvg`) rather than being baked in as elements, so
// they have to be fitted into the bounds explicitly. `getFrameRenderingConfig`
// turns names off when exporting a single frame.
const frameLabelBounds: Bounds[] =
frameRendering.enabled && frameRendering.name
? getFrameLikeElements(elementsForRender).map((frame) => {
const label = getFrameLabel(frame, { exportWithDarkMode });
return [
label.x,
label.y,
label.x + label.maxWidth,
label.y + label.height,
];
})
: [];
const [minX, minY, width, height] = getCanvasSize(
exportingFrame ? [exportingFrame] : getRootElements(elementsForRender),
exportPadding,
frameLabelBounds,
);
const offsetX = -minX + exportPadding;
@@ -602,8 +600,16 @@ export const decodeSvgBase64Payload = ({ svg }: { svg: string }) => {
const getCanvasSize = (
elements: readonly NonDeletedExcalidrawElement[],
exportPadding: number,
/** extra boxes to fit, for things drawn that aren't elements (frame labels) */
extraBounds: readonly Bounds[] = [],
): Bounds => {
const [minX, minY, maxX, maxY] = getCommonBounds(elements);
let [minX, minY, maxX, maxY] = getCommonBounds(elements);
for (const [x1, y1, x2, y2] of extraBounds) {
minX = Math.min(minX, x1);
minY = Math.min(minY, y1);
maxX = Math.max(maxX, x2);
maxY = Math.max(maxY, y2);
}
const width = distance(minX, maxX) + exportPadding * 2;
const height = distance(minY, maxY) + exportPadding * 2;
+5 -3
View File
@@ -58,9 +58,11 @@ export type StaticCanvasRenderConfig = {
export type SVGRenderConfig = {
/**
* Host environment used for the text measurements this render needs (the
* SVG itself is built through `exportToSvg`'s owner document). Defaults to
* the process-wide environment.
* Host environment for the one thing this render still measures text for:
* embeddable placeholder labels (`createPlaceholderEmbeddableLabel`). The
* SVG itself is built through `exportToSvg`'s owner document, and frame
* labels are drawn without measuring. Defaults to the process-wide
* environment.
*/
renderEnvironment?: RenderEnvironment;
offsetX: number;
@@ -7,6 +7,12 @@ import {
FRAME_STYLE,
} from "@excalidraw/common";
import {
newElementWith,
resetRenderEnvironment,
setRenderEnvironment,
} from "@excalidraw/element";
import { pointFrom } from "@excalidraw/math";
import type {
@@ -634,6 +640,66 @@ describe("exporting frames", () => {
);
});
it("renders frame labels without measuring text (no canvas needed)", async () => {
const createElementSpy = vi.spyOn(document, "createElement");
// any text measurement would build a metrics canvas through the
// environment; SVG export must not need one
setRenderEnvironment({
createCanvas: () => {
throw new Error("exportToSvg must not create a canvas");
},
});
try {
const frame = newElementWith(
API.createElement({
type: "frame",
width: 100,
height: 100,
x: 0,
y: 0,
}),
{ name: "a frame name long enough to overflow the frame width" },
);
const svg = await exportToSvg({
elements: [frame],
files: null,
exportPadding: 0,
});
expect(
createElementSpy.mock.calls.filter(([tag]) => tag === "canvas"),
).toHaveLength(0);
// the full title stays in the document -- clipped to the frame
// rather than ellipsis-truncated like the canvas export
const label = svg.querySelector("text");
expect(label?.textContent).toBe(frame.name);
const clipRect = svg.querySelector(
`clipPath[id="${frame.id}-label"] rect`,
);
expect(clipRect?.getAttribute("width")).toBe(`${frame.width}`);
expect(label?.closest("g[clip-path]")?.getAttribute("clip-path")).toBe(
`url(#${frame.id}-label)`,
);
// the label sits above the frame: at the top of the export, with
// the export grown by the label's height
expect(
svg
.querySelector(`clipPath[id="${frame.id}-label"]`)
?.parentElement?.getAttribute("transform"),
).toBe("translate(0 0)");
expect(svg.getAttribute("height")).toBe(
(frame.height + getFrameNameHeight("svg")).toString(),
);
} finally {
resetRenderEnvironment();
createElementSpy.mockRestore();
}
});
it("should not export frame-overlapping elements belonging to different frame", async () => {
const frame1 = API.createElement({
type: "frame",