@olenbetong/appframe-ds 0.9.1 → 1.0.0

package/src/mdi/layoutStore.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { layoutSpecToLayout } from "./layoutSpec.js";
+import { createLayoutStore } from "./layoutStore.js";
+import { createMemorySettingsStore } from "./memorySettingsStore.js";
+import { testSpec, testTypes } from "./testTypes.js";
+
+describe("layout store", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it("prefixes keys with the article", () => {
+		let store = createLayoutStore(createMemorySettingsStore(), "my-article");
+		expect(store.key("dock")).toBe("my-article.dock");
+	});
+
+	it("prefetches layouts of the article and ignores other values", async () => {
+		let layout = layoutSpecToLayout(testSpec, testTypes, 1);
+		let settings = createMemorySettingsStore({
+			"my-article.dock": layout,
+			"my-article.junk": { hello: "world" },
+			"other-article.dock": layout,
+		});
+		let store = createLayoutStore(settings, "my-article");
+
+		await store.loaded;
+
+		expect(store.get("my-article.dock", 1)).toEqual(layout);
+		expect(store.get("my-article.junk", 1)).toBeUndefined();
+		expect(store.get("other-article.dock", 1)).toBeUndefined();
+	});
+
+	it("returns nothing when the layout version differs", async () => {
+		let layout = layoutSpecToLayout(testSpec, testTypes, 1);
+		let store = createLayoutStore(createMemorySettingsStore({ "a.dock": layout }), "a");
+
+		await store.loaded;
+
+		expect(store.get("a.dock", 2)).toBeUndefined();
+		expect(store.get("a.dock", "1")).toBeUndefined();
+		expect(store.get("a.dock", 1)).toEqual(layout);
+	});
+
+	it("caches immediately and writes after a delay, coalescing bursts", async () => {
+		let settings = createMemorySettingsStore();
+		let store = createLayoutStore(settings, "a");
+		let first = layoutSpecToLayout(testSpec, testTypes, 1);
+		let second = { ...first, layoutVersion: 1, documents: {} };
+
+		store.set("a.dock", first);
+		store.set("a.dock", second);
+
+		expect(store.get("a.dock", 1)).toBe(second);
+		expect(settings.data.has("a.dock")).toBe(false);
+
+		await vi.advanceTimersByTimeAsync(300);
+
+		expect(settings.data.get("a.dock")).toBe(second);
+	});
+
+	it("writes immediately with setNow and cancels a pending delayed write", async () => {
+		let settings = createMemorySettingsStore();
+		let store = createLayoutStore(settings, "a");
+		let first = layoutSpecToLayout(testSpec, testTypes, 1);
+		let second = { ...first, documents: {} };
+
+		store.set("a.dock", first);
+		await store.setNow("a.dock", second);
+
+		expect(settings.data.get("a.dock")).toBe(second);
+
+		await vi.advanceTimersByTimeAsync(300);
+
+		expect(settings.data.get("a.dock")).toBe(second);
+	});
+
+	it("removes from the cache and the store", async () => {
+		let layout = layoutSpecToLayout(testSpec, testTypes, 1);
+		let settings = createMemorySettingsStore({ "a.dock": layout });
+		let store = createLayoutStore(settings, "a");
+
+		await store.loaded;
+		await store.remove("a.dock");
+
+		expect(store.get("a.dock", 1)).toBeUndefined();
+		expect(settings.data.has("a.dock")).toBe(false);
+	});
+});

package/src/mdi/layoutStore.ts

