@olenbetong/appframe-ds 0.9.0 → 1.0.0

package/src/mdi/dockviewHost.ts

@@ -0,0 +1,132 @@
+import type { AddPanelOptions, DockviewApi, IDockviewGroupPanel, IDockviewPanel } from "dockview-react";
+
+import type { MdiHost, MdiHostGroup, MdiHostPanel } from "./host.js";
+import { MDI_COMPONENT } from "./layoutSpec.js";
+import type { MdiPosition } from "./types.js";
+
+function wrapGroup(group: IDockviewGroupPanel): MdiHostGroup {
+	return {
+		id: group.id,
+		get panelCount() {
+			return group.panels.length;
+		},
+		setLocked(locked) {
+			group.locked = locked;
+		},
+		setHeaderHidden(hidden) {
+			group.model.header.hidden = hidden;
+		},
+	};
+}
+
+function wrapPanel(panel: IDockviewPanel): MdiHostPanel {
+	return {
+		id: panel.id,
+		get group() {
+			return wrapGroup(panel.group);
+		},
+		setTitle: (title) => panel.api.setTitle(title),
+		setActive: () => panel.api.setActive(),
+		close: () => panel.api.close(),
+		getWindow: () => panel.api.getWindow(),
+	};
+}
+
+function toPosition(position: MdiPosition): AddPanelOptions["position"] {
+	if ("referencePanel" in position) {
+		return { referencePanel: position.referencePanel, direction: position.direction, index: position.index };
+	}
+
+	return { direction: position.direction };
+}
+
+/** A group that shows tabs and accepts documents: not locked, header visible. */
+function isDocumentGroup(group: IDockviewGroupPanel): boolean {
+	return !group.locked && !group.model.header.hidden;
+}
+
+/** Adapts the dockview API to the slice the controller works against. */
+export function createDockviewHost(api: DockviewApi): MdiHost {
+	// Where new documents go by default: the active group, unless that is a fixed pane
+	// (locked or without a tab bar), then the document group that was active most recently.
+	let lastDocumentGroup: string | undefined;
+	api.onDidActivePanelChange((event) => {
+		let group = event.panel?.group;
+		if (group && isDocumentGroup(group)) lastDocumentGroup = group.id;
+	});
+
+	function defaultPosition(): AddPanelOptions["position"] {
+		let active = api.activePanel;
+
+		if (active && isDocumentGroup(active.group)) {
+			return { referencePanel: active.id, direction: "within" };
+		}
+
+		let group = (lastDocumentGroup && api.getGroup(lastDocumentGroup)) || api.groups.find(isDocumentGroup);
+		return group ? { referenceGroup: group.id, direction: "within" } : undefined;
+	}
+
+	return {
+		addPanel({ id, title, position, inactive }) {
+			let panel = api.addPanel({
+				id,
+				title,
+				component: MDI_COMPONENT,
+				tabComponent: MDI_COMPONENT,
+				position: position ? toPosition(position) : defaultPosition(),
+				inactive,
+			});
+
+			return wrapPanel(panel);
+		},
+		getPanel(id) {
+			let panel = api.getPanel(id);
+			return panel ? wrapPanel(panel) : undefined;
+		},
+		getGroup(id) {
+			let group = api.getGroup(id);
+			return group ? wrapGroup(group) : undefined;
+		},
+		getActivePanelId: () => api.activePanel?.id,
+		toJSON: () => api.toJSON(),
+		fromJSON: (data) => api.fromJSON(data),
+		async addPopoutGroup(id, popoutUrl) {
+			let panel = api.getPanel(id);
+			return panel ? api.addPopoutGroup(panel, { popoutUrl }) : false;
+		},
+		onDidActivePanelChange(handler) {
+			let disposable = api.onDidActivePanelChange((event) => handler(event.panel?.id));
+			return () => disposable.dispose();
+		},
+		onDidRemovePanel(handler) {
+			let disposable = api.onDidRemovePanel((panel) => handler(panel.id));
+			return () => disposable.dispose();
+		},
+		onDidLayoutChange(handler) {
+			let disposable = api.onDidLayoutChange(() => handler());
+			return () => disposable.dispose();
+		},
+	};
+}
+
+/**
+ * dockview copies the stylesheets into a popout window, but not the attributes
+ * Designsystemet keys its tokens off (`data-color-scheme`, `data-size`, `lang`, …).
+ */
+export function copyDocumentAttributes(from: Document, to: Document) {
+	let pairs: [Element, Element][] = [
+		[from.documentElement, to.documentElement],
+		[from.body, to.body],
+	];
+
+	for (let [source, target] of pairs) {
+		for (let attribute of Array.from(source.attributes)) {
+			if (attribute.name === "lang" || attribute.name === "class" || attribute.name.startsWith("data-")) {
+				target.setAttribute(attribute.name, attribute.value);
+			}
+		}
+	}
+
+	to.body.style.margin = "0";
+	to.body.style.overflow = "hidden";
+}

