shelving 1.200.1 → 1.202.0

package/api/provider/APIProvider.d.ts

@@ -2,7 +2,7 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 /** Provider for API endpoints rooted at a common base URL. */
-export declare abstract class APIProvider<P = unknown, R = unknown> {
+export declare abstract class APIProvider<P = unknown, R = unknown> implements AsyncDisposable {
     /** The base URL for this API. */
     abstract readonly url: URL;
     /**
@@ -43,4 +43,5 @@ export declare abstract class APIProvider<P = unknown, R = unknown> {
     abstract parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
     /** Send a payload to an `Endpoint` and retrieve the result. */
     call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/APIProvider.js

@@ -6,4 +6,8 @@ export class APIProvider {
         const response = await this.fetch(request);
         return this.parseResponse(endpoint, response, caller);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        // Empty by default.
+    }
 }

package/api/provider/CachedAPIProvider.d.ts

@@ -13,7 +13,7 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - Note: This is not used for `refresh()` calls — when you call `refresh()` you likely mean "do it now".
  * - When we are using `call()` on a cache, the entire point of the cache is to "cache", so the default isn't `0` like it is for `refresh()`
  */
-export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
+export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> implements AsyncDisposable {
     readonly maxAge: number | undefined;
     private readonly _cache;
     constructor(source: APIProvider<P, R>, maxAge?: number);
@@ -22,4 +22,5 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
     invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
     refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/CachedAPIProvider.js

@@ -1,4 +1,5 @@
 import { AVOID_REFRESH } from "../../store/FetchStore.js";
+import { awaitDispose } from "../../util/dispose.js";
 import { APICache } from "../cache/APICache.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
@@ -35,4 +36,9 @@ export class CachedAPIProvider extends ThroughAPIProvider {
     refreshAll(endpoint) {
         this._cache.refreshAll(endpoint, this.maxAge);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this._cache, // Dispose the cache.
+        super[Symbol.asyncDispose]());
+    }
 }

package/api/provider/ThroughAPIProvider.d.ts

@@ -15,4 +15,5 @@ export declare class ThroughAPIProvider<P, R> extends APIProvider<P, R> implemen
     getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
     fetch(request: Request): Promise<Response>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/ThroughAPIProvider.js

@@ -1,3 +1,4 @@
+import { awaitDispose } from "../../util/dispose.js";
 import { APIProvider } from "./APIProvider.js";
 /**
  * Provider wrapper that delegates API operations to a source provider.
@@ -24,4 +25,8 @@ export class ThroughAPIProvider extends APIProvider {
     fetch(request) {
         return this.source.fetch(request);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this.source);
+    }
 }

package/db/provider/CacheDBProvider.d.ts

@@ -23,4 +23,5 @@ export declare class CacheDBProvider<I extends Identifier, T extends Data> exten
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/CacheDBProvider.js

@@ -1,3 +1,4 @@
+import { awaitDispose } from "../../util/dispose.js";
 import { DBProvider } from "./DBProvider.js";
 import { MemoryDBProvider } from "./MemoryDBProvider.js";
 /** Keep a copy of asynchronous remote data in a local synchronous cache. */
@@ -58,4 +59,10 @@ export class CacheDBProvider extends DBProvider {
         await this.source.deleteQuery(collection, query);
         this.memory.getTable(collection).deleteQuery(query);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this.source, // Dispose the source API provider.
+        this.memory, // Dispose the source API provider.
+        super[Symbol.asyncDispose]());
+    }
 }

package/db/provider/ChangesDBProvider.d.ts

@@ -14,7 +14,10 @@ export type DBChange<I extends Identifier> = {
     readonly data?: unknown;
     readonly updates?: unknown;
 };
-/** Asynchronous provider that keeps a log of any written changes to its `.changes` property. */
+/**
+ * Database provider that keeps a log of any written changes to its `.changes` property.
+ * - This is useful if you want to hook into a database to build out audit logging functionality.
+ */
 export declare class ChangesDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
     get changes(): ReadonlyArray<DBChange<I>>;
     readonly _changes: MutableArray<DBChange<I>>;

package/db/provider/ChangesDBProvider.js

