shelving 1.215.1 → 1.216.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.215.1",
+	"version": "1.216.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/README.md

@@ -21,7 +21,7 @@ A few conventions run through every component (see also the React Components sec
 
 | Folder | What's inside |
 |---|---|
-| [block](/ui/block) | Block-level content — `Card`, `Section`, `Heading`, `Table`, `List`, `Prose`, `Figure`, `Flex` |
+| [block](/ui/block) | Block-level content — `Card`, `Section`, `Title`, `Heading`, `Table`, `List`, `Prose`, `Figure`, `Flex` |
 | [inline](/ui/inline) | Inline content — `Code`, `Strong`, `Emphasis`, `Link`, `Mark`, `Small` |
 | [misc](/ui/misc) | Cross-cutting pieces — `Markup`, `Tag`, `Status`, `Loading`, `Color`, `Catcher`, `Mapper` |
 
@@ -57,14 +57,14 @@ A few conventions run through every component (see also the React Components sec
 A minimal single-screen app:
 
 ```tsx
-import { App, CenteredLayout, Section, Heading, Paragraph } from "shelving/ui";
+import { App, CenteredLayout, Section, Title, Paragraph } from "shelving/ui";
 
 function HelloApp() {
   return (
     <App app="My app">
       <CenteredLayout>
         <Section narrow>
-          <Heading>Hello</Heading>
+          <Title>Hello</Title>
           <Paragraph>Welcome to the app.</Paragraph>
         </Section>
       </CenteredLayout>

package/ui/block/Card.d.ts

@@ -12,7 +12,7 @@ export interface CardProps extends ClickableProps {
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  *
- * @example <Card><Heading>Static</Heading></Card>
- * @example <Card href="/foo" title="Open foo"><Heading>Clickable</Heading></Card>
+ * @example <Card><Subheading>Static</Subheading></Card>
+ * @example <Card href="/foo" title="Open foo"><Subheading>Clickable</Subheading></Card>
  */
 export declare function Card({ children, href, onClick, title, ...props }: CardProps): ReactElement;

package/ui/block/Card.js

@@ -7,8 +7,8 @@ import CARD_CSS from "./Card.module.css";
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  *
- * @example <Card><Heading>Static</Heading></Card>
- * @example <Card href="/foo" title="Open foo"><Heading>Clickable</Heading></Card>
+ * @example <Card><Subheading>Static</Subheading></Card>
+ * @example <Card href="/foo" title="Open foo"><Subheading>Clickable</Subheading></Card>
  */
 export function Card({ children, href, onClick, title = "Open", ...props }) {
     const overlay = (href || onClick) && _jsx(Clickable, { title: title, href: href, onClick: onClick, ...props, className: CARD_CSS.overlay });

package/ui/block/Card.tsx

@@ -18,8 +18,8 @@ export interface CardProps extends ClickableProps {
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  *
- * @example <Card><Heading>Static</Heading></Card>
- * @example <Card href="/foo" title="Open foo"><Heading>Clickable</Heading></Card>
+ * @example <Card><Subheading>Static</Subheading></Card>
+ * @example <Card href="/foo" title="Open foo"><Subheading>Clickable</Subheading></Card>
  */
 export function Card({ children, href, onClick, title = "Open", ...props }: CardProps): ReactElement {
 	const overlay = (href || onClick) && <Clickable title={title} href={href} onClick={onClick} {...props} className={CARD_CSS.overlay} />;

package/ui/block/Heading.d.ts

@@ -1,6 +1,16 @@
-import type { ReactNode } from "react";
+import type { ReactElement, ReactNode } from "react";
+/** Props shared by `Title`, `Heading`, and `Subheading`. */
 export interface HeadingProps {
+    /**
+     * Heading level (`1`–`6`) — sets the rendered `<h1>`–`<h6>` tag.
+     * Avoid overriding this in practice: pick the component that matches the level — `Title` (`<h1>`), `Heading` (`<h2>`), or `Subheading` (`<h3>`) — so the visual size and the document outline stay in step.
+     */
     level?: "1" | "2" | "3" | "4" | "5" | "6" | 1 | 2 | 3 | 4 | 5 | 6;
+    /** Heading content. */
     children: ReactNode;
 }
-export declare function Heading({ level, children, ...variants }: HeadingProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Section heading — renders an `<h2>`.
+ * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
+ */
+export declare function Heading({ level, children, ...variants }: HeadingProps): ReactElement;

package/ui/block/Heading.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getModuleClass } from "../util/css.js";
 import styles from "./Heading.module.css";
-export function Heading({ level = "1", children, ...variants }) {
+/**
+ * Section heading — renders an `<h2>`.
+ * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
+ */
+export function Heading({ level = "2", children, ...variants }) {
     const Element = `h${level}`;
     return _jsx(Element, { className: getModuleClass(styles, "heading", variants), children: children });
 }

package/ui/block/Heading.module.css

@@ -1,22 +1,19 @@
 .heading,
-.prose h1 {
+.prose h2 {
 	/* Box */
 	display: block;
 	inline-size: 100%;
 	margin-inline: 0;
-	margin-block: var(--heading-spacing, var(--space-normal));
+	/* `em` top margin scales with font-size, so larger headings get proportionally more space above them. */
+	margin-block-start: var(--heading-spacing-before, 1.5em);
+	margin-block-end: var(--heading-spacing, var(--space-normal));
 
 	/* Style */
 	font-family: var(--heading-font, var(--font-body));
 	font-weight: var(--heading-weight, var(--weight-strong));
 	line-height: var(--heading-leading, var(--leading));
 	color: var(--heading-color, var(--color-text));
-
-	/*
-	 * Default font-size — applies to h1 (the `<Heading>` default) and to `.prose h1`.
-	 * Per-level rules below override for `<Heading level="2-6">` cases.
-	 */
-	font-size: var(--heading-font-size, var(--size-xxxlarge));
+	font-size: var(--heading-font-size, var(--size-xxlarge));
 
 	/* Psuedo-classes */
 	&:first-child {
@@ -26,14 +23,3 @@
 		margin-block-end: 0;
 	}
 }
-
-/* Per-level font-size scaling — `<Heading level="N">` sizes itself by its tag. */
-.heading:is(h2) {
-	font-size: var(--heading-font-size, var(--size-xxlarge));
-}
-.heading:is(h3) {
-	font-size: var(--heading-font-size, var(--size-xlarge));
-}
-.heading:is(h4, h5, h6) {
-	font-size: var(--heading-font-size, var(--size-large));
-}

package/ui/block/Heading.tsx

@@ -1,13 +1,23 @@
-import type { ReactNode } from "react";
+import type { ReactElement, ReactNode } from "react";
 import { getModuleClass } from "../util/css.js";
 import styles from "./Heading.module.css";
 
+/** Props shared by `Title`, `Heading`, and `Subheading`. */
 export interface HeadingProps {
+	/**
+	 * Heading level (`1`–`6`) — sets the rendered `<h1>`–`<h6>` tag.
+	 * Avoid overriding this in practice: pick the component that matches the level — `Title` (`<h1>`), `Heading` (`<h2>`), or `Subheading` (`<h3>`) — so the visual size and the document outline stay in step.
+	 */
 	level?: "1" | "2" | "3" | "4" | "5" | "6" | 1 | 2 | 3 | 4 | 5 | 6;
+	/** Heading content. */
 	children: ReactNode;
 }
 
-export function Heading({ level = "1", children, ...variants }: HeadingProps) {
+/**
+ * Section heading — renders an `<h2>`.
+ * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
+ */
+export function Heading({ level = "2", children, ...variants }: HeadingProps): ReactElement {
 	const Element: `h${typeof level}` = `h${level}`;
 	return <Element className={getModuleClass(styles, "heading", variants)}>{children}</Element>;
 }

package/ui/block/README.md

@@ -31,10 +31,10 @@ Some block components ship multiple pieces intended to compose:
 ### Content card with a heading
 
 ```tsx
-import { Card, Heading, Paragraph } from "shelving/ui";
+import { Card, Paragraph, Subheading } from "shelving/ui";
 
 <Card href="/products/42" title="Open product">
-  <Heading level={2}>Widget Pro</Heading>
+  <Subheading>Widget Pro</Subheading>
   <Paragraph>The best widget on the market.</Paragraph>
 </Card>
 ```
@@ -56,7 +56,7 @@ import { Section, Heading, Definitions, Definition } from "shelving/ui";
 </Section>
 ```
 
-`<Subheading>` uses the same `level` prop as `<Heading>` but applies secondary typography styles — use it for in-section labels and panel titles.
+`<Title>`, `<Heading>`, and `<Subheading>` render `<h1>`, `<h2>`, and `<h3>` respectively — pick the component that matches the level rather than overriding it with the `level` prop. Use `<Subheading>` for card titles, in-section labels, and panel titles.
 
 ### Prose content from a renderer
 
@@ -73,12 +73,12 @@ Wrap `<Markup>` (or any component that emits raw HTML elements) in `<Prose>` to
 ### Flex row of cards
 
 ```tsx
-import { Flex, Card, Heading } from "shelving/ui";
+import { Card, Flex, Subheading } from "shelving/ui";
 
 <Flex wrap>
   {products.map(p => (
     <Card key={p.id} href={`/products/${p.id}`}>
-      <Heading level={3}>{p.name}</Heading>
+      <Subheading>{p.name}</Subheading>
     </Card>
   ))}
 </Flex>

package/ui/block/Subheading.d.ts

@@ -1,3 +1,9 @@
+import type { ReactElement } from "react";
 import type { HeadingProps } from "./Heading.js";
+/** Props for `Subheading` — identical to `HeadingProps`. */
 export type SubheadingProps = HeadingProps;
-export declare function Subheading({ level, children, ...variants }: SubheadingProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Subsection heading — renders an `<h3>`.
+ * - Only marginally larger than body text; its bold weight is the main differentiator.
+ */
+export declare function Subheading({ level, children, ...variants }: SubheadingProps): ReactElement;

package/ui/block/Subheading.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getModuleClass } from "../util/css.js";
 import styles from "./Subheading.module.css";
-export function Subheading({ level = "2", children, ...variants }) {
+/**
+ * Subsection heading — renders an `<h3>`.
+ * - Only marginally larger than body text; its bold weight is the main differentiator.
+ */
+export function Subheading({ level = "3", children, ...variants }) {
     const Element = `h${level}`;
     return _jsx(Element, { className: getModuleClass(styles, "subheading", variants), children: children });
 }

package/ui/block/Subheading.module.css

@@ -1,22 +1,19 @@
 .subheading,
-.prose :is(h2, h3, h4, h5, h6) {
+.prose :is(h3, h4, h5, h6) {
 	/* Box */
 	display: block;
 	inline-size: 100%;
 	margin-inline: 0;
-	margin-block: var(--subheading-spacing, var(--space-normal));
+	/* `em` top margin scales with font-size, so larger headings get proportionally more space above them. */
+	margin-block-start: var(--subheading-spacing-before, 1.5em);
+	margin-block-end: var(--subheading-spacing, var(--space-normal));
 
 	/* Style */
 	font-family: var(--subheading-font, var(--font-body));
 	font-weight: var(--subheading-weight, var(--weight-strong));
 	line-height: var(--subheading-leading, var(--leading));
 	color: var(--subheading-color, var(--color-text));
-
-	/*
-	 * Default font-size — applies to h2 (the `<Subheading>` default).
-	 * Per-level rules below override for `<Subheading level="3-6">` cases and for `.prose` headings.
-	 */
-	font-size: var(--subheading-font-size, var(--size-xxlarge));
+	font-size: var(--subheading-font-size, var(--size-large));
 
 	/* Psuedo-classes */
 	&:first-child {
@@ -26,13 +23,3 @@
 		margin-block-end: 0;
 	}
 }
-
-/* Per-level font-size scaling — `<Subheading level="N">` (and prose headings) size by tag. */
-.subheading:is(h3),
-.prose h3 {
-	font-size: var(--subheading-font-size, var(--size-xlarge));
-}
-.subheading:is(h4, h5, h6),
-.prose :is(h4, h5, h6) {
-	font-size: var(--subheading-font-size, var(--size-large));
-}

package/ui/block/Subheading.tsx

@@ -1,10 +1,16 @@
+import type { ReactElement } from "react";
 import { getModuleClass } from "../util/css.js";
 import type { HeadingProps } from "./Heading.js";
 import styles from "./Subheading.module.css";
 
+/** Props for `Subheading` — identical to `HeadingProps`. */
 export type SubheadingProps = HeadingProps;
 
-export function Subheading({ level = "2", children, ...variants }: SubheadingProps) {
+/**
+ * Subsection heading — renders an `<h3>`.
+ * - Only marginally larger than body text; its bold weight is the main differentiator.
+ */
+export function Subheading({ level = "3", children, ...variants }: SubheadingProps): ReactElement {
 	const Element: `h${typeof level}` = `h${level}`;
 	return <Element className={getModuleClass(styles, "subheading", variants)}>{children}</Element>;
 }

package/ui/block/Title.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from "react";
+import type { HeadingProps } from "./Heading.js";
+/** Props for `Title` — identical to `HeadingProps`. */
+export type TitleProps = HeadingProps;
+/**
+ * Page title — renders an `<h1>`.
+ * - The most prominent heading on a page; there should normally be exactly one.
+ */
+export declare function Title({ level, children, ...variants }: TitleProps): ReactElement;

package/ui/block/Title.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getModuleClass } from "../util/css.js";
+import styles from "./Title.module.css";
+/**
+ * Page title — renders an `<h1>`.
+ * - The most prominent heading on a page; there should normally be exactly one.
+ */
+export function Title({ level = "1", children, ...variants }) {
+    const Element = `h${level}`;
+    return _jsx(Element, { className: getModuleClass(styles, "title", variants), children: children });
+}

package/ui/block/Title.module.css

@@ -0,0 +1,25 @@
+.title,
+.prose h1 {
+	/* Box */
+	display: block;
+	inline-size: 100%;
+	margin-inline: 0;
+	/* `em` top margin scales with font-size, so larger headings get proportionally more space above them. */
+	margin-block-start: var(--title-spacing-before, 1.5em);
+	margin-block-end: var(--title-spacing, var(--space-normal));
+
+	/* Style */
+	font-family: var(--title-font, var(--font-body));
+	font-weight: var(--title-weight, var(--weight-strong));
+	line-height: var(--title-leading, var(--leading));
+	color: var(--title-color, var(--color-text));
+	font-size: var(--title-font-size, var(--size-xxxlarge));
+
+	/* Psuedo-classes */
+	&:first-child {
+		margin-block-start: 0;
+	}
+	&:last-child {
+		margin-block-end: 0;
+	}
+}

package/ui/block/Title.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { getModuleClass } from "../util/css.js";
+import type { HeadingProps } from "./Heading.js";
+import styles from "./Title.module.css";
+
+/** Props for `Title` — identical to `HeadingProps`. */
+export type TitleProps = HeadingProps;
+
+/**
+ * Page title — renders an `<h1>`.
+ * - The most prominent heading on a page; there should normally be exactly one.
+ */
+export function Title({ level = "1", children, ...variants }: TitleProps): ReactElement {
+	const Element: `h${typeof level}` = `h${level}`;
+	return <Element className={getModuleClass(styles, "title", variants)}>{children}</Element>;
+}

package/ui/block/index.d.ts

@@ -15,4 +15,5 @@ export * from "./Prose.js";
 export * from "./Section.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./Title.js";
 export * from "./Video.js";

package/ui/block/index.js

@@ -15,4 +15,5 @@ export * from "./Prose.js";
 export * from "./Section.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./Title.js";
 export * from "./Video.js";

package/ui/block/index.ts

@@ -15,4 +15,5 @@ export * from "./Prose.js";
 export * from "./Section.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./Title.js";
 export * from "./Video.js";

package/ui/docs/DirectoryCard.d.ts

@@ -2,8 +2,8 @@ import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
 interface DirectoryCardProps extends DirectoryElementProps {
-    path?: AbsolutePath | undefined;
+    path: AbsolutePath;
 }
 /** Card renderer for a `tree-directory` element. */
-export declare function DirectoryCard({ path, title, name, content }: DirectoryCardProps): ReactNode;
+export declare function DirectoryCard({ path, name, title, content }: DirectoryCardProps): ReactNode;
 export {};

package/ui/docs/DirectoryCard.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Heading } from "../block/Heading.js";
 import { Prose } from "../block/Prose.js";
+import { Subheading } from "../block/Subheading.js";
 import { Markup } from "../misc/Markup.js";
 /** Card renderer for a `tree-directory` element. */
-export function DirectoryCard({ path = "/", title, name, content }) {
+export function DirectoryCard({ path, name, title, content }) {
     const href = joinPath(path, name);
-    return (_jsxs(Card, { href: href, children: [_jsx(Heading, { level: "3", children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
+    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
 }

package/ui/docs/DirectoryCard.tsx

@@ -2,20 +2,20 @@ import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
 import { type AbsolutePath, joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Heading } from "../block/Heading.js";
 import { Prose } from "../block/Prose.js";
+import { Subheading } from "../block/Subheading.js";
 import { Markup } from "../misc/Markup.js";
 
 interface DirectoryCardProps extends DirectoryElementProps {
-	path?: AbsolutePath | undefined;
+	path: AbsolutePath;
 }
 
 /** Card renderer for a `tree-directory` element. */
-export function DirectoryCard({ path = "/", title, name, content }: DirectoryCardProps): ReactNode {
+export function DirectoryCard({ path, name, title, content }: DirectoryCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>
-			<Heading level="3">{title ?? name}</Heading>
+			<Subheading>{title ?? name}</Subheading>
 			{content && (
 				<Prose>
 					<Markup>{content}</Markup>

package/ui/docs/DirectoryPage.js

@@ -1,9 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
+import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-directory` element — shows title, content, and child cards. */
 export function DirectoryPage({ title, name, description, content, children }) {
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { children: children })] }));
+    const { url } = requireMeta();
+    const path = url?.pathname ?? "/";
+    return (_jsxs(Page, { title: title ?? name, description: description, children: [content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
 }

package/ui/docs/DirectoryPage.tsx

@@ -2,11 +2,14 @@ import type { ReactNode } from "react";
 import type { DirectoryElementProps } from "../../util/element.js";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
+import { requireMeta } from "../misc/MetaContext.js";
 import { Page } from "../page/Page.js";
 import { TreeCards } from "../tree/TreeCards.js";
 
 /** Page renderer for a `tree-directory` element — shows title, content, and child cards. */
 export function DirectoryPage({ title, name, description, content, children }: DirectoryElementProps): ReactNode {
+	const { url } = requireMeta();
+	const path = url?.pathname ?? "/";
 	return (
 		<Page title={title ?? name} description={description}>
 			{content && (
@@ -14,7 +17,7 @@ export function DirectoryPage({ title, name, description, content, children }: D
 					<Markup>{content}</Markup>
 				</Prose>
 			)}
-			<TreeCards>{children}</TreeCards>
+			<TreeCards path={path}>{children}</TreeCards>
 		</Page>
 	);
 }

package/ui/docs/DocumentationCard.d.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
 interface DocumentationCardProps extends DocumentationElementProps {
-    path?: AbsolutePath | undefined;
+    path: AbsolutePath;
 }
 /** Card renderer for a `tree-documentation` element. */
 export declare function DocumentationCard({ path, title, name, kind, content, signatures }: DocumentationCardProps): ReactNode;

package/ui/docs/DocumentationCard.js

@@ -2,14 +2,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
 import { Flex } from "../block/Flex.js";
-import { Heading } from "../block/Heading.js";
 import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
+import { Subheading } from "../block/Subheading.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { DocumentationKind } from "./DocumentationKind.js";
 /** Card renderer for a `tree-documentation` element. */
-export function DocumentationCard({ path = "/", title, name, kind, content, signatures }) {
+export function DocumentationCard({ path, title, name, kind, content, signatures }) {
     const href = joinPath(path, name);
-    return (_jsxs(Card, { href: href, children: [_jsx(Heading, { level: "3", children: _jsxs(Flex, { left: true, children: [_jsx(Code, { children: title ?? name }), kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
+    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: _jsxs(Flex, { left: true, children: [_jsx(Code, { children: title ?? name }), kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
 }

package/ui/docs/DocumentationCard.tsx

@@ -3,28 +3,28 @@ import type { DocumentationElementProps } from "../../util/element.js";
 import { type AbsolutePath, joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
 import { Flex } from "../block/Flex.js";
-import { Heading } from "../block/Heading.js";
 import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
+import { Subheading } from "../block/Subheading.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { DocumentationKind } from "./DocumentationKind.js";
 
 interface DocumentationCardProps extends DocumentationElementProps {
-	path?: AbsolutePath | undefined;
+	path: AbsolutePath;
 }
 
 /** Card renderer for a `tree-documentation` element. */
-export function DocumentationCard({ path = "/", title, name, kind, content, signatures }: DocumentationCardProps): ReactNode {
+export function DocumentationCard({ path, title, name, kind, content, signatures }: DocumentationCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>
-			<Heading level="3">
+			<Subheading>
 				<Flex left>
 					<Code>{title ?? name}</Code>
 					{kind && <DocumentationKind kind={kind} />}
 				</Flex>
-			</Heading>
+			</Subheading>
 			{signatures?.map(sig => (
 				<Preformatted key={sig}>{sig}</Preformatted>
 			))}

package/ui/docs/FileCard.d.ts

@@ -2,8 +2,8 @@ import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
 import { type AbsolutePath } from "../../util/path.js";
 interface FileCardProps extends FileElementProps {
-    path?: AbsolutePath | undefined;
+    path: AbsolutePath;
 }
 /** Card renderer for a `tree-file` element. */
-export declare function FileCard({ path, title, name, content }: FileCardProps): ReactNode;
+export declare function FileCard({ path, name, title, content }: FileCardProps): ReactNode;
 export {};

package/ui/docs/FileCard.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Heading } from "../block/Heading.js";
 import { Prose } from "../block/Prose.js";
+import { Subheading } from "../block/Subheading.js";
 import { Markup } from "../misc/Markup.js";
 /** Card renderer for a `tree-file` element. */
-export function FileCard({ path = "/", title, name, content }) {
+export function FileCard({ path, name, title, content }) {
     const href = joinPath(path, name);
-    return (_jsxs(Card, { href: href, children: [_jsx(Heading, { level: "3", children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
+    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: title ?? name }), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) }))] }));
 }

package/ui/docs/FileCard.tsx

@@ -2,20 +2,20 @@ import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
 import { type AbsolutePath, joinPath } from "../../util/path.js";
 import { Card } from "../block/Card.js";
-import { Heading } from "../block/Heading.js";
 import { Prose } from "../block/Prose.js";
+import { Subheading } from "../block/Subheading.js";
 import { Markup } from "../misc/Markup.js";
 
 interface FileCardProps extends FileElementProps {
-	path?: AbsolutePath | undefined;
+	path: AbsolutePath;
 }
 
 /** Card renderer for a `tree-file` element. */
-export function FileCard({ path = "/", title, name, content }: FileCardProps): ReactNode {
+export function FileCard({ path, name, title, content }: FileCardProps): ReactNode {
 	const href = joinPath(path, name);
 	return (
 		<Card href={href}>
-			<Heading level="3">{title ?? name}</Heading>
+			<Subheading>{title ?? name}</Subheading>
 			{content && (
 				<Prose>
 					<Markup>{content}</Markup>

package/ui/docs/FilePage.js

@@ -7,6 +7,6 @@ import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-file` element — shows title, content, and child code symbols. */
 export function FilePage({ title, name, description, content, children }) {
     const { url } = requireMeta();
-    const path = (url?.pathname ?? "/");
+    const path = url?.pathname ?? "/";
     return (_jsxs(Page, { title: title ?? name, description: description, children: [content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), _jsx(TreeCards, { path: path, children: children })] }));
 }

package/ui/docs/FilePage.tsx

@@ -1,6 +1,5 @@
 import type { ReactNode } from "react";
 import type { FileElementProps } from "../../util/element.js";
-import type { AbsolutePath } from "../../util/path.js";
 import { Prose } from "../block/Prose.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
@@ -10,7 +9,7 @@ import { TreeCards } from "../tree/TreeCards.js";
 /** Page renderer for a `tree-file` element — shows title, content, and child code symbols. */
 export function FilePage({ title, name, description, content, children }: FileElementProps): ReactNode {
 	const { url } = requireMeta();
-	const path = (url?.pathname ?? "/") as AbsolutePath;
+	const path = url?.pathname ?? "/";
 	return (
 		<Page title={title ?? name} description={description}>
 			{content && (

package/ui/tree/TreeCards.d.ts

@@ -3,21 +3,21 @@ import { type TreeElements } from "../../util/element.js";
 import type { AbsolutePath } from "../../util/path.js";
 /** Extras threaded through `TreeCardMapper` to every card — currently just the parent URL path. */
 export interface TreeCardExtras {
-    /** URL path of the parent element. Each card computes its own path as `path + mapped.key`. Defaults to `/`. */
-    readonly path?: AbsolutePath | undefined;
+    /** URL path of the parent element. Each card computes its own path as `path + mapped.name`. Defaults to `/`. */
+    readonly path: AbsolutePath;
 }
 /** Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override. */
 export declare const TreeCardMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<TreeCardExtras>>, TreeCardMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps<TreeCardExtras>>;
 export interface TreeCardsProps {
     /** The children to render as cards. */
     readonly children?: TreeElements;
-    /** URL path of the parent element. Each card appends its own key to compute its href. */
+    /** URL path of the parent element. Each card appends its own name to compute its href. */
     readonly path?: AbsolutePath | undefined;
 }
 /**
  * Render a list of tree elements as a stack of cards.
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer.
- * - `path` is threaded through to each card so it can compute its href as `path + key`.
+ * - `path` is threaded through to each card so it can compute its href as `path + name`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
  */
-export declare function TreeCards({ children, path }: TreeCardsProps): ReactNode;
+export declare function TreeCards({ path, children }: TreeCardsProps): ReactNode;

package/ui/tree/TreeCards.js

@@ -13,9 +13,9 @@ export const [TreeCardMapping, TreeCardMapper] = createMapper({
 /**
  * Render a list of tree elements as a stack of cards.
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer.
- * - `path` is threaded through to each card so it can compute its href as `path + key`.
+ * - `path` is threaded through to each card so it can compute its href as `path + name`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
  */
-export function TreeCards({ children, path }) {
+export function TreeCards({ path = "/", children }) {
     return _jsx(TreeCardMapper, { path: path, children: walkElements(children) });
 }

package/ui/tree/TreeCards.tsx

@@ -8,8 +8,8 @@ import { createMapper } from "../misc/Mapper.js";
 
 /** Extras threaded through `TreeCardMapper` to every card — currently just the parent URL path. */
 export interface TreeCardExtras {
-	/** URL path of the parent element. Each card computes its own path as `path + mapped.key`. Defaults to `/`. */
-	readonly path?: AbsolutePath | undefined;
+	/** URL path of the parent element. Each card computes its own path as `path + mapped.name`. Defaults to `/`. */
+	readonly path: AbsolutePath;
 }
 
 /** Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override. */
@@ -22,16 +22,16 @@ export const [TreeCardMapping, TreeCardMapper] = createMapper<TreeCardExtras>({
 export interface TreeCardsProps {
 	/** The children to render as cards. */
 	readonly children?: TreeElements;
-	/** URL path of the parent element. Each card appends its own key to compute its href. */
+	/** URL path of the parent element. Each card appends its own name to compute its href. */
 	readonly path?: AbsolutePath | undefined;
 }
 
 /**
  * Render a list of tree elements as a stack of cards.
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer.
- * - `path` is threaded through to each card so it can compute its href as `path + key`.
+ * - `path` is threaded through to each card so it can compute its href as `path + name`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
  */
-export function TreeCards({ children, path }: TreeCardsProps): ReactNode {
+export function TreeCards({ path = "/", children }: TreeCardsProps): ReactNode {
 	return <TreeCardMapper path={path}>{walkElements(children)}</TreeCardMapper>;
 }

package/ui/tree/TreeMenu.d.ts

@@ -9,7 +9,7 @@ export declare const MENU_QUERY: Query<{
 /** Extras threaded through `TreeMenuMapper` to every menu item — the parent's URL path. */
 interface TreeMenuExtras {
     /** URL path of the parent element. Each item appends its own `name` to compute its own path. Defaults to `/`. */
-    readonly path?: AbsolutePath | undefined;
+    readonly path: AbsolutePath;
 }
 /**
  * Default menu item renderer for any `tree-*` element.
@@ -31,5 +31,5 @@ export interface TreeMenuProps {
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  */
-export declare function TreeMenu({ tree, path }: TreeMenuProps): ReactNode;
+export declare function TreeMenu({ path, tree }: TreeMenuProps): ReactNode;
 export {};

package/ui/tree/TreeMenu.js

@@ -27,6 +27,6 @@ export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  */
-export function TreeMenu({ tree, path = "/" }) {
+export function TreeMenu({ path = "/", tree }) {
     return (_jsx(Menu, { children: _jsx(TreeMenuMapper, { path: path, children: queryElements(tree.props.children, MENU_QUERY) }) }));
 }

package/ui/tree/TreeMenu.tsx

@@ -12,7 +12,7 @@ export const MENU_QUERY: Query<{ type: string }> = { type: ["tree-directory", "t
 /** Extras threaded through `TreeMenuMapper` to every menu item — the parent's URL path. */
 interface TreeMenuExtras {
 	/** URL path of the parent element. Each item appends its own `name` to compute its own path. Defaults to `/`. */
-	readonly path?: AbsolutePath | undefined;
+	readonly path: AbsolutePath;
 }
 
 /**
@@ -54,7 +54,7 @@ export interface TreeMenuProps {
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
  */
-export function TreeMenu({ tree, path = "/" }: TreeMenuProps): ReactNode {
+export function TreeMenu({ path = "/", tree }: TreeMenuProps): ReactNode {
 	return (
 		<Menu>
 			<TreeMenuMapper path={path}>{queryElements(tree.props.children, MENU_QUERY)}</TreeMenuMapper>