Skip to content

Add config.fonts to load fonts before the first draw and embed them in exports - #8172

Open
nul0m wants to merge 7 commits into
plotly:mainfrom
nul0m:font-data-8056
Open

nul0m wants to merge 7 commits into
plotly:mainfrom
nul0m:font-data-8056

Conversation

@nul0m

@nul0m nul0m commented Nov 16, 2026

Copy link
Copy Markdown

Closes #8056.

@camdecoster i've finally got some time to look into this, this PR covers most of the things you mentioned in comments to #8056 so we can iterate here on the proposed solutions and possible gaps.

What it adds

  • config.fonts: a list of {family, source, weight?, style?}
  • source is the URL of a font file, a base64 data URL, or the bytes (ArrayBuffer or a typed array)
  • FontSource type, exported from lib/index.d.ts; fonts added to the ConfigOverrides in src/types/core/config.d.ts, since its schema valType is any

Loading

  • _doPlot loads the faces of config.fonts before it measures any text (a step after Plots.previousPromises)
  • it waits for the listed faces with FontFace.load(), so no font-family parsing and no loadingdone
  • a graph without config.fonts still draws synchronously
  • loaded faces are cached by family, weight, style and source (bytes by content), so later graphs draw synchronously
  • a face that loads during the wait clears Drawing.savedBBoxes
  • a failure logs a warning and the graph draws with a fallback font - it never throws
  • download timeout: 10 s
  • a failed download (network error, HTTP status, timeout) is tried again on the next draw; a file that can't be decoded stays failed, with one warning
  • a purge during the wait stops the waiting draw (newPlot resolves, nothing drawn)
  • later calls on the graph wait in Plots.previousPromises until the fonts load (checked: relayout, restyle, react with style, range, annotation, shape, layout.images or transition changes, Plotly.animate, resize)
  • react with the same font bytes in a new buffer isn't a config change: helpers.collectionsAreEqual compares binary values by their bytes
  • an ArrayBuffer source is copied
  • a wrong shape gives a warning: fonts not an array, string items, an unsupported source type

Exports

  • toSVG adds a <style> with base64 @font-face rules for the faces that a font-family declaration of the SVG names (rich-text spans included; case and quotes don't matter)
  • svg, pdf and eps leave out a face whose OS/2 fsType forbids embedding (restricted license, bitmap only), with a warning
  • png, jpeg and webp always use the face
  • a face whose permission can't be read is embedded - every WOFF2, since browsers have no Brotli decoder
  • Plotly.Snapshot.toImage / Snapshot.clone keep config.fonts, and pass the format to toSVG

Not in this PR

  • Google Fonts CSS parsing - direct font file links instead, as suggested in the issue
  • fonts that are only installed on the system - no browser API gives their bytes

Known limits

  • a face that forbids embedding still sizes the text of an svg, pdf or eps export, because the export clone measures with the loaded face (legend box 105 px vs 86 px with the fallback, in the test font)
  • other graphs on the page that already use the family without config.fonts switch to the face when it loads, but aren't re-measured - the same as any web font that loads after a draw
  • a call made before the first draw finishes counts as part of the initial figure: a relayout of xaxis.range during the wait becomes the double-click reset range
  • a relayout queued during the wait and followed by a purge still rejects, as before this change

Tests

  • config_test.js, fonts: (11): load before the draw, sync draw from the cache, typed array, decode failure warns once, no second download of a bad file, retry after a failed download, purge during the wait, relayout during the wait, react with new bytes, item without a family, wrong shapes
  • toimage_test.js, with config.fonts (9): svg embed, forbidden face in svg and in raster, unreadable permission, compressed OS/2 table in WOFF, detached ArrayBuffer, unused family, rich-text span, snapshot clone
  • lib_test.js, readEmbeddingPermission (3)
  • plot_api_test.js, collectionsAreEqual: binary values
  • test/jasmine/assets/test_fonts.js: synthetic fonts, every glyph a 1 em square, so text widths are exact (TTF and WOFF, fsType 0 and 2)
  • no mocks and no baselines changed

Checks run

  • npm run lint, typecheck, test-syntax, test-types, entry-point-types-check: pass
  • npm run schema-typegen-diff-check: no drift
  • npm run test-jasmine -- config toimage lib plot_api plots snapshot: 591 of 591 (Chrome 157, macOS)
  • headless Chrome 142 against build/plotly.js: title 100 px with the font vs 68.9 px with the fallback; a direct URL from a local server that answers after 300 ms draws after about 320 ms; a URL that never answers falls back after 10 s
  • not run: the image tests, Firefox, Safari

Open questions

  • should the 10 s timeout be configurable? With the retry, a host that never answers costs 10 s on every draw (30 s for newPlot, one relayout and an export)
  • should the export embed only the weights and styles the SVG uses, rather than every loaded face of a used family?
  • should the shared font.family description, which says only installed fonts work, mention config.fonts?
  • Kaleido drops figure.config today, so this doesn't reach plotly.py's write_image yet - is a Kaleido issue the right next step?
  • is embedding a WOFF2 face of unknown permission OK, or would you rather bundle a Brotli decoder?

draftlogs/0000_add.md gets the PR number once it exists.

…hem in exports

Text that plotly.js measures before a web font loads keeps the size of the
fallback font, so titles, legends and margins do not fit the final text. An
exported SVG cannot use the fonts of the page, so the exported text shows a
fallback font.

config.fonts gives plotly.js the font data, as a URL, a base64 data URL or the
bytes. plotly.js loads these faces before it measures text. SVG exports embed
the faces that the image uses, if the font file permits embedding.

See plotly#8056.
The repository uses jasmine 3.5, which has no jasmine.stringContaining.
…n in the next draw

plotly.js cannot read the embedding permission of a WOFF2 file, because
browsers have no Brotli decoder. Before this change, svg, pdf and eps exports
refused every WOFF2 face, so the exported text showed a fallback font. Now an
export refuses a face only if the font file forbids embedding.

A face that failed to load stayed in the cache for the life of the page. Thus
a short network fault removed the font from all later graphs. Now the cache
forgets a failed face, and the next draw tries the font again.

See plotly#8056.
…led downloads

A data URL, a byte source or a downloaded file that the browser cannot decode
gives the same result each time. Before this change, the next draw tried such
a face again and logged the same warning again. Now only a failed download
makes the next draw try the face again, because a network fault can go away.

See plotly#8056.
…ing, buffers and warnings

A purge during the font wait made the waiting draw throw, and a relayout
during the wait failed on the undrawn graph. Now a purge stops the waiting
draw, and Plots.previousPromises holds later calls until the fonts load.

Plotly.react compared font bytes by reference, so new bytes rebuilt the plot.
collectionsAreEqual now compares binary values by their bytes.

The export embedded a family whose name only occurred in class names, and
Snapshot.toImage lost the fonts. Now the export reads the font-family
declarations, and the snapshot clone keeps config.fonts.

A detached ArrayBuffer source broke the next export, so plotly.js now copies
the buffer. A config.fonts value of the wrong shape now gives a warning.

See plotly#8056.
@nul0m
nul0m marked this pull request as ready for review November 16, 2026 16:45
@camdecoster camdecoster self-assigned this Nov 16, 2026
@camdecoster

Copy link
Copy Markdown
Contributor

Thanks for putting this together. I'll review and follow up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE]: accept font data (a URL or the bytes) for export and text measurement

2 participants