@jbrowse/display-ui 4.3.0

package/esm/trackOverlay/TrackOverlayPortal.js

@@ -0,0 +1,66 @@
+import { use } from 'react';
+import { observer } from 'mobx-react';
+import { createPortal } from 'react-dom';
+import { TrackOverlayContext } from './TrackOverlayContext.js';
+// Portals floating track chrome (legends, badges, on-canvas overlays) into the
+// TrackContainer's overlay node, which is mounted *above* the inter-region
+// padding masks (elided/boundary/region-separator blocks). A display's own
+// React tree is sealed in a `contain:strict` sandbox those masks paint over, so
+// anything rendered inline there gets buried at whole-genome / multi-region
+// scale. Wrapping it here lifts it above the masks without the display knowing
+// how the LGV lays them out — the single reusable answer to that recurring
+// problem (previously re-solved per-display: the multi-wiggle color key,
+// FloatingLegend).
+//
+// The sandbox is `contain: strict`, and the obvious simplification — drop the
+// containment so chrome can just out-z-index the masks and none of this is
+// needed — is measured and rejected (ADR-058): it costs 2.4-4.8x paint time
+// under DOM load, because the stacking context that blocks the z-index is the
+// same thing that isolates the paint. See `browser-tests/probe-containment.ts`
+// in jbrowse-web and the comment on `trackRenderingContainer`. The portal buys
+// both.
+//
+// The overlay node is `pointer-events:none` (so it doesn't eat canvas
+// events), and that does NOT change here — children that should capture hover
+// (any interactive legend/panel) must set `pointer-events:auto` on their own
+// positioned box, or hovering them falls through to feature tooltips / click
+// actions on the canvas below. It can't be defaulted here: the value must live
+// on the positioned element itself, and full-span SVG overlays deliberately
+// stay `none` except on their sub-content (see FloatingLegend).
+//
+// Taking events back is all a panel has to do: the overlay node carries
+// `data-gesture-owner`, so the LGV's click-drag pan already skips anything in
+// this layer that can be a press target (TrackContainer). Without that, every
+// panel here would separately have to know that dragging its own text pans the
+// view under it — which is how it shipped, on the legend and the Hi-C panel.
+// The `fallbackInline` path renders outside that node, so chrome that is
+// interactive AND meaningful inline still declares its own marker.
+//
+// `TrackOverlayContext` is null outside a TrackContainer (some tests, or a
+// display used standalone). `fallbackInline` (default) then renders the children
+// in place, preserving behavior for chrome that is still meaningful without the
+// escape (e.g. FloatingLegend). Pass `fallbackInline={false}` for chrome that
+// only makes sense above the masks and has its own non-masked path elsewhere
+// (e.g. the multi-wiggle overlay legend, whose SVG-export path draws its own).
+/**
+ * #api
+ * Lift floating track chrome out of the display's `contain: strict` sandbox and
+ * into the host's overlay node, so the LGV's inter-region masks cannot bury it
+ * at multi-region scale. `TrackOverlaySlot` is the other end.
+ *
+ * The overlay node takes no pointer events, so anything of yours the user
+ * hovers or clicks sets `pointer-events: auto` on its own positioned box.
+ *
+ * With no slot above it this renders the children in place (`fallbackInline`,
+ * the default), which preserves chrome that is still meaningful unescaped. Pass
+ * `fallbackInline={false}` for chrome that only makes sense above the masks and
+ * draws itself some other way elsewhere.
+ */
+export const TrackOverlayPortal = observer(function TrackOverlayPortal({ children, fallbackInline = true, }) {
+    const overlayEl = use(TrackOverlayContext);
+    return overlayEl
+        ? createPortal(children, overlayEl)
+        : fallbackInline
+            ? children
+            : null;
+});

package/esm/trackOverlay/TrackOverlaySlot.d.ts

@@ -0,0 +1,54 @@
+/**
+ * #api
+ * The box a display is mounted in, plus the overlay node its floating chrome
+ * escapes into. Pair to `TrackOverlayPortal`, which is the other end.
+ *
+ * A display's React tree is sealed in a `contain: strict` sandbox — that is what
+ * isolates its paint, and dropping it is measured and rejected (ADR-058). A
+ * stacking context comes with the isolation, so floating chrome a display draws
+ * (a colour key, hi-c's overlay panel, maf's row labels) cannot out-z-index
+ * anything painted over the track stack from outside. The escape is a node
+ * mounted *beside* the sandbox rather than inside it, published through
+ * `TrackOverlayContext`; this component is that node, its context and the paint
+ * order between them, in the one place they have to agree.
+ *
+ * `TrackContainer` uses it, so JBrowse's own layout and an embedder's go through
+ * the same code rather than two copies of one rule. **An embedder mounting
+ * `RenderingComponent` directly needs it too**, and that is the case it was
+ * added for: with no provider the context is null, the portal falls back to
+ * rendering inline, and a host that paints region seams over its column buries
+ * the chrome under them with nothing to say so.
+ *
+ * ```tsx
+ * <TrackOverlaySlot zIndex={3} style={{ height: display.height }}>
+ *   <div style={{ position: 'absolute', inset: 0, contain: 'strict' }}>
+ *     <RenderingComponent model={display} />
+ *   </div>
+ * </TrackOverlaySlot>
+ * ```
+ *
+ * **`zIndex` is required, and deliberately has no default.** It is the answer to
+ * "above what?", and that is a fact about the caller's layout rather than about
+ * 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.
+ *
+ * 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
+ * `data-gesture-owner`, so anything that does is already exempt from the LGV's
+ * click-drag pan.
+ */
+export declare function TrackOverlaySlot({ children, zIndex, style, overlayStyle, }: {
+    children: React.ReactNode;
+    /** Paint order for the overlay node, against whatever the caller draws over
+     * the track stack. No default on purpose — see above. */
+    zIndex: number;
+    /** The box the display is mounted in. Its height, usually. */
+    style?: React.CSSProperties;
+    /** Placement escape for the overlay node. `TrackContainer` passes a negative
+     * `left` to cancel its Paper border, so the node covers the canvas
+     * edge-to-edge rather than leaving a sliver. */
+    overlayStyle?: React.CSSProperties;
+}): import("react").JSX.Element;

