@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/ui/SvgColorLegend.js

@@ -0,0 +1,106 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* eslint-disable react-refresh/only-export-components -- geometry constants belong with this leaf SVG primitive; no component state to fast-refresh */
+import { useId } from 'react';
+import { svgSafeId } from '../svg/svgId.js';
+import { LegendSwatchGlyph } from './LegendSwatchGlyph.js';
+import { measureLegendText } from './measureLegendText.js';
+const FONT_SIZE = 10;
+const SWATCH_LEFT = 2;
+const SWATCH_GAP = 2;
+// Row geometry, exported so callers sizing an outer container stay in lockstep
+// with what this draws.
+export const LEGEND_ROW_HEIGHT = 14;
+export const LEGEND_SWATCH = 10;
+const GRADIENT_BAR_WIDTH = 100;
+const GRADIENT_BAR_HEIGHT = 10;
+// the bar plus the row of domain labels under it
+const GRADIENT_ROW_HEIGHT = GRADIENT_BAR_HEIGHT + 4 + LEGEND_ROW_HEIGHT;
+/**
+ * Horizontal space the LGV export reserves beside the plot for a display whose
+ * legend asked to sit off the plot (`LegendMixin.svgLegendWidth`): the widest
+ * row this draws for a ramp, plus a margin either side.
+ */
+export const LEGEND_SVG_GUTTER_WIDTH = GRADIENT_BAR_WIDTH + 40;
+// A row's swatches, with the flat `color` shorthand read as the single
+// square it has always drawn.
+function entrySwatches(entry) {
+    return (entry.swatches ??
+        (entry.color === undefined ? [] : [{ color: entry.color }]));
+}
+// A row keying a color, as opposed to a title or note over such rows.
+function keysAColor(entry) {
+    return entry.gradient !== undefined || entrySwatches(entry).length > 0;
+}
+// A ramp row is the bar and its labels, captioned when the entry has a label.
+function rowHeight(entry) {
+    return entry.gradient
+        ? GRADIENT_ROW_HEIGHT + (entry.label ? LEGEND_ROW_HEIGHT : 0)
+        : LEGEND_ROW_HEIGHT;
+}
+// The rows that fit `maxHeight`, leaving room for a "+N more" summary when
+// they do not all fit. A heading the cut separated from every row under it is
+// dropped with them.
+function fitEntries(entries, maxHeight) {
+    let used = 0;
+    const shown = [];
+    for (const [idx, entry] of entries.entries()) {
+        const rest = entries.length - idx - 1;
+        const reserve = rest > 0 ? LEGEND_ROW_HEIGHT : 0;
+        if (used + rowHeight(entry) + reserve > maxHeight && shown.length > 0) {
+            break;
+        }
+        used += rowHeight(entry);
+        shown.push(entry);
+    }
+    while (shown.length > 1 &&
+        shown.length < entries.length &&
+        !keysAColor(shown.at(-1))) {
+        shown.pop();
+    }
+    return shown;
+}
+function GradientRow({ entry, width, gradientId, }) {
+    const { stops, minLabel, maxLabel } = entry.gradient;
+    const barTop = (entry.label ? LEGEND_ROW_HEIGHT : 0) + 2;
+    const labelY = barTop + GRADIENT_BAR_HEIGHT + 2 + FONT_SIZE;
+    return (_jsxs(_Fragment, { children: [_jsx("rect", { x: 0, y: 0, width: width, height: rowHeight(entry), fill: "rgba(255,255,255,0.95)" }), entry.label ? (_jsx("text", { x: SWATCH_LEFT, y: 11, fontSize: FONT_SIZE, fill: "black", children: entry.label })) : null, _jsx("defs", { children: _jsx("linearGradient", { id: gradientId, x1: "0%", y1: "0%", x2: "100%", y2: "0%", children: stops.map(stop => (_jsx("stop", { offset: stop.offset, style: { stopColor: stop.color, stopOpacity: stop.opacity ?? 1 } }, stop.offset))) }) }), _jsx("rect", { x: SWATCH_LEFT, y: barTop, width: GRADIENT_BAR_WIDTH, height: GRADIENT_BAR_HEIGHT, fill: `url(#${gradientId})`, rx: 2 }), _jsx("text", { x: SWATCH_LEFT, y: labelY, fontSize: FONT_SIZE, fill: "black", children: minLabel }), _jsx("text", { x: SWATCH_LEFT + GRADIENT_BAR_WIDTH, y: labelY, fontSize: FONT_SIZE, fill: "black", textAnchor: "end", children: maxLabel })] }));
+}
+// Shared SVG color key: one translucent row per entry — a swatch and a label,
+// or a ramp bar with its domain ends — right-aligned within `canvasWidth`, or
+// at `x` when the caller places it (the LGV export's legend gutter). A <g>, so
+// an on-screen SVG overlay and the export share one renderer.
+//
+// `maxHeight` (the display height) caps the box: entries past what fits
+// collapse into a trailing "+N more" summary row, so the legend never overflows
+// its display — the full list stays reachable via the track menu.
+export default function SvgColorLegend({ entries, canvasWidth, x, maxHeight, testid, idPrefix, }) {
+    const reactId = useId();
+    const legendId = idPrefix ?? reactId;
+    const shown = maxHeight === undefined ? entries : fitEntries(entries, maxHeight);
+    const cutRows = entries.slice(shown.length).filter(keysAColor).length;
+    const overflowLabel = cutRows > 0 ? `+${cutRows} more` : undefined;
+    // Labels line up across rows, so the swatch column is sized by the row with
+    // the most swatches — otherwise a two-box row shoves its own label out of the
+    // column the others share. One box reproduces the original 16px inset.
+    const swatchColumns = Math.max(1, ...shown.map(e => entrySwatches(e).length));
+    const textLeft = SWATCH_LEFT + swatchColumns * (LEGEND_SWATCH + SWATCH_GAP) + 2;
+    let contentRight = 0;
+    for (const entry of shown) {
+        contentRight = Math.max(contentRight, entry.gradient
+            ? SWATCH_LEFT +
+                Math.max(GRADIENT_BAR_WIDTH, measureLegendText(entry.label, FONT_SIZE))
+            : textLeft + measureLegendText(entry.label, FONT_SIZE));
+    }
+    if (overflowLabel !== undefined) {
+        contentRight = Math.max(contentRight, textLeft + measureLegendText(overflowLabel, FONT_SIZE));
+    }
+    const totalWidth = contentRight + 6;
+    const left = x ?? Math.max(0, canvasWidth - totalWidth - 4);
+    const rowTops = [];
+    let y = 0;
+    for (const entry of shown) {
+        rowTops.push(y);
+        y += rowHeight(entry);
+    }
+    return shown.length || overflowLabel ? (_jsxs("g", { transform: `translate(${left} 0)`, "data-testid": testid, children: [shown.map((entry, idx) => (_jsx("g", { transform: `translate(0 ${rowTops[idx]})`, children: entry.gradient ? (_jsx(GradientRow, { entry: entry, width: totalWidth, gradientId: svgSafeId(`${legendId}-${entry.key}`) })) : (_jsxs(_Fragment, { children: [_jsx("rect", { x: 0, y: 0, width: totalWidth, height: LEGEND_ROW_HEIGHT, fill: "rgba(255,255,255,0.95)" }), _jsxs("g", { opacity: entry.hidden ? 0.35 : 1, children: [entrySwatches(entry).map((swatch, i) => (_jsx(LegendSwatchGlyph, { swatch: swatch, size: LEGEND_SWATCH, x: SWATCH_LEFT + i * (LEGEND_SWATCH + SWATCH_GAP), y: 2 }, `${swatch.shape}-${swatch.color}`))), _jsx("text", { x: textLeft, y: 11, fontSize: FONT_SIZE, fill: "black", textDecoration: entry.hidden ? 'line-through' : undefined, children: entry.label })] })] })) }, entry.key))), overflowLabel === undefined ? null : (_jsxs("g", { transform: `translate(0 ${y})`, children: [_jsx("rect", { x: 0, y: 0, width: totalWidth, height: LEGEND_ROW_HEIGHT, fill: "rgba(255,255,255,0.95)" }), _jsx("text", { x: textLeft, y: 11, fontSize: FONT_SIZE, fill: "#555", children: overflowLabel })] }))] })) : null;
+}

