@olenbetong/appframe-ds 1.2.0 → 1.3.0

package/src/layout/AppMenuDrawer.tsx

@@ -1,122 +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>
-		</>
-	);
-}
+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/ErrorBoundary.tsx

@@ -1,162 +1,162 @@
-import "./ErrorBoundary.css";
-
-import type { DataObject } from "@olenbetong/appframe-data";
-import { useError } from "@olenbetong/appframe-react";
-
-import { Component, useEffect } from "react";
-import { useAsyncError, useRouteError } from "react-router";
-
-import { PageContainer } from "./PageContainer.js";
-import { getLocalizedString } from "../i18n.js";
-
-function parseError(error: unknown) {
-	let message = "Unspecified error";
-	let stackTrace: string | null = null;
-	let title: string = getLocalizedString("Unexpected application error");
-
-	if (typeof error === "string") {
-		message = error;
-	} else if (error && typeof error === "object") {
-		const err = error as any;
-		if (err.status) {
-			title = `${err.status} ${err.statusText}`;
-			message = err.message ?? "";
-		} else if (err.message) {
-			message = err.message;
-			if (err.type) {
-				message = `${err.type}: ${message}`;
-			}
-		} else {
-			message = String(error);
-		}
-
-		if (err.stack || err.stackTrace) {
-			stackTrace = err.stack ?? err.stackTrace;
-		}
-	}
-
-	return { message, stackTrace, title };
-}
-
-// ── AppErrorBoundary ──────────────────────────────────────────────────────────
-
-export type AppErrorBoundaryProps = {
-	children?: React.ReactNode;
-	message?: string | ((error: unknown) => string);
-	imgSrc?: string;
-	image?: React.ReactNode;
-};
-
-type AppErrorBoundaryState = {
-	hasError: boolean;
-	error: unknown;
-};
-
-export class AppErrorBoundary extends Component<AppErrorBoundaryProps, AppErrorBoundaryState> {
-	constructor(props: AppErrorBoundaryProps) {
-		super(props);
-		this.state = { hasError: false, error: null };
-	}
-
-	static getDerivedStateFromError(error: unknown): AppErrorBoundaryState {
-		return { hasError: true, error };
-	}
-
-	componentDidCatch(error: unknown, errorInfo: unknown) {
-		console.error(error, errorInfo);
-	}
-
-	render(): React.ReactNode {
-		if (this.state.hasError) {
-			const { imgSrc, message, image } = this.props;
-			const { message: errorMessage } = parseError(this.state.error);
-			const customMessage = typeof message === "function" ? message(this.state.error) : message;
-
-			return (
-				<div className="AppErrorBoundary-root">
-					<div className="AppErrorBoundary-inner">
-						{image ?? (
-							<img
-								alt=""
-								src={imgSrc ?? "/file/site/graphic/error-broken-robot.svg"}
-								className="AppErrorBoundary-image"
-							/>
-						)}
-						<h1 className="AppErrorBoundary-title">{getLocalizedString("Something went terribly wrong!")}</h1>
-						<div className="AppErrorBoundary-alert">{errorMessage}</div>
-						<p className="AppErrorBoundary-message">
-							{customMessage ??
-								getLocalizedString(
-									"Sometimes it is enough to simply refresh the page. If the error persists, contact the IT department.",
-								)}
-						</p>
-						<button type="button" className="AppErrorBoundary-reload" onClick={() => window.location.reload()}>
-							{getLocalizedString("Refresh page")}
-						</button>
-					</div>
-				</div>
-			);
-		}
-
-		return this.props.children;
-	}
-}
-
-// ── ErrorAlertFallback ────────────────────────────────────────────────────────
-
-export type ErrorAlertFallbackProps = {
-	error: unknown;
-	className?: string;
-};
-
-export function ErrorAlertFallback({ error, className }: ErrorAlertFallbackProps) {
-	const message = error instanceof Error ? error.message : String(error);
-
-	return (
-		<div className={`ErrorAlertFallback-root${className ? ` ${className}` : ""}`}>
-			<div className="ErrorAlertFallback-content">
-				<p className="ErrorAlertFallback-title">{getLocalizedString("An error occured. Try refreshing the page")}</p>
-				<p>{message}</p>
-			</div>
-			<button type="button" className="ErrorAlertFallback-reload" onClick={() => window.location.reload()}>
-				{getLocalizedString("Reload page")}
-			</button>
-		</div>
-	);
-}
-
-// ── RouteErrorPage ────────────────────────────────────────────────────────────
-
-export function RouteErrorPage() {
-	const error = useRouteError();
-	const { message, stackTrace, title } = parseError(error);
-
-	useEffect(() => {
-		(globalThis as any).af?.common?.logError?.(error);
-	}, [error]);
-
-	return (
-		<PageContainer className="flow">
-			<h1>{title}</h1>
-			{message && <p>{message}</p>}
-			{stackTrace && <pre className="RouteErrorPage-stack">{stackTrace}</pre>}
-		</PageContainer>
-	);
-}
-
-// ── AsyncErrorAlert ───────────────────────────────────────────────────────────
-
-export function AsyncErrorAlert() {
-	const error = useAsyncError();
-	const message = typeof error === "string" ? error : (error as any)?.message;
-
-	return <div className="ErrorAlertFallback-root">{message}</div>;
-}
-
-// ── DataObjectErrorAlert ──────────────────────────────────────────────────────
-
-export function DataObjectErrorAlert({ dataObject }: { dataObject: DataObject<any> }) {
-	const error = useError(dataObject);
-
-	return error ? <div className="ErrorAlertFallback-root">{error}</div> : null;
-}
+import "./ErrorBoundary.css";
+
+import type { DataObject } from "@olenbetong/appframe-data";
+import { useError } from "@olenbetong/appframe-react";
+
+import { Component, useEffect } from "react";
+import { useAsyncError, useRouteError } from "react-router";
+
+import { PageContainer } from "./PageContainer.js";
+import { getLocalizedString } from "../i18n.js";
+
+function parseError(error: unknown) {
+	let message = "Unspecified error";
+	let stackTrace: string | null = null;
+	let title: string = getLocalizedString("Unexpected application error");
+
+	if (typeof error === "string") {
+		message = error;
+	} else if (error && typeof error === "object") {
+		const err = error as any;
+		if (err.status) {
+			title = `${err.status} ${err.statusText}`;
+			message = err.message ?? "";
+		} else if (err.message) {
+			message = err.message;
+			if (err.type) {
+				message = `${err.type}: ${message}`;
+			}
+		} else {
+			message = String(error);
+		}
+
+		if (err.stack || err.stackTrace) {
+			stackTrace = err.stack ?? err.stackTrace;
+		}
+	}
+
+	return { message, stackTrace, title };
+}
+
+// ── AppErrorBoundary ──────────────────────────────────────────────────────────
+
+export type AppErrorBoundaryProps = {
+	children?: React.ReactNode;
+	message?: string | ((error: unknown) => string);
+	imgSrc?: string;
+	image?: React.ReactNode;
+};
+
+type AppErrorBoundaryState = {
+	hasError: boolean;
+	error: unknown;
+};
+
+export class AppErrorBoundary extends Component<AppErrorBoundaryProps, AppErrorBoundaryState> {
+	constructor(props: AppErrorBoundaryProps) {
+		super(props);
+		this.state = { hasError: false, error: null };
+	}
+
+	static getDerivedStateFromError(error: unknown): AppErrorBoundaryState {
+		return { hasError: true, error };
+	}
+
+	componentDidCatch(error: unknown, errorInfo: unknown) {
+		console.error(error, errorInfo);
+	}
+
+	render(): React.ReactNode {
+		if (this.state.hasError) {
+			const { imgSrc, message, image } = this.props;
+			const { message: errorMessage } = parseError(this.state.error);
+			const customMessage = typeof message === "function" ? message(this.state.error) : message;
+
+			return (
+				<div className="AppErrorBoundary-root">
+					<div className="AppErrorBoundary-inner">
+						{image ?? (
+							<img
+								alt=""
+								src={imgSrc ?? "/file/site/graphic/error-broken-robot.svg"}
+								className="AppErrorBoundary-image"
+							/>
+						)}
+						<h1 className="AppErrorBoundary-title">{getLocalizedString("Something went terribly wrong!")}</h1>
+						<div className="AppErrorBoundary-alert">{errorMessage}</div>
+						<p className="AppErrorBoundary-message">
+							{customMessage ??
+								getLocalizedString(
+									"Sometimes it is enough to simply refresh the page. If the error persists, contact the IT department.",
+								)}
+						</p>
+						<button type="button" className="AppErrorBoundary-reload" onClick={() => window.location.reload()}>
+							{getLocalizedString("Refresh page")}
+						</button>
+					</div>
+				</div>
+			);
+		}
+
+		return this.props.children;
+	}
+}
+
+// ── ErrorAlertFallback ────────────────────────────────────────────────────────
+
+export type ErrorAlertFallbackProps = {
+	error: unknown;
+	className?: string;
+};
+
+export function ErrorAlertFallback({ error, className }: ErrorAlertFallbackProps) {
+	const message = error instanceof Error ? error.message : String(error);
+
+	return (
+		<div className={`ErrorAlertFallback-root${className ? ` ${className}` : ""}`}>
+			<div className="ErrorAlertFallback-content">
+				<p className="ErrorAlertFallback-title">{getLocalizedString("An error occured. Try refreshing the page")}</p>
+				<p>{message}</p>
+			</div>
+			<button type="button" className="ErrorAlertFallback-reload" onClick={() => window.location.reload()}>
+				{getLocalizedString("Reload page")}
+			</button>
+		</div>
+	);
+}
+
+// ── RouteErrorPage ────────────────────────────────────────────────────────────
+
+export function RouteErrorPage() {
+	const error = useRouteError();
+	const { message, stackTrace, title } = parseError(error);
+
+	useEffect(() => {
+		(globalThis as any).af?.common?.logError?.(error);
+	}, [error]);
+
+	return (
+		<PageContainer className="flow">
+			<h1>{title}</h1>
+			{message && <p>{message}</p>}
+			{stackTrace && <pre className="RouteErrorPage-stack">{stackTrace}</pre>}
+		</PageContainer>
+	);
+}
+
+// ── AsyncErrorAlert ───────────────────────────────────────────────────────────
+
+export function AsyncErrorAlert() {
+	const error = useAsyncError();
+	const message = typeof error === "string" ? error : (error as any)?.message;
+
+	return <div className="ErrorAlertFallback-root">{message}</div>;
+}
+
+// ── DataObjectErrorAlert ──────────────────────────────────────────────────────
+
+export function DataObjectErrorAlert({ dataObject }: { dataObject: DataObject<any> }) {
+	const error = useError(dataObject);
+
+	return error ? <div className="ErrorAlertFallback-root">{error}</div> : null;
+}