@@ -0,0 +1,99 @@
+import { createSettingsStore, type SettingsStore } from "@olenbetong/appframe-react";
+
+import type { MdiLayout } from "./types.js";
+
+const PERSIST_DELAY = 300;
+
+export type MdiLayoutStore = {
+	/** Resolves once every layout of the current article has been read into the cache */
+	loaded: Promise<void>;
+	key(id: string): string;
+	/** The cached layout, or `undefined` on a miss or when the version or format does not match */
+	get(key: string, layoutVersion: string | number): MdiLayout | undefined;
+	/** Caches immediately, writes to storage after a short delay so frequent layout changes coalesce */
+	set(key: string, layout: MdiLayout): void;
+	/** Caches and writes immediately */
+	setNow(key: string, layout: MdiLayout): Promise<void>;
+	remove(key: string): Promise<void>;
+};
+
+function isMdiLayout(value: unknown): value is MdiLayout {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		(value as MdiLayout).format === 1 &&
+		typeof (value as MdiLayout).documents === "object" &&
+		typeof (value as MdiLayout).dockview === "object"
+	);
+}
+
+/**
+ * Same pattern as the grid layouts: one IndexedDB store per user, keys prefixed with the
+ * article id, and every key of the article prefetched at module load so the first render
+ * can restore synchronously.
+ */
+export function createLayoutStore(store: SettingsStore, article: string): MdiLayoutStore {
+	let cache: Record<string, MdiLayout> = {};
+	let timeouts: Record<string, ReturnType<typeof setTimeout>> = {};
+
+	let loaded = store
+		.keys()
+		.then((keys) =>
+			Promise.allSettled(
+				keys
+					.filter((key) => key.startsWith(`${article}.`))
+					.map((key) =>
+						store.getItem<MdiLayout>(key).then((layout) => {
+							if (isMdiLayout(layout) && !cache[key]) {
+								cache[key] = layout;
+							}
+						}),
+					),
+			),
+		)
+		.then(() => undefined);
+
+	function clearPending(key: string) {
+		clearTimeout(timeouts[key]);
+		delete timeouts[key];
+	}
+
+	return {
+		loaded,
+		key: (id) => `${article}.${id}`,
+		get(key, layoutVersion) {
+			let layout = cache[key];
+
+			if (isMdiLayout(layout) && layout.layoutVersion === layoutVersion) {
+				return layout;
+			}
+
+			return undefined;
+		},
+		set(key, layout) {
+			cache[key] = layout;
+			clearPending(key);
+			timeouts[key] = setTimeout(() => {
+				delete timeouts[key];
+				store.setItem(key, layout);
+			}, PERSIST_DELAY);
+		},
+		async setNow(key, layout) {
+			cache[key] = layout;
+			clearPending(key);
+			await store.setItem(key, layout);
+		},
+		async remove(key) {
+			delete cache[key];
+			clearPending(key);
+			await store.removeItem(key);
+		},
+	};
+}
+
+const article = globalThis.af?.article?.id ?? globalThis.window?.location.pathname.substring(1).split("/")[0] ?? "";
+
+export const layoutStore = createLayoutStore(
+	createSettingsStore(`AfMdiLayouts.${globalThis.af?.userSession?.login ?? "anonymous"}`),
+	article,
+);

package/src/mdi/memorySettingsStore.ts

@@ -0,0 +1,21 @@
+import type { SettingsStore } from "@olenbetong/appframe-react";
+
+/** An in-memory SettingsStore for tests */
+export function createMemorySettingsStore(
+	initial: Record<string, unknown> = {},
+): SettingsStore & { data: Map<string, unknown> } {
+	let data = new Map<string, unknown>(Object.entries(initial));
+
+	return {
+		data,
+		getItem: async <T>(key: string) => (data.get(key) as T) ?? null,
+		setItem: async <T>(key: string, value: T) => {
+			data.set(key, value);
+			return value;
+		},
+		removeItem: async (key: string) => {
+			data.delete(key);
+		},
+		keys: async () => [...data.keys()],
+	};
+}

package/src/mdi/registry.ts

@@ -0,0 +1,34 @@
+import { panelId } from "./ids.js";
+import type { MdiDocumentType, MdiDocumentTypes, MdiParams } from "./types.js";
+
+export function resolveType(types: MdiDocumentTypes, type: string): MdiDocumentType {
+	if (type.includes(":")) {
+		throw new Error(`Mdi: document type "${type}" must not contain ":" (it separates type and key in panel ids).`);
+	}
+
+	let definition = types[type];
+
+	if (!definition) {
+		throw new Error(`Mdi: unknown document type "${type}". Register it in the \`types\` of MdiProvider.`);
+	}
+
+	return definition;
+}
+
+/** The panel id a document of this type/key gets. Singleton types ignore the key. */
+export function resolveDocumentId(types: MdiDocumentTypes, type: string, key?: string): string {
+	let definition = resolveType(types, type);
+	return panelId(type, definition.singleton ? undefined : key);
+}
+
+export function resolveTitle(definition: MdiDocumentType, type: string, params: MdiParams, key?: string): string {
+	if (typeof definition.title === "function") {
+		return definition.title(params, key);
+	}
+
+	return definition.title ?? type;
+}
+
+export function resolveClosable(definition: MdiDocumentType, override?: boolean): boolean {
+	return override ?? definition.closable ?? true;
+}

