@olenbetong/appframe-ds 0.9.0 → 1.0.0

package/src/mdi/MdiDocumentContext.tsx

@@ -0,0 +1,60 @@
+import { createContext, use, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+
+import { parsePanelId } from "./ids.js";
+import { useMdiController } from "./MdiContext.js";
+import type { MdiCloseOptions, MdiDocumentHandle, MdiDocumentOptions, MdiParams } from "./types.js";
+
+export const MdiDocumentIdContext = createContext<string | null>(null);
+
+/**
+ * The document a component is rendered in: its params, whether it is active, and
+ * the handle to set its title and dirty state or close it. Pass `onSave`/`onClosing`
+ * to take part in the close flow.
+ */
+export function useMdiDocument<P extends MdiParams = MdiParams>(options?: MdiDocumentOptions): MdiDocumentHandle<P> {
+	let controller = useMdiController();
+	let id = use(MdiDocumentIdContext);
+
+	if (!id) {
+		throw new Error("Mdi: useMdiDocument() must be called from a component rendered as an Mdi document.");
+	}
+
+	// The guards are registered once; they always call the latest callbacks.
+	let latest = useRef(options);
+	useEffect(() => {
+		latest.current = options;
+	});
+
+	let [guards] = useState<MdiDocumentOptions>(() => ({
+		onSave: () => latest.current?.onSave?.() ?? true,
+		onClosing: () => latest.current?.onClosing?.() ?? true,
+	}));
+
+	useEffect(() => controller.registerGuards(id, guards), [controller, id, guards]);
+
+	let info = useSyncExternalStore(
+		controller.subscribeStore,
+		() => controller.getDocument(id),
+		() => controller.getDocument(id),
+	);
+
+	return useMemo(() => {
+		let parsed = parsePanelId(id);
+
+		return {
+			id,
+			type: info?.type ?? parsed.type,
+			key: info?.key ?? parsed.key,
+			params: (info?.params ?? {}) as P,
+			isActive: info?.isActive ?? false,
+			dirty: info?.dirty ?? false,
+			closable: info?.closable ?? true,
+			setTitle: (title: string) => controller.setTitle(id, title),
+			setDirty: (dirty: boolean) => controller.setDirty(id, dirty),
+			close: (closeOptions?: MdiCloseOptions) => controller.close(id, closeOptions),
+			activate: () => controller.activate(id),
+			getWindow: () => controller.getWindow(id),
+			mdi: controller,
+		};
+	}, [controller, id, info]);
+}

package/src/mdi/MdiPanel.tsx

@@ -0,0 +1,61 @@
+import { Button } from "@digdir/designsystemet-react";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+import type { IDockviewPanelProps } from "dockview-react";
+import { useSyncExternalStore } from "react";
+import { ErrorBoundary, type FallbackProps } from "react-error-boundary";
+
+import { useMdiController } from "./MdiContext.js";
+import { MdiDocumentIdContext } from "./MdiDocumentContext.js";
+
+function MdiErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
+	let message = error instanceof Error ? error.message : String(error);
+
+	return (
+		<div className="ObMdi-error" role="alert">
+			<p className="ObMdi-error-title">{getLocalizedString("The document could not be displayed")}</p>
+			<pre className="ObMdi-error-message">{message}</pre>
+			<Button data-size="sm" variant="secondary" onClick={resetErrorBoundary}>
+				{getLocalizedString("Try again")}
+			</Button>
+		</div>
+	);
+}
+
+/**
+ * The one dockview content component. Every panel renders through it; it looks the
+ * document up by panel id and renders the component registered for its type.
+ */
+export function MdiPanel(props: IDockviewPanelProps) {
+	let id = props.api.id;
+	let controller = useMdiController();
+	let info = useSyncExternalStore(
+		controller.subscribeStore,
+		() => controller.getDocument(id),
+		() => controller.getDocument(id),
+	);
+
+	if (!info) {
+		return null;
+	}
+
+	let definition = controller.getTypes()[info.type];
+
+	if (!definition) {
+		return (
+			<div className="ObMdi-error" role="alert">
+				<p className="ObMdi-error-title">{getLocalizedString("Unknown document type")}</p>
+				<pre className="ObMdi-error-message">{info.type}</pre>
+			</div>
+		);
+	}
+
+	let Component = definition.component;
+
+	return (
+		<MdiDocumentIdContext value={id}>
+			<ErrorBoundary FallbackComponent={MdiErrorFallback} resetKeys={[info.params]}>
+				<Component id={id} type={info.type} documentKey={info.key} params={info.params} />
+			</ErrorBoundary>
+		</MdiDocumentIdContext>
+	);
+}