package/src/layout/PageContainer.css

@@ -10,9 +10,11 @@
 	}
 
 	.ObPageContainer-inner {
+		--ob-page-container-gutter: 1rem;
+
 		margin-left: 0;
 		height: auto;
-		padding: 1rem;
+		padding: 1rem var(--ob-page-container-gutter);
 		box-sizing: border-box;
 		max-width: 100%;
 	}
@@ -20,10 +22,27 @@
 	.ObPageContainer-fullHeight .ObPageContainer-inner {
 		height: 100%;
 	}
+
+	/* The content width on the MUI Container scale; the gutters come on top. */
+	.ObPageContainer-inner.ObPageContainer-text {
+		max-width: calc(36rem + 2 * var(--ob-page-container-gutter));
+	}
+
+	.ObPageContainer-inner.ObPageContainer-md {
+		max-width: calc(48rem + 2 * var(--ob-page-container-gutter));
+	}
+
+	.ObPageContainer-inner.ObPageContainer-lg {
+		max-width: calc(64rem + 2 * var(--ob-page-container-gutter));
+	}
+
+	.ObPageContainer-inner.ObPageContainer-xl {
+		max-width: calc(80rem + 2 * var(--ob-page-container-gutter));
+	}
 }
 
 @media screen and (min-width: 600px) {
 	.ObPageContainer-inner {
-		padding: 1rem 1.5rem;
+		--ob-page-container-gutter: 1.5rem;
 	}
 }

