@jbrowse/app-core 5.0.0-beta.10 → 5.0.0-beta.13

package/esm/WorkspaceLayout/panelChrome.d.ts

@@ -1,17 +1,14 @@
 import type { PanelNode, TabNode } from './tree.ts';
-import type { TabDragHandlers } from './useLayoutDrag.ts';
+import type { PointerGestureHandlers } from './usePointerGesture.ts';
 /**
- * The app's half of a panel — what a tab is *called* and what it *contains*.
- *
- * One object rather than five props because every one is forwarded unchanged
- * down the whole recursion, and because one object can be memoised: it reaches
- * every panel, so a fresh one per render re-renders the entire workspace.
+ * The app's half of a panel, as one object so it can be memoised: it reaches
+ * every panel, and a fresh one re-renders the whole workspace.
  */
 export interface PanelChrome {
     renderTabLabel: (tab: TabNode) => React.ReactNode;
     renderTabContent: (tab: TabNode) => React.ReactNode;
     renderPanelActions?: (panel: PanelNode) => React.ReactNode;
-    dragHandlers: TabDragHandlers;
+    dragHandlers: PointerGestureHandlers;
     /** middle-click; the caller pairs it with closing that tab's views */
     onTabClose?: (tabId: string) => void;
 }

package/esm/WorkspaceLayout/panelChrome.js

@@ -1,4 +1,2 @@
-// The tablist wires `aria-controls`/`aria-labelledby` with these, and the strip
-// mints one end of each pair while the tabpanel mints the other.
 export const tabDomId = (tabId) => `jbrowse-tab-${tabId}`;
 export const tabPanelDomId = (panelId) => `jbrowse-tabpanel-${panelId}`;

package/esm/WorkspaceLayout/spec.d.ts