package/src/mdi/fakeHost.ts

@@ -0,0 +1,200 @@
+import type { SerializedDockview } from "dockview-react";
+
+import type { MdiHost, MdiHostAddPanelOptions, MdiHostGroup, MdiHostPanel } from "./host.js";
+import type { MdiGroupState } from "./layoutSpec.js";
+import type { MdiLocked } from "./types.js";
+
+type FakePanel = { id: string; title: string; groupId: string };
+type FakeGroup = { id: string; locked: MdiLocked; headerHidden: boolean };
+
+/**
+ * An in-memory stand-in for dockview: one flat list of groups, panels with a title
+ * and a group, and the events the controller listens to.
+ */
+export function createFakeHost() {
+	let panels = new Map<string, FakePanel>();
+	let groups = new Map<string, FakeGroup>();
+	let activeId: string | undefined;
+	let groupCounter = 0;
+	let activeHandlers: ((id: string | undefined) => void)[] = [];
+	let removeHandlers: ((id: string) => void)[] = [];
+	let layoutHandlers: (() => void)[] = [];
+	let popouts: { id: string; popoutUrl: string }[] = [];
+
+	function fireLayout() {
+		for (let handler of layoutHandlers) handler();
+	}
+
+	function setActive(id: string | undefined) {
+		if (id === activeId) return;
+		activeId = id;
+		for (let handler of activeHandlers) handler(id);
+	}
+
+	function newGroup(): FakeGroup {
+		groupCounter += 1;
+		let group = { id: `fake-g${groupCounter}`, locked: false, headerHidden: false };
+		groups.set(group.id, group);
+		return group;
+	}
+
+	function wrapGroup(group: FakeGroup): MdiHostGroup {
+		return {
+			id: group.id,
+			get panelCount() {
+				return [...panels.values()].filter((other) => other.groupId === group.id).length;
+			},
+			setLocked: (locked) => {
+				group.locked = locked;
+			},
+			setHeaderHidden: (hidden) => {
+				group.headerHidden = hidden;
+			},
+		};
+	}
+
+	function wrap(panel: FakePanel): MdiHostPanel {
+		return {
+			id: panel.id,
+			get group() {
+				return wrapGroup(groups.get(panel.groupId)!);
+			},
+			setTitle: (title: string) => {
+				panel.title = title;
+			},
+			setActive: () => setActive(panel.id),
+			close: () => {
+				panels.delete(panel.id);
+				for (let handler of removeHandlers) handler(panel.id);
+				if (activeId === panel.id) {
+					setActive([...panels.keys()][0]);
+				}
+				fireLayout();
+			},
+			getWindow: () => globalThis.window,
+		};
+	}
+
+	let host: MdiHost = {
+		addPanel({ id, title, position, inactive }: MdiHostAddPanelOptions) {
+			let groupId: string;
+
+			if (position && "referencePanel" in position && position.direction === "within") {
+				groupId = panels.get(position.referencePanel)?.groupId ?? newGroup().id;
+			} else if (!position && activeId) {
+				groupId = panels.get(activeId)!.groupId;
+			} else {
+				groupId = newGroup().id;
+			}
+
+			let panel = { id, title, groupId };
+			panels.set(id, panel);
+			if (!inactive) setActive(id);
+			fireLayout();
+
+			return wrap(panel);
+		},
+		getPanel(id) {
+			let panel = panels.get(id);
+			return panel ? wrap(panel) : undefined;
+		},
+		getGroup(id) {
+			let group = groups.get(id);
+			return group ? wrapGroup(group) : undefined;
+		},
+		getActivePanelId: () => activeId,
+		toJSON() {
+			let groupStates: MdiGroupState[] = [...groups.values()].map((group) => ({
+				id: group.id,
+				views: [...panels.values()].filter((panel) => panel.groupId === group.id).map((panel) => panel.id),
+				activeView: activeId && panels.get(activeId)?.groupId === group.id ? activeId : undefined,
+				locked: group.locked || undefined,
+				hideHeader: group.headerHidden || undefined,
+			}));
+
+			return {
+				grid: {
+					root: { type: "branch", size: 1000, data: groupStates.map((data) => ({ type: "leaf", data, size: 1000 })) },
+					width: 1000,
+					height: 1000,
+					orientation: "HORIZONTAL" as SerializedDockview["grid"]["orientation"],
+				},
+				panels: Object.fromEntries(
+					[...panels.values()].map((panel) => [
+						panel.id,
+						{ id: panel.id, contentComponent: "mdi", title: panel.title },
+					]),
+				),
+				activeGroup: activeId ? panels.get(activeId)?.groupId : undefined,
+			};
+		},
+		fromJSON(data) {
+			// Mimic dockview: existing panels are removed (and reported) before the new ones are created.
+			for (let id of panels.keys()) {
+				panels.delete(id);
+				for (let handler of removeHandlers) handler(id);
+			}
+			groups.clear();
+			activeId = undefined;
+
+			function visit(node: { type: string; data: unknown }) {
+				if (node.type === "leaf") {
+					let state = node.data as MdiGroupState;
+					// dockview reduces `locked` to a boolean here; the controller puts the stricter value back.
+					groups.set(state.id, { id: state.id, locked: !!state.locked, headerHidden: !!state.hideHeader });
+					for (let view of state.views) {
+						let title = data.panels[view]?.title ?? view;
+						panels.set(view, { id: view, title, groupId: state.id });
+					}
+					if (state.id === data.activeGroup) {
+						activeId = state.activeView ?? state.views[0];
+					}
+				} else {
+					for (let child of node.data as { type: string; data: unknown }[]) visit(child);
+				}
+			}
+
+			visit(data.grid.root);
+			activeId ??= [...panels.keys()][0];
+			for (let handler of activeHandlers) handler(activeId);
+			fireLayout();
+		},
+		async addPopoutGroup(id, popoutUrl) {
+			if (!panels.has(id)) return false;
+			popouts.push({ id, popoutUrl });
+			return true;
+		},
+		onDidActivePanelChange(handler) {
+			activeHandlers.push(handler);
+			return () => {
+				activeHandlers = activeHandlers.filter((other) => other !== handler);
+			};
+		},
+		onDidRemovePanel(handler) {
+			removeHandlers.push(handler);
+			return () => {
+				removeHandlers = removeHandlers.filter((other) => other !== handler);
+			};
+		},
+		onDidLayoutChange(handler) {
+			layoutHandlers.push(handler);
+			return () => {
+				layoutHandlers = layoutHandlers.filter((other) => other !== handler);
+			};
+		},
+	};
+
+	return {
+		host,
+		panels,
+		groups,
+		popouts,
+		get activeId() {
+			return activeId;
+		},
+		/** Simulates the user activating a tab */
+		activate: setActive,
+		/** Simulates a layout change such as a sash drag */
+		fireLayout,
+	};
+}

