Export guarantees

What each export of @workspace/active-charts guarantees for international text, who owns that guarantee, and which route a consumer takes when the package does not guarantee what it needs. Decided in ADR-060; the font model is ADR-058 (PDF) and ADR-059 (SVG, PNG); the API is API.md § 4. active-grid carries the same tiers in its own words for its own formats.

The tiers#

No tier promises more than it says. "Supported" in any row below means the tier named, under its condition.

SVG and PNG#

In every mode the browser shapes: the package lays text out in the live font and never again in the export font, so a family with other metrics can shift text. Put the live family first.

What an export shows#

Every export and print shows the chart at rest (ADR-064, ADR-065): its static polish (geometry, typography, axis layout, grid, theme) is in it; interaction state is not. No hover, recede or inactive paint, keyboard cue, legend preview, crosshair, emphasised node, gutter mark, tooltip or selection mark reaches an SVG, PNG, PDF or print, in any family: the state is painted by the package stylesheet, which an export never copies, and the transient marks carry one attribute the composer drops. A report that needs highlighted data encodes it in the data, as a series or an annotation.

Never mid-motion (ADR-104). An export waits until the chart is still: two frames without a change, no running web animation, and past the end of every scripted motion the chart declared on its scope (an update, a path morph, a count-up or gauge replay, a grouped slot reflow, a discrete zoom), because an eased tail that snaps to whole pixels leaves quiet frames before it ends. It waits at most the chart's motion budget (the longest motion its animation allows) plus one second, and at least four seconds; a chart that never comes to rest within that rejects the export. An export started during an entrance, an update, a reflow or a replay therefore writes the resting geometry, and the tooltip, the crosshair, the cues, attention and the colour-key marker are not in it (asserted in Chromium and Firefox for SVG, with PNG and PDF waiting the same way).

An export means the same thing whichever route starts it (ADR-085). The handle (ChartHandle.exportAs*) and the context menu run one composed export per chart: the same legend on the side it is painted (its entries, keys, colours and hidden items as on the screen), the same export fonts and the same rows. The menu writes its PNG at contextMenu.pngScale and offers CSV on every chart with a menu, the export-only menu of the scalars included (ADR-087); the Sparkline has no menu and exports through its handle. A PDF draws the whole chart on every route: the export clone always carries a viewBox, so svg2pdf scales the drawing into its box instead of clipping it (ADR-088). A drawing that shows only part of its content says so in the image too: a partial org chart view carries its note in the export's caption, after the host's own.

Per script#

Thai, Lao, Khmer, Myanmar, Tibetan, Mongolian, Syriac, Thaana and N'Ko are refused in PDF like Arabic. A refusal names one code point and, for a script, its name; it never carries the text.

Which route#

The package never hands over to a host route by itself: it refuses, and the host decides.

Errors#

ChartExportError.code separates four kinds of failure; none carries the exported text (at most one code point and a script name, the host's family name, the detected font format, the missing module, the families tried).

active-grid's GridExportError uses the same codes for the same meaning.

Configuring export fonts in a host#

The host owns its fonts: which families, which faces, where the bytes come from and the right to embed them. A typical enterprise set is a corporate Latin family first and a CJK family as its fallback, with faces loaded only when an export needs them:

const load = (path: string) => () =>  fetch(path, {signal: AbortSignal.timeout(15_000)}).then((response) => {    if (!response.ok) throw new Error(`font ${response.status}`);    return response.arrayBuffer();  });
const exportFonts: ChartExportFonts = {  families: [    {      family: 'Corporate Sans',      faces: [        {source: load('/fonts/corporate-sans-regular.ttf')},        {source: load('/fonts/corporate-sans-bold.ttf'), weight: 700},        {source: load('/fonts/corporate-sans-italic.ttf'), style: 'italic'},      ],    },    {      family: 'Example CJK Sans',      faces: [{source: load('/fonts/example-cjk-sans-regular.ttf')}],    },  ],};
<ChartDefaults exportFonts={exportFonts}>{children}</ChartDefaults>;

• PDF needs static TrueType (glyf) faces. A WOFF or WOFF2 web font, a CFF-flavoured OpenType font or a variable font cannot be embedded; SVG and PNG take TrueType, CFF, WOFF and WOFF2.

• Keep the object stable (a module constant): the package loads each face object once and shares the load between concurrent exports.

• Name the live family first, so export metrics match the live layout.

• The same object is an active-grid GridExportFonts.

Host routes (L3b)#

These are recipes for a host. The package provides neither.

L3b-raster: a browser image in a PDF#

1. Render the chart in a browser or headless browser that has the fonts the text needs (installed in the image, or loaded as web fonts).

2. Wait for document.fonts.ready and for the chart to be still.

3. Take a PNG at a scale for print (for example 2x device pixels), with exportAsPng or a screenshot of the chart element.

4. Place the image in the host's PDF.

The browser shapes every script it has fonts for, and the image looks like the screen. The chart's text is pixels: it cannot be selected, searched or read by assistive technology from the PDF, so the host adds any text it needs in its own PDF layer.

L3b-print: the browser prints a PDF#

1. Launch a browser the host controls (for example headless Chromium) with the fonts installed or loaded.

2. Render a page that contains the live chart, or its SVG export.

3. Wait for document.fonts.ready and for the chart to be still.

4. Print with the browser's PDF mechanism (in Chromium, page.pdf()).

5. Verify before relying on it: extract the text from the PDF (for example with pdftotext) and render the PDF back to an image, for each script the host serves.

The browser shapes the text and writes it as selectable text with a Unicode mapping. This was verified once in a research harness (Chromium 153 on Windows with the operating system's fonts): Arabic, Hebrew and Devanagari came back from pdftotext in logical order, and the rendered PDF showed joined Arabic, right-to-left Hebrew and formed Devanagari conjuncts. That is evidence the recipe works, not a guarantee for another browser version, operating system or font set. A host claims L3b-print only for what it has verified itself.