package/src/mdi/MdiRestore.test.tsx

@@ -0,0 +1,82 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { layoutSpecToLayout } from "./layoutSpec.js";
+import { layoutStore } from "./layoutStore.js";
+import { Mdi } from "./Mdi.js";
+import { MdiProvider } from "./MdiContext.js";
+import type { MdiDocumentProps, MdiDocumentTypes, MdiLayout, MdiLayoutSpec } from "./types.js";
+
+vi.mock("@olenbetong/appframe-core", () => ({
+	getLocalizedString: (value: string) => value,
+}));
+
+function Doc({ id }: MdiDocumentProps) {
+	return <div data-testid={id}>{id}</div>;
+}
+
+const types: MdiDocumentTypes = {
+	explorer: { component: Doc, singleton: true, closable: false, title: "Explorer" },
+	properties: { component: Doc, singleton: true, closable: false, title: "Properties" },
+	welcome: { component: Doc, singleton: true, title: "Welcome" },
+	serie: { component: Doc, title: "Serie", restore: async () => true },
+};
+
+const spec: MdiLayoutSpec = {
+	root: {
+		direction: "horizontal",
+		children: [
+			{ tabs: [{ type: "explorer" }], hideHeader: true, locked: true },
+			{
+				direction: "vertical",
+				children: [{ tabs: [{ type: "welcome" }] }, { tabs: [{ type: "properties" }] }],
+			},
+		],
+	},
+};
+
+/**
+ * What dockview serialises after a panel was popped out of the welcome group: the
+ * panel sits in `popoutGroups` with the welcome group as its reference group.
+ */
+function layoutWithPopout(): MdiLayout {
+	let layout = layoutSpecToLayout(spec, types, 1);
+	let serieId = "serie:abc";
+
+	layout.documents[serieId] = { type: "serie", key: "abc", params: { name: "S" }, title: "S", closable: true };
+	layout.dockview.panels[serieId] = { id: serieId, contentComponent: "mdi", tabComponent: "mdi", title: "S" };
+	layout.dockview.popoutGroups = [
+		{
+			data: { id: "4", views: [serieId], activeView: serieId },
+			gridReferenceGroup: "mdi-g2",
+			position: { top: 10, left: 10, width: 300, height: 200 },
+			url: "/popout",
+		},
+	];
+
+	return layout;
+}
+
+describe("Mdi restore", () => {
+	it("re-docks a popped-out document when a saved layout is restored", async () => {
+		let key = layoutStore.key("restore-popout");
+		await layoutStore.setNow(key, layoutWithPopout());
+
+		render(
+			<MdiProvider types={types}>
+				<div style={{ width: 800, height: 600 }}>
+					<Mdi id="restore-popout" layoutVersion={1} defaultLayout={spec} />
+				</div>
+			</MdiProvider>,
+		);
+
+		// dockview only mounts the content of the active tab of a group, so check the tabs.
+		expect(await screen.findByTestId("welcome")).toBeInTheDocument();
+		let tabIds = [...document.querySelectorAll("[data-tab-panel-id]")].map((tab) =>
+			tab.getAttribute("data-tab-panel-id"),
+		);
+		expect(tabIds).toEqual(["explorer", "welcome", "serie:abc", "properties"]);
+		expect(screen.getByTestId("explorer")).toBeInTheDocument();
+		expect(screen.getByTestId("properties")).toBeInTheDocument();
+	});
+});

package/src/mdi/MdiTab.tsx