@@ -1,5 +1,8 @@
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
-/** Asynchronous provider that keeps a log of any written changes to its `.changes` property. */
+/**
+ * Database provider that keeps a log of any written changes to its `.changes` property.
+ * - This is useful if you want to hook into a database to build out audit logging functionality.
+ */
 export class ChangesDBProvider extends ThroughDBProvider {
     get changes() {
         return this._changes;

package/db/provider/DBProvider.d.ts

@@ -4,7 +4,7 @@ import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 /** Provider with a fully asynchronous interface for database access. */
-export declare abstract class DBProvider<I extends Identifier = Identifier, T extends Data = Data> {
+export declare abstract class DBProvider<I extends Identifier = Identifier, T extends Data = Data> implements AsyncDisposable {
     abstract getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
     requireItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<Item<II, TT>>;
     abstract getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
@@ -20,4 +20,5 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/DBProvider.js

@@ -1,5 +1,6 @@
 import { RequiredError } from "../../error/RequiredError.js";
 import { countArray, getFirst } from "../../util/array.js";
+import { awaitDispose } from "../../util/dispose.js";
 /** Provider with a fully asynchronous interface for database access. */
 export class DBProvider {
     async requireItem(collection, id) {
@@ -30,4 +31,10 @@ export class DBProvider {
             });
         return first;
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(
+        // Empty by default.
+        );
+    }
 }

package/db/provider/MemoryDBProvider.d.ts

@@ -8,7 +8,7 @@ import { DBProvider } from "./DBProvider.js";
 /**
  * Fast in-memory store for data.
  * - Extremely fast (ideal for caching!), but does not persist data after the browser window is closed.
- * - `get()` etc return the exact same instance of an object that's passed into `set()`
+ * - `getItem()` etc return the exact same instance of an object that's passed into `setItem()`
  */
 export declare class MemoryDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends DBProvider<I, T> {
     /** List of tables in `{ name: MemoryTable }` format. */

package/db/provider/MemoryDBProvider.js

@@ -11,7 +11,7 @@ import { DBProvider } from "./DBProvider.js";
 /**
  * Fast in-memory store for data.
  * - Extremely fast (ideal for caching!), but does not persist data after the browser window is closed.
- * - `get()` etc return the exact same instance of an object that's passed into `set()`
+ * - `getItem()` etc return the exact same instance of an object that's passed into `setItem()`
  */
 export class MemoryDBProvider extends DBProvider {
     /** List of tables in `{ name: MemoryTable }` format. */

package/db/provider/ThroughDBProvider.d.ts

@@ -24,4 +24,5 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/ThroughDBProvider.js

@@ -1,3 +1,4 @@
+import { awaitDispose } from "../../util/dispose.js";
 /** A provider that passes through to an asynchronous source. */
 export class ThroughDBProvider {
     source;
@@ -49,4 +50,8 @@ export class ThroughDBProvider {
     requireFirst(collection, query) {
         return this.source.requireFirst(collection, query);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this.source);
+    }
 }

package/markup/render.d.ts

@@ -1,13 +1,13 @@
-import type { JSXNode } from "../util/jsx.js";
+import type { Elements } from "../util/element.js";
 import type { MarkupOptions } from "./util/options.js";
 /**
- * Parse a text string as Markdownish syntax and render it as a JSX node.
+ * Parse a text string as Markdownish syntax and render it as elements.
  * - Syntax is not defined by this code, but by the rules supplied to it.
  *
  * @param input The string content possibly containing markup syntax, e.g. "This is a *bold* string.
  * @param options An options object for the render.
  * @param context The context to render in (defaults to `"block"`).
  *
- * @returns JSXNode, i.e. either a complete `JSXElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
+ * @returns Elements, i.e. either a complete `Element`, `null`, `undefined`, `string`, or an array of zero or more of those.
  */
-export declare function renderMarkup(input: string, options: MarkupOptions, context?: string): JSXNode;
+export declare function renderMarkup(input: string, options: MarkupOptions, context?: string): Elements;

package/markup/render.js

@@ -1,20 +1,20 @@
 /**
- * Parse a text string as Markdownish syntax and render it as a JSX node.
+ * Parse a text string as Markdownish syntax and render it as elements.
  * - Syntax is not defined by this code, but by the rules supplied to it.
  *
  * @param input The string content possibly containing markup syntax, e.g. "This is a *bold* string.
  * @param options An options object for the render.
  * @param context The context to render in (defaults to `"block"`).
  *
- * @returns JSXNode, i.e. either a complete `JSXElement`, `null`, `undefined`, `string`, or an array of zero or more of those.
+ * @returns Elements, i.e. either a complete `Element`, `null`, `undefined`, `string`, or an array of zero or more of those.
  */
 export function renderMarkup(input, options, context = "block") {
     const arr = Array.from(_parseString(input, options, context));
     return !arr.length ? null : arr.length === 1 ? arr[0] : arr;
 }
 /**
- * Parse a string to its corresponding JSX nodes in a given context.
- * - This code is heavily inspired by `simple-markdown`, but intends to be even simpler (and faster) by always producing JSX elements.
+ * Parse a string to its corresponding elements in a given context.
+ * - This code is heavily inspired by `simple-markdown`, but intends to be even simpler (and faster) by always producing elements.
  */
 function* _parseString(
 /** The input string. */

package/markup/rule/unordered.d.ts

@@ -1,4 +1,4 @@
-import type { JSXElement } from "../../util/jsx.js";
+import type { Element } from "../../util/element.js";
 import type { MarkupOptions } from "../util/options.js";
 export declare const UNORDERED_REGEXP: import("../../index.js").NamedRegExp<{
     list?: string;
@@ -13,4 +13,4 @@ export declare const UNORDERED_REGEXP: import("../../index.js").NamedRegExp<{
  */
 export declare const UNORDERED_RULE: import("../util/rule.js").MarkupRule;
 /** Parse a markdown list into a set of items elements. */
-export declare function _getItems(list: string, options: MarkupOptions): Iterable<JSXElement>;
+export declare function _getItems(list: string, options: MarkupOptions): Iterable<Element>;

package/markup/util/rule.d.ts

@@ -1,12 +1,12 @@
-import type { JSXElement } from "../../util/jsx.js";
+import type { Element } from "../../util/element.js";
 import type { NamedRegExp, NamedRegExpExecArray } from "../../util/regexp.js";
 import type { MarkupOptions } from "./options.js";
 export type MarkupContexts = [string, ...string[]];
 export interface MarkupRule {
     /** Regular expression used for matching the rule. */
     regexp: RegExp;
-    /** Use the matched data to render a JSX element. */
-    render(match: RegExpExecArray, options: MarkupOptions, key: string): JSXElement;
+    /** Use the matched data to render an element. */
+    render(match: RegExpExecArray, options: MarkupOptions, key: string): Element;
     /** One or more contexts this rule should render in. */
     contexts: MarkupContexts;
     /** Priority for this rule (higher priority rules override lower priority rules). */
@@ -14,4 +14,4 @@ export interface MarkupRule {
 }
 export type MarkupRules = readonly MarkupRule[];
 /** Helper to make it easier to create typed `MarkupRule` instances using `NamedRegExp` regular expressions. */
-export declare function getMarkupRule<T extends NamedRegExp | RegExp>(regexp: T, render: T extends NamedRegExp<infer X> ? (match: NamedRegExpExecArray<X>, options: MarkupOptions, key: string) => JSXElement : (match: RegExpExecArray, options: MarkupOptions, key: string) => JSXElement, contexts: MarkupContexts, priority?: number): MarkupRule;
+export declare function getMarkupRule<T extends NamedRegExp | RegExp>(regexp: T, render: T extends NamedRegExp<infer X> ? (match: NamedRegExpExecArray<X>, options: MarkupOptions, key: string) => Element : (match: RegExpExecArray, options: MarkupOptions, key: string) => Element, contexts: MarkupContexts, priority?: number): MarkupRule;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.200.1",
+	"version": "1.202.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -18,7 +18,8 @@
 		"@typescript/native-preview": "^7.0.0-dev.20260502.1",
 		"firebase": "^12.12.1",
 		"react": "canary",
-		"react-dom": "canary"
+		"react-dom": "canary",
+		"typescript": "^5"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=7.0.0",
@@ -69,6 +70,7 @@
 		"test:unit": "bun test --concurrent --only-failures",
 		"fix": "bun run --sequential fix:*",
 		"fix:0:lint": "biome check --write .",
+		"docs": "bun ./scripts/docs.tsx",
 		"build": "bun run --sequential build:*",
 		"build:0:setup": "rm -rf ./dist && mkdir -p ./dist",
 		"build:1:copy": "cp package.json dist/package.json && cp LICENSE.md dist/LICENSE.md && cp README.md dist/README.md && cp .npmignore dist/.npmignore && cp -r modules/ui dist/ui",

package/ui/app/App.d.ts

@@ -1,6 +1,6 @@
 import { type ReactElement, type ReactNode } from "react";
-import type { PossibleMetaData } from "../util/meta.js";
-export interface AppProps extends PossibleMetaData {
+import type { PossibleMeta } from "../util/meta.js";
+export interface AppProps extends PossibleMeta {
     children: ReactNode;
 }
 /**

package/ui/app/App.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from "react";
 import { Meta } from "../misc/Meta.js";
 import APP_CSS from "./App.module.css";
-const _appClass = APP_CSS.app;
+const APP_CLASS = APP_CSS.app;
 /**
  * Root component for an application.
  * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
@@ -10,12 +10,10 @@ const _appClass = APP_CSS.app;
  */
 export function App({ children, ...metadata }) {
     useEffect(() => {
-        if (!_appClass)
+        if (!APP_CLASS)
             return;
-        document.body.classList.add(_appClass);
-        return () => {
-            document.body.classList.remove(_appClass);
-        };
+        document.body.classList.add(APP_CLASS);
+        return () => document.body.classList.remove(APP_CLASS);
     }, []);
     return _jsx(Meta, { ...metadata, children: children });
 }

package/ui/app/App.tsx

@@ -1,13 +1,13 @@
 import { type ReactElement, type ReactNode, useEffect } from "react";
 import { Meta } from "../misc/Meta.js";
-import type { PossibleMetaData } from "../util/meta.js";
+import type { PossibleMeta } from "../util/meta.js";
 import APP_CSS from "./App.module.css";
 
-export interface AppProps extends PossibleMetaData {
+export interface AppProps extends PossibleMeta {
 	children: ReactNode;
 }
 
-const _appClass = APP_CSS.app;
+const APP_CLASS = APP_CSS.app;
 
 /**
  * Root component for an application.
@@ -16,11 +16,9 @@ const _appClass = APP_CSS.app;
  */
 export function App({ children, ...metadata }: AppProps): ReactElement {
 	useEffect(() => {
-		if (!_appClass) return;
-		document.body.classList.add(_appClass);
-		return () => {
-			document.body.classList.remove(_appClass);
-		};
+		if (!APP_CLASS) return;
+		document.body.classList.add(APP_CLASS);
+		return () => document.body.classList.remove(APP_CLASS);
 	}, []);
 	return <Meta {...metadata}>{children}</Meta>;
 }

package/ui/block/Video.js

@@ -22,7 +22,7 @@ export function VideoButton({ children, title, onClick, disabled, ...variants })
 }
 /** Button to make a video element go fullscreen. */
 export function FullscreenVideoButton() {
-    const [isFull, setFull] = useState(!!document.fullscreenElement);
+    const [isFull, setFull] = useState(() => typeof document !== "undefined" && !!document.fullscreenElement);
     useEffect(() => {
         const onChange = () => setFull(!!document.fullscreenElement);
         document.addEventListener("fullscreenchange", onChange);

package/ui/block/Video.tsx

@@ -63,7 +63,7 @@ export interface FullscreenVideoButtonProps {
 
 /** Button to make a video element go fullscreen. */
 export function FullscreenVideoButton(): ReactElement | null {
-	const [isFull, setFull] = useState(!!document.fullscreenElement);
+	const [isFull, setFull] = useState(() => typeof document !== "undefined" && !!document.fullscreenElement);
 
 	useEffect(() => {
 		const onChange = () => setFull(!!document.fullscreenElement);

package/ui/layout/SidebarLayout.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement, ReactNode } from "react";
+import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
+export interface SidebarLayoutProps {
+    /** Content rendered in the fixed-width side column. */
+    sidebar: ReactNode;
+    /** Main content rendered in the scrollable content column. */
+    children?: ReactNode;
+    /** Render the sidebar on the right rather than the left. */
+    right?: boolean | undefined;
+}
+/**
+ * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
+ * - The sidebar collapses above the main content on narrow viewports.
+ * - Use the `--sidebar-layout-width` and `--sidebar-layout-bg` custom properties to override defaults.
+ */
+export declare function SidebarLayout({ sidebar, children, right }: SidebarLayoutProps): ReactElement;
+export { SIDEBAR_LAYOUT_CSS };

package/ui/layout/SidebarLayout.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getClass } from "../util/css.js";
+import { LAYOUT_CSS } from "./Layout.js";
+import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
+/**
+ * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
+ * - The sidebar collapses above the main content on narrow viewports.
+ * - Use the `--sidebar-layout-width` and `--sidebar-layout-bg` custom properties to override defaults.
+ */
+export function SidebarLayout({ sidebar, children, right = false }) {
+    const sidebarEl = (_jsx("aside", { className: SIDEBAR_LAYOUT_CSS.sidebar, children: sidebar }, "sidebar"));
+    const contentEl = (_jsx("div", { className: SIDEBAR_LAYOUT_CSS.content, children: _jsx("div", { className: SIDEBAR_LAYOUT_CSS.contentInner, children: children }) }, "content"));
+    return (_jsx("main", { className: getClass(SIDEBAR_LAYOUT_CSS.main, LAYOUT_CSS.layout), children: right ? [contentEl, sidebarEl] : [sidebarEl, contentEl] }));
+}
+export { SIDEBAR_LAYOUT_CSS };

package/ui/layout/SidebarLayout.module.css

@@ -0,0 +1,47 @@
+/*
+ * Sidebar layout: a fixed-width column on the left, scrollable main content on the right.
+ *
+ * The outer `.layout` class (from Layout.module.css) owns the overall page scroll,
+ * but here we override that: the sidebar and the main column each scroll independently.
+ */
+
+.main {
+	display: grid;
+	grid-template-columns: var(--sidebar-layout-width, 17.5rem) 1fr;
+	gap: 0;
+	padding: 0;
+	overflow: hidden;
+}
+
+.sidebar {
+	overflow-y: auto;
+	overscroll-behavior: contain;
+	padding: var(--spacing-block);
+	background: var(--sidebar-layout-bg, var(--color-surface));
+	border-right: 1px solid var(--color-border);
+}
+
+.content {
+	overflow-y: auto;
+	overscroll-behavior: contain;
+	padding: var(--spacing-block) var(--spacing-spacious);
+	min-width: 0;
+}
+
+.contentInner {
+	width: 100%;
+	max-width: var(--width-wide);
+	margin: 0 auto;
+}
+
+/* On narrow viewports collapse to a single column with the sidebar above. */
+@media (max-width: 48rem) {
+	.main {
+		grid-template-columns: 1fr;
+	}
+	.sidebar {
+		border-right: none;
+		border-bottom: 1px solid var(--color-border);
+		max-height: 50vh;
+	}
+}

package/ui/layout/SidebarLayout.tsx

@@ -0,0 +1,36 @@
+import type { ReactElement, ReactNode } from "react";
+import { getClass } from "../util/css.js";
+import { LAYOUT_CSS } from "./Layout.js";
+import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
+
+export interface SidebarLayoutProps {
+	/** Content rendered in the fixed-width side column. */
+	sidebar: ReactNode;
+	/** Main content rendered in the scrollable content column. */
+	children?: ReactNode;
+	/** Render the sidebar on the right rather than the left. */
+	right?: boolean | undefined;
+}
+
+/**
+ * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
+ * - The sidebar collapses above the main content on narrow viewports.
+ * - Use the `--sidebar-layout-width` and `--sidebar-layout-bg` custom properties to override defaults.
+ */
+export function SidebarLayout({ sidebar, children, right = false }: SidebarLayoutProps): ReactElement {
+	const sidebarEl = (
+		<aside key="sidebar" className={SIDEBAR_LAYOUT_CSS.sidebar}>
+			{sidebar}
+		</aside>
+	);
+	const contentEl = (
+		<div key="content" className={SIDEBAR_LAYOUT_CSS.content}>
+			<div className={SIDEBAR_LAYOUT_CSS.contentInner}>{children}</div>
+		</div>
+	);
+	return (
+		<main className={getClass(SIDEBAR_LAYOUT_CSS.main, LAYOUT_CSS.layout)}>{right ? [contentEl, sidebarEl] : [sidebarEl, contentEl]}</main>
+	);
+}
+
+export { SIDEBAR_LAYOUT_CSS };

package/ui/layout/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./CenteredLayout.js";
 export * from "./Layout.js";
+export * from "./SidebarLayout.js";

package/ui/layout/index.js

@@ -1,2 +1,3 @@
 export * from "./CenteredLayout.js";
 export * from "./Layout.js";
+export * from "./SidebarLayout.js";

package/ui/layout/index.tsx

@@ -1,2 +1,3 @@
 export * from "./CenteredLayout.js";
 export * from "./Layout.js";
+export * from "./SidebarLayout.js";

package/ui/misc/Meta.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
-import { type MetaData, type PossibleMetaData } from "../util/meta.js";
-export interface MetaProps extends PossibleMetaData {
+import { type MetaData, type PossibleMeta } from "../util/meta.js";
+export interface MetaProps extends PossibleMeta {
     children: ReactNode;
 }
 /** Create or update the current meta context. */

package/ui/misc/Meta.tsx

@@ -1,11 +1,11 @@
 import { createContext, type ReactNode, use } from "react";
-import { type MetaData, mergeMeta, type PossibleMetaData } from "../util/meta.js";
+import { type MetaData, mergeMeta, type PossibleMeta } from "../util/meta.js";
 
 /** Context to store the `Config` object. */
 const _MetaContext = createContext<MetaData>({});
 _MetaContext.displayName = "MetaContext";
 
-export interface MetaProps extends PossibleMetaData {
+export interface MetaProps extends PossibleMeta {
 	children: ReactNode;
 }
 

package/ui/page/HTML.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement, ReactNode } from "react";
+export interface HTMLProps {
+    children: ReactNode;
+}
+/**
+ * Output a `<html>` element wrapping `<body id="root">`.
+ * - No `<head>` element is rendered. Head tags (`<title>`, `<meta>`, `<link>`, `<script>`) are emitted inline by `<Page>` / `<Head>` lower in the tree, and React 19 hoists them automatically — to the document `<head>` on the client, and to a generated `<head>` element during `renderToString` SSR.
+ * - This means the same component tree works for both modes without any shell-aware logic.
+ */
+export declare function HTML({ children }: HTMLProps): ReactElement;

package/ui/page/HTML.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { requireMeta } from "../misc/Meta.js";
+/**
+ * Output a `<html>` element wrapping `<body id="root">`.
+ * - No `<head>` element is rendered. Head tags (`<title>`, `<meta>`, `<link>`, `<script>`) are emitted inline by `<Page>` / `<Head>` lower in the tree, and React 19 hoists them automatically — to the document `<head>` on the client, and to a generated `<head>` element during `renderToString` SSR.
+ * - This means the same component tree works for both modes without any shell-aware logic.
+ */
+export function HTML({ children }) {
+    const { language } = requireMeta();
+    return (_jsx("html", { lang: language, children: _jsx("body", { id: "root", children: children }) }));
+}

package/ui/page/HTML.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement, ReactNode } from "react";
+import { requireMeta } from "../misc/Meta.js";
+
+export interface HTMLProps {
+	children: ReactNode;
+}
+
+/**
+ * Output a `<html>` element wrapping `<body id="root">`.
+ * - No `<head>` element is rendered. Head tags (`<title>`, `<meta>`, `<link>`, `<script>`) are emitted inline by `<Page>` / `<Head>` lower in the tree, and React 19 hoists them automatically — to the document `<head>` on the client, and to a generated `<head>` element during `renderToString` SSR.
+ * - This means the same component tree works for both modes without any shell-aware logic.
+ */
+export function HTML({ children }: HTMLProps): ReactElement {
+	const { language } = requireMeta();
+	return (
+		<html lang={language}>
+			<body id="root">{children}</body>
+		</html>
+	);
+}

package/ui/page/Head.d.ts

@@ -1,8 +1,3 @@
 import { type ReactElement } from "react";
-declare const _componentProps: unique symbol;
-export interface HeadProps {
-    readonly [_componentProps]?: never;
-}
 /** Use the details from the current page data context to set the document `<title>`, meta tags, and history state. */
 export declare function Head(): ReactElement;
-export {};