package/src/mdi/host.ts

@@ -0,0 +1,44 @@
+import type { SerializedDockview } from "dockview-react";
+
+import type { MdiLocked, MdiPosition } from "./types.js";
+
+export type MdiHostGroup = {
+	id: string;
+	panelCount: number;
+	setLocked(locked: MdiLocked): void;
+	setHeaderHidden(hidden: boolean): void;
+};
+
+export type MdiHostPanel = {
+	id: string;
+	group: MdiHostGroup;
+	setTitle(title: string): void;
+	setActive(): void;
+	/** Removes the panel from dockview. Fires `onDidRemovePanel`. */
+	close(): void;
+	getWindow(): Window;
+};
+
+export type MdiHostAddPanelOptions = {
+	id: string;
+	title: string;
+	position?: MdiPosition;
+	inactive?: boolean;
+};
+
+/**
+ * The slice of the dockview API the controller uses. Narrow on purpose, so the
+ * controller can be tested against an in-memory fake.
+ */
+export type MdiHost = {
+	addPanel(options: MdiHostAddPanelOptions): MdiHostPanel;
+	getPanel(id: string): MdiHostPanel | undefined;
+	getGroup(id: string): MdiHostGroup | undefined;
+	getActivePanelId(): string | undefined;
+	toJSON(): SerializedDockview;
+	fromJSON(data: SerializedDockview): void;
+	addPopoutGroup(id: string, popoutUrl: string): Promise<boolean>;
+	onDidActivePanelChange(handler: (id: string | undefined) => void): () => void;
+	onDidRemovePanel(handler: (id: string) => void): () => void;
+	onDidLayoutChange(handler: () => void): () => void;
+};

