@olenbetong/appframe-ds 0.9.0 → 1.0.0

package/src/layout/AppMenuDrawer.css

@@ -0,0 +1,70 @@
+/* --- drawer --- */
+
+@media screen {
+	.ObPageHeader-drawer {
+		/*
+		 * Absolute, not fixed: the drawer belongs to the page, so it stays clear of any site
+		 * chrome rendered above the app. Raising z-index instead would put the menu over that
+		 * chrome and hide it, and #root often creates its own stacking context anyway.
+		 * Requires Page (which is position: relative); use layout="app" so it has a height.
+		 */
+		position: absolute;
+		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: absolute;
+		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-drawer,
+	.ObPageHeader-drawerOverlay {
+		display: none !important;
+	}
+}

package/src/layout/AppMenuDrawer.tsx

@@ -0,0 +1,122 @@
+import "./AppMenuDrawer.css";
+
+import clsx from "clsx";
+import type React from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useLocation } from "react-router";
+
+import { AppMenu, type AppMenuProps } from "./AppMenu.js";
+
+/** Below this width the drawer is an overlay rather than docked beside the content. */
+const MOBILE_QUERY = "(max-width: 1199px)";
+
+function useIsMobile() {
+	let [isMobile, setIsMobile] = useState(() => {
+		if (typeof window === "undefined") return false;
+		return window.matchMedia(MOBILE_QUERY).matches;
+	});
+
+	useEffect(() => {
+		let mq = window.matchMedia(MOBILE_QUERY);
+		let handler = (e: MediaQueryListEvent) => setIsMobile(e.matches);
+		mq.addEventListener("change", handler);
+		return () => mq.removeEventListener("change", handler);
+	}, []);
+
+	return isMobile;
+}
+
+export type AppMenuDrawerState = {
+	/** Whether the drawer is showing. Docked drawers start open, overlays start closed. */
+	open: boolean;
+	/** True while the drawer is an overlay rather than docked. */
+	isMobile: boolean;
+	toggle: () => void;
+	close: () => void;
+};
+
+/**
+ * Open/closed state for an {@link AppMenuDrawer}, including the responsive behaviour: docked and
+ * open by default on desktop, an overlay that starts closed on smaller screens.
+ *
+ * Exposed separately from the drawer so the toggle button can live somewhere else entirely —
+ * an app on a site template that renders its own toolbar puts the toggle in that toolbar rather
+ * than in a second one of its own.
+ */
+export function useAppMenuDrawer(): AppMenuDrawerState {
+	let isMobile = useIsMobile();
+	let [desktopOpen, setDesktopOpen] = useState(true);
+	let [mobileOpen, setMobileOpen] = useState(false);
+
+	let toggle = useCallback(() => {
+		if (isMobile) {
+			setMobileOpen((open) => !open);
+		} else {
+			setDesktopOpen((open) => !open);
+		}
+	}, [isMobile]);
+
+	let close = useCallback(() => setMobileOpen(false), []);
+
+	return { open: isMobile ? mobileOpen : desktopOpen, isMobile, toggle, close };
+}
+
+export type AppMenuDrawerProps = {
+	/** Props for the `AppMenu` wrapping the items. */
+	AppMenuProps?: AppMenuProps;
+	/** Menu content — typically `AppMenuItem` and `AppMenuSubheader`. */
+	children: React.ReactNode;
+	isMobile: boolean;
+	onClose: () => void;
+	open: boolean;
+};
+
+/**
+ * The app-navigation drawer: docked beside the content on desktop, an overlay on smaller
+ * screens. Use it with {@link useAppMenuDrawer}.
+ *
+ * `Page.Header`'s `appbar` variant renders this for you along with a toggle and a title bar. Use
+ * this component directly when the app must *not* render a bar of its own — for example on a site
+ * template that already renders a toolbar, where an appbar would be a second one.
+ *
+ * It must be rendered inside `Page` for the docked drawer to offset the content (`Page.css`
+ * matches on these class names). The drawer is `position: fixed` and starts at
+ * `--ob-page-drawer-top`, which defaults to `0`; set that to the height of a site toolbar so the
+ * drawer sits below it rather than over it.
+ */
+export function AppMenuDrawer({ AppMenuProps, children, isMobile, onClose, open }: AppMenuDrawerProps) {
+	let location = useLocation();
+	let prevLocation = useRef(location);
+
+	// Following a link should dismiss an overlay; a docked drawer stays put.
+	useEffect(() => {
+		if (location !== prevLocation.current) {
+			prevLocation.current = location;
+			if (isMobile) onClose();
+		}
+	}, [location, isMobile, onClose]);
+
+	return (
+		<>
+			{isMobile && (
+				// oxlint-disable-next-line click-events-have-key-events -- Escape and the toggle
+				// both close the drawer; this is a pointer affordance for the scrim only.
+				<div
+					className={clsx("ObPageHeader-drawerOverlay", open && "ObPageHeader-drawerOpen")}
+					onClick={onClose}
+					aria-hidden="true"
+				/>
+			)}
+			<div
+				className={clsx(
+					"ObPageHeader-drawer",
+					"AppMenu-drawer",
+					isMobile ? "ObPageHeader-drawerOverlayMode" : "ObPageHeader-drawerDocked",
+					open && "ObPageHeader-drawerOpen",
+				)}
+			>
+				<AppMenu {...AppMenuProps}>{children}</AppMenu>
+			</div>
+		</>
+	);
+}

