@jbrowse/display-ui 5.0.0-beta.1 → 5.0.0-beta.11

package/README.md

@@ -36,7 +36,7 @@ above them.
 
 |                                             |                                                                                         |
 | ------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `DisplayChromeOverlays`                     | the five `displayPhase` states, as a component set, with the model shape each is handed |
+| `DisplayChromeOverlays`                     | the `displayPhase` states, as a five-component set, with the model shape each is handed |
 | `DisplayChromeOverlayProvider`              | redirects those states for JBrowse's own displays                                       |
 | `TrackControlComponent`                     | one shape for every ambient bottom-right control, icons named rather than passed        |
 | `TrackControlProvider`                      | redirects those                                                                         |
@@ -89,10 +89,9 @@ and the status text disappearing under them.
 It has never been reachable: the two displays that render the control row
 (alignments, canvas) are not among the four that report a `ready`-phase status
 (clustering, on multi-wiggle / multi-row features / maf / the multi-sample
-variant pair). That is the _reason_ to make it structural rather than to leave
-it — nothing on either side is aware of the constraint, so the first display to
-want both would find the bug, and it presents as a status message that silently
-never appears.
+variant pair). The layout is structural anyway, because neither side checks for
+the constraint, so the first display to want both would hit the bug as a status
+message that never appears.
 
 `BottomRightIndicators` already described itself as "the single anchor point for
 every bottom-right overlay ... so they lay out as one row instead of each
@@ -208,9 +207,9 @@ question only exists for an MST node.
 
 ### plainChromeOverlays
 
-The five `displayPhase` states drawn with no UI toolkit: no theme provider to
-mount, no emotion in the host page, and nothing that reads as a stray Material
-widget inside someone else's design system.
+The `displayPhase` states drawn with no UI toolkit: no theme provider to mount,
+no emotion in the host page, and nothing that reads as a stray Material widget
+inside someone else's design system.
 
 `DisplayUIProvider` installs this by default, so mount that rather than naming
 this — reach for it directly only to wrap a state or to build a context value by
@@ -288,9 +287,8 @@ toolkit, so the package's no-Material-UI guarantee holds.
 Takes a single element child and clones it rather than wrapping it: the controls
 that want a tooltip are absolutely positioned inside a legend or sit in a flex
 row, where an extra `<span>` moves them. The child keeps its own handlers —
