@jbrowse/core 5.0.0-beta.7 → 5.0.0-beta.9

package/esm/util/translateTranscript.d.ts

@@ -0,0 +1,44 @@
+import type { TranslExcept } from './geneticCodes.ts';
+import type { Feature } from './simpleFeature.ts';
+export interface CdsSegment {
+    start: number;
+    end: number;
+    phase: number;
+}
+/**
+ * A transcript's CDS segments in genome coordinates, sorted and deduplicated. A
+ * GFF3 file can repeat a CDS row, and the duplicated bases would stitch into
+ * the translation and frameshift the protein. A standalone polyprotein CDS
+ * carries cleavage products rather than CDS children, so its own span is the
+ * one segment.
+ */
+export declare function transcriptCDS(transcript: Feature): CdsSegment[];
+/**
+ * The genetic code a transcript translates with: a `transl_table` on it or on
+ * its CDS, else the assembly's code for its contig, else undefined for the
+ * standard code.
+ */
+export declare function transcriptGeneticCodeId(transcript: Feature, assemblyGeneticCodeId?: number): number | undefined;
+/**
+ * A transcript's `transl_except` overrides (RefSeq's selenocysteines), read off
+ * the CDS by NCBI convention or the transcript itself, in the transcript-
+ * relative, strand-corrected frame `translateTranscript` translates in.
+ */
+export declare function transcriptTranslExcept(transcript: Feature): TranslExcept[] | undefined;
+/**
+ * A transcript's protein as JBrowse shows it: its CDS stitched in order, read
+ * with its genetic code and that code's alternative initiators, with any
+ * `transl_except` applied. `seq` is the genome under the transcript, its start
+ * to its end. Undefined for a transcript with no CDS. `cds` and `translExcept`
+ * are the transcript-relative, strand-corrected frame the protein was read in,
+ * for a caller placing residues back on it.
+ */
+export declare function translateTranscript({ transcript, seq, assemblyGeneticCodeId, }: {
+    transcript: Feature;
+    seq: string;
+    assemblyGeneticCodeId?: number;
+}): {
+    protein: string;
+    cds: CdsSegment[];
+    translExcept?: TranslExcept[];
+} | undefined;

package/esm/util/translateTranscript.js

