shelving 1.236.0 → 1.236.2

package/ui/block/Section.d.ts

@@ -4,21 +4,84 @@ import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * CSS class applied to the root element of every `Section` and its semantic siblings.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SECTION_CLASS
+ */
 export declare const SECTION_CLASS: string | undefined;
+/**
+ * CSS class that styles a `Section` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SECTION_PROSE_CLASS
+ */
 export declare const SECTION_PROSE_CLASS: string | undefined;
+/**
+ * Semantic element names a `Section` may render as via its `as` prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SectionElement
+ */
 export type SectionElement = "section" | "header" | "footer" | "nav" | "aside" | "figure";
+/**
+ * Props for `Section` and its semantic siblings — colour, space, typography, and width variants plus an optional `as` element override.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SectionProps
+ */
 export interface SectionProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
     as?: SectionElement | undefined;
 }
-/** `<section>` block with block-level spacing. */
+/**
+ * `<section>` block with block-level spacing.
+ * - Pass `as` to render a different semantic element.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<section>` element.
+ * @example <Section><Heading>About</Heading></Section>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Section
+ */
 export declare function Section(props: SectionProps): ReactElement;
-/** `<header>` block with block-level spacing. */
+/**
+ * `<header>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<header>` element.
+ * @example <Header><Title>Welcome</Title></Header>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Header
+ */
 export declare function Header(props: SectionProps): ReactElement;
-/** `<footer>` block with block-level spacing. */
+/**
+ * `<footer>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<footer>` element.
+ * @example <Footer><Small>© 2026</Small></Footer>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Footer
+ */
 export declare function Footer(props: SectionProps): ReactElement;
-/** `<nav>` block with block-level spacing. */
+/**
+ * `<nav>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<nav>` element.
+ * @example <Nav><Link href="/">Home</Link></Nav>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Nav
+ */
 export declare function Nav(props: SectionProps): ReactElement;
-/** `<aside>` block with block-level spacing. */
+/**
+ * `<aside>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<aside>` element.
+ * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Aside
+ */
 export declare function Aside(props: SectionProps): ReactElement;
-/** `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content. */
+/**
+ * `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<figure>` element.
+ * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Figure
+ */
 export declare function Figure(props: SectionProps): ReactElement;

package/ui/block/Section.js

@@ -5,32 +5,85 @@ import { getTypographyClass } from "../style/Typography.js";
 import { getWidthClass } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import SECTION_CSS from "./Section.module.css";
+/**
+ * CSS class applied to the root element of every `Section` and its semantic siblings.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SECTION_CLASS
+ */
 export const SECTION_CLASS = getModuleClass(SECTION_CSS, "section");
+/**
+ * CSS class that styles a `Section` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SECTION_PROSE_CLASS
+ */
 export const SECTION_PROSE_CLASS = getModuleClass(SECTION_CSS, "prose");
 function renderSection(defaultComponent, { as: Component = defaultComponent, children, ...variants }) {
     return (_jsx(Component, { className: getClass(SECTION_CLASS, getColorClass(variants), getSpaceClass(variants), getTypographyClass(variants), getWidthClass(variants)), children: children }));
 }
-/** `<section>` block with block-level spacing. */
+/**
+ * `<section>` block with block-level spacing.
+ * - Pass `as` to render a different semantic element.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<section>` element.
+ * @example <Section><Heading>About</Heading></Section>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Section
+ */
 export function Section(props) {
     return renderSection("section", props);
 }
-/** `<header>` block with block-level spacing. */
+/**
+ * `<header>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<header>` element.
+ * @example <Header><Title>Welcome</Title></Header>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Header
+ */
 export function Header(props) {
     return renderSection("header", props);
 }
-/** `<footer>` block with block-level spacing. */
+/**
+ * `<footer>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<footer>` element.
+ * @example <Footer><Small>© 2026</Small></Footer>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Footer
+ */
 export function Footer(props) {
     return renderSection("footer", props);
 }
-/** `<nav>` block with block-level spacing. */
+/**
+ * `<nav>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<nav>` element.
+ * @example <Nav><Link href="/">Home</Link></Nav>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Nav
+ */
 export function Nav(props) {
     return renderSection("nav", props);
 }