package/src/mdi/ids.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { panelId, parsePanelId } from "./ids.js";
+
+describe("panel ids", () => {
+	it("uses the type alone when there is no key", () => {
+		expect(panelId("explorer")).toBe("explorer");
+		expect(parsePanelId("explorer")).toEqual({ type: "explorer" });
+	});
+
+	it("joins type and key with a colon", () => {
+		expect(panelId("editor", "42")).toBe("editor:42");
+		expect(parsePanelId("editor:42")).toEqual({ type: "editor", key: "42" });
+	});
+
+	it("round-trips keys that contain colons", () => {
+		let id = panelId("editor", "a:b:c");
+		expect(parsePanelId(id)).toEqual({ type: "editor", key: "a:b:c" });
+	});
+});

package/src/mdi/ids.ts

@@ -0,0 +1,18 @@
+/**
+ * The panel id scheme: `type` for documents without a key (singletons) and `type:key`
+ * otherwise. Deterministic ids make "open or activate" a lookup, and join the
+ * `documents` map with dockview's own panel list.
+ */
+export function panelId(type: string, key?: string): string {
+	return key === undefined ? type : `${type}:${key}`;
+}
+
+export function parsePanelId(id: string): { type: string; key?: string } {
+	let separator = id.indexOf(":");
+
+	if (separator === -1) {
+		return { type: id };
+	}
+
+	return { type: id.slice(0, separator), key: id.slice(separator + 1) };
+}

package/src/mdi/index.ts

@@ -0,0 +1,31 @@
+export { Mdi, type MdiProps } from "./Mdi.js";
+export { MdiProvider, type MdiProviderProps, useMdi, useMdiActiveDocument, useMdiDocuments } from "./MdiContext.js";
+export { useMdiDocument } from "./MdiDocumentContext.js";
+export { MdiConfirmCloseDialog, type MdiConfirmCloseDialogProps } from "./MdiConfirmCloseDialog.js";
+export { panelId, parsePanelId } from "./ids.js";
+export { layoutSpecToLayout } from "./layoutSpec.js";
+export type {
+	MdiApi,
+	MdiCloseOptions,
+	MdiConfirmCloseResult,
+	MdiDirection,
+	MdiDocumentHandle,
+	MdiDocumentInfo,
+	MdiDocumentOptions,
+	MdiDocumentProps,
+	MdiDocumentSpec,
+	MdiDocumentState,
+	MdiDocumentType,
+	MdiDocumentTypes,
+	MdiEvents,
+	MdiGroupSpec,
+	MdiLayout,
+	MdiLayoutNode,
+	MdiLayoutSpec,
+	MdiLocked,
+	MdiOpenOptions,
+	MdiParams,
+	MdiPosition,
+	MdiRestoreResult,
+	MdiSplitSpec,
+} from "./types.js";

