@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/ui/AppReadyMarker.d.ts

@@ -0,0 +1,45 @@
+import type { AbstractSessionModel } from '../util/types/index.ts';
+/**
+ * One element that says whether the whole app has finished, and what is open.
+ *
+ * `[data-app-phase="ready"]` is the entire readiness contract for anything
+ * driving JBrowse from outside — a screenshot tool, a test, an agent. Wait for
+ * that selector and you are done; there is no chain to assemble and no
+ * per-display census to take.
+ *
+ * Why it exists when `data-view-phase` and `data-display-phase` already do:
+ * those are per-element and NEGATIVE. Asking them "is everything finished"
+ * means asserting that no element carries the loading value, which is equally
+ * true of an app that has not started — and the gap is real, measured at about
+ * a second on a two-track session. A positive attribute cannot be satisfied
+ * early, because something has to render it.
+ *
+ * The census attributes beside it — `data-app-views`, `data-app-assemblies`,
+ * `data-app-tracks` (the latter two JSON arrays) — publish WHAT is open the
+ * same way the phase publishes whether it is done, so an outside reader asking
+ * "is the track I requested actually open" reads one element instead of
+ * walking `window.JBrowseSession` with its own copy of the view nesting. The
+ * walk itself is `openViews`/`openTracks` over each view's declared
+ * `ownViews`/`ownTracks`, so this component knows nothing about which property
+ * a container view keeps its children on either.
+ *
+ * Its own component, and `hidden`, for two reasons: an observer here subscribes
+ * to every view's phase without re-rendering the app shell around it, and a
+ * marker that is never drawn cannot be mistaken for UI or shift a layout. It is
+ * still found by `querySelector`, which is what reads it.
+ *
+ * **What it is silent about**: a display in a TERMINAL state. `error` and
+ * `canceled` are finished states, so this reads `ready` over a display whose
+ * fetch failed or that the user stopped — correctly, since nothing is still
+ * working, and a user's cancel is durable until Retry. A capture wants more than
+ * that: it wants a picture, and neither banner is one. The capture census after
+ * this is what draws that line: it names every `data-display-drawn="false"`,
+ * which the two comparative canvases publish from their stricter `settled` gate
+ * (see `comparativeReadiness` in `@jbrowse/synteny-core`, which holds both
+ * answers and says why an error separates them), and every
+ * `data-display-phase="canceled"`.
+ */
+declare const AppReadyMarker: ({ session, }: {
+    session: AbstractSessionModel;
+}) => import("react").JSX.Element;
+export default AppReadyMarker;