package/src/layout/index.tsx

@@ -47,6 +47,7 @@ function useIsMobile() {
 }
 
 export * from "./AppMenu.js";
+export * from "./AppMenuDrawer.js";
 export * from "./AppMenuItem.js";
 export * from "./AppMenuSubheader.js";
 export * from "./constants.js";

package/src/mdi/Mdi.css

@@ -0,0 +1,138 @@
+.ObMdi-root {
+	position: relative;
+	width: 100%;
+	height: 100%;
+	min-width: 0;
+	min-height: 0;
+}
+
+.ObMdi-root > .dv-dockview {
+	width: 100%;
+	height: 100%;
+}
+
+/*
+ * The dockview variables mapped to Designsystemet tokens. The theme class is also
+ * applied to the container in popout windows, so the mapping travels with them.
+ */
+.ObMdi-theme {
+	--dv-paneview-active-outline-color: var(--ds-color-focus-outer, #1e2b3c);
+	--dv-tabs-and-actions-container-font-size: var(--ds-font-size-3, 0.875rem);
+	--dv-tabs-and-actions-container-height: 2.25rem;
+	--dv-tab-font-size: inherit;
+	--dv-tabs-and-actions-container-background-color: var(--ds-color-neutral-surface-default, #f3f4f5);
+	--dv-group-view-background-color: var(--ds-color-neutral-background-default, #fff);
+	--dv-activegroup-visiblepanel-tab-background-color: var(--ds-color-neutral-background-default, #fff);
+	--dv-activegroup-hiddenpanel-tab-background-color: var(--ds-color-neutral-surface-default, #f3f4f5);
+	--dv-inactivegroup-visiblepanel-tab-background-color: var(--ds-color-neutral-background-tinted, #f8f9fa);
+	--dv-inactivegroup-hiddenpanel-tab-background-color: var(--ds-color-neutral-surface-default, #f3f4f5);
+	--dv-activegroup-visiblepanel-tab-color: var(--ds-color-neutral-text-default, #292c30);
+	--dv-activegroup-hiddenpanel-tab-color: var(--ds-color-neutral-text-subtle, #5b5f64);
+	--dv-inactivegroup-visiblepanel-tab-color: var(--ds-color-neutral-text-subtle, #5b5f64);
+	--dv-inactivegroup-hiddenpanel-tab-color: var(--ds-color-neutral-text-subtle, #5b5f64);
+	--dv-tab-divider-color: var(--ds-color-neutral-border-subtle, #d5d7d9);
+	--dv-separator-border: var(--ds-color-neutral-border-subtle, #d5d7d9);
+	--dv-paneview-header-border-color: var(--ds-color-neutral-border-default, #a6a9ad);
+	--dv-sash-color: transparent;
+	--dv-active-sash-color: var(--ds-color-accent-base-default, #116069);
+	--dv-active-sash-transition-duration: 0.1s;
+	--dv-active-sash-transition-delay: 0.3s;
+	--dv-drag-over-background-color: color-mix(in srgb, var(--ds-color-accent-base-default, #116069) 20%, transparent);
+	--dv-drag-over-border-color: var(--ds-color-accent-base-default, #116069);
+	--dv-drag-over-border: none;
+	--dv-edge-dock-indicator-color: var(--ds-color-accent-base-default, #116069);
+	--dv-dnd-compass-color: var(--ds-color-neutral-border-default, #a6a9ad);
+	--dv-dnd-compass-cell-color: var(--ds-color-neutral-surface-default, #f3f4f5);
+	--dv-dnd-compass-edge-cell-color: var(--ds-color-neutral-surface-hover, #e6e8ea);
+	--dv-dnd-compass-active-cell-color: var(--ds-color-accent-surface-hover, #d1e5e7);
+	--dv-tabs-container-scrollbar-color: var(--ds-color-neutral-border-default, #a6a9ad);
+	--dv-scrollbar-background-color: var(--ds-color-neutral-border-default, #a6a9ad);
+	--dv-icon-hover-background-color: var(--ds-color-neutral-surface-hover, #e6e8ea);
+	--dv-context-menu-background-color: var(--ds-color-neutral-background-default, #fff);
+	--dv-context-menu-color: var(--ds-color-neutral-text-default, #292c30);
+	--dv-floating-box-shadow: var(--ds-shadow-lg, 0 8px 32px rgba(0, 0, 0, 0.12));
+	--dv-floating-border: 1px solid var(--ds-color-neutral-border-default, #a6a9ad);
+	--dv-floating-group-border: none;
+	--dv-floating-group-dragging-opacity: 0.5;
+	--dv-floating-titlebar-height: 22px;
+	--dv-floating-titlebar-background-color: var(--dv-tabs-and-actions-container-background-color);
+	--dv-floating-titlebar-border-bottom: var(--dv-floating-border);
+	--dv-overlay-z-index: 999;
+	--dv-border-radius: 0px;
+	--dv-tab-margin: 0;
+	--dv-spacing-padding: 0px;
+	--dv-tab-border-radius: 0px;
+	--dv-sash-border-radius: 0px;
+	--dv-dropdown-border-radius: var(--ds-border-radius-md, 0.25rem);
+	--dv-tab-close-icon-size: inherit;
+	--dv-smart-guides-color: var(--ds-color-accent-base-default, #116069);
+	--dv-smart-guides-preview-color: color-mix(in srgb, var(--ds-color-accent-base-default, #116069) 20%, transparent);
+	--dv-tab-group-color-grey: #5f6368;
+	--dv-tab-group-color-blue: #1a73e8;
+	--dv-tab-group-color-red: #d93025;
+	--dv-tab-group-color-yellow: #f9ab00;
+	--dv-tab-group-color-green: #188038;
+	--dv-tab-group-color-pink: #d01884;
+	--dv-tab-group-color-purple: #a142f4;
+	--dv-tab-group-color-cyan: #007b83;
+	--dv-tab-group-color-orange: #e8710a;
+	--dv-tab-group-chip-padding: 4px 8px;
+	--dv-tab-group-chip-border-radius: 6px;
+	--dv-tab-group-chip-font-size: 11px;
+	--dv-tab-group-line-height: 2px;
+	--dv-tab-group-line-opacity: 0.6;
+
+	font-family: var(--ds-font-family, inherit);
+	color: var(--ds-color-neutral-text-default, #292c30);
+}
+
+/* The active tab gets an accent line so it reads as selected without relying on background alone. */
+.ObMdi-theme .dv-tab.dv-active-tab {
+	box-shadow: inset 0 -2px 0 var(--ds-color-accent-base-default, #116069);
+}
+
+.ObMdi-theme .dv-tab:focus-visible {
+	outline: 2px solid var(--ds-color-focus-outer, #1e2b3c);
+	outline-offset: -2px;
+}
+
+/* Dirty marker: a dot after the title */
+.ObMdi-tab--dirty .dv-default-tab-content::after {
+	content: " \2022";
+	color: var(--ds-color-warning-base-default, #b8860b);
+}
+
+.ObMdi-error {
+	display: flex;
+	flex-direction: column;
+	gap: var(--ds-size-2, 0.5rem);
+	padding: var(--ds-size-4, 1rem);
+	color: var(--ds-color-danger-text-default, #b3221a);
+}
+
+.ObMdi-error-title {
+	margin: 0;
+	font-weight: 600;
+}
+
+.ObMdi-error-message {
+	margin: 0;
+	white-space: pre-wrap;
+	font-size: var(--ds-font-size-2, 0.8125rem);
+	color: var(--ds-color-neutral-text-subtle, #5b5f64);
+}
+
+.ObMdi-watermark {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	width: 100%;
+	height: 100%;
+	color: var(--ds-color-neutral-text-subtle, #5b5f64);
+}
+
+.ObMdi-confirmClose-actions {
+	display: flex;
+	gap: var(--ds-size-2, 0.5rem);
+	justify-content: flex-end;
+}

package/src/mdi/Mdi.test.tsx

@@ -0,0 +1,87 @@
+import { act, render, screen } from "@testing-library/react";
+import { useEffect } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { Mdi } from "./Mdi.js";
+import { MdiProvider, useMdi, useMdiActiveDocument } from "./MdiContext.js";
+import { useMdiDocument } from "./MdiDocumentContext.js";
+import type { MdiApi, MdiDocumentProps, MdiDocumentTypes, MdiLayoutSpec } from "./types.js";
+
+vi.mock("@olenbetong/appframe-core", () => ({
+	getLocalizedString: (value: string) => value,
+}));
+
+function Note({ params }: MdiDocumentProps<{ label: string }>) {
+	let document = useMdiDocument();
+
+	return (
+		<div data-testid={document.id}>
+			<span>{params.label}</span>
+			<button type="button" onClick={() => document.setTitle(`${params.label}!`)}>
+				rename
+			</button>
+		</div>
+	);
+}
+
+function ActiveLabel() {
+	let active = useMdiActiveDocument();
+	return <output data-testid="active">{active?.id ?? "none"}</output>;
+}
+
+let apiRef: { current: MdiApi | null } = { current: null };
+
+function Grab() {
+	let api = useMdi();
+	useEffect(() => {
+		apiRef.current = api;
+	});
+	return null;
+}
+
+const types: MdiDocumentTypes = {
+	note: { component: Note, title: (params) => `Note ${params.label as string}` },
+	tree: { component: Note, singleton: true, closable: false, title: "Tree" },
+};
+
+const spec: MdiLayoutSpec = {
+	root: {
+		direction: "horizontal",
+		children: [
+			{ tabs: [{ type: "tree", params: { label: "Tree" } }], hideHeader: true },
+			{ tabs: [{ type: "note", key: "1", params: { label: "First" } }] },
+		],
+	},
+};
+
+describe("Mdi", () => {
+	it("renders the default layout through dockview and exposes the api", async () => {
+		render(
+			<MdiProvider types={types}>
+				<Grab />
+				<ActiveLabel />
+				<div style={{ width: 800, height: 600 }}>
+					<Mdi defaultLayout={spec} />
+				</div>
+			</MdiProvider>,
+		);
+
+		expect(await screen.findByText("First")).toBeInTheDocument();
+		expect(screen.getByTestId("tree")).toBeInTheDocument();
+		expect(apiRef.current?.getDocuments().map((document) => document.id)).toEqual(["tree", "note:1"]);
+
+		await act(async () => {
+			apiRef.current!.openDocument({ type: "note", key: "2", params: { label: "Second" } });
+		});
+
+		expect(await screen.findByText("Second")).toBeInTheDocument();
+		expect(screen.getByTestId("active")).toHaveTextContent("note:2");
+
+		await act(async () => {
+			await apiRef.current!.close("note:2");
+		});
+
+		expect(screen.queryByText("Second")).not.toBeInTheDocument();
+		expect(apiRef.current?.getDocument("tree")?.closable).toBe(false);
+	});
+});

package/src/mdi/Mdi.tsx

@@ -0,0 +1,141 @@
+import "dockview-react/dist/styles/dockview.css";
+import "./Mdi.css";
+
+import clsx from "clsx";
+import { type DockviewReadyEvent, DockviewReact, type IWatermarkPanelProps } from "dockview-react";
+import { type CSSProperties, createContext, type ReactNode, use, useCallback, useEffect, useState } from "react";
+
+import { useDsColorScheme } from "../theme/useDsColorScheme.js";
+import { copyDocumentAttributes, createDockviewHost } from "./dockviewHost.js";
+import { MDI_COMPONENT } from "./layoutSpec.js";
+import { MdiConfirmCloseDialog } from "./MdiConfirmCloseDialog.js";
+import { useMdiController } from "./MdiContext.js";
+import { MdiPanel } from "./MdiPanel.js";
+import { MdiTab } from "./MdiTab.js";
+import { mdiThemeDark, mdiThemeLight } from "./theme.js";
+import type { MdiConfirmCloseResult, MdiDocumentInfo, MdiLayoutSpec } from "./types.js";
+
+export type MdiProps = {
+	/** Storage key within the article. Without it nothing is restored or saved. */
+	id?: string;
+	/** A persisted layout is only restored when this matches. Bump it when `defaultLayout` changes shape. Default `0`. */
+	layoutVersion?: string | number;
+	defaultLayout: MdiLayoutSpec;
+	/**
+	 * Save every layout change to IndexedDB. Default: `true` when `id` is set. With `false` the
+	 * layout is only written by `saveLayout()`, and a saved layout is still restored on load
+	 * (explicit save/load commands, as in the Windows DailyOrders app).
+	 */
+	persist?: boolean;
+	/** Same-origin blank page popout windows open into. Default `/popout`. */
+	popoutUrl?: string;
+	/**
+	 * Turn drag and drop off entirely. Use it for fixed layouts where every group is
+	 * `locked: "no-drop-target"`: otherwise a tab dragged to the outer edge of the dock
+	 * lands in a new group it can never leave again.
+	 */
+	disableDnd?: boolean;
+	/** Replaces the built-in Save / Discard / Cancel dialog */
+	confirmClose?: (document: MdiDocumentInfo) => Promise<MdiConfirmCloseResult>;
+	/** Shown in a group that has no documents */
+	watermark?: ReactNode;
+	className?: string;
+	style?: CSSProperties;
+};
+
+const WatermarkContext = createContext<ReactNode>(null);
+
+function MdiWatermark(_props: IWatermarkPanelProps) {
+	let content = use(WatermarkContext);
+	return <div className="ObMdi-watermark">{content}</div>;
+}
+
+// Module-level so dockview sees the same registry on every render.
+const COMPONENTS = { [MDI_COMPONENT]: MdiPanel };
+const TAB_COMPONENTS = { [MDI_COMPONENT]: MdiTab };
+type CloseRequest = { document: MdiDocumentInfo; resolve: (result: MdiConfirmCloseResult) => void };
+
+/**
+ * The dock: tiled groups of tabbed documents that can be rearranged by drag and
+ * drop or moved to a popout window. Fills its parent, so render it in a block
+ * with a height, such as `<Page.Block grow overflow="hidden">`.
+ */
+export function Mdi({
+	id,
+	layoutVersion = 0,
+	defaultLayout,
+	persist = id !== undefined,
+	popoutUrl = "/popout",
+	disableDnd = false,
+	confirmClose,
+	watermark = null,
+	className,
+	style,
+}: MdiProps) {
+	let controller = useMdiController();
+	let [anchor, setAnchor] = useState<HTMLDivElement | null>(null);
+	let colorScheme = useDsColorScheme(anchor);
+	let [closeRequest, setCloseRequest] = useState<CloseRequest | null>(null);
+
+	let defaultConfirmClose = useCallback(
+		(document: MdiDocumentInfo) =>
+			new Promise<MdiConfirmCloseResult>((resolve) => {
+				setCloseRequest({ document, resolve });
+			}),
+		[],
+	);
+
+	// The controller reads the options when it needs them, so they may change freely.
+	controller.setOptions({
+		id,
+		layoutVersion,
+		defaultLayout,
+		persist,
+		popoutUrl,
+		confirmClose: confirmClose ?? defaultConfirmClose,
+	});
+
+	let onReady = useCallback(
+		(event: DockviewReadyEvent) => {
+			let { api } = event;
+			controller.attach(createDockviewHost(api));
+
+			// dockview disposes these listeners together with the api.
+			api.onDidAddPopoutGroup((popout) => {
+				copyDocumentAttributes(document, popout.window.document);
+			});
+			api.onDidOpenPopoutWindowFail(() => {
+				console.warn("Mdi: the popout window was blocked by the browser.");
+			});
+
+			void controller.initialize();
+		},
+		[controller],
+	);
+
+	useEffect(() => () => controller.detach(), [controller]);
+
+	function handleCloseResult(result: MdiConfirmCloseResult) {
+		closeRequest?.resolve(result);
+		setCloseRequest(null);
+	}
+
+	return (
+		<WatermarkContext value={watermark}>
+			<div className={clsx("ObMdi-root", className)} style={style} ref={setAnchor}>
+				<DockviewReact
+					components={COMPONENTS}
+					tabComponents={TAB_COMPONENTS}
+					defaultTabComponent={MdiTab}
+					watermarkComponent={MdiWatermark}
+					theme={colorScheme === "dark" ? mdiThemeDark : mdiThemeLight}
+					popoutUrl={popoutUrl}
+					disableDnd={disableDnd}
+					disableFloatingGroups
+					onReady={onReady}
+				/>
+				<MdiConfirmCloseDialog document={closeRequest?.document ?? null} onResult={handleCloseResult} />
+			</div>
+		</WatermarkContext>
+	);
+}

package/src/mdi/MdiConfirmCloseDialog.tsx

@@ -0,0 +1,47 @@
+import { Button, Dialog, Heading, Paragraph } from "@digdir/designsystemet-react";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+
+import type { MdiConfirmCloseResult, MdiDocumentInfo } from "./types.js";
+
+export type MdiConfirmCloseDialogProps = {
+	/** The document being closed, or `null` when the dialog is closed */
+	document: MdiDocumentInfo | null;
+	onResult: (result: MdiConfirmCloseResult) => void;
+};
+
+/** Save / Discard / Cancel prompt shown when a dirty document is closed. */
+export function MdiConfirmCloseDialog({ document, onResult }: MdiConfirmCloseDialogProps) {
+	let title = document?.title ?? document?.id ?? "";
+
+	return (
+		<Dialog
+			open={document !== null}
+			closedby="any"
+			data-size="sm"
+			className="ObMdi-confirmClose"
+			onClose={() => onResult("cancel")}
+		>
+			<Dialog.Block>
+				<Heading level={2} data-size="xs">
+					{getLocalizedString("Unsaved changes")}
+				</Heading>
+			</Dialog.Block>
+			<Dialog.Block>
+				<Paragraph>
+					{getLocalizedString("Do you want to save the changes to {0} before closing?").replace("{0}", title)}
+				</Paragraph>
+			</Dialog.Block>
+			<Dialog.Block className="ObMdi-confirmClose-actions">
+				<Button type="button" data-size="sm" onClick={() => onResult("save")}>
+					{getLocalizedString("Save")}
+				</Button>
+				<Button type="button" data-size="sm" variant="secondary" onClick={() => onResult("discard")}>
+					{getLocalizedString("Discard")}
+				</Button>
+				<Button type="button" data-size="sm" variant="tertiary" onClick={() => onResult("cancel")}>
+					{getLocalizedString("Cancel")}
+				</Button>
+			</Dialog.Block>
+		</Dialog>
+	);
+}

package/src/mdi/MdiContext.tsx

@@ -0,0 +1,59 @@
+import { createContext, type ReactNode, use, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+
+import { MdiController } from "./controller.js";
+import type { MdiApi, MdiDocumentInfo, MdiDocumentTypes } from "./types.js";
+
+const MdiControllerContext = createContext<MdiController | null>(null);
+
+export type MdiProviderProps = {
+	/** The document types this workspace can show, keyed by type name */
+	types: MdiDocumentTypes;
+	children: ReactNode;
+};
+
+/**
+ * Owns the document controller. Anything inside it can call `useMdi()`, so
+ * toolbars and menus outside the dock itself can open and close documents.
+ */
+export function MdiProvider({ types, children }: MdiProviderProps) {
+	let [controller] = useState(() => new MdiController(types));
+
+	useEffect(() => {
+		controller.setTypes(types);
+	}, [controller, types]);
+
+	return <MdiControllerContext value={controller}>{children}</MdiControllerContext>;
+}
+
+export function useMdiController(): MdiController {
+	let controller = use(MdiControllerContext);
+
+	if (!controller) {
+		throw new Error("Mdi: this component must be rendered inside <MdiProvider>.");
+	}
+
+	return controller;
+}
+
+/** The imperative document API: open, activate, close, titles, layout commands. */
+export function useMdi(): MdiApi {
+	return useMdiController();
+}
+
+/** The active document, re-rendering when it changes. Drives shared panels such as a property grid. */
+export function useMdiActiveDocument(): MdiDocumentInfo | undefined {
+	let controller = useMdiController();
+	return useSyncExternalStore(controller.subscribeStore, controller.getActive, controller.getActive);
+}
+
+/** The open documents, optionally of one type. For "Windows" menus and the like. */
+export function useMdiDocuments(type?: string): MdiDocumentInfo[] {
+	let controller = useMdiController();
+	let all = useSyncExternalStore(
+		controller.subscribeStore,
+		controller.getDocumentsSnapshot,
+		controller.getDocumentsSnapshot,
+	);
+
+	return useMemo(() => (type === undefined ? all : all.filter((document) => document.type === type)), [all, type]);
+}