@jbrowse/core 5.0.0-beta.8 → 5.0.0-beta.9

package/esm/svg/exportViewSvg.d.ts

@@ -0,0 +1,32 @@
+import type React from 'react';
+/** What every view's `exportSvg` accepts. A view with more extends it. */
+export interface ViewExportSvgOptions {
+    rasterizeLayers?: boolean;
+    format?: 'svg' | 'png';
+    filename?: string;
+    /**
+     * Whether to hand the result to the browser's download path. Default true,
+     * which is the dialog. False returns the markup and writes nothing — the
+     * caller has somewhere of its own to put it, and a download it did not ask
+     * for would land beside that under a name it did not choose.
+     */
+    save?: boolean;
+    Wrapper?: React.FC<{
+        children: React.ReactNode;
+    }>;
+    /** a named theme; the session's active one when absent */
+    themeName?: string;
+    fontFamily?: string;
+    /**
+     * headless canvas factory for `rasterizeLayers` (jbrowse-img passes
+     * node-canvas); without it the raster path needs a DOM canvas
+     */
+    createCanvas?: (width: number, height: number) => HTMLCanvasElement;
+}
+/**
+ * The body of every view's `exportSvg` action: load the view's lazy
+ * `renderToSvg`, render, save unless `save: false`, and return the markup.
+ */
+export declare function exportViewSvg<V, O extends ViewExportSvgOptions>(view: V, opts: O, load: () => Promise<{
+    renderToSvg: (view: V, opts: O) => Promise<string>;
+}>): Promise<string>;

package/esm/svg/exportViewSvg.js

@@ -0,0 +1,13 @@
+/**
+ * The body of every view's `exportSvg` action: load the view's lazy
+ * `renderToSvg`, render, save unless `save: false`, and return the markup.
+ */
+export async function exportViewSvg(view, opts, load) {
+    const { renderToSvg } = await load();
+    const html = await renderToSvg(view, opts);
+    if (opts.save !== false) {
+        const { saveSvgAsImage } = await import('./saveSvgAsImage.js');
+        await saveSvgAsImage(html, opts);
+    }
+    return html;
+}

package/esm/svg/normalizeSvgMarkup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The markup rules an SVG file has to meet that a React render into an HTML
+ * container does not: XML entities only (HTML serialization writes U+00A0 as
+ * ` `, which XML does not define, so one no-break space in a feature label
+ * made the whole file unparsable), SVG 1.1 colors, and rounded numbers.
+ */
+export declare function normalizeSvgMarkup(html: string): string;

package/esm/svg/normalizeSvgMarkup.js