package/esm/trackOverlay/TrackOverlaySlot.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { TrackOverlayContext } from './TrackOverlayContext.js';
+/**
+ * #api
+ * The box a display is mounted in, plus the overlay node its floating chrome
+ * escapes into. Pair to `TrackOverlayPortal`, which is the other end.
+ *
+ * A display's React tree is sealed in a `contain: strict` sandbox — that is what
+ * isolates its paint, and dropping it is measured and rejected (ADR-058). A
+ * stacking context comes with the isolation, so floating chrome a display draws
+ * (a colour key, hi-c's overlay panel, maf's row labels) cannot out-z-index
+ * anything painted over the track stack from outside. The escape is a node
+ * mounted *beside* the sandbox rather than inside it, published through
+ * `TrackOverlayContext`; this component is that node, its context and the paint
+ * order between them, in the one place they have to agree.
+ *
+ * `TrackContainer` uses it, so JBrowse's own layout and an embedder's go through
+ * the same code rather than two copies of one rule. **An embedder mounting
+ * `RenderingComponent` directly needs it too**, and that is the case it was
+ * added for: with no provider the context is null, the portal falls back to
+ * rendering inline, and a host that paints region seams over its column buries
+ * the chrome under them with nothing to say so.
+ *
+ * ```tsx
+ * <TrackOverlaySlot zIndex={3} style={{ height: display.height }}>
+ *   <div style={{ position: 'absolute', inset: 0, contain: 'strict' }}>
+ *     <RenderingComponent model={display} />
+ *   </div>
+ * </TrackOverlaySlot>
+ * ```
+ *
+ * **`zIndex` is required, and deliberately has no default.** It is the answer to
+ * "above what?", and that is a fact about the caller's layout rather than about
+ * 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.
+ *
+ * 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
+ * `data-gesture-owner`, so anything that does is already exempt from the LGV's
+ * click-drag pan.
+ */
+export function TrackOverlaySlot({ children, zIndex, style, overlayStyle, }) {
+    // element state rather than a ref, so consumers re-render once the portal
+    // target mounts and the context value flips from null to the node
+    const [overlayEl, setOverlayEl] = useState(null);
+    return (_jsxs("div", { "data-track-overlay-slot": "true", style: { position: 'relative', ...style }, children: [_jsx(TrackOverlayContext, { value: overlayEl, children: children }), _jsx("div", { ref: setOverlayEl, "data-gesture-owner": "true", "data-track-overlay-node": "true", style: {
+                    position: 'absolute',
+                    top: 0,
+                    bottom: 0,
+                    left: 0,
+                    width: '100%',
+                    pointerEvents: 'none',
+                    zIndex,
+                    ...overlayStyle,
+                } })] }));
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@jbrowse/display-ui",
+  "version": "4.3.0",
+  "type": "module",
+  "description": "The UI a display draws that is not data: the swappable chrome contract, its toolkit-free implementations, and the track overlay layer",
+  "keywords": [
+    "jbrowse",
+    "jbrowse2",
+    "embedding"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://jbrowse.org",
+  "bugs": "https://github.com/GMOD/jbrowse-components/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GMOD/jbrowse-components.git",
+    "directory": "packages/display-ui"
+  },
+  "author": "JBrowse Team",
+  "main": "esm/index.js",
+  "files": [
+    "esm"
+  ],
+  "dependencies": {
+    "@jbrowse/mobx-state-tree": "^6.5.1",
+    "mobx-react": "^10.0.2",
+    "@jbrowse/core": "^4.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build:esm": "node ../../node_modules/typescript7/bin/tsc --build tsconfig.build.esm.json",
+    "build": "pnpm build:esm",
+    "test": "cd ../..; jest --passWithNoTests packages/display-ui",
+    "clean": "rimraf esm *.tsbuildinfo",
+    "prebuild": "pnpm clean"
+  },
+  "types": "esm/index.d.ts",
+  "exports": {
+    ".": "./esm/index.js"
+  }
+}