package/src/mdi/testTypes.ts

@@ -0,0 +1,37 @@
+import type { MdiDocumentTypes, MdiLayoutSpec } from "./types.js";
+
+function Placeholder() {
+	return null;
+}
+
+/** A registry shaped like the ElementsProjectsSetup app: two fixed panes, one keyed editor, one singleton. */
+export const testTypes: MdiDocumentTypes = {
+	explorer: { component: Placeholder, singleton: true, closable: false, title: "Explorer" },
+	properties: { component: Placeholder, singleton: true, closable: false, title: "Properties" },
+	editor: { component: Placeholder, title: (params, key) => `Editor ${(params.name as string) ?? key}` },
+	settings: { component: Placeholder, singleton: true, title: "Settings" },
+};
+
+export const testSpec: MdiLayoutSpec = {
+	root: {
+		direction: "horizontal",
+		children: [
+			{ tabs: [{ type: "explorer" }], hideHeader: true, locked: true, size: 1 },
+			{
+				direction: "vertical",
+				size: 3,
+				children: [
+					{
+						tabs: [
+							{ type: "editor", key: "a", params: { name: "A" } },
+							{ type: "editor", key: "b", params: { name: "B" } },
+						],
+						active: "editor:b",
+						size: 3,
+					},
+					{ tabs: [{ type: "properties" }], size: 1 },
+				],
+			},
+		],
+	},
+};

package/src/mdi/theme.ts

@@ -0,0 +1,22 @@
+import type { DockviewTheme } from "dockview-react";
+
+/**
+ * Both themes share the `ObMdi-theme` class, whose variables resolve to
+ * Designsystemet tokens and therefore follow `data-color-scheme` on their own.
+ * `colorScheme` only tells dockview which of its own defaults to use.
+ */
+export const mdiThemeLight: DockviewTheme = {
+	name: "ob-light",
+	className: "ObMdi-theme",
+	colorScheme: "light",
+	gap: 0,
+	dndOverlayMounting: "absolute",
+	dndPanelOverlay: "group",
+	dndTabIndicator: "line",
+};
+
+export const mdiThemeDark: DockviewTheme = {
+	...mdiThemeLight,
+	name: "ob-dark",
+	colorScheme: "dark",
+};

package/src/mdi/types.ts