@@ -0,0 +1,99 @@
+import { splitPaintAlpha } from '../util/svgColorProps.js';
+// Coordinates computed as bp/bpPerPx land in attributes as long floats
+// (`-32.4816`) or floating-point noise (`242.23839999999998`), bloating exports
+// with sub-pixel precision no renderer needs. Round numbers inside a fixed
+// whitelist of numeric attributes, so a track label or id that happens to look
+// numeric is never a candidate for rewriting. Geometry gets 2 decimals
+// (sub-pixel); opacity keeps 3 so a faint 0.01 mark can't collapse to 0.
+const COORD_ATTRS = [
+    'x',
+    'y',
+    'x1',
+    'y1',
+    'x2',
+    'y2',
+    'cx',
+    'cy',
+    'r',
+    'rx',
+    'ry',
+    'dx',
+    'dy',
+    'width',
+    'height',
+    'd',
+    'points',
+    'transform',
+    'gradientTransform',
+    'offset',
+    'viewBox',
+    'font-size',
+    'stroke-width',
+    'stroke-dashoffset',
+    'stroke-dasharray',
+];
+const OPACITY_ATTRS = [
+    'opacity',
+    'fill-opacity',
+    'stroke-opacity',
+    'stop-opacity',
+    'flood-opacity',
+];
+function makeRounder(attrs, digits) {
+    const re = new RegExp(`\\b(${attrs.join('|')})="([^"]*)"`, 'g');
+    return (svg) => svg.replaceAll(re, (_, name, value) => {
+        const rounded = value.replaceAll(/-?\d+\.\d{3,}(?:e-?\d+)?/gi, n => String(Number.parseFloat(Number(n).toFixed(digits))));
+        return `${name}="${rounded}"`;
+    });
+}
+const roundCoords = makeRounder(COORD_ATTRS, 2);
+const roundOpacity = makeRounder(OPACITY_ATTRS, 3);
+const OPACITY_OF = {
+    fill: 'fill-opacity',
+    stroke: 'stroke-opacity',
+    'stop-color': 'stop-opacity',
+    'flood-color': 'flood-opacity',
+};
+// a start tag, attribute by attribute, so a `>` inside a quoted value (which
+// HTML serialization leaves unescaped) cannot end it early
+const START_TAG = /<[a-zA-Z][^\s/>]*(?:\s+[^\s"'/=>]+="[^"]*")*\s*\/?>/g;
+const PAINT_ATTR = /\s(fill|stroke|stop-color|flood-color)="([^"]*)"/g;
+const MAY_NEED_SPLIT = /(?:fill|stroke|stop-color|flood-color)="(?:rgba|hsl|#[\da-f]{4}"|#[\da-f]{8}"|transparent)/i;
+// A JSX color reaches the file as React wrote it, and theme palette entries are
+// routinely `rgba()` (`divider`, `text.secondary`) — see `splitPaintAlpha` for
+// why that can't stay. Scoped to one start tag so an alpha folds into an
+// opacity attribute the element already carries instead of duplicating it,
+// which would not parse as XML.
+function splitTagPaintAlpha(tag) {
+    const alphas = [];
+    let out = tag.replaceAll(PAINT_ATTR, (whole, name, value) => {
+        const split = splitPaintAlpha(value);
+        if (!split) {
+            return whole;
+        }
+        if (split.opacity < 1) {
+            alphas.push([OPACITY_OF[name], split.opacity]);
+        }
+        return ` ${name}="${split.color}"`;
+    });
+    for (const [opacityName, alpha] of alphas) {
+        const existing = new RegExp(`\\s${opacityName}="([^"]*)"`);
+        out = existing.test(out)
+            ? out.replace(existing, (_, v) => ` ${opacityName}="${Number(v) * alpha}"`)
+            : out.replace(/\s*(\/?>)$/, ` ${opacityName}="${alpha}"$1`);
+    }
+    return out;
+}
+/**
+ * The markup rules an SVG file has to meet that a React render into an HTML
+ * container does not: XML entities only (HTML serialization writes U+00A0 as
+ * `&nbsp;`, which XML does not define, so one no-break space in a feature label
+ * made the whole file unparsable), SVG 1.1 colors, and rounded numbers.
+ */
+export function normalizeSvgMarkup(html) {
+    const xml = html.replaceAll('&nbsp;', '&#160;');
+    const split = MAY_NEED_SPLIT.test(xml)
+        ? xml.replaceAll(START_TAG, splitTagPaintAlpha)
+        : xml;
+    return roundOpacity(roundCoords(split));
+}

package/esm/svg/serializeSvg.d.ts

@@ -0,0 +1,7 @@
+import type React from 'react';
+export { normalizeSvgMarkup } from './normalizeSvgMarkup.ts';
+/**
+ * Serialize one standalone SVG document: its own clip-id numbering run (see
+ * `withFreshSvgClipIds`) and the file rules in `normalizeSvgMarkup`.
+ */
+export declare function serializeSvg(node: React.ReactElement): string;

package/esm/svg/serializeSvg.js