package/esm/ui/TagTextField.d.ts

@@ -0,0 +1,40 @@
+import type { TextFieldProps } from '@mui/material';
+/** A quick-pick shortcut: the two-character tag plus a human label. */
+export interface TagQuickPick {
+    tag: string;
+    label?: string;
+}
+interface OwnProps {
+    /** Initial tag; undefined or '' renders as empty input. */
+    defaultValue?: string;
+    /**
+     * Fires on every keystroke with the tag when it is a valid 2-character SAM
+     * tag, or undefined otherwise. The parent gates submission on undefined.
+     */
+    onValueChange: (value: string | undefined) => void;
+    /**
+     * Optional hint shown under the input. Off by default — the field is capped at
+     * two characters and the quick-pick chips already teach the common tags, so a
+     * persistent hint just adds a line that misaligns the field against its
+     * siblings. The invalid-tag error still shows regardless.
+     */
+    helperText?: TextFieldProps['helperText'];
+    /** data-testid forwarded to the inner <input> (used by screenshot specs). */
+    inputTestId?: string;
+    /**
+     * One-click shortcuts for common tags (e.g. HP, RG) shown as chips above the
+     * field, so users don't have to know and type the two-letter code. Clicking a
+     * chip fills the field and emits the value exactly as typing it would.
+     */
+    quickPicks?: TagQuickPick[];
+}
+type Props = Omit<TextFieldProps, 'value' | 'onChange' | 'error' | 'helperText' | 'slotProps'> & OwnProps;
+/**
+ * Uncontrolled-style TextField for a two-character SAM tag (e.g. HP, RG, XS).
+ * Owns the input text internally; emits the tag string when valid (or
+ * undefined) to the parent. Caps input at two characters and shows an inline
+ * error once two invalid characters are entered. Optional `quickPicks` render a
+ * chip row of common tags that fill the field on click.
+ */
+export default function TagTextField(props: Props): import("react").JSX.Element;
+export {};

