@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/ui/MenuTypes.d.ts

@@ -1,38 +1,158 @@
+import type { Pin } from '../configuration/promotablePin.ts';
+/** #menuItem divider | a horizontal rule; not clickable */
 export interface MenuDivider {
     priority?: number;
     type: 'divider';
 }
+/** #menuItem subHeader | a text label for a section of a menu; not clickable */
 export interface MenuSubHeader {
     type: 'subHeader';
     priority?: number;
     label: string;
 }
+export type MenuItemClickHandler = (...args: any[]) => void;
 export interface BaseMenuItem {
+    /** #menuField stable identifier, for tests and for finding a row again */
     id?: string;
+    /** #menuField the row's text */
     label: React.ReactNode;
+    /** #menuField sort weight within the menu; higher sorts earlier */
     priority?: number;
+    /**
+     * #menuField secondary text under the label; prefer `withHint` in the label
+     *
+     * Renders as a second line under the label, which makes the row two lines
+     * tall. Nothing in this repo uses it any more: a menu whose rows are each two
+     * lines is harder to scan than the labels it buried, so a short clarifier
+     * goes in the label (`withHint` where it is conditional) and real prose goes
+     * in `helpText`. Kept because it renders and plugins may pass one.
+     */
     subLabel?: string;
+    /** #menuField any [MUI icon](https://mui.com/material-ui/material-icons/) component */
     icon?: React.ElementType;
+    /** #menuField renders the row unclickable */
     disabled?: boolean;
+    /** #menuField tooltip shown from a help icon at the trailing edge */
     helpText?: string;
+    /** #menuField tooltip shown when the item is disabled, in place of helpText */
+    disabledHelpText?: string;
+    /**
+     * #menuField override the dismiss-on-click rule; see `staysOpenOnClick`
+     *
+     * Override whether the menu stays open after this row is clicked. Leave it
+     * unset and the row TYPE decides: a `checkbox`/`radio` is a setting, so the
+     * menu stays put (users flip several in one visit, and the menu content is an
+     * observer, so its checked marks update live), while every other row is an
+     * action and dismisses.
+     *
+     * Set `false` on a checkbox/radio whose click is really terminal — it opens a
+     * dialog ("Custom...", "Solid color...") or swaps the display out from under
+     * the menu. Set `true` on a non-checkbox row that should survive its click.
+     */
+    keepMenuOpen?: boolean;
+    /**
+     * #menuField arbitrary trailing content; prefer `pin`
+     *
+     * Extra content rendered at the trailing (right) edge of the row, after the
+     * checkbox/radio decoration and help icon — e.g. a secondary toggle. The
+     * content must `stopPropagation` on its own click so it doesn't fire the row's
+     * onClick or dismiss the menu.
+     *
+     * An **element**, so a module that sets it drags React and whatever it renders
+     * into its own graph. That is fine for the one-off it exists for (synteny's
+     * color swatch) and wrong for the common case, which is why the pin below is
+     * a description instead. Prefer `pin`; reach for this only when the
+     * content is genuinely arbitrary.
+     */
+    endAdornment?: React.ReactNode;
+    /**
+     * #menuField the "apply this to all open tracks of this type" pin; set it with a promotable builder
+     *
+     * The trailing "default for all tracks of this type" pin, as a **description**
+     * rather than an element — the renderer builds `PinAdornment` from
+     * it. Same rule as a `TrackControlProps` icon name (reference/DISPLAYCHROME.md):
+     * menu-item builders are called from state models and menu modules, which are
+     * eager, so an element here puts MUI's `ToggleButton`, `Tooltip` and two icons
+     * 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.
+     *
+     * A `type: 'custom'` row (`makePromotableSizeMenu`) draws its own pin inside
+     * its rendered content and still sets this — the declaration is what lets a
+     * built menu be asked which promotable slots it offers a pin for at all. Such
+     * a row is excluded from the trailing-column reservation; see
+     * `hasMenuItemAdornment`.
+     */
+    pin?: MenuItemPin;
 }