@@ -0,0 +1,11 @@
+import { withFreshSvgClipIds } from '../util/SvgCanvas.js';
+import { renderToStaticMarkup } from '../util/renderToStaticMarkup.js';
+import { normalizeSvgMarkup } from './normalizeSvgMarkup.js';
+export { normalizeSvgMarkup } from './normalizeSvgMarkup.js';
+/**
+ * Serialize one standalone SVG document: its own clip-id numbering run (see
+ * `withFreshSvgClipIds`) and the file rules in `normalizeSvgMarkup`.
+ */
+export function serializeSvg(node) {
+    return normalizeSvgMarkup(withFreshSvgClipIds(() => renderToStaticMarkup(node)));
+}

package/esm/svg/svgReady.d.ts

@@ -37,9 +37,9 @@ export interface SvgReadyTerminals {
  * data is current for what is on screen, or the fetch reached a terminal state.
  *
  * Single-sourced for the same reason as `computeDisplayPhase`: every display
- * family expresses freshness differently — spatial coverage (per-region),
- * viewport-snapshot compare (global), signature compare (arc / dotplot /
- * synteny) — but the *policy* wrapping it is identical, and each of the five
+ * family expresses freshness differently — spatial coverage (per-region), a
+ * signature compare (global, dotplot, synteny) — but the *policy* wrapping it
+ * is identical, and each of the five
  * hand-written copies this replaced was one place to forget a terminal and hang
  * the export, or to forget freshness and capture a stale viewport (both have
  * shipped; see agent-docs/reference/SVG_EXPORT.md).
@@ -55,10 +55,11 @@ export declare function computeSvgReady({ error, regionTooLarge, extraTerminal,
  * Off-screen renderers (SVG export, headless jbrowse-img) must wait until the
  * display reaches a terminal state before reading its data. That whole policy
  * lives in `svgReady`; this is the one shared way to await it, so renderers
- * never re-inline `data != null || error || …`. No time bound: `svgReady` is a
- * terminal state (data loaded, or error / too-large), so it resolves once the
- * fetch it observes settles. If a throwing `svgReady` getter rejects the wait,
- * that error propagates faithfully rather than being masked.
+ * never re-inline `data != null || error || …`. `svgReady` is a terminal state
+ * (data loaded, or error / too-large / canceled), so it resolves once the fetch
+ * it observes settles; the half-hour `timeoutMs` is only a backstop for a gate
+ * that cannot converge. If a throwing `svgReady` getter rejects the wait, that
+ * error propagates faithfully rather than being masked.
  *
  * It then fails the export if the terminal it settled on was the error
  * (`throwOnExportErrors`, below, for why that is fatal), making this the exact

package/esm/svg/svgReady.js

@@ -17,9 +17,9 @@ const SVG_READY_TIMEOUT_MS = 1_800_000;
  * data is current for what is on screen, or the fetch reached a terminal state.
  *
  * Single-sourced for the same reason as `computeDisplayPhase`: every display
- * family expresses freshness differently — spatial coverage (per-region),
- * viewport-snapshot compare (global), signature compare (arc / dotplot /
- * synteny) — but the *policy* wrapping it is identical, and each of the five
+ * family expresses freshness differently — spatial coverage (per-region), a
+ * signature compare (global, dotplot, synteny) — but the *policy* wrapping it
+ * is identical, and each of the five
  * hand-written copies this replaced was one place to forget a terminal and hang
  * the export, or to forget freshness and capture a stale viewport (both have
  * shipped; see agent-docs/reference/SVG_EXPORT.md).
@@ -37,10 +37,11 @@ export function computeSvgReady({ error, regionTooLarge, extraTerminal, fetchCan
  * Off-screen renderers (SVG export, headless jbrowse-img) must wait until the
  * display reaches a terminal state before reading its data. That whole policy
  * lives in `svgReady`; this is the one shared way to await it, so renderers
- * never re-inline `data != null || error || …`. No time bound: `svgReady` is a
- * terminal state (data loaded, or error / too-large), so it resolves once the
- * fetch it observes settles. If a throwing `svgReady` getter rejects the wait,
- * that error propagates faithfully rather than being masked.
+ * never re-inline `data != null || error || …`. `svgReady` is a terminal state
+ * (data loaded, or error / too-large / canceled), so it resolves once the fetch
+ * it observes settles; the half-hour `timeoutMs` is only a backstop for a gate
+ * that cannot converge. If a throwing `svgReady` getter rejects the wait, that
+ * error propagates faithfully rather than being masked.
  *
  * It then fails the export if the terminal it settled on was the error
  * (`throwOnExportErrors`, below, for why that is fatal), making this the exact

package/esm/svg/trackNames.d.ts

@@ -12,10 +12,10 @@ export declare function svgTrackName(track: {
     configuration: AnyConfigurationModel;
 }, session: TrackCatalog): string;
 /**
- * Tell the user which visible tracks the export left out because their display
- * type implements no `renderSvg`. Called once per export, after the renders —
- * the stacked views flatten every row's `skippedTracks` into one call rather
- * than notifying per row.
+ * Tell the user which visible tracks the export left out, by default because
+ * their display type implements no `renderSvg`. Called once per reason per
+ * export, after the renders — the stacked views flatten every row's
+ * `skippedTracks` into one call rather than notifying per row.
  *
  * Skipping is deliberate (see `SvgExportTrack.renderSvg`), so this is
  * informational rather than an error. But it is not silent: a figure that is
@@ -24,4 +24,4 @@ export declare function svgTrackName(track: {
  */
 export declare function notifySkippedSvgTracks(session: NotificationSink & TrackCatalog, skipped: {
     configuration: AnyConfigurationModel;
-}[]): void;
+}[], reason?: string): void;

package/esm/svg/trackNames.js

@@ -12,20 +12,20 @@ export function svgTrackName(track, session) {
     return coarseStripHTML(getTrackName(track.configuration, session));
 }
 /**
- * Tell the user which visible tracks the export left out because their display
- * type implements no `renderSvg`. Called once per export, after the renders —
- * the stacked views flatten every row's `skippedTracks` into one call rather
- * than notifying per row.
+ * Tell the user which visible tracks the export left out, by default because
+ * their display type implements no `renderSvg`. Called once per reason per
+ * export, after the renders — the stacked views flatten every row's
+ * `skippedTracks` into one call rather than notifying per row.
  *
  * Skipping is deliberate (see `SvgExportTrack.renderSvg`), so this is
  * informational rather than an error. But it is not silent: a figure that is
  * quietly short a track is worse than one whose author was told why, and the
  * reader of the file has no way to tell the difference afterwards.
  */
-export function notifySkippedSvgTracks(session, skipped) {
+export function notifySkippedSvgTracks(session, skipped, reason = `${skipped.length === 1 ? 'Its display type does' : 'Their display types do'} not support SVG export.`) {
     if (skipped.length === 0) {
         return;
     }
     const names = skipped.map(t => svgTrackName(t, session)).join(', ');
-    session.notify(`Not included in the SVG: ${names}. ${skipped.length === 1 ? 'Its display type does' : 'Their display types do'} not support SVG export.`, 'info');
+    session.notify(`Not included in the SVG: ${names}. ${reason}`, 'info');
 }

package/esm/svg/wrapSvgExport.js

@@ -1,78 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { ThemeProvider } from '@mui/material';
-import { StyleThemeProvider } from '../ui/PaletteContext.js';
-import { resolveStyleTheme } from '../ui/styleTheme.js';
-import { createJBrowseTheme } from '../ui/theme.js';
-import { resetSvgClipIds } from '../util/SvgCanvas.js';
-import { renderToStaticMarkup } from '../util/renderToStaticMarkup.js';
 import { SVGExportRoot } from './SvgExport.js';
-// Coordinates computed as bp/bpPerPx land in attributes as long floats
-// (`-32.4816`) or floating-point noise (`242.23839999999998`), bloating exports
-// with sub-pixel precision no renderer needs. Round numbers inside a fixed
-// whitelist of numeric attributes, so a track label or id that happens to look
-// numeric is never a candidate for rewriting. Geometry gets 2 decimals
-// (sub-pixel); opacity keeps 3 so a faint 0.01 mark can't collapse to 0.
-const COORD_ATTRS = [
-    'x',
-    'y',
-    'x1',
-    'y1',
-    'x2',
-    'y2',
-    'cx',
-    'cy',
-    'r',
-    'rx',
-    'ry',
-    'dx',
-    'dy',
-    'width',
-    'height',
-    'd',
-    'points',
-    'transform',
-    'gradientTransform',
-    'offset',
-    'viewBox',
-    'font-size',
-    'stroke-width',
-    'stroke-dashoffset',
-    'stroke-dasharray',
-];
-const OPACITY_ATTRS = [
-    'opacity',
-    'fill-opacity',
-    'stroke-opacity',
-    'stop-opacity',
-    'flood-opacity',
-];
-function makeRounder(attrs, digits) {
-    const re = new RegExp(`\\b(${attrs.join('|')})="([^"]*)"`, 'g');
-    return (svg) => svg.replaceAll(re, (_, name, value) => {
-        const rounded = value.replaceAll(/-?\d+\.\d{3,}(?:e-?\d+)?/gi, n => String(Number.parseFloat(Number(n).toFixed(digits))));
-        return `${name}="${rounded}"`;
-    });
-}
-const roundCoords = makeRounder(COORD_ATTRS, 2);
-const roundOpacity = makeRounder(OPACITY_ATTRS, 3);
-function roundSvgNumbers(svg) {
-    return roundOpacity(roundCoords(svg));
-}
-// The identical tail every view's `renderToSvg` ends in: resolve the export
-// theme into a provider, apply the caller-supplied Wrapper, wrap the content in
-// the root <svg>, and serialize to a markup string. Callers keep their own
-// layout math and children — only this boilerplate lives here.
+import { SvgThemeProviders } from './SvgThemeProviders.js';
+import { serializeSvg } from './serializeSvg.js';
+// The identical tail every view's `renderToSvg` ends in: the export theme's
+// providers, the caller-supplied Wrapper, the root <svg>, and serialization to
+// a file's markup. Callers keep their own layout math and children.
 export function wrapSvgExport({ theme, width, height, margin, fontFamily, Wrapper = ({ children }) => children, children, }) {
-    // One document, one clip-id numbering run. The counter SvgCanvas draws from is
-    // document-global because SVG ids are, so left alone it also spans documents
-    // and numbers each export from wherever the last one stopped — see
-    // resetSvgClipIds. This is the only place that can reset it: the render below
-    // is synchronous, so it is the one moment a whole document's ids are minted
-    // with no other export able to interleave.
-    resetSvgClipIds();
-    // Both providers, from the same options — the export renders outside every
-    // React tree the app mounted, so a `makeStyles` component here would
-    // otherwise style itself from the *default* style theme and quietly ignore
-    // the theme the user picked in the export dialog.
-    return roundSvgNumbers(renderToStaticMarkup(_jsx(ThemeProvider, { theme: createJBrowseTheme(theme), children: _jsx(StyleThemeProvider, { theme: resolveStyleTheme({ configTheme: theme }), children: _jsx(Wrapper, { children: _jsx(SVGExportRoot, { width: width, height: height, margin: margin, fontFamily: fontFamily, children: children }) }) }) })));
+    return serializeSvg(_jsx(SvgThemeProviders, { theme: theme, children: _jsx(Wrapper, { children: _jsx(SVGExportRoot, { width: width, height: height, margin: margin, fontFamily: fontFamily, children: children }) }) }));
 }