-these compose on top of them. This is the same trigger pattern MUI's own
-`Tooltip` uses, which is what the rest of JBrowse's chrome is built on; the
-toolkit is what differs here, not the shape.
+these compose on top of them. MUI's `Tooltip`, which the rest of JBrowse's
+chrome is built on, uses the same trigger pattern; only the toolkit differs.
 
 ```tsx
 <Tooltip title="Hide legend">
@@ -366,8 +364,8 @@ under them with nothing to say so.
 this component: JBrowse's own track container passes 100, which is positioned
 above `PaddingBlocks` and below `TrackLabel` at 200, and means nothing to a host
 whose masks sit at 2. A default would be a number that is right in one layout
-and silently wrong in every other, and the failure — chrome painted under a mask
-— is invisible until someone looks at the right zoom.
+and wrong in every other, and the failure — chrome painted under a mask — goes
+unseen until someone looks at the right zoom.
 
 The node takes no pointer events, so it does not eat the canvas's. Chrome that
 wants them takes them back on its own positioned box; it also carries
@@ -430,4 +428,46 @@ carries position only.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/display-ui/src/trackControl/useTrackControlMenu.tsx)
 
+### ValueScale
+
+A value scale a display places its y through, declared so the chrome can derive
+the axis from it — the score axis's counterpart to a colour scale.
+
+`domain` is the resolved `[min, max]`; `height` the band it rules and `offset`
+the inset of the plot box inside that band (`axisPlotBox(height, offset)`);
+`minimalTicks` and `symlogConstant` how the ticks are chosen. `ticks` is the
+display's own ladder where the band's arithmetic is its own (the coverage band's
+octaves against the shader's box, the read cloud's decades against the arc
+geometry); `ScoreScaleMixin` derives one through `computeYTicks` otherwise.
+
+`bandTops` is the screen y of each band the scale rules — one at 0 unless the
+display stacks the same plot: the multi-wiggle's rows, a grouped alignments
+track's coverage band per group, each projected through the display's own
+scroll; the chrome drops the ones off screen. `[]` is a scale the display maps
+to colour rather than to y (density rows each in their own colour), which gets
+the `[min, max]` caption and no axis, as a scale whose bands are too short for
+one does. `side` and `left` are which of the band's edges the display's own
+panels leave clear for a gutter: `right` where a group label chip takes the
+left, `left: n` where a dendrogram takes the first `n` px. `caption` is what the
+scale measures (`TLEN`), as a colour scale's `field` is; the chrome draws it
+once for the scale, beside the bands on screen, however many it rules. `rules`
+are the reference lines the scale declares and `grid` a line at every tick, both
+drawn across every band.
+
+A member describes the scale or the band it rules, never the axis — not an
+orientation, a form, a gutter width or a font. The chrome reads a member to keep
+off what the display put in the band, never to choose between two drawings of it
+(ADR-109).
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/display-ui/src/valueScale.ts)
+
+### ValueScaleRule
+
+One reference line a value scale declares, at a value in the scale's own units.
+`label` is free text and carries no meaning the chrome assigns: over a coverage
+plot "2 copies" is a claim only the author can make, since no ploidy can be
+assumed.
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/display-ui/src/valueScale.ts)
+
 <!-- API_DOCS_END -->

package/esm/AxisCaption.d.ts

@@ -0,0 +1,24 @@
+import type { YAxis } from './valueScale.ts';
+/**
+ * A scale's caption, drawn once however many bands the scale rules: rotated
+ * along the outer edge of the gutter column, the origin at the column's top
+ * left, centred on the bands given as nearly as the display's `height` holds
+ * it whole, and cut to that height where it is longer. The on-screen overlay
+ * and the export both draw through this, so the two cannot place a caption
+ * differently.
+ */
+export default function AxisCaption({ axis, bandTops, height, }: {
+    axis: YAxis;
+    bandTops: number[];
+    height: number;
+}): import("react").JSX.Element | null;
+/**
+ * The on-screen caption of one scale: an `<svg>` over the gutter column, the
+ * height of the display, with `AxisCaption` inside.
+ */
+export declare function AxisCaptionOverlay({ axis, bandTops, width, height, }: {
+    axis: YAxis;
+    bandTops: number[];
+    width: number;
+    height: number;
+}): import("react").JSX.Element;

package/esm/AxisCaption.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePalette } from '@jbrowse/core/ui/PaletteContext';
+import { VERTICAL_SCROLLBAR_CLEARANCE } from '@jbrowse/core/ui/VerticalScrollbar';
+import { measureText } from '@jbrowse/core/util/measureText';
+import { axisCaptionY, axisGutterLeft, axisGutterWidth, } from './axisPlacement.js';
+import { AXIS_FONT_PX, CAPTION_INSET_PX } from './yAxisConstants.js';
+// The caption and its length, cut to an ellipsis where it is longer than
+// `room`, as a Vega-Lite axis title is cut at its `titleLimit`. The ellipsis
+// is one em.
+function fitCaption(caption, room) {
+    const whole = measureText(caption, AXIS_FONT_PX);
+    if (whole <= room) {
+        return { text: caption, length: whole };
+    }
+    for (let end = caption.length - 1; end > 0; end--) {
+        const length = measureText(caption.slice(0, end), AXIS_FONT_PX) + AXIS_FONT_PX;
+        if (length <= room) {
+            return { text: `${caption.slice(0, end)}…`, length };
+        }
+    }
+    return undefined;
+}
+/**
+ * A scale's caption, drawn once however many bands the scale rules: rotated
+ * along the outer edge of the gutter column, the origin at the column's top
+ * left, centred on the bands given as nearly as the display's `height` holds
+ * it whole, and cut to that height where it is longer. The on-screen overlay
+ * and the export both draw through this, so the two cannot place a caption
+ * differently.
+ */
+export default function AxisCaption({ axis, bandTops, height, }) {
+    const palette = usePalette();
+    const x = axis.side === 'right'
+        ? axisGutterWidth(axis) - CAPTION_INSET_PX
+        : CAPTION_INSET_PX;
+    const caption = fitCaption(axis.caption ?? '', height);
+    if (!caption) {
+        return null;
+    }
+    const half = caption.length / 2;
+    const y = Math.min(Math.max(axisCaptionY(axis, bandTops), half), height - half);
+    return (_jsx("text", { x: x, y: y, fontSize: AXIS_FONT_PX, textAnchor: "middle", fill: palette.text.primary, stroke: palette.background.default, strokeWidth: 2.5, paintOrder: "stroke", transform: `rotate(-90, ${x}, ${y})`, children: caption.text }));
+}
+/**
+ * The on-screen caption of one scale: an `<svg>` over the gutter column, the
+ * height of the display, with `AxisCaption` inside.
+ */
+export function AxisCaptionOverlay({ axis, bandTops, width, height, }) {
+    return (_jsx("svg", { style: {
+            position: 'absolute',
+            top: 0,
+            left: axisGutterLeft(axis, width, VERTICAL_SCROLLBAR_CLEARANCE),
+            pointerEvents: 'none',
+            height,
+            width: axisGutterWidth(axis),
+        }, children: _jsx(AxisCaption, { axis: axis, bandTops: bandTops, height: height }) }));
+}

package/esm/AxisGutter.d.ts

@@ -0,0 +1,12 @@
+import type { YAxis } from './valueScale.ts';
+/**
+ * One band's axis drawn inside its gutter, the origin at the gutter's left
+ * edge: the spine on the gutter's inner edge — its right for a left-side
+ * axis, its left for a right-side one — with the numbers growing outward. The
+ * on-screen overlay and the export both draw through this, so the two cannot
+ * place a spine differently. The scale's caption is `AxisCaption`'s, drawn once
+ * for the scale and not per band.
+ */
+export default function AxisGutter({ axis }: {
+    axis: YAxis;
+}): import("react").JSX.Element;

package/esm/AxisGutter.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import YScaleBar from './YScaleBar.js';
+import { axisGutterWidth } from './axisPlacement.js';
+/**
+ * One band's axis drawn inside its gutter, the origin at the gutter's left
+ * edge: the spine on the gutter's inner edge — its right for a left-side
+ * axis, its left for a right-side one — with the numbers growing outward. The
+ * on-screen overlay and the export both draw through this, so the two cannot
+ * place a spine differently. The scale's caption is `AxisCaption`'s, drawn once
+ * for the scale and not per band.
+ */
+export default function AxisGutter({ axis }) {
+    const right = axis.side === 'right';
+    return (_jsx("g", { transform: `translate(${right ? 0 : axisGutterWidth(axis)} 0)`, children: _jsx(YScaleBar, { ticks: axis.ticks, orientation: right ? 'right' : 'left', bandHeight: axis.height }) }));
+}

package/esm/CrossHatches.d.ts

@@ -0,0 +1,12 @@
+import type { YScaleTicks } from './yScaleTicks.ts';
+export declare function CrossHatchLines({ ticks, width, offsetY, }: {
+    ticks: YScaleTicks;
+    width: number;
+    offsetY?: number;
+}): import("react").JSX.Element;
+export default function CrossHatches({ ticks, width, height, bandTops, }: {
+    ticks: YScaleTicks;
+    width: number;
+    height: number;
+    bandTops: number[];
+}): import("react").JSX.Element;

package/esm/CrossHatches.js

@@ -0,0 +1,31 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { clampStrokeInsideAxis } from './yScaleTicks.js';
+// Bare <line> set for the Y-scale tick guide lines, no wrapping <svg>. Shared by
+// the absolutely-positioned on-screen CrossHatches overlay and the flat SVG
+// export, so the two can't drift. `offsetY` is the band's top.
+export function CrossHatchLines({ ticks, width, offsetY = 0, }) {
+    return (_jsx(_Fragment, { children: ticks.items.map(({ value, y }) => {
+            // Same clamp the axis ticks take, so a guide line and the tick it
+            // belongs to can't disagree at the bottom edge — where, in multi-wiggle,
+            // "one pixel lower" is the next sample's row. Only that edge moves; the
+            // guide lines don't crispen to a half pixel the way the axis does.
+            const lineY = offsetY + clampStrokeInsideAxis(y, ticks.yBottom);
+            return (_jsx("line", { x1: 0, x2: width, y1: lineY, y2: lineY, stroke: "rgb(200,200,200)", 
+                // a separate stroke-opacity attribute (not baked into an rgba()
+                // string) survives the SVG export, whose renderToStaticMarkup strips
+                // rgba() alpha
+                strokeOpacity: 0.8, strokeWidth: 1 }, `${value}-${y}`));
+        }) }));
+}
+// Horizontal guide lines at each Y-scale tick, once per band the scale rules.
+// Pointer-events disabled so the underlying canvas still receives mouse events.
+export default function CrossHatches({ ticks, width, height, bandTops, }) {
+    return (_jsx("svg", { style: {
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            pointerEvents: 'none',
+            height,
+            width,
+        }, children: bandTops.map(top => (_jsx(CrossHatchLines, { ticks: ticks, width: width, offsetY: top }, top))) }));
+}

package/esm/FloatingLegend.d.ts

@@ -1,16 +1,14 @@
 import type { LegendItem, LegendSection } from '@jbrowse/core/ui/legendSpec';
-import type { ReactNode } from 'react';
-export type { LegendItem, LegendMark, LegendSection, LegendSpec, LegendSwatch, } from '@jbrowse/core/ui/legendSpec';
-declare const FloatingLegend: ({ items, sections, title, onDismiss, onDismissSection, onItemClick, maxItems, maxWidth, top, children, }: {
-    items?: LegendItem[];
-    sections?: LegendSection[];
+export type { LegendGradient, LegendItem, LegendSection, LegendSpec, LegendSwatch, } from '@jbrowse/core/ui/legendSpec';
+declare const FloatingLegend: ({ sections, title, onDismiss, onDismissSection, onItemClick, maxItems, maxWidth, top, right, }: {
+    sections: readonly LegendSection[];
     title?: string;
-    children?: ReactNode;
     onDismiss?: () => void;
     onDismissSection?: (id: string) => void;
     onItemClick?: (item: LegendItem, section: LegendSection) => void;
     maxItems?: number;
     maxWidth?: number;
     top?: number;
+    right?: number;
 }) => import("react").JSX.Element | null;
 export default FloatingLegend;

package/esm/FloatingLegend.js

@@ -8,12 +8,12 @@ import { LegendSwatchGlyph } from '@jbrowse/core/ui/LegendSwatchGlyph';
 import { legendSwatches, nonEmptyLegendSections, } from '@jbrowse/core/ui/legendSpec';
 import { cx, makeStyles } from '@jbrowse/core/util/tss-react';
 import { observer } from 'mobx-react';
+import { FLOATING_LEGEND_RIGHT_PX, FLOATING_LEGEND_TOP_PX, } from './floatingLegendTop.js';
 import Tooltip from './tooltip/Tooltip.js';
 import { TrackOverlayPortal } from './trackOverlay/TrackOverlayPortal.js';
 const useStyles = makeStyles()(theme => ({
     legend: {
         position: 'absolute',
-        right: 10,
         background: theme.palette.background.paper,
         // A hairline edge, because `background.paper` on a track whose canvas is
         // also paper-white is no edge at all: the key read as loose text floating
@@ -25,6 +25,9 @@ const useStyles = makeStyles()(theme => ({
         border: `1px solid ${theme.palette.divider}`,
         borderRadius: 3,
         padding: 3,
+        // Two keys on one short display ran past its bottom edge and were cut
+        // there; the box scrolls inside the display instead.
+        overflowY: 'auto',
         fontSize: 10,
         zIndex: 100,
         // the default; `maxWidth` overrides it per display
@@ -34,20 +37,9 @@ const useStyles = makeStyles()(theme => ({
         // rendered inline, where events already pass through)
         pointerEvents: 'auto',
     },
-    // A plain <button>, not MUI's IconButton, and the glyph is `×` rather than
-    // the Material Close icon.
-    //
-    // This component is rendered by canvas, alignments, variants and multi-wiggle
-    // displays *directly*, behind neither bring-your-own seam, so a Material
-    // widget here reaches an embedder who has opted out of both — and the
-    // build-your-own site's zero-MUI census, which no page currently trips only
-    // because no page turns on a colorBy that raises a legend. Same call
-    // `BaseTooltip` made in 2026-08: what it needed was colors, and colors have a
-    // toolkit-free home already. See DISPLAYCHROME.md, "a third seam was
-    // considered for the tooltip and rejected".
-    //
-    // `×` is what `SvgColorLegend` already draws for this control, so the
-    // exported legend and the on-screen one now agree.
+    // A plain <button> with a `×` glyph, not MUI: displays render this legend
+    // directly, behind neither bring-your-own seam. See DISPLAYCHROME.md, "The
+    // bring-your-own seams".
     closeButton: {
         position: 'absolute',
         top: 0,
@@ -87,6 +79,13 @@ const useStyles = makeStyles()(theme => ({
         overflow: 'hidden',
         textOverflow: 'ellipsis',
     },
+    // Wraps where every other line ellipsizes: a note is a sentence, and half of
+    // one says nothing.
+    sectionNote: {
+        color: theme.palette.text.secondary,
+        whiteSpace: 'normal',
+        marginBottom: 2,
+    },
     sectionClose: {
         font: 'inherit',
         lineHeight: 1,
@@ -134,6 +133,28 @@ const useStyles = makeStyles()(theme => ({
         overflow: 'hidden',
         textOverflow: 'ellipsis',
     },
+    hiddenItem: {
+        opacity: 0.4,
+        textDecoration: 'line-through',
+    },
+    gradientRow: {
+        marginBottom: 1,
+    },
+    gradientBar: {
+        width: GRADIENT_BAR_WIDTH,
+        height: 10,
+        borderRadius: 2,
+        border: `1px solid ${theme.palette.divider}`,
+        // clip the gradient to the padding box so it doesn't paint under the
+        // translucent divider border — otherwise the border composites over the
+        // gradient's end and the edge renders a dark sliver
+        backgroundClip: 'padding-box',
+    },
+    gradientLabels: {
+        display: 'flex',
+        justifyContent: 'space-between',
+        width: GRADIENT_BAR_WIDTH,
+    },
     // was `<Link component="button" underline="hover">`, which is the same
     // element with Material's typography on it — see `closeButton` above for why
     // that mattered
@@ -146,7 +167,7 @@ const useStyles = makeStyles()(theme => ({
         border: 0,
         background: 'none',
         textAlign: 'left',
-        color: theme.palette.primary.main,
+        color: theme.palette.accent,
         cursor: 'pointer',
         '&:hover': {
             textDecoration: 'underline',
@@ -155,56 +176,88 @@ const useStyles = makeStyles()(theme => ({
 }));
 const DEFAULT_MAX_ITEMS = 12;
 const DEFAULT_MAX_WIDTH = 200;
-// Side of one mark. The old fixed color box's size, kept so a legend of plain
-// fills is pixel-identical to what shipped before marks existed.
+const GRADIENT_BAR_WIDTH = 100;
+// Side of one swatch box.
 const SWATCH = 12;
+// A ramp row: the caption, the bar and the domain ends. The bar is a CSS
+// gradient over the same stops the export's <linearGradient> takes, so the
+// two draw one ramp. Stops are flattened over the paper because a translucent
+// first stop (Hi-C's juicebox fade) rasterizes to a dark sliver at the bar's
+// left edge.
+function gradientCss({ stops }, paper) {
+    const list = stops.map(({ color, opacity = 1, offset }) => {
+        const flat = opacity >= 1
+            ? color
+            : `color-mix(in srgb, ${color} ${Math.round(opacity * 100)}%, ${paper})`;
+        return `${flat} ${offset * 100}%`;
+    });
+    return `linear-gradient(to right, ${list.join(', ')})`;
+}
+function GradientRow({ label, gradient, }) {
+    const { classes, theme } = useStyles();
+    return (_jsxs("div", { className: classes.gradientRow, children: [label ? _jsx("div", { className: classes.label, children: label }) : null, _jsx("div", { className: classes.gradientBar, 
+                // backgroundImage (longhand), not the `background` shorthand: the
+                // shorthand resets background-clip back to border-box, undoing the
+                // padding-box clip
+                style: {
+                    backgroundImage: gradientCss(gradient, theme.palette.background.paper),
+                } }), _jsxs("div", { className: classes.gradientLabels, children: [_jsx("span", { children: gradient.minLabel }), _jsx("span", { children: gradient.maxLabel })] })] }));
+}
 // One list of swatches with its own independent collapse state, so each section
 // in a multi-section legend expands/collapses on its own.
 const LegendItemList = observer(function LegendItemList({ items, maxItems, onItemClick, }) {
     const { classes } = useStyles();
     const [expanded, setExpanded] = useState(false);
-    const collapsible = items.length > maxItems;
+    // A toggle revealing one row costs the row it saves.
+    const collapsible = items.length > maxItems + 1;
     const shown = collapsible && !expanded ? items.slice(0, maxItems) : items;
     const hiddenCount = items.length - maxItems;
-    // Every row reserves the widest row's swatch column, so labels stay in one
-    // vertical line whether a row draws one mark or two — and so a color-less
-    // heading row indents like the swatches it heads, as the fixed-size box it
-    // replaces used to.
-    const columns = Math.max(1, ...shown.map(i => legendSwatches(i).length));
+    // Every row reserves the widest row's swatch column, collapsed or not, so
+    // labels stay in one vertical line and do not shift on expanding.
+    const columns = Math.max(1, ...items.map(i => legendSwatches(i).length));
     return (_jsxs(_Fragment, { children: [shown.map((item, i) => {
-                const row = (_jsxs(_Fragment, { children: [_jsx("div", { className: classes.swatches, style: { minWidth: columns * SWATCH + (columns - 1) * 2 }, children: legendSwatches(item).map(swatch => (_jsx("svg", { width: SWATCH, height: SWATCH, children: _jsx(LegendSwatchGlyph, { swatch: swatch, size: SWATCH }) }, `${swatch.color}-${swatch.mark ?? 'fill'}`))) }), _jsx("span", { className: classes.label, children: item.label })] }));
-                return onItemClick ? (_jsx("button", { type: "button", className: cx(classes.item, classes.itemButton), title: "Show only these rows", onClick: () => {
+                if (item.gradient) {
+                    return (_jsx(GradientRow
+                    // eslint-disable-next-line @eslint-react/no-array-index-key
+                    , { label: item.label, gradient: item.gradient }, `${item.label}-${i}`));
+                }
+                const row = (_jsxs(_Fragment, { children: [_jsx("div", { className: classes.swatches, style: { minWidth: columns * SWATCH + (columns - 1) * 2 }, children: legendSwatches(item).map(swatch => (_jsx("svg", { width: SWATCH, height: SWATCH, children: _jsx(LegendSwatchGlyph, { swatch: swatch, size: SWATCH }) }, `${swatch.shape}-${swatch.color}`))) }), _jsx("span", { className: classes.label, children: item.label })] }));
+                const itemClass = cx(classes.item, item.hidden && classes.hiddenItem);
+                return onItemClick ? (_jsx("button", { type: "button", className: cx(itemClass, classes.itemButton), title: "Show only these rows", onClick: () => {
                         onItemClick(item);
-                    }, children: row }, `${item.label}-${i}`)) : (_jsx("div", { className: classes.item, children: row }, `${item.label}-${i}`));
+                    }, children: row }, `${item.label}-${i}`)) : (_jsx("div", { className: itemClass, children: row }, `${item.label}-${i}`));
             }), collapsible ? (_jsx("button", { type: "button", className: classes.toggle, onClick: () => {
                     setExpanded(!expanded);
                 }, children: expanded ? 'Show less' : `Show ${hiddenCount} more…` })) : null] }));
 });
-// Floating color-key overlay. Pass a flat `items` list for a single scheme, or
-// `sections` to show several titled, individually-closable panels in one box
-// (e.g. genotype colors vs. sample-grouping colors on the multi-sample variant
-// display). Section titles + per-section close buttons only appear when there
-// is more than one section, so a single-scheme legend looks unchanged. `title`
-// is a heading for the whole box, shown regardless of section count.
+// Floating color-key overlay: one panel per section (e.g. genotype colors vs.
+// sample-grouping colors on the multi-sample variant display). Section titles
+// and per-section close buttons only appear when there is more than one
+// section, so a single-scheme legend is just its rows. `title` is a heading
+// for the whole box, shown regardless of section count.
 //
-// `onItemClick` makes the rows act — for a key whose entries name groups of
-// rows, clicking one focuses those rows. It is handed the section too, so a
-// display with several vocabularies can act on the one that names rows and
-// leave the others inert.
-const FloatingLegend = observer(function FloatingLegend({ items, sections, title, onDismiss, onDismissSection, onItemClick, maxItems = DEFAULT_MAX_ITEMS, maxWidth = DEFAULT_MAX_WIDTH, top = 10, children, }) {
+// `onItemClick` makes the rows of a section declaring `focusesRows` act —
+// clicking an entry focuses the rows it names. A section coloring features or
+// cells stays inert text beside it.
+const FloatingLegend = observer(function FloatingLegend({ sections, title, onDismiss, onDismissSection, onItemClick, maxItems = DEFAULT_MAX_ITEMS, maxWidth = DEFAULT_MAX_WIDTH, top = FLOATING_LEGEND_TOP_PX, right = FLOATING_LEGEND_RIGHT_PX, }) {
     const { classes } = useStyles();
-    const nonEmpty = nonEmptyLegendSections({ items, sections });
-    if (nonEmpty.length === 0 && !children) {
+    const nonEmpty = nonEmptyLegendSections(sections);
+    if (nonEmpty.length === 0) {
         return null;
     }
     const multiSection = nonEmpty.length > 1;
     // portal above the inter-region padding masks so the key isn't buried at
     // whole-genome / multi-region scale (see TrackOverlayPortal)
-    return (_jsx(TrackOverlayPortal, { children: _jsxs("div", { className: cx(classes.legend, onDismiss && classes.withClose), style: { top, maxWidth }, "data-testid": "floating-legend", "data-gesture-owner": "true", children: [onDismiss ? (_jsx(Tooltip, { title: "Hide legend", children: _jsx("button", { type: "button", className: classes.closeButton, "aria-label": "Hide legend", onClick: () => {
+    return (_jsx(TrackOverlayPortal, { children: _jsxs("div", { className: cx(classes.legend, onDismiss && classes.withClose), style: {
+                top,
+                right,
+                maxWidth,
+                maxHeight: `calc(100% - ${top + 4}px)`,
+            }, "data-testid": "floating-legend", "data-gesture-owner": "true", children: [onDismiss ? (_jsx(Tooltip, { title: "Hide legend", children: _jsx("button", { type: "button", className: classes.closeButton, "aria-label": "Hide legend", onClick: () => {
                             onDismiss();
-                        }, children: "\u00D7" }) })) : null, title ? _jsx("div", { className: classes.topTitle, children: title }) : null, children, nonEmpty.map(section => (_jsxs("div", { className: classes.section, children: [multiSection && section.title ? (_jsxs("div", { className: classes.sectionHeader, children: [_jsx("span", { className: classes.sectionTitle, children: section.title }), onDismissSection ? (_jsx(Tooltip, { title: `Hide ${section.title}`, children: _jsx("button", { type: "button", className: classes.sectionClose, "aria-label": `Hide ${section.title}`, onClick: () => {
+                        }, children: "\u00D7" }) })) : null, title ? _jsx("div", { className: classes.topTitle, children: title }) : null, nonEmpty.map(section => (_jsxs("div", { className: classes.section, children: [multiSection && section.title ? (_jsxs("div", { className: classes.sectionHeader, children: [_jsx("span", { className: classes.sectionTitle, children: section.title }), onDismissSection ? (_jsx(Tooltip, { title: `Hide ${section.title}`, children: _jsx("button", { type: "button", className: classes.sectionClose, "aria-label": `Hide ${section.title}`, onClick: () => {
                                             onDismissSection(section.id);
-                                        }, children: "\u00D7" }) })) : null] })) : null, _jsx(LegendItemList, { items: section.items, maxItems: maxItems, onItemClick: onItemClick
+                                        }, children: "\u00D7" }) })) : null] })) : null, section.note ? (_jsx("div", { className: classes.sectionNote, children: section.note })) : null, _jsx(LegendItemList, { items: section.items, maxItems: maxItems, onItemClick: onItemClick && section.focusesRows
                                 ? item => {
                                     onItemClick(item, section);
                                 }

package/esm/FloatingSvgOverlay.d.ts

@@ -0,0 +1,5 @@
+export declare const FloatingSvgOverlay: ({ width, height, children, }: {
+    width: number;
+    height: number;
+    children: React.ReactNode;
+}) => import("react").JSX.Element;

package/esm/FloatingSvgOverlay.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { observer } from 'mobx-react';
+import { TrackOverlayPortal } from './trackOverlay/TrackOverlayPortal.js';
+// Lifts an SVG legend / chrome above the inter-region padding masks: a
+// full-track, pointer-events:none <svg> portaled into the TrackContainer overlay
+// node (see TrackOverlayPortal). The SVG counterpart to the HTML overlays
+// (FloatingLegend, HicOverlayPanel) — used where the same legend
+// markup is also drawn by an SVG-export path, so it must stay <svg>.
+//
+// Children draw in <svg> user space; the wrapping <svg> stays pointer-events:none
+// so it doesn't eat canvas events, so any interactive sub-content (a dismiss
+// "×", clickable swatches) must set pointer-events:auto on its own element.
+// fallbackInline={false}: outside a TrackContainer it renders nothing, matching
+// callers whose export path draws its own inline legend.
+export const FloatingSvgOverlay = observer(function FloatingSvgOverlay({ width, height, children, }) {
+    return (_jsx(TrackOverlayPortal, { fallbackInline: false, children: _jsx("svg", { style: {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width,
+                height,
+                pointerEvents: 'none',
+                overflow: 'hidden',
+            }, children: children }) }));
+});

package/esm/FloatingText.d.ts

@@ -0,0 +1,50 @@
+import type { CSSProperties, ComponentPropsWithoutRef, ReactNode } from 'react';
+/**
+ * Four offset shadows in the surface colour: a halo under a line of DOM text
+ * that needs no measured stroke and reads the same over a mark and over the
+ * background.
+ */
+export declare function textHalo(color: string): string;
+/**
+ * Where a line box's glyph baseline sits below its top, as a fraction of the
+ * font size. A DOM label is positioned by its top and an exported `<text>` by
+ * its baseline, and this is what puts the two on one line.
+ */
+export declare const TEXT_BASELINE_RATIO = 0.84;
+/**
+ * One line of text floated over a display, at the px `x` and `y` of its line
+ * box's top-left corner: absolutely positioned, one line high, never wrapped.
+ * The canvas feature labels and the mark display's text marks emit through
+ * this, so the typography of a floated label is one declaration; what places
+ * each label is its display's own rule. `halo` draws {@link textHalo} under
+ * the glyphs in that colour. Everything else a caller passes reaches the div:
+ * a class for the pointer and the cursor, the data attributes a delegated
+ * handler reads, a `title`.
+ */
+export declare function FloatingText({ x, y, color, fontSize, halo, style, children, ...rest }: {
+    x: number;
+    y: number;
+    color: string;
+    fontSize: number;
+    halo?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'style' | 'color' | 'children'>): import("react").JSX.Element;
+/**
+ * The same line in an SVG export: two `<text>`s at the baseline `y`, a stroke
+ * in the surface colour under the glyphs, since SVG paints stroke over fill
+ * and a thick stroke beneath a second copy is how a halo is drawn there. Both
+ * carry the size and family explicitly, because a `<text>` with neither takes
+ * SVG's 16px default in a saved file.
+ */
+export declare function SvgHaloText({ x, y, fill, halo, haloWidth, fontSize, fontFamily, anchor, children, }: {
+    x: number;
+    y: number;
+    fill: string;
+    halo: string;
+    haloWidth: number | string;
+    fontSize: number;
+    fontFamily: string;
+    anchor?: 'start' | 'middle' | 'end';
+    children: ReactNode;
+}): import("react").JSX.Element;

package/esm/FloatingText.js

@@ -0,0 +1,48 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Four offset shadows in the surface colour: a halo under a line of DOM text
+ * that needs no measured stroke and reads the same over a mark and over the
+ * background.
+ */
+export function textHalo(color) {
+    return `-1px -1px 0 ${color}, 1px -1px 0 ${color}, -1px 1px 0 ${color}, 1px 1px 0 ${color}`;
+}
+/**
+ * Where a line box's glyph baseline sits below its top, as a fraction of the
+ * font size. A DOM label is positioned by its top and an exported `<text>` by
+ * its baseline, and this is what puts the two on one line.
+ */
+export const TEXT_BASELINE_RATIO = 0.84;
+/**
+ * One line of text floated over a display, at the px `x` and `y` of its line
+ * box's top-left corner: absolutely positioned, one line high, never wrapped.
+ * The canvas feature labels and the mark display's text marks emit through
+ * this, so the typography of a floated label is one declaration; what places
+ * each label is its display's own rule. `halo` draws {@link textHalo} under
+ * the glyphs in that colour. Everything else a caller passes reaches the div:
+ * a class for the pointer and the cursor, the data attributes a delegated
+ * handler reads, a `title`.
+ */
+export function FloatingText({ x, y, color, fontSize, halo, style, children, ...rest }) {
+    return (_jsx("div", { ...rest, style: {
+            position: 'absolute',
+            lineHeight: 1,
+            whiteSpace: 'nowrap',
+            color,
+            fontSize,
+            transform: `translate(${x}px, ${y}px)`,
+            ...(halo ? { textShadow: textHalo(halo) } : {}),
+            ...style,
+        }, children: children }));
+}
+/**
+ * The same line in an SVG export: two `<text>`s at the baseline `y`, a stroke
+ * in the surface colour under the glyphs, since SVG paints stroke over fill
+ * and a thick stroke beneath a second copy is how a halo is drawn there. Both
+ * carry the size and family explicitly, because a `<text>` with neither takes
+ * SVG's 16px default in a saved file.
+ */
+export function SvgHaloText({ x, y, fill, halo, haloWidth, fontSize, fontFamily, anchor = 'start', children, }) {
+    const attrs = { x, y, fontSize, fontFamily, textAnchor: anchor };
+    return (_jsxs(_Fragment, { children: [_jsx("text", { ...attrs, stroke: halo, strokeWidth: haloWidth, strokeLinejoin: "round", children: children }), _jsx("text", { ...attrs, fill: fill, children: children })] }));
+}