shelving 1.215.2 → 1.216.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.215.2",
+	"version": "1.216.1",
 	"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.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, 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,8 +2,8 @@ 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 {
@@ -15,7 +15,7 @@ export function DirectoryCard({ path, name, title, content }: DirectoryCardProps
 	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/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 }) {
     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,9 +3,9 @@ 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";
@@ -19,12 +19,12 @@ export function DocumentationCard({ path, title, name, kind, content, signatures
 	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/DocumentationPage.js

@@ -1,9 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Definition, Definitions } from "../block/Definitions.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 { Section } from "../block/Section.js";
+import { Title } from "../block/Title.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
@@ -19,5 +21,5 @@ const DEFAULT_TYPE = "unknown";
 export function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, }) {
     const { url } = requireMeta();
     const path = (url?.pathname ?? "/");
-    return (_jsxs(Page, { title: title ?? name, description: description, children: [kind && _jsx(DocumentationKind, { kind: kind }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), params?.length && (_jsxs(Section, { children: [_jsx(Heading, { level: "2", children: "Parameters" }), _jsx(Definitions, { row: true, children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsx(Definition, { term: _jsxs(_Fragment, { children: [_jsx(Code, { children: name }), ": ", _jsx(Code, { children: type }), optional && _jsx(_Fragment, { children: " (optional)" })] }), children: description }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { children: [_jsx(Heading, { level: "2", children: "Returns" }), _jsx(Definitions, { row: true, children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { children: [_jsx(Heading, { level: "2", children: "Throws" }), _jsx(Definitions, { row: true, children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { level: "2", children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(TreeCards, { path: path, children: children })] }));
+    return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Title, { children: _jsxs(Flex, { left: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })), params?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Parameters" }), _jsx(Definitions, { row: true, children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsx(Definition, { term: _jsxs(_Fragment, { children: [_jsx(Code, { children: name }), ": ", _jsx(Code, { children: type }), optional && _jsx(_Fragment, { children: " (optional)" })] }), children: description }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Returns" }), _jsx(Definitions, { row: true, children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Throws" }), _jsx(Definitions, { row: true, children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsx(Definition, { term: _jsx(Code, { children: type }), children: description }, `${type}-${description}`))) })] })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(TreeCards, { path: path, children: children })] }));
 }

package/ui/docs/DocumentationPage.tsx

@@ -2,10 +2,12 @@ import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/element.js";
 import type { AbsolutePath } from "../../util/path.js";
 import { Definition, Definitions } from "../block/Definitions.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 { Section } from "../block/Section.js";
+import { Title } from "../block/Title.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
 import { requireMeta } from "../misc/MetaContext.js";
@@ -37,7 +39,12 @@ export function DocumentationPage({
 	const path = (url?.pathname ?? "/") as AbsolutePath;
 	return (
 		<Page title={title ?? name} description={description}>
-			{kind && <DocumentationKind kind={kind} />}
+			<Title>
+				<Flex left>
+					{title ?? name}
+					{kind && <DocumentationKind kind={kind} />}
+				</Flex>
+			</Title>
 			{signatures?.map(sig => (
 				<Preformatted key={sig}>{sig}</Preformatted>
 			))}
@@ -48,7 +55,7 @@ export function DocumentationPage({
 			)}
 			{params?.length && (
 				<Section>
-					<Heading level="2">Parameters</Heading>
+					<Heading>Parameters</Heading>
 					<Definitions row>
 						{params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (
 							<Definition
@@ -68,7 +75,7 @@ export function DocumentationPage({
 			)}
 			{returns?.length && (
 				<Section>
-					<Heading level="2">Returns</Heading>
+					<Heading>Returns</Heading>
 					<Definitions row>
 						{returns.map(({ type = DEFAULT_TYPE, description = "" }) => (
 							<Definition key={`${type}-${description}`} term={<Code>{type}</Code>}>
@@ -80,7 +87,7 @@ export function DocumentationPage({
 			)}
 			{throws?.length && (
 				<Section>
-					<Heading level="2">Throws</Heading>
+					<Heading>Throws</Heading>
 					<Definitions row>
 						{throws.map(({ type = DEFAULT_TYPE, description = "" }) => (
 							<Definition key={`${type}-${description}`} term={<Code>{type}</Code>}>
@@ -92,7 +99,7 @@ export function DocumentationPage({
 			)}
 			{examples?.length && (
 				<Section>
-					<Heading level="2">Examples</Heading>
+					<Heading>Examples</Heading>
 					{examples.map(({ description }) => (
 						<Preformatted key={description}>{description}</Preformatted>
 					))}

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, 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,8 +2,8 @@ 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 {
@@ -15,7 +15,7 @@ export function FileCard({ path, name, title, content }: FileCardProps): ReactNo
 	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/menu/Menu.module.css

@@ -9,7 +9,7 @@
 
 	/* Typography */
 	font-family: var(--menu-font, var(--font-body));
-	font-size: var(--menu-size, var(--size-small));
+	font-size: var(--menu-size, var(--size-normal));
 	line-height: var(--menu-leading, var(--leading-normal));
 	color: var(--menu-color-text, var(--color-quiet));
 }