@olenbetong/appframe-ds 1.7.2 → 1.9.0

package/src/layout/AppMenu.tsx

@@ -1,74 +1,74 @@
-import "./AppMenu.css";
-
-import clsx from "clsx";
-import type React from "react";
-import { getLocalizedString } from "../i18n.js";
-
-type MenuHeaderProps = {
-	children?: React.ReactNode[] | React.ReactNode;
-	primary: string;
-	secondary?: string;
-};
-
-function MenuHeader({ primary, secondary }: MenuHeaderProps) {
-	return (
-		<>
-			<div className="AppMenu-header">
-				<h1 className="AppMenu-title" id="NavigationHeader">
-					{primary}
-				</h1>
-				{secondary && <p className="AppMenu-subTitle">{secondary}</p>}
-			</div>
-			<hr className="AppMenu-divider" />
-		</>
-	);
-}
-
-function handleKeyDown(evt: React.KeyboardEvent) {
-	let nextElement: Element | null | undefined = null;
-	let appMenu = evt.currentTarget;
-
-	if (!document.activeElement || !(appMenu instanceof HTMLElement) || !appMenu.contains(document.activeElement)) return;
-
-	let links = Array.from(appMenu.querySelectorAll<HTMLElement>("a, button"));
-	let currentIndex = links.indexOf(document.activeElement as HTMLElement);
-
-	if (evt.key === "ArrowDown" || evt.key === "ArrowRight") {
-		if (currentIndex < links.length) {
-			nextElement = links[currentIndex + 1];
-		}
-	} else if (evt.key === "ArrowUp" || evt.key === "ArrowLeft") {
-		if (currentIndex > 0) {
-			nextElement = links[currentIndex - 1];
-		}
-	} else if (evt.key === "Home" || evt.key === "End") {
-		nextElement = links.at(evt.key === "Home" ? 0 : -1);
-	}
-
-	if (nextElement instanceof HTMLElement) {
-		evt.preventDefault();
-		nextElement.scrollIntoView({ block: "nearest" });
-		nextElement.focus();
-	}
-}
-
-export type AppMenuProps = Pick<React.HTMLProps<HTMLElement>, "aria-label" | "aria-labelledby" | "className" | "id"> & {
-	children?: React.ReactNode[] | React.ReactNode;
-	headerPrimary?: string;
-	headerSecondary?: string;
-};
-
-export function AppMenu({ children, className, headerPrimary, headerSecondary, ...props }: AppMenuProps) {
-	return (
-		<nav
-			aria-labelledby={headerPrimary ? "NavigationHeader" : undefined}
-			aria-label={headerPrimary ? undefined : getLocalizedString("Application pages")}
-			className={clsx(className, "MenuItems-root")}
-			onKeyDown={handleKeyDown}
-			{...props}
-		>
-			{headerPrimary && <MenuHeader primary={headerPrimary} secondary={headerSecondary} />}
-			{children}
-		</nav>
-	);
-}
+import "./AppMenu.css";
+
+import clsx from "clsx";
+import type React from "react";
+import { getLocalizedString } from "../i18n.js";
+
+type MenuHeaderProps = {
+	children?: React.ReactNode[] | React.ReactNode;
+	primary: string;
+	secondary?: string;
+};
+
+function MenuHeader({ primary, secondary }: MenuHeaderProps) {
+	return (
+		<>
+			<div className="AppMenu-header">
+				<h1 className="AppMenu-title" id="NavigationHeader">
+					{primary}
+				</h1>
+				{secondary && <p className="AppMenu-subTitle">{secondary}</p>}
+			</div>
+			<hr className="AppMenu-divider" />
+		</>
+	);
+}
+
+function handleKeyDown(evt: React.KeyboardEvent) {
+	let nextElement: Element | null | undefined = null;
+	let appMenu = evt.currentTarget;
+
+	if (!document.activeElement || !(appMenu instanceof HTMLElement) || !appMenu.contains(document.activeElement)) return;
+
+	let links = Array.from(appMenu.querySelectorAll<HTMLElement>("a, button"));
+	let currentIndex = links.indexOf(document.activeElement as HTMLElement);
+
+	if (evt.key === "ArrowDown" || evt.key === "ArrowRight") {
+		if (currentIndex < links.length) {
+			nextElement = links[currentIndex + 1];
+		}
+	} else if (evt.key === "ArrowUp" || evt.key === "ArrowLeft") {
+		if (currentIndex > 0) {
+			nextElement = links[currentIndex - 1];
+		}
+	} else if (evt.key === "Home" || evt.key === "End") {
+		nextElement = links.at(evt.key === "Home" ? 0 : -1);
+	}
+
+	if (nextElement instanceof HTMLElement) {
+		evt.preventDefault();
+		nextElement.scrollIntoView({ block: "nearest" });
+		nextElement.focus();
+	}
+}
+
+export type AppMenuProps = Pick<React.HTMLProps<HTMLElement>, "aria-label" | "aria-labelledby" | "className" | "id"> & {
+	children?: React.ReactNode[] | React.ReactNode;
+	headerPrimary?: string;
+	headerSecondary?: string;
+};
+
+export function AppMenu({ children, className, headerPrimary, headerSecondary, ...props }: AppMenuProps) {
+	return (
+		<nav
+			aria-labelledby={headerPrimary ? "NavigationHeader" : undefined}
+			aria-label={headerPrimary ? undefined : getLocalizedString("Application pages")}
+			className={clsx(className, "MenuItems-root")}
+			onKeyDown={handleKeyDown}
+			{...props}
+		>
+			{headerPrimary && <MenuHeader primary={headerPrimary} secondary={headerSecondary} />}
+			{children}
+		</nav>
+	);
+}

package/src/layout/AppMenuDrawer.css

@@ -1,71 +1,71 @@
-/* --- 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%);
-		/* Same timing as the content offset in Page.css, so the two edges move together. */
-		transition: transform 225ms cubic-bezier(0.4, 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;
-	}
-}
+/* --- 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%);
+		/* Same timing as the content offset in Page.css, so the two edges move together. */
+		transition: transform 225ms cubic-bezier(0.4, 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

@@ -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>
+		</>
+	);
+}