+/**
+ * A row's pin declaration: the {@link Pin} `makePin` built, plus the one thing
+ * the row knows and the pin doesn't — what to call the setting.
+ *
+ * **`control` holds the pin by reference; don't flatten this into
+ * `interface MenuItemPin extends Pin`.** That was tried, to save the hop every
+ * reader spells (`item.pin.control.active`), and it turns the declaration into a
+ * *copy* of the control — so a `Pin` whose `toggle` resolves anything through
+ * `this` silently mutates the copy and the real control never changes. Nothing in
+ * `Pin` promises copy-safety: `makePin` happens to close over what it needs, but
+ * the interface is a plain object a plugin can build by hand, and the failure is
+ * a pin that draws correctly and does nothing. Two hops in `pinnedSlots` and
+ * `menuItemAdornment` is the whole cost of not having that.
+ */
+export interface MenuItemPin {
+    control: Pin;
+    /**
+     * Names the setting in the pin's tooltip and aria-label. Carried here rather
+     * than read off the row's `label`, which is a `ReactNode` and may not be a
+     * string; a pin that can't name what it promotes reads as a bug.
+     */
+    label: string;
+}
+/** #menuItem normal | an action row; the default when `type` is omitted */
 export interface NormalMenuItem extends BaseMenuItem {
     type?: 'normal';
-    onClick: (...args: any[]) => void;
+    onClick: MenuItemClickHandler;
 }
+/** #menuItem checkbox | a setting row with a checkbox; leaves the menu open */
 export interface CheckboxMenuItem extends BaseMenuItem {
     type: 'checkbox';
     checked: boolean;
-    onClick: (...args: any[]) => void;
+    onClick: MenuItemClickHandler;
 }
+/** #menuItem radio | a setting row with a radio button; leaves the menu open */
 export interface RadioMenuItem extends BaseMenuItem {
     type: 'radio';
     checked: boolean;
-    onClick: (...args: any[]) => void;
+    onClick: MenuItemClickHandler;
 }
+/** #menuItem subMenu | nests another `MenuItem[]`, to any depth */
 export interface SubMenuItem extends BaseMenuItem {
     type?: 'subMenu';
     subMenu: MenuItem[];
 }
-export type MenuItem = MenuDivider | MenuSubHeader | NormalMenuItem | CheckboxMenuItem | RadioMenuItem | SubMenuItem;
+/**
+ * #menuItem custom | renders arbitrary React content inline, e.g. a slider
+ *
+ * The menu is not dismissed when interacting with it, so a control can be
+ * dragged live; `onClose` is passed for content that wants to close the menu
+ * explicitly. `label` is used only as a React key/testid.
+ */
+export interface CustomMenuItem extends BaseMenuItem {
+    type: 'custom';
+    render: (onClose: () => void) => React.ReactNode;
+}
+export type ClickableMenuItem = NormalMenuItem | CheckboxMenuItem | RadioMenuItem;
+export type MenuItem = MenuDivider | MenuSubHeader | NormalMenuItem | CheckboxMenuItem | RadioMenuItem | SubMenuItem | CustomMenuItem;
+/**
+ * Whether clicking a row leaves the menu up — the rule `CascadingMenu` applies,
+ * exported so a display's menu-shape test asserts the behavior a user gets
+ * rather than re-deriving it from the flag (each test that spelled out
+ * `keepMenuOpen === true` had to be revisited when the default moved here).
+ *
+ * Defaulted by row TYPE: a checkbox/radio is a setting and stays put, every
+ * other row is an action and dismisses. `keepMenuOpen` overrides either way.
+ */
+export declare function staysOpenOnClick(item: ClickableMenuItem): boolean;
 export type MenuItemsGetter = MenuItem[] | (() => MenuItem[]);

package/esm/ui/MenuTypes.js

