@olenbetong/appframe-ds 0.9.1 → 1.0.0

package/src/mdi/controller.ts

@@ -0,0 +1,656 @@
+import mitt, { type Emitter } from "mitt";
+
+import type { MdiHost } from "./host.js";
+import { panelId } from "./ids.js";
+import {
+	dockPopoutGroups,
+	isLayoutEmpty,
+	listGridGroups,
+	missingRequiredDocuments,
+	placementFor,
+	pruneLayout,
+} from "./layoutRestore.js";
+import { layoutSpecToLayout, resolveLocked } from "./layoutSpec.js";
+import { layoutStore as defaultLayoutStore, type MdiLayoutStore } from "./layoutStore.js";
+import { resolveClosable, resolveTitle, resolveType } from "./registry.js";
+import type {
+	MdiApi,
+	MdiCloseOptions,
+	MdiConfirmCloseResult,
+	MdiDocumentInfo,
+	MdiDocumentOptions,
+	MdiDocumentState,
+	MdiDocumentTypes,
+	MdiEvents,
+	MdiLayout,
+	MdiLayoutSpec,
+	MdiOpenOptions,
+	MdiParams,
+} from "./types.js";
+
+export type MdiControllerOptions = {
+	/** Storage key within the article. Without it nothing is restored or saved. */
+	id?: string;
+	layoutVersion: string | number;
+	defaultLayout: MdiLayoutSpec;
+	/** Save every layout change automatically. Off: only `saveLayout()` writes, but a saved layout is still restored on load. */
+	persist: boolean;
+	popoutUrl: string;
+	confirmClose: (document: MdiDocumentInfo) => Promise<MdiConfirmCloseResult>;
+};
+
+type InternalDocument = MdiDocumentState & { dirty: boolean };
+
+type StoreEvents = MdiEvents & { change: undefined };
+
+/**
+ * Owns the documents of one `Mdi`: the registry lookup, the open/close/dirty
+ * lifecycle, restore and persistence. Talks to dockview through the narrow
+ * `MdiHost` interface so it can be tested without a DOM. The React layer is a thin
+ * shell around it; `MdiProvider` creates one and `useMdi()` hands it out.
+ */
+export class MdiController implements MdiApi {
+	#types: MdiDocumentTypes;
+	#store: MdiLayoutStore;
+	#documents = new Map<string, InternalDocument>();
+	#guards = new Map<string, MdiDocumentOptions>();
+	#emitter: Emitter<StoreEvents> = mitt<StoreEvents>();
+	#host: MdiHost | undefined;
+	#hostDisposables: (() => void)[] = [];
+	#options: MdiControllerOptions | undefined;
+	#activeId: string | undefined;
+	#infoCache = new Map<string, MdiDocumentInfo>();
+	#listCache: MdiDocumentInfo[] | undefined;
+	#emptyList: MdiDocumentInfo[] = [];
+	#initialized = false;
+	#applying = false;
+	#generation = 0;
+
+	constructor(types: MdiDocumentTypes, store: MdiLayoutStore = defaultLayoutStore) {
+		this.#types = types;
+		this.#store = store;
+	}
+
+	getTypes(): MdiDocumentTypes {
+		return this.#types;
+	}
+
+	setTypes(types: MdiDocumentTypes) {
+		this.#types = types;
+	}
+
+	setOptions(options: MdiControllerOptions) {
+		this.#options = options;
+	}
+
+	get isAttached(): boolean {
+		return this.#host !== undefined;
+	}
+
+	/* ---------------------------------------------------------------- host */
+
+	attach(host: MdiHost) {
+		this.detach();
+		this.#host = host;
+		this.#hostDisposables = [
+			host.onDidActivePanelChange((id) => this.#setActive(id)),
+			host.onDidRemovePanel((id) => this.#handleRemoved(id)),
+			host.onDidLayoutChange(() => {
+				if (this.#applying) return;
+				this.#emitter.emit("layoutChange", undefined);
+				this.#scheduleSave();
+			}),
+		];
+	}
+
+	detach() {
+		for (let dispose of this.#hostDisposables) dispose();
+		this.#hostDisposables = [];
+		this.#host = undefined;
+		this.#initialized = false;
+		this.#generation += 1;
+	}
+
+	/**
+	 * Restores the persisted layout (dropping documents the app no longer wants) or
+	 * applies the default one, then makes sure every fixed pane is present.
+	 */
+	async initialize(): Promise<void> {
+		let options = this.#requireOptions();
+		let generation = ++this.#generation;
+		let key = this.#storageKey();
+		let layout: MdiLayout | undefined;
+
+		if (key) {
+			await this.#store.loaded;
+			if (generation !== this.#generation) return;
+
+			let persisted = this.#store.get(key, options.layoutVersion);
+
+			if (persisted) {
+				layout = await this.#resolvePersisted(persisted);
+				if (generation !== this.#generation) return;
+			}
+		}
+
+		this.#applyRestoredOrDefault(layout);
+	}
+
+	/* ---------------------------------------------------------- documents */
+
+	openDocument<P extends MdiParams = MdiParams>(options: MdiOpenOptions<P>): string {
+		let host = this.#requireHost();
+		let definition = resolveType(this.#types, options.type);
+		let key = definition.singleton ? undefined : options.key;
+		let id = panelId(options.type, key);
+		let existing = this.#documents.get(id);
+
+		if (existing) {
+			let changed = false;
+
+			if (options.params) {
+				existing.params = { ...options.params };
+				changed = true;
+			}
+
+			if (options.title !== undefined && options.title !== existing.title) {
+				existing.title = options.title;
+				host.getPanel(id)?.setTitle(options.title);
+				this.#emitter.emit("titleChange", { id, title: options.title });
+				changed = true;
+			}
+
+			if (changed) {
+				this.#invalidate(id);
+				this.#scheduleSave();
+			}
+
+			if (!options.inactive) {
+				this.activate(id);
+			}
+
+			return id;
+		}
+
+		let params: MdiParams = { ...options.params };
+		let title = options.title ?? resolveTitle(definition, options.type, params, key);
+
+		this.#documents.set(id, {
+			type: options.type,
+			key,
+			params,
+			title,
+			closable: resolveClosable(definition, options.closable),
+			dirty: false,
+		});
+
+		host.addPanel({ id, title, position: options.position, inactive: options.inactive });
+		this.#invalidate(id);
+		this.#emitter.emit("open", this.getDocument(id)!);
+		this.#scheduleSave();
+
+		return id;
+	}
+
+	activate(id: string) {
+		this.#host?.getPanel(id)?.setActive();
+	}
+
+	async close(id: string, options: MdiCloseOptions = {}): Promise<boolean> {
+		let document = this.#documents.get(id);
+
+		if (!document) {
+			return false;
+		}
+
+		if (!options.force) {
+			if (!document.closable) {
+				return false;
+			}
+
+			let guards = this.#guards.get(id);
+
+			if (guards?.onClosing && !(await guards.onClosing())) {
+				return false;
+			}
+
+			if (document.dirty) {
+				let result = await this.#requireOptions().confirmClose(this.getDocument(id)!);
+
+				if (result === "cancel") {
+					return false;
+				}
+
+				if (result === "save") {
+					let saved = guards?.onSave ? await guards.onSave() : true;
+
+					if (!saved) {
+						return false;
+					}
+				}
+			}
+		}
+
+		// The document may have gone away while a guard was pending.
+		if (!this.#documents.has(id)) {
+			return true;
+		}
+
+		let panel = this.#host?.getPanel(id);
+
+		if (panel) {
+			panel.close();
+		} else {
+			this.#handleRemoved(id, true);
+		}
+
+		return true;
+	}
+
+	async closeByKey(key: string, options: MdiCloseOptions = { force: true }): Promise<void> {
+		let ids = [...this.#documents.entries()].filter(([, document]) => document.key === key).map(([id]) => id);
+
+		for (let id of ids) {
+			await this.close(id, options);
+		}
+	}
+
+	async closeAll(type?: string): Promise<boolean> {
+		let ids = [...this.#documents.entries()]
+			.filter(([, document]) => document.closable && (type === undefined || document.type === type))
+			.map(([id]) => id);
+
+		for (let id of ids) {
+			if (this.#documents.has(id) && !(await this.close(id))) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	setTitle(id: string, title: string) {
+		let document = this.#documents.get(id);
+
+		if (!document || document.title === title) {
+			return;
+		}
+
+		document.title = title;
+		this.#host?.getPanel(id)?.setTitle(title);
+		this.#invalidate(id);
+		this.#emitter.emit("titleChange", { id, title });
+		this.#scheduleSave();
+	}
+
+	setDirty(id: string, dirty: boolean) {
+		let document = this.#documents.get(id);
+
+		if (!document || document.dirty === dirty) {
+			return;
+		}
+
+		document.dirty = dirty;
+		this.#invalidate(id);
+		this.#emitter.emit("dirtyChange", { id, dirty });
+	}
+
+	getActive = (): MdiDocumentInfo | undefined => {
+		return this.#activeId ? this.getDocument(this.#activeId) : undefined;
+	};
+
+	getDocument = (id: string): MdiDocumentInfo | undefined => {
+		let cached = this.#infoCache.get(id);
+
+		if (cached) {
+			return cached;
+		}
+
+		let document = this.#documents.get(id);
+
+		if (!document) {
+			return undefined;
+		}
+
+		let info: MdiDocumentInfo = { ...document, id, isActive: id === this.#activeId };
+		this.#infoCache.set(id, info);
+
+		return info;
+	};
+
+	/** Every open document, in insertion order. Referentially stable until something changes. */
+	getDocumentsSnapshot = (): MdiDocumentInfo[] => {
+		if (!this.#listCache) {
+			let list = [...this.#documents.keys()].map((id) => this.getDocument(id)!);
+			this.#listCache = list.length === 0 ? this.#emptyList : list;
+		}
+
+		return this.#listCache;
+	};
+
+	getDocuments(type?: string): MdiDocumentInfo[] {
+		let all = this.getDocumentsSnapshot();
+		return type === undefined ? [...all] : all.filter((document) => document.type === type);
+	}
+
+	hasDirty(): boolean {
+		for (let document of this.#documents.values()) {
+			if (document.dirty) return true;
+		}
+
+		return false;
+	}
+
+	async popout(id: string): Promise<boolean> {
+		let host = this.#requireHost();
+		return host.addPopoutGroup(id, this.#requireOptions().popoutUrl);
+	}
+
+	getWindow(id: string): Window {
+		return this.#host?.getPanel(id)?.getWindow() ?? globalThis.window;
+	}
+
+	panelId(type: string, key?: string): string {
+		let definition = this.#types[type];
+		return panelId(type, definition?.singleton ? undefined : key);
+	}
+
+	/* -------------------------------------------------------------- guards */
+
+	/** Registers the close guards of a mounted document component. Returns the unregister function. */
+	registerGuards(id: string, guards: MdiDocumentOptions): () => void {
+		this.#guards.set(id, guards);
+
+		return () => {
+			// Another instance may already have registered for the same id (React remounts).
+			if (this.#guards.get(id) === guards) {
+				this.#guards.delete(id);
+			}
+		};
+	}
+
+	/* -------------------------------------------------------------- events */
+
+	subscribe<K extends keyof MdiEvents>(event: K, handler: (event: MdiEvents[K]) => void): () => void {
+		this.#emitter.on(event, handler);
+		return () => this.#emitter.off(event, handler);
+	}
+
+	/** Fires on every change of the document list, a document, or the active document. For `useSyncExternalStore`. */
+	subscribeStore = (handler: () => void): (() => void) => {
+		this.#emitter.on("change", handler);
+		return () => this.#emitter.off("change", handler);
+	};
+
+	/* -------------------------------------------------------------- layout */
+
+	getLayout(): MdiLayout | undefined {
+		if (!this.#host || !this.#options) {
+			return undefined;
+		}
+
+		let documents: Record<string, MdiDocumentState> = {};
+
+		for (let [id, document] of this.#documents) {
+			let { dirty: _dirty, ...state } = document;
+			documents[id] = state;
+		}
+
+		return {
+			format: 1,
+			layoutVersion: this.#options.layoutVersion,
+			documents,
+			dockview: this.#host.toJSON(),
+		};
+	}
+
+	async saveLayout(): Promise<MdiLayout | undefined> {
+		let key = this.#storageKey();
+		let layout = this.getLayout();
+
+		if (key && layout) {
+			await this.#store.setNow(key, layout);
+		}
+
+		return layout;
+	}
+
+	async loadLayout(layout?: MdiLayout): Promise<void> {
+		let options = this.#requireOptions();
+		let key = this.#storageKey();
+		let source = layout ?? (key ? this.#store.get(key, options.layoutVersion) : undefined);
+		let resolved = source ? await this.#resolvePersisted(source) : undefined;
+
+		this.#applyRestoredOrDefault(resolved);
+	}
+
+	async resetLayout(): Promise<void> {
+		let key = this.#storageKey();
+
+		if (key) {
+			await this.#store.remove(key);
+		}
+
+		this.#applyRestoredOrDefault(undefined);
+	}
+
+	/* ------------------------------------------------------------ internal */
+
+	#requireHost(): MdiHost {
+		if (!this.#host) {
+			throw new Error("Mdi: no dock is mounted yet. Open documents after <Mdi> has rendered.");
+		}
+
+		return this.#host;
+	}
+
+	#requireOptions(): MdiControllerOptions {
+		if (!this.#options) {
+			throw new Error("Mdi: the controller has no options. Render <Mdi> inside the provider first.");
+		}
+
+		return this.#options;
+	}
+
+	#storageKey(): string | undefined {
+		let id = this.#options?.id;
+		return id ? this.#store.key(id) : undefined;
+	}
+
+	#defaultLayout(): MdiLayout {
+		let options = this.#requireOptions();
+		return layoutSpecToLayout(options.defaultLayout, this.#types, options.layoutVersion);
+	}
+
+	#applyRestoredOrDefault(layout: MdiLayout | undefined) {
+		let options = this.#requireOptions();
+
+		if (layout && !isLayoutEmpty(layout)) {
+			try {
+				this.#applyLayout(layout);
+			} catch (error) {
+				console.warn("Mdi: could not apply the saved layout, falling back to the default.", error);
+				layout = undefined;
+			}
+		} else {
+			layout = undefined;
+		}
+
+		if (!layout) {
+			layout = this.#defaultLayout();
+			this.#applyLayout(layout);
+		}
+
+		this.#initialized = true;
+		this.#addMissingRequired(options.defaultLayout, layout);
+	}
+
+	/** Re-docks popouts, runs the `restore` resolvers and drops what they reject. */
+	async #resolvePersisted(persisted: MdiLayout): Promise<MdiLayout> {
+		let layout: MdiLayout = { ...persisted, dockview: dockPopoutGroups(persisted.dockview) };
+		let keep = new Set<string>();
+		let documents: Record<string, MdiDocumentState> = {};
+
+		await Promise.all(
+			Object.entries(layout.documents).map(async ([id, document]) => {
+				let definition = this.#types[document.type];
+
+				if (!definition) {
+					console.warn(`Mdi: dropping document "${id}", its type is no longer registered.`);
+					return;
+				}
+
+				try {
+					let result = definition.restore
+						? await definition.restore({ key: document.key, params: document.params })
+						: true;
+
+					if (result === false) {
+						return;
+					}
+
+					let state: MdiDocumentState = { ...document, params: { ...document.params } };
+
+					if (typeof result === "object") {
+						if (result.params) state.params = { ...result.params };
+						if (result.title !== undefined) state.title = result.title;
+					}
+
+					keep.add(id);
+					documents[id] = state;
+				} catch (error) {
+					console.warn(`Mdi: dropping document "${id}", restore failed.`, error);
+				}
+			}),
+		);
+
+		let pruned = pruneLayout({ ...layout, documents }, keep);
+
+		for (let [id, document] of Object.entries(pruned.documents)) {
+			let panel = pruned.dockview.panels[id];
+			if (panel) panel.title = document.title;
+		}
+
+		return pruned;
+	}
+
+	#applyLayout(layout: MdiLayout) {
+		let host = this.#requireHost();
+
+		this.#applying = true;
+
+		try {
+			this.#documents.clear();
+			this.#guards.clear();
+
+			for (let [id, document] of Object.entries(layout.documents)) {
+				this.#documents.set(id, { ...document, params: { ...document.params }, dirty: false });
+			}
+
+			host.fromJSON(structuredClone(layout.dockview));
+
+			// dockview's fromJSON reduces `locked` to a boolean, which still allows drops beside
+			// the group; put the stricter value back.
+			for (let group of listGridGroups(layout.dockview)) {
+				if (group.locked === "no-drop-target") host.getGroup(group.id)?.setLocked("no-drop-target");
+			}
+
+			// Drop anything dockview did not accept, so the two sides agree.
+			for (let id of this.#documents.keys()) {
+				if (!host.getPanel(id)) this.#documents.delete(id);
+			}
+		} finally {
+			this.#applying = false;
+		}
+
+		this.#activeId = host.getActivePanelId();
+		this.#invalidate();
+		this.#emitter.emit("activeChange", this.getActive());
+		this.#emitter.emit("layoutChange", undefined);
+	}
+
+	/** Fixed panes added to the default layout after a layout was saved are missing from it; put them back. */
+	#addMissingRequired(spec: MdiLayoutSpec, layout: MdiLayout) {
+		let host = this.#requireHost();
+
+		for (let document of missingRequiredDocuments(spec, this.#types, layout)) {
+			let existing = new Set(this.#documents.keys());
+			let { position, groupSpec } = placementFor(spec, document.id, this.#types, existing);
+			let id = this.openDocument({
+				type: document.type,
+				key: document.key,
+				params: document.params,
+				title: document.title,
+				closable: false,
+				position,
+				inactive: true,
+			});
+			let panel = host.getPanel(id);
+
+			if (panel && groupSpec && position.direction !== "within" && panel.group.panelCount === 1) {
+				let locked = resolveLocked(groupSpec);
+				if (groupSpec.hideHeader) panel.group.setHeaderHidden(true);
+				if (locked) panel.group.setLocked(locked);
+			}
+		}
+	}
+
+	#handleRemoved(id: string, force = false) {
+		if (this.#applying) return;
+
+		// dockview reports removals while moving panels between groups too; only a panel
+		// that is really gone counts as closed.
+		if (!force && this.#host?.getPanel(id)) return;
+
+		let info = this.getDocument(id);
+
+		if (!info) return;
+
+		this.#documents.delete(id);
+		this.#guards.delete(id);
+
+		if (this.#activeId === id) {
+			this.#activeId = undefined;
+		}
+
+		this.#invalidate();
+		this.#emitter.emit("close", info);
+		this.#scheduleSave();
+	}
+
+	#setActive(id: string | undefined) {
+		if (id === this.#activeId) return;
+
+		let previous = this.#activeId;
+		this.#activeId = id;
+
+		if (previous) this.#infoCache.delete(previous);
+		if (id) this.#infoCache.delete(id);
+		this.#listCache = undefined;
+
+		this.#emitter.emit("change", undefined);
+		this.#emitter.emit("activeChange", this.getActive());
+	}
+
+	#invalidate(id?: string) {
+		if (id === undefined) {
+			this.#infoCache.clear();
+		} else {
+			this.#infoCache.delete(id);
+		}
+
+		this.#listCache = undefined;
+		this.#emitter.emit("change", undefined);
+	}
+
+	#scheduleSave() {
+		if (!this.#initialized || this.#applying || !this.#options?.persist) return;
+
+		let key = this.#storageKey();
+		let layout = this.getLayout();
+
+		if (key && layout) {
+			this.#store.set(key, layout);
+		}
+	}
+}