package/esm/ui/AppReadyMarker.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { observer } from 'mobx-react';
+import { openTracks, openViews } from '../util/openViews.js';
+function trackLoading(track) {
+    return track.displays.some(d => d.displayPhase === 'loading');
+}
+/**
+ * A view whose init failed (its assembly was never found) stays uninitialized
+ * for good and paints its error, so like a display's terminal phase it is
+ * finished, not pending: without this the whole app read `loading` for as long
+ * as that view was open, and every settle answered false with no reason.
+ *
+ * `pendingLaunch` is the third term and the one that was missing. `initialized`
+ * goes true mid-launch — LGV's flips the moment displayedRegions land, while
+ * the same apply pass still has the spec's tracks to attach — and `showLoading`
+ * goes false at the same moment, deliberately, so the reader sees the
+ * navigated view rather than a spinner while its tracks arrive. That left a
+ * window, exactly as wide as attaching the tracks, in which the marker said
+ * `ready` over a session missing everything it had been asked for.
+ * `whenViewSettled` states the same rule for the callers that await a single
+ * view, and says why in more detail. Not shared as one predicate: that one
+ * requires `initialized`, while absent here means not loading, and an adapter
+ * between the two null rules would read as agreement it does not have.
+ *
+ * `showImportForm` excuses the `initialized` term, and only that one. The
+ * comparative views spell `initialized` as "every row exists and is ready" —
+ * LinearSyntenyView's wants `views.length > 0`, dotplot's wants regions on both
+ * axes — so a view clicked into existence through `Add -> Linear synteny view`
+ * reads uninitialized for as long as its form is up, which is until a person
+ * fills it in. The app sat at `loading` behind every import-form figure. The
+ * other two terms keep their meaning: `showLoading` is the spinner the form
+ * yields to, and `showImportForm` is already false while a launch is pending.
+ */
+function viewLoading(view) {
+    const flags = view;
+    return (flags.error === undefined &&
+        (flags.showLoading === true ||
+            flags.pendingLaunch !== undefined ||
+            (flags.initialized === false && flags.showImportForm !== true)));
+}
+/**
+ * One element that says whether the whole app has finished, and what is open.
+ *
+ * `[data-app-phase="ready"]` is the entire readiness contract for anything
+ * driving JBrowse from outside — a screenshot tool, a test, an agent. Wait for
+ * that selector and you are done; there is no chain to assemble and no
+ * per-display census to take.
+ *
+ * Why it exists when `data-view-phase` and `data-display-phase` already do:
+ * those are per-element and NEGATIVE. Asking them "is everything finished"
+ * means asserting that no element carries the loading value, which is equally
+ * true of an app that has not started — and the gap is real, measured at about
+ * a second on a two-track session. A positive attribute cannot be satisfied
+ * early, because something has to render it.
+ *
+ * The census attributes beside it — `data-app-views`, `data-app-assemblies`,
+ * `data-app-tracks` (the latter two JSON arrays) — publish WHAT is open the
+ * same way the phase publishes whether it is done, so an outside reader asking
+ * "is the track I requested actually open" reads one element instead of
+ * walking `window.JBrowseSession` with its own copy of the view nesting. The
+ * walk itself is `openViews`/`openTracks` over each view's declared
+ * `ownViews`/`ownTracks`, so this component knows nothing about which property
+ * a container view keeps its children on either.
+ *
+ * Its own component, and `hidden`, for two reasons: an observer here subscribes
+ * to every view's phase without re-rendering the app shell around it, and a
+ * marker that is never drawn cannot be mistaken for UI or shift a layout. It is
+ * still found by `querySelector`, which is what reads it.
+ *
+ * **What it is silent about**: a display in a TERMINAL state. `error` and
+ * `canceled` are finished states, so this reads `ready` over a display whose
+ * fetch failed or that the user stopped — correctly, since nothing is still
+ * working, and a user's cancel is durable until Retry. A capture wants more than
+ * that: it wants a picture, and neither banner is one. The capture census after
+ * this is what draws that line: it names every `data-display-drawn="false"`,
+ * which the two comparative canvases publish from their stricter `settled` gate
+ * (see `comparativeReadiness` in `@jbrowse/synteny-core`, which holds both
+ * answers and says why an error separates them), and every
+ * `data-display-phase="canceled"`.
+ */
+const AppReadyMarker = observer(function AppReadyMarker({ session, }) {
+    const views = openViews(session);
+    const tracks = openTracks(session);
+    const loading = views.some(viewLoading) || tracks.some(trackLoading);
+    return (_jsx("span", { hidden: true, "data-testid": "app-ready-marker", "data-app-phase": loading ? 'loading' : 'ready', "data-app-views": session.views.length, "data-app-assemblies": JSON.stringify([
+            ...new Set(views.flatMap(v => v.assemblyNames ?? [])),
+        ]), "data-app-tracks": JSON.stringify(tracks.map(t => t.configuration.trackId ?? '(unnamed)')) }));
+});
+export default AppReadyMarker;

package/esm/ui/AssemblySelector.d.ts

@@ -1,13 +1,10 @@
-import type { AbstractSessionModel } from '../util/index.ts';
-import type { InputProps as IIP, TextFieldProps as TFP } from '@mui/material';
-declare const AssemblySelector: ({ session, onChange, label, selected, InputProps, TextFieldProps, localStorageKey, helperText, }: {
-    session: AbstractSessionModel;
+import type { AssemblyHost } from '../util/index.ts';
+declare const AssemblySelector: ({ session, onChange, label, selected, fullWidth, helperText, }: {
+    session: AssemblyHost;
     label?: string;
     helperText?: string;
     onChange: (arg: string) => void;
     selected?: string;
-    localStorageKey?: string;
-    InputProps?: IIP;
-    TextFieldProps?: TFP;
-}) => import("react/jsx-runtime").JSX.Element;
+    fullWidth?: boolean;
+}) => import("react").JSX.Element;
 export default AssemblySelector;

package/esm/ui/AssemblySelector.js