package/esm/ui/TagTextField.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { Chip, Stack, TextField } from '@mui/material';
+import { isValidTag } from '../util/tags.js';
+/**
+ * Uncontrolled-style TextField for a two-character SAM tag (e.g. HP, RG, XS).
+ * Owns the input text internally; emits the tag string when valid (or
+ * undefined) to the parent. Caps input at two characters and shows an inline
+ * error once two invalid characters are entered. Optional `quickPicks` render a
+ * chip row of common tags that fill the field on click.
+ */
+export default function TagTextField(props) {
+    const { defaultValue = '', onValueChange, helperText, inputTestId, quickPicks, ...rest } = props;
+    const [text, setText] = useState(defaultValue);
+    const showError = text.length === 2 && !isValidTag(text);
+    // Both a chip click and typing flow through here so the two paths can't
+    // disagree about validation or what gets emitted.
+    const setValue = (next) => {
+        setText(next);
+        onValueChange(isValidTag(next) ? next : undefined);
+    };
+    return (_jsxs(Stack, { spacing: 1, children: [quickPicks?.length ? (_jsx(Stack, { direction: "row", spacing: 1, useFlexGap: true, sx: { flexWrap: 'wrap' }, children: quickPicks.map(({ tag, label }) => (_jsx(Chip, { size: "small", label: label ? `${tag} — ${label}` : tag, color: text === tag ? 'primary' : 'default', variant: text === tag ? 'filled' : 'outlined', onClick: () => {
+                        setValue(tag);
+                    } }, tag))) })) : null, _jsx(TextField, { label: "Tag name", ...rest, value: text, error: showError, helperText: showError ? 'Not a valid tag' : helperText, autoComplete: "off", slotProps: {
+                    htmlInput: {
+                        maxLength: 2,
+                        'data-testid': inputTestId,
+                    },
+                }, onChange: event => {
+                    setValue(event.target.value);
+                } })] }));
+}

package/esm/ui/VerticalScrollbar.d.ts