@@ -0,0 +1,102 @@
+import { convertCodingSequenceToPeptides } from './convertCodingSequenceToPeptides.js';
+import { getGeneticCode, parseTranslTable, relativizeTranslExcept, } from './geneticCodes.js';
+import { revlist } from './revlist.js';
+import { revcom } from './seqUtils.js';
+function isCDS(feature) {
+    return feature.get('type')?.toLowerCase() === 'cds';
+}
+function subfeatures(feature) {
+    return feature.get('subfeatures') ?? [];
+}
+/**
+ * A transcript's CDS segments in genome coordinates, sorted and deduplicated. A
+ * GFF3 file can repeat a CDS row, and the duplicated bases would stitch into
+ * the translation and frameshift the protein. A standalone polyprotein CDS
+ * carries cleavage products rather than CDS children, so its own span is the
+ * one segment.
+ */
+export function transcriptCDS(transcript) {
+    const seen = new Set();
+    const cds = [];
+    const sorted = subfeatures(transcript).toSorted((a, b) => a.get('start') - b.get('start'));
+    for (const sub of sorted) {
+        const start = sub.get('start');
+        const end = sub.get('end');
+        const key = `${start}-${end}`;
+        if (isCDS(sub) && start < end && !seen.has(key)) {
+            seen.add(key);
+            cds.push({ start, end, phase: sub.get('phase') ?? 0 });
+        }
+    }
+    if (cds.length === 0 && isCDS(transcript)) {
+        const start = transcript.get('start');
+        const end = transcript.get('end');
+        if (start < end) {
+            cds.push({ start, end, phase: transcript.get('phase') ?? 0 });
+        }
+    }
+    return cds;
+}
+/**
+ * The genetic code a transcript translates with: a `transl_table` on it or on
+ * its CDS, else the assembly's code for its contig, else undefined for the
+ * standard code.
+ */
+export function transcriptGeneticCodeId(transcript, assemblyGeneticCodeId) {
+    const cds = subfeatures(transcript).find(isCDS);
+    return (parseTranslTable(transcript.get('transl_table')) ??
+        parseTranslTable(cds?.get('transl_table')) ??
+        assemblyGeneticCodeId);
+}
+/**
+ * A transcript's `transl_except` overrides (RefSeq's selenocysteines), read off
+ * the CDS by NCBI convention or the transcript itself, in the transcript-
+ * relative, strand-corrected frame `translateTranscript` translates in.
+ */
+export function transcriptTranslExcept(transcript) {
+    const cds = subfeatures(transcript).find(isCDS);
+    const raw = transcript.get('transl_except') ?? cds?.get('transl_except');
+    const start = transcript.get('start');
+    return raw
+        ? relativizeTranslExcept({
+            raw,
+            featureStart: start,
+            featureLength: transcript.get('end') - start,
+            strand: transcript.get('strand'),
+        })
+        : undefined;
+}
+/**
+ * A transcript's protein as JBrowse shows it: its CDS stitched in order, read
+ * with its genetic code and that code's alternative initiators, with any
+ * `transl_except` applied. `seq` is the genome under the transcript, its start
+ * to its end. Undefined for a transcript with no CDS. `cds` and `translExcept`
+ * are the transcript-relative, strand-corrected frame the protein was read in,
+ * for a caller placing residues back on it.
+ */
+export function translateTranscript({ transcript, seq, assemblyGeneticCodeId, }) {
+    const start = transcript.get('start');
+    const relative = transcriptCDS(transcript).map(c => ({
+        ...c,
+        start: c.start - start,
+        end: c.end - start,
+    }));
+    if (relative.length === 0) {
+        return undefined;
+    }
+    const minus = transcript.get('strand') === -1;
+    const cds = minus ? revlist(relative, seq.length) : relative;
+    const translExcept = transcriptTranslExcept(transcript);
+    const { codonTable, starts } = getGeneticCode(transcriptGeneticCodeId(transcript, assemblyGeneticCodeId));
+    return {
+        protein: convertCodingSequenceToPeptides({
+            cds,
+            sequence: minus ? revcom(seq) : seq,
+            codonTable,
+            starts,
+            translExcept,
+        }),
+        cds,
+        translExcept,
+    };
+}

package/esm/util/types/index.d.ts

@@ -1,10 +1,11 @@
 import type { ViewSnapshotInput } from '../../PluginManager.ts';
 import type TextSearchManager from '../../TextSearch/TextSearchManager.ts';
 import type { AnyConfigurationModel } from '../../configuration/index.ts';
-import type { BaseInternetAccountModel } from '../../pluggableElementTypes/models/index.ts';
+import type { BaseInternetAccountModel, BaseTrackConfig } from '../../pluggableElementTypes/models/index.ts';
 import type { PluginDefinition } from '../../pluginDefinitions.ts';
 import type RpcManager from '../../rpc/RpcManager.ts';
 import type { MenuItem } from '../../ui/index.ts';
+import type { HighlightType } from '../highlights.ts';
 import type { Feature } from '../simpleFeature.ts';
 import type { TrackConfigChange } from '../trackConfigDelta.ts';
 import type { UriLocation } from './data.ts';
@@ -66,6 +67,7 @@ export interface AbstractSessionModel extends AbstractViewContainer, RenderingSe
     jbrowse: IAnyStateTreeNode;
     drawerPosition?: DrawerPosition;
     stickyViewHeaders?: boolean;
+    viewTitleBars?: boolean;
     configuration: AnyConfigurationModel;
     rpcManager: RpcManager;
     assemblyNames: string[];
@@ -75,9 +77,13 @@ export interface AbstractSessionModel extends AbstractViewContainer, RenderingSe
     theme: Theme;
     animationMode: AnimationMode;
     scrollZoom: boolean;
+    highlights: readonly HighlightType[];
+    addHighlight: (highlight: HighlightType) => void;
+    removeHighlight: (highlight: HighlightType) => void;
+    updateHighlight: (old: HighlightType, updates: Partial<HighlightType>) => void;
+    setHighlights: (highlights: HighlightType[]) => void;
     highlightsVisible: boolean;
     setHighlightsVisible: (arg: boolean) => void;