@@ -1 +1,13 @@
-export {};
+// #endregion
+/**
+ * Whether clicking a row leaves the menu up — the rule `CascadingMenu` applies,
+ * exported so a display's menu-shape test asserts the behavior a user gets
+ * rather than re-deriving it from the flag (each test that spelled out
+ * `keepMenuOpen === true` had to be revisited when the default moved here).
+ *
+ * Defaulted by row TYPE: a checkbox/radio is a setting and stays put, every
+ * other row is an action and dismisses. `keepMenuOpen` overrides either way.
+ */
+export function staysOpenOnClick(item) {
+    return (item.keepMenuOpen ?? (item.type === 'checkbox' || item.type === 'radio'));
+}

package/esm/ui/MonospaceTextField.d.ts

@@ -0,0 +1,9 @@
+import type { TextFieldProps } from '@mui/material';
+export default function MonospaceTextField({ value, onChange, error, label, children, style, className, readOnly, variant, ...rest }: {
+    value: string;
+    onChange?: (value: string) => void;
+    error?: unknown;
+    label?: React.ReactNode;
+    children?: React.ReactNode;
+    readOnly?: boolean;
+} & Omit<TextFieldProps, 'value' | 'onChange' | 'error' | 'slotProps'>): import("react").JSX.Element;

package/esm/ui/MonospaceTextField.js

@@ -0,0 +1,37 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { InputLabel, TextField, alpha } from '@mui/material';
+import { makeStyles } from '../util/tss-react/index.js';
+const monospaceFontFamily = 'Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace';
+const useStyles = makeStyles()(theme => ({
+    error: {
+        color: theme.palette.error.main,
+        fontSize: '0.8em',
+    },
+    container: {
+        width: '100%',
+        overflowX: 'auto',
+    },
+    field: {
+        fontFamily: monospaceFontFamily,
+    },
+    errorField: {
+        background: alpha(theme.palette.error.main, 0.15),
+    },
+}));
+// Monospace multiline TextField for code/jexl/JSON/sequence content. Turns red
+// on a parse error, renders an optional error banner above and an InputLabel,
+// and applies the shared monospace font stack to the input slot. `children`
+// render below the field (e.g. a description or help button).
+export default function MonospaceTextField({ value, onChange, error, label, children, style, className, readOnly, variant = 'outlined', ...rest }) {
+    const { classes, cx } = useStyles();
+    return (_jsxs(_Fragment, { children: [error ? _jsx("p", { className: classes.error, children: `${error}` }) : null, _jsxs("div", { className: classes.container, children: [label ? _jsx(InputLabel, { shrink: true, children: label }) : null, _jsx(TextField, { ...rest, variant: variant, multiline: true, value: value, onChange: event => {
+                            onChange?.(event.target.value);
+                        }, className: cx(className, error ? classes.errorField : undefined), style: style, slotProps: {
+                            input: {
+                                readOnly,
+                                classes: {
+                                    input: classes.field,
+                                },
+                            },
+                        } }), children] })] }));
+}

package/esm/ui/NumberTextField.d.ts

@@ -0,0 +1,31 @@
+import type { TextFieldProps } from '@mui/material';
+interface OwnProps {
+    /** Initial numeric value; undefined renders as empty input. */
+    defaultValue?: number;
+    /**
+     * Fires on every keystroke with the parsed number, or undefined when
+     * the input is empty or invalid (NaN / out of bounds). The parent
+     * decides whether to gate submission on undefined.
+     */
+    onValueChange: (value: number | undefined) => void;
+    /** Optional inclusive lower bound. */
+    min?: number;
+    /** Optional inclusive upper bound. */
+    max?: number;
+    /** Shown under the input when the value is non-empty and invalid. */
+    errorText?: string;
+}
+type Props = Omit<TextFieldProps, 'value' | 'onChange' | 'type' | 'error'> & OwnProps & {
+    helperText?: TextFieldProps['helperText'];
+};
+/**
+ * Uncontrolled-style numeric TextField. Owns the input *text* internally;
+ * emits the parsed *number* (or undefined) to the parent on every change.
+ *
+ * Use over `<TextField type="number" />` — the browser number input has
+ * known UX problems (scroll-to-change, locale issues, browser-specific
+ * spinners). This component keeps a plain text input and validates with
+ * `Number.isFinite` + optional min/max.
+ */
+export default function NumberTextField(props: Props): import("react").JSX.Element;
+export {};