@@ -0,0 +1,24 @@
+import type { VirtualScrollModel } from '../util/useVirtualScrollWheel.ts';
+/**
+ * How much of a display's right edge this occupies while it is drawn, for the
+ * chrome the displays draw beside it.
+ */
+export declare const VERTICAL_SCROLLBAR_WIDTH = 12;
+/** Where the right edge of something sitting beside the thumb goes. */
+export declare const VERTICAL_SCROLLBAR_CLEARANCE: number;
+/**
+ * Draggable vertical scrollbar overlay for a virtually scrolled display.
+ * Renders nothing when the content fits.
+ *
+ * Not a keyboard tab stop: the views have no keyboard navigation to reach the
+ * scrolled content, so `tabIndex` would only add noise. The `role="scrollbar"`
+ * semantics stay for pointer and voice assistive tech.
+ */
+declare const VerticalScrollbar: ({ model, controlsId, top, }: {
+    model: VirtualScrollModel;
+    /** `id` of the scrolled viewport element, for `aria-controls`. */
+    controlsId: string;
+    /** Track offset from the top, for displays with a sticky band above it. */
+    top?: number;
+}) => import("react").JSX.Element | null;
+export default VerticalScrollbar;

package/esm/ui/VerticalScrollbar.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { observer } from 'mobx-react';
+import { clamp } from '../util/numericUtils.js';
+import { makeStyles } from '../util/tss-react/index.js';
+import { usePointerDrag } from '../util/usePointerDrag.js';
+import { useRafCommit } from '../util/useRafCommit.js';
+import { useVirtualScrollWheel } from '../util/useVirtualScrollWheel.js';
+/**
+ * How much of a display's right edge this occupies while it is drawn, for the
+ * chrome the displays draw beside it.
+ */
+export const VERTICAL_SCROLLBAR_WIDTH = 12;
+/** Where the right edge of something sitting beside the thumb goes. */
+export const VERTICAL_SCROLLBAR_CLEARANCE = VERTICAL_SCROLLBAR_WIDTH + 2;
+const MIN_THUMB_HEIGHT = 20;
+const useStyles = makeStyles()(theme => ({
+    track: {
+        position: 'absolute',
+        right: 0,
+        width: VERTICAL_SCROLLBAR_WIDTH,
+        cursor: 'default',
+        zIndex: 10,
+        // without it the browser claims a touch drag as a page scroll
+        touchAction: 'none',
+        '&:hover > *': {
+            background: theme.palette.action.active,
+        },
+    },
+    thumb: {
+        position: 'absolute',
+        right: 2,
+        width: 6,
+        borderRadius: 3,
+        background: theme.palette.action.disabled,
+        pointerEvents: 'none',
+    },
+}));
+/**
+ * Draggable vertical scrollbar overlay for a virtually scrolled display.
+ * Renders nothing when the content fits.
+ *
+ * Not a keyboard tab stop: the views have no keyboard navigation to reach the
+ * scrolled content, so `tabIndex` would only add noise. The `role="scrollbar"`
+ * semantics stay for pointer and voice assistive tech.
+ */
+const VerticalScrollbar = observer(function VerticalScrollbar({ model, controlsId, top = 0, }) {
+    const { classes } = useStyles();
+    const dragRef = useRef(undefined);
+    const [trackEl, setTrackEl] = useState(null);
+    const { schedule: scheduleScroll, flush: flushScroll } = useRafCommit((n) => {
+        model.setScrollTop(n);
+    });
+    const { scrollTop, scrollableHeight, scrollViewportHeight: viewportHeight, } = model;
+    // Wheeling the scrollbar always scrolls the panel, whatever `scrollZoom`
+    // says, and never reaches the view.
+    useVirtualScrollWheel(trackEl, model, (e, scroll) => {
+        scroll();
+        e.stopPropagation();
+    });
+    const clampedScrollTop = clamp(scrollTop, 0, scrollableHeight);
+    const contentHeight = viewportHeight + scrollableHeight;
+    const thumbHeight = Math.min(viewportHeight, Math.max(MIN_THUMB_HEIGHT, viewportHeight * (viewportHeight / contentHeight)));
+    const usableTrack = viewportHeight - thumbHeight;
+    const thumbTop = clamp((clampedScrollTop / scrollableHeight) * usableTrack, 0, usableTrack);
+    // A press on the track above or below the thumb pages one viewport toward it
+    // rather than starting a drag; `dragRef` staying unset makes the captured
+    // moves that follow do nothing.
+    const drag = usePointerDrag({
+        onDragStart: e => {
+            const clickY = e.clientY - e.currentTarget.getBoundingClientRect().top;
+            if (clickY < thumbTop || clickY > thumbTop + thumbHeight) {
+                const dir = clickY < thumbTop ? -1 : 1;
+                model.setScrollTop(clamp(clampedScrollTop + dir * viewportHeight, 0, scrollableHeight));
+            }
+            else {
+                dragRef.current = { startY: e.clientY, startScroll: clampedScrollTop };
+            }
+        },
+        onDrag: e => {
+            const d = dragRef.current;
+            if (d && usableTrack > 0) {
+                const delta = ((e.clientY - d.startY) / usableTrack) * scrollableHeight;
+                scheduleScroll(clamp(d.startScroll + delta, 0, scrollableHeight));
+            }
+        },
+        onDragEnd: () => {
+            flushScroll();
+            dragRef.current = undefined;
+        },
+    });
+    // below every hook: "the content fits" flips while mounted
+    if (scrollableHeight <= 0) {
+        return null;
+    }
+    return (_jsx("div", { ref: setTrackEl, "data-testid": "vertical-scrollbar", "data-gesture-owner": "true", className: classes.track, style: { top, height: viewportHeight }, role: "scrollbar", "aria-label": "Vertical scrollbar", "aria-controls": controlsId, "aria-orientation": "vertical", "aria-valuemin": 0, "aria-valuemax": Math.round(scrollableHeight), "aria-valuenow": Math.round(clampedScrollTop), ...drag, 
+        // every button, so a right-press the drag ignores doesn't pan the view
+        // either; no preventDefault, so focus still moves and menus still open
+        onPointerDown: e => {
+            e.stopPropagation();
+            drag.onPointerDown(e);
+        }, children: _jsx("div", { className: classes.thumb, style: { top: thumbTop, height: thumbHeight } }) }));
+});
+export default VerticalScrollbar;