package/src/mdi/layoutRestore.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "vitest";
+
+import { dockPopoutGroups, missingRequiredDocuments, placementFor, pruneLayout } from "./layoutRestore.js";
+import { layoutSpecToLayout, type MdiGroupState } from "./layoutSpec.js";
+import { testSpec, testTypes } from "./testTypes.js";
+import type { MdiLayout } from "./types.js";
+
+type Node = { type: string; size?: number; visible?: boolean; data: Node[] | MdiGroupState };
+
+function leaves(node: Node): MdiGroupState[] {
+	return node.type === "leaf" ? [node.data as MdiGroupState] : (node.data as Node[]).flatMap(leaves);
+}
+
+function baseLayout(): MdiLayout {
+	return layoutSpecToLayout(testSpec, testTypes, 1);
+}
+
+describe("dockPopoutGroups", () => {
+	it("returns the layout untouched when nothing is popped out", () => {
+		let layout = baseLayout();
+		let result = dockPopoutGroups(layout.dockview);
+
+		expect(result.grid).toEqual(layout.dockview.grid);
+		expect(result.popoutGroups).toBeUndefined();
+	});
+
+	it("puts a popped-out group back into its hidden reference group", () => {
+		let layout = baseLayout();
+		let root = layout.dockview.grid.root as Node;
+		let explorerLeaf = (root.data as Node[])[0]!;
+		explorerLeaf.visible = false;
+		(explorerLeaf.data as MdiGroupState).views = [];
+		delete (explorerLeaf.data as MdiGroupState).activeView;
+		layout.dockview.popoutGroups = [
+			{
+				data: { id: "popout-1", views: ["explorer"], activeView: "explorer" },
+				gridReferenceGroup: "mdi-g1",
+				position: null,
+			},
+		];
+
+		let result = dockPopoutGroups(layout.dockview);
+		let restored = (result.grid.root.data as Node[])[0]!;
+
+		expect(result.popoutGroups).toBeUndefined();
+		expect(restored.visible).toBeUndefined();
+		expect((restored.data as MdiGroupState).views).toEqual(["explorer"]);
+		expect((restored.data as MdiGroupState).activeView).toBe("explorer");
+	});
+
+	it("appends a popped-out group to the root when it has no reference group", () => {
+		let layout = baseLayout();
+		layout.dockview.popoutGroups = [
+			{ data: { id: "mdi-g1", views: ["settings"], activeView: "settings" }, position: null },
+		];
+		layout.dockview.floatingGroups = [
+			{ data: { id: "float", views: ["editor:c"] }, position: { top: 0, left: 0, width: 100, height: 100 } },
+		];
+
+		let result = dockPopoutGroups(layout.dockview);
+		let ids = leaves(result.grid.root as Node).map((group) => group.id);
+
+		expect(ids).toEqual(["mdi-g1", "mdi-g2", "mdi-g3", "mdi-g1-docked", "float"]);
+		expect(result.floatingGroups).toBeUndefined();
+	});
+});
+
+describe("pruneLayout", () => {
+	it("drops documents, panels, empty groups and collapses single-leaf branches", () => {
+		let layout = baseLayout();
+		let pruned = pruneLayout(layout, new Set(["explorer", "editor:a"]));
+
+		expect(Object.keys(pruned.documents)).toEqual(["explorer", "editor:a"]);
+		expect(Object.keys(pruned.dockview.panels)).toEqual(["explorer", "editor:a"]);
+
+		let root = pruned.dockview.grid.root as Node;
+		let children = root.data as Node[];
+		expect(children).toHaveLength(2);
+		// The vertical branch lost its properties group and now wraps a single leaf, so it collapses.
+		expect(children[1]!.type).toBe("leaf");
+		expect(children[1]!.size).toBe(750);
+		expect((children[1]!.data as MdiGroupState).views).toEqual(["editor:a"]);
+		expect((children[1]!.data as MdiGroupState).activeView).toBe("editor:a");
+	});
+
+	it("clears the active group when it was removed", () => {
+		let layout = baseLayout();
+		let pruned = pruneLayout(layout, new Set(["editor:a"]));
+
+		expect(pruned.dockview.activeGroup).toBeUndefined();
+	});
+
+	it("keeps the active group when it survives", () => {
+		let layout = baseLayout();
+		let pruned = pruneLayout(layout, new Set(["explorer"]));
+
+		expect(pruned.dockview.activeGroup).toBe("mdi-g1");
+	});
+
+	it("returns an empty root when nothing is kept", () => {
+		let pruned = pruneLayout(baseLayout(), new Set());
+
+		expect(pruned.documents).toEqual({});
+		expect(pruned.dockview.grid.root).toEqual({ type: "branch", size: 1000, data: [] });
+	});
+});
+
+describe("missingRequiredDocuments", () => {
+	it("lists unclosable spec documents that are not in the layout", () => {
+		let layout = pruneLayout(baseLayout(), new Set(["editor:a", "editor:b"]));
+		let missing = missingRequiredDocuments(testSpec, testTypes, layout);
+
+		expect(missing.map((document) => document.id)).toEqual(["explorer", "properties"]);
+	});
+
+	it("is empty for the default layout", () => {
+		expect(missingRequiredDocuments(testSpec, testTypes, baseLayout())).toEqual([]);
+	});
+});
+
+describe("placementFor", () => {
+	it("places a document with an open sibling tab in that group", () => {
+		let existing = new Set(["explorer", "editor:b"]);
+		expect(placementFor(testSpec, "editor:a", testTypes, existing).position).toEqual({
+			referencePanel: "editor:b",
+			direction: "within",
+		});
+	});
+
+	it("places a document next to the nearest sibling subtree", () => {
+		let existing = new Set(["explorer", "editor:a"]);
+		let { position, groupSpec } = placementFor(testSpec, "properties", testTypes, existing);
+
+		expect(position).toEqual({ referencePanel: "editor:a", direction: "below" });
+		expect(groupSpec?.tabs[0]?.type).toBe("properties");
+	});
+
+	it("walks up to the parent split when the sibling subtree is empty", () => {
+		let existing = new Set(["explorer"]);
+		expect(placementFor(testSpec, "properties", testTypes, existing).position).toEqual({
+			referencePanel: "explorer",
+			direction: "right",
+		});
+		expect(placementFor(testSpec, "explorer", testTypes, new Set(["editor:a"])).position).toEqual({
+			referencePanel: "editor:a",
+			direction: "left",
+		});
+	});
+
+	it("falls back to the right edge", () => {
+		expect(placementFor(testSpec, "explorer", testTypes, new Set()).position).toEqual({ direction: "right" });
+		expect(placementFor(testSpec, "settings", testTypes, new Set(["explorer"])).position).toEqual({
+			direction: "right",
+		});
+	});
+});