package/src/layout/PageContainer.tsx

@@ -3,9 +3,25 @@ import "./PageContainer.css";
 import clsx from "clsx";
 import type React from "react";
 
+export type PageContainerMaxWidth = "xs" | "sm" | "md" | "lg" | "xl" | false;
+
 export type PageContainerProps = React.HTMLAttributes<HTMLDivElement> & {
 	fullHeight?: boolean;
-	maxWidth?: "xs" | "sm" | "md" | "lg" | "xl" | false;
+	/**
+	 * Predefined max-width of the content, on the MUI `Container` scale (`xs`/`sm` 36rem,
+	 * `md` 48rem, `lg` 64rem, `xl` 80rem, plus the gutters). The content stays against the
+	 * leading edge, as the MUI-era `PageContainer` did; `Page.Block`/`Container` centre it.
+	 * @default max-width: 100%
+	 */
+	maxWidth?: PageContainerMaxWidth;
+};
+
+const maxWidthClassName: Record<Exclude<PageContainerMaxWidth, false>, string> = {
+	xs: "ObPageContainer-text",
+	sm: "ObPageContainer-text",
+	md: "ObPageContainer-md",
+	lg: "ObPageContainer-lg",
+	xl: "ObPageContainer-xl",
 };
 
 /**
@@ -17,7 +33,7 @@ export type PageContainerProps = React.HTMLAttributes<HTMLDivElement> & {
 export function PageContainer({ children, className, fullHeight, maxWidth, ...props }: PageContainerProps) {
 	return (
 		<div className={clsx("ObPageContainer-root", fullHeight && "ObPageContainer-fullHeight")}>
-			<div className={clsx("ObPageContainer-inner", className)} {...props}>
+			<div className={clsx("ObPageContainer-inner", maxWidth && maxWidthClassName[maxWidth], className)} {...props}>
 				{children}
 			</div>
 		</div>