@olenbetong/appframe-ds 0.9.0 → 1.0.0

package/src/mdi/layoutRestore.ts

@@ -0,0 +1,311 @@
+import type { SerializedDockview, SerializedGridObject } from "dockview-react";
+
+import { isGroupSpec, type MdiGroupState, specDocumentId } from "./layoutSpec.js";
+import { resolveClosable, resolveType } from "./registry.js";
+import type {
+	MdiDocumentSpec,
+	MdiDocumentTypes,
+	MdiGroupSpec,
+	MdiLayout,
+	MdiLayoutNode,
+	MdiLayoutSpec,
+	MdiPosition,
+} from "./types.js";
+
+type GridNode = SerializedGridObject<MdiGroupState>;
+type LeafNode = GridNode & { type: "leaf"; data: MdiGroupState };
+type BranchNode = GridNode & { type: "branch"; data: GridNode[] };
+
+function isLeaf(node: GridNode): node is LeafNode {
+	return node.type === "leaf";
+}
+
+function isBranch(node: GridNode): node is BranchNode {
+	return node.type === "branch";
+}
+
+function collectLeaves(node: GridNode, result: LeafNode[] = []): LeafNode[] {
+	if (isLeaf(node)) {
+		result.push(node);
+	} else if (isBranch(node)) {
+		for (let child of node.data) {
+			collectLeaves(child, result);
+		}
+	}
+
+	return result;
+}
+
+/** The group states in the grid, in layout order. Popout and floating groups are docked first. */
+export function listGridGroups(dockview: SerializedDockview): MdiGroupState[] {
+	return collectLeaves(dockview.grid.root).map((leaf) => leaf.data);
+}
+
+/** Merges the groups of a floating/popout window into one group state */
+function mergeGroups(groups: MdiGroupState[]): MdiGroupState | undefined {
+	let [first, ...rest] = groups;
+
+	if (!first) {
+		return undefined;
+	}
+
+	let views = [...first.views];
+	for (let group of rest) {
+		views.push(...group.views);
+	}
+
+	return { ...first, views, activeView: first.activeView ?? views[0] };
+}
+
+function windowGroups(entry: { data?: MdiGroupState; grid?: { root: GridNode } }): MdiGroupState[] {
+	if (entry.data) {
+		return [entry.data];
+	}
+
+	if (entry.grid) {
+		return collectLeaves(entry.grid.root).map((leaf) => leaf.data);
+	}
+
+	return [];
+}
+
+/**
+ * Moves floating and popout groups back into the grid. Browsers block `window.open`
+ * without a user gesture, so popouts cannot be restored as windows on page load anyway;
+ * docking them keeps the documents visible instead of relying on dockview's fallback.
+ */
+export function dockPopoutGroups(dockview: SerializedDockview): SerializedDockview {
+	let result = structuredClone(dockview);
+	let popouts = result.popoutGroups ?? [];
+	let floating = result.floatingGroups ?? [];
+	delete result.popoutGroups;
+	delete result.floatingGroups;
+
+	if (popouts.length === 0 && floating.length === 0) {
+		return result;
+	}
+
+	if (!isBranch(result.grid.root)) {
+		result.grid.root = { type: "branch", size: result.grid.root.size, data: [result.grid.root] };
+	}
+
+	let root = result.grid.root as BranchNode;
+	let leaves = collectLeaves(root);
+	let toDock: MdiGroupState[] = [];
+
+	for (let popout of popouts) {
+		let merged = mergeGroups(windowGroups(popout));
+		if (!merged) continue;
+
+		// A popped-out group leaves a hidden placeholder in the grid; put the documents back there.
+		let reference = popout.gridReferenceGroup
+			? leaves.find((leaf) => leaf.data.id === popout.gridReferenceGroup)
+			: undefined;
+
+		if (reference) {
+			reference.data.views.push(...merged.views);
+			reference.data.activeView ??= merged.activeView;
+			delete reference.visible;
+		} else {
+			toDock.push(merged);
+		}
+	}
+
+	for (let entry of floating) {
+		let merged = mergeGroups(windowGroups(entry));
+		if (merged) toDock.push(merged);
+	}
+
+	let usedIds = new Set(leaves.map((leaf) => leaf.data.id));
+	let averageSize =
+		root.data.length > 0 ? root.data.reduce((sum, node) => sum + (node.size ?? 0), 0) / root.data.length : 1;
+
+	for (let group of toDock) {
+		let id = group.id;
+		while (usedIds.has(id)) {
+			id = `${id}-docked`;
+		}
+		usedIds.add(id);
+		root.data.push({ type: "leaf", data: { ...group, id }, size: averageSize || 1 });
+	}
+
+	return result;
+}
+
+function pruneNode(node: GridNode, keep: Set<string>): GridNode | undefined {
+	if (isLeaf(node)) {
+		let views = node.data.views.filter((view) => keep.has(view));
+
+		if (views.length === 0) {
+			return undefined;
+		}
+
+		let activeView = node.data.activeView && views.includes(node.data.activeView) ? node.data.activeView : views[0];
+		return { ...node, data: { ...node.data, views, activeView } };
+	}
+
+	if (isBranch(node)) {
+		let children = node.data.map((child) => pruneNode(child, keep)).filter((child) => child !== undefined);
+
+		if (children.length === 0) {
+			return undefined;
+		}
+
+		// A branch wrapping a single leaf is redundant. A single nested branch has to stay,
+		// since dockview alternates orientation per level.
+		if (children.length === 1 && isLeaf(children[0]!)) {
+			return { ...children[0]!, size: node.size };
+		}
+
+		return { ...node, data: children };
+	}
+
+	return node;
+}
+
+/** Removes every document that is not in `keep` from the layout, dropping groups and splits that become empty. */
+export function pruneLayout(layout: MdiLayout, keep: Set<string>): MdiLayout {
+	let documents: MdiLayout["documents"] = {};
+	for (let [id, document] of Object.entries(layout.documents)) {
+		if (keep.has(id)) documents[id] = document;
+	}
+
+	let panels: SerializedDockview["panels"] = {};
+	for (let [id, panel] of Object.entries(layout.dockview.panels)) {
+		if (keep.has(id)) panels[id] = panel;
+	}
+
+	let root = pruneNode(layout.dockview.grid.root, keep);
+
+	if (!root) {
+		root = { type: "branch", size: layout.dockview.grid.root.size, data: [] };
+	} else if (!isBranch(root)) {
+		root = { type: "branch", size: root.size, data: [root] };
+	}
+
+	let remainingGroups = new Set(collectLeaves(root).map((leaf) => leaf.data.id));
+	let activeGroup =
+		layout.dockview.activeGroup && remainingGroups.has(layout.dockview.activeGroup)
+			? layout.dockview.activeGroup
+			: undefined;
+
+	return {
+		...layout,
+		documents,
+		dockview: { ...layout.dockview, panels, activeGroup, grid: { ...layout.dockview.grid, root } },
+	};
+}
+
+export function isLayoutEmpty(layout: MdiLayout): boolean {
+	return Object.keys(layout.documents).length === 0;
+}
+
+/** Spec documents that must always be present (not closable) but are missing from the layout */
+export function missingRequiredDocuments(
+	spec: MdiLayoutSpec,
+	types: MdiDocumentTypes,
+	layout: MdiLayout,
+): (MdiDocumentSpec & { id: string })[] {
+	let missing: (MdiDocumentSpec & { id: string })[] = [];
+
+	function walk(node: MdiLayoutNode) {
+		if (isGroupSpec(node)) {
+			for (let tab of node.tabs) {
+				let definition = resolveType(types, tab.type);
+				let id = specDocumentId(types, tab);
+
+				if (!resolveClosable(definition, tab.closable) && !layout.documents[id]) {
+					missing.push({ ...tab, id });
+				}
+			}
+		} else {
+			node.children.forEach(walk);
+		}
+	}
+
+	walk(spec.root);
+	return missing;
+}
+
+function firstExistingPanel(node: MdiLayoutNode, types: MdiDocumentTypes, existing: Set<string>): string | undefined {
+	if (isGroupSpec(node)) {
+		for (let tab of node.tabs) {
+			let id = specDocumentId(types, tab);
+			if (existing.has(id)) return id;
+		}
+		return undefined;
+	}
+
+	for (let child of node.children) {
+		let found = firstExistingPanel(child, types, existing);
+		if (found) return found;
+	}
+
+	return undefined;
+}
+
+type PlacementResult = { found: boolean; position?: MdiPosition; groupSpec?: MdiGroupSpec };
+
+function findPlacement(
+	node: MdiLayoutNode,
+	id: string,
+	types: MdiDocumentTypes,
+	existing: Set<string>,
+): PlacementResult {
+	if (isGroupSpec(node)) {
+		let ids = node.tabs.map((tab) => specDocumentId(types, tab));
+
+		if (!ids.includes(id)) {
+			return { found: false };
+		}
+
+		let sibling = ids.find((tabId) => tabId !== id && existing.has(tabId));
+		return {
+			found: true,
+			groupSpec: node,
+			position: sibling ? { referencePanel: sibling, direction: "within" } : undefined,
+		};
+	}
+
+	for (let [index, child] of node.children.entries()) {
+		let result = findPlacement(child, id, types, existing);
+		if (!result.found) continue;
+		if (result.position) return result;
+
+		// Place it next to the nearest sibling subtree that still has a panel in the layout.
+		for (let distance = 1; distance < node.children.length; distance++) {
+			for (let siblingIndex of [index - distance, index + distance]) {
+				let sibling = node.children[siblingIndex];
+				if (!sibling) continue;
+
+				let referencePanel = firstExistingPanel(sibling, types, existing);
+				if (!referencePanel) continue;
+
+				let before = siblingIndex < index;
+				let direction: MdiPosition["direction"] =
+					node.direction === "horizontal" ? (before ? "right" : "left") : before ? "below" : "above";
+
+				return { found: true, groupSpec: result.groupSpec, position: { referencePanel, direction } };
+			}
+		}
+
+		return { found: true, groupSpec: result.groupSpec };
+	}
+
+	return { found: false };
+}
+
+/**
+ * Where to add a spec document that is missing from a restored layout: in its spec group
+ * if a sibling tab is still open, otherwise next to the nearest panel of a neighbouring
+ * subtree, otherwise at the right edge.
+ */
+export function placementFor(
+	spec: MdiLayoutSpec,
+	id: string,
+	types: MdiDocumentTypes,
+	existing: Set<string>,
+): { position: MdiPosition; groupSpec?: MdiGroupSpec } {
+	let result = findPlacement(spec.root, id, types, existing);
+	return { position: result.position ?? { direction: "right" }, groupSpec: result.groupSpec };
+}

