shelving 1.201.0 → 1.202.0

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.201.0",
+	"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 {};

package/ui/page/Head.js

@@ -1,4 +1,4 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect } from "react";
 import { notNullish } from "../../util/null.js";
 import { getProps } from "../../util/object.js";
@@ -11,10 +11,12 @@ const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
 export function Head() {
     const { url, title, base, app, links, tags } = requireMeta();
     useEffect(() => {
+        if (typeof window === "undefined")
+            return;
         if (url)
             window.history.replaceState(null, "", url);
     }, [url]);
-    return (_jsxs(_Fragment, { children: [_jsx("title", { children: joinTitles(title, app) }), base && _jsx("base", { href: base.href }), tags &&
+    return (_jsxs("head", { children: [_jsx("title", { children: joinTitles(title, app) }), base && _jsx("base", { href: base.href }), tags &&
                 getProps(tags)
                     .map(([k, x]) => {
                     if (notNullish(x)) {

package/ui/page/Head.tsx

@@ -8,22 +8,17 @@ import { joinTitles } from "../util/meta.js";
 /** Meta tags with a capital first letter and hyphens, e.g. `Content-Security-Policy` or `Accept`, are `http-equiv=""` tags. */
 const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
 
-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 function Head(): ReactElement {
 	const { url, title, base, app, links, tags } = requireMeta();
 
 	useEffect(() => {
+		if (typeof window === "undefined") return;
 		if (url) window.history.replaceState(null, "", url);
 	}, [url]);
 
 	return (
-		<>
+		<head>
 			<title>{joinTitles(title, app)}</title>
 			{base && <base href={base.href} />}
 			{tags &&
@@ -44,6 +39,6 @@ export function Head(): ReactElement {
 						<link key={k} rel={k} href={v} type={v.endsWith(".png") ? "image/png" : v.endsWith(".ico") ? "image/x-icon" : undefined} />
 					) : null,
 				)}
-		</>
+		</head>
 	);
 }

package/ui/page/Page.d.ts

@@ -1,10 +1,11 @@
 import type { ReactElement, ReactNode } from "react";
-import type { PossibleMetaData } from "../util/meta.js";
-export interface PageProps extends PossibleMetaData {
+import type { PossibleMeta } from "../util/meta.js";
+export interface PageProps extends PossibleMeta {
     children: ReactNode;
 }
 /**
  * Component for a single page (or screen) within an app.
- * - Changes the document title (that appears in the page tab) on render.
+ * - Sets the document title and other head metadata.
+ * - `<Head />` renders `<title>` / `<meta>` / `<link>` tags inline; React 19 hoists them automatically to the document `<head>` (or to `document.head` on the client). Works for both client-mounted SPAs and `renderToString` SSR.
  */
 export declare function Page({ children, ...metadata }: PageProps): ReactElement;

package/ui/page/Page.js

@@ -3,7 +3,8 @@ import { Meta } from "../misc/Meta.js";
 import { Head } from "./Head.js";
 /**
  * Component for a single page (or screen) within an app.
- * - Changes the document title (that appears in the page tab) on render.
+ * - Sets the document title and other head metadata.
+ * - `<Head />` renders `<title>` / `<meta>` / `<link>` tags inline; React 19 hoists them automatically to the document `<head>` (or to `document.head` on the client). Works for both client-mounted SPAs and `renderToString` SSR.
  */
 export function Page({ children, ...metadata }) {
     return (_jsxs(Meta, { ...metadata, children: [_jsx(Head, {}), children] }));

package/ui/page/Page.tsx

@@ -1,15 +1,16 @@
 import type { ReactElement, ReactNode } from "react";
 import { Meta } from "../misc/Meta.js";
-import type { PossibleMetaData } from "../util/meta.js";
+import type { PossibleMeta } from "../util/meta.js";
 import { Head } from "./Head.js";
 
-export interface PageProps extends PossibleMetaData {
+export interface PageProps extends PossibleMeta {
 	children: ReactNode;
 }
 
 /**
  * Component for a single page (or screen) within an app.
- * - Changes the document title (that appears in the page tab) on render.
+ * - Sets the document title and other head metadata.
+ * - `<Head />` renders `<title>` / `<meta>` / `<link>` tags inline; React 19 hoists them automatically to the document `<head>` (or to `document.head` on the client). Works for both client-mounted SPAs and `renderToString` SSR.
  */
 export function Page({ children, ...metadata }: PageProps): ReactElement {
 	return (

package/ui/page/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./Head.js";
+export * from "./HTML.js";
 export * from "./Page.js";

package/ui/page/index.js

@@ -1,2 +1,3 @@
 export * from "./Head.js";
+export * from "./HTML.js";
 export * from "./Page.js";

package/ui/page/index.ts

@@ -1,2 +1,3 @@
 export * from "./Head.js";
+export * from "./HTML.js";
 export * from "./Page.js";

package/ui/router/Router.d.ts

@@ -1,26 +1,29 @@
 import { type ReactElement, type ReactNode } from "react";
 import type { Routes } from "./Routes.js";
 export interface RouterProps {
-    routes: Routes;
-    children?: ReactNode;
-}
-export interface RouterIsolateProps {
-    children: ReactNode;
-}
-declare const _routerOutputProps: unique symbol;
-export interface RouterOutputProps {
-    readonly [_routerOutputProps]?: never;
+    readonly routes: Routes;
+    readonly children?: ReactNode | undefined;
 }
 /**
  * Provides Router based on the browser URL and renders the active route.
+ * - Creates a new `RouterStore`
+ * - Exposes it via `requireRouter()` to descendants.
+ * - Renders the route matched for the current path.
+ * - Intercepts same-origin anchor clicks (excluding anchors with a `download` attribute) to perform client-side routing.
+ * - Synchronizes store state with browser back/forward (`popstate`) events.
  *
- * Creates a RouterStore, exposes it via context to descendants, renders the route matched for the current path, intercepts same-origin anchor clicks (excluding anchors with a `download` attribute) to perform client-side Router, and synchronizes store state with browser back/forward (`popstate`) events.
+ * Integrated with meta via the current `Meta`
+ * - Set `url` in a wrapper component to set the initial URL for this router, e.g. `<App url="/a/b/c">`
+ * - Set `base` , e.g. `<App base="https://p.com/subdir" />`
  *
  * @param routes - Route definitions used to select and render the active route
  * @param children - Content to render inside the Router Meta; defaults to the routing output component
  * @returns The Router provider element rendering the active route and supplying Router context
  */
 export declare function Router({ routes, children }: RouterProps): ReactElement;
+export interface RouterIsolateProps {
+    children: ReactNode;
+}
 /**
  * Isolate a set of children so they remount on Router.
  * - Use this when you want to ensure an entire React tree is remounted when the Router route changes.
@@ -28,4 +31,3 @@ export declare function Router({ routes, children }: RouterProps): ReactElement;
 export declare function RouterIsolate({ children }: RouterIsolateProps): ReactElement;
 /** Show the content active for the current router route. */
 export declare function RouterOutput(): ReactElement | null;
-export {};

package/ui/router/Router.js

@@ -3,23 +3,33 @@ import { Fragment, useEffect } from "react";
 import { useInstance } from "../../react/useInstance.js";
 import { useStore } from "../../react/useStore.js";
 import { getURIParams } from "../../util/uri.js";
-import { Meta } from "../misc/Meta.js";
+import { Meta, requireMeta } from "../misc/Meta.js";
 import { RouterContext, requireRouter } from "./RouterContext.js";
 import { RouterStore } from "./RouterStore.js";
 /**
  * Provides Router based on the browser URL and renders the active route.
+ * - Creates a new `RouterStore`
+ * - Exposes it via `requireRouter()` to descendants.
+ * - Renders the route matched for the current path.
+ * - Intercepts same-origin anchor clicks (excluding anchors with a `download` attribute) to perform client-side routing.
+ * - Synchronizes store state with browser back/forward (`popstate`) events.
  *
- * Creates a RouterStore, exposes it via context to descendants, renders the route matched for the current path, intercepts same-origin anchor clicks (excluding anchors with a `download` attribute) to perform client-side Router, and synchronizes store state with browser back/forward (`popstate`) events.
+ * Integrated with meta via the current `Meta`
+ * - Set `url` in a wrapper component to set the initial URL for this router, e.g. `<App url="/a/b/c">`
+ * - Set `base` , e.g. `<App base="https://p.com/subdir" />`
  *
  * @param routes - Route definitions used to select and render the active route
  * @param children - Content to render inside the Router Meta; defaults to the routing output component
  * @returns The Router provider element rendering the active route and supplying Router context
  */
 export function Router({ routes, children = _jsx(RouterOutput, {}) }) {
-    const nav = useInstance(RouterStore, routes);
+    const { url, base } = requireMeta();
+    const nav = useInstance(RouterStore, routes, url, base);
     useStore(nav);
     // Effect to attach listeners when this router is active.
     useEffect(() => {
+        if (typeof document === "undefined" || typeof window === "undefined")
+            return;
         // Listen for `click` events on `<a href="">` anchors and fire the forward event instead.
         const onClick = (e) => {
             // Look for clicks on `<a href="">` elements or `.targeted` elements containing `<a href="" class="target">`

package/ui/router/Router.tsx

@@ -2,40 +2,41 @@ import { Fragment, type ReactElement, type ReactNode, useEffect } from "react";
 import { useInstance } from "../../react/useInstance.js";
 import { useStore } from "../../react/useStore.js";
 import { getURIParams } from "../../util/uri.js";
-import { Meta } from "../misc/Meta.js";
+import { Meta, requireMeta } from "../misc/Meta.js";
 import { RouterContext, requireRouter } from "./RouterContext.js";
 import { RouterStore } from "./RouterStore.js";
 import type { Routes } from "./Routes.js";
 
 export interface RouterProps {
-	routes: Routes;
-	children?: ReactNode;
+	readonly routes: Routes;
+	readonly children?: ReactNode | undefined;
 }
 
-export interface RouterIsolateProps {
-	children: ReactNode;
-}
-
-declare const _routerOutputProps: unique symbol;
-
-export interface RouterOutputProps {
-	readonly [_routerOutputProps]?: never;
-}
 /**
  * Provides Router based on the browser URL and renders the active route.
+ * - Creates a new `RouterStore`
+ * - Exposes it via `requireRouter()` to descendants.
+ * - Renders the route matched for the current path.
+ * - Intercepts same-origin anchor clicks (excluding anchors with a `download` attribute) to perform client-side routing.
+ * - Synchronizes store state with browser back/forward (`popstate`) events.
  *
- * Creates a RouterStore, exposes it via context to descendants, renders the route matched for the current path, intercepts same-origin anchor clicks (excluding anchors with a `download` attribute) to perform client-side Router, and synchronizes store state with browser back/forward (`popstate`) events.
+ * Integrated with meta via the current `Meta`
+ * - Set `url` in a wrapper component to set the initial URL for this router, e.g. `<App url="/a/b/c">`
+ * - Set `base` , e.g. `<App base="https://p.com/subdir" />`
  *
  * @param routes - Route definitions used to select and render the active route
  * @param children - Content to render inside the Router Meta; defaults to the routing output component
  * @returns The Router provider element rendering the active route and supplying Router context
  */
 export function Router({ routes, children = <RouterOutput /> }: RouterProps): ReactElement {
-	const nav = useInstance(RouterStore, routes);
+	const { url, base } = requireMeta();
+	const nav = useInstance(RouterStore, routes, url, base);
 	useStore(nav);
 
 	// Effect to attach listeners when this router is active.
 	useEffect(() => {
+		if (typeof document === "undefined" || typeof window === "undefined") return;
+
 		// Listen for `click` events on `<a href="">` anchors and fire the forward event instead.
 		const onClick = (e: MouseEvent) => {
 			// Look for clicks on `<a href="">` elements or `.targeted` elements containing `<a href="" class="target">`
@@ -71,6 +72,10 @@ export function Router({ routes, children = <RouterOutput /> }: RouterProps): Re
 	);
 }
 
+export interface RouterIsolateProps {
+	children: ReactNode;
+}
+
 /**
  * Isolate a set of children so they remount on Router.
  * - Use this when you want to ensure an entire React tree is remounted when the Router route changes.

package/ui/router/RouterStore.d.ts

@@ -5,7 +5,7 @@ import { type Routes } from "./Routes.js";
 /** Store the current router state. */
 export declare class RouterStore extends URLStore {
     readonly routes: Routes;
-    constructor(routes: Routes);
+    constructor(routes: Routes, url?: PossibleURL, base?: PossibleURL);
     forward(possible: PossibleURL): void;
     redirect(possible: PossibleURL): void;
     /** Match a route against this router's routes and return the matched component. */

package/ui/router/RouterStore.js

@@ -4,8 +4,8 @@ import { matchRoute } from "./Routes.js";
 /** Store the current router state. */
 export class RouterStore extends URLStore {
     routes;
-    constructor(routes) {
-        super(requireURL(window.location.href));
+    constructor(routes, url = "/", base) {
+        super(url, base);
         this.routes = routes;
     }
     forward(possible) {

package/ui/router/RouterStore.tsx

@@ -7,8 +7,8 @@ import { matchRoute, type Routes } from "./Routes.js";
 export class RouterStore extends URLStore {
 	readonly routes: Routes;
 
-	constructor(routes: Routes) {
-		super(requireURL(window.location.href));
+	constructor(routes: Routes, url: PossibleURL = "/", base?: PossibleURL) {
+		super(url, base);
 		this.routes = routes;
 	}
 

package/ui/util/meta.d.ts

@@ -14,11 +14,11 @@ export type MetaAssets = ImmutableArray<Nullish<string>>;
 export type MetaCSP = {
     readonly [resource: string]: string[];
 };
-/** Combined meta information for a website page. */
+/** Combined meta data for a website page. */
 export interface MetaData {
     /** Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). */
     readonly base?: ImmutableURL | undefined;
-    /** URL of the current page (used to update history API  */
+    /** URL of the current page (used to update history API and as the initial URL for routing). */
     readonly url?: ImmutableURL | undefined;
     /** Title of the entire application. */
     readonly app?: string | undefined;
@@ -27,7 +27,7 @@ export interface MetaData {
     /** Description of the current page. */
     readonly description?: string | undefined;
     readonly image?: string | undefined;
-    /** Language code (used for  */
+    /** Language code (used for `lang` tag in HTML). */
     readonly language?: string | undefined;
     readonly csp?: MetaCSP | undefined;
     readonly tags?: MetaTags | undefined;
@@ -37,7 +37,7 @@ export interface MetaData {
     readonly styles?: MetaAssets | undefined;
 }
 /** Input metadata that can be parsed and converted to proper metadata. */
-export interface PossibleMetaData extends Omit<MetaData, "url"> {
+export interface PossibleMeta extends Omit<MetaData, "url"> {
     /**
      * New URL for the page.
      * - Resolved using `requireURL()` if set relative to `base`
@@ -51,17 +51,17 @@ export interface PossibleMetaData extends Omit<MetaData, "url"> {
     readonly params?: PossibleURIParams | undefined;
 }
 /** Turn a deconstructed CSP into a string. */
-export declare function joinCSP(csp: Nullish<MetaCSP>): string | undefined;
+export declare function joinMetaCSP(csp: Nullish<MetaCSP>): string | undefined;
 /** Merge two page or site titles together, e.g. `Manchester Runners` + `Messages` becomes `Messages - Manchester Runners` */
 export declare function joinTitles(...titles: (string | undefined)[]): string;
 /**
- * Merge two metadata objects.
+ * Merge two `MetaData` objects.
  * - `title` is merged.
  * - `URL` is resolved to an absolute URL, e.g. `./d/e/f` + `/a/b/c` becomes `https://d.com/a/b/c/d/e/f`
  */
-export declare function mergeMeta(meta1: MetaData, meta2: PossibleMetaData, caller?: AnyCaller): MetaData;
+export declare function mergeMeta(meta1: MetaData, meta2: PossibleMeta, caller?: AnyCaller): MetaData;
 /**
  * Merge two metadata URLs.
  * - New URL is resolved relative to: current URL, new base URL, current base URL
  */
-export declare function mergeURL(base: ImmutableURL | undefined, current: ImmutableURL | undefined, next: PossibleURL | undefined, params: PossibleURIParams | undefined, caller?: AnyCaller): ImmutableURL | undefined;
+export declare function mergeMetaURL(base: ImmutableURL | undefined, current: ImmutableURL | undefined, next: PossibleURL | undefined, params: PossibleURIParams | undefined, caller?: AnyCaller): ImmutableURL | undefined;

package/ui/util/meta.js

@@ -1,7 +1,7 @@
 import { withURIParams } from "../../util/uri.js";
 import { requireURL } from "../../util/url.js";
 /** Turn a deconstructed CSP into a string. */
-export function joinCSP(csp) {
+export function joinMetaCSP(csp) {
     if (typeof csp === "string")
         return csp;
     if (csp !== null && csp !== undefined)
@@ -13,21 +13,21 @@ export function joinTitles(...titles) {
     return titles.filter(Boolean).join(" - ");
 }
 /**
- * Merge two metadata objects.
+ * Merge two `MetaData` objects.
  * - `title` is merged.
  * - `URL` is resolved to an absolute URL, e.g. `./d/e/f` + `/a/b/c` becomes `https://d.com/a/b/c/d/e/f`
  */
 export function mergeMeta(meta1, meta2, caller = mergeMeta) {
     const title = joinTitles(meta2.title, meta1.title);
-    const base = mergeURL(undefined, meta1.base, meta2.base, undefined, caller);
-    const url = mergeURL(base, meta1.url, meta2.url, meta2.params, caller);
+    const base = mergeMetaURL(undefined, meta1.base, meta2.base, undefined, caller);
+    const url = mergeMetaURL(base, meta1.url, meta2.url, meta2.params, caller);
     return { ...meta1, ...meta2, base, url, title };
 }
 /**
  * Merge two metadata URLs.
  * - New URL is resolved relative to: current URL, new base URL, current base URL
  */
-export function mergeURL(base, current, next, params, caller = mergeURL) {
+export function mergeMetaURL(base, current, next, params, caller = mergeMetaURL) {
     const url = next ? requireURL(next, base, caller) : current;
     return url && params ? withURIParams(url, params, caller) : url;
 }

package/ui/util/meta.ts

@@ -17,11 +17,11 @@ export type MetaAssets = ImmutableArray<Nullish<string>>;
 /** Type for a meta `Content-Security-Policy` tag in `{ resource: string[] }` format. */
 export type MetaCSP = { readonly [resource: string]: string[] };
 
-/** Combined meta information for a website page. */
+/** Combined meta data for a website page. */
 export interface MetaData {
 	/** Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). */
 	readonly base?: ImmutableURL | undefined;
-	/** URL of the current page (used to update history API  */
+	/** URL of the current page (used to update history API and as the initial URL for routing). */
 	readonly url?: ImmutableURL | undefined;
 	/** Title of the entire application. */
 	readonly app?: string | undefined;
@@ -30,7 +30,7 @@ export interface MetaData {
 	/** Description of the current page. */
 	readonly description?: string | undefined;
 	readonly image?: string | undefined;
-	/** Language code (used for  */
+	/** Language code (used for `lang` tag in HTML). */
 	readonly language?: string | undefined;
 	readonly csp?: MetaCSP | undefined;
 	readonly tags?: MetaTags | undefined;
@@ -41,7 +41,7 @@ export interface MetaData {
 }
 
 /** Input metadata that can be parsed and converted to proper metadata. */
-export interface PossibleMetaData extends Omit<MetaData, "url"> {
+export interface PossibleMeta extends Omit<MetaData, "url"> {
 	/**
 	 * New URL for the page.
 	 * - Resolved using `requireURL()` if set relative to `base`
@@ -56,7 +56,7 @@ export interface PossibleMetaData extends Omit<MetaData, "url"> {
 }
 
 /** Turn a deconstructed CSP into a string. */
-export function joinCSP(csp: Nullish<MetaCSP>): string | undefined {
+export function joinMetaCSP(csp: Nullish<MetaCSP>): string | undefined {
 	if (typeof csp === "string") return csp;
 	if (csp !== null && csp !== undefined) return Object.entries(csp).map(_mapCSP).join("; ");
 }
@@ -68,15 +68,15 @@ export function joinTitles(...titles: (string | undefined)[]): string {
 }
 
 /**
- * Merge two metadata objects.
+ * Merge two `MetaData` objects.
  * - `title` is merged.
  * - `URL` is resolved to an absolute URL, e.g. `./d/e/f` + `/a/b/c` becomes `https://d.com/a/b/c/d/e/f`
  */
-export function mergeMeta(meta1: MetaData, meta2: PossibleMetaData, caller: AnyCaller = mergeMeta): MetaData {
+export function mergeMeta(meta1: MetaData, meta2: PossibleMeta, caller: AnyCaller = mergeMeta): MetaData {
 	const title = joinTitles(meta2.title, meta1.title);
 
-	const base = mergeURL(undefined, meta1.base, meta2.base, undefined, caller);
-	const url = mergeURL(base, meta1.url, meta2.url, meta2.params, caller);
+	const base = mergeMetaURL(undefined, meta1.base, meta2.base, undefined, caller);
+	const url = mergeMetaURL(base, meta1.url, meta2.url, meta2.params, caller);
 
 	return { ...meta1, ...meta2, base, url, title };
 }
@@ -85,12 +85,12 @@ export function mergeMeta(meta1: MetaData, meta2: PossibleMetaData, caller: AnyC
  * Merge two metadata URLs.
  * - New URL is resolved relative to: current URL, new base URL, current base URL
  */
-export function mergeURL(
+export function mergeMetaURL(
 	base: ImmutableURL | undefined,
 	current: ImmutableURL | undefined,
 	next: PossibleURL | undefined,
 	params: PossibleURIParams | undefined,
-	caller: AnyCaller = mergeURL,
+	caller: AnyCaller = mergeMetaURL,
 ): ImmutableURL | undefined {
 	const url = next ? requireURL(next, base, caller) : current;
 	return url && params ? withURIParams(url, params, caller) : url;

package/util/element.d.ts

@@ -0,0 +1,32 @@
+/** Set of valid props for an element. */
+export interface ElementProps {
+    readonly [key: string]: unknown;
+    readonly children?: Elements;
+}
+/** Element with a type, props, and optional key (compatible with `React.ReactElement`). */
+export interface Element<P extends ElementProps = ElementProps> {
+    readonly type: string | ((props: P) => Elements | null);
+    readonly props: P;
+    readonly key: string | null;
+    readonly $$typeof?: symbol;
+}
+/** Collection of elements (compatible with `React.ReactNode`). */
+export type Elements = undefined | null | string | Element | readonly Elements[];
+/** Is an unknown value an element? */
+export declare function isElement(value: unknown): value is Element;
+/** Is an unknown value a collection of elements? */
+export declare function isElements(value: unknown): value is Elements;
+/**
+ * Strip all tags from elements to produce a plain text string.
+ *
+ * @param elements An element, a plain string, or null/undefined (or an array of those things).
+ * @returns The combined string made from the elements.
+ *
+ * @example `- Item with *strong*\n- Item with _em_` becomes `Item with strong Item with em`
+ */
+export declare function getElementText(elements?: Elements): string;
+/**
+ * Iterate through all elements in a collection.
+ * - This is useful if you, e.g. want to apply a `className` to all `<h1>` elements, or make a list of all URLs found in a collection.
+ */
+export declare function getElements(elements: Elements): Iterable<Element>;

package/util/element.js

@@ -0,0 +1,41 @@
+import { isArray } from "./array.js";
+/** Is an unknown value an element? */
+export function isElement(value) {
+    return typeof value === "object" && value !== null && "type" in value;
+}
+/** Is an unknown value a collection of elements? */
+export function isElements(value) {
+    return value === null || typeof value === "string" || isElement(value) || isArray(value);
+}
+/**
+ * Strip all tags from elements to produce a plain text string.
+ *
+ * @param elements An element, a plain string, or null/undefined (or an array of those things).
+ * @returns The combined string made from the elements.
+ *
+ * @example `- Item with *strong*\n- Item with _em_` becomes `Item with strong Item with em`
+ */
+export function getElementText(elements) {
+    if (typeof elements === "string")
+        return elements;
+    if (isArray(elements))
+        return elements.map(getElementText).filter(Boolean).join(" ");
+    if (isElement(elements))
+        return getElementText(elements.props.children);
+    return "";
+}
+/**
+ * Iterate through all elements in a collection.
+ * - This is useful if you, e.g. want to apply a `className` to all `<h1>` elements, or make a list of all URLs found in a collection.
+ */
+export function* getElements(elements) {
+    if (isArray(elements)) {
+        for (const n of elements)
+            yield* getElements(n);
+    }
+    else if (isElement(elements)) {
+        yield elements;
+        if (elements.props.children)
+            yield* getElements(elements.props.children);
+    }
+}

package/util/index.d.ts

@@ -17,6 +17,7 @@ export * from "./dictionary.js";
 export * from "./diff.js";
 export * from "./dispose.js";
 export * from "./duration.js";
+export * from "./element.js";
 export * from "./entity.js";
 export * from "./entry.js";
 export * from "./env.js";
@@ -33,7 +34,6 @@ export * from "./http.js";
 export * from "./hydrate.js";
 export * from "./item.js";
 export * from "./iterate.js";
-export * from "./jsx.js";
 export * from "./jwt.js";
 export * from "./lazy.js";
 export * from "./map.js";

package/util/index.js

@@ -17,6 +17,7 @@ export * from "./dictionary.js";
 export * from "./diff.js";
 export * from "./dispose.js";
 export * from "./duration.js";
+export * from "./element.js";
 export * from "./entity.js";
 export * from "./entry.js";
 export * from "./env.js";
@@ -33,7 +34,6 @@ export * from "./http.js";
 export * from "./hydrate.js";
 export * from "./item.js";
 export * from "./iterate.js";
-export * from "./jsx.js";
 export * from "./jwt.js";
 export * from "./lazy.js";
 export * from "./map.js";

package/util/jsx.d.ts

@@ -1,32 +0,0 @@
-/** Set of valid props for a JSX element. */
-export interface JSXProps {
-    readonly [key: string]: unknown;
-    readonly children?: JSXNode;
-}
-/** JSX element (similar to `React.ReactElement`)  */
-export interface JSXElement<P extends JSXProps = JSXProps> {
-    readonly type: string | ((props: P) => JSXNode | null);
-    readonly props: P;
-    readonly key: string | null;
-    readonly $$typeof?: symbol;
-}
-/** JSX node (similar to `React.ReactNode`) */
-export type JSXNode = undefined | null | string | JSXElement | readonly JSXNode[];
-/** Is an unknown value a JSX element? */
-export declare function isJSXElement(value: unknown): value is JSXElement;
-/** Is an unknown value a JSX node? */
-export declare function isJSXNode(value: unknown): value is JSXNode;
-/**
- * Take a Markup JSX node and strip all tags from it to produce a plain text string.
- *
- * @param node A JsxNode, e.g. either a JSX element, a plain string, or null/undefined (or an array of those things).
- * @returns The combined string made from the JSX node.
- *
- * @example `- Item with *strong*\n- Item with _em_` becomes `Item with strong Item with em`
- */
-export declare function getJSXNodeText(node?: JSXNode): string;
-/**
- * Iterate through all elements in a node.
- * - This is useful if you, e.g. want to apply a `className` to all `<h1>` elements, or make a list of all URLs found in a Node.
- */
-export declare function getJSXNodeElements(node: JSXNode): Iterable<JSXElement>;

package/util/jsx.js

@@ -1,41 +0,0 @@
-import { isArray } from "./array.js";
-/** Is an unknown value a JSX element? */
-export function isJSXElement(value) {
-    return typeof value === "object" && value !== null && "type" in value;
-}
-/** Is an unknown value a JSX node? */
-export function isJSXNode(value) {
-    return value === null || typeof value === "string" || isJSXElement(value) || isArray(value);
-}
-/**
- * Take a Markup JSX node and strip all tags from it to produce a plain text string.
- *
- * @param node A JsxNode, e.g. either a JSX element, a plain string, or null/undefined (or an array of those things).
- * @returns The combined string made from the JSX node.
- *
- * @example `- Item with *strong*\n- Item with _em_` becomes `Item with strong Item with em`
- */
-export function getJSXNodeText(node) {
-    if (typeof node === "string")
-        return node;
-    if (isArray(node))
-        return node.map(getJSXNodeText).filter(Boolean).join(" ");
-    if (isJSXElement(node))
-        return getJSXNodeText(node.props.children);
-    return "";
-}
-/**
- * Iterate through all elements in a node.
- * - This is useful if you, e.g. want to apply a `className` to all `<h1>` elements, or make a list of all URLs found in a Node.
- */
-export function* getJSXNodeElements(node) {
-    if (isArray(node)) {
-        for (const n of node)
-            yield* getJSXNodeElements(n);
-    }
-    else if (isJSXElement(node)) {
-        yield node;
-        if (node.props.children)
-            yield* getJSXNodeElements(node.props.children);
-    }
-}