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

package/esm/WorkspaceLayout/dropZone.d.ts

@@ -1,11 +1,4 @@
-/**
- * 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.
- */
+/** Drop geometry over plain rects, so it is testable without a DOM. */
 export type DropZone = 'center' | 'left' | 'right' | 'top' | 'bottom';
 export interface Rect {
     left: number;
@@ -13,11 +6,7 @@ export interface Rect {
     width: number;
     height: number;
 }
-/**
- * Where a drop would land. `zone` alone says which half of a cell; `strip` is
- * set when the pointer is on the tab strip itself, which is a finer answer than
- * `center` — that one appends, this one says where in the order.
- */
+/** `strip` is set on the tab strip, and gives a position in the tab order. */
 export interface DropTarget {
     zone: DropZone;
     strip?: StripDrop;
@@ -30,33 +19,14 @@ export interface StripDrop {
     left: number;
 }
 /**
- * `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%.
+ * `center` adds as a tab; an edge splits the panel. Bands are proportional and
+ * capped below half, so a narrow panel keeps a centre. A corner goes to the
+ * edge the pointer is proportionally deeper into.
  */
 export declare function dropZoneAt(rect: Rect, x: number, y: number, edgeFraction?: number): DropZone;
 /**
- * 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.
+ * The gap between tabs nearest `x`, by tab midpoint so every x has exactly one.
+ * `x` is in the rects' coordinate space, whichever that is.
  */
 export declare function stripDropAt(rects: Rect[], x: number): StripDrop;
 /**

package/esm/WorkspaceLayout/dropZone.js

@@ -1,26 +1,8 @@
+/** Drop geometry over plain rects, so it is testable without a DOM. */
 /**
- * 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%.
+ * `center` adds as a tab; an edge splits the panel. Bands are proportional and
+ * capped below half, so a narrow panel keeps a centre. A corner goes to the
+ * edge the pointer is proportionally deeper into.
  */
 export function dropZoneAt(rect, x, y, edgeFraction = 0.25) {
     const fraction = Math.min(Math.max(edgeFraction, 0), 0.49);
@@ -43,16 +25,8 @@ export function dropZoneAt(rect, x, y, edgeFraction = 0.25) {
     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.
+ * The gap between tabs nearest `x`, by tab midpoint so every x has exactly one.
+ * `x` is in the rects' coordinate space, whichever that is.
  */
 export function stripDropAt(rects, x) {
     for (const [i, rect] of rects.entries()) {
@@ -66,18 +40,7 @@ export function stripDropAt(rects, x) {
         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.
- */
+// one table, so the shaded half and the half a drop lands in cannot disagree
 const ZONES = {
     left: {
         split: { direction: 'row', before: true },

package/esm/WorkspaceLayout/model.d.ts

@@ -78,29 +78,16 @@ export declare function WorkspaceLayoutMixin(): import("@jbrowse/mobx-state-tree
     }>>, [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.
+     * Show only this cell, at the size of the whole workspace. Kept here
+     * rather than as a flag on `PanelNode` so no `tree.ts` operation has to
+     * say what it does to it.
      */
     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.
+     * Referentially stable, since `getSnapshot` is cached. Uncast on
+     * purpose: this assignment is what checks the models above agree with
+     * the interfaces in `tree.ts`.
      */
     readonly tree: LayoutTree;
 } & {
@@ -115,31 +102,18 @@ export declare function WorkspaceLayoutMixin(): import("@jbrowse/mobx-state-tree
     /** 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.
+     * The maximized cell alone, or the whole tree. The cell is resized to 1
+     * because CSS hands out free space by grow factor only up to a total of
+     * 1, so a third-of-a-row cell would draw a third of the window.
      */
     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_PORTABILITY.md`) can
-     * only go down. That is the reason it is this and not a `display:
-     * none` over a still-mounted workspace.
+     * Show one cell at the size of the workspace, or go back; naming a
+     * different cell moves the mode. Unmounts every other cell's views
+     * rather than hiding them, to stay under the WebGL2 context ceiling
+     * (`agent-docs/reference/GPU_PORTABILITY.md`).
      */
     toggleMaximizedPanel(panelId: string): void;
     restorePanels(): void;
@@ -151,106 +125,62 @@ export declare function WorkspaceLayoutMixin(): import("@jbrowse/mobx-state-tree
     /** "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.
+     * Close a tab, and its cell too if that was the last tab and not the
+     * workspace's last cell: a tabless cell renders nothing at all.
      */
     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.
-     */
+    /** Drop a dragged tab into an existing panel, as a tab. */
     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.
+     * Arrange the workspace as a spec states, in the shape a session
+     * spec's `layout` takes: a leaf's `views` names views by index into
+     * `session.views` or by id. A malformed leaf, an index past the end or
+     * an unknown id throws.
      */
     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.
+     * own list, since homing drops any view the list omits.
      */
     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`.
+     * ViewMenu's "move to split": the view leaves for a new cell to the
+     * right (`row`) or below (`column`) of its own.
+     */
+    moveViewToSplit(viewId: string, direction: 'row' | 'column', allViewIds?: string[]): string | undefined;
+    /**
+     * ViewMenu's "move to tab": the view joins an existing tab, which
+     * becomes the one shown.
      */
-    moveViewToSplitRight(viewId: string, allViewIds?: string[]): string | undefined;
+    moveViewToTab(viewId: string, tabId: string, allViewIds?: string[]): void;
     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.
+     * Move one view to a new tab or a split beside its cell, keeping the
+     * rest of the arrangement. PUBLIC API: protein3d and msaview call it
+     * with the move alone, so `allViewIds` stays optional; it is read only
+     * on a host with no view list.
      */
     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.
+     * Re-arrange the whole workspace, one view per cell, in one of four
+     * shapes. Pass `allViewIds` in `session.views` order so 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.
+     * Arrange the session's views into panels: `applyLayoutSpec`, then
+     * `session.views` ordered to the spec's top-to-bottom order, which tabs
+     * read their order from. 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>;