@olenbetong/appframe-ds 1.2.0 → 1.3.0

package/src/mdi/layoutRestore.ts

@@ -1,311 +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 };
-}
+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 };
+}