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

package/esm/WorkspaceLayout/dropZone.js

@@ -0,0 +1,113 @@
+/**
+ * Where a pointer sitting over a panel would drop a view.
+ *
+ * Kept as geometry over a plain rect rather than reading the DOM, because this
+ * is the part of drag-and-drop with actual decisions in it — the edge band, the
+ * tie-break between two edges, what happens in the middle — and all of it is
+ * checkable without rendering anything or synthesising a pointer.
+ */
+/**
+ * `center` means "add as a tab in this panel"; an edge means "split this panel
+ * and put the view in the new half".
+ *
+ * The bands are proportional rather than a fixed pixel depth so a narrow panel
+ * stays droppable — at a fixed 40px a 100px-wide panel would be all edge and
+ * have no centre to drop a tab into. `edgeFraction` is capped below 0.5 for the
+ * same reason: at 0.5 the centre vanishes entirely.
+ *
+ * Corners go to whichever edge the pointer is proportionally deeper into, so
+ * the diagonal is the tie-break and neither axis silently wins. **This is a
+ * deliberate divergence from dockview**, whose `calculateQuadrantAsPercentage`
+ * tests left, right, top, bottom in that order and returns the first hit — so
+ * in its top-left corner `left` always wins, however far into the top band the
+ * pointer is. Its band is 20% where this defaults to 25%.
+ */
+export function dropZoneAt(rect, x, y, edgeFraction = 0.25) {
+    const fraction = Math.min(Math.max(edgeFraction, 0), 0.49);
+    if (rect.width <= 0 || rect.height <= 0) {
+        return 'center';
+    }
+    // 0 at the left/top edge, 1 at the right/bottom
+    const px = (x - rect.left) / rect.width;
+    const py = (y - rect.top) / rect.height;
+    // how far into an edge band the pointer is, as a share of that band
+    const depths = [
+        { zone: 'left', depth: (fraction - px) / fraction },
+        { zone: 'right', depth: (px - (1 - fraction)) / fraction },
+        { zone: 'top', depth: (fraction - py) / fraction },
+        { zone: 'bottom', depth: (py - (1 - fraction)) / fraction },
+    ].filter(candidate => candidate.depth > 0);
+    if (depths.length === 0) {
+        return 'center';
+    }
+    return depths.reduce((best, candidate) => candidate.depth > best.depth ? candidate : best).zone;
+}
+/**
+ * Which gap between tabs a pointer at `x` is nearest — the insertion index a
+ * drop there would use, and the x to draw the caret at.
+ *
+ * The test is each tab's MIDPOINT rather than its edges, so every x belongs to
+ * exactly one gap and there is no dead band between tabs where a drop would
+ * have to fall back to appending. `rects` are in strip order and `x` is in
+ * their coordinate space, whatever that is — this function does not know
+ * whether it was handed viewport or panel-relative numbers.
+ *
+ * An empty strip is index 0, which is the only sensible place for a first tab.
+ */
+export function stripDropAt(rects, x) {
+    for (const [i, rect] of rects.entries()) {
+        if (x < rect.left + rect.width / 2) {
+            return { index: i, left: rect.left };
+        }
+    }
+    const last = rects.at(-1);
+    return {
+        index: rects.length,
+        left: last ? last.left + last.width : 0,
+    };
+}
+/**
+ * What each zone means, in one table.
+ *
+ * `split` is the split a drop there asks for — which way the panel divides and
+ * whether the new half goes first; `center` is not a split. `rect` is where the
+ * indicator is drawn, as CSS percentages of the panel.
+ *
+ * One table rather than two switches because the pair has to agree: the shaded
+ * half IS the half the drop lands in, and that is the whole content of the
+ * indicator. Written apart, `right` could shade the left half and nothing would
+ * be wrong with either function on its own.
+ */
+const ZONES = {
+    left: {
+        split: { direction: 'row', before: true },
+        rect: { left: '0%', top: '0%', width: '50%', height: '100%' },
+    },
+    right: {
+        split: { direction: 'row', before: false },
+        rect: { left: '50%', top: '0%', width: '50%', height: '100%' },
+    },
+    top: {
+        split: { direction: 'column', before: true },
+        rect: { left: '0%', top: '0%', width: '100%', height: '50%' },
+    },
+    bottom: {
+        split: { direction: 'column', before: false },
+        rect: { left: '0%', top: '50%', width: '100%', height: '50%' },
+    },
+    center: {
+        split: undefined,
+        rect: { left: '0%', top: '0%', width: '100%', height: '100%' },
+    },
+};
+/**
+ * The split a drop on `zone` asks for: which way the panel divides, and whether
+ * the new half goes first. `center` is not a split.
+ */
+export function splitForZone(zone) {
+    return ZONES[zone].split;
+}
+/** Where the drop indicator goes, as CSS percentages of the panel. */
+export function indicatorRect(zone) {
+    return ZONES[zone].rect;
+}