-/** `<aside>` block with block-level spacing. */
+/**
+ * `<aside>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<aside>` element.
+ * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Aside
+ */
 export function Aside(props) {
     return renderSection("aside", props);
 }
-/** `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content. */
+/**
+ * `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<figure>` element.
+ * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Figure
+ */
 export function Figure(props) {
     return renderSection("figure", props);
 }

package/ui/block/Section.tsx

@@ -7,11 +7,32 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import SECTION_CSS from "./Section.module.css";
 
+/**
+ * CSS class applied to the root element of every `Section` and its semantic siblings.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SECTION_CLASS
+ */
 export const SECTION_CLASS = getModuleClass(SECTION_CSS, "section");
+
+/**
+ * CSS class that styles a `Section` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SECTION_PROSE_CLASS
+ */
 export const SECTION_PROSE_CLASS = getModuleClass(SECTION_CSS, "prose");
 
+/**
+ * Semantic element names a `Section` may render as via its `as` prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SectionElement
+ */
 export type SectionElement = "section" | "header" | "footer" | "nav" | "aside" | "figure";
 
+/**
+ * Props for `Section` and its semantic siblings — colour, space, typography, and width variants plus an optional `as` element override.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/SectionProps
+ */
 export interface SectionProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
 	as?: SectionElement | undefined;
 }
@@ -35,32 +56,75 @@ function renderSection(
 	);
 }
 
-/** `<section>` block with block-level spacing. */
+/**
+ * `<section>` block with block-level spacing.
+ * - Pass `as` to render a different semantic element.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<section>` element.
+ * @example <Section><Heading>About</Heading></Section>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Section
+ */
 export function Section(props: SectionProps): ReactElement {
 	return renderSection("section", props);
 }
 
-/** `<header>` block with block-level spacing. */
+/**
+ * `<header>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<header>` element.
+ * @example <Header><Title>Welcome</Title></Header>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Header
+ */
 export function Header(props: SectionProps): ReactElement {
 	return renderSection("header", props);
 }
 
-/** `<footer>` block with block-level spacing. */
+/**
+ * `<footer>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<footer>` element.
+ * @example <Footer><Small>© 2026</Small></Footer>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Footer
+ */
 export function Footer(props: SectionProps): ReactElement {
 	return renderSection("footer", props);
 }
 
-/** `<nav>` block with block-level spacing. */
+/**
+ * `<nav>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<nav>` element.
+ * @example <Nav><Link href="/">Home</Link></Nav>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Nav
+ */
 export function Nav(props: SectionProps): ReactElement {
 	return renderSection("nav", props);
 }
 
-/** `<aside>` block with block-level spacing. */
+/**
+ * `<aside>` block with block-level spacing.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<aside>` element.
+ * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Aside
+ */
 export function Aside(props: SectionProps): ReactElement {
 	return renderSection("aside", props);
 }
 
-/** `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content. */
+/**
+ * `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content.
+ *
+ * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
+ * @returns Rendered `<figure>` element.
+ * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Figure
+ */
 export function Figure(props: SectionProps): ReactElement {
 	return renderSection("figure", props);
 }

package/ui/block/Subheading.d.ts

@@ -1,11 +1,30 @@
 import type { ReactElement } from "react";
 import type { HeadingProps } from "./Heading.js";
+/**
+ * CSS class applied to the root element of every `Subheading`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SUBHEADING_CLASS
+ */
 export declare const SUBHEADING_CLASS: string | undefined;
+/**
+ * CSS class that styles a `Subheading` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SUBHEADING_PROSE_CLASS
+ */
 export declare const SUBHEADING_PROSE_CLASS: string | undefined;
-/** Props for `Subheading` — identical to `HeadingProps`. */
+/**
+ * Props for `Subheading` — identical to `HeadingProps`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SubheadingProps
+ */
 export type SubheadingProps = HeadingProps;
 /**
  * Subsection heading — renders an `<h3>`.
  * - Only marginally larger than body text; its bold weight is the main differentiator.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h3>` heading element.
+ * @example <Subheading>Details</Subheading>
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/Subheading
  */
 export declare function Subheading({ level, children, ...props }: SubheadingProps): ReactElement;

