@jbrowse/display-ui 4.3.0

package/esm/chromeOverlays.d.ts

@@ -0,0 +1,88 @@
+import type { ComponentType } from 'react';
+/** What `ErrorBar` reads: a failed fetch, and the way to run it again. */
+export interface DisplayErrorBarModel {
+    error: unknown;
+    reload: () => void;
+}
+/** What `Loading` reads. Everything is optional — a display that reports no
+ * progress and offers no cancel still gets a scrim. */
+export interface DisplayLoadingOverlayModel {
+    statusMessage?: string;
+    statusProgress?: number;
+    fetchCanceled?: boolean;
+    cancelFetchByUser?: () => void;
+    reload?: () => void;
+}
+/** What `BackgroundProgress` reads: the status channel for work with no fetch
+ * behind it, while the phase is `ready`. */
+export interface DisplayBackgroundProgressModel {
+    statusMessage?: string;
+    statusProgress?: number;
+}
+/** What `TooLarge` reads. `forceLoad` is the whole point of the state — see the
+ * entry below. */
+export interface TooLargeMessageModel {
+    regionTooLargeReason: string;
+    zoomCanReleaseGate: boolean;
+    forceLoad: () => void;
+}
+export interface DisplayChromeOverlays {
+    /**
+     * GPU/render-backend failure. A subtree-replacing terminal state: the canvas
+     * unmounts and the backend disposes, so this owns the full display area.
+     */
+    RenderError: ComponentType<{
+        error: unknown;
+        onRetry: () => void;
+        height: number;
+    }>;
+    /**
+     * The byte gate tripped. Also subtree-replacing. Must offer `model.forceLoad`
+     * or the region becomes unreachable for the rest of the session.
+     */
+    TooLarge: ComponentType<{
+        model: TooLargeMessageModel;
+    }>;
+    /**
+     * Fetch error, drawn *over* a live canvas rather than replacing it. Mounted
+     * unconditionally like the two below, so `visible` (`displayPhase ===
+     * 'error'`) is the gate -- don't re-derive it from `model.error`, which is
+     * the same subtraction `displayPhase` exists to retire.
+     */
+    ErrorBar: ComponentType<{
+        model: DisplayErrorBarModel;
+        visible: boolean;
+    }>;
+    /**
+     * The loading scrim. `visible` is `displayPhase === 'loading'`; `immediate`
+     * asks it to skip its anti-flash delay because nothing is painted yet.
+     *
+     * Mounted unconditionally, so it must handle `visible === false` itself — and
+     * that is load-bearing rather than a style choice: the anti-flash delay is
+     * component state, so a chrome that mounted this only while loading would
+     * restart the timer on every activation and never reach it. Keep any
+     * replacement mountable-while-hidden for the same reason.
+     */
+    Loading: ComponentType<{
+        model: DisplayLoadingOverlayModel;
+        visible: boolean;
+        immediate?: boolean;
+    }>;
+    /**
+     * Status for work with no fetch behind it, while the phase is `ready`.
+     * Mounted unconditionally; gates on `visible` itself.
+     *
+     * **The one state that does not own its own box.** The chrome anchors the
+     * bottom-right corner and lays this out there, because that corner is shared
+     * with the display's own control row (`BottomRightIndicators`) and two boxes
+     * claiming it independently is exactly what they used to do — each pinning
+     * itself to `bottom: 2; right: 2` of the same overlay layer, the controls
+     * winning on z-index and the status text vanishing underneath. So render an
+     * **in-flow** chip: no `position`, no `inset`, no corner offsets. Sizing and
+     * colours are yours; placement is not. See `bottomRightCorner.ts`.
+     */
+    BackgroundProgress: ComponentType<{
+        model: DisplayBackgroundProgressModel;
+        visible: boolean;
+    }>;
+}

package/esm/chromeOverlays.js

@@ -0,0 +1 @@
+export {};

package/esm/index.d.ts