package/esm/ui/NumberTextField.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
+import { TextField } from '@mui/material';
+/**
+ * Uncontrolled-style numeric TextField. Owns the input *text* internally;
+ * emits the parsed *number* (or undefined) to the parent on every change.
+ *
+ * Use over `<TextField type="number" />` — the browser number input has
+ * known UX problems (scroll-to-change, locale issues, browser-specific
+ * spinners). This component keeps a plain text input and validates with
+ * `Number.isFinite` + optional min/max.
+ */
+export default function NumberTextField(props) {
+    const { defaultValue, onValueChange, min, max, errorText = 'Must be a valid number', helperText, ...rest } = props;
+    const [text, setText] = useState(defaultValue === undefined ? '' : `${defaultValue}`);
+    const parsed = parseInBounds(text, min, max);
+    const showError = text !== '' && parsed === undefined;
+    return (_jsx(TextField, { ...rest, value: text, error: showError, helperText: showError ? errorText : helperText, autoComplete: "off", onChange: event => {
+            const next = event.target.value;
+            setText(next);
+            onValueChange(parseInBounds(next, min, max));
+        } }));
+}
+function parseInBounds(text, min, max) {
+    if (text === '') {
+        return undefined;
+    }
+    const n = Number(text);
+    const ok = Number.isFinite(n) &&
+        (min === undefined || n >= min) &&
+        (max === undefined || n <= max);
+    return ok ? n : undefined;
+}

package/esm/ui/PaletteContext.d.ts