package/esm/ui/ViewLoadingScreen.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The "view exists but isn't ready yet" screen a view renders instead of its
+ * content — LGV, dotplot and linear synteny all show it while the assembly they
+ * name is still loading. A load past two seconds is labelled with which of the
+ * assembly's files is downloading, and a determinate bar when that download
+ * reports one; a faster one says only "Loading".
+ *
+ * A load that then stops reporting names the file it is waiting on. The phase
+ * label alone does not: "Downloading chromosome aliases" is a fair description
+ * of what is happening and no help at all in front of a hub that has stopped
+ * answering, where the one useful fact is which server that is. Shown only once
+ * the load has actually stalled, so a healthy startup never sees a URL.
+ *
+ * Metrics deliberately match `DiagonalizeLoadingScreen`, which is the sibling
+ * render branch in both comparative views: a view that flipped between the two
+ * would otherwise jump between two differently laid-out loading screens. That
+ * shared layout is also why this exists at all rather than each view calling
+ * {@link LoadingProgress} directly — bare, it renders an unconstrained
+ * full-width bar under an unaligned label.
+ */
+export default function ViewLoadingScreen({ message, progress, source, }: {
+    message?: string;
+    progress?: number;
+    source?: string;
+}): import("react").JSX.Element;

package/esm/ui/ViewLoadingScreen.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Typography } from '@mui/material';
+import { useSlowLoad, useStalled } from '../util/hooks.js';
+import { makeStyles } from '../util/tss-react/index.js';
+import LoadingProgress from './LoadingProgress.js';
+const useStyles = makeStyles()(theme => ({
+    root: {
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 8,
+        padding: 20,
+    },
+    bar: {
+        width: 300,
+        maxWidth: '80%',
+    },
+    stalled: {
+        maxWidth: 500,
+        textAlign: 'center',
+        // a presigned URL is a few hundred unbroken characters, and the notice must
+        // not widen the view it is centered in
+        overflowWrap: 'anywhere',
+        color: theme.palette.text.secondary,
+    },
+}));
+/**
+ * The "view exists but isn't ready yet" screen a view renders instead of its
+ * content — LGV, dotplot and linear synteny all show it while the assembly they
+ * name is still loading. A load past two seconds is labelled with which of the
+ * assembly's files is downloading, and a determinate bar when that download
+ * reports one; a faster one says only "Loading".
+ *
+ * A load that then stops reporting names the file it is waiting on. The phase
+ * label alone does not: "Downloading chromosome aliases" is a fair description
+ * of what is happening and no help at all in front of a hub that has stopped
+ * answering, where the one useful fact is which server that is. Shown only once
+ * the load has actually stalled, so a healthy startup never sees a URL.
+ *
+ * Metrics deliberately match `DiagonalizeLoadingScreen`, which is the sibling
+ * render branch in both comparative views: a view that flipped between the two
+ * would otherwise jump between two differently laid-out loading screens. That
+ * shared layout is also why this exists at all rather than each view calling
+ * {@link LoadingProgress} directly — bare, it renders an unconstrained
+ * full-width bar under an unaligned label.
+ */
+export default function ViewLoadingScreen({ message, progress, source, }) {
+    const { classes } = useStyles();
+    const slow = useSlowLoad();
+    const stalled = useStalled(`${message}|${progress}|${source}`);
+    return (_jsxs("div", { className: classes.root, children: [_jsx(LoadingProgress, { variant: "h6", message: slow ? message : undefined, fraction: slow ? progress : undefined, barClassName: classes.bar }), stalled && source ? (_jsxs(Typography, { variant: "body2", className: classes.stalled, children: ["still waiting on ", source] })) : null] }));
+}