-    revealHighlights: () => void;
     getPreference: (key: string) => unknown;
     setPreferenceOverride: (key: string, value: unknown) => void;
     clearPreferenceOverrides: () => void;
@@ -101,11 +107,11 @@ export interface AbstractSessionModel extends AbstractViewContainer, RenderingSe
     version: string;
     gitCommit?: string;
     getTrackActionMenuItems?: (arg: {
-        config: AnyConfigurationModel;
+        config: BaseTrackConfig;
         view?: TrackActionView;
     }) => MenuItem[];
-    getTrackActions?: (arg: AnyConfigurationModel, view?: TrackActionView) => MenuItem[];
-    getTrackListMenuItems?: (arg: AnyConfigurationModel, view?: TrackActionView) => MenuItem[];
+    getTrackActions?: (arg: BaseTrackConfig, view?: TrackActionView) => MenuItem[];
+    getTrackListMenuItems?: (arg: BaseTrackConfig, view?: TrackActionView) => MenuItem[];
     addAssembly?: (conf: Record<string, unknown>) => void;
     addSessionAssembly?: (conf: Record<string, unknown>) => void;
     sessionAssemblies?: AnyConfigurationModel[];
@@ -310,6 +316,9 @@ export interface SessionWithWidgets extends AbstractSessionModel {
     addWidget(typeName: string, id: string, initialState?: Record<string, unknown>, configuration?: {
         type: string;
     }): Widget;
+    openWidget(typeName: string, id: string, initialState?: Record<string, unknown>, configuration?: {
+        type: string;
+    }): Widget;
     showWidget(widget: unknown): void;
     hideWidget(widget: unknown): void;
 }
