shelving 1.236.0 → 1.236.2

package/ui/block/Block.tsx

@@ -8,15 +8,37 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import BLOCK_CSS from "./Block.module.css";
 
+/**
+ * CSS class applied to the root element of every `Block`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Block/BLOCK_CLASS
+ */
 export const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
 
+/**
+ * Semantic element names a `Block` may render as via its `as` prop.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Block/BlockElement
+ */
 export type BlockElement = "div" | "section" | "header" | "footer" | "nav" | "aside" | "figure";
 
+/**
+ * Props for `Block` — colour, space, typography, and width variants plus an optional `as` element override.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Block/BlockProps
+ */
 export interface BlockProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
 	as?: BlockElement | undefined;
 }
 
-/** Plain `<div>` block with block-level spacing. */
+/**
+ * Plain `<div>` block with block-level spacing.
+ * - Pass `as` to render a different semantic element (`section`, `header`, `footer`, `nav`, `aside`, `figure`).
+ *
+ * @example <Block><Paragraph>Hello</Paragraph></Block>
+ * @example <Block as="aside" narrow><Paragraph>Sidebar</Paragraph></Block>
+ * @see https://dhoulb.github.io/shelving/ui/block/Block/Block
+ */
 export function Block({ as: Component = "div", children, ...props }: BlockProps): ReactElement {
 	return (
 		<Component

package/ui/block/Blockquote.d.ts

@@ -3,8 +3,29 @@ import { type ColorVariants } from "../style/Color.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * CSS class applied to the root `<blockquote>` element of every `Blockquote`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BLOCKQUOTE_CLASS
+ */
 export declare const BLOCKQUOTE_CLASS: string | undefined;
+/**
+ * CSS class that styles `<blockquote>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BLOCKQUOTE_PROSE_CLASS
+ */
 export declare const BLOCKQUOTE_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Blockquote` — colour, space, and typography variants plus optional children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BlockquoteProps
+ */
 export interface BlockquoteProps extends ColorVariants, SpaceVariants, TypographyVariants, OptionalChildProps {
 }
+/**
+ * Quoted block of text — rendered as `<blockquote>`.
+ *
+ * @example <Blockquote>To be or not to be.</Blockquote>
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/Blockquote
+ */
 export declare function Blockquote({ children, ...props }: BlockquoteProps): ReactElement;

package/ui/block/Blockquote.js

@@ -4,8 +4,24 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import BLOCKQUOTE_CSS from "./Blockquote.module.css";
+/**
+ * CSS class applied to the root `<blockquote>` element of every `Blockquote`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BLOCKQUOTE_CLASS
+ */
 export const BLOCKQUOTE_CLASS = getModuleClass(BLOCKQUOTE_CSS, "blockquote");
+/**
+ * CSS class that styles `<blockquote>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BLOCKQUOTE_PROSE_CLASS
+ */
 export const BLOCKQUOTE_PROSE_CLASS = getModuleClass(BLOCKQUOTE_CSS, "prose");
+/**
+ * Quoted block of text — rendered as `<blockquote>`.
+ *
+ * @example <Blockquote>To be or not to be.</Blockquote>
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/Blockquote
+ */
 export function Blockquote({ children, ...props }) {
     return (_jsx("blockquote", { className: getClass(BLOCKQUOTE_CLASS, //
         getColorClass(props), getSpaceClass(props), getTypographyClass(props)), children: children }));

package/ui/block/Blockquote.tsx

@@ -6,11 +6,33 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import BLOCKQUOTE_CSS from "./Blockquote.module.css";
 
+/**
+ * CSS class applied to the root `<blockquote>` element of every `Blockquote`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BLOCKQUOTE_CLASS
+ */
 export const BLOCKQUOTE_CLASS = getModuleClass(BLOCKQUOTE_CSS, "blockquote");
+
+/**
+ * CSS class that styles `<blockquote>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BLOCKQUOTE_PROSE_CLASS
+ */
 export const BLOCKQUOTE_PROSE_CLASS = getModuleClass(BLOCKQUOTE_CSS, "prose");
 
+/**
+ * Props for `Blockquote` — colour, space, and typography variants plus optional children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/BlockquoteProps
+ */
 export interface BlockquoteProps extends ColorVariants, SpaceVariants, TypographyVariants, OptionalChildProps {}
 
+/**
+ * Quoted block of text — rendered as `<blockquote>`.
+ *
+ * @example <Blockquote>To be or not to be.</Blockquote>
+ * @see https://dhoulb.github.io/shelving/ui/block/Blockquote/Blockquote
+ */
 export function Blockquote({ children, ...props }: BlockquoteProps): ReactElement {
 	return (
 		<blockquote

package/ui/block/Caption.d.ts

@@ -3,9 +3,29 @@ import { type ColorVariants } from "../style/Color.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/index.js";
+/**
+ * CSS class applied to the root `<figcaption>` element of every `Caption`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CAPTION_CLASS
+ */
 export declare const CAPTION_CLASS: string | undefined;
+/**
+ * CSS class that styles `<figcaption>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CAPTION_PROSE_CLASS
+ */
 export declare const CAPTION_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Caption` — colour, space, and typography variants plus optional children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CaptionProps
+ */
 export interface CaptionProps extends ColorVariants, SpaceVariants, TypographyVariants, OptionalChildProps {
 }
-/** `<figcaption>` block — caption text for a `<Figure>`. */
+/**
+ * `<figcaption>` block — caption text for a `<Figure>`.
+ *
+ * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/Caption
+ */
 export declare function Caption({ children, ...props }: CaptionProps): ReactElement;

package/ui/block/Caption.js

@@ -4,9 +4,24 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import CAPTION_CSS from "./Caption.module.css";
+/**
+ * CSS class applied to the root `<figcaption>` element of every `Caption`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CAPTION_CLASS
+ */
 export const CAPTION_CLASS = getModuleClass(CAPTION_CSS, "divider");
+/**
+ * CSS class that styles `<figcaption>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CAPTION_PROSE_CLASS
+ */
 export const CAPTION_PROSE_CLASS = getModuleClass(CAPTION_CSS, "prose");
-/** `<figcaption>` block — caption text for a `<Figure>`. */
+/**
+ * `<figcaption>` block — caption text for a `<Figure>`.
+ *
+ * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/Caption
+ */
 export function Caption({ children, ...props }) {
     return (_jsx("figcaption", { className: getClass(CAPTION_CLASS, //
         getColorClass(props), getSpaceClass(props), getTypographyClass(props)), children: children }));

package/ui/block/Caption.tsx

@@ -6,12 +6,33 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/index.js";
 import CAPTION_CSS from "./Caption.module.css";
 
+/**
+ * CSS class applied to the root `<figcaption>` element of every `Caption`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CAPTION_CLASS
+ */
 export const CAPTION_CLASS = getModuleClass(CAPTION_CSS, "divider");
+
+/**
+ * CSS class that styles `<figcaption>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CAPTION_PROSE_CLASS
+ */
 export const CAPTION_PROSE_CLASS = getModuleClass(CAPTION_CSS, "prose");
 
+/**
+ * Props for `Caption` — colour, space, and typography variants plus optional children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/CaptionProps
+ */
 export interface CaptionProps extends ColorVariants, SpaceVariants, TypographyVariants, OptionalChildProps {}
 
-/** `<figcaption>` block — caption text for a `<Figure>`. */
+/**
+ * `<figcaption>` block — caption text for a `<Figure>`.
+ *
+ * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
+ * @see https://dhoulb.github.io/shelving/ui/block/Caption/Caption
+ */
 export function Caption({ children, ...props }: CaptionProps): ReactElement {
 	return (
 		<figcaption

package/ui/block/Card.d.ts

@@ -6,6 +6,11 @@ import { type SpaceVariants } from "../style/Space.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
+/**
+ * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, and width variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Card/CardProps
+ */
 export interface CardProps extends ClickableProps, ColorVariants, StatusVariants, PaddingVariants, SpaceVariants, TypographyVariants, WidthVariants {
 }
 /**
@@ -17,5 +22,6 @@ export interface CardProps extends ClickableProps, ColorVariants, StatusVariants
  * @example <Card><Subheading>Static</Subheading></Card>
  * @example <Card href="/foo" title="Open foo"><Subheading>Clickable</Subheading></Card>
  * @example <Card status="error"><Subheading>Not found</Subheading></Card>
+ * @see https://dhoulb.github.io/shelving/ui/block/Card/Card
  */
 export declare function Card({ children, href, onClick, title, ...props }: CardProps): ReactElement;

package/ui/block/Card.js

@@ -17,6 +17,7 @@ import CARD_CSS from "./Card.module.css";
  * @example <Card><Subheading>Static</Subheading></Card>
  * @example <Card href="/foo" title="Open foo"><Subheading>Clickable</Subheading></Card>
  * @example <Card status="error"><Subheading>Not found</Subheading></Card>
+ * @see https://dhoulb.github.io/shelving/ui/block/Card/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

@@ -9,6 +9,11 @@ import { getWidthClass, type WidthVariants } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import CARD_CSS from "./Card.module.css";
 
+/**
+ * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, and width variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Card/CardProps
+ */
 export interface CardProps
 	extends ClickableProps,
 		ColorVariants,
@@ -27,6 +32,7 @@ export interface CardProps
  * @example <Card><Subheading>Static</Subheading></Card>
  * @example <Card href="/foo" title="Open foo"><Subheading>Clickable</Subheading></Card>
  * @example <Card status="error"><Subheading>Not found</Subheading></Card>
+ * @see https://dhoulb.github.io/shelving/ui/block/Card/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/Definitions.d.ts

@@ -4,13 +4,31 @@ import { type GapVariants } from "../style/Gap.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * CSS class applied to the root `<dl>` element of every `Definitions`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DEFINITIONS_CLASS
+ */
 export declare const DEFINITIONS_CLASS: string | undefined;
+/**
+ * CSS class that styles `<dl>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DEFINITIONS_PROSE_CLASS
+ */
 export declare const DEFINITIONS_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Definitions` — colour, gap, space, and typography variants plus optional children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DefinitionsProps
+ */
 export interface DefinitionsProps extends ColorVariants, GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {
 }
 /**
  * Description list — a sequence of term/value pairs rendered as a `<dl>`.
  * - Children are raw `<dt>` / `<dd>` elements — `<dt>` is the term label, `<dd>` the value, stacked term-above-value.
  * - The spacing between pairs is overridable via the `--definitions-gap` hook.
+ *
+ * @example <Definitions><dt>Name</dt><dd>Acme</dd></Definitions>
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/Definitions
  */
 export declare function Definitions({ children, ...props }: DefinitionsProps): ReactElement;

package/ui/block/Definitions.js

@@ -5,12 +5,25 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import DEFINITIONS_CSS from "./Definitions.module.css";
+/**
+ * CSS class applied to the root `<dl>` element of every `Definitions`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DEFINITIONS_CLASS
+ */
 export const DEFINITIONS_CLASS = getModuleClass(DEFINITIONS_CSS, "definitions");
+/**
+ * CSS class that styles `<dl>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DEFINITIONS_PROSE_CLASS
+ */
 export const DEFINITIONS_PROSE_CLASS = getModuleClass(DEFINITIONS_CSS, "prose");
 /**
  * Description list — a sequence of term/value pairs rendered as a `<dl>`.
  * - Children are raw `<dt>` / `<dd>` elements — `<dt>` is the term label, `<dd>` the value, stacked term-above-value.
  * - The spacing between pairs is overridable via the `--definitions-gap` hook.
+ *
+ * @example <Definitions><dt>Name</dt><dd>Acme</dd></Definitions>
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/Definitions
  */
 export function Definitions({ children, ...props }) {
     return (_jsx("dl", { className: getClass(DEFINITIONS_CLASS, //

package/ui/block/Definitions.tsx

@@ -7,15 +7,34 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import DEFINITIONS_CSS from "./Definitions.module.css";
 
+/**
+ * CSS class applied to the root `<dl>` element of every `Definitions`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DEFINITIONS_CLASS
+ */
 export const DEFINITIONS_CLASS = getModuleClass(DEFINITIONS_CSS, "definitions");
+
+/**
+ * CSS class that styles `<dl>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DEFINITIONS_PROSE_CLASS
+ */
 export const DEFINITIONS_PROSE_CLASS = getModuleClass(DEFINITIONS_CSS, "prose");
 
+/**
+ * Props for `Definitions` — colour, gap, space, and typography variants plus optional children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/DefinitionsProps
+ */
 export interface DefinitionsProps extends ColorVariants, GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {}
 
 /**
  * Description list — a sequence of term/value pairs rendered as a `<dl>`.
  * - Children are raw `<dt>` / `<dd>` elements — `<dt>` is the term label, `<dd>` the value, stacked term-above-value.
  * - The spacing between pairs is overridable via the `--definitions-gap` hook.
+ *
+ * @example <Definitions><dt>Name</dt><dd>Acme</dd></Definitions>
+ * @see https://dhoulb.github.io/shelving/ui/block/Definitions/Definitions
  */
 export function Definitions({ children, ...props }: DefinitionsProps): ReactElement {
 	return (

package/ui/block/Divider.d.ts

@@ -1,7 +1,28 @@
 import { type ColorVariants } from "../style/Color.js";
 import { type SpaceVariants } from "../style/Space.js";
+/**
+ * CSS class applied to the root `<hr>` element of every `Divider`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DIVIDER_CLASS
+ */
 export declare const DIVIDER_CLASS: string | undefined;
+/**
+ * CSS class that styles `<hr>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DIVIDER_PROSE_CLASS
+ */
 export declare const DIVIDER_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Divider` — space and colour variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DividerProps
+ */
 export interface DividerProps extends SpaceVariants, ColorVariants {
 }
+/**
+ * Horizontal rule separating blocks of content — rendered as `<hr>`.
+ *
+ * @example <Divider />
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/Divider
+ */
 export declare function Divider(props: DividerProps): import("react").JSX.Element;

package/ui/block/Divider.js

@@ -3,8 +3,24 @@ import { getColorClass } from "../style/Color.js";
 import { getSpaceClass } from "../style/Space.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import DIVIDER_CSS from "./Divider.module.css";
+/**
+ * CSS class applied to the root `<hr>` element of every `Divider`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DIVIDER_CLASS
+ */
 export const DIVIDER_CLASS = getModuleClass(DIVIDER_CSS, "divider");
+/**
+ * CSS class that styles `<hr>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DIVIDER_PROSE_CLASS
+ */
 export const DIVIDER_PROSE_CLASS = getModuleClass(DIVIDER_CSS, "prose");
+/**
+ * Horizontal rule separating blocks of content — rendered as `<hr>`.
+ *
+ * @example <Divider />
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/Divider
+ */
 export function Divider(props) {
     return (_jsx("hr", { className: getClass(DIVIDER_CLASS, //
         getSpaceClass(props), getColorClass(props)) }));

package/ui/block/Divider.tsx

@@ -3,11 +3,33 @@ import { getSpaceClass, type SpaceVariants } from "../style/Space.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import DIVIDER_CSS from "./Divider.module.css";
 
+/**
+ * CSS class applied to the root `<hr>` element of every `Divider`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DIVIDER_CLASS
+ */
 export const DIVIDER_CLASS = getModuleClass(DIVIDER_CSS, "divider");
+
+/**
+ * CSS class that styles `<hr>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DIVIDER_PROSE_CLASS
+ */
 export const DIVIDER_PROSE_CLASS = getModuleClass(DIVIDER_CSS, "prose");
 
+/**
+ * Props for `Divider` — space and colour variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/DividerProps
+ */
 export interface DividerProps extends SpaceVariants, ColorVariants {}
 
+/**
+ * Horizontal rule separating blocks of content — rendered as `<hr>`.
+ *
+ * @example <Divider />
+ * @see https://dhoulb.github.io/shelving/ui/block/Divider/Divider
+ */
 export function Divider(props: DividerProps) {
 	return (
 		<hr

package/ui/block/Heading.d.ts

@@ -3,9 +3,23 @@ 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 `Heading`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HEADING_CLASS
+ */
 export declare const HEADING_CLASS: string | undefined;
+/**
+ * CSS class that styles a `Heading` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HEADING_PROSE_CLASS
+ */
 export declare const HEADING_PROSE_CLASS: string | undefined;
-/** Props shared by `Title`, `Heading`, and `Subheading`. */
+/**
+ * Props shared by `Title`, `Heading`, and `Subheading` — colour, space, and typography variants plus a heading-level override.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HeadingProps
+ */
 export interface HeadingProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {
     /**
      * Heading level (`1`–`6`) — sets the rendered `<h1>`–`<h6>` tag.
@@ -16,5 +30,10 @@ export interface HeadingProps extends ColorVariants, SpaceVariants, TypographyVa
 /**
  * Section heading — renders an `<h2>`.
  * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h2>` heading element.
+ * @example <Heading>Section title</Heading>
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/Heading
  */
 export declare function Heading({ level, children, ...props }: HeadingProps): ReactElement;

package/ui/block/Heading.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 HEADING_CSS from "./Heading.module.css";
+/**
+ * CSS class applied to the root element of every `Heading`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HEADING_CLASS
+ */
 export const HEADING_CLASS = getModuleClass(HEADING_CSS, "heading");
+/**
+ * CSS class that styles a `Heading` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HEADING_PROSE_CLASS
+ */
 export const HEADING_PROSE_CLASS = getModuleClass(HEADING_CSS, "prose");
 /**
  * Section heading — renders an `<h2>`.
  * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h2>` heading element.
+ * @example <Heading>Section title</Heading>
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/Heading
  */
 export function Heading({ level = "2", children, ...props }) {
     const Element = `h${level}`;

package/ui/block/Heading.tsx

@@ -6,10 +6,25 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { ChildProps } from "../util/props.js";
 import HEADING_CSS from "./Heading.module.css";
 
+/**
+ * CSS class applied to the root element of every `Heading`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HEADING_CLASS
+ */
 export const HEADING_CLASS = getModuleClass(HEADING_CSS, "heading");
+
+/**
+ * CSS class that styles a `Heading` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HEADING_PROSE_CLASS
+ */
 export const HEADING_PROSE_CLASS = getModuleClass(HEADING_CSS, "prose");
 
-/** Props shared by `Title`, `Heading`, and `Subheading`. */
+/**
+ * Props shared by `Title`, `Heading`, and `Subheading` — colour, space, and typography variants plus a heading-level override.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/HeadingProps
+ */
 export interface HeadingProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {
 	/**
 	 * Heading level (`1`–`6`) — sets the rendered `<h1>`–`<h6>` tag.
@@ -21,6 +36,11 @@ export interface HeadingProps extends ColorVariants, SpaceVariants, TypographyVa
 /**
  * Section heading — renders an `<h2>`.
  * - Sits between `Title` (`<h1>`) and `Subheading` (`<h3>`) in the heading hierarchy.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h2>` heading element.
+ * @example <Heading>Section title</Heading>
+ * @see https://dhoulb.github.io/shelving/ui/block/Heading/Heading
  */
 export function Heading({ level = "2", children, ...props }: HeadingProps): ReactElement {
 	const Element: `h${typeof level}` = `h${level}`;

package/ui/block/Image.d.ts

@@ -1,10 +1,33 @@
 import type { ReactElement } from "react";
 import { type SpaceVariants } from "../style/Space.js";
 import { type WidthVariants } from "../style/Width.js";
+/**
+ * CSS class applied to the root element of every `Image`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Image/IMAGE_CLASS
+ */
 export declare const IMAGE_CLASS: string | undefined;
+/**
+ * CSS class that styles an `Image` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Image/IMAGE_PROSE_CLASS
+ */
 export declare const IMAGE_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Image` — an `src`, optional `alt` text, plus space and width variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Image/ImageProps
+ */
 export interface ImageProps extends SpaceVariants, WidthVariants {
     src: string;
     alt?: string;
 }
+/**
+ * Image block — renders an `<img>` with space and width variants applied.
+ *
+ * @param props The image `src`, optional `alt` text, plus space and width variants.
+ * @returns Rendered `<img>` element.
+ * @example <Image src="/logo.png" alt="Logo" width="medium" />
+ * @see https://dhoulb.github.io/shelving/ui/block/Image/Image
+ */
 export declare function Image({ src, alt, ...variants }: ImageProps): ReactElement;

package/ui/block/Image.js

@@ -3,8 +3,26 @@ import { getSpaceClass } from "../style/Space.js";
 import { getWidthClass } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import styles from "./Image.module.css";
+/**
+ * CSS class applied to the root element of every `Image`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Image/IMAGE_CLASS
+ */
 export const IMAGE_CLASS = getModuleClass(styles, "image");
+/**
+ * CSS class that styles an `Image` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Image/IMAGE_PROSE_CLASS
+ */
 export const IMAGE_PROSE_CLASS = getModuleClass(styles, "prose");
+/**
+ * Image block — renders an `<img>` with space and width variants applied.
+ *
+ * @param props The image `src`, optional `alt` text, plus space and width variants.
+ * @returns Rendered `<img>` element.
+ * @example <Image src="/logo.png" alt="Logo" width="medium" />
+ * @see https://dhoulb.github.io/shelving/ui/block/Image/Image
+ */
 export function Image({ src, alt, ...variants }) {
     return _jsx("img", { src: src, alt: alt, className: getClass(IMAGE_CLASS, getSpaceClass(variants), getWidthClass(variants)) });
 }