@@ -1,39 +1,21 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect } from 'react';
 import { MenuItem, TextField } from '@mui/material';
 import { observer } from 'mobx-react';
-import { useLocalStorage } from "../util/index.js";
-import { makeStyles } from "../util/tss-react/index.js";
+import { makeStyles } from '../util/tss-react/index.js';
 const useStyles = makeStyles()({
     importFormEntry: {
         minWidth: 180,
     },
 });
-const AssemblySelector = observer(function AssemblySelector({ session, onChange, label = 'Assembly', selected, InputProps, TextFieldProps, localStorageKey, helperText = 'Select assembly to view', }) {
+const AssemblySelector = observer(function AssemblySelector({ session, onChange, label = 'Assembly', selected, fullWidth, helperText = 'Select assembly to view', }) {
     const { classes } = useStyles();
     const { assemblyNames, assemblyManager } = session;
-    const config = new URLSearchParams(window.location.search).get('config');
-    const [lastSelected, setLastSelected] = useLocalStorage(`lastAssembly-${[
-        window.location.host + window.location.pathname,
-        config,
-        localStorageKey,
-    ].join('-')}`, selected, typeof jest === 'undefined' && Boolean(localStorageKey));
-    const selection = assemblyNames.includes(lastSelected || '')
-        ? lastSelected
-        : selected;
-    useEffect(() => {
-        if (selection && selection !== selected) {
-            onChange(selection);
-        }
-    }, [selection, onChange, selected]);
+    // ignore a stale/removed selection so MUI doesn't warn about an out-of-range
+    // select value
+    const value = selected && assemblyNames.includes(selected) ? selected : '';
     const error = assemblyNames.length ? '' : 'No configured assemblies';
-    return (_jsx(TextField, { select: true, "data-testid": "assembly-selector-textfield", label: label, variant: "outlined", helperText: error || helperText, value: selection || '', onChange: event => {
-            setLastSelected(event.target.value);
-        }, error: !!error, disabled: !!error, className: classes.importFormEntry, ...TextFieldProps, slotProps: {
-            input: InputProps,
-            htmlInput: {
-                'data-testid': 'assembly-selector',
-            },
-        }, children: assemblyNames.map(name => (_jsx(MenuItem, { value: name, children: assemblyManager.get(name)?.displayName || name }, name))) }));
+    return (_jsx(TextField, { select: true, label: label, variant: "outlined", helperText: error || helperText, value: value, fullWidth: fullWidth, onChange: event => {
+            onChange(event.target.value);
+        }, error: !!error, disabled: !!error, className: classes.importFormEntry, children: assemblyNames.map(name => (_jsx(MenuItem, { value: name, children: assemblyManager.get(name)?.displayName || name }, name))) }));
 });
 export default AssemblySelector;

package/esm/ui/BaseExportSvgDialog.d.ts

@@ -0,0 +1,16 @@
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface BaseExportSvgOptions {
+    rasterizeLayers: boolean;
+    format: 'svg' | 'png';
+    filename: string;
+    themeName: string;
+    fontFamily: string;
+}
+declare const _default: ({ model, handleClose, exportSvg, children, checkboxes, }: {
+    model: IAnyStateTreeNode;
+    handleClose: () => void;
+    exportSvg: (opts: BaseExportSvgOptions) => Promise<unknown>;
+    children?: React.ReactNode;
+    checkboxes?: React.ReactNode;
+}) => import("react").JSX.Element;
+export default _default;

package/esm/ui/BaseExportSvgDialog.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { CircularProgress, MenuItem, TextField, ToggleButton, ToggleButtonGroup, Typography, } from '@mui/material';
+import { observer } from 'mobx-react';
+import { getSession } from '../util/index.js';
+import ErrorBanner from './ErrorBanner.js';
+import LabeledCheckbox from './LabeledCheckbox.js';
+import SubmitDialog from './SubmitDialog.js';
+import { useExportSvgPreference } from './useExportSvgPreference.js';
+// Generic CSS families only, so exported text resolves in any SVG renderer
+// (browser, Inkscape, Illustrator) without embedding a named font like Roboto.
+// The 'default' sentinel is the selected default; it maps to no font-family so
+// the renderer decides (see the exportSvg call below).
+const DEFAULT_FONT = 'default';
+const fontFamilyOptions = [
+    { value: DEFAULT_FONT, label: 'Default' },
+    { value: 'sans-serif', label: 'Sans-serif' },
+    { value: 'serif', label: 'Serif' },
+    { value: 'monospace', label: 'Monospace' },
+    { value: 'system-ui, sans-serif', label: 'System UI' },
+];
+export default observer(function BaseExportSvgDialog({ model, handleClose, exportSvg, children, checkboxes, }) {
+    const session = getSession(model);
+    const offscreenCanvas = typeof OffscreenCanvas !== 'undefined';
+    // persisted like every other option here, but still gated on the capability:
+    // the checkbox isn't rendered without OffscreenCanvas, so a stored `true` must
+    // not survive into a browser that can't rasterize
+    const [rasterizePreference, setRasterizePreference] = useExportSvgPreference('rasterize', true);
+    const rasterizeLayers = offscreenCanvas && rasterizePreference;
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState();
+    const [format, setFormat] = useExportSvgPreference('format', 'svg');
+    const [filename, setFilename] = useExportSvgPreference('file', 'jbrowse.svg');
+    const [themePreference, setThemeName] = useExportSvgPreference('theme', session.themeName || 'default');
+    // A stored name outlives the theme it names: an admin drops an `extraThemes`
+    // entry, or another JBrowse on this origin writes `svg-theme`, which has no
+    // instance scope. Unguarded it draws a blank Select and makes
+    // `getActiveThemeOptions` answer undefined, so the export comes out stock.
+    // `session.themeName` guards the name it stores the same way.
+    const allThemes = session.allThemes?.();
+    const themeName = allThemes?.[themePreference]
+        ? themePreference
+        : session.themeName || 'default';
+    const [fontFamily, setFontFamily] = useExportSvgPreference('fontfamily', DEFAULT_FONT);
+    return (_jsxs(SubmitDialog, { open: true, title: "Export image", submitDisabled: loading, onCancel: handleClose, onSubmit: async () => {
+            setLoading(true);
+            setError(undefined);
+            try {
+                await exportSvg({
+                    rasterizeLayers,
+                    format,
+                    filename,
+                    themeName,
+                    fontFamily: fontFamily === DEFAULT_FONT ? '' : fontFamily,
+                });
+                handleClose();
+            }
+            catch (e) {
+                console.error(e);
+                setError(e);
+            }
+            finally {
+                setLoading(false);
+            }
+        }, children: [error ? (_jsx(ErrorBanner, { error: error })) : loading ? (_jsxs("div", { children: [_jsx(CircularProgress, { size: 20, style: { marginRight: 20 } }), _jsxs(Typography, { sx: { display: 'inline' }, children: ["Creating ", format.toUpperCase()] })] })) : null, _jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 12 }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: 8 }, children: [_jsx(TextField, { label: "Filename", value: filename, onChange: event => {
+                                    setFilename(event.target.value);
+                                } }), _jsxs(ToggleButtonGroup, { value: format, exclusive: true, onChange: (_event, value) => {
+                                    if (value) {
+                                        setFormat(value);
+                                        if (filename.endsWith('.svg') && value === 'png') {
+                                            setFilename(filename.replace(/\.svg$/, '.png'));
+                                        }
+                                        else if (filename.endsWith('.png') && value === 'svg') {
+                                            setFilename(filename.replace(/\.png$/, '.svg'));
+                                        }
+                                    }
+                                }, size: "small", children: [_jsx(ToggleButton, { value: "svg", children: "SVG" }), _jsx(ToggleButton, { value: "png", children: "PNG" })] })] }), children, allThemes ? (_jsx(TextField, { select: true, label: "Theme", variant: "outlined", style: { minWidth: 200 }, value: themeName, onChange: event => {
+                            setThemeName(event.target.value);
+                        }, children: Object.entries(allThemes).map(([key, val]) => (_jsx(MenuItem, { value: key, children: val.name || '(Unknown name)' }, key))) })) : null, _jsx(TextField, { select: true, label: "Font", variant: "outlined", style: { minWidth: 200 }, value: fontFamily, onChange: event => {
+                            setFontFamily(event.target.value);
+                        }, children: fontFamilyOptions.map(({ value, label }) => (_jsx(MenuItem, { value: value, children: label }, value))) }), _jsxs("div", { style: { display: 'flex', flexDirection: 'column' }, children: [checkboxes, offscreenCanvas ? (_jsx(LabeledCheckbox, { checked: rasterizeLayers, onChange: val => {
+                                    setRasterizePreference(val);
+                                }, label: "Rasterize canvas based tracks? File may be much larger if this is turned off" })) : (_jsx(Typography, { children: "Note: rasterizing layers not yet supported in this browser, so SVG size may be large" }))] })] })] }));
+});

