@olenbetong/appframe-ds 1.0.3 → 1.2.0

package/src/mdi/types.ts

@@ -1,214 +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;
-};
+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

@@ -1,53 +1,53 @@
-@media screen {
-	/*
-	 * Pages get a tinted background so surfaces (Paper, drawer, dialogs —
-	 * which use neutral-background/surface-default) stand out, matching the
-	 * old site design. Scoped to Page usage so the token itself is untouched.
-	 */
-	body:has(.ObPage-root) {
-		background-color: var(--ds-color-neutral-background-tinted, #f3f3f4);
-	}
-
-	.ObPage-root {
-		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: 100%;
-		overflow: hidden;
-	}
-
-	/* Offset content when a docked Page.Header drawer is open (desktop) */
-	.ObPage-root:has(.ObPageHeader-drawer.ObPageHeader-drawerDocked.ObPageHeader-drawerOpen) {
-		padding-left: var(--ob-page-drawer-width, 20rem);
-		transition: padding-left 225ms cubic-bezier(0.4, 0, 0.2, 1);
-	}
-}
-
-@media print {
-	.ObPage-root,
-	.ObPage-app {
-		display: block;
-		height: auto;
-		overflow: visible;
-	}
-
-	.ObPage-root:has(.ObPageHeader-drawer.ObPageHeader-drawerDocked.ObPageHeader-drawerOpen) {
-		padding-left: 0;
-	}
-}
+@media screen {
+	/*
+	 * Pages get a tinted background so surfaces (Paper, drawer, dialogs —
+	 * which use neutral-background/surface-default) stand out, matching the
+	 * old site design. Scoped to Page usage so the token itself is untouched.
+	 */
+	body:has(.ObPage-root) {
+		background-color: var(--ds-color-neutral-background-tinted, #f3f3f4);
+	}
+
+	.ObPage-root {
+		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: 100%;
+		overflow: hidden;
+	}
+
+	/* Offset content when a docked Page.Header drawer is open (desktop) */
+	.ObPage-root:has(.ObPageHeader-drawer.ObPageHeader-drawerDocked.ObPageHeader-drawerOpen) {
+		padding-left: var(--ob-page-drawer-width, 20rem);
+		transition: padding-left 225ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+}
+
+@media print {
+	.ObPage-root,
+	.ObPage-app {
+		display: block;
+		height: auto;
+		overflow: visible;
+	}
+
+	.ObPage-root:has(.ObPageHeader-drawer.ObPageHeader-drawerDocked.ObPageHeader-drawerOpen) {
+		padding-left: 0;
+	}
+}

package/src/page/PageBlock.css

@@ -1,64 +1,64 @@
-.ObPageBlock-root {
-	box-sizing: border-box;
-	width: 100%;
-	margin-inline: auto;
-}
-
-.ObPageBlock-text {
-	max-width: calc(36rem + 2 * var(--ob-page-gutter, 0rem));
-}
-
-.ObPageBlock-md {
-	max-width: 48rem;
-}
-
-.ObPageBlock-lg {
-	max-width: 64rem;
-}
-
-.ObPageBlock-xl {
-	max-width: 80rem;
-}
-
-.ObPageBlock-2xl {
-	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;
-
-	padding-inline: var(--ob-page-gutter);
-}
-
-@media screen and (min-width: 600px) {
-	.ObPageBlock-gutters {
-		--ob-page-gutter: 1.5rem;
-	}
-}
-
-@media screen {
-	.ObPageBlock-grow {
-		flex: 1 1 auto;
-		min-height: 0;
-	}
-
-	.ObPageBlock-overflowAuto {
-		overflow: auto;
-	}
-
-	.ObPageBlock-overflowHidden {
-		overflow: hidden;
-	}
-}
-
-@media print {
-	.ObPageBlock-overflowAuto,
-	.ObPageBlock-overflowHidden {
-		overflow: visible;
-	}
-}
+.ObPageBlock-root {
+	box-sizing: border-box;
+	width: 100%;
+	margin-inline: auto;
+}
+
+.ObPageBlock-text {
+	max-width: calc(36rem + 2 * var(--ob-page-gutter, 0rem));
+}
+
+.ObPageBlock-md {
+	max-width: 48rem;
+}
+
+.ObPageBlock-lg {
+	max-width: 64rem;
+}
+
+.ObPageBlock-xl {
+	max-width: 80rem;
+}
+
+.ObPageBlock-2xl {
+	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;
+
+	padding-inline: var(--ob-page-gutter);
+}
+
+@media screen and (min-width: 600px) {
+	.ObPageBlock-gutters {
+		--ob-page-gutter: 1.5rem;
+	}
+}
+
+@media screen {
+	.ObPageBlock-grow {
+		flex: 1 1 auto;
+		min-height: 0;
+	}
+
+	.ObPageBlock-overflowAuto {
+		overflow: auto;
+	}
+
+	.ObPageBlock-overflowHidden {
+		overflow: hidden;
+	}
+}
+
+@media print {
+	.ObPageBlock-overflowAuto,
+	.ObPageBlock-overflowHidden {
+		overflow: visible;
+	}
+}