@@ -0,0 +1,214 @@
+import type { SerializedDockview } from "dockview-react";
+import type { ComponentType } from "react";
+
+/** Parameters handed to a document component. Must be JSON-serialisable, as they are persisted with the layout. */
+export type MdiParams = Record<string, unknown>;
+
+export type MdiDocumentProps<P extends MdiParams = MdiParams> = {
+	/** Panel id: `type` for singleton types, `type:key` otherwise */
+	id: string;
+	type: string;
+	/** The document key (`key` itself is reserved by React) */
+	documentKey?: string;
+	params: P;
+};
+
+export type MdiRestoreResult<P extends MdiParams = MdiParams> = boolean | Partial<{ params: P; title: string }>;
+
+export type MdiDocumentType<P extends MdiParams = MdiParams> = {
+	component: ComponentType<MdiDocumentProps<P>>;
+	/** Initial tab caption. Documents usually override it with `setTitle()` once their data is loaded. */
+	title?: string | ((params: P, key?: string) => string);
+	/** One instance per type; `key` is ignored. Default `false` (one instance per key). */
+	singleton?: boolean;
+	/** Default for documents of this type; can be overridden per document. Default `true`. */
+	closable?: boolean;
+	/**
+	 * Runs for every persisted document of this type before a saved layout is restored.
+	 * Return `false` to drop it (record deleted, no access, …), `true` to keep it, or an
+	 * object with new `params`/`title` to keep it with updated values.
+	 */
+	restore?: (doc: { key?: string; params: P }) => MdiRestoreResult<P> | Promise<MdiRestoreResult<P>>;
+};
+
+// oxlint-disable-next-line typescript/no-explicit-any -- the registry holds types with different param shapes
+export type MdiDocumentTypes = Record<string, MdiDocumentType<any>>;
+
+/* ---------------------------------------------------------------------------
+ * Layout spec (what apps write as `defaultLayout`)
+ * ------------------------------------------------------------------------- */
+
+export type MdiDocumentSpec<P extends MdiParams = MdiParams> = {
+	type: string;
+	key?: string;
+	params?: P;
+	title?: string;
+	/** Overrides the type default */
+	closable?: boolean;
+};
+
+/**
+ * How a group treats drops. `true`: nothing can be dropped into the group (onto its tabs
+ * or its centre), so it keeps exactly the tabs the layout gives it, but documents can
+ * still be dropped beside it and split its space. `"no-drop-target"`: the group shows
+ * no drop zones at all, not even along its edges. Either way its tabs cannot be reordered,
+ * but they can still be dragged out; see `disableDnd` on `Mdi` for fully fixed layouts.
+ */
+export type MdiLocked = boolean | "no-drop-target";
+
+export type MdiGroupSpec = {
+	/** Tabs in this group, in order */
+	tabs: MdiDocumentSpec[];
+	/** Panel id of the active tab (`type` or `type:key`). Default: the first tab. */
+	active?: string;
+	/**
+	 * See {@link MdiLocked}. Defaults to `true` when `hideHeader` is set: a tab dropped into
+	 * a group without a tab bar could neither be seen nor moved back out.
+	 */
+	locked?: MdiLocked;
+	/** Hide the tab bar, for a single fixed pane such as a tree. */
+	hideHeader?: boolean;
+	/** Relative weight within the parent split. Default `1`. */
+	size?: number;
+};
+
+export type MdiSplitSpec = {
+	/** `horizontal` lays children out side by side, `vertical` stacks them. */
+	direction: "horizontal" | "vertical";
+	children: MdiLayoutNode[];
+	/** Relative weight within the parent split. Default `1`. */
+	size?: number;
+};
+
+export type MdiLayoutNode = MdiGroupSpec | MdiSplitSpec;
+
+export type MdiLayoutSpec = {
+	root: MdiLayoutNode;
+};
+
+/* ---------------------------------------------------------------------------
+ * Persisted layout (IndexedDB value, and what `saveLayout()` returns)
+ * ------------------------------------------------------------------------- */
+
+export type MdiDocumentState = {
+	type: string;
+	key?: string;
+	params: MdiParams;
+	/** Last title shown, so the tab has a caption before the component sets its own */
+	title?: string;
+	closable: boolean;
+};
+
+export type MdiLayout = {
+	/** Schema version of this wrapper. Bump when `MdiLayout` itself changes shape. */
+	format: 1;
+	layoutVersion: string | number;
+	/** What each dockview panel is, keyed by panel id */
+	documents: Record<string, MdiDocumentState>;
+	/** dockview's own layout JSON (splits, groups, tabs, popouts) */
+	dockview: SerializedDockview;
+};
+
+/* ---------------------------------------------------------------------------
+ * Imperative API
+ * ------------------------------------------------------------------------- */
+
+export type MdiDirection = "left" | "right" | "above" | "below";
+
+export type MdiPosition =
+	| { referencePanel: string; direction: MdiDirection | "within"; index?: number }
+	| { direction: MdiDirection };
+
+export type MdiOpenOptions<P extends MdiParams = MdiParams> = {
+	type: string;
+	key?: string;
+	params?: P;
+	title?: string;
+	closable?: boolean;
+	/** Where to put a new panel. Default: in the active group. Ignored when the document is already open. */
+	position?: MdiPosition;
+	/** Open without activating. Default `false`. */
+	inactive?: boolean;
+};
+
+export type MdiDocumentInfo = MdiDocumentState & {
+	id: string;
+	dirty: boolean;
+	isActive: boolean;
+};
+
+export type MdiCloseOptions = {
+	/** Skip the closable check, the `onClosing` guard and the dirty prompt */
+	force?: boolean;
+};
+
+export type MdiConfirmCloseResult = "save" | "discard" | "cancel";
+
+export type MdiEvents = {
+	open: MdiDocumentInfo;
+	close: MdiDocumentInfo;
+	activeChange: MdiDocumentInfo | undefined;
+	titleChange: { id: string; title: string };
+	dirtyChange: { id: string; dirty: boolean };
+	layoutChange: undefined;
+};
+
+export type MdiApi = {
+	/**
+	 * Opens a document, or activates it if it is already open. An open document gets the
+	 * new `params` (its component re-renders). Returns the panel id.
+	 */
+	openDocument<P extends MdiParams = MdiParams>(options: MdiOpenOptions<P>): string;
+	activate(id: string): void;
+	/** Runs the close guards and the dirty prompt. Resolves `true` when the document was closed. */
+	close(id: string, options?: MdiCloseOptions): Promise<boolean>;
+	/** Closes every document with this key, across types. Forces by default, for when the record is gone. */
+	closeByKey(key: string, options?: MdiCloseOptions): Promise<void>;
+	/** Closes all closable documents, optionally of one type. Stops at the first cancelled close and returns `false`. */
+	closeAll(type?: string): Promise<boolean>;
+	setTitle(id: string, title: string): void;
+	setDirty(id: string, dirty: boolean): void;
+	getActive(): MdiDocumentInfo | undefined;
+	getDocument(id: string): MdiDocumentInfo | undefined;
+	getDocuments(type?: string): MdiDocumentInfo[];
+	hasDirty(): boolean;
+	/** Moves the document's group to a separate browser window. Resolves `false` if the window was blocked. */
+	popout(id: string): Promise<boolean>;
+	subscribe<K extends keyof MdiEvents>(event: K, handler: (event: MdiEvents[K]) => void): () => void;
+	/** Writes the current layout to IndexedDB immediately and returns it */
+	saveLayout(): Promise<MdiLayout | undefined>;
+	/** Re-applies the given layout, or the persisted one, or the default */
+	loadLayout(layout?: MdiLayout): Promise<void>;
+	/** Removes the persisted layout and applies the default */
+	resetLayout(): Promise<void>;
+	getLayout(): MdiLayout | undefined;
+	/** The panel id for a type/key pair */
+	panelId(type: string, key?: string): string;
+};
+
+export type MdiDocumentOptions = {
+	/**
+	 * Called when the document is dirty and the user chose "Save" in the close prompt.
+	 * Resolve `true` when saved (the close continues) or `false` to keep the document open.
+	 */
+	onSave?: () => boolean | Promise<boolean>;
+	/** Runs before the dirty prompt. Return `false` to veto the close. */
+	onClosing?: () => boolean | Promise<boolean>;
+};
+
+export type MdiDocumentHandle<P extends MdiParams = MdiParams> = {
+	id: string;
+	type: string;
+	key?: string;
+	params: P;
+	isActive: boolean;
+	dirty: boolean;
+	closable: boolean;
+	setTitle(title: string): void;
+	setDirty(dirty: boolean): void;
+	close(options?: MdiCloseOptions): Promise<boolean>;
+	activate(): void;
+	/** The window the document is rendered in (the main window or a popout). Use it as a portal container. */
+	getWindow(): Window;
+	mdi: MdiApi;
+};