@@ -0,0 +1,22 @@
+export { default as DisplayUIProvider, resolveOverlays, } from './DisplayUIProvider.tsx';
+export { DisplayChromeOverlayProvider, useChromeOverlayOverride, } from './chromeOverlayContext.ts';
+export { default as plainChromeOverlays } from './plainChromeOverlays.tsx';
+export type { DisplayBackgroundProgressModel, DisplayChromeOverlays, DisplayErrorBarModel, DisplayLoadingOverlayModel, TooLargeMessageModel, } from './chromeOverlays.ts';
+export { TrackControlProvider, useTrackControlOverride, } from './trackControl/trackControlContext.ts';
+export { default as plainTrackControl } from './trackControl/plainTrackControl.tsx';
+export { useTrackControlMenu } from './trackControl/useTrackControlMenu.tsx';
+export type { TrackControlMenu } from './trackControl/useTrackControlMenu.tsx';
+export type { TrackControlComponent, TrackControlIcon, TrackControlOption, TrackControlProps, } from './trackControl/types.ts';
+export { default as FloatingLegend } from './FloatingLegend.tsx';
+export type { LegendItem, LegendSection } from './FloatingLegend.tsx';
+export { default as Tooltip } from './tooltip/Tooltip.tsx';
+export { useTooltip } from './tooltip/useTooltip.tsx';
+export type { TooltipTrigger } from './tooltip/useTooltip.tsx';
+export type { TooltipPlacement } from '@jbrowse/core/ui/BaseTooltip';
+export { PointerLayer } from './PointerLayer.tsx';
+export { TrackOverlayContext } from './trackOverlay/TrackOverlayContext.ts';
+export { TrackOverlayPortal } from './trackOverlay/TrackOverlayPortal.tsx';
+export { TrackOverlaySlot } from './trackOverlay/TrackOverlaySlot.tsx';
+export { tooLargeBannerText } from './tooLargeBannerText.ts';
+export { isLiveModel } from './isLiveModel.ts';
+export { BOTTOM_RIGHT_CONTROLS_ORDER, BottomRightCornerContext, } from './bottomRightCorner.ts';

package/esm/index.js

@@ -0,0 +1,51 @@
+// The UI a display draws that is not data, and none of it reaches a UI toolkit.
+//
+// This package has no `@mui/*` dependency, which is the guarantee the whole
+// bring-your-own story rests on and the one thing a rendered-element census
+// cannot check. The Material implementations live in
+// `@jbrowse/plugin-linear-genome-view`, which depends on this — never the
+// reverse. See README.md.
+// Both seams at once, defaulting to the plain sets: what an embedder mounts.
+// `resolveOverlays` is the partial-over-plain merge on its own, for code
+// building the context value by hand — it returns one stable object per input,
+// which is what keeps a context value from re-rendering every display.
+export { default as DisplayUIProvider, resolveOverlays, } from './DisplayUIProvider.js';
+// The status states.
+export { DisplayChromeOverlayProvider, useChromeOverlayOverride, } from './chromeOverlayContext.js';
+export { default as plainChromeOverlays } from './plainChromeOverlays.js';
+// The bottom-right controls.
+export { TrackControlProvider, useTrackControlOverride, } from './trackControl/trackControlContext.js';
+export { default as plainTrackControl } from './trackControl/plainTrackControl.js';
+export { useTrackControlMenu } from './trackControl/useTrackControlMenu.js';
+// The one floating legend every display that has colors to explain renders.
+// Here rather than in the LGV plugin because six plugins render it, it reaches
+// no UI toolkit, and it is chrome by the definition this package uses — a thing
+// a display draws that is not its data. `@jbrowse/plugin-linear-genome-view`
+// re-exports it, so its published name is unchanged.
+export { default as FloatingLegend } from './FloatingLegend.js';
+// The hover label every control in here used to delegate to the browser's
+// `title` attribute. The box it draws is `@jbrowse/core`'s `BaseTooltip`, the
+// same one the display tooltips draw, anchored to the control instead of to the
+// cursor — what lives here is the hover, the focus and the dismissal. It stays
+// behind a `lazy()` one module in, which `tooltip/eagerBoundary.test.ts` pins.
+export { default as Tooltip } from './tooltip/Tooltip.js';
+export { useTooltip } from './tooltip/useTooltip.js';
+// What follows the pointer, in a leaf that re-renders alone.
+export { PointerLayer } from './PointerLayer.js';
+// The per-track overlay layer: the node floating chrome escapes into, and the
+// host's half of that portal.
+export { TrackOverlayContext } from './trackOverlay/TrackOverlayContext.js';
+export { TrackOverlayPortal } from './trackOverlay/TrackOverlayPortal.js';
+export { TrackOverlaySlot } from './trackOverlay/TrackOverlaySlot.js';
+// What the byte gate says, so every set that renders the too-large state says
+// the same thing. The measurement behind the gate stays with the mixin that
+// makes it.
+export { tooLargeBannerText } from './tooLargeBannerText.js';
+// The liveness check an overlay's one button needs, for a model that may be an
+// MST node or the plain object the contract invites. Exported because both
+// shipped sets render that button and a bare `isAlive` is wrong in each.
+export { isLiveModel } from './isLiveModel.js';
+// The corner `BackgroundProgress` is laid out in — the half of that state's
+// contract the prop types cannot carry, so it belongs with them rather than
+// with the chrome that happens to mount it.
+export { BOTTOM_RIGHT_CONTROLS_ORDER, BottomRightCornerContext, } from './bottomRightCorner.js';