package/src/mdi/layoutSpec.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+
+import { layoutSpecToLayout, listSpecDocuments, specDocumentId } from "./layoutSpec.js";
+import { testSpec, testTypes } from "./testTypes.js";
+import type { MdiLayoutSpec } from "./types.js";
+
+describe("layoutSpecToLayout", () => {
+	it("builds the documents map with resolved titles and closable flags", () => {
+		let layout = layoutSpecToLayout(testSpec, testTypes, 1);
+
+		expect(layout.format).toBe(1);
+		expect(layout.layoutVersion).toBe(1);
+		expect(Object.keys(layout.documents)).toEqual(["explorer", "editor:a", "editor:b", "properties"]);
+		expect(layout.documents["explorer"]).toEqual({
+			type: "explorer",
+			key: undefined,
+			params: {},
+			title: "Explorer",
+			closable: false,
+		});
+		expect(layout.documents["editor:a"]).toMatchObject({
+			key: "a",
+			params: { name: "A" },
+			title: "Editor A",
+			closable: true,
+		});
+	});
+
+	it("registers every panel on the shared mdi renderer", () => {
+		let layout = layoutSpecToLayout(testSpec, testTypes, 1);
+
+		for (let [id, panel] of Object.entries(layout.dockview.panels)) {
+			expect(panel).toEqual({ id, contentComponent: "mdi", tabComponent: "mdi", title: layout.documents[id]!.title });
+		}
+	});
+
+	it("mirrors the split tree with proportional sizes and alternating orientation", () => {
+		let { dockview } = layoutSpecToLayout(testSpec, testTypes, 1);
+		let root = dockview.grid.root;
+
+		expect(dockview.grid.orientation).toBe("HORIZONTAL");
+		expect(root.type).toBe("branch");
+
+		let [explorer, right] = root.data as { type: string; size?: number; data: unknown }[];
+		expect(explorer!.type).toBe("leaf");
+		expect(explorer!.size).toBe(250);
+		expect(right!.type).toBe("branch");
+		expect(right!.size).toBe(750);
+
+		let [editors, properties] = right!.data as { type: string; size?: number; data: { views: string[] } }[];
+		expect(editors!.size).toBe(750);
+		expect(properties!.size).toBe(250);
+		expect(editors!.data.views).toEqual(["editor:a", "editor:b"]);
+	});
+
+	it("carries group options and the active tab", () => {
+		let { dockview } = layoutSpecToLayout(testSpec, testTypes, 1);
+		let [explorer, right] = dockview.grid.root.data as { data: unknown }[];
+		let explorerGroup = explorer!.data as { id: string; locked?: unknown; hideHeader?: boolean; activeView?: string };
+		let editorsGroup = (right!.data as { data: { activeView?: string } }[])[0]!.data;
+
+		expect(explorerGroup).toMatchObject({
+			id: "mdi-g1",
+			locked: true,
+			hideHeader: true,
+			activeView: "explorer",
+		});
+		expect(editorsGroup.activeView).toBe("editor:b");
+		expect(dockview.activeGroup).toBe("mdi-g1");
+	});
+
+	it("locks a group without a tab bar unless the spec says otherwise", () => {
+		let spec: MdiLayoutSpec = {
+			root: {
+				direction: "horizontal",
+				children: [
+					{ tabs: [{ type: "explorer" }], hideHeader: true },
+					{ tabs: [{ type: "properties" }], hideHeader: true, locked: false },
+					{ tabs: [{ type: "settings" }], locked: "no-drop-target" },
+				],
+			},
+		};
+		let { dockview } = layoutSpecToLayout(spec, testTypes, 1);
+		let groups = (dockview.grid.root.data as { data: { locked?: unknown } }[]).map((leaf) => leaf.data.locked);
+
+		expect(groups).toEqual([true, undefined, "no-drop-target"]);
+	});
+
+	it("wraps a root group in a branch", () => {
+		let layout = layoutSpecToLayout({ root: { tabs: [{ type: "settings" }] } }, testTypes, 0);
+
+		expect(layout.dockview.grid.root.type).toBe("branch");
+		expect((layout.dockview.grid.root.data as unknown[]).length).toBe(1);
+	});
+
+	it("inlines nested splits with the same direction", () => {
+		let spec: MdiLayoutSpec = {
+			root: {
+				direction: "horizontal",
+				children: [
+					{ tabs: [{ type: "explorer" }], size: 2 },
+					{
+						direction: "horizontal",
+						size: 2,
+						children: [{ tabs: [{ type: "settings" }] }, { tabs: [{ type: "properties" }] }],
+					},
+				],
+			},
+		};
+		let { dockview } = layoutSpecToLayout(spec, testTypes, 0);
+		let children = dockview.grid.root.data as { type: string; size?: number }[];
+
+		expect(children.map((child) => child.type)).toEqual(["leaf", "leaf", "leaf"]);
+		expect(children.map((child) => child.size)).toEqual([500, 250, 250]);
+	});
+
+	it("rejects duplicate documents, unknown types and empty groups", () => {
+		expect(() =>
+			layoutSpecToLayout({ root: { tabs: [{ type: "settings" }, { type: "settings" }] } }, testTypes, 0),
+		).toThrow(/more than once/);
+		expect(() => layoutSpecToLayout({ root: { tabs: [{ type: "nope" }] } }, testTypes, 0)).toThrow(
+			/unknown document type/,
+		);
+		expect(() => layoutSpecToLayout({ root: { tabs: [] } }, testTypes, 0)).toThrow(/at least one tab/);
+	});
+
+	it("rejects an active tab that is not in the group", () => {
+		expect(() =>
+			layoutSpecToLayout({ root: { tabs: [{ type: "settings" }], active: "editor:a" } }, testTypes, 0),
+		).toThrow(/not part of its group/);
+	});
+});
+
+describe("spec helpers", () => {
+	it("ignores the key of singleton types", () => {
+		expect(specDocumentId(testTypes, { type: "explorer", key: "ignored" })).toBe("explorer");
+		expect(specDocumentId(testTypes, { type: "editor", key: "x" })).toBe("editor:x");
+	});
+
+	it("lists every document in the spec", () => {
+		expect(listSpecDocuments(testSpec).map((tab) => tab.type)).toEqual(["explorer", "editor", "editor", "properties"]);
+	});
+});