package/esm/ui/addExtensionElement.d.ts

@@ -0,0 +1,18 @@
+import type PluginManager from '../PluginManager.ts';
+import type { ExtensionPointProps, PointsOfKind } from '../PluginManager.ts';
+import type { ComponentType } from 'react';
+/**
+ * The extension points that accumulate an array of rendered elements — every
+ * point declared `ElementList`, the LGV and dotplot overlays.
+ * {@link PluggableElements} is the producer side.
+ */
+export type ElementExtensionPointName = PointsOfKind<'elementList'>;
+/**
+ * Render `component` into an overlay extension point, passing it the point's
+ * props.
+ *
+ * Prefer this to contributing the element yourself: it fixes the React `key` at
+ * registration time, and forgetting that one produces a warning pointing at
+ * framework code rather than at the plugin.
+ */
+export declare function addExtensionElement<N extends ElementExtensionPointName>(pluginManager: PluginManager, name: N, component: ComponentType<ExtensionPointProps<N>>): void;

package/esm/ui/addExtensionElement.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Render `component` into an overlay extension point, passing it the point's
+ * props.
+ *
+ * Prefer this to contributing the element yourself: it fixes the React `key` at
+ * registration time, and forgetting that one produces a warning pointing at
+ * framework code rather than at the plugin.
+ */
+export function addExtensionElement(pluginManager, name, component) {
+    const Component = component;
+    // unique per registration, and stable across renders because it is fixed at
+    // registration time rather than derived from anything the fold sees
+    const key = `${name}-${Component.displayName ?? Component.name}-${pluginManager.extensionPoints.get(name)?.length ?? 0}`;
+    // ElementExtensionPointName constrains this point's entry to a ReactNode, but
+    // neither compiler resolves ExtensionPointEntry<N> through the generic key.
+    // tsc7 rejects the element without the assertion; eslint's TS6 service thinks
+    // the assertion is redundant. Same split as SessionTracks.ts.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- tsc7 needs it
+    /* oxlint-disable typescript/no-unnecessary-type-assertion */
+    pluginManager.contributeToExtensionPoint(name, props => (_jsx(Component, { ...props }, key)));
+    /* oxlint-enable typescript/no-unnecessary-type-assertion */
+}

package/esm/ui/buildExtraTrackMenuItems.d.ts

@@ -0,0 +1,22 @@
+import type PluginManager from '../PluginManager.ts';
+import type { AnyConfigurationModel } from '../configuration/index.ts';
+import type { AbstractSessionModel, TrackActionView } from '../util/types/index.ts';
+import type { MenuItem } from './MenuTypes.ts';
+export interface ExtraTrackMenuItemsProps {
+    session: AbstractSessionModel;
+    config: AnyConfigurationModel;
+    view?: TrackActionView;
+}
+/** Return the items to add, or nothing when the track isn't yours. */
+export type ExtraTrackMenuItemsCallback = (props: ExtraTrackMenuItemsProps) => MenuItem | MenuItem[] | undefined;
+declare module '@jbrowse/core/PluginManager' {
+    interface ExtensionPointRegistry {
+        'Core-extraTrackMenuItems': {
+            args: MenuItem[];
+            result: MenuItem[];
+            props: ExtraTrackMenuItemsProps;
+        };
+    }
+}
+export declare function addExtraTrackMenuItems(pluginManager: PluginManager, callback: ExtraTrackMenuItemsCallback): void;
+export declare function buildExtraTrackMenuItems(pluginManager: PluginManager, props: ExtraTrackMenuItemsProps): MenuItem[];