@@ -6,15 +6,10 @@ import type { LayoutTree, NodeKind } from './tree.ts';
  */
 export type LayoutViewRef = number | string;
 /**
- * The `layout` a session spec / URL param states, in the vocabulary users
- * write it in, and the same shape the live `applyLayoutSpec` action takes — one
- * shape, so an agent that has written one has written the other. **This shape
- * is public** — it is documented as a URL parameter — so it keeps
- * `horizontal`/`vertical`/`tabs` and percentage `size` rather than being
- * renamed to match the internal tree.
- *
- * `resolveLayoutSpec` turns the indexes into ids; the tree builder below takes
- * the resolved form only.
+ * The `layout` a session spec or URL param states, and the shape
+ * `applyLayoutSpec` takes. Public, documented as a URL parameter, so it keeps
+ * `horizontal`/`vertical`/`tabs` and percentage `size` rather than the
+ * internal tree's vocabulary.
  */
 export interface LayoutSpecNode<View = LayoutViewRef> {
     /** a leaf: the views to stack vertically in one tab */
@@ -28,20 +23,11 @@ export interface LayoutSpecNode<View = LayoutViewRef> {
 export type ResolvedLayoutSpecNode = LayoutSpecNode<string>;
 /**
  * Resolve every view a spec names to an id against `allViewIds`, the list its
- * indexes count into. Anything that resolves to nothing throws, naming what was
- * received: an untyped caller (the MCP `run_javascript` tool) that writes
- * `viewIds` where `views` goes, or an index past the end, used to be accepted
- * as an empty leaf and collapse the workspace into one blank tab with nothing
- * said.
- *
- * A node stating no `views` and no `children` is NOT that slip — it is the
- * empty panel `treeFromSpec` has always built, and refusing it here made the
- * two surfaces disagree about the one shape they share. The slip is an
- * unrecognized KEY, which is what `viewIds` actually is, and naming it beats
- * the old message that could only say the node needed something else.
+ * indexes count into. An unknown key, index or id throws, naming what was
+ * received, so an untyped caller writing `viewIds` for `views` hears about it.
+ * A node with neither `views` nor `children` is a legal empty panel.
  *
- * `allViewIds` is undefined only on a model that composes no view list, where
- * an id cannot be checked and an index cannot mean anything.
+ * `allViewIds` is undefined only on a model that composes no view list.
  */
 export declare function resolveLayoutSpec(spec: LayoutSpecNode, allViewIds: string[] | undefined): ResolvedLayoutSpecNode;
 /** A request to move one view relative to the others. Public plugin API. */
@@ -49,40 +35,13 @@ export interface PendingMove {
     type: 'newTab' | 'splitRight';
     viewId: string;
 }
-/**
- * Build a layout tree from a spec.
- *
- * The old converter had to answer "which dockview group does a nested split
- * address?" and could not, because dockview forces orientation to alternate by
- * depth — which is why `size` was honoured only on the top-level split, and
- * only if every panel there carried one. Here the spec's nesting is the tree's
- * nesting, so `size` applies wherever it is written and there is no all-or-
- * nothing pass.
- */
 export declare function treeFromSpec(spec: ResolvedLayoutSpecNode, nextId: (kind: NodeKind) => string): LayoutTree;
 /** Every viewId a spec names, depth-first — the order it states. */
 export declare function viewIdsInSpec(spec: ResolvedLayoutSpecNode): string[];
 /** How "arrange everything" lays the whole session out. */
 export type TileMode = 'tabs' | 'horizontal' | 'vertical' | 'grid';
 /**
- * Re-arrange every view at once, one view per cell.
- *
- * The four whole-workspace commands, as a spec. dockview had these as imperative
- * re-tiling — walk every panel and re-add it relative to the first, in an order
- * chosen so the grid came out right — and the grid case had to compute its own
- * row/column arithmetic against `api.panels` because there was no way to state
- * the shape. Here the shape IS the statement, so a tiling is a spec and goes
- * through the same `applyLayoutSpec` a session spec does.
- *
- * `grid` fills row-major at ceil(sqrt(n)) columns, which is what the dockview
- * version computed; a trailing row shorter than the rest keeps its cells at full
- * width, since `resolveSizes` reads bare siblings as an even share of their own
- * branch rather than of the grid.
+ * One view per cell, as a spec. `grid` fills row-major at ceil(sqrt(n))
+ * columns; a short trailing row's cells stretch to full width.
  */
 export declare function tileLayoutSpec(viewIds: string[], mode: TileMode): ResolvedLayoutSpecNode;
-/**
- * `setPendingMove` as a spec: everything else keeps its side, the named view
- * takes the other. With nothing else on screen there is nothing to split from,
- * so the view just takes the space.
- */
-export declare function specForPendingMove(move: PendingMove, allViewIds: string[]): ResolvedLayoutSpecNode;

package/esm/WorkspaceLayout/spec.js

@@ -1,23 +1,12 @@
 import { normalize } from './tree.js';
-// `views`/`children` are pulled off by name; the rest pass through to the tree,
-// so an unrecognized one is a key the writer expected to mean something
 const layoutNodeKeys = new Set(['views', 'direction', 'children', 'size']);
 /**
  * Resolve every view a spec names to an id against `allViewIds`, the list its
- * indexes count into. Anything that resolves to nothing throws, naming what was
- * received: an untyped caller (the MCP `run_javascript` tool) that writes
- * `viewIds` where `views` goes, or an index past the end, used to be accepted
- * as an empty leaf and collapse the workspace into one blank tab with nothing
- * said.
+ * indexes count into. An unknown key, index or id throws, naming what was
+ * received, so an untyped caller writing `viewIds` for `views` hears about it.
+ * A node with neither `views` nor `children` is a legal empty panel.
  *
- * A node stating no `views` and no `children` is NOT that slip — it is the
- * empty panel `treeFromSpec` has always built, and refusing it here made the
- * two surfaces disagree about the one shape they share. The slip is an
- * unrecognized KEY, which is what `viewIds` actually is, and naming it beats
- * the old message that could only say the node needed something else.
- *
- * `allViewIds` is undefined only on a model that composes no view list, where
- * an id cannot be checked and an index cannot mean anything.
+ * `allViewIds` is undefined only on a model that composes no view list.
  */
 export function resolveLayoutSpec(spec, allViewIds) {
     const describe = (value) => typeof value === 'string' ? `"${value}"` : String(value);
@@ -73,22 +62,9 @@ export function resolveLayoutSpec(spec, allViewIds) {
     return resolved;
 }
 /**
- * The effective size of each child of one branch.
- *
- * `size` is documented as a **percentage**, so a spec that sizes some siblings
- * and leaves the rest bare means the rest to share what is left over: `70` and
- * blank is 70/30. Defaulting a bare sibling to 1 instead reads a weight against
- * a percentage, and the panel comes out at 1/71 of the width — present, about a
- * pixel wide, and reported by nothing.
- *
- * The mixed case used to be unreachable: dockview forced orientation to
- * alternate by depth, so the converter discarded any partially-sized branch
- * wholesale and raised a notification saying so. Nesting works now, which means
- * this has to mean something instead.
- *
- * All-sized and none-sized both stay plain weights — `normalize` renormalises
- * them, so `70`/`30` and `7`/`3` are the same layout and neither has to sum to
- * anything in particular.
+ * `size` is a percentage, so bare siblings share what the sized ones leave:
+ * `70` and blank is 70/30, not a 1/71 sliver. All-sized and none-sized stay
+ * plain weights for `normalize`.
  */
 function resolveSizes(children) {
     const stated = children.map(child => child.size);
@@ -100,21 +76,10 @@ function resolveSizes(children) {
     const remainder = 100 - claimed;
     const share = remainder > 0
         ? remainder / (children.length - named.length)
-        : // an over-subscribed branch has nothing left to hand out, so a bare
-            // sibling takes a typical share rather than collapsing to nothing
+        : // over-subscribed: a bare sibling takes an average share
             claimed / named.length;
     return stated.map(size => size ?? share);
 }
-/**
- * Build a layout tree from a spec.
- *
- * The old converter had to answer "which dockview group does a nested split
- * address?" and could not, because dockview forces orientation to alternate by
- * depth — which is why `size` was honoured only on the top-level split, and
- * only if every panel there carried one. Here the spec's nesting is the tree's
- * nesting, so `size` applies wherever it is written and there is no all-or-
- * nothing pass.
- */
 export function treeFromSpec(spec, nextId) {
     function build(node, size) {
         if (node.views) {
@@ -129,14 +94,8 @@ export function treeFromSpec(spec, nextId) {
         if (children.length === 0) {
             return undefined;
         }
-        // `tabs` is not a split: every child's views become a tab in one cell.
-        //
-        // A tab holds a FLAT stack of views, so a container child has no split to
-        // become — and the docs say containers nest arbitrarily deep, so one can be
-        // written. Its views are flattened into a single tab; they used to be
-        // dropped from the layout outright, which is invisible rather than wrong,
-        // since homing then swept them into whichever tab happened to be showing.
-        // `loadSessionSpec` reports the flattening, as it does the sizes below.
+        // every child becomes a tab in one cell; a tab holds a flat stack, so a
+        // container child's views flatten into it (`loadSessionSpec` reports this)
         if (node.direction === 'tabs') {
             const tabs = children.flatMap(child => {
                 const viewIds = viewIdsInSpec(child);
@@ -176,23 +135,10 @@ export function viewIdsInSpec(spec) {
     ];
 }
 /**
- * Re-arrange every view at once, one view per cell.
- *
- * The four whole-workspace commands, as a spec. dockview had these as imperative
- * re-tiling — walk every panel and re-add it relative to the first, in an order
- * chosen so the grid came out right — and the grid case had to compute its own
- * row/column arithmetic against `api.panels` because there was no way to state
- * the shape. Here the shape IS the statement, so a tiling is a spec and goes
- * through the same `applyLayoutSpec` a session spec does.
- *
- * `grid` fills row-major at ceil(sqrt(n)) columns, which is what the dockview
- * version computed; a trailing row shorter than the rest keeps its cells at full
- * width, since `resolveSizes` reads bare siblings as an even share of their own
- * branch rather than of the grid.
+ * One view per cell, as a spec. `grid` fills row-major at ceil(sqrt(n))
+ * columns; a short trailing row's cells stretch to full width.
  */
 export function tileLayoutSpec(viewIds, mode) {
-    // Nothing to arrange: one view is the whole workspace whatever the mode, and
-    // no views leaves the empty panel the tree already guarantees.
     if (viewIds.length <= 1) {
         return { views: [...viewIds] };
     }
@@ -210,17 +156,3 @@ export function tileLayoutSpec(viewIds, mode) {
     }
     return { direction: 'vertical', children: rows };
 }
-/**
- * `setPendingMove` as a spec: everything else keeps its side, the named view
- * takes the other. With nothing else on screen there is nothing to split from,
- * so the view just takes the space.
- */
-export function specForPendingMove(move, allViewIds) {
-    const others = allViewIds.filter(id => id !== move.viewId);
-    return others.length > 0
-        ? {
-            direction: move.type === 'splitRight' ? 'horizontal' : 'tabs',
-            children: [{ views: others }, { views: [move.viewId] }],
-        }
-        : { views: [move.viewId] };
-}

package/esm/WorkspaceLayout/splitter.d.ts

@@ -1,25 +1,9 @@
-/**
- * Moving the boundary between two panes: pure, so it is checkable without a DOM
- * or a synthetic pointer. The handle in `LayoutRenderer.tsx` only measures.
- */
-/**
- * A pane never shrinks below this many pixels.
- *
- * dockview's `MINIMUM_DOCKVIEW_GROUP_PANEL_WIDTH`/`_HEIGHT`. A `flex-grow`
- * share of zero is legal, so without it a pane can be dragged — or `Home`'d —
- * to nothing, taking its tab strip and views with it.
- */
 export declare const MIN_PANE_PX = 100;
 /** The space the two panes either side of the boundary before `index` share. */
 export declare function pairSpan(sizes: number[], index: number): number;
 /**
- * `sizes` with that boundary moved to `position`, measured in the same units.
- *
- * The move stays inside the pair, so every other pane holds still. The pointer
- * and the arrow keys are the same gesture at two resolutions and both land here.
- *
- * `pairPx` is the pair's current pixel span, needed only to convert
- * `MIN_PANE_PX` into a share; 0 means nothing measurable (jsdom, or a pane not
- * laid out yet) and gives the unconstrained clamp.
+ * `sizes` with that boundary moved to `position`, in the same units; other
+ * panes hold still. `pairPx` converts `MIN_PANE_PX` to a share; 0 (jsdom, or
+ * not laid out) skips the minimum.
  */
 export declare function withBoundaryAt(sizes: number[], index: number, position: number, pairPx?: number): number[];

package/esm/WorkspaceLayout/splitter.js

@@ -1,33 +1,17 @@
-/**
- * Moving the boundary between two panes: pure, so it is checkable without a DOM
- * or a synthetic pointer. The handle in `LayoutRenderer.tsx` only measures.
- */
-/**
- * A pane never shrinks below this many pixels.
- *
- * dockview's `MINIMUM_DOCKVIEW_GROUP_PANEL_WIDTH`/`_HEIGHT`. A `flex-grow`
- * share of zero is legal, so without it a pane can be dragged — or `Home`'d —
- * to nothing, taking its tab strip and views with it.
- */
+// a `flex-grow` share of zero is legal, so this keeps a pane from vanishing
 export const MIN_PANE_PX = 100;
 /** The space the two panes either side of the boundary before `index` share. */
 export function pairSpan(sizes, index) {
     return sizes[index - 1] + sizes[index];
 }
 /**
- * `sizes` with that boundary moved to `position`, measured in the same units.
- *
- * The move stays inside the pair, so every other pane holds still. The pointer
- * and the arrow keys are the same gesture at two resolutions and both land here.
- *
- * `pairPx` is the pair's current pixel span, needed only to convert
- * `MIN_PANE_PX` into a share; 0 means nothing measurable (jsdom, or a pane not
- * laid out yet) and gives the unconstrained clamp.
+ * `sizes` with that boundary moved to `position`, in the same units; other
+ * panes hold still. `pairPx` converts `MIN_PANE_PX` to a share; 0 (jsdom, or
+ * not laid out) skips the minimum.
  */
 export function withBoundaryAt(sizes, index, position, pairPx = 0) {
     const pair = pairSpan(sizes, index);
-    // no room for two minimums: the boundary stops in the middle rather than
-    // pinning both ends past each other
+    // with no room for two minimums the boundary stops in the middle
     const floor = pairPx > 0 ? Math.min((MIN_PANE_PX / pairPx) * pair, pair / 2) : 0;
     const before = Math.min(Math.max(position, floor), pair - floor);
     const next = [...sizes];

package/esm/WorkspaceLayout/tabName.d.ts

@@ -0,0 +1,8 @@
+import type { TabNode } from './tree.ts';
+import type { AbstractViewModel } from '@jbrowse/core/util';
+/** A tab's name: the user's title if it has one, else derived from its views */
+export declare function tabDisplayName(tab: TabNode, views: AbstractViewModel[], session: {
+    assemblyManager: {
+        getDisplayName: (name: string) => string;
+    };
+}): string;

package/esm/WorkspaceLayout/tabName.js

@@ -0,0 +1,14 @@
+import { viewName } from '../ui/App/viewTitle.js';
+/** A tab's name: the user's title if it has one, else derived from its views */
+export function tabDisplayName(tab, views, session) {
+    if (tab.title) {
+        return tab.title;
+    }
+    if (views.length === 0) {
+        return 'Empty';
+    }
+    if (views.length === 1) {
+        return viewName(views[0], r => session.assemblyManager.getDisplayName(r));
+    }
+    return `${views.length} views`;
+}

package/esm/WorkspaceLayout/tree.d.ts

@@ -1,24 +1,9 @@
 /**
- * The layout tree, as pure functions over plain snapshots.
- *
- * This is the half of an MST-native workspace that carries the risk, so it is
- * deliberately not MST: no nodes, no parents, no lifecycle, nothing to be alive
- * or dead. Every operation is `tree in -> tree out`, which means the invariants
- * below can be tested exhaustively instead of observed to hold.
- *
- * The trade being made is worth naming, because it is not "complexity for no
- * complexity". Reconciling with dockview is replaced by **normalisation**: a
- * tree that has just had a panel removed, or a branch split, is usually not in
- * canonical form, and every operation has to put it back. That is real work and
- * it is where this design's bugs would live. What it is not is timing: there is
- * no event, no re-entrancy, no window during which the tree is half-updated,
- * and no second owner to disagree with.
- */
-/**
- * One tab. Its content is a **vertical stack of views**, which is JBrowse's own
- * concept and the reason a generic window manager never fits cleanly: dockview
- * has a group holding tabs, and we need a third level under that.
+ * The layout tree as pure functions over plain snapshots, deliberately not MST
+ * so its invariants can be tested exhaustively. Every operation returns a tree
+ * in canonical form (`normalize`).
  */
+/** One tab: a vertical stack of views. */
 export interface TabNode {
     id: string;
     /** membership only — `session.views` is the order (see WorkspaceLayout/CLAUDE.md) */
@@ -66,23 +51,13 @@ export declare function panelContainingView(node: LayoutTree, viewId: string): P
  *    it, its children's sizes scaled to preserve their share of the whole
  * 4. sizes are renormalised so a node's siblings always sum to 1
  *
- * Rule 3 is the one dockview cannot express: it forces orientation to alternate
- * by depth, so `row` inside `row` is not representable and a nested split gets
- * silently reparented. Here it is representable AND canonicalised, which is
- * what makes `size` work at any depth rather than only on the top-level split.
- *
- * Empty panels are NOT dropped, and neither are empty tabs. A tab with no views
- * is exactly what "new empty tab" creates — it shows the view launcher — so
- * pruning empties wholesale would delete the thing the user just asked for.
+ * Empty panels and empty tabs stay: "new empty tab" creates one on purpose, to
+ * show the view launcher.
  */
 export declare function normalize(node: LayoutTree): LayoutTree;
 /**
- * Split `panelId`, putting `newPanel` beside it in `direction`.
- *
- * Always builds a branch around the panel and lets `normalize` flatten it into
- * the parent when the directions agree. Trying to decide up front whether to
- * nest or to insert as a sibling is the same decision rule twice, and the two
- * copies drift.
+ * Split `panelId`, putting `newPanel` beside it in `direction`. Always wraps
+ * the panel in a branch and lets `normalize` flatten it when directions agree.
  */
 export declare function splitPanel(root: LayoutTree, panelId: string, direction: 'row' | 'column', newPanel: PanelNode, before?: boolean): LayoutTree;
 /** Drop a panel. Its space goes back to its siblings via renormalisation. */
@@ -96,25 +71,11 @@ export declare function addTab(root: LayoutTree, panelId: string, tab: TabNode):
  */
 export declare function removeTab(root: LayoutTree, tabId: string): LayoutTree;
 /**
- * Move a tab into another panel, at `index` if given.
- *
- * One function returning one tree, so there is no instant at which the tab is
- * in both panels or neither — the state the imperative bridge had to wrap an
- * explicit `runInAction` around to hide from its own reconcile autorun.
+ * Move a tab into another panel, at `index` if given, or append.
  *
- * **`index` counts the tabs as they are ordered NOW**, before the move. That is
- * the only reading a caller can supply, because it is the strip the user is
- * looking at — and it differs from the post-removal ordering exactly when the
- * tab is moving within its own panel and is currently to the LEFT of the gap it
- * was dropped in. Dragging A to the gap between B and C in `[A, B, C]` is index
- * 2 on screen; taking A out first makes that gap index 1, and inserting at 2
- * lands it after C instead. Adjusting here rather than in the caller keeps the
- * whole "remove then insert" mechanic inside the one function that does it.
- *
- * dockview reaches the same rule from the other end and it is worth knowing
- * they agree, since this is the fiddliest arithmetic in the file: its tabs
- * container computes `insertionIndex - (sourceIndex !== -1 && sourceIndex <
- * insertionIndex ? 1 : 0)`, which is the condition below with the same bounds.
+ * `index` counts the strip the user sees, before the move. Within one panel a
+ * tab left of the gap shifts it by one once removed: dragging A between B and C
+ * in `[A, B, C]` is index 2 on screen but 1 after A comes out.
  */
 export declare function moveTabToPanel(root: LayoutTree, tabId: string, targetPanelId: string, index?: number): LayoutTree;
 export declare function setActiveTab(root: LayoutTree, panelId: string, tabId: string): LayoutTree;
@@ -123,36 +84,18 @@ export declare function addViewToTab(root: LayoutTree, tabId: string, viewId: st
 /** Take a view out of whatever tab holds it, leaving the tab in place. */
 export declare function removeView(root: LayoutTree, viewId: string): LayoutTree;
 /**
- * Make the tree's membership agree with the session's list of views.
- *
- * The only reconciliation left, and one-directional: `session.views` owns which
- * views exist, and nothing reads back.
- *
- * **`viewIds` is the session's WHOLE set.** A shorter list does not leave the
- * rest alone — it unhomes them, and the next homing pass sweeps them into one
- * tab.
+ * Make the tree's membership agree with `session.views`, which owns which views
+ * exist. `viewIds` is the WHOLE set: a shorter list unhomes the rest.
  */
 export declare function homeViews(root: LayoutTree, viewIds: string[], activePanelId: string | undefined, nextTabId: () => string): LayoutTree;
 /**
- * Drop a panel that has been left with no tabs, unless it is the only one.
- *
- * Deliberately NOT a normalisation rule. A panel with no tabs is reachable on
- * purpose, so pruning empties wholesale would delete a space the user asked
- * for. It is a step the *drag* gesture takes about its own source panel,
- * because dragging the last tab out of a split and leaving a blank half is the
- * one place an empty panel is clearly not what was meant.
+ * Drop a panel left with no tabs, unless it is the only one. Not a
+ * normalisation rule: only the gesture that emptied the panel calls it.
  */
 export declare function pruneEmptyPanel(root: LayoutTree, panelId: string): LayoutTree;
 /**
- * Drop a tab that a move has left with no views, unless it is the panel's last.
- *
- * The mirror of `pruneEmptyPanel`, and deliberately as narrow: an empty tab is
- * legitimate (it shows the view launcher), so this only ever runs on the tab a
- * move just emptied, never as a rule over the tree.
- *
- * Which is why closing a tab's last VIEW leaves the tab standing where a move
- * out of it does not: the move acted somewhere else and left this behind, and
- * the close acted here, where an empty tab is a usable place to open the next
- * thing. A cell's last tab prunes because a blank cell is not usable.
+ * Drop a tab a move has left with no views, unless it is the panel's last.
+ * Closing a tab's last view leaves the tab standing, as a place to open the
+ * next one; only a move out of it prunes.
  */
 export declare function pruneEmptyTabIn(root: LayoutTree, panelId: string, tabId: string): LayoutTree;