/** * @file * * Mock of Obsidian's `Workspace`, which manages the app's leaves, splits and layout. */ import type { Constructor as ConstructorOriginal, MarkdownFileInfo as MarkdownFileInfoOriginal, Menu as MenuOriginal, OpenViewState as OpenViewStateOriginal, PaneType as PaneTypeOriginal, Side as SideOriginal, SplitDirection as SplitDirectionOriginal, View as ViewOriginal, Workspace as WorkspaceOriginal, WorkspaceParent as WorkspaceParentOriginal, WorkspaceWindowInitData as WorkspaceWindowInitDataOriginal } from 'obsidian'; import type { SerializedWorkspace, SerializedWorkspaceItem, WorkspaceEnsureSideLeafOptions, WorkspaceSetActiveLeafOptions } from '../internal/types.mjs'; import type { App } from './App.mjs'; import type { WorkspaceItem } from './WorkspaceItem.mjs'; import { Events } from './Events.mjs'; import { TFile } from './TFile.mjs'; import { WorkspaceFloating } from './WorkspaceFloating.mjs'; import { WorkspaceLeaf } from './WorkspaceLeaf.mjs'; import { WorkspaceRibbon } from './WorkspaceRibbon.mjs'; import { WorkspaceRoot } from './WorkspaceRoot.mjs'; import { WorkspaceSidedock } from './WorkspaceSidedock.mjs'; import { WorkspaceTabs } from './WorkspaceTabs.mjs'; import { WorkspaceWindow } from './WorkspaceWindow.mjs'; /** * Mock of Obsidian's `Workspace`. * * Leaves live in a real layout tree, as in Obsidian: tab groups inside the root split, the two sidebars, and the * popout windows under {@link Workspace.floatingSplit}. Methods that create a leaf place it where Obsidian would and * make it active, lookups and iterators walk the tree, and every layout change runs through * {@link Workspace.onLayoutChange} into {@link Workspace.updateLayout}, which re-picks an active leaf and re-populates * an emptied root split. * * The layout-ready state is driven by the test through {@link Workspace.setLayoutReady__}, and it is load-bearing: * exactly as in Obsidian, {@link Workspace.updateLayout} and {@link Workspace.activeLeafEvents} do nothing until it is * set, so `active-leaf-change`, `file-open` and `layout-change` do not fire in a workspace that was never made ready. * * Nothing is rendered, and leaves are always treated as visible. */ export declare class Workspace extends Events { /** * The editor component of the active view, or `null` when it has none. The mock never sets it. */ activeEditor: MarkdownFileInfoOriginal | null; /** * The currently focused leaf, if any. Obsidian discourages reading it in favor of * {@link Workspace.getActiveViewOfType} and {@link Workspace.getLeaf}. */ activeLeaf: null | WorkspaceLeaf; /** * The tab group the active leaf sits in, or `null` when it sits in something else or there is no active leaf. */ activeTabGroup: null | WorkspaceTabs; /** * The workspace's root element. */ containerEl: HTMLElement; /** * The parent of every popout window. */ floatingSplit: WorkspaceFloating; /** * The file `file-open` was last fired for, which is what {@link Workspace.activeLeafEvents} compares against to * decide whether to fire it again. */ lastActiveFile: null | TFile; /** * Whether the last tab group to lose its final leaf was stacked. {@link Workspace.updateLayout} gives the group it * re-creates in an emptied root split the same stacking. */ lastTabGroupStacked: boolean; /** * Whether the layout has been initialized; `false` until {@link Workspace.setLayoutReady__} is called. */ layoutReady: boolean; /** * The ribbon on the left edge of the app. */ leftRibbon: WorkspaceRibbon; /** * The left sidebar. */ leftSplit: WorkspaceSidedock; /** * Requests a debounced run of {@link Workspace.activeLeafEvents}, as Obsidian does. Call `run()` on it to fire the * pending events at once instead of waiting for the timer. */ requestActiveLeafEvents: import("obsidian").Debouncer<[], void>; /** * Requests a debounced `layout-change` trigger, as Obsidian does. Call `run()` on it to fire a pending event at once * instead of waiting for the timer. */ requestLayoutChangeEvents: import("obsidian").Debouncer<[], void>; /** * Requests a debounced save of the workspace layout. Debounces a no-op in the mock. */ requestSaveLayout: import("obsidian").Debouncer<[], void>; /** * The ribbon on the right edge of the app. Obsidian deprecates it as no longer used. */ rightRibbon: WorkspaceRibbon; /** * The right sidebar. */ rightSplit: WorkspaceSidedock; /** * The main area's root split. */ rootSplit: WorkspaceRoot; private readonly app; private isUpdateLayoutQueued; private lastActiveTime; private layoutReadyCallbacks; /** * Creates the workspace with its ribbons, sidebars, root split and floating split, and no leaves. * * @param app - The app the workspace belongs to. * @param containerEl - The workspace's root element. */ protected constructor(app: App, containerEl: HTMLElement); /** * Mock-only factory: creates a workspace, spyable via `vi.spyOn(Workspace, 'create2__')`. It is numbered because * `Events.create__` takes no arguments, so a `create__` here would conflict on the static side. * * @param app - The app the workspace belongs to. * @param containerEl - The workspace's root element. * @returns The new workspace. */ static create2__(app: App, containerEl: HTMLElement): Workspace; /** * Mock-only: views a value typed as Obsidian's `Workspace` as this mock. * * @param value - The value typed as the original `Workspace`. * @returns The same object, typed as the mock. */ static fromOriginalType2__(value: WorkspaceOriginal): Workspace; /** * Fires the events that follow an active-leaf change: `active-leaf-change`, then `file-open` when the active file * changed too. {@link Workspace.setActiveLeaf} asks for it through {@link Workspace.requestActiveLeafEvents} rather * than calling it directly. As in Obsidian, it does nothing until the layout is ready. */ activeLeafEvents(): void; /** * Mock-only: views this mock as Obsidian's `Workspace` type. * * @returns The same object, typed as the original `Workspace`. */ asOriginalType2__(): WorkspaceOriginal; /** * Replaces the workspace layout with a serialized one, as Obsidian does: once the layout is ready, it clears the * current layout through {@link Workspace.clearLayout} and rebuilds it from `workspace` through * {@link Workspace.setLayout}. Before the layout is ready it does nothing at all. * * @param workspace - The serialized layout, as {@link Workspace.getLayout} returns it. */ changeLayout(workspace: unknown): Promise; /** * Takes the current layout down before {@link Workspace.setLayout} builds a new one, as Obsidian does: the layout * stops being ready, a pending `layout-change` is cancelled, every leaf goes back to the empty view, and there is no * active leaf any more. * * Obsidian then detaches the splits' elements, unloads their components, closes the popout windows and sets the four * splits to `null`. The mock builds no layout DOM and has no window to close, and its splits are never `null`, so it * puts fresh empty ones in their place instead: a leaf built afterwards finds none of the old leaves, which is what * keeps an old leaf's linked-view group, and its pinned flag with it, out of the restored layout. */ clearLayout(): Promise; /** * Mock-only construction hook, called at the end of the constructor; a no-op meant for * `vi.spyOn(Workspace.prototype, 'constructor2__')`. * * @param _app - The app the workspace was created with. * @param _containerEl - The root element the workspace was created with. */ constructor2__(_app: App, _containerEl: HTMLElement): void; /** * Splits a leaf, creating a new leaf in its own tab group beside it and making it active, as Obsidian does. * * @param leaf - The leaf to split. * @param direction - Whether to split vertically (side by side) or horizontally (stacked); `'vertical'` by default. * @param before - Whether to place the new leaf before the existing one. * @returns The new leaf. */ createLeafBySplit(leaf: WorkspaceLeaf, direction?: SplitDirectionOriginal, before?: boolean): WorkspaceLeaf; /** * Creates a leaf at an index inside a parent and makes it active, as Obsidian does. A parent that already holds * children gives the new leaf an equal share of them. * * @param parent - The parent to create the leaf in. * @param index - The position within the parent; a negative or out-of-range index appends. * @returns The new leaf. */ createLeafInParent(parent: WorkspaceParentOriginal, index: number): WorkspaceLeaf; /** * Creates a leaf in a tab group, after the group's most recently active tab, as Obsidian does — and makes it active * when the vault's `focusNewTab` setting is on, which it is by default. When that most recently active tab is * already showing the empty view, Obsidian hands it back instead of creating anything, and without activating it; * the mock asks the same question its own way. So two `getLeaf('tab')` calls with nothing done to the leaf in * between answer with the same leaf, exactly as the real app does. * * One departure. Obsidian throws `No tab group found.` when no group is given and no leaf was ever active; the * mock falls back to the root tab group, creating it when the root split is empty, so `getLeaf('tab')` works on a * workspace no test has populated. * * @param tabs - The group to create the leaf in; the most recently active leaf's group by default. * @returns The new leaf. */ createLeafInTabGroup(tabs?: WorkspaceParentOriginal): WorkspaceLeaf; /** * Builds one node of the layout tree from its serialized form, as Obsidian does, and the subtree under it. * * - A `split` becomes the root split when `side` is `root`, a sidedock with its width and collapsed state when `side` * is `left` or `right`, and a plain split otherwise. A split that ends up with no children is dropped, except a * sidedock. On a platform that cannot split, every tab group of the root is merged into its first one. * - A `floating` entry keeps only its `window` children, and a `window` entry is restored only in the desktop app. * - A `tabs` entry restores its stacked state and its current tab, and is dropped when it ends up empty. * - A `leaf` entry gets a leaf with the entry's id, its view state, its linked-view group and its pinned flag. A view * state that fails to apply is logged, as in Obsidian. * - A leaf found directly under anything but a tab group is wrapped in a tab group of its own, and a child that cannot * be restored is removed from `entry.children` in place. * * Not modelled: Obsidian's 10-second limit on restoring a leaf's view, and the mobile drawers, so a `mobile-drawer` * entry, and a sidebar entry on mobile, answer `null`. * * @param entry - The serialized node. * @param side - `root`, `left` or `right` for the top of the main area or a sidebar, `null` for anything below. * @returns The restored node, or `null` when there is nothing to restore. */ deserializeLayout(entry: SerializedWorkspaceItem, side: 'left' | 'right' | 'root' | null): Promise; /** * Detaches every leaf showing the given view type. * * @param viewType - The view type to remove. */ detachLeavesOfType(viewType: string): void; /** * Duplicates a leaf into a new tab, split or window, copying its view state and ephemeral state. `'split'`, or a * split direction in place of the leaf type, splits the leaf; anything else asks {@link Workspace.getLeaf}. * * @param leaf - The leaf to duplicate. * @param leafType - Where to open the duplicate, or the split direction. * @param direction - The split direction, when splitting. * @returns The new leaf. */ duplicateLeaf(leaf: WorkspaceLeaf, leafType?: boolean | PaneTypeOriginal | SplitDirectionOriginal, direction?: SplitDirectionOriginal): Promise; /** * Gets a sidebar leaf of the given type, as Obsidian does: the first leaf of that type anywhere, or a new leaf from * {@link Workspace.getLeftLeaf} / {@link Workspace.getRightLeaf}. The leaf's view state is set when a state is given * or its type differs; the leaf is then revealed unless `reveal` is `false`, and made active when `active` is set. * * @param type - The view type. * @param side - Which sidebar to create the leaf in. * @param options - Whether to activate, split or reveal the leaf, and the state to give it. * @returns The leaf. */ ensureSideLeaf(type: string, side: SideOriginal, options?: WorkspaceEnsureSideLeafOptions): Promise; /** * Gets the file of the active view, or the most recently active file. The mock returns the active leaf's file. * * @returns The file, or `null` when there is no active leaf or it has no file. */ getActiveFile(): null | TFile; /** * Gets the active leaf's view when it is an instance of the given class. * * @typeParam T - The view class. * @param type - The view constructor to match. * @returns The active leaf's view, or `null` when there is no active leaf or its view is not a `type`. */ getActiveViewOfType(type: ConstructorOriginal): null | T; /** * Gets the container the workspace considers focused. The mock has one window, so it is always the root split — * which is what Obsidian answers whenever its focused window is the main one. * * @returns The root split. */ getFocusedContainer(): WorkspaceRoot; /** * Gets all leaves that belong to a linked group. * * @param group - The group id. * @returns The leaves whose group is `group`; empty for an empty group id. */ getGroupLeaves(group: string): WorkspaceLeaf[]; /** * Gets the paths of the ten most recently opened files. * * @returns The paths; always empty in the mock. */ getLastOpenFiles(): string[]; /** * Serializes the workspace layout, as Obsidian does: the root split as `main`, the two sidebars as `left` and * `right`, the left ribbon as `left-ribbon`, the popout windows as `floating` when there are any, and the active * leaf's id as `active` when there is one. {@link Workspace.setLayout} and {@link Workspace.changeLayout} read it * back. * * @returns The serialized layout. */ getLayout(): Record; /** * Gets a leaf to open something in. `'split'` splits the most recent leaf, `'tab'` or `true` adds a tab next to the * most recently active one, and `'window'` opens a popout window. `false` or omitted asks * {@link Workspace.getUnpinnedLeaf}. * * @param newLeaf - Whether, and where, to create a new leaf. * @param direction - The split direction, for `'split'`. * @returns The leaf. */ getLeaf(newLeaf?: boolean | PaneTypeOriginal, direction?: SplitDirectionOriginal): WorkspaceLeaf; /** * Gets a leaf by its id. * * @param id - The leaf id. * @returns The leaf, or `null` when no leaf in the layout has that id. */ getLeafById(id: string): null | WorkspaceLeaf; /** * Gets every leaf showing the given view type, as its view reports it. * * @param viewType - The view type. * @returns The matching leaves. */ getLeavesOfType(viewType: string): WorkspaceLeaf[]; /** * Creates a leaf in the left sidebar: in a new tab group when `split` is set, and otherwise in the sidebar's first * tab group, which is created when the sidebar is empty. * * @param split - Whether to put the leaf in a new tab group. * @returns The new leaf, or `null` when the sidebar's first child is not a parent that can hold it. */ getLeftLeaf(split: boolean): null | WorkspaceLeaf; /** * Gets the most recently active leaf in a part of the layout: the leaf with the highest * {@link WorkspaceLeaf.activeTime}, or the first leaf found when none was ever active. * * @param root - The part of the layout to search; the root split and the popout windows by default, as in Obsidian. * @returns The leaf, or `null` when there are no leaves there. */ getMostRecentLeaf(root?: WorkspaceParentOriginal): null | WorkspaceLeaf; /** * Creates a leaf in the right sidebar: in a new tab group when `split` is set, and otherwise in the sidebar's first * tab group, which is created when the sidebar is empty. * * @param split - Whether to put the leaf in a new tab group. * @returns The new leaf, or `null` when the sidebar's first child is not a parent that can hold it. */ getRightLeaf(split: boolean): null | WorkspaceLeaf; /** * Gets a leaf to navigate in, as Obsidian does, and makes it active unless told not to. Obsidian deprecates it in * favor of `getLeaf(false)`, which is a call to this. * * The active leaf is handed straight back when it can navigate — and is then NOT re-activated, since it already is. * Otherwise it searches the active leaf's container, or the root split when there is none, for the most recently * active leaf that can navigate and is its tab group's current tab (or sits in a stacked group). Failing that it * creates one beside the container's most recently active leaf. * * @param activate - Whether to make the leaf active; `true` by default, as in Obsidian. * @returns The leaf. */ getUnpinnedLeaf(activate?: boolean): WorkspaceLeaf; /** * Adds the internal-link items to a context menu. A no-op in the mock. * * @param _menu - The menu to add to. * @param _linktext - The link text. * @param _sourcePath - The path of the note containing the link. * @param _leaf - The leaf the link is in. * @returns Whether items were added; always `false` in the mock. */ handleLinkContextMenu(_menu: MenuOriginal, _linktext: string, _sourcePath: string, _leaf?: WorkspaceLeaf): boolean; /** * Checks whether an item is part of the layout: whether its root is one of the root split, the two sidebars or the * floating split. * * @param item - The item to check. * @returns Whether the item is attached. */ isAttached(item?: WorkspaceItem): boolean; /** * Calls the callback on every leaf, in Obsidian's order: the root split, the left sidebar, the right sidebar, then * the popout windows. * * A callback that returns a truthy value stops the walk of the part it is in — and, as in Obsidian, only that part: * the four walks are started independently and their answers are discarded, so stopping inside the root split does * not stop the sidebars. * * @param callback - Called with each leaf. */ iterateAllLeaves(callback: (leaf: WorkspaceLeaf) => unknown): void; /** * Calls the callback on every leaf under an item, depth first. As in Obsidian, a callback that returns a truthy * value stops the walk. * * @param item - The item to walk, or several of them. * @param callback - Called with each leaf. * @returns Whether the walk was stopped by the callback. */ iterateLeaves(item: WorkspaceItem | WorkspaceItem[], callback: (leaf: WorkspaceLeaf) => unknown): boolean; /** * Calls the callback on every leaf in the root split: the main area, without the sidebars or popout windows. A * callback that returns a truthy value stops the walk. * * @param callback - Called with each leaf. */ iterateRootLeaves(callback: (leaf: WorkspaceLeaf) => unknown): void; /** * Moves a leaf into a new popout window, in a tab group of its own. The leaf gives up its share of the split it * came from, as in Obsidian. The mock never throws for a missing popout capability. * * @param leaf - The leaf to move. * @param _data - The window's initial size and position; not kept by the mock. * @returns The new window. */ moveLeafToPopout(leaf: WorkspaceLeaf, _data?: WorkspaceWindowInitDataOriginal): WorkspaceWindow; /** * Records that the layout changed, which asks for a debounced {@link Workspace.updateLayout}. `WorkspaceParent` * calls it whenever it adopts, releases or replaces a child. * * @param _item - The item whose children changed. Obsidian queues it for a dimension recompute, which the mock does * not model. */ onLayoutChange(_item?: WorkspaceItem): void; /** * Runs the callback now if the layout is ready, or queues it until {@link Workspace.setLayoutReady__} is called. * * @param callback - The callback to run. */ onLayoutReady(callback: () => unknown): void; /** * Opens the file a link resolves to, via `metadataCache.getFirstLinkpathDest`, in the leaf {@link Workspace.getLeaf} * picks, and makes that leaf active. Does nothing when the link resolves to no file. * * @param linktext - The link text to resolve. * @param sourcePath - The path of the note the link is in. * @param newLeaf - Whether, and where, to open a new leaf. * @param _openViewState - The view state to open with; ignored by the mock. */ openLinkText(linktext: string, sourcePath: string, newLeaf?: boolean | PaneTypeOriginal, _openViewState?: OpenViewStateOriginal): Promise; /** * Opens a popout window with a single new leaf, in a tab group of its own. * * @param _data - The window's initial size and position; not kept by the mock. * @returns The new leaf. */ openPopoutLeaf(_data?: WorkspaceWindowInitDataOriginal): WorkspaceLeaf; /** * Reads the saved workspace layout, as Obsidian does: `workspace.json` in the vault's config folder, or * `workspace-mobile.json` on mobile, parsed as JSON. A file that is missing or does not parse answers an empty object. * * @returns The saved layout, as {@link Workspace.setLayout} reads it. */ readWorkspaceFile(): Promise; /** * Mock-only: removes a leaf from the layout tree; called when a leaf detaches. * * It does NOT clear {@link Workspace.activeLeaf}, because Obsidian does not either: a detached active leaf stays * there until {@link Workspace.updateLayout} notices it is no longer attached and picks another one, which the * layout change this removal causes asks for. * * @param leaf - The leaf to remove. */ removeLeaf__(leaf: WorkspaceLeaf): void; /** * Asks for a {@link Workspace.updateLayout} on a microtask, coalescing every request made before it runs — as * Obsidian does. Await a microtask (for example `await Promise.resolve()`) to let it run, or call `updateLayout()` * directly to do the work at once. */ requestUpdateLayout(): void; /** * Brings a leaf to the foreground: expands its sidebar when that is collapsed, then loads the leaf if deferred. As * in Obsidian, it does not make the leaf active. * * @param leaf - The leaf to reveal. */ revealLeaf(leaf: WorkspaceLeaf): Promise; /** * Makes a leaf active, stamps its {@link WorkspaceLeaf.activeTime}, shows it in its tab group, and asks for the * `active-leaf-change` and `file-open` events through {@link Workspace.requestActiveLeafEvents}. * * As in Obsidian, a leaf that is already active is left alone and fires nothing, and the events are DEFERRED rather * than fired from this call — `requestActiveLeafEvents.run()` delivers a pending one at once. Unlike Obsidian, which * ignores a leaf outside the layout, a leaf outside the layout is first added to the root tab group, so a leaf built * with `WorkspaceLeaf.create2__(app)` can be made active without being placed by hand. * * @param leaf - The new active leaf. * @param _options - Whether to focus the leaf; ignored by the mock. */ setActiveLeaf(leaf: WorkspaceLeaf, _options?: WorkspaceSetActiveLeafOptions): void; /** * Rebuilds the whole layout from a serialized one, as Obsidian does. * * The layout stops being ready while it runs. `main`, `left`, `right` and `floating` are each built through * {@link Workspace.deserializeLayout}, the root split turned vertical and the sidebars horizontal, and the left ribbon * is loaded from `left-ribbon`. Whatever the data leaves out is created fresh: a root split holding one tab group with * one leaf, which opens the most recently opened file and is made active; a left and a collapsed right sidedock; and * an empty floating split. The leaf named by `active` is then made active, unless it sits in a collapsed sidebar. * Finally the layout is ready again, and a layout change and the active-leaf events are requested. * * Departures: a `main` entry that does not restore to a root split, or a sidebar entry that does not restore to a * sidedock, is treated as missing, since Obsidian would store whatever it got; the layout's elements are not placed * in {@link Workspace.containerEl}; the mobile drawers are not modelled; and no view is deferred, so there is nothing * to load at the end. * * @param data - The serialized layout, as {@link Workspace.getLayout} or {@link Workspace.readWorkspaceFile} gives it. */ setLayout(data: SerializedWorkspace): Promise; /** * Mock-only: simulates the layout becoming ready: sets {@link Workspace.layoutReady} and runs, then clears, the * callbacks queued by {@link Workspace.onLayoutReady}. */ setLayoutReady__(): void; /** * Splits the most recently active leaf, or creates a leaf at the start of the root split when there is none. * Obsidian deprecates it in favor of `getLeaf('split')`. * * @param direction - Whether to split vertically or horizontally. * @returns The new leaf. */ splitActiveLeaf(direction?: SplitDirectionOriginal): WorkspaceLeaf; /** * Places an item in its own tab group beside another, as Obsidian does: next to the existing item's tab group when * the nearest split already runs in `direction`, and otherwise inside a new split of that direction that takes the * tab group's place. The share of the split is divided between the two, or carried onto the new split. * * An item outside the layout has nothing to split — Obsidian throws there; the mock adds the new item to the root * tab group instead. * * @param item - The item to split. * @param newItem - The item to place beside it. * @param direction - Whether to split vertically (side by side) or horizontally (stacked); `'vertical'` by default. * @param before - Whether to place the new item before the existing one. */ splitLeaf(item: WorkspaceItem, newItem: WorkspaceItem, direction?: SplitDirectionOriginal, before?: boolean): void; /** * Brings the layout back into a consistent state after it changed, as Obsidian does, and fires the events that go * with it. {@link Workspace.onLayoutChange} asks for it on a microtask; calling it directly does the work at once. * * It re-creates a tab group and a leaf in an emptied root split; picks a new active leaf when there is none or the * one there is has been detached, preferring the active tab group's current tab, then the most recently active leaf * of the focused container, then the most recently active leaf anywhere, and finally a new one; clears a link group * that is down to a single leaf; and ends by requesting a layout save and the `layout-change` event. * * As in Obsidian, it does nothing at all until the layout is ready. */ updateLayout(): void; /** * Reconfigures the options of every Markdown view. A no-op in the mock. */ updateOptions(): void; private clearSingleMemberGroups; private createLeafBesideMostRecent; private createPopoutWindow; private createSidebarLeaf; private deserializeChildren; private deserializeLeaf; private deserializeSidedock; private deserializeSplit; private findSelectedNavigableLeaf; private getMostRecentTabGroup; private getRootTabGroup; private layoutChangeEvents; private pickActiveLeaf; }