package/ui/block/Subheading.js

@@ -4,11 +4,26 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import SUBHEADING_CSS from "./Subheading.module.css";
+/**
+ * CSS class applied to the root element of every `Subheading`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SUBHEADING_CLASS
+ */
 export const SUBHEADING_CLASS = getModuleClass(SUBHEADING_CSS, "subheading");
+/**
+ * CSS class that styles a `Subheading` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SUBHEADING_PROSE_CLASS
+ */
 export const SUBHEADING_PROSE_CLASS = getModuleClass(SUBHEADING_CSS, "prose");
 /**
  * Subsection heading — renders an `<h3>`.
  * - Only marginally larger than body text; its bold weight is the main differentiator.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h3>` heading element.
+ * @example <Subheading>Details</Subheading>
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/Subheading
  */
 export function Subheading({ level = "3", children, ...props }) {
     const Element = `h${level}`;

package/ui/block/Subheading.tsx

@@ -6,15 +6,35 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { HeadingProps } from "./Heading.js";
 import SUBHEADING_CSS from "./Subheading.module.css";
 
+/**
+ * CSS class applied to the root element of every `Subheading`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SUBHEADING_CLASS
+ */
 export const SUBHEADING_CLASS = getModuleClass(SUBHEADING_CSS, "subheading");
+
+/**
+ * CSS class that styles a `Subheading` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SUBHEADING_PROSE_CLASS
+ */
 export const SUBHEADING_PROSE_CLASS = getModuleClass(SUBHEADING_CSS, "prose");
 
-/** Props for `Subheading` — identical to `HeadingProps`. */
+/**
+ * Props for `Subheading` — identical to `HeadingProps`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/SubheadingProps
+ */
 export type SubheadingProps = HeadingProps;
 
 /**
  * Subsection heading — renders an `<h3>`.
  * - Only marginally larger than body text; its bold weight is the main differentiator.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h3>` heading element.
+ * @example <Subheading>Details</Subheading>
+ * @see https://dhoulb.github.io/shelving/ui/block/Subheading/Subheading
  */
 export function Subheading({ level = "3", children, ...props }: SubheadingProps): ReactElement {
 	const Element: `h${typeof level}` = `h${level}`;

package/ui/block/Table.d.ts

@@ -3,13 +3,33 @@ import { type ColorVariants } from "../style/Color.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { ChildProps } from "../util/props.js";
+/**
+ * CSS class applied to the root element of every `Table`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TABLE_CLASS
+ */
 export declare const TABLE_CLASS: string | undefined;
+/**
+ * CSS class that styles a `Table` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TABLE_PROSE_CLASS
+ */
 export declare const TABLE_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Table` — colour, space, and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TableProps
+ */
 export interface TableProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {
 }
 /**
  * Table block — rendered as `<table>`.
  * - Wrap in a `<Scroll horizontal>` if the table may exceed the container width on small screens.
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
+ *
+ * @param props Colour, space, and typography variants plus `children`.
+ * @returns Rendered `<table>` element.
+ * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/Table
  */
 export declare function Table({ children, ...props }: TableProps): ReactElement;

package/ui/block/Table.js

@@ -4,12 +4,27 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import TABLE_CSS from "./Table.module.css";
+/**
+ * CSS class applied to the root element of every `Table`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TABLE_CLASS
+ */
 export const TABLE_CLASS = getModuleClass(TABLE_CSS, "divider");
+/**
+ * CSS class that styles a `Table` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TABLE_PROSE_CLASS
+ */
 export const TABLE_PROSE_CLASS = getModuleClass(TABLE_CSS, "prose");
 /**
  * Table block — rendered as `<table>`.
  * - Wrap in a `<Scroll horizontal>` if the table may exceed the container width on small screens.
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
+ *
+ * @param props Colour, space, and typography variants plus `children`.
+ * @returns Rendered `<table>` element.
+ * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/Table
  */
 export function Table({ children, ...props }) {
     return (_jsx("table", { className: getClass(TABLE_CLASS, //

package/ui/block/Table.tsx

@@ -6,15 +6,36 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { ChildProps } from "../util/props.js";
 import TABLE_CSS from "./Table.module.css";
 
+/**
+ * CSS class applied to the root element of every `Table`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TABLE_CLASS
+ */
 export const TABLE_CLASS = getModuleClass(TABLE_CSS, "divider");
+
+/**
+ * CSS class that styles a `Table` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TABLE_PROSE_CLASS
+ */
 export const TABLE_PROSE_CLASS = getModuleClass(TABLE_CSS, "prose");
 
+/**
+ * Props for `Table` — colour, space, and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/TableProps
+ */
 export interface TableProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {}
 
 /**
  * Table block — rendered as `<table>`.
  * - Wrap in a `<Scroll horizontal>` if the table may exceed the container width on small screens.
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
+ *
+ * @param props Colour, space, and typography variants plus `children`.
+ * @returns Rendered `<table>` element.
+ * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>
+ * @see https://dhoulb.github.io/shelving/ui/block/Table/Table
  */
 export function Table({ children, ...props }: TableProps): ReactElement {
 	return (

package/ui/block/Title.d.ts

@@ -1,11 +1,30 @@
 import type { ReactElement } from "react";
 import type { HeadingProps } from "./Heading.js";
+/**
+ * CSS class applied to the root element of every `Title`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TITLE_CLASS
+ */
 export declare const TITLE_CLASS: string | undefined;
+/**
+ * CSS class that styles a `Title` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TITLE_PROSE_CLASS
+ */
 export declare const TITLE_PROSE_CLASS: string | undefined;
-/** Props for `Title` — identical to `HeadingProps`. */
+/**
+ * Props for `Title` — identical to `HeadingProps`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TitleProps
+ */
 export type TitleProps = HeadingProps;
 /**
  * Page title — renders an `<h1>`.
  * - The most prominent heading on a page; there should normally be exactly one.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h1>` heading element.
+ * @example <Title>Welcome</Title>
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/Title
  */
 export declare function Title({ level, children, ...props }: TitleProps): ReactElement;

package/ui/block/Title.js

@@ -4,11 +4,26 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import TITLE_CSS from "./Title.module.css";
+/**
+ * CSS class applied to the root element of every `Title`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TITLE_CLASS
+ */
 export const TITLE_CLASS = getModuleClass(TITLE_CSS, "title");
+/**
+ * CSS class that styles a `Title` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TITLE_PROSE_CLASS
+ */
 export const TITLE_PROSE_CLASS = getModuleClass(TITLE_CSS, "prose");
 /**
  * Page title — renders an `<h1>`.
  * - The most prominent heading on a page; there should normally be exactly one.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h1>` heading element.
+ * @example <Title>Welcome</Title>
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/Title
  */
 export function Title({ level = "1", children, ...props }) {
     const Element = `h${level}`;

package/ui/block/Title.tsx

@@ -6,15 +6,35 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { HeadingProps } from "./Heading.js";
 import TITLE_CSS from "./Title.module.css";
 
+/**
+ * CSS class applied to the root element of every `Title`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TITLE_CLASS
+ */
 export const TITLE_CLASS = getModuleClass(TITLE_CSS, "title");
+
+/**
+ * CSS class that styles a `Title` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TITLE_PROSE_CLASS
+ */
 export const TITLE_PROSE_CLASS = getModuleClass(TITLE_CSS, "prose");
 
-/** Props for `Title` — identical to `HeadingProps`. */
+/**
+ * Props for `Title` — identical to `HeadingProps`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/TitleProps
+ */
 export type TitleProps = HeadingProps;
 
 /**
  * Page title — renders an `<h1>`.
  * - The most prominent heading on a page; there should normally be exactly one.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h1>` heading element.
+ * @example <Title>Welcome</Title>
+ * @see https://dhoulb.github.io/shelving/ui/block/Title/Title
  */
 export function Title({ level = "1", children, ...props }: TitleProps): ReactElement {
 	const Element: `h${typeof level}` = `h${level}`;