@@ -0,0 +1,85 @@
+import type { JBrowsePalette } from './palette.ts';
+import type { JBrowseStyleTheme } from './styleTheme.ts';
+import type { ReactNode } from 'react';
+/**
+ * Supply the whole style theme — colors plus spacing and type scale. This is
+ * what JBrowse's own products mount, from `session.styleTheme`, so a config
+ * `theme` that sets `spacing` or `typography` reaches `makeStyles` and Material
+ * UI alike.
+ */
+export declare function StyleThemeProvider({ theme, children, }: {
+    theme: JBrowseStyleTheme;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Supply colors only, leaving JBrowse's default sizing in place. The narrower
+ * of the two, and what a host that already holds a palette mounts: it is saying
+ * what JBrowse should draw *with*, not restating its type scale.
+ *
+ * **A host following its own light/dark state wants
+ * {@link SessionPaletteProvider} instead**, which is this plus the session
+ * write that the worker-side half of the rendering derives from. This one
+ * colors React and nothing else.
+ */
+export declare function PaletteProvider({ palette, children, }: {
+    palette: JBrowsePalette;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useStyleTheme(): JBrowseStyleTheme;
+export declare function usePalette(): JBrowsePalette;
+/** What {@link useSessionPalette} needs of a session. */
+export interface ThemeModeSession {
+    setThemeMode: (mode: 'light' | 'dark') => void;
+    readonly palette: JBrowsePalette;
+}
+/**
+ * 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
+ * hand somewhere other than a provider. A host that only wants JBrowse to
+ * follow its dark mode mounts {@link SessionPaletteProvider}, which is this
+ * 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.
+ *
+ * **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
+ * this writes is also what ships to the RPC worker, where feature labels are
+ * baked into the rendered image. Mount `PaletteProvider` on a palette from
+ * somewhere else and those labels stay in the old mode — light text on a light
+ * image, and no error anywhere. `setThemeMode` writes the one slot both are
+ * derived from, which is why this returns the palette rather than taking one.
+ *
+ * The write lands in an effect, so the first paint after a mode change uses
+ * 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;
+/**
+ * #api
+ * Make JBrowse follow the host's light/dark state — the whole of it, in one
+ * mount:
+ *
+ * ```tsx
+ * <SessionPaletteProvider session={session} mode={myAppIsDark ? 'dark' : 'light'}>
+ *   {tracks}
+ * </SessionPaletteProvider>
+ * ```
+ *
+ * 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
+ * write is what reaches the RPC worker, which bakes feature labels into the
+ * rendered image. So a host that mounts only the provider gets light-mode
+ * labels on a dark page, from a canvas whose every other pixel is right, and
+ * nothing errors. See {@link useSessionPalette} for the mechanism.
+ *
+ * The session is the only thing that resolves a palette here, so a host
+ * supplying colors of its own mounts `PaletteProvider` directly instead.
+ */
+export declare function SessionPaletteProvider({ session, mode, children, }: {
+    session: ThemeModeSession;
+    mode: 'light' | 'dark';
+    children: ReactNode;
+}): import("react").JSX.Element;

package/esm/ui/PaletteContext.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useEffect, useMemo } from 'react';
+import { defaultStyleTheme } from './styleTheme.js';
+/**
+ * How a React component asks for JBrowse's design tokens.
+ *
+ * This is the toolkit-free counterpart to Material UI's `useTheme`, and it is
+ * the seam that lets a display component render without Material UI at all: a
+ * display reads `usePalette()` for its content colors, an embedding app
+ * supplies them by mounting `PaletteProvider` rather than a `ThemeProvider`,
+ * and `makeStyles` reads the whole thing through `useStyleTheme`.
+ *
+ * JBrowse's own products mount both, from the same session, so the Material UI
+ * chrome and the display content cannot disagree.
+ *
+ * With no provider above it this falls back to the default style theme,
+ * mirroring `useTheme`'s fall back to the default theme. That keeps a bare
+ * display mountable in a test or a minimal host without ceremony.
+ */
+const StyleThemeContext = createContext(undefined);
+/**
+ * Supply the whole style theme — colors plus spacing and type scale. This is
+ * what JBrowse's own products mount, from `session.styleTheme`, so a config
+ * `theme` that sets `spacing` or `typography` reaches `makeStyles` and Material
+ * UI alike.
+ */
+export function StyleThemeProvider({ theme, children, }) {
+    return _jsx(StyleThemeContext, { value: theme, children: children });
+}
+/**
+ * Supply colors only, leaving JBrowse's default sizing in place. The narrower
+ * of the two, and what a host that already holds a palette mounts: it is saying
+ * what JBrowse should draw *with*, not restating its type scale.
+ *
+ * **A host following its own light/dark state wants
+ * {@link SessionPaletteProvider} instead**, which is this plus the session
+ * write that the worker-side half of the rendering derives from. This one
+ * colors React and nothing else.
+ */
+export function PaletteProvider({ palette, children, }) {
+    const theme = useMemo(() => ({ ...defaultStyleTheme, palette }), [palette]);
+    return _jsx(StyleThemeProvider, { theme: theme, children: children });
+}
+export function useStyleTheme() {
+    return use(StyleThemeContext) ?? defaultStyleTheme;
+}
+export function usePalette() {
+    return useStyleTheme().palette;
+}
+/**
+ * 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
+ * hand somewhere other than a provider. A host that only wants JBrowse to
+ * follow its dark mode mounts {@link SessionPaletteProvider}, which is this
+ * 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.
+ *
+ * **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
+ * this writes is also what ships to the RPC worker, where feature labels are
+ * baked into the rendered image. Mount `PaletteProvider` on a palette from
+ * somewhere else and those labels stay in the old mode — light text on a light
+ * image, and no error anywhere. `setThemeMode` writes the one slot both are
+ * derived from, which is why this returns the palette rather than taking one.
+ *
+ * The write lands in an effect, so the first paint after a mode change uses
+ * 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 function useSessionPalette(session, mode) {
+    useEffect(() => {
+        session.setThemeMode(mode);
+    }, [session, mode]);
+    return session.palette;
+}
+/**
+ * #api
+ * Make JBrowse follow the host's light/dark state — the whole of it, in one
+ * mount:
+ *
+ * ```tsx
+ * <SessionPaletteProvider session={session} mode={myAppIsDark ? 'dark' : 'light'}>
+ *   {tracks}
+ * </SessionPaletteProvider>
+ * ```
+ *
+ * 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
+ * write is what reaches the RPC worker, which bakes feature labels into the
+ * rendered image. So a host that mounts only the provider gets light-mode
+ * labels on a dark page, from a canvas whose every other pixel is right, and
+ * nothing errors. See {@link useSessionPalette} for the mechanism.
+ *
+ * The session is the only thing that resolves a palette here, so a host
+ * supplying colors of its own mounts `PaletteProvider` directly instead.
+ */
+export function SessionPaletteProvider({ session, mode, children, }) {
+    const palette = useSessionPalette(session, mode);
+    return _jsx(PaletteProvider, { palette: palette, children: children });
+}

package/esm/ui/PinAdornment.d.ts

@@ -0,0 +1,5 @@
+import type { MenuItemPin } from './MenuTypes.ts';
+export declare function PinAdornment({ pin, disabled, }: {
+    pin: MenuItemPin;
+    disabled?: boolean;
+}): import("react").JSX.Element;

package/esm/ui/PinAdornment.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import PushPinIcon from '@mui/icons-material/PushPin';
+import PushPinOutlinedIcon from '@mui/icons-material/PushPinOutlined';
+import { ToggleButton, Tooltip } from '@mui/material';
+import { makeStyles } from '../util/tss-react/index.js';
+const useStyles = makeStyles()(theme => ({
+    // compact enough to sit inline with the value check: drop the default
+    // ToggleButton border/padding so it's ~icon-sized, but keep the selected
+    // background tint (an unmistakable on/off signal, unlike a hollow-vs-filled
+    // icon alone)
+    button: {
+        border: 0,
+        padding: theme.spacing(0.25),
+    },
+    // the Tooltip listens on this rather than on the button, which fires no
+    // events once the row disables it
+    wrapper: {
+        display: 'inline-flex',
+    },
+}));
+// How the pin names what it acts on. Two shapes, decided by the on-value:
+//
+// - **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
+        ? {
+            title: `${label} is ${pinPredicate(onValue)} for all tracks of this type (click to clear)`,
+            ariaLabel: `clear the default for ${label}`,
+        }
+        : typeof onValue === 'boolean'
+            ? {
+                title: `Turn ${label} ${onValue ? 'on' : 'off'} for all open tracks of this type`,
+                ariaLabel: `turn ${label} ${onValue ? 'on' : 'off'} for all open tracks`,
+            }
+            : {
+                title: `Apply ${label} to all open tracks of this type`,
+                ariaLabel: `apply ${label} to all open tracks`,
+            };
+}
+// 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.
+//
+// **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.
+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 => {
+                    e.stopPropagation();
+                    control.toggle();
+                }, children: isDefault ? (_jsx(PushPinIcon, { fontSize: "small" })) : (_jsx(PushPinOutlinedIcon, { fontSize: "small" })) }) }) }));
+}