@@ -463,10 +472,13 @@ export interface AbstractViewModel {
     /**
      * The same, counting the views this one is nested inside — a synteny row has
      * no container of its own to write `bodyMounted`, so that flag alone reads
-     * `true` for a row whose whole stack is off screen. This is what a display's
+     * `true` for a row whose whole stack is off screen — and false while the body
+     * renders none of its displays (`rendersDisplays`). This is what a display's
      * phase asks.
      */
     effectiveBodyMounted: boolean;
+    /** See `BaseViewModel.rendersDisplays`. */
+    rendersDisplays: boolean;
     setWidth(width: number): void;
     setBodyMounted(flag: boolean): void;
     setMinimized(flag: boolean): void;
@@ -517,7 +529,7 @@ type Display = {
 export interface AbstractTrackModel {
     id: string;
     displays: AbstractDisplayModel[];
-    configuration: AnyConfigurationModel & {
+    configuration: BaseTrackConfig & {
         displays: Display[];
     };
     minimized: boolean;

package/esm/util/types/services.d.ts

@@ -38,7 +38,7 @@ export type DialogComponentType = React.LazyExoticComponent<React.FC<any>> | Rea
  * dialog. It is the most-called session member from plugin code (49 sites), and
  * nearly all of them are a display saying "the user wants to configure
  * something" — so a host drawing its own UI needs exactly this one name, not a
- * session. `agent-docs/ideas/lightweight-toolkit.md` §3.
+ * session. `agent-docs/ideas/waiting-on-a-call/lightweight-toolkit.md` §3.
  */
 export interface DialogHost {
     DialogComponent?: DialogComponentType;

package/esm/util/unknownSnapshotKeys.d.ts

@@ -8,6 +8,21 @@ export declare function viewLabel(self: IStateTreeNode): string;
  * a typo reads the same whether it was written in a config or in a URL.
  */
 export declare function unknownKeysMessage(label: string, keys: string[]): string;
+/** Why a settings key `applyDisplaySettings` was handed wrote nothing. */
+export type UnappliedReason = 'no-slot' | 'setter-only' | 'display-type';
+export interface UnappliedSetting {
+    key: string;
+    reason: UnappliedReason;
+}
+/** The action `setter-only` names: `height` -> `setHeight`. */
+export declare function displaySetterName(key: string): string;
+/**
+ * What a surface calls a key the display has an action for but no slot. Its own
+ * sentence rather than `unknownKeysMessage`'s: the display does take the
+ * setting, just not written this way, and saying "unknown key" over a key whose
+ * setter we name in the same breath contradicts itself.
+ */
+export declare function setterOnlyMessage(label: string, keys: string[]): string;
 /**
  * Name the keys a view was handed and could not place, from the partition
  * `withLaunchInput` runs on the snapshot.

package/esm/util/unknownSnapshotKeys.js

@@ -13,6 +13,19 @@ export function viewLabel(self) {
 export function unknownKeysMessage(label, keys) {
     return `${label} ignored unknown key(s): ${keys.join(', ')}`;
 }
+/** The action `setter-only` names: `height` -> `setHeight`. */
+export function displaySetterName(key) {
+    return `set${key[0].toUpperCase()}${key.slice(1)}`;
+}
+/**
+ * What a surface calls a key the display has an action for but no slot. Its own
+ * sentence rather than `unknownKeysMessage`'s: the display does take the
+ * setting, just not written this way, and saying "unknown key" over a key whose
+ * setter we name in the same breath contradicts itself.
+ */
+export function setterOnlyMessage(label, keys) {
+    return `${label} did not apply ${keys.join(', ')}: no config slot takes ${keys.length > 1 ? 'them' : 'it'}. Call ${keys.map(displaySetterName).join(', ')} on the display instead.`;
+}
 /**
  * Name the keys a view was handed and could not place, from the partition
  * `withLaunchInput` runs on the snapshot.

package/esm/util/useFeatureSequence.js

@@ -15,7 +15,7 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
             +forceLoad,
         ]
         : null, guard
-        ? async (_name, _asm, _ref, _start, _end, _upDown, _force, stopToken, statusCallback) => {
+        ? async (_name, _asm, _ref, _start, _end, _upDown, _force, signal, statusCallback) => {
             const { session: s, assemblyName: asmName } = guard;
             if (!forceLoad && end - start > BPLIMIT) {
                 return {
@@ -32,7 +32,7 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
                     refName,
                     assemblyName: asmName,
                     session: s,
-                    stopToken,
+                    signal,
                     statusCallback: slot(),
                 }),
                 upDownBp > 0
@@ -42,7 +42,7 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
                         refName,
                         assemblyName: asmName,
                         session: s,
-                        stopToken,
+                        signal,
                         statusCallback: slot(),
                     })
                     : Promise.resolve(''),
@@ -53,7 +53,7 @@ export function useFeatureSequence({ session, start, end, refName, upDownBp, for
                         refName,
                         assemblyName: asmName,
                         session: s,
-                        stopToken,
+                        signal,
                         statusCallback: slot(),
                     })
                     : Promise.resolve(''),

package/esm/util/useFetch.d.ts

@@ -1,5 +1,4 @@
 import type { RpcStatus, StatusCallback } from './progress.ts';
-import type { StopToken } from './stopToken.ts';
 export type FetchKey = string | readonly unknown[] | null | undefined | false;
 type FetchingKey<Key> = Exclude<Key, null | undefined | false>;
 /**
@@ -10,8 +9,8 @@ type FetchingKey<Key> = Exclude<Key, null | undefined | false>;
  * single argument (`useGenomesData`). Most fetchers close over what they need
  * and declare no parameters at all, which stays assignable either way.
  *
- * A stop token and a status callback follow the key arguments. The token is
- * created per fetch and stopped when the key changes or the component unmounts,
+ * A signal and a status callback follow the key arguments. The signal is
+ * created per fetch and aborted when the key changes or the component unmounts,
  * so a fetcher that forwards it to an RPC cancels the worker instead of leaving
  * it grinding on an answer nobody is waiting for. The callback is what the RPC's
  * own progress comes back through, and it surfaces on the hook's `status` — a
@@ -19,7 +18,7 @@ type FetchingKey<Key> = Exclude<Key, null | undefined | false>;
  * works, instead of a bare spinner over an uninterruptible whole-chromosome
  * read. Fetchers that take neither are unaffected.
  */
-type FetcherArgs<Key> = FetchingKey<Key> extends readonly unknown[] ? [...FetchingKey<Key>, StopToken, StatusCallback] : [FetchingKey<Key>, StopToken, StatusCallback];
+type FetcherArgs<Key> = FetchingKey<Key> extends readonly unknown[] ? [...FetchingKey<Key>, AbortSignal, StatusCallback] : [FetchingKey<Key>, AbortSignal, StatusCallback];
 interface FetchState<Data> {
     data: Data | undefined;
     error: unknown;

package/esm/util/useFetch.js

@@ -1,6 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { createStatusWindow } from './progress.js';
-import { createStopToken, stopStopToken } from './stopToken.js';
 const isNil = (k) => k === null || k === undefined || k === false;
 // A null result means "don't fetch": no key, or an array key with a missing
 // piece (e.g. an offset that isn't resolved yet).
@@ -85,7 +84,7 @@ export function useFetch(key, fetcher, options = {}) {
             // fetch resolved is a different case, and the stream's own `clear` drops
             // that one.)
             let settled = false;
-            const stopToken = createStopToken();
+            const controller = new AbortController();
             // A refetch under the same key — mutate(), or the cross-component
             // mutate(key) — is the same question asked again, so what is on screen is
             // a stale answer to it rather than an answer to something else: leave it
@@ -107,7 +106,7 @@ export function useFetch(key, fetcher, options = {}) {
             setStatus(undefined);
             // The runtime counterpart of FetcherArgs: an array key becomes one
             // argument per element, anything else a single argument, then the stop
-            // token and the status callback. A conditional type over an unresolved
+            // signal and the status callback. A conditional type over an unresolved
             // `Key` can't be discharged
             // inside the function body, so the parameter list is erased for this one
             // call — callers still get the precise arity, and the looseness stops
@@ -127,7 +126,7 @@ export function useFetch(key, fetcher, options = {}) {
             const { statusCallback, clear: clearStatus } = statusWindow.open({
                 isCurrent: () => alive && !settled,
             });
-            const args = [...keyArgs, stopToken, statusCallback];
+            const args = [...keyArgs, controller.signal, statusCallback];
             const call = fetcher;
             Promise.resolve()
                 .then(() => call(...args))
@@ -151,9 +150,9 @@ export function useFetch(key, fetcher, options = {}) {
             });
             return () => {
                 alive = false;
-                // the token's lifetime is this fetch's. An abort rejection lands in the
+                // the signal's lifetime is this fetch's. An abort rejection lands in the
                 // catch above with alive already false, so it never surfaces as an error
-                stopStopToken(stopToken);
+                controller.abort();
                 // and the window's lifetime is too: `alive` already makes a queued
                 // trailing write a no-op, but the timer behind it would otherwise stand
                 // for up to a window past unmount

package/esm/util/usePanelVirtualScroll.d.ts

@@ -1,41 +1,9 @@
-interface PanelScrollTarget {
-    scrollTop: number;
-    scrollableHeight: number;
-    setScrollTop: (n: number) => void;
-}
+import type { VirtualScrollModel } from './useVirtualScrollWheel.ts';
 /**
- * Wheel gestures over a **scrolled canvas panel** — the alignments pileup and
- * the canvas basic display: a plain wheel scrolls it, `shift` keeps scrolling it
- * once `scrollZoom` has claimed the plain wheel for the view, and ctrl/meta is
- * left to the browser and the view's pinch-zoom. Nothing here resizes anything.
- * A sideways-dominant wheel is the view's pan and is declined
- * (`useVirtualScrollWheel`, which says what latching does with that).
- *
- * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
- * DOM overflow container, so nothing scrolls them without this. The latch (inside
- * `applyScroll`) owns `preventDefault` but never `stopPropagation`: the event
- * still reaches the LGV, which reads that flag and declines a gesture this panel
- * has claimed, so a diagonal wheel scrolls the reads without also panning the
- * genome sideways.
- *
- * ADR-027 keeps wheel-*intent* dispatch per handler, because the panels do not
- * agree on what a gesture means. This is the second of the two rules that
- * survived that split — the row-stack rule (`useRowVirtualScroll`, where `shift`
- * resizes) is the other — and the two displays sharing it had byte-identical
- * copies differing only in which getter named the viewport. The canvas display
- * converged here when it moved off a native overflow container; the ADR's table
- * still described its pre-virtual-scroll rule and has been corrected.
- *
- * `scrollZoom` and `viewportHeight` are inputs rather than reads off the model,
- * so core needs no view typing and each display keeps naming its own viewport
- * (the pileup's excludes the sticky coverage band; the canvas display's is the
- * whole track).
- *
- * `panel` is the element wrapping the canvas AND the DOM overlays drawn over it,
- * never the canvas alone — see `useVirtualScrollWheel`, which says why.
+ * Wheel gestures over a **scrolled canvas panel** — the alignments pileup, the
+ * canvas feature display, multi-way synteny: a plain wheel scrolls it, `shift`
+ * still scrolls it once `scrollZoom` has given the plain wheel to the view, and
+ * ctrl/meta is left to the browser and the view's pinch-zoom. The row-stack
+ * rule, where `shift` resizes, is `useRowVirtualScroll` (ADR-027).
  */
-export declare function usePanelVirtualScroll(panel: HTMLElement | null, model: PanelScrollTarget, { viewportHeight, scrollZoom, }: {
-    viewportHeight: number;
-    scrollZoom: boolean;
-}): void;
-export {};
+export declare function usePanelVirtualScroll(panel: HTMLElement | null, model: VirtualScrollModel, scrollZoom: boolean): void;

package/esm/util/usePanelVirtualScroll.js

@@ -1,46 +1,15 @@
 import { useVirtualScrollWheel } from './useVirtualScrollWheel.js';
 /**
- * Wheel gestures over a **scrolled canvas panel** — the alignments pileup and
- * the canvas basic display: a plain wheel scrolls it, `shift` keeps scrolling it
- * once `scrollZoom` has claimed the plain wheel for the view, and ctrl/meta is
- * left to the browser and the view's pinch-zoom. Nothing here resizes anything.
- * A sideways-dominant wheel is the view's pan and is declined
- * (`useVirtualScrollWheel`, which says what latching does with that).
- *
- * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
- * DOM overflow container, so nothing scrolls them without this. The latch (inside
- * `applyScroll`) owns `preventDefault` but never `stopPropagation`: the event
- * still reaches the LGV, which reads that flag and declines a gesture this panel
- * has claimed, so a diagonal wheel scrolls the reads without also panning the
- * genome sideways.
- *
- * ADR-027 keeps wheel-*intent* dispatch per handler, because the panels do not
- * agree on what a gesture means. This is the second of the two rules that
- * survived that split — the row-stack rule (`useRowVirtualScroll`, where `shift`
- * resizes) is the other — and the two displays sharing it had byte-identical
- * copies differing only in which getter named the viewport. The canvas display
- * converged here when it moved off a native overflow container; the ADR's table
- * still described its pre-virtual-scroll rule and has been corrected.
- *
- * `scrollZoom` and `viewportHeight` are inputs rather than reads off the model,
- * so core needs no view typing and each display keeps naming its own viewport
- * (the pileup's excludes the sticky coverage band; the canvas display's is the
- * whole track).
- *
- * `panel` is the element wrapping the canvas AND the DOM overlays drawn over it,
- * never the canvas alone — see `useVirtualScrollWheel`, which says why.
+ * Wheel gestures over a **scrolled canvas panel** — the alignments pileup, the
+ * canvas feature display, multi-way synteny: a plain wheel scrolls it, `shift`
+ * still scrolls it once `scrollZoom` has given the plain wheel to the view, and
+ * ctrl/meta is left to the browser and the view's pinch-zoom. The row-stack
+ * rule, where `shift` resizes, is `useRowVirtualScroll` (ADR-027).
  */
-export function usePanelVirtualScroll(panel, model, { viewportHeight, scrollZoom, }) {
-    useVirtualScrollWheel(panel, (e, applyScroll) => {
-        if ((scrollZoom && !e.shiftKey) || e.ctrlKey || e.metaKey) {
-            return;
+export function usePanelVirtualScroll(panel, model, scrollZoom) {
+    useVirtualScrollWheel(panel, model, (e, scroll) => {
+        if ((!scrollZoom || e.shiftKey) && !e.ctrlKey && !e.metaKey) {
+            scroll();
         }
-        applyScroll(e, {
-            scrollTop: model.scrollTop,
-            viewportHeight,
-            scrollableHeight: model.scrollableHeight,
-        }, n => {
-            model.setScrollTop(n);
-        });
     });
 }

package/esm/util/useRowVirtualScroll.d.ts

@@ -1,32 +1,9 @@
-interface RowScrollTarget {
-    effectiveRowHeight: number;
-    scrollTop: number;
-    nrow: number;
-    scrollableHeight: number;
-    setRowHeight: (n: number) => void;
-    setScrollTop: (n: number) => void;
-}
+import type { RowResizeTarget } from './applyRowResizeWheel.ts';
 /**
  * Wheel gestures over a **row-stack** panel — the multi-sample variant displays
- * and MAF: `shift`+wheel resizes the rows (a vertical-zoom that keeps the row
- * under the cursor put), a plain wheel scrolls them, and anything the panel
- * can't consume — a sideways swipe included — is left to bubble to the view.
- *
- * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
- * DOM overflow container, so nothing scrolls them without this.
- *
- * ADR-027 keeps wheel-*intent* dispatch per handler, because the four panels do
- * not agree on what a gesture means — and that still holds. This is the one rule
- * two of them genuinely share, which the ADR states outright ("same rule as the
- * variant displays, and deliberately so: same sample-row shape, same coupled
- * row-height axis"). It is unified for exactly that reason, and no further: the
- * pileup / canvas-basic rule (`shift` scrolls, nothing resizes) stays where it
- * is. `scrollZoom` and `viewportHeight` are inputs rather than reads off the
- * model, so core needs no view typing and each display keeps naming its own
- * rows-area height.
+ * and MAF: `shift`+wheel resizes the rows, keeping the row under the cursor
+ * put, and a plain wheel scrolls them unless `scrollZoom` gave it to the view.
+ * ctrl/meta is the browser's zoom whatever else is held. The canvas-panel rule,
+ * where `shift` scrolls, is `usePanelVirtualScroll` (ADR-027).
  */
-export declare function useRowVirtualScroll(el: HTMLElement | null, model: RowScrollTarget, { viewportHeight, scrollZoom, }: {
-    viewportHeight: number;
-    scrollZoom: boolean;
-}): void;
-export {};
+export declare function useRowVirtualScroll(el: HTMLElement | null, model: RowResizeTarget, scrollZoom: boolean): void;

package/esm/util/useRowVirtualScroll.js

@@ -2,62 +2,21 @@ import { applyRowResizeWheel } from './applyRowResizeWheel.js';
 import { useVirtualScrollWheel } from './useVirtualScrollWheel.js';
 /**
  * Wheel gestures over a **row-stack** panel — the multi-sample variant displays
- * and MAF: `shift`+wheel resizes the rows (a vertical-zoom that keeps the row
- * under the cursor put), a plain wheel scrolls them, and anything the panel
- * can't consume — a sideways swipe included — is left to bubble to the view.
- *
- * These panels paint a fixed-size canvas at `-scrollTop` rather than living in a
- * DOM overflow container, so nothing scrolls them without this.
- *
- * ADR-027 keeps wheel-*intent* dispatch per handler, because the four panels do
- * not agree on what a gesture means — and that still holds. This is the one rule
- * two of them genuinely share, which the ADR states outright ("same rule as the
- * variant displays, and deliberately so: same sample-row shape, same coupled
- * row-height axis"). It is unified for exactly that reason, and no further: the
- * pileup / canvas-basic rule (`shift` scrolls, nothing resizes) stays where it
- * is. `scrollZoom` and `viewportHeight` are inputs rather than reads off the
- * model, so core needs no view typing and each display keeps naming its own
- * rows-area height.
+ * and MAF: `shift`+wheel resizes the rows, keeping the row under the cursor
+ * put, and a plain wheel scrolls them unless `scrollZoom` gave it to the view.
+ * ctrl/meta is the browser's zoom whatever else is held. The canvas-panel rule,
+ * where `shift` scrolls, is `usePanelVirtualScroll` (ADR-027).
  */
-export function useRowVirtualScroll(el, model, { viewportHeight, scrollZoom, }) {
-    useVirtualScrollWheel(el, (e, applyScroll, rowsEl) => {
-        // ctrl/meta is the browser's own zoom (and the view's pinch-zoom) and is
-        // never ours, whatever else is held. Tested first rather than only in the
-        // scroll branch: ctrl+shift+wheel used to reach the resize below, which
-        // `preventDefault`s — so a row-stack display swallowed page zoom where
-        // every other display passes it through.
+export function useRowVirtualScroll(el, model, scrollZoom) {
+    useVirtualScrollWheel(el, model, (e, scroll, rowsEl) => {
         if (e.ctrlKey || e.metaKey) {
             return;
         }
         if (e.shiftKey) {
-            // Resizing exits fit-to-height into a pinned height, which is what makes
-            // the gesture meaningful: the fit height is exactly the floor it shrinks
-            // to, so there is nothing to zoom while the sentinel is set.
-            applyRowResizeWheel(e, rowsEl, {
-                effectiveRowHeight: model.effectiveRowHeight,
-                scrollTop: model.scrollTop,
-                nrow: model.nrow,
-                viewportHeight,
-                setRowHeight: n => {
-                    model.setRowHeight(n);
-                },
-                setScrollTop: n => {
-                    model.setScrollTop(n);
-                },
-            });
+            applyRowResizeWheel(e, rowsEl, model);
         }
         else if (!scrollZoom) {
-            // A gesture the panel can't consume is left alone: with the rows fitting
-            // the track (`scrollableHeight === 0`, always true in fit-to-height mode)
-            // the wheel reaches the view and zooms or scrolls the page exactly as it
-            // does over any other track. Same for the explicit zoom gestures.
-            applyScroll(e, {
-                scrollTop: model.scrollTop,
-                viewportHeight,
-                scrollableHeight: model.scrollableHeight,
-            }, n => {
-                model.setScrollTop(n);
-            });
+            scroll();
         }
     });
 }

package/esm/util/useVirtualScrollWheel.d.ts

@@ -1,7 +1,23 @@
-export interface VirtualScrollOpts {
+/**
+ * What a virtually scrolled panel reads and writes. `TrackHeightMixin`
+ * implements it, so a display passes itself.
+ */
+export interface VirtualScrollModel {
     scrollTop: number;
-    viewportHeight: number;
+    /** 0 when the content fits; never sub-pixel */
     scrollableHeight: number;
+    scrollViewportHeight: number;
+    setScrollTop: (scrollTop: number) => void;
 }
-export type ApplyVirtualScroll = (e: WheelEvent, opts: VirtualScrollOpts, commit: (scrollTop: number) => void) => void;
-export declare function useVirtualScrollWheel(panel: HTMLElement | null, onWheel: (e: WheelEvent, applyScroll: ApplyVirtualScroll, el: HTMLElement) => void): void;
+/**
+ * Non-passive wheel wiring for a canvas-backed virtual scroll. Owns the scroll
+ * latch (and so `preventDefault`), per-frame coalescing of `setScrollTop`, and
+ * the listener lifecycle. `onWheel` decides what the gesture means and calls
+ * `scroll` when it means scrolling `model`.
+ *
+ * **Bind this to the panel, not to the `<canvas>`.** A canvas holds no DOM
+ * children, so the clickable overlays drawn over it are siblings, and a wheel
+ * over one never reaches a listener on the canvas. Overlays that run their own
+ * gestures opt out with `[data-gesture-owner]`.
+ */
+export declare function useVirtualScrollWheel(panel: HTMLElement | null, model: VirtualScrollModel, onWheel: (e: WheelEvent, scroll: () => void, panel: HTMLElement) => void): void;