package/src/mdi/layoutSpec.ts

@@ -0,0 +1,214 @@
+import type { GroupviewPanelState, SerializedDockview, SerializedGridObject } from "dockview-react";
+import { Orientation } from "dockview-react";
+
+import { panelId } from "./ids.js";
+import { resolveClosable, resolveTitle, resolveType } from "./registry.js";
+import type {
+	MdiDocumentSpec,
+	MdiDocumentState,
+	MdiDocumentTypes,
+	MdiGroupSpec,
+	MdiLayout,
+	MdiLayoutNode,
+	MdiLayoutSpec,
+	MdiLocked,
+	MdiSplitSpec,
+} from "./types.js";
+
+/** dockview does not export its group state type; derive it from the serialized layout. */
+export type MdiGroupState = SerializedDockview["grid"]["root"] extends SerializedGridObject<infer T> ? T : never;
+
+/** The single dockview component/tab renderer every Mdi panel uses */
+export const MDI_COMPONENT = "mdi";
+
+/**
+ * dockview scales the serialized sizes proportionally to the real container, so the
+ * numbers only need to be consistent relative to each other.
+ */
+const NOMINAL_SIZE = 1000;
+
+export function isGroupSpec(node: MdiLayoutNode): node is MdiGroupSpec {
+	return "tabs" in node;
+}
+
+/** A group without a tab bar refuses drops into it unless the spec says otherwise. */
+export function resolveLocked(group: MdiGroupSpec): MdiLocked {
+	if (group.locked !== undefined) return group.locked;
+	return group.hideHeader ? true : false;
+}
+
+export function specDocumentId(types: MdiDocumentTypes, tab: MdiDocumentSpec): string {
+	let definition = resolveType(types, tab.type);
+	return panelId(tab.type, definition.singleton ? undefined : tab.key);
+}
+
+export function listSpecDocuments(spec: MdiLayoutSpec): MdiDocumentSpec[] {
+	let result: MdiDocumentSpec[] = [];
+
+	function walk(node: MdiLayoutNode) {
+		if (isGroupSpec(node)) {
+			result.push(...node.tabs);
+		} else {
+			node.children.forEach(walk);
+		}
+	}
+
+	walk(spec.root);
+	return result;
+}
+
+type BuildContext = {
+	types: MdiDocumentTypes;
+	documents: Record<string, MdiDocumentState>;
+	panels: Record<string, GroupviewPanelState>;
+	groupCount: number;
+	firstGroup?: string;
+};
+
+function toOrientation(direction: MdiSplitSpec["direction"]): Orientation {
+	return direction === "horizontal" ? Orientation.HORIZONTAL : Orientation.VERTICAL;
+}
+
+function addDocument(tab: MdiDocumentSpec, context: BuildContext): string {
+	let definition = resolveType(context.types, tab.type);
+	let key = definition.singleton ? undefined : tab.key;
+	let id = panelId(tab.type, key);
+
+	if (context.documents[id]) {
+		throw new Error(`Mdi: the layout contains the document "${id}" more than once.`);
+	}
+
+	let params = { ...tab.params };
+	let title = tab.title ?? resolveTitle(definition, tab.type, params, key);
+
+	context.documents[id] = {
+		type: tab.type,
+		key,
+		params,
+		title,
+		closable: resolveClosable(definition, tab.closable),
+	};
+	context.panels[id] = {
+		id,
+		contentComponent: MDI_COMPONENT,
+		tabComponent: MDI_COMPONENT,
+		title,
+	};
+
+	return id;
+}
+
+function serializeGroup(group: MdiGroupSpec, context: BuildContext): MdiGroupState {
+	if (group.tabs.length === 0) {
+		throw new Error("Mdi: every group in the layout needs at least one tab.");
+	}
+
+	context.groupCount += 1;
+	let id = `mdi-g${context.groupCount}`;
+	let views = group.tabs.map((tab) => addDocument(tab, context));
+
+	if (group.active !== undefined && !views.includes(group.active)) {
+		throw new Error(`Mdi: active tab "${group.active}" is not part of its group.`);
+	}
+
+	context.firstGroup ??= id;
+
+	let state: MdiGroupState = {
+		id,
+		views,
+		activeView: group.active ?? views[0],
+	};
+	let locked = resolveLocked(group);
+
+	if (locked) {
+		state.locked = locked;
+	}
+
+	if (group.hideHeader) {
+		state.hideHeader = true;
+	}
+
+	return state;
+}
+
+/**
+ * The children of a split with their normalised weights. dockview alternates the
+ * orientation on every level of the tree, so a nested split with the same direction as
+ * its parent is inlined into the parent instead.
+ */
+function flattenChildren(split: MdiSplitSpec): { node: MdiLayoutNode; weight: number }[] {
+	let result: { node: MdiLayoutNode; weight: number }[] = [];
+	let total = split.children.reduce((sum, child) => sum + (child.size ?? 1), 0) || 1;
+
+	for (let child of split.children) {
+		let weight = (child.size ?? 1) / total;
+
+		if (!isGroupSpec(child) && child.direction === split.direction) {
+			for (let inner of flattenChildren(child)) {
+				result.push({ node: inner.node, weight: weight * inner.weight });
+			}
+		} else {
+			result.push({ node: child, weight });
+		}
+	}
+
+	return result;
+}
+
+/**
+ * A node's `size` is its extent along the parent's axis. A branch's children share the
+ * branch's extent along its own axis, which equals the parent's `size`.
+ */
+function serializeNode(
+	node: MdiLayoutNode,
+	size: number,
+	axisExtent: number,
+	context: BuildContext,
+): SerializedGridObject<MdiGroupState> {
+	if (isGroupSpec(node)) {
+		return { type: "leaf", data: serializeGroup(node, context), size };
+	}
+
+	let children = flattenChildren(node);
+
+	if (children.length === 0) {
+		throw new Error("Mdi: every split in the layout needs at least one child.");
+	}
+
+	return {
+		type: "branch",
+		size,
+		data: children.map((child) => serializeNode(child.node, child.weight * axisExtent, size, context)),
+	};
+}
+
+/** Builds the persisted layout for a layout spec. */
+export function layoutSpecToLayout(
+	spec: MdiLayoutSpec,
+	types: MdiDocumentTypes,
+	layoutVersion: string | number,
+): MdiLayout {
+	let context: BuildContext = { types, documents: {}, panels: {}, groupCount: 0 };
+	let root: SerializedGridObject<MdiGroupState>;
+	let orientation: Orientation;
+
+	if (isGroupSpec(spec.root)) {
+		orientation = Orientation.HORIZONTAL;
+		root = {
+			type: "branch",
+			size: NOMINAL_SIZE,
+			data: [serializeNode(spec.root, NOMINAL_SIZE, NOMINAL_SIZE, context)],
+		};
+	} else {
+		orientation = toOrientation(spec.root.direction);
+		root = serializeNode(spec.root, NOMINAL_SIZE, NOMINAL_SIZE, context);
+	}
+
+	let dockview: SerializedDockview = {
+		grid: { root, width: NOMINAL_SIZE, height: NOMINAL_SIZE, orientation },
+		panels: context.panels,
+		activeGroup: context.firstGroup,
+	};
+
+	return { format: 1, layoutVersion, documents: context.documents, dockview };
+}