@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.3

package/esm/ui/MenuTypes.d.ts

@@ -66,7 +66,7 @@ export interface BaseMenuItem {
      */
     endAdornment?: React.ReactNode;
     /**
-     * #menuField the "apply this to all open tracks of this type" pin; set it with a promotable builder
+     * #menuField the "apply this to all open tracks of this type" pin; set it through a row builder's `pin` option
      *
      * The trailing "default for all tracks of this type" pin, as a **description**
      * rather than an element — the renderer builds `PinAdornment` from
@@ -76,8 +76,8 @@ export interface BaseMenuItem {
      * into every host's first paint. It did, until 2026-08-05; see
      * reference/EAGER_BUNDLE.md.
      *
-     * Set it through `promotableToggleItem` / `promotableRadioItems` (or
-     * `promotableRadioItem` for a lone row), not by hand.
+     * Set it through the `pin` option of `checkboxItem` / `toggleItem` /
+     * `radioItem` / `radioItems`, not by hand.
      *
      * A `type: 'custom'` row (`makePromotableSizeMenu`) draws its own pin inside
      * its rendered content and still sets this — the declaration is what lets a
@@ -127,11 +127,20 @@ export interface RadioMenuItem extends BaseMenuItem {
     checked: boolean;
     onClick: MenuItemClickHandler;
 }
-/** #menuItem subMenu | nests another `MenuItem[]`, to any depth */
+/**
+ * #menuItem subMenu | nests another `MenuItem[]`, or a function building one, to any depth
+ *
+ * The function form is called when the submenu opens (or a walker asks for its
+ * rows), not when the parent menu is built — for a submenu whose rows cost a
+ * scan of the display's data to name. Read the field through `resolveSubMenu`
+ * rather than by hand, so the two forms stay one thing to the renderer, the
+ * pin-coverage walk and every test helper that flattens a menu.
+ */
 export interface SubMenuItem extends BaseMenuItem {
     type?: 'subMenu';
-    subMenu: MenuItem[];
+    subMenu: MenuItem[] | (() => MenuItem[]);
 }
+export declare function resolveSubMenu(item: SubMenuItem): MenuItem[];
 /**
  * #menuItem custom | renders arbitrary React content inline, e.g. a slider
  *

package/esm/ui/MenuTypes.js

@@ -1,3 +1,6 @@
+export function resolveSubMenu(item) {
+    return typeof item.subMenu === 'function' ? item.subMenu() : item.subMenu;
+}
 // #endregion
 /**
  * Whether clicking a row leaves the menu up — the rule `CascadingMenu` applies,

package/esm/ui/PaletteContext.d.ts

@@ -40,8 +40,9 @@ export interface ThemeModeSession {
  * hook and the provider in one.
  *
  * How the host knows its own mode is the host's business — an attribute on
- * `<html>`, a `prefers-color-scheme` media query, a design-system context —
- * and deliberately not this hook's.
+ * `<html>`, a design-system context, a toggle in its own state. Pass no mode
+ * and JBrowse follows `prefers-color-scheme` instead, tracking OS changes; a
+ * host whose mode is only ever the OS preference has nothing to write.
  *
  * **Both halves are load-bearing, which is why the pairing is published as a
  * component.** The palette is what *React* draws with; the config `theme` slot
@@ -55,7 +56,7 @@ export interface ThemeModeSession {
  * the previous palette. That is a frame on a canvas that is about to be
  * redrawn anyway; it is not somewhere to add a suspense boundary.
  */
-export declare function useSessionPalette(session: ThemeModeSession, mode: 'light' | 'dark'): JBrowsePalette;
+export declare function useSessionPalette(session: ThemeModeSession, mode?: 'light' | 'dark'): JBrowsePalette;
 /**
  * #api
  * Make JBrowse follow the host's light/dark state — the whole of it, in one
@@ -67,6 +68,12 @@ export declare function useSessionPalette(session: ThemeModeSession, mode: 'ligh
  * </SessionPaletteProvider>
  * ```
  *
+ * `mode` is optional. Left out, JBrowse follows `prefers-color-scheme` and
+ * re-themes when the OS preference changes, through the same session write an
+ * explicit mode takes — so a host whose dark mode *is* the OS preference mounts
+ * this with a session and nothing else. Pass a mode as soon as the host has a
+ * toggle of its own, since the media query cannot see it.
+ *
  * A component rather than a documented pair of calls because the pair has a
  * half that can be left out with nothing to show for it. `PaletteProvider` is
  * the name a host reaches for, and it colors the React side alone; the session
@@ -80,6 +87,6 @@ export declare function useSessionPalette(session: ThemeModeSession, mode: 'ligh
  */
 export declare function SessionPaletteProvider({ session, mode, children, }: {
     session: ThemeModeSession;
-    mode: 'light' | 'dark';
+    mode?: 'light' | 'dark';
     children: ReactNode;
 }): import("react").JSX.Element;

package/esm/ui/PaletteContext.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, use, useEffect, useMemo } from 'react';
+import { createContext, use, useEffect, useMemo, useSyncExternalStore, } from 'react';
 import { defaultStyleTheme } from './styleTheme.js';
 /**
  * How a React component asks for JBrowse's design tokens.
@@ -47,6 +47,27 @@ export function useStyleTheme() {
 export function usePalette() {
     return useStyleTheme().palette;
 }
+function darkSchemeQuery() {
+    return typeof window.matchMedia === 'function'
+        ? window.matchMedia('(prefers-color-scheme: dark)')
+        : undefined;
+}
+function subscribeToColorScheme(onChange) {
+    const media = darkSchemeQuery();
+    media?.addEventListener('change', onChange);
+    return () => {
+        media?.removeEventListener('change', onChange);
+    };
+}
+function readColorScheme() {
+    return darkSchemeQuery()?.matches ? 'dark' : 'light';
+}
+const alwaysLight = () => 'light';
+const subscribeToNothing = () => () => { };
+function useResolvedMode(mode) {
+    const systemMode = useSyncExternalStore(mode === undefined ? subscribeToColorScheme : subscribeToNothing, mode === undefined ? readColorScheme : alwaysLight, alwaysLight);
+    return mode === undefined ? systemMode : mode;
+}
 /**
  * Point a session at light or dark and get back the palette it resolves to,
  * for a host that wants the palette itself — to read a color out of, or to
@@ -55,8 +76,9 @@ export function usePalette() {
  * hook and the provider in one.
  *
  * How the host knows its own mode is the host's business — an attribute on
- * `<html>`, a `prefers-color-scheme` media query, a design-system context —
- * and deliberately not this hook's.
+ * `<html>`, a design-system context, a toggle in its own state. Pass no mode
+ * and JBrowse follows `prefers-color-scheme` instead, tracking OS changes; a
+ * host whose mode is only ever the OS preference has nothing to write.
  *
  * **Both halves are load-bearing, which is why the pairing is published as a
  * component.** The palette is what *React* draws with; the config `theme` slot
@@ -71,9 +93,10 @@ export function usePalette() {
  * redrawn anyway; it is not somewhere to add a suspense boundary.
  */
 export function useSessionPalette(session, mode) {
+    const resolved = useResolvedMode(mode);
     useEffect(() => {
-        session.setThemeMode(mode);
-    }, [session, mode]);
+        session.setThemeMode(resolved);
+    }, [session, resolved]);
     return session.palette;
 }
 /**
@@ -87,6 +110,12 @@ export function useSessionPalette(session, mode) {
  * </SessionPaletteProvider>
  * ```
  *
+ * `mode` is optional. Left out, JBrowse follows `prefers-color-scheme` and
+ * re-themes when the OS preference changes, through the same session write an
+ * explicit mode takes — so a host whose dark mode *is* the OS preference mounts
+ * this with a session and nothing else. Pass a mode as soon as the host has a
+ * toggle of its own, since the media query cannot see it.
+ *
  * A component rather than a documented pair of calls because the pair has a
  * half that can be left out with nothing to show for it. `PaletteProvider` is
  * the name a host reaches for, and it colors the React side alone; the session

package/esm/ui/PinAdornment.js

@@ -18,62 +18,50 @@ const useStyles = makeStyles()(theme => ({
         display: 'inline-flex',
     },
 }));
-// How the pin names what it acts on. Two shapes, decided by the on-value:
+// A toggle pin sits on a checkbox row: the copy names the state the click
+// applies, and the fill mirrors the checkbox. A value pin's on-value IS what
+// the label says — a radio option ("Compact"), a size row whose caller folds
+// the value into the label ("Line width (2px)") — and there the fill means the
+// value is the promoted default, so a click clears it.
 //
-// - **A boolean on-value carries a state**, and the row's label names the
-//   setting rather than a value ("Show legend", "Show soft clipping"). A pin on
-//   an unchecked such row applies the setting *off*, so the value-shaped copy
-//   below stated the opposite of what the click does — and then, once filled,
-//   claimed the setting was on by default when it had just been turned off.
-// - **Everything else IS what the label says**: a radio option ("Compact"), a
-//   size row whose caller folds the value into the label ("Line width (2px)").
-//
-// One `typeof` rather than a flag on the row, because the two forms of
-// `makePin` are exactly this distinction: a symmetric pin over a `maybeBoolean`
-// slot is the only way a pin's value and its label can disagree.
-function pinPredicate(onValue) {
-    return typeof onValue === 'boolean'
-        ? `${onValue ? 'on' : 'off'} by default`
-        : 'the default';
-}
-// The click, which is not the state the pin draws: an outline pin applies the
-// value to the open tracks, a filled one clears the default it stands for.
-function pinCopy(label, onValue, isDefault) {
-    return isDefault
+// The aria-label carries "of this type" wherever the tooltip does: it used to
+// stop at "for all open tracks", stating a wider blast radius than the control
+// has.
+function pinCopy(label, control) {
+    const { kind, active } = control;
+    return kind === 'toggle'
         ? {
-            title: `${label} is ${pinPredicate(onValue)} for all tracks of this type (click to clear)`,
-            ariaLabel: `clear the default for ${label}`,
+            title: `Turn ${label} ${active ? 'off' : 'on'} for all open tracks of this type`,
+            ariaLabel: `turn ${label} ${active ? 'off' : 'on'} for all open tracks of this type`,
         }
-        : typeof onValue === 'boolean'
+        : active
             ? {
-                title: `Turn ${label} ${onValue ? 'on' : 'off'} for all open tracks of this type`,
-                ariaLabel: `turn ${label} ${onValue ? 'on' : 'off'} for all open tracks`,
+                title: `${label} is the default for all tracks of this type (click to clear)`,
+                ariaLabel: `clear the default for ${label} for all tracks of this type`,
             }
             : {
                 title: `Apply ${label} to all open tracks of this type`,
-                ariaLabel: `apply ${label} to all open tracks`,
+                ariaLabel: `apply ${label} to all open tracks of this type`,
             };
 }
-// Trailing pin for a promotable setting, rendered as a menu item's
-// `endAdornment` beside the value check. A ToggleButton (native button a11y + a
-// clear selected tint) with a pin — distinct from the value checkbox.
+// Trailing pin for a promotable setting, drawn beside the value check from the
+// row's `pin` declaration (`menuItemAdornment` builds this; a row never
+// constructs it, which is what keeps MUI out of the eager menu-builder graph). A
+// ToggleButton (native button a11y + a clear selected tint) with a pin —
+// distinct from the value checkbox.
 //
-// **The click and the state are two different things.** One click writes the
-// value into every open track of this display type and raises a snackbar
-// offering to keep it as the display type's default; the filled pin means that
-// default is in place, so a click on a filled pin clears it and touches no
-// track. A default therefore takes two deliberate clicks, which is what it costs
-// to govern every track of the type opened later (ADR-048). Always shown so the
-// capability is discoverable. stopPropagation keeps the click off the row value
-// / menu dismissal. "of this type" because a promoted default is scoped to the
-// display type (e.g. every LinearAlignmentsDisplay), not literally all tracks.
+// One click writes the value into every open track of this display type and
+// raises a snackbar offering to keep it as the display type's default, so a
+// default takes two deliberate clicks (ADR-048). Always shown so the capability
+// is discoverable. stopPropagation keeps the click off the row value / menu
+// dismissal. "of this type" because a promoted default is scoped to the display
+// type (e.g. every LinearAlignmentsDisplay), not literally all tracks.
 export function PinAdornment({ pin, disabled, }) {
     const { classes } = useStyles();
     const { label, control } = pin;
-    const isDefault = control.active;
-    const { title, ariaLabel } = pinCopy(label, control.onValue, isDefault);
-    return (_jsx(Tooltip, { title: title, children: _jsx("span", { className: classes.wrapper, children: _jsx(ToggleButton, { className: classes.button, value: "default", disabled: disabled, selected: isDefault, color: "primary", size: "small", "aria-label": ariaLabel, onChange: e => {
+    const { title, ariaLabel } = pinCopy(label, control);
+    return (_jsx(Tooltip, { title: title, children: _jsx("span", { className: classes.wrapper, children: _jsx(ToggleButton, { className: classes.button, value: "default", disabled: disabled, selected: control.active, color: "primary", size: "small", "aria-label": ariaLabel, onChange: e => {
                     e.stopPropagation();
                     control.toggle();
-                }, children: isDefault ? (_jsx(PushPinIcon, { fontSize: "small" })) : (_jsx(PushPinOutlinedIcon, { fontSize: "small" })) }) }) }));
+                }, children: control.active ? (_jsx(PushPinIcon, { fontSize: "small" })) : (_jsx(PushPinOutlinedIcon, { fontSize: "small" })) }) }) }));
 }

package/esm/ui/ScrollChrome.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The chrome a display that scrolls its content virtually mounts over its
+ * viewport: `ScrollEdgeShadow` saying content is hidden past an edge, and
+ * `VerticalScrollbar` to reach it. Both read the same three numbers, so a
+ * display hands them over once here. Renders nothing when the content fits.
+ */
+export default function ScrollChrome({ scrollTop, setScrollTop, viewportHeight, contentHeight, controlsId, top, }: {
+    scrollTop: number;
+    setScrollTop: (n: number) => void;
+    viewportHeight: number;
+    contentHeight: number;
+    /** `id` of the scrolled viewport element, for `aria-controls`. */
+    controlsId: string;
+    /** Viewport offset from the top, for a display with a sticky band above it. */
+    top?: number;
+}): import("react").JSX.Element;