package/esm/ui/buildExtraTrackMenuItems.js

@@ -0,0 +1,14 @@
+// Plugins call this to contribute per-track menu items (keyed off the track
+// config) to the hierarchical track selector. Wrapping the registration here
+// keeps the typed callback contract in one place so callers don't depend on the
+// extension-point type augmentation crossing package boundaries.
+export function addExtraTrackMenuItems(pluginManager, callback) {
+    pluginManager.contributeToExtensionPoint('Core-extraTrackMenuItems', callback);
+}
+// Returns the contributed per-track menu items, or an empty array when no
+// plugin contributes, so callers can spread it.
+export function buildExtraTrackMenuItems(pluginManager, props) {
+    return pluginManager.evaluateExtensionPoint(
+    /** #extensionPoint Core-extraTrackMenuItems | sync | Add items to a single track's menu */
+    'Core-extraTrackMenuItems', [], props);
+}

package/esm/ui/colorScale.d.ts

@@ -0,0 +1,92 @@
+import type { LegendSpec, LegendSwatch } from './legendSpec.ts';
+/**
+ * One value a categorical scale colors. `value` is the datum the color
+ * classifies (an SV type, a sample group, an impact tier), `label` how the key
+ * names it. A row with no `color` is a note in the key rather than a swatch —
+ * "+N more", or a rule the swatches cannot state.
+ */
+export interface CategoricalEntry {
+    value: string;
+    /**
+     * Every value painted in this row's color where the key is derived from
+     * the painting (`derivedColorScale`), `value` being the first; the label
+     * names them all. A row declared one value at a time leaves it unset.
+     */
+    values?: string[];
+    label: string;
+    color?: string;
+    swatches?: LegendSwatch[];
+    hidden?: boolean;
+    missing?: boolean;
+}
+/**
+ * A color vocabulary: a finite set of values, each drawn in one color. ADR-094's
+ * palette-index and per-instance-value cardinalities both resolve to this once
+ * the values are enumerated.
+ */
+export interface CategoricalScale {
+    kind: 'categorical';
+    id: string;
+    title?: string;
+    entries: CategoricalEntry[];
+    domain?: readonly string[];
+    focusesRows?: boolean;
+    note?: string;
+}
+/** One stop of a continuous ramp, `offset` in `[0, 1]`. */
+export interface RampStop {
+    offset: number;
+    color: string;
+    opacity?: number;
+}
+/**
+ * A scalar through a color ramp: ADR-094's scalar-through-a-scale
+ * cardinality. `stops` are what the painter samples — read them out of the
+ * same LUT the GPU uploads (`stopsFromRampLut`) so the bar is byte-identical
+ * to the plot. `format` prints the domain ends; `formatScore` by default, so
+ * a domain measured off the data prints `24.4` and not the float it was
+ * measured as.
+ */
+export interface RampScale {
+    kind: 'ramp';
+    id: string;
+    title?: string;
+    domain: [number, number];
+    stops: RampStop[];
+    format?: (value: number) => string;
+    /**
+     * The loaded values' extremes. An end of `domain` the data runs past prints
+     * `≤` or `≥`, since the ramp paints every value beyond it in its end colour.
+     */
+    extent?: readonly [number, number];
+}
+/**
+ * What a display says about one of its color channels. A display declares a
+ * list of these (`LegendMixin.colorScales`) and the legend derives from it, so
+ * the key cannot list a color nothing painted.
+ */
+export type ColorScale = CategoricalScale | RampScale;
+/**
+ * The one derivation of a legend from a display's color scales: a section per
+ * scale, in the order declared. On screen `FloatingLegend` renders the result
+ * and the export flattens it through `legendEntries`, so the two cannot
+ * describe different colors.
+ *
+ * A lone scale names itself: section titles draw only beside other sections,
+ * so a lone categorical scale's title becomes the box's (a field's name over
+ * its values) and a lone ramp's goes on its row. Empty scales are
+ * dropped first, so one waiting for data does not leave its sibling untitled.
+ */
+export declare function legendSpecOf(scales: ColorScale[]): LegendSpec;
+/**
+ * The no-value row goes after every value a `domain` orders: the domain never
+ * lists it, so ordering by the domain alone ranks it with the values the
+ * domain leaves out.
+ */
+export declare function missingRowLast(a: {
+    missing?: boolean;
+}, b: {
+    missing?: boolean;
+}): number;
+/** Whether a scale has anything for a key to show. */
+export declare function colorScaleIsEmpty(scale: ColorScale): boolean;