package/src/page/Page.css

@@ -12,15 +12,23 @@
 		display: flex;
 		flex-direction: column;
 		box-sizing: border-box;
+		/* Containing block for the app-menu drawer, so the drawer is confined to the page
+		   rather than the viewport. That is what keeps it clear of a site toolbar rendered
+		   above the app, without needing to know the toolbar's height. */
+		position: relative;
 	}
 
 	.ObPage-document {
 		min-height: 100%;
 	}
 
+	/*
+	 * Fills the element the app is mounted in, not the viewport. A site template may render
+	 * chrome above #root (ob.2026.application renders a toolbar), in which case 100vh is taller
+	 * than the space available and the bottom of the page is cut off.
+	 */
 	.ObPage-app {
-		height: 100vh;
-		height: 100dvh;
+		height: 100%;
 		overflow: hidden;
 	}
 

package/src/page/PageBlock.css

@@ -24,6 +24,11 @@
 	max-width: 90rem;
 }
 
+/* Against the leading edge instead of centred in the space left over. */
+.ObPageBlock-alignStart {
+	margin-inline-start: 0;
+}
+
 .ObPageBlock-gutters {
 	--ob-page-gutter: 1rem;
 

package/src/page/PageBlock.tsx

@@ -8,6 +8,18 @@ export const pageBlockWidths = ["text", "md", "lg", "xl", "2xl"] as const;
 export type PageBlockWidth = (typeof pageBlockWidths)[number];
 
 export type PageBlockProps = React.HTMLAttributes<HTMLElement> & {
+	/**
+	 * Where a width-constrained block sits in the space available to it.
+	 *
+	 * `center` is the MUI `Container` behaviour. `start` keeps the content against the leading
+	 * edge, which is what the old `PageContainer` did (it forced `margin-left: 0`) and what an app
+	 * with a docked navigation drawer usually wants — centering leaves the content floating away
+	 * from the menu it belongs to.
+	 *
+	 * Has no effect without a `width`, since the block already fills its parent.
+	 * @default "center"
+	 */
+	align?: "center" | "start";
 	/**
 	 * Overrides the rendered element (e.g. `"main"`, `"header"`, `"footer"`)
 	 * @default "div"
@@ -51,6 +63,7 @@ export type PageBlockProps = React.HTMLAttributes<HTMLElement> & {
  * `text`, `md` → `md`, `lg` → `lg`, `xl` → `xl`, `false` → no `width`).
  */
 export function PageBlock({
+	align,
 	as: Component = "div",
 	children,
 	className,
@@ -65,6 +78,7 @@ export function PageBlock({
 			className={clsx(
 				"ObPageBlock-root",
 				width && `ObPageBlock-${width}`,
+				align === "start" && "ObPageBlock-alignStart",
 				gutters && "ObPageBlock-gutters",
 				grow && "ObPageBlock-grow",
 				overflow && `ObPageBlock-overflow${overflow === "auto" ? "Auto" : "Hidden"}`,

package/src/page/PageHeader.css

@@ -80,68 +80,8 @@
 	display: none;
 }
 
-/* --- drawer --- */
-
-@media screen {
-	.ObPageHeader-drawer {
-		position: fixed;
-		top: 0;
-		left: 0;
-		bottom: 0;
-		width: var(--ob-page-drawer-width, 20rem);
-		max-width: 90%;
-		box-sizing: border-box;
-		background-color: var(--ds-color-neutral-background-default, #fff);
-		color: var(--ds-color-neutral-text-default, #1e2b3c);
-		transform: translateX(-100%);
-		transition: transform 225ms cubic-bezier(0, 0, 0.2, 1);
-		overflow: hidden;
-		display: flex;
-		flex-direction: column;
-	}
-
-	.ObPageHeader-drawer > .MenuItems-root {
-		flex: 1 1 auto;
-		min-height: 0;
-	}
-
-	.ObPageHeader-drawer.ObPageHeader-drawerOpen {
-		transform: translateX(0);
-	}
-
-	.ObPageHeader-drawerDocked {
-		border-right: 1px solid var(--ds-color-neutral-border-subtle, #dfdfdf);
-		z-index: 1100;
-	}
-
-	.ObPageHeader-drawerOverlayMode {
-		z-index: 1200;
-		box-shadow:
-			rgb(0 0 0 / 20%) 0px 8px 10px -5px,
-			rgb(0 0 0 / 14%) 0px 16px 24px 2px,
-			rgb(0 0 0 / 12%) 0px 6px 30px 5px;
-	}
-
-	.ObPageHeader-drawerOverlay {
-		position: fixed;
-		inset: 0;
-		background-color: rgb(0 0 0 / 50%);
-		z-index: 1199;
-		opacity: 0;
-		pointer-events: none;
-		transition: opacity 225ms cubic-bezier(0.4, 0, 0.2, 1);
-	}
-
-	.ObPageHeader-drawerOverlay.ObPageHeader-drawerOpen {
-		opacity: 1;
-		pointer-events: auto;
-	}
-}
-
 @media print {
 	.ObPageHeader-appbar .ObPageHeader-bar,
-	.ObPageHeader-drawer,
-	.ObPageHeader-drawerOverlay,
 	.ObPageHeader-toggle {
 		display: none !important;
 	}