package/esm/ui/ScrollChrome.js

@@ -0,0 +1,12 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import ScrollEdgeShadow from './ScrollEdgeShadow.js';
+import VerticalScrollbar from './VerticalScrollbar.js';
+/**
+ * The chrome a display that scrolls its content virtually mounts over its
+ * viewport: `ScrollEdgeShadow` saying content is hidden past an edge, and
+ * `VerticalScrollbar` to reach it. Both read the same three numbers, so a
+ * display hands them over once here. Renders nothing when the content fits.
+ */
+export default function ScrollChrome({ scrollTop, setScrollTop, viewportHeight, contentHeight, controlsId, top = 0, }) {
+    return (_jsxs(_Fragment, { children: [_jsx(ScrollEdgeShadow, { scrollTop: scrollTop, viewportHeight: viewportHeight, contentHeight: contentHeight, top: top }), _jsx(VerticalScrollbar, { scrollTop: scrollTop, setScrollTop: setScrollTop, viewportHeight: viewportHeight, contentHeight: contentHeight, controlsId: controlsId, top: top })] }));
+}

package/esm/ui/ScrollZoomToggle.d.ts

@@ -27,9 +27,10 @@ export interface ScrollZoomToggleModel {
  * of this button pulse with it, which is the preference being session-wide made
  * visible.
  *
- * `iconOnly` is for a header where this sits inside a run of icon buttons (the
- * comparative views), where a single labelled button reads as a mistake rather
- * than as emphasis. The tooltip carries the same words either way.
+ * `iconOnly` is for a header with no room for the words, or one where this sits
+ * inside a run of icon buttons with nothing else labelled — a single labelled
+ * button there reads as a mistake rather than as emphasis. The tooltip carries
+ * the same words either way.
  */
 declare const ScrollZoomToggle: ({ model, iconOnly, }: {
     model: ScrollZoomToggleModel;

package/esm/ui/ScrollZoomToggle.js

@@ -67,9 +67,10 @@ const useStyles = makeStyles()(theme => {
  * of this button pulse with it, which is the preference being session-wide made
  * visible.
  *
- * `iconOnly` is for a header where this sits inside a run of icon buttons (the
- * comparative views), where a single labelled button reads as a mistake rather
- * than as emphasis. The tooltip carries the same words either way.
+ * `iconOnly` is for a header with no room for the words, or one where this sits
+ * inside a run of icon buttons with nothing else labelled — a single labelled
+ * button there reads as a mistake rather than as emphasis. The tooltip carries
+ * the same words either way.
  */
 const ScrollZoomToggle = observer(function ScrollZoomToggle({ model, iconOnly, }) {
     const { classes } = useStyles();

package/esm/ui/SizeSliderRow.js

@@ -33,7 +33,7 @@ export const SizeSliderRow = observer(function SizeSliderRow({ title, getValue,
     const slug = title.toLowerCase().replaceAll(' ', '-');
     return (_jsxs("div", { className: classes.root, children: [_jsxs("div", { className: classes.header, children: [_jsxs(Typography, { variant: "caption", color: "textSecondary", className: classes.label, children: [title, ": ", format(value)] }), _jsx(ResetToDefaultButton, { disabled: isDefault, onClick: () => {
                             onReset();
-                        } }), pin ? (_jsx(PinAdornment, { pin: { control: pin, label: `${title} (${format(value)})` } })) : null] }), _jsx(SingleSlider, { value: toSlider(value), min: toSlider(min), max: toSlider(max), step: sliderStep ?? step, size: "small", "aria-label": title.toLowerCase(), "data-testid": `${slug}-slider`, valueLabelDisplay: "auto", valueLabelFormat: (v) => format(fromSlider(v)), sx: { py: 0.5, display: 'block' }, onChange: v => {
+                        } }), pin ? (_jsx(PinAdornment, { pin: { control: pin, label: `${title} (${format(modelValue)})` } })) : null] }), _jsx(SingleSlider, { value: toSlider(value), min: toSlider(min), max: toSlider(max), step: sliderStep ?? step, size: "small", "aria-label": title.toLowerCase(), "data-testid": `${slug}-slider`, valueLabelDisplay: "auto", valueLabelFormat: (v) => format(fromSlider(v)), sx: { py: 0.5, display: 'block' }, onChange: v => {
                     const n = fromSlider(v);
                     if (commitOnRelease) {
                         setDragValue(n);

package/esm/ui/index.d.ts

@@ -48,6 +48,7 @@ export { default as StatusProgressBar } from './StatusProgressBar.tsx';
 export { default as Menu } from './Menu.tsx';
 export { default as PrerenderedCanvas } from './PrerenderedCanvas.tsx';
 export { default as ResizeHandle } from './ResizeHandle.tsx';
+export { default as ScrollChrome } from './ScrollChrome.tsx';
 export { default as ScrollEdgeShadow } from './ScrollEdgeShadow.tsx';
 export { default as VerticalScrollbar } from './VerticalScrollbar.tsx';
 export { default as SubmitDialog } from './SubmitDialog.tsx';
@@ -70,7 +71,7 @@ export type { SlotExtensionPointName, SlotProps, WrapperProps, } from './wrapCom
 export { matchesTrackSelector } from './extensionSelectors.ts';
 export type { TrackSelector } from './extensionSelectors.ts';
 export type { BaseMenuItem, CheckboxMenuItem, ClickableMenuItem, CustomMenuItem, MenuDivider, MenuItem, MenuItemClickHandler, MenuItemsGetter, MenuSubHeader, NormalMenuItem, RadioMenuItem, SubMenuItem, } from './MenuTypes.ts';
-export { staysOpenOnClick } from './MenuTypes.ts';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.ts';
 export { LAUNCH_LABEL, pushIntoSubMenu, pushLaunchViewMenuItem, } from './launchViewMenu.ts';
 export { launchTargetsMenuItem } from './launchTargetsMenuItem.ts';
 export { default as Crosshairs } from './Crosshairs.tsx';
@@ -78,8 +79,7 @@ export { hoverBoxStyle } from './hoverBoxStyle.ts';
 export { useMouseState, useMouseTracking } from './useMouseTracking.ts';
 export type { MouseState, MouseTracker } from './useMouseTracking.ts';
 export { PinAdornment } from './PinAdornment.tsx';
-export { promotableRadioItem, promotableRadioItems, promotableToggleItem, } from './promotableMenuItems.ts';
-export { displayTypesWithPromotableSlots, promotableSlotsWithoutPin, } from './promotablePinCoverage.ts';
+export { displayTypesWithPromotableSlots, misKindedPins, promotableSlotsWithoutPin, } from './promotablePinCoverage.ts';
 export declare const VIEW_HEADER_HEIGHT = 28;
 export { GRADIENT_LEGEND_HEIGHT, GRADIENT_LEGEND_SVG_AREA_WIDTH, GRADIENT_LEGEND_WIDTH, default as SvgGradientLegend, } from './SvgGradientLegend.tsx';
 export type { GradientLabel, GradientStop } from './SvgGradientLegend.tsx';

package/esm/ui/index.js

@@ -44,6 +44,7 @@ export { default as StatusProgressBar } from './StatusProgressBar.js';
 export { default as Menu } from './Menu.js';
 export { default as PrerenderedCanvas } from './PrerenderedCanvas.js';
 export { default as ResizeHandle } from './ResizeHandle.js';
+export { default as ScrollChrome } from './ScrollChrome.js';
 export { default as ScrollEdgeShadow } from './ScrollEdgeShadow.js';
 export { default as VerticalScrollbar } from './VerticalScrollbar.js';
 export { default as SubmitDialog } from './SubmitDialog.js';
@@ -65,15 +66,14 @@ export { default as PluggableElements } from './PluggableElements.js';
 export { addExtensionElement } from './addExtensionElement.js';
 export { wrapComponent } from './wrapComponent.js';
 export { matchesTrackSelector } from './extensionSelectors.js';
-export { staysOpenOnClick } from './MenuTypes.js';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.js';
 export { LAUNCH_LABEL, pushIntoSubMenu, pushLaunchViewMenuItem, } from './launchViewMenu.js';
 export { launchTargetsMenuItem } from './launchTargetsMenuItem.js';
 export { default as Crosshairs } from './Crosshairs.js';
 export { hoverBoxStyle } from './hoverBoxStyle.js';
 export { useMouseState, useMouseTracking } from './useMouseTracking.js';
 export { PinAdornment } from './PinAdornment.js';
-export { promotableRadioItem, promotableRadioItems, promotableToggleItem, } from './promotableMenuItems.js';
-// Not on the React-free `menuItems.ts` entry beside the two builders above: this
+// Not on the React-free `menuItems.ts` entry beside the row builders: this
 // reads a config's slot table, so it pulls `configuration/promotableSlots.ts`
 // in, and that entry exists precisely to stay out of every plugin's eager graph.
 //
@@ -81,7 +81,7 @@ export { promotableRadioItem, promotableRadioItems, promotableToggleItem, } from
 // caller has is "which promotable slots does this menu miss", and answering the
 // half of it that lists what a menu *does* offer needs the schema's slot table
 // to mean anything.
-export { displayTypesWithPromotableSlots, promotableSlotsWithoutPin, } from './promotablePinCoverage.js';
+export { displayTypesWithPromotableSlots, misKindedPins, promotableSlotsWithoutPin, } from './promotablePinCoverage.js';
 export const VIEW_HEADER_HEIGHT = 28;
 export { GRADIENT_LEGEND_HEIGHT, GRADIENT_LEGEND_SVG_AREA_WIDTH, GRADIENT_LEGEND_WIDTH, default as SvgGradientLegend, } from './SvgGradientLegend.js';
 export { LEGEND_ROW_HEIGHT, LEGEND_SWATCH, default as SvgColorLegend, } from './SvgColorLegend.js';

package/esm/ui/launchViewMenu.js

@@ -10,7 +10,13 @@ export const LAUNCH_LABEL = 'Launch';
 export function pushIntoSubMenu(items, label, item) {
     const existing = items.find((i) => i.type === 'subMenu' && i.label === label);
     if (existing) {
-        existing.subMenu.push(item);
+        const { subMenu } = existing;
+        if (typeof subMenu === 'function') {
+            existing.subMenu = () => [...subMenu(), item];
+        }
+        else {
+            subMenu.push(item);
+        }
     }
     else {
         items.push({ label, type: 'subMenu', subMenu: [item] });

package/esm/ui/legendMenuItem.d.ts

@@ -1,5 +1,5 @@
-import type { Pin } from '../configuration/promotablePin.ts';
 import type { MenuItem } from './MenuTypes.ts';
+import type { CheckboxRowOptions } from './toggleMenuItems.ts';
 /**
  * The "Show legend" checkbox, which seven displays build by hand — Hi-C, LD,
  * alignments, LGVSynteny, multi-wiggle, multi-row features, both multi-sample
@@ -14,25 +14,19 @@ import type { MenuItem } from './MenuTypes.ts';
  * values legitimately differ (a Hi-C color scale is off by default, a variant
  * genotype key on), and their descriptions describe genuinely different legends.
  * What they now share is being *promotable* — pass `opts.pin` and the row gains
- * the pin that makes the current state this display type's session-wide
- * default. Every display whose legend is backed by a config slot passes one,
- * and gets it from `LegendMixin`'s `showLegendDisplayTypeDefault` rather than
- * calling `makePin` itself: the slot is the per-display half, the accessors
- * over it are not.
+ * the pin that toggles the legend on every open track of this display type,
+ * offering the new state as the display-type default in its snackbar. Every
+ * display whose legend is backed by a config slot passes one, and gets it from
+ * `LegendMixin`'s `showLegendDisplayTypeDefault` rather than calling
+ * `makeTogglePin` itself: the slot is the per-display half, the accessors over
+ * it are not.
  *
  * `pin` is optional because two callers have no slot to promote: the Manhattan
  * plot's LD legend and `LinearBasicDisplay`'s color key are a volatile and a
  * per-legend `dismissed` flag respectively, neither of which is config at all.
- * They get the plain row, which is what `checkboxItem` builds either way — the
- * promotable form is that same row plus the pin, per `promotableToggleItem`.
  *
- * Deliberately not used by `synteny-core`'s "Show color legend", which sits
- * inside a "Color by..." submenu where the bare word would not say which legend.
+ * `synteny-core`'s color-by legend has no toggle at all: it comes up with the
+ * modes that have a key and is dismissed from its own close button.
  */
 /** #menuBuilder showLegendCheckboxItem | the shared "Show legend" checkbox */
-export declare function showLegendCheckboxItem(checked: boolean, onToggle: () => void, opts?: {
-    helpText?: string;
-    disabled?: boolean;
-    disabledHelpText?: string;
-    pin?: Pin;
-}): MenuItem;
+export declare function showLegendCheckboxItem(checked: boolean, onToggle: () => void, opts?: CheckboxRowOptions): MenuItem;

package/esm/ui/legendMenuItem.js

@@ -1,4 +1,3 @@
-import { promotableToggleItem } from './promotableMenuItems.js';
 import { checkboxItem } from './toggleMenuItems.js';
 /**
  * The "Show legend" checkbox, which seven displays build by hand — Hi-C, LD,
@@ -14,31 +13,21 @@ import { checkboxItem } from './toggleMenuItems.js';
  * values legitimately differ (a Hi-C color scale is off by default, a variant
  * genotype key on), and their descriptions describe genuinely different legends.
  * What they now share is being *promotable* — pass `opts.pin` and the row gains
- * the pin that makes the current state this display type's session-wide
- * default. Every display whose legend is backed by a config slot passes one,
- * and gets it from `LegendMixin`'s `showLegendDisplayTypeDefault` rather than
- * calling `makePin` itself: the slot is the per-display half, the accessors
- * over it are not.
+ * the pin that toggles the legend on every open track of this display type,
+ * offering the new state as the display-type default in its snackbar. Every
+ * display whose legend is backed by a config slot passes one, and gets it from
+ * `LegendMixin`'s `showLegendDisplayTypeDefault` rather than calling
+ * `makeTogglePin` itself: the slot is the per-display half, the accessors over
+ * it are not.
  *
  * `pin` is optional because two callers have no slot to promote: the Manhattan
  * plot's LD legend and `LinearBasicDisplay`'s color key are a volatile and a
  * per-legend `dismissed` flag respectively, neither of which is config at all.
- * They get the plain row, which is what `checkboxItem` builds either way — the
- * promotable form is that same row plus the pin, per `promotableToggleItem`.
  *
- * Deliberately not used by `synteny-core`'s "Show color legend", which sits
- * inside a "Color by..." submenu where the bare word would not say which legend.
+ * `synteny-core`'s color-by legend has no toggle at all: it comes up with the
+ * modes that have a key and is dismissed from its own close button.
  */
 /** #menuBuilder showLegendCheckboxItem | the shared "Show legend" checkbox */
 export function showLegendCheckboxItem(checked, onToggle, opts) {
-    const { pin, ...rest } = opts ?? {};
-    return pin
-        ? promotableToggleItem({
-            label: 'Show legend',
-            checked,
-            onToggle,
-            pin,
-            ...rest,
-        })
-        : checkboxItem('Show legend', checked, onToggle, rest);
+    return checkboxItem('Show legend', checked, onToggle, opts);
 }

package/esm/ui/makeSizeMenu.js

@@ -51,7 +51,7 @@ export function makeSizeSubMenu(opts) {
 // The same row over a **promotable** slot, which derives both halves the plain
 // form takes by hand — the reset button's enablement (`isSlotCustomized`) and
 // the "default for all tracks of this type" pin — from the one slot name. A
-// slider has no fixed on-value, so the pin promotes whatever the track is
+// slider has no fixed on-value, so the pin carries whatever the track is
 // currently showing.
 //
 // Naming the slot once is the point: the call sites used to spell it twice, in

package/esm/ui/menuItemAdornment.d.ts

@@ -6,9 +6,8 @@ import type { MenuItem } from './MenuTypes.ts';
  * the builder already made — the escape hatch, for content nothing else can
  * describe. `pin` is a *description* of the "default for all tracks of
  * this type" pin, and turning it into `PinAdornment` here is the whole
- * point: the builders that set it (`promotableToggleItem`,
- * `promotableRadioItem`) are called from state models and menu modules, which
- * are eager, so a module that constructs the element instead puts MUI's
+ * point: the row builders that set it (`toggleMenuItems.ts`) are called from
+ * state models and menu modules, which are eager, so a module that constructs the element instead puts MUI's
  * `ToggleButton`, `Tooltip` and two icons into every host's first paint.
  *
  * Live in one place rather than at each of the four render sites, because the

package/esm/ui/menuItemAdornment.js

@@ -7,9 +7,8 @@ import { PinAdornment } from './PinAdornment.js';
  * the builder already made — the escape hatch, for content nothing else can
  * describe. `pin` is a *description* of the "default for all tracks of
  * this type" pin, and turning it into `PinAdornment` here is the whole
- * point: the builders that set it (`promotableToggleItem`,
- * `promotableRadioItem`) are called from state models and menu modules, which
- * are eager, so a module that constructs the element instead puts MUI's
+ * point: the row builders that set it (`toggleMenuItems.ts`) are called from
+ * state models and menu modules, which are eager, so a module that constructs the element instead puts MUI's
  * `ToggleButton`, `Tooltip` and two icons into every host's first paint.
  *
  * Live in one place rather than at each of the four render sites, because the

package/esm/ui/menuItems.d.ts

@@ -22,7 +22,6 @@ export { checkboxItem, radioItem, radioItems, toggleItem, withSubHeader, } from
 export { withHint } from './menuLabels.ts';
 export { makeRadioSubMenu } from './radioSubMenu.ts';
 export { showLegendCheckboxItem } from './legendMenuItem.ts';
-export { promotableRadioItem, promotableRadioItems, promotableToggleItem, } from './promotableMenuItems.ts';
-export type { RadioOption, SettingRowOptions } from './toggleMenuItems.ts';
-export { staysOpenOnClick } from './MenuTypes.ts';
+export type { CheckboxRowOptions, RadioOption, RadioRowOptions, SettingRowOptions, } from './toggleMenuItems.ts';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.ts';
 export type { BaseMenuItem, CheckboxMenuItem, ClickableMenuItem, CustomMenuItem, MenuDivider, MenuItem, MenuItemClickHandler, MenuItemPin, MenuItemsGetter, MenuSubHeader, NormalMenuItem, RadioMenuItem, SubMenuItem, } from './MenuTypes.ts';

package/esm/ui/menuItems.js

@@ -22,5 +22,4 @@ export { checkboxItem, radioItem, radioItems, toggleItem, withSubHeader, } from
 export { withHint } from './menuLabels.js';
 export { makeRadioSubMenu } from './radioSubMenu.js';
 export { showLegendCheckboxItem } from './legendMenuItem.js';
-export { promotableRadioItem, promotableRadioItems, promotableToggleItem, } from './promotableMenuItems.js';
-export { staysOpenOnClick } from './MenuTypes.js';
+export { resolveSubMenu, staysOpenOnClick } from './MenuTypes.js';

package/esm/ui/palette.d.ts

@@ -117,33 +117,33 @@ export interface SemanticColors {
 export declare const colorFwdStrand = "#EC8B8B";
 /** #color alignments-strand | Reverse strand | Read maps to the reverse strand */
 export declare const colorRevStrand = "#8F8FD8";
-/** #color alignments-pair-orientation | LR (→ ←, normal proper pair) | Concordant */
+/** #color alignments-pair-orientation | LR (→ ←) | Normal proper pair */
 export declare const colorPairLR = "#d3d3d3";
 export declare const colorPairLRDark = "#8a8a8a";
-/** #color alignments-pair-orientation | RL (← →, mates point away from each other) | Abnormal orientation */
+/** #color alignments-pair-orientation | RL (← →) | Mates point away from each other */
 export declare const colorPairRL = "#0099bb";
-/** #color alignments-pair-orientation | LL (→ →, both mates forward strand) | Abnormal orientation */
+/** #color alignments-pair-orientation | LL (→ →) | Both mates on the forward strand */
 export declare const colorPairLL = "#4d9a4d";
-/** #color alignments-pair-orientation | RR (← ←, both mates reverse strand) | Abnormal orientation */
+/** #color alignments-pair-orientation | RR (← ←) | Both mates on the reverse strand */
 export declare const colorPairRR = "#5555bb";
 export declare const colorNeutralRead = "#c8c8c8";
 /**
- * #color alignments-pair-orientation | Inter-chromosomal | Mate maps to a different chromosome; colored distinctly rather than by orientation
- * #color alignments-insert-size | Mate on a different chromosome | Suggests an inter-chromosomal event
+ * #color alignments-pair-orientation | Inter-chromosomal | Mate on another chromosome
+ * #color alignments-insert-size | Inter-chromosomal | Mate on another chromosome
  */
 export declare const colorInterchrom = "#af4d19";
-/** #color alignments-insert-size | Insert larger than expected | Suggests a deletion spanning the pair */
+/** #color alignments-insert-size | Insert larger than expected | Deletion between the mates */
 export declare const colorLongInsert = "#ff0000";
-/** #color alignments-insert-size | Insert smaller than expected | Suggests an insertion between the pair */
+/** #color alignments-insert-size | Insert smaller than expected | Insertion between the mates */
 export declare const colorShortInsert = "#f582c0";
 /**
- * #color alignments-pair-orientation | Mate unmapped | The other end of the pair aligned nowhere, so orientation and insert size say nothing
- * #color alignments-insert-size | Mate unmapped | The other end of the pair aligned nowhere, so insert size says nothing
+ * #color alignments-pair-orientation | Mate unmapped | Mate aligned nowhere
+ * #color alignments-insert-size | Mate unmapped | Mate aligned nowhere
  */
 export declare const colorUnmappedMate = "#000000";
 export declare const colorUnmappedMateDark = "#4a4a4a";
 export declare const colorLongreadInv = "#7755bb";
-/** #color alignments-pair-orientation | Split paired-end read (inverted) | A paired read's supplementary segment maps opposite-strand to its primary, so the junction is inverted — an inversion or an inverted duplication */
+/** #color alignments-pair-orientation | Split read (inverted) | Supplementary segment on the opposite strand to its primary */
 export declare const colorSplitReadInversion = "#9b30b0";
 export declare const colorSupplementary = "#f0b878";
 export declare const tagColorPalette: string[];