@@ -0,0 +1,30 @@
+import clsx from "clsx";
+import { DockviewDefaultTab, type IDockviewPanelHeaderProps } from "dockview-react";
+import { useCallback, useSyncExternalStore } from "react";
+
+import { useMdiController } from "./MdiContext.js";
+
+/**
+ * The default tab with the close button hidden for unclosable documents, and every
+ * close (button and middle-click) routed through the controller guards.
+ */
+export function MdiTab(props: IDockviewPanelHeaderProps) {
+	let id = props.api.id;
+	let controller = useMdiController();
+	let info = useSyncExternalStore(
+		controller.subscribeStore,
+		() => controller.getDocument(id),
+		() => controller.getDocument(id),
+	);
+
+	let close = useCallback(() => {
+		void controller.close(id);
+	}, [controller, id]);
+
+	// DockviewDefaultTab overwrites `className`, so the state classes go on a layout-neutral wrapper.
+	return (
+		<div className={clsx("ObMdi-tab", info?.dirty && "ObMdi-tab--dirty")} style={{ display: "contents" }}>
+			<DockviewDefaultTab {...props} hideClose={info ? !info.closable : false} closeActionOverride={close} />
+		</div>
+	);
+}

package/src/mdi/controller.test.ts

@@ -0,0 +1,382 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { MdiController, type MdiControllerOptions } from "./controller.js";
+import { createFakeHost } from "./fakeHost.js";
+import { layoutSpecToLayout } from "./layoutSpec.js";
+import { createLayoutStore, type MdiLayoutStore } from "./layoutStore.js";
+import { createMemorySettingsStore } from "./memorySettingsStore.js";
+import { testSpec, testTypes } from "./testTypes.js";
+import type { MdiConfirmCloseResult, MdiDocumentTypes, MdiLayout, MdiLayoutSpec } from "./types.js";
+
+function setup(
+	options: Partial<MdiControllerOptions> = {},
+	types: MdiDocumentTypes = testTypes,
+	store?: MdiLayoutStore,
+) {
+	let fake = createFakeHost();
+	let confirmClose = vi.fn<(document: unknown) => Promise<MdiConfirmCloseResult>>().mockResolvedValue("discard");
+	let controller = new MdiController(types, store ?? createLayoutStore(createMemorySettingsStore(), "art"));
+
+	controller.setOptions({
+		layoutVersion: 1,
+		defaultLayout: testSpec,
+		persist: false,
+		popoutUrl: "/popout",
+		confirmClose,
+		...options,
+	});
+	controller.attach(fake.host);
+
+	return { controller, fake, confirmClose };
+}
+
+describe("MdiController", () => {
+	beforeEach(() => {
+		vi.spyOn(console, "warn").mockImplementation(() => {});
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	describe("initialize", () => {
+		it("applies the default layout", async () => {
+			let { controller, fake } = setup();
+
+			await controller.initialize();
+
+			expect([...fake.panels.keys()]).toEqual(["explorer", "editor:a", "editor:b", "properties"]);
+			expect(controller.getDocuments().map((document) => document.id)).toEqual([
+				"explorer",
+				"editor:a",
+				"editor:b",
+				"properties",
+			]);
+			expect(controller.getActive()?.id).toBe("explorer");
+			expect(fake.groups.get("mdi-g1")).toMatchObject({ locked: true, headerHidden: true });
+		});
+
+		it("restores no-drop-target groups after dockview reduced the flag to a boolean", async () => {
+			let spec: MdiLayoutSpec = {
+				root: {
+					direction: "horizontal",
+					children: [
+						{ tabs: [{ type: "explorer" }], locked: "no-drop-target" },
+						{ tabs: [{ type: "properties" }], locked: true },
+					],
+				},
+			};
+			let { controller, fake } = setup({ defaultLayout: spec });
+
+			await controller.initialize();
+
+			expect(fake.groups.get("mdi-g1")?.locked).toBe("no-drop-target");
+			expect(fake.groups.get("mdi-g2")?.locked).toBe(true);
+		});
+
+		it("restores a persisted layout and drops documents the resolver rejects", async () => {
+			let restore = vi.fn(async ({ key }: { key?: string }) => (key === "b" ? false : { title: `Restored ${key}` }));
+			let types: MdiDocumentTypes = { ...testTypes, editor: { ...testTypes["editor"]!, restore } };
+			let persisted = layoutSpecToLayout(testSpec, types, 1);
+			let store = createLayoutStore(createMemorySettingsStore({ "art.dock": persisted }), "art");
+			let { controller, fake } = setup({ id: "dock", persist: true }, types, store);
+
+			await controller.initialize();
+
+			expect(restore).toHaveBeenCalledTimes(2);
+			expect([...fake.panels.keys()]).toEqual(["explorer", "editor:a", "properties"]);
+			expect(controller.getDocument("editor:a")?.title).toBe("Restored a");
+			expect(fake.panels.get("editor:a")?.title).toBe("Restored a");
+		});
+
+		it("falls back to the default layout when the version differs", async () => {
+			let persisted = { ...layoutSpecToLayout(testSpec, testTypes, 1), layoutVersion: 0 };
+			let store = createLayoutStore(createMemorySettingsStore({ "art.dock": persisted }), "art");
+			let { controller, fake } = setup({ id: "dock", persist: true }, testTypes, store);
+
+			await controller.initialize();
+
+			expect(fake.panels.size).toBe(4);
+		});
+
+		it("re-adds fixed panes that are missing from a saved layout", async () => {
+			let persisted = layoutSpecToLayout(testSpec, testTypes, 1);
+			delete persisted.documents["properties"];
+			delete persisted.dockview.panels["properties"];
+			let store = createLayoutStore(createMemorySettingsStore({ "art.dock": persisted }), "art");
+			let { controller, fake } = setup({ id: "dock", persist: true }, testTypes, store);
+
+			await controller.initialize();
+
+			expect(fake.panels.has("properties")).toBe(true);
+			expect(controller.getDocument("properties")).toMatchObject({ closable: false, isActive: false });
+		});
+
+		it("drops documents whose type is no longer registered", async () => {
+			let persisted = layoutSpecToLayout(testSpec, testTypes, 1);
+			let { settings: _settings, ...types } = testTypes;
+			persisted.documents["ghost"] = { type: "ghost", params: {}, closable: true };
+			persisted.dockview.panels["ghost"] = { id: "ghost", contentComponent: "mdi" };
+			let store = createLayoutStore(createMemorySettingsStore({ "art.dock": persisted }), "art");
+			let { controller, fake } = setup({ id: "dock", persist: true }, types, store);
+
+			await controller.initialize();
+
+			expect(fake.panels.has("ghost")).toBe(false);
+			expect(controller.getDocument("ghost")).toBeUndefined();
+		});
+	});
+
+	describe("opening", () => {
+		it("opens a keyed document once and activates it on the second call", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+			let opened = vi.fn();
+			controller.subscribe("open", opened);
+
+			let id = controller.openDocument({ type: "editor", key: "c", params: { name: "C" } });
+			fake.activate("explorer");
+			let again = controller.openDocument({ type: "editor", key: "c", params: { name: "C2" } });
+
+			expect(id).toBe("editor:c");
+			expect(again).toBe(id);
+			expect(opened).toHaveBeenCalledTimes(1);
+			expect(fake.panels.size).toBe(5);
+			expect(controller.getDocument(id)?.params).toEqual({ name: "C2" });
+			expect(controller.getActive()?.id).toBe(id);
+		});
+
+		it("ignores the key of singleton types", async () => {
+			let { controller } = setup();
+			await controller.initialize();
+
+			expect(controller.openDocument({ type: "settings", key: "whatever" })).toBe("settings");
+			expect(controller.panelId("settings", "x")).toBe("settings");
+			expect(controller.panelId("editor", "x")).toBe("editor:x");
+		});
+
+		it("adds new documents to the active group by default", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+			fake.activate("editor:a");
+
+			controller.openDocument({ type: "editor", key: "d" });
+
+			expect(fake.panels.get("editor:d")?.groupId).toBe(fake.panels.get("editor:a")?.groupId);
+		});
+
+		it("rejects unknown types", async () => {
+			let { controller } = setup();
+			await controller.initialize();
+
+			expect(() => controller.openDocument({ type: "nope" })).toThrow(/unknown document type/);
+		});
+	});
+
+	describe("closing", () => {
+		it("refuses to close unclosable documents unless forced", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+
+			expect(await controller.close("explorer")).toBe(false);
+			expect(fake.panels.has("explorer")).toBe(true);
+			expect(await controller.close("explorer", { force: true })).toBe(true);
+			expect(fake.panels.has("explorer")).toBe(false);
+		});
+
+		it("closes a clean document and reports it", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+			let closed = vi.fn();
+			controller.subscribe("close", closed);
+
+			expect(await controller.close("editor:a")).toBe(true);
+			expect(fake.panels.has("editor:a")).toBe(false);
+			expect(controller.getDocument("editor:a")).toBeUndefined();
+			expect(closed).toHaveBeenCalledWith(expect.objectContaining({ id: "editor:a" }));
+		});
+
+		it("lets an onClosing guard veto", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+			let unregister = controller.registerGuards("editor:a", { onClosing: () => false });
+
+			expect(await controller.close("editor:a")).toBe(false);
+			expect(fake.panels.has("editor:a")).toBe(true);
+
+			unregister();
+			expect(await controller.close("editor:a")).toBe(true);
+		});
+
+		it("asks before closing a dirty document", async () => {
+			let { controller, fake, confirmClose } = setup();
+			await controller.initialize();
+			let onSave = vi.fn().mockResolvedValue(false);
+			controller.registerGuards("editor:a", { onSave });
+			controller.setDirty("editor:a", true);
+
+			confirmClose.mockResolvedValueOnce("cancel");
+			expect(await controller.close("editor:a")).toBe(false);
+
+			confirmClose.mockResolvedValueOnce("save");
+			expect(await controller.close("editor:a")).toBe(false);
+			expect(onSave).toHaveBeenCalledTimes(1);
+			expect(fake.panels.has("editor:a")).toBe(true);
+
+			onSave.mockResolvedValue(true);
+			confirmClose.mockResolvedValueOnce("save");
+			expect(await controller.close("editor:a")).toBe(true);
+			expect(fake.panels.has("editor:a")).toBe(false);
+
+			controller.setDirty("editor:b", true);
+			confirmClose.mockResolvedValueOnce("discard");
+			expect(await controller.close("editor:b")).toBe(true);
+			expect(confirmClose).toHaveBeenCalledTimes(4);
+		});
+
+		it("closes by key without prompting", async () => {
+			let { controller, fake, confirmClose } = setup();
+			await controller.initialize();
+			controller.setDirty("editor:a", true);
+
+			await controller.closeByKey("a");
+
+			expect(confirmClose).not.toHaveBeenCalled();
+			expect(fake.panels.has("editor:a")).toBe(false);
+		});
+
+		it("closes all closable documents of a type and stops at a veto", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+			controller.openDocument({ type: "settings" });
+
+			expect(await controller.closeAll("editor")).toBe(true);
+			expect([...fake.panels.keys()]).toEqual(["explorer", "properties", "settings"]);
+
+			controller.openDocument({ type: "editor", key: "x" });
+			controller.openDocument({ type: "editor", key: "y" });
+			controller.registerGuards("editor:x", { onClosing: () => false });
+
+			expect(await controller.closeAll()).toBe(false);
+			expect(fake.panels.has("editor:x")).toBe(true);
+			expect(fake.panels.has("explorer")).toBe(true);
+		});
+
+		it("treats a panel removed by dockview as closed", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+
+			fake.host.getPanel("editor:b")!.close();
+
+			expect(controller.getDocument("editor:b")).toBeUndefined();
+		});
+	});
+
+	describe("state", () => {
+		it("tracks titles, dirty flags and the active document", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+			let events: string[] = [];
+			controller.subscribe("titleChange", (event) => events.push(`title:${event.id}:${event.title}`));
+			controller.subscribe("dirtyChange", (event) => events.push(`dirty:${event.id}:${event.dirty}`));
+			controller.subscribe("activeChange", (event) => events.push(`active:${event?.id}`));
+
+			controller.setTitle("editor:a", "Renamed");
+			controller.setDirty("editor:a", true);
+			fake.activate("editor:a");
+
+			expect(fake.panels.get("editor:a")?.title).toBe("Renamed");
+			expect(controller.getDocument("editor:a")).toMatchObject({ title: "Renamed", dirty: true, isActive: true });
+			expect(controller.hasDirty()).toBe(true);
+			expect(events).toEqual(["title:editor:a:Renamed", "dirty:editor:a:true", "active:editor:a"]);
+		});
+
+		it("keeps snapshots stable until something changes", async () => {
+			let { controller } = setup();
+			await controller.initialize();
+
+			let first = controller.getDocumentsSnapshot();
+			expect(controller.getDocumentsSnapshot()).toBe(first);
+			expect(controller.getDocument("editor:a")).toBe(controller.getDocument("editor:a"));
+
+			controller.setTitle("editor:a", "x");
+
+			expect(controller.getDocumentsSnapshot()).not.toBe(first);
+		});
+
+		it("pops a document out through the host", async () => {
+			let { controller, fake } = setup();
+			await controller.initialize();
+
+			expect(await controller.popout("editor:a")).toBe(true);
+			expect(fake.popouts).toEqual([{ id: "editor:a", popoutUrl: "/popout" }]);
+			expect(await controller.popout("nope")).toBe(false);
+		});
+	});
+
+	describe("persistence", () => {
+		it("saves layout changes when persistence is on", async () => {
+			vi.useFakeTimers();
+			let settings = createMemorySettingsStore();
+			let store = createLayoutStore(settings, "art");
+			let { controller, fake } = setup({ id: "dock", persist: true }, testTypes, store);
+
+			await controller.initialize();
+			expect(settings.data.has("art.dock")).toBe(false);
+
+			controller.openDocument({ type: "editor", key: "z" });
+			fake.fireLayout();
+			await vi.advanceTimersByTimeAsync(300);
+
+			let saved = settings.data.get("art.dock") as MdiLayout;
+			expect(saved.format).toBe(1);
+			expect(Object.keys(saved.documents)).toContain("editor:z");
+			expect(saved.dockview.panels["editor:z"]).toBeDefined();
+			vi.useRealTimers();
+		});
+
+		it("does not touch the store without an id", async () => {
+			let settings = createMemorySettingsStore();
+			let { controller, fake } = setup({ persist: true }, testTypes, createLayoutStore(settings, "art"));
+
+			await controller.initialize();
+			fake.fireLayout();
+			await controller.saveLayout();
+
+			expect(settings.data.size).toBe(0);
+		});
+
+		it("saves, loads and resets on demand without auto-save", async () => {
+			let settings = createMemorySettingsStore();
+			let store = createLayoutStore(settings, "art");
+			let { controller, fake } = setup({ id: "dock", persist: false }, testTypes, store);
+			await controller.initialize();
+
+			controller.openDocument({ type: "settings" });
+			let saved = await controller.saveLayout();
+			expect(settings.data.get("art.dock")).toBe(saved);
+
+			await controller.close("settings", { force: true });
+			expect(fake.panels.has("settings")).toBe(false);
+
+			await controller.loadLayout();
+			expect(fake.panels.has("settings")).toBe(true);
+
+			await controller.resetLayout();
+			expect(fake.panels.has("settings")).toBe(false);
+			expect(settings.data.has("art.dock")).toBe(false);
+			expect(fake.panels.size).toBe(4);
+		});
+	});
+
+	it("stops acting on the host after detach", async () => {
+		let { controller, fake } = setup();
+		await controller.initialize();
+
+		controller.detach();
+		fake.activate("editor:a");
+
+		expect(controller.getActive()?.id).toBe("explorer");
+		expect(() => controller.openDocument({ type: "settings" })).toThrow(/no dock is mounted/);
+	});
+});