@jbrowse/app-core 4.3.0 → 5.0.0-beta.1

package/esm/WorkspaceLayout/spec.js

@@ -0,0 +1,153 @@
+import { normalize } from './tree.js';
+/**
+ * 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.
+ */
+function resolveSizes(children) {
+    const stated = children.map(child => child.size);
+    const named = stated.filter(size => size !== undefined);
+    if (named.length === 0 || named.length === children.length) {
+        return stated.map(size => size ?? 1);
+    }
+    const claimed = named.reduce((a, b) => a + b, 0);
+    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
+            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.viewIds) {
+            return {
+                id: nextId('panel'),
+                size,
+                tabs: [{ id: nextId('tab'), viewIds: [...node.viewIds] }],
+                activeTabId: undefined,
+            };
+        }
+        const children = node.children ?? [];
+        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.
+        if (node.direction === 'tabs') {
+            const tabs = children.flatMap(child => {
+                const viewIds = viewIdsInSpec(child);
+                return child.viewIds === undefined && viewIds.length === 0
+                    ? []
+                    : [{ id: nextId('tab'), viewIds }];
+            });
+            return {
+                id: nextId('panel'),
+                size,
+                tabs,
+                activeTabId: tabs[0]?.id,
+            };
+        }
+        const sizes = resolveSizes(children);
+        const built = children.flatMap((child, i) => {
+            const subtree = build(child, sizes[i]);
+            return subtree ? [subtree] : [];
+        });
+        return built.length === 0
+            ? undefined
+            : {
+                id: nextId('branch'),
+                size,
+                direction: node.direction === 'vertical' ? 'column' : 'row',
+                children: built,
+            };
+    }
+    const root = build(spec, spec.size ?? 1);
+    return root ? normalize(root) : { id: nextId('panel'), size: 1, tabs: [] };
+}
+/** Every viewId a spec names, depth-first — the order it states. */
+export function viewIdsInSpec(spec) {
+    return [
+        ...(spec.viewIds ?? []),
+        ...(spec.children ?? []).flatMap(viewIdsInSpec),
+    ];
+}
+/**
+ * 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.
+ */
+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 { viewIds: [...viewIds] };
+    }
+    const cell = (id) => ({ viewIds: [id] });
+    if (mode !== 'grid') {
+        return { direction: mode, children: viewIds.map(cell) };
+    }
+    const cols = Math.ceil(Math.sqrt(viewIds.length));
+    const rows = [];
+    for (let i = 0; i < viewIds.length; i += cols) {
+        rows.push({
+            direction: 'horizontal',
+            children: viewIds.slice(i, i + cols).map(cell),
+        });
+    }
+    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: [{ viewIds: others }, { viewIds: [move.viewId] }],
+        }
+        : { viewIds: [move.viewId] };
+}

package/esm/WorkspaceLayout/splitter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+export declare function withBoundaryAt(sizes: number[], index: number, position: number, pairPx?: number): number[];

package/esm/WorkspaceLayout/splitter.js

@@ -0,0 +1,37 @@
+/**
+ * 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 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.
+ */
+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
+    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];
+    next[index - 1] = before;
+    next[index] = pair - before;
+    return next;
+}

package/esm/WorkspaceLayout/tree.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+export interface TabNode {
+    id: string;
+    /** membership only — `session.views` is the order (see WorkspaceLayout/CLAUDE.md) */
+    viewIds: string[];
+    /** set only when the user renames it; otherwise derived from the views */
+    title?: string;
+}
+/** A cell of the grid: the space a tab strip and one visible tab live in. */
+export interface PanelNode {
+    id: string;
+    /** share of the parent branch's space, relative to its siblings */
+    size: number;
+    tabs: TabNode[];
+    activeTabId?: string;
+}
+export interface BranchNode {
+    id: string;
+    size: number;
+    direction: 'row' | 'column';
+    children: LayoutTree[];
+}
+export type LayoutTree = PanelNode | BranchNode;
+/** What an id is being minted for. Ids are prefixed with it, so they read. */
+export type NodeKind = 'panel' | 'tab' | 'branch';
+export declare function isBranch(node: LayoutTree): node is BranchNode;
+export declare function panels(node: LayoutTree): PanelNode[];
+export declare function tabs(node: LayoutTree): TabNode[];
+/** A tab and the panel holding it — there are no parent pointers to walk. */
+export interface TabHome {
+    panel: PanelNode;
+    tab: TabNode;
+}
+export declare function findTab(node: LayoutTree, tabId: string): TabHome | undefined;
+/** The tab a panel is showing: the one it names, or its first. */
+export declare function activeTabIn(panel: PanelNode): TabNode | undefined;
+export declare function tabContainingView(node: LayoutTree, viewId: string): TabHome | undefined;
+export declare function panelContainingView(node: LayoutTree, viewId: string): PanelNode | undefined;
+/**
+ * Put a tree back in canonical form. Four rules, applied bottom-up:
+ *
+ * 1. a branch with no children is dropped by its parent
+ * 2. a branch with one child is replaced by that child, which inherits the
+ *    branch's size — so the space the branch occupied does not move
+ * 3. a branch directly inside a branch of the same direction is flattened into
+ *    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.
+ */
+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.
+ */
+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. */
+export declare function removePanel(root: LayoutTree, panelId: string): LayoutTree;
+/** Set the sizes of one branch's children, e.g. from a splitter drag. */
+export declare function setSizes(root: LayoutTree, branchId: string, sizes: number[]): LayoutTree;
+export declare function addTab(root: LayoutTree, panelId: string, tab: TabNode): LayoutTree;
+/**
+ * Close a tab. The panel stays — an empty panel shows the view launcher, which
+ * is a state the user can reach deliberately.
+ */
+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.
+ *
+ * **`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.
+ */
+export declare function moveTabToPanel(root: LayoutTree, tabId: string, targetPanelId: string, index?: number): LayoutTree;
+export declare function setActiveTab(root: LayoutTree, panelId: string, tabId: string): LayoutTree;
+export declare function renameTab(root: LayoutTree, tabId: string, title: string | undefined): LayoutTree;
+export declare function addViewToTab(root: LayoutTree, tabId: string, viewId: string): LayoutTree;
+/** 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.
+ */
+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.
+ */
+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.
+ */
+export declare function pruneEmptyTabIn(root: LayoutTree, panelId: string, tabId: string): LayoutTree;