package/esm/WorkspaceLayout/index.d.ts

@@ -0,0 +1,8 @@
+export { WorkspaceLayoutMixin, isSessionWithWorkspaceLayout } from './model.ts';
+export { WorkspaceContainer } from './WorkspaceContainer.tsx';
+export { LayoutRenderer } from './LayoutRenderer.tsx';
+export { useLayoutDrag } from './useLayoutDrag.ts';
+export type { WorkspaceLayoutMixinType, WorkspaceLayout } from './model.ts';
+export type { LayoutTree, PanelNode, TabNode, BranchNode, TabHome, } from './tree.ts';
+export type { LayoutSpecNode, PendingMove, TileMode } from './spec.ts';
+export type { DropZone } from './dropZone.ts';

package/esm/WorkspaceLayout/index.js

@@ -0,0 +1,4 @@
+export { WorkspaceLayoutMixin, isSessionWithWorkspaceLayout } from './model.js';
+export { WorkspaceContainer } from './WorkspaceContainer.js';
+export { LayoutRenderer } from './LayoutRenderer.js';
+export { useLayoutDrag } from './useLayoutDrag.js';

package/esm/WorkspaceLayout/model.d.ts

@@ -0,0 +1,260 @@
+import type { LayoutSpecNode, PendingMove, TileMode } from './spec.ts';
+import type { LayoutTree, PanelNode, TabHome, TabNode } from './tree.ts';
+import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree';
+export declare function WorkspaceLayoutMixin(): import("@jbrowse/mobx-state-tree").IModelType<{
+    layout: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<{
+        id: string;
+        size: number | undefined;
+        tabs: readonly import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            id: string;
+            viewIds: readonly string[] | undefined;
+            title: string | undefined;
+        }>[] | undefined;
+        activeTabId: string | undefined;
+    }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+        id: string;
+        size: number | undefined;
+        direction: "column" | "row";
+        children: readonly import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            id: string;
+            size: number | undefined;
+            tabs: readonly import("@jbrowse/mobx-state-tree").ModelCreationType<{
+                id: string;
+                viewIds: readonly string[] | undefined;
+                title: string | undefined;
+            }>[] | undefined;
+            activeTabId: string | undefined;
+        }>[] | undefined;
+    }>, import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+        id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        size: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
+        tabs: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<{
+            id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            viewIds: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            /** set only by an explicit rename; otherwise the name is derived from views */
+            title: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+        activeTabId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    }> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+        id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        size: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
+        direction: import("@jbrowse/mobx-state-tree").ISimpleType<"column" | "row">;
+        children: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<{
+            id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            size: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
+            tabs: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<{
+                id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+                viewIds: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+                /** set only by an explicit rename; otherwise the name is derived from views */
+                title: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+            activeTabId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+    }>, import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+        id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        size: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
+        tabs: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<{
+            id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            viewIds: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            /** set only by an explicit rename; otherwise the name is derived from views */
+            title: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+        activeTabId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    }> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+        id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        size: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
+        direction: import("@jbrowse/mobx-state-tree").ISimpleType<"column" | "row">;
+        children: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<{
+            id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            size: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<number>, [undefined]>;
+            tabs: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").IModelType<{
+                id: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+                viewIds: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+                /** set only by an explicit rename; otherwise the name is derived from views */
+                title: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+            activeTabId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+    }>>, [undefined]>;
+    activePanelId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    /**
+     * Show only this cell, at the size of the whole workspace.
+     *
+     * Deliberately HERE and not a `maximized` flag on `PanelNode`. On the
+     * node it would be inside `tree.ts`, the half that carries the risk and
+     * is proven by a randomised operation sequence asserting canonical form
+     * after every step — and every operation would then have to say what it
+     * does to the flag: a split of a maximized panel, a drag of its last tab
+     * out, a normalize that collapses it into its parent. Beside
+     * `activePanelId` it is the same class of thing as `activePanelId`,
+     * including its failure mode, which `livePanelIds` already repairs.
+     */
+    maximizedPanelId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+}, {
+    /**
+     * The plain tree the pure functions take.
+     *
+     * `getSnapshot` is a `keepAlive` computed, so this is cached and
+     * referentially stable — which also lets MST's reconcile short-circuit on
+     * identity when `apply` writes an untouched subtree back.
+     *
+     * Uncast on purpose: the models below and the interfaces in `tree.ts` are
+     * two spellings of one shape, and this assignment is the only thing that
+     * checks they agree.
+     */
+    readonly tree: LayoutTree;
+} & {
+    readonly panels: PanelNode[];
+    readonly tabs: TabNode[];
+    hasPanel(panelId: string): boolean;
+    findTab(tabId: string): TabHome | undefined;
+    tabContainingView(viewId: string): TabHome | undefined;
+    panelContainingView(viewId: string): PanelNode | undefined;
+    /** The views a tab renders: its members, in `session.views` order. */
+    viewIdsForTab(tabId: string, order: string[]): string[];
+    /** The tab a panel is showing, or its first. */
+    activeTabOf(panelId: string): TabNode | undefined;
+    /**
+     * What to render: the maximized cell alone, or the whole tree.
+     *
+     * Sized to 1 rather than handed over as it sits. A pane's `size` is its
+     * share of its siblings, and CSS distributes free space by grow factor
+     * only up to a total of 1 — so a cell that was a third of a row, alone
+     * in the workspace with `flexGrow: 0.33`, draws a third of the window
+     * and leaves the rest blank.
+     */
+    readonly visibleTree: LayoutTree;
+} & {
+    setActivePanelId(panelId: string | undefined): void;
+    /**
+     * Show one cell at the size of the workspace, or go back.
+     *
+     * A toggle rather than a pair, because the gesture is a toggle: the
+     * strip's double-click and the cell menu's one item both mean "this
+     * cell, or not any more". Maximizing a DIFFERENT cell while one is
+     * already maximized moves the mode rather than restoring, which is
+     * what the menu item on another cell's strip is asking for.
+     *
+     * Mounts no views that were not mounted — it is the same cell showing
+     * the same tab — and unmounts every other cell's, so the WebGL2
+     * context ceiling (`agent-docs/reference/GPU_CONTEXT_BUDGET.md`) can
+     * only go down. That is the reason it is this and not a `display:
+     * none` over a still-mounted workspace.
+     */
+    toggleMaximizedPanel(panelId: string): void;
+    restorePanels(): void;
+    setActiveTab(panelId: string, tabId: string): void;
+    renameTab(tabId: string, title: string | undefined): void;
+    /** Split a grid cell; the new cell gets one empty tab. */
+    splitPanel(panelId: string, direction: 'row' | 'column', before?: any): PanelNode | undefined;
+    closePanel(panelId: string): void;
+    /** "New empty tab": a tab in an existing cell, showing the launcher. */
+    addTab(panelId: string, viewIds?: string[]): TabNode | undefined;
+    /**
+     * Close a tab, and the cell with it if that was its last.
+     *
+     * A cell whose tabs are all gone is the state `pruneEmptyPanel` was
+     * written for — "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" — and closing that tab arrives at the identical half by a
+     * different gesture. It rendered nothing at all, not even the launcher
+     * an empty TAB shows, so the only way back out of it was the `+`.
+     *
+     * `pruneEmptyPanel` carries both guards already: a cell with tabs left
+     * stays, and the last cell in the workspace stays whatever happens to
+     * it, since there is nowhere for the tree to collapse to.
+     */
+    closeTab(tabId: string): void;
+    addViewToTab(tabId: string, viewId: string): void;
+    /**
+     * Drop a dragged tab into an existing panel, as a tab.
+     *
+     * One action, so the tree never exists in a state where the tab is in
+     * both panels or neither. The imperative bridge needed an explicit
+     * `runInAction` around the unassign+reassign pair for exactly this, and
+     * a comment explaining that without it the reconcile autorun would
+     * observe the gap and re-home the view.
+     */
+    dropTabInPanel(tabId: string, targetPanelId: string, index?: number): void;
+    /** Drop a dragged tab on a panel edge: split, and land in the new half. */
+    dropTabInNewSplit(tabId: string, targetPanelId: string, direction: 'row' | 'column', before: boolean): string | undefined;
+    setSizes(branchId: string, sizes: number[]): void;
+    /**
+     * Arrange the workspace as a spec states.
+     *
+     * The spec is the same shape a session spec's `layout` takes: a leaf's
+     * `views` names views by index into `session.views` or by id, so
+     * `{ direction: 'horizontal', children: [{ views: [0] }, { views: [1] }] }`
+     * means here what it means in a link. A leaf spelled any other way, an
+     * index past the end or an id no view has throws rather than arranging
+     * nothing — an untyped caller used to collapse the workspace into one
+     * blank tab that way.
+     *
+     * There is no `init` property and no standing request: the spec is
+     * converted and *becomes* the layout, here and now. `init` existed only
+     * because dockview had to be told, could not be told before it mounted,
+     * and had to be told again afterwards — three problems that all came
+     * from the layout living somewhere this action could not reach.
+     */
+    applyLayoutSpec(spec: LayoutSpecNode): string[];
+    /**
+     * ViewMenu's "move to new tab": the view leaves its tab for a new one.
+     *
+     * `allViewIds` is EVERY view in the session, defaulting to the host's
+     * own list — homing drops any view the list does not name, so the
+     * `[viewId]` default this used to carry unhomed all the others.
+     */
+    moveViewToNewTab(viewId: string, allViewIds?: string[]): string | undefined;
+    /**
+     * ViewMenu's "move to split view": the view leaves for a new cell.
+     * `allViewIds` is every view in the session — see `moveViewToNewTab`.
+     */
+    moveViewToSplitRight(viewId: string, allViewIds?: string[]): string | undefined;
+    homeUnassignedViews(viewIds: string[]): void;
+} & {
+    /**
+     * Move one view relative to the others. PUBLIC API: an external plugin
+     * calls this behind a `'setPendingMove' in session` guard
+     * (jbrowse-plugin-protein3d, putting a protein view beside its genome
+     * view). It survived the last storage change by being kept as sugar, and
+     * it survives this one the same way — a capability-detecting caller
+     * cannot tell you it lost a capability.
+     *
+     * **`allViewIds` is therefore OPTIONAL, and has to stay that way.** The
+     * plugin passes the move alone, because that was the whole signature when
+     * its call site was written; requiring the second argument threw
+     * `undefined.filter` out of a launch the plugin does not wrap, and the
+     * figure was again the only thing that noticed. Keeping the NAME is half
+     * of not breaking a runtime lookup — the call has to keep working as it
+     * is spelled.
+     */
+    setPendingMove(move: PendingMove | undefined, allViewIds?: string[]): void;
+    /**
+     * The whole-workspace re-arrange: every view one cell, in one of four
+     * shapes. Restored from the dockview header's four "Global:" commands,
+     * which went with that component and were not reimplemented.
+     *
+     * `allViewIds` is passed in rather than read off the session for the same
+     * reason `moveViewToNewTab` takes it: this mixin owns the tree and has no
+     * view list of its own. Passing `session.views` order means the
+     * arrangement it states is already the order views render in, so unlike a
+     * session spec's layout there is nothing for `orderViews` to apply.
+     */
+    tileViews(mode: TileMode, allViewIds: string[]): void;
+    /**
+     * #action
+     * Arrange the session's views into panels. Calls `applyLayoutSpec`,
+     * turns workspaces mode on for this session (a layout renders nowhere
+     * else), and orders `session.views` to the spec's top-to-bottom
+     * order, which tabs read their order from. Without the last two steps
+     * the layout applies but does not display, or the tabs appear in the
+     * wrong order. Leaves take view ids or indexes into `session.views`; a
+     * layout that seats no view throws rather than leaving a blank tab. A
+     * session spec's `layout` and an agent's live re-layout both call it.
+     */
+    layoutViews(spec: LayoutSpecNode): string[];
+}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+export type WorkspaceLayoutMixinType = ReturnType<typeof WorkspaceLayoutMixin>;
+export interface WorkspaceLayout extends Instance<WorkspaceLayoutMixinType> {
+}
+export declare function isSessionWithWorkspaceLayout(session: IAnyStateTreeNode): session is WorkspaceLayout;