package/esm/isLiveModel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * #api
+ * Whether an overlay's model can still be called into.
+ *
+ * The terminal states unmount the canvas, so a click landing after the track was
+ * closed would otherwise run an action on a destroyed node — which is why both
+ * overlay sets guard their one button with `isAlive`.
+ *
+ * **`isAlive` alone is wrong here, and it throws rather than answering.** The
+ * four model shapes in `chromeOverlays.ts` are structural on purpose ("A display
+ * satisfies one by having the fields; no mixin has to be composed"), so a host
+ * writing their own display over `DisplayChromeBase` may hand these components a
+ * plain object. `isAlive` runs `assertIsStateTreeNode` and throws on one, inside
+ * an event handler, where React logs it and moves on — leaving the Force load
+ * button looking live and doing nothing, which is the exact state
+ * `DisplayChromeOverlays.TooLarge` documents itself as existing to prevent.
+ *
+ * A plain object is never destroyed, so it is always callable. The liveness
+ * question only exists for an MST node.
+ */
+export declare function isLiveModel(model: unknown): boolean;

package/esm/isLiveModel.js

@@ -0,0 +1,24 @@
+import { isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api
+ * Whether an overlay's model can still be called into.
+ *
+ * The terminal states unmount the canvas, so a click landing after the track was
+ * closed would otherwise run an action on a destroyed node — which is why both
+ * overlay sets guard their one button with `isAlive`.
+ *
+ * **`isAlive` alone is wrong here, and it throws rather than answering.** The
+ * four model shapes in `chromeOverlays.ts` are structural on purpose ("A display
+ * satisfies one by having the fields; no mixin has to be composed"), so a host
+ * writing their own display over `DisplayChromeBase` may hand these components a
+ * plain object. `isAlive` runs `assertIsStateTreeNode` and throws on one, inside
+ * an event handler, where React logs it and moves on — leaving the Force load
+ * button looking live and doing nothing, which is the exact state
+ * `DisplayChromeOverlays.TooLarge` documents itself as existing to prevent.
+ *
+ * A plain object is never destroyed, so it is always callable. The liveness
+ * question only exists for an MST node.
+ */
+export function isLiveModel(model) {
+    return !isStateTreeNode(model) || isAlive(model);
+}

package/esm/plainChromeOverlays.d.ts

@@ -0,0 +1,18 @@
+import type { DisplayChromeOverlays } from './chromeOverlays.ts';
+/**
+ * #api
+ * 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.
+ *
+ * `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 hand. Colours come from `currentColor` and the CSS system
+ * colours, so the host's own cascade drives them in both light and dark.
+ *
+ * The `data-testid` values it renders are a contract four of JBrowse's test
+ * systems key on, so a replacement set that keeps them can be driven by those
+ * suites too.
+ */
+declare const plainChromeOverlays: DisplayChromeOverlays;
+export default plainChromeOverlays;

package/esm/plainChromeOverlays.js

@@ -0,0 +1,189 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// the subpath, not the `@jbrowse/core/ui` barrel: this file is the MUI-free
+// chrome, and gpuFallback.ts is React-free for exactly that reason
+import { GPU_FALLBACK_LABEL, GPU_FALLBACK_TOOLTIP, disableGpuRendering, shouldOfferGpuFallback, } from '@jbrowse/core/ui/gpuFallback';
+import { progressLabel } from '@jbrowse/core/util/progress';
+import { observer } from 'mobx-react';
+import { isLiveModel } from './isLiveModel.js';
+import { tooLargeBannerText } from './tooLargeBannerText.js';
+import Tooltip from './tooltip/Tooltip.js';
+// A dependency-free `DisplayChromeOverlays` for embedders who don't want MUI:
+// no theme provider to mount, no emotion injected into the host page, and
+// nothing that reads as a stray Material widget inside someone else's design
+// system. Pair it with `DisplayChromeBase` (NOT `DisplayChrome`, which binds
+// the MUI set and would defeat the point by keeping MUI in the module graph).
+//
+// Deliberately plain rather than pretty: every rule below is either layout that
+// the chrome's contract requires, or a hairline so the state is legible against
+// an unknown background. Colors come from `currentColor` and `color-mix` so the
+// host's own cascade drives them. Restyle by wrapping these, or write your own
+// set against the same interface.
+//
+// The testids are NOT cosmetic. `loading-overlay`, `loading-overlay-cancel`,
+// `loading-overlay-retry`, `progress-chip`, `reload_button` and
+// `use_canvas2d_button` are a contract across four test systems (jest, browser
+// tests, screenshot harness, jbrowse-img), so a replacement set that wants to
+// run the existing suites has to keep them.
+// The scrim and the too-large/error banners all need to sit over the canvas
+// without eating pointer events; only the inner content is interactive. Matches
+// the MUI set's behavior, where leaving an interactive box mounted over every
+// track silently swallowed clicks.
+const overlayBox = {
+    position: 'absolute',
+    inset: 0,
+    display: 'flex',
+    justifyContent: 'center',
+    alignItems: 'flex-start',
+    pointerEvents: 'none',
+    zIndex: 1,
+};
+// Nearly opaque on purpose. These sit over a canvas whose colours are not known
+// here, and a translucent chip over dense data was measurably hard to read.
+// `Canvas`/`CanvasText` are the CSS system colours, so this tracks the host's
+// light/dark mode without needing a theme object.
+const chip = {
+    pointerEvents: 'auto',
+    margin: 4,
+    padding: '3px 8px',
+    fontSize: '0.8rem',
+    lineHeight: 1.4,
+    color: 'CanvasText',
+    border: '1px solid',
+    borderColor: 'color-mix(in srgb, CanvasText 35%, transparent)',
+    borderRadius: 4,
+    background: 'color-mix(in srgb, Canvas 94%, transparent)',
+};
+const button = {
+    font: 'inherit',
+    color: 'CanvasText',
+    marginLeft: 8,
+    padding: '0 6px',
+    cursor: 'pointer',
+    border: '1px solid',
+    borderColor: 'color-mix(in srgb, CanvasText 45%, transparent)',
+    borderRadius: 3,
+    background: 'transparent',
+};
+// Terminal states replace the whole subtree, so unlike the overlays above they
+// own the display box and are the only thing in it.
+function banner(height) {
+    return {
+        height,
+        boxSizing: 'border-box',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 8,
+        padding: 8,
+        fontSize: '0.8rem',
+        border: '1px solid',
+        borderColor: 'color-mix(in srgb, currentColor 25%, transparent)',
+    };
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// Announcement, split across two elements on purpose.
+//
+// The chip carrying a status is a `role="status"` polite live region, so a
+// screen reader reads the phase once when it changes ("Loading", "Clustering
+// samples"). The percentage is deliberately NOT in that region: a determinate
+// status ticks about ten times a second, and a live region carrying the number
+// talks over everything else on the page until the fetch ends.
+//
+// The bar below is where the number goes. Screen readers do not announce
+// `aria-valuenow` changes on a `progressbar`, so the value is reachable on
+// demand and silent otherwise — which is the behaviour a progress indicator
+// should have. `StatusProgressBar` in core does the same thing and is
+// toolkit-free, but it paints `theme.palette.primary.main`; every rule in this
+// file reads the host's own cascade instead, so the bar is drawn here rather
+// than imported.
+function ProgressBar({ fraction }) {
+    const filled = Math.min(1, Math.max(0, fraction));
+    return (_jsx("div", { role: "progressbar", "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": Math.round(filled * 100), style: {
+            overflow: 'hidden',
+            width: 60,
+            height: 3,
+            marginLeft: 6,
+            borderRadius: 2,
+            background: 'color-mix(in srgb, currentColor 26%, transparent)',
+        }, children: _jsx("div", { style: {
+                width: '100%',
+                height: '100%',
+                background: 'currentColor',
+                // scaled rather than sized, so an update is a compositor transform
+                transformOrigin: 'left center',
+                transform: `scaleX(${filled})`,
+                transition: 'transform 200ms linear',
+            } }) }));
+}
+const PlainRenderError = observer(function PlainRenderError({ error, onRetry, height, }) {
+    return (_jsxs("div", { style: banner(height), role: "alert", children: [_jsx("span", { style: { wordBreak: 'break-word' }, children: errorText(error) }), _jsx("button", { type: "button", style: button, "data-testid": "reload_button", onClick: onRetry, children: "Retry" }), shouldOfferGpuFallback(error) ? (_jsx(Tooltip, { title: GPU_FALLBACK_TOOLTIP, children: _jsx("button", { type: "button", style: button, "data-testid": "use_canvas2d_button", onClick: () => {
+                        disableGpuRendering();
+                        onRetry();
+                    }, children: GPU_FALLBACK_LABEL }) })) : null] }));
+});
+const PlainTooLarge = observer(function PlainTooLarge({ model, }) {
+    return (_jsxs("div", { style: banner(), role: "status", children: [_jsx("span", { style: { wordBreak: 'break-word' }, children: tooLargeBannerText(model.regionTooLargeReason, {
+                    zoomCanRelease: model.zoomCanReleaseGate,
+                }) }), _jsx("button", { type: "button", style: button, onClick: () => {
+                    // the banner unmounts the canvas, so a click landing after the track
+                    // was closed would otherwise call an action on a dead node. Not bare
+                    // `isAlive` — this model may be the plain object the contract invites,
+                    // which that throws on. See isLiveModel.ts.
+                    if (isLiveModel(model)) {
+                        model.forceLoad();
+                    }
+                }, children: "Force load" })] }));
+});
+const PlainErrorBar = observer(function PlainErrorBar({ model, visible, }) {
+    return visible && model.error ? (_jsx("div", { style: overlayBox, role: "alert", children: _jsxs("div", { style: chip, children: [_jsx("span", { style: { wordBreak: 'break-word' }, children: errorText(model.error) }), _jsx("button", { type: "button", style: button, "data-testid": "reload_button", onClick: () => {
+                        model.reload();
+                    }, children: "Retry" })] }) })) : null;
+});
+// No anti-flash delay here, unlike the MUI set: that timing is a product
+// judgment JBrowse made for its own UI, and an embedder pacing their own
+// loading affordances shouldn't inherit it invisibly. Wrap this if you want it.
+const PlainLoading = observer(function PlainLoading({ model, visible, }) {
+    if (!visible) {
+        return null;
+    }
+    const { statusMessage, statusProgress, fetchCanceled } = model;
+    return (_jsx("div", { style: overlayBox, "data-testid": "loading-overlay", children: _jsx("div", { style: { ...chip, display: 'flex', alignItems: 'center' }, role: "status", children: fetchCanceled ? (_jsxs(_Fragment, { children: [_jsx("span", { children: "Loading canceled" }), model.reload ? (_jsx("button", { type: "button", style: button, "data-testid": "loading-overlay-retry", onClick: () => {
+                            model.reload?.();
+                        }, children: "Retry" })) : null] })) : (_jsxs(_Fragment, { children: [_jsx("span", { children: statusProgress === undefined
+                            ? `${statusMessage || 'Loading'}...`
+                            : progressLabel(statusMessage || 'Loading', statusProgress) }), statusProgress === undefined ? null : (_jsx(ProgressBar, { fraction: statusProgress })), model.cancelFetchByUser ? (_jsx("button", { type: "button", style: button, "data-testid": "loading-overlay-cancel", onClick: () => {
+                            model.cancelFetchByUser?.();
+                        }, children: "Cancel" })) : null] })) }) }));
+});
+const PlainBackgroundProgress = observer(function PlainBackgroundProgress({ model, visible, }) {
+    // The only state that renders no positioned box of its own: the chrome
+    // anchors the bottom-right corner and shares it with the display's control
+    // row, so this is laid out there. Claiming `inset: 0` here would collapse
+    // against that box, and pinning to the corner would sit under the row.
+    return visible && model.statusMessage ? (_jsxs("div", { style: { ...chip, display: 'flex', alignItems: 'center' }, role: "status", "data-testid": "progress-chip", children: [_jsx("span", { children: progressLabel(model.statusMessage, model.statusProgress) }), model.statusProgress === undefined ? null : (_jsx(ProgressBar, { fraction: model.statusProgress }))] })) : null;
+});
+/**
+ * #api
+ * 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.
+ *
+ * `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 hand. Colours come from `currentColor` and the CSS system
+ * colours, so the host's own cascade drives them in both light and dark.
+ *
+ * The `data-testid` values it renders are a contract four of JBrowse's test
+ * systems key on, so a replacement set that keeps them can be driven by those
+ * suites too.
+ */
+const plainChromeOverlays = {
+    RenderError: PlainRenderError,
+    TooLarge: PlainTooLarge,
+    ErrorBar: PlainErrorBar,
+    Loading: PlainLoading,
+    BackgroundProgress: PlainBackgroundProgress,
+};
+export default plainChromeOverlays;

package/esm/tooLargeBannerText.d.ts

@@ -0,0 +1,18 @@
+/**
+ * #api
+ * Which axis tripped (empty when the display gates without a reason), then the
+ * way out.
+ *
+ * `zoomCanRelease` decides whether "zoom in" is offered, and it has to be asked
+ * because the advice is not always true. It was, once: the `AUTO_FORCE_LOAD_BP`
+ * floor turned the byte gate off below 20kb, so zooming far enough always
+ * worked. The byte gate no longer stops at any floor, and an index quotes whole
+ * blocks — so for a file whose blocks are large the same bytes come down however
+ * far the user goes, and telling them to keep zooming into a fetch whose cost
+ * cannot fall is the one thing the banner must not do. `zoomCanReleaseGate`
+ * answers it from two consecutive measurements rather than from a threshold; see
+ * `ByteEstimate.zoomIneffective`.
+ */
+export declare function tooLargeBannerText(regionTooLargeReason: string, { zoomCanRelease }?: {
+    zoomCanRelease?: boolean;
+}): string;

package/esm/tooLargeBannerText.js

@@ -0,0 +1,34 @@
+// What the byte gate says, and the only part of that gate that belongs to the
+// UI. The measurement side — byte estimates, the sub-floor budget factor,
+// `resolveByteLimit` — stays in `RegionTooLargeMixin`'s own module, which
+// re-exports this so a display keeps one import.
+//
+// It is here because *both* overlay sets render it: JBrowse's Material
+// `TooLargeMessage` and the toolkit-free `PlainTooLarge`, plus anyone writing a
+// third. Wording that drifts between them is a difference nobody would see in
+// review and the screenshot harness keys off the literal.
+/**
+ * #api
+ * Which axis tripped (empty when the display gates without a reason), then the
+ * way out.
+ *
+ * `zoomCanRelease` decides whether "zoom in" is offered, and it has to be asked
+ * because the advice is not always true. It was, once: the `AUTO_FORCE_LOAD_BP`
+ * floor turned the byte gate off below 20kb, so zooming far enough always
+ * worked. The byte gate no longer stops at any floor, and an index quotes whole
+ * blocks — so for a file whose blocks are large the same bytes come down however
+ * far the user goes, and telling them to keep zooming into a fetch whose cost
+ * cannot fall is the one thing the banner must not do. `zoomCanReleaseGate`
+ * answers it from two consecutive measurements rather than from a threshold; see
+ * `ByteEstimate.zoomIneffective`.
+ */
+export function tooLargeBannerText(regionTooLargeReason, { zoomCanRelease = true } = {}) {
+    return [
+        regionTooLargeReason,
+        zoomCanRelease
+            ? 'Zoom in to see features, or force load this track for the rest of the session (may be slow)'
+            : 'Force load this track for the rest of the session (may be slow)',
+    ]
+        .filter(f => !!f)
+        .join('. ');
+}

package/esm/tooltip/Tooltip.d.ts

@@ -0,0 +1,52 @@
+import type { TooltipPlacement } from '@jbrowse/core/ui/BaseTooltip';
+import type { ReactElement, ReactNode, Ref } from 'react';
+interface TriggerProps {
+    ref?: Ref<HTMLElement>;
+    onPointerEnter?: (event: React.PointerEvent<HTMLElement>) => void;
+    onPointerLeave?: (event: React.PointerEvent<HTMLElement>) => void;
+    onPointerDown?: (event: React.PointerEvent<HTMLElement>) => void;
+    onFocus?: (event: React.FocusEvent<HTMLElement>) => void;
+    onBlur?: (event: React.FocusEvent<HTMLElement>) => void;
+}
+/**
+ * #api
+ * A hover/focus label for a control, drawn rather than delegated to the
+ * browser's `title` attribute — positioned so it clears the display's
+ * `contain: strict` box and the window edge, dismissed by Escape, and drawn
+ * like every other JBrowse tooltip instead of like whatever the host OS
+ * renders.
+ *
+ * `title` is what this chrome used to use, and it was the wrong tool three
+ * ways: it can be neither styled nor positioned, it waits about a second and
+ * then disappears on a timer of its own, and on a control that already carries
+ * an `aria-label` some screen readers announce both strings. This reaches no UI
+ * 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.
+ *
+ * ```tsx
+ * <Tooltip title="Hide legend">
+ *   <button type="button" aria-label="Hide legend" onClick={onDismiss}>
+ *     ×
+ *   </button>
+ * </Tooltip>
+ * ```
+ *
+ * **The child still needs its own accessible name**, because this sets
+ * `aria-describedby` and never `aria-label` — see {@link useTooltip}, which is
+ * this without the cloning, for a host writing its own markup.
+ */
+export default function Tooltip({ title, placement, children, }: {
+    /** What the bubble says. Nothing renders while this is empty. */
+    title: ReactNode;
+    /** Preferred side. `flip()` overrides it near a viewport edge. */
+    placement?: TooltipPlacement;
+    /** Exactly one element, cloned rather than wrapped. */
+    children: ReactElement<TriggerProps>;
+}): import("react").JSX.Element;
+export {};

package/esm/tooltip/Tooltip.js

@@ -0,0 +1,67 @@
+import { Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cloneElement } from 'react';
+import { useTooltip } from './useTooltip.js';
+function compose(theirs, ours) {
+    return (event) => {
+        theirs?.(event);
+        ours(event);
+    };
+}
+/**
+ * #api
+ * A hover/focus label for a control, drawn rather than delegated to the
+ * browser's `title` attribute — positioned so it clears the display's
+ * `contain: strict` box and the window edge, dismissed by Escape, and drawn
+ * like every other JBrowse tooltip instead of like whatever the host OS
+ * renders.
+ *
+ * `title` is what this chrome used to use, and it was the wrong tool three
+ * ways: it can be neither styled nor positioned, it waits about a second and
+ * then disappears on a timer of its own, and on a control that already carries
+ * an `aria-label` some screen readers announce both strings. This reaches no UI
+ * 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.
+ *
+ * ```tsx
+ * <Tooltip title="Hide legend">
+ *   <button type="button" aria-label="Hide legend" onClick={onDismiss}>
+ *     ×
+ *   </button>
+ * </Tooltip>
+ * ```
+ *
+ * **The child still needs its own accessible name**, because this sets
+ * `aria-describedby` and never `aria-label` — see {@link useTooltip}, which is
+ * this without the cloning, for a host writing its own markup.
+ */
+export default function Tooltip({ title, placement, children, }) {
+    const { triggerProps, tooltip } = useTooltip(title, { placement });
+    const props = children.props;
+    // eslint-disable-next-line @eslint-react/no-clone-element -- wrapping instead would move the absolutely-positioned and flex-row controls this exists for
+    const trigger = cloneElement(children, {
+        ...triggerProps,
+        ref: (node) => {
+            ;
+            triggerProps.ref(node);
+            const theirs = props.ref;
+            if (typeof theirs === 'function') {
+                theirs(node);
+            }
+            else if (theirs) {
+                theirs.current = node;
+            }
+        },
+        onPointerEnter: compose(props.onPointerEnter, triggerProps.onPointerEnter),
+        onPointerLeave: compose(props.onPointerLeave, triggerProps.onPointerLeave),
+        onPointerDown: compose(props.onPointerDown, triggerProps.onPointerDown),
+        onFocus: compose(props.onFocus, triggerProps.onFocus),
+        onBlur: compose(props.onBlur, triggerProps.onBlur),
+    });
+    return (_jsxs(_Fragment, { children: [trigger, tooltip] }));
+}

package/esm/tooltip/useTooltip.d.ts

@@ -0,0 +1,50 @@
+import type { TooltipPlacement } from '@jbrowse/core/ui/BaseTooltip';
+import type { ReactNode, Ref } from 'react';
+export interface TooltipTrigger {
+    /** Whether the bubble is up, for a caller that wants to style the trigger. */
+    open: boolean;
+    /**
+     * Spread onto the control the tooltip describes. `aria-describedby`, not
+     * `aria-label`: the tooltip is a visual affordance, and a name pointing at a
+     * node that exists only during a hover leaves the control unnamed the rest of
+     * the time. **The control still needs its own accessible name.**
+     */
+    triggerProps: {
+        ref: Ref<HTMLElement>;
+        'aria-describedby': string | undefined;
+        onPointerEnter: (event: React.PointerEvent<HTMLElement>) => void;
+        onPointerLeave: () => void;
+        onPointerDown: () => void;
+        onFocus: () => void;
+        onBlur: () => void;
+    };
+    /** Render this. It is `null` until the bubble is up, and portals itself. */
+    tooltip: ReactNode;
+}
+/**
+ * #api
+ * A hover/focus label for one control, as props to spread — the headless half
+ * of {@link Tooltip}, for a host writing its own chrome rather than restyling
+ * ours. Same relationship `useTrackControlMenu` has to `plainTrackControl`.
+ *
+ * ```tsx
+ * const { triggerProps, tooltip } = useTooltip('Hide legend')
+ * return (
+ *   <>
+ *     <button {...triggerProps} aria-label="Hide legend" onClick={onDismiss}>
+ *       ×
+ *     </button>
+ *     {tooltip}
+ *   </>
+ * )
+ * ```
+ *
+ * `triggerProps` carries no `onClick`, so a control's own handler does not
+ * collide with it. Any other handler on this list has to compose rather than
+ * replace — spread first, then call `triggerProps.onFocus` from yours.
+ */
+export declare function useTooltip(
+/** What the bubble says. It stays down while this is empty. */
+title: ReactNode, { placement }?: {
+    placement?: TooltipPlacement;
+}): TooltipTrigger;