package/esm/ui/PluggableComponent.d.ts

@@ -0,0 +1,10 @@
+import type PluginManager from '../PluginManager';
+import type { ExtensionPointName, ExtensionPointProps } from '../PluginManager';
+import type React from 'react';
+declare const PluggableComponent: <N extends ExtensionPointName, P extends object>({ pluginManager, name, component: DefaultComponent, props, }: {
+    pluginManager: PluginManager;
+    name: N;
+    component: React.ComponentType<P> | React.LazyExoticComponent<React.ComponentType<P>>;
+    props: P & ExtensionPointProps<N>;
+}) => React.JSX.Element;
+export default PluggableComponent;

package/esm/ui/PluggableComponent.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { observer } from 'mobx-react';
+// A point rendered here is a single-component fold: its registry entry declares
+// `args`/`result` as the component type and `props` as that component's prop
+// bag (see Core-replaceWidget for the canonical shape). Taking the name as a
+// registry key rather than a bare string is what checks the default component
+// and the props against the contract, instead of trusting the call site.
+//
+// observer so that observable reads inside evaluateExtensionPoint callbacks
+// (e.g. model.trackAdapterType) are tracked here — re-evaluates when they
+// change without relying on the parent being an observer
+const PluggableComponent = observer(function PluggableComponent({ pluginManager, name, component: DefaultComponent, props, }) {
+    // the result is the point's declared component type, and `props` satisfies
+    // the point's declared props by the signature above. TS can't narrow either
+    // through the generic key, so both are restated here
+    const Component = pluginManager.evaluateComponentExtensionPoint(name, DefaultComponent, ...[props]);
+    return _jsx(Component, { ...props });
+});
+export default PluggableComponent;