package/esm/ui/BaseTooltip.d.ts

@@ -1,8 +1,19 @@
-export default function BaseTooltip({ clientPoint: clientPointCoords, children, placement, }: {
-    placement?: 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
+export type TooltipPlacement = 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
+export default function BaseTooltip({ clientPoint: clientPointCoords, anchor, id, children, placement, }: {
+    placement?: TooltipPlacement;
+    /** Follow the pointer. The cursor-anchored mode, and the older of the two. */
     clientPoint?: {
         x: number;
         y: number;
     };
+    /**
+     * Hang off an element instead — what a control's hover label wants, where
+     * following the cursor across a button reads as a stray box. Mutually
+     * exclusive with `clientPoint`; `@jbrowse/display-ui`'s `useTooltip` is what
+     * drives this arm.
+     */
+    anchor?: HTMLElement;
+    /** For a trigger pointing at this with `aria-describedby`. */
+    id?: string;
     children: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").ReactPortal | null;

package/esm/ui/BaseTooltip.js

@@ -1,42 +1,159 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { offset, useClientPoint, useFloating, useInteractions, } from '@floating-ui/react';
-import { Portal, alpha, useTheme } from '@mui/material';
-import { makeStyles } from "../util/tss-react/index.js";
-function round(value) {
-    return Math.round(value * 1e5) / 1e5;
+import { useEffect, useState } from 'react';
+import { autoUpdate, flip, offset, shift, useClientPoint, useFloating, useInteractions, } from '@floating-ui/react';
+import { createPortal } from 'react-dom';
+import { useStyleTheme } from './PaletteContext.js';
+import { alpha, grey } from './palette.js';
+import { TOOLTIP_Z_INDEX } from './zIndexes.js';
+// The hover tooltip every display shares, in both of its anchorings: following
+// the pointer over a display's data (`clientPoint`, what the ten display
+// tooltips use through `HoverTooltip`), or hanging off a control that was
+// hovered (`anchor`, what `@jbrowse/display-ui`'s `Tooltip` drives). One
+// component rather than two, because the second one only ever differed in which
+// reference it positioned against — everything below this line was the part
+// worth having once.
+//
+// Its look comes from the palette and plain inline styles rather than from a
+// `makeStyles` reading the Material UI theme, and that is deliberate: an
+// embedder who installs `plainChromeOverlays` + `plainTrackControl` gets stock
+// displays that render no Material UI, and a tooltip carrying the MUI *default*
+// theme's grey and Roboto (which is what it did, since such a host mounts no
+// ThemeProvider) put a Material widget back on their screen. It was invisible
+// to `jbrowse-build-your-own`'s smoke census too, which counts `Mui*`
+// classnames and never sees an emotion class.
+//
+// The chip is dark in both palette modes, the way a tooltip conventionally is.
+// It is the one thing on screen that deliberately does not match the page.
+//
+// `fontFamily: inherit` puts it in whatever font it is portaled into: Roboto in
+// JBrowse's own products, whose `CssBaseline` sets the body font, and the
+// host's font in an embed. The size is stated rather than inherited, because
+// body text is a good deal larger than a tooltip should be.
+const tooltipBaseStyle = {
+    pointerEvents: 'none',
+    borderRadius: 4,
+    fontFamily: 'inherit',
+    fontSize: 12,
+    padding: '4px 8px',
+    lineHeight: 1.4,
+    maxWidth: 300,
+    wordWrap: 'break-word',
+};
+// The gap between the reference and the tooltip, and the ONLY place it is
+// decided. `offset()` applies it along the resolved placement axis, so it stays
+// a gap when `flip()` puts the tooltip to the LEFT of the cursor near the right
+// edge of the viewport.
+//
+// Callers pass the pointer's true client point. Eight of them used to add 5, 10
+// or 15 to `x` themselves on top of this, so the same affordance sat 20, 25 or
+// 30px from the cursor depending on which track you hovered — nobody chose
+// that, and a nudge baked into the coordinate moves the reference point rather
+// than the tooltip, so on a flipped placement it pushed the tooltip *toward*
+// the cursor instead of away. Don't reintroduce one; change this number.
+const CURSOR_GAP_PX = 15;
+// Where the pointer last was, app-wide.
+//
+// A hover tooltip mounts BECAUSE the pointer landed on something, so the event
+// that could position it has already been delivered — and floating-ui's own
+// follow mode (`useClientPoint` with no x/y) registers its window listener on
+// mount, so it learns nothing until the NEXT move. An unpositioned tooltip is
+// `visibility: hidden` (see below), which means landing on a narrow feature and
+// stopping showed no tooltip at all, indefinitely. It is why the callers that
+// have a pointer in hand pass `clientPoint`; the ones that do not are hovering
+// an ELEMENT (an SVG arc, a breakpoint connector), whose `onMouseOver` says
+// only that it was entered.
+//
+// One passive listener storing two numbers, installed at import rather than per
+// tooltip: the value a tooltip needs is the one from before it existed, so
+// there is nothing for a listener installed with it to have recorded.
+let lastPointerPoint;
+if (typeof window !== 'undefined') {
+    window.addEventListener('pointermove', event => {
+        lastPointerPoint = { x: event.clientX, y: event.clientY };
+    }, { passive: true, capture: true });
 }
-const useStyles = makeStyles()(theme => ({
-    tooltip: {
-        position: 'absolute',
-        pointerEvents: 'none',
-        backgroundColor: alpha(theme.palette.grey[700], 0.9),
-        borderRadius: theme.shape.borderRadius,
-        color: theme.palette.common.white,
-        fontFamily: theme.typography.fontFamily,
-        padding: '4px 8px',
-        fontSize: theme.typography.fontSize,
-        lineHeight: `${round(14 / 10)}em`,
-        maxWidth: 300,
-        wordWrap: 'break-word',
-    },
-}));
-export default function BaseTooltip({ clientPoint: clientPointCoords, children, placement = 'right', }) {
-    const theme = useTheme();
-    const popperTheme = theme.components?.MuiPopper;
-    const { classes } = useStyles();
+// An element is its own size, so the gap is measured from its edge rather than
+// from a point the pointer happens to be at. 15px off a button reads as a
+// tooltip belonging to nothing in particular.
+const ANCHOR_GAP_PX = 6;
+export default function BaseTooltip({ clientPoint: clientPointCoords, anchor, id, children, placement = anchor ? 'top' : 'right', }) {
+    // The style theme is read for two things and neither is a Material import:
+    // the colors below, and the portal container a shadow-DOM embed configures
+    // through `MuiPopper.defaultProps.container` — the same slot every other
+    // portaled thing in JBrowse honours, lifted onto the style theme by
+    // `resolveStyleTheme` so reading it here costs no UI toolkit.
+    const { palette, portalContainer } = useStyleTheme();
     const { refs, floatingStyles, context } = useFloating({
         placement,
         strategy: 'fixed',
-        middleware: [offset(5)],
+        elements: { reference: anchor },
+        // flip/shift keep the tooltip on-screen when the reference is near a
+        // viewport edge instead of letting it clip off the right/bottom — and a
+        // control with a hover label is usually in a corner, so this arm needs it
+        // at least as much as the cursor one
+        middleware: [
+            offset(anchor ? ANCHOR_GAP_PX : CURSOR_GAP_PX),
+            flip(),
+            shift({ padding: 8 }),
+        ],
+        // An anchored tooltip is measured against an element that scrolls with the
+        // track under it, so its position is followed. A cursor-anchored one is
+        // remeasured by every pointer move anyway.
+        whileElementsMounted: anchor ? autoUpdate : undefined,
+    });
+    // Follow the pointer here, rather than handing floating-ui its own follow
+    // mode, so the tooltip opens AT a point instead of at nothing — see
+    // `lastPointerPoint`. A caller that named a point, or an element, owns the
+    // position outright and this stays out of the way.
+    const [tracked, setTracked] = useState(lastPointerPoint);
+    const following = !anchor && clientPointCoords === undefined;
+    useEffect(() => {
+        if (!following) {
+            return undefined;
+        }
+        setTracked(lastPointerPoint);
+        const onMove = (event) => {
+            setTracked({ x: event.clientX, y: event.clientY });
+        };
+        window.addEventListener('pointermove', onMove, {
+            passive: true,
+            capture: true,
+        });
+        return () => {
+            window.removeEventListener('pointermove', onMove, true);
+        };
+    }, [following]);
+    // `enabled` rather than a conditional hook: with an element reference in
+    // play, letting this also write one would leave the two arms fighting over
+    // the same slot.
+    const clientPoint = useClientPoint(context, {
+        ...(clientPointCoords ?? tracked),
+        enabled: !anchor,
     });
-    const clientPoint = useClientPoint(context, clientPointCoords);
     const { getFloatingProps } = useInteractions([clientPoint]);
-    return (_jsx(Portal, { container: popperTheme?.defaultProps?.container, children: _jsx("div", { className: classes.tooltip, ref: refs.setFloating, style: {
-                ...floatingStyles,
-                zIndex: 100000,
-                visibility: floatingStyles.transform === 'translate(0px, 0px)'
-                    ? 'hidden'
-                    : undefined,
-                pointerEvents: 'none',
-            }, ...getFloatingProps(), children: children }) }));
+    // `document.body` is the default, which is what MUI's `Portal` did. Resolved
+    // at render rather than in an effect: a tooltip only ever mounts in response
+    // to a pointer, so there is no first paint to be wrong about and no
+    // hydration pass to mismatch — but the `document` guard stays, because this
+    // module is reachable from a server render even when this component is not.
+    const target = (typeof portalContainer === 'function'
+        ? portalContainer()
+        : portalContainer) ??
+        (typeof document === 'undefined' ? undefined : document.body);
+    if (!target) {
+        return null;
+    }
+    return createPortal(_jsx("div", { id: id, ref: refs.setFloating, role: "tooltip", style: {
+            ...tooltipBaseStyle,
+            backgroundColor: alpha(grey[700], 0.9),
+            color: palette.common.white,
+            // after the base style, so the strategy's `position: fixed` wins
+            ...floatingStyles,
+            zIndex: TOOLTIP_Z_INDEX,
+            // workaround for tooltips flashing at top left corner of screen
+            // when first appearing
+            visibility: floatingStyles.transform === 'translate(0px, 0px)'
+                ? 'hidden'
+                : undefined,
+        }, ...getFloatingProps(), children: children }), target);
 }

package/esm/ui/CascadingMenu.d.ts

@@ -1,30 +1,21 @@
-import type { MenuItemsGetter } from './MenuTypes.ts';
+import type { MenuItemClickHandler, MenuItemsGetter } from './MenuTypes.ts';
+import type { PopoverOrigin } from '@mui/material';
 export type { MenuItemsGetter } from './MenuTypes.ts';
-export default function CascadingMenu({ onMenuItemClick, closeAfterItemClick, menuItems, open, onClose, anchorEl, anchorOrigin, transformOrigin, anchorReference, anchorPosition, slotProps, marginThreshold, style, }: {
-    onMenuItemClick: (event: unknown, callback: () => void) => void;
+interface CascadingMenuProps {
+    onMenuItemClick: (callback: MenuItemClickHandler) => void;
     closeAfterItemClick?: boolean;
     menuItems: MenuItemsGetter;
     open: boolean;
     onClose: () => void;
     anchorEl?: Element | null;
-    anchorOrigin?: {
-        vertical: 'top' | 'center' | 'bottom';
-        horizontal: 'left' | 'center' | 'right';
-    };
-    transformOrigin?: {
-        vertical: 'top' | 'center' | 'bottom';
-        horizontal: 'left' | 'center' | 'right';
-    };
+    anchorOrigin?: PopoverOrigin;
+    transformOrigin?: PopoverOrigin;
     anchorReference?: 'anchorEl' | 'anchorPosition' | 'none';
     anchorPosition?: {
         top: number;
         left: number;
     };
-    slotProps?: {
-        transition?: {
-            onExit?: () => void;
-        };
-    };
-    marginThreshold?: number | null;
     style?: React.CSSProperties;
-}): import("react/jsx-runtime").JSX.Element;
+}
+declare const CascadingMenu: ({ onMenuItemClick, closeAfterItemClick, menuItems, open, onClose, anchorEl, anchorOrigin, transformOrigin, anchorReference, anchorPosition, style, }: CascadingMenuProps) => import("react").JSX.Element;
+export default CascadingMenu;