package/esm/ui/colorScale.js

@@ -0,0 +1,72 @@
+import { groupKeyComparator } from '../util/groupKeys.js';
+import { formatScore } from '../util/numericUtils.js';
+// A lone ramp names itself on its row: `FloatingLegend` and `legendEntries`
+// draw a section's title only beside other sections, and a bar of numbers
+// with nothing saying what they count is not a key.
+function rampItem({ title, domain, stops, format = formatScore, extent }, lone) {
+    const [min, max] = domain;
+    const [lo, hi] = extent ?? domain;
+    // compared at float32 as well, since a value lane carries the extent in one
+    // and a pinned 0.3 is then a hair under the 0.3 it read
+    const below = lo < min && Math.fround(lo) < Math.fround(min);
+    const above = hi > max && Math.fround(hi) > Math.fround(max);
+    return {
+        label: lone ? (title ?? '') : '',
+        gradient: {
+            stops,
+            minLabel: `${below ? '≤' : ''}${format(min)}`,
+            maxLabel: `${above ? '≥' : ''}${format(max)}`,
+        },
+    };
+}
+function sectionOf(scale, lone) {
+    if (scale.kind !== 'categorical') {
+        return { id: scale.id, title: scale.title, items: [rampItem(scale, lone)] };
+    }
+    // A key a display ordered itself keeps that order, rows it lists after the
+    // no-value row included.
+    const compare = scale.domain?.length
+        ? groupKeyComparator(scale.domain)
+        : undefined;
+    const items = compare
+        ? scale.entries.toSorted((a, b) => missingRowLast(a, b) || compare(a.value, b.value))
+        : scale.entries;
+    return {
+        id: scale.id,
+        title: scale.title,
+        note: scale.note,
+        items,
+        focusesRows: scale.focusesRows,
+    };
+}
+/**
+ * The one derivation of a legend from a display's color scales: a section per
+ * scale, in the order declared. On screen `FloatingLegend` renders the result
+ * and the export flattens it through `legendEntries`, so the two cannot
+ * describe different colors.
+ *
+ * A lone scale names itself: section titles draw only beside other sections,
+ * so a lone categorical scale's title becomes the box's (a field's name over
+ * its values) and a lone ramp's goes on its row. Empty scales are
+ * dropped first, so one waiting for data does not leave its sibling untitled.
+ */
+export function legendSpecOf(scales) {
+    const drawn = scales.filter(scale => !colorScaleIsEmpty(scale));
+    const lone = drawn.length === 1 ? drawn[0] : undefined;
+    return {
+        title: lone?.kind === 'categorical' ? lone.title : undefined,
+        sections: drawn.map(scale => sectionOf(scale, lone !== undefined)),
+    };
+}
+/**
+ * The no-value row goes after every value a `domain` orders: the domain never
+ * lists it, so ordering by the domain alone ranks it with the values the
+ * domain leaves out.
+ */
+export function missingRowLast(a, b) {
+    return Number(a.missing ?? false) - Number(b.missing ?? false);
+}
+/** Whether a scale has anything for a key to show. */
+export function colorScaleIsEmpty(scale) {
+    return scale.kind === 'categorical' && scale.entries.length === 0;
+}

package/esm/ui/colorSwatchStyle.d.ts

@@ -0,0 +1,9 @@
+export declare const swatchStyle: {
+    readonly width: 24;
+    readonly height: 24;
+    readonly margin: 4;
+    readonly border: 'none';
+    readonly padding: 0;
+    readonly cursor: 'pointer';
+    readonly outline: 'none';
+};