package/esm/ui/PluggableComponents.d.ts

@@ -0,0 +1,29 @@
+import type PluginManager from '../PluginManager.ts';
+import type { ExtensionPointRegistry, PointsOfKind } from '../PluginManager.ts';
+/**
+ * The extension points that accumulate an array of components — every point
+ * declared `ComponentList`. Points accumulating rendered `ReactNode`s are
+ * `ElementList` instead, and belong to {@link PluggableElements}.
+ */
+export type ComponentExtensionPointName = PointsOfKind<'componentList'>;
+/** The props a component point hands each of its panels. */
+export type PanelProps<N extends ComponentExtensionPointName> = ExtensionPointRegistry[N]['props'];
+/**
+ * Render every component contributed to an accumulating point, in registration
+ * order, each with the point's props.
+ *
+ * The component sibling of {@link PluggableElements}. Owning the loop here is
+ * what makes a new panel seam one tag rather than a producer that re-derives
+ * the `Suspense` boundary, the keys and the legacy normalization — each of
+ * which was wrong in one of the two producers that used to hand-roll it.
+ *
+ * A contributed panel scopes itself, rendering `null` when it does not apply —
+ * {@link matchesTrackSelector} is what decides that. It also draws its own card
+ * chrome, since only the panel knows whether it wants a title.
+ */
+declare const PluggableComponents: <N extends ComponentExtensionPointName>({ pluginManager, name, props, }: {
+    pluginManager: PluginManager;
+    name: N;
+    props: PanelProps<N>;
+}) => import("react").JSX.Element;
+export default PluggableComponents;

package/esm/ui/PluggableComponents.js

@@ -0,0 +1,28 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Suspense } from 'react';
+import { observer } from 'mobx-react';
+/**
+ * Render every component contributed to an accumulating point, in registration
+ * order, each with the point's props.
+ *
+ * The component sibling of {@link PluggableElements}. Owning the loop here is
+ * what makes a new panel seam one tag rather than a producer that re-derives
+ * the `Suspense` boundary, the keys and the legacy normalization — each of
+ * which was wrong in one of the two producers that used to hand-roll it.
+ *
+ * A contributed panel scopes itself, rendering `null` when it does not apply —
+ * {@link matchesTrackSelector} is what decides that. It also draws its own card
+ * chrome, since only the panel knows whether it wants a title.
+ */
+const PluggableComponents = observer(function PluggableComponents({ pluginManager, name, props, }) {
+    // restated for the same reason as PluggableElements: neither the empty
+    // accumulator nor the props narrow through the generic key. [x].flat()
+    // tolerates a pre-v5 callback that returned one component instead of appending
+    const components = [
+        pluginManager.evaluateExtensionPoint(name, [], ...[props]),
+    ].flat();
+    return (_jsx(_Fragment, { children: components.map((Component, i) => (_jsx(Suspense
+        // eslint-disable-next-line @eslint-react/no-array-index-key -- registration-ordered, so stable across renders
+        , { fallback: null, children: _jsx(Component, { ...props }) }, i))) }));
+});
+export default PluggableComponents;