shelving 1.236.0 → 1.236.2

package/ui/block/Image.tsx

@@ -4,14 +4,38 @@ import { getWidthClass, type WidthVariants } 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");
 
+/**
+ * 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 function Image({ src, alt, ...variants }: ImageProps): ReactElement {
 	return <img src={src} alt={alt} className={getClass(IMAGE_CLASS, getSpaceClass(variants), getWidthClass(variants))} />;
 }

package/ui/block/Label.d.ts

@@ -1,11 +1,26 @@
 import type { ReactElement } from "react";
 import type { SubheadingProps } from "./Subheading.js";
+/**
+ * CSS class applied to the root element of every `Label`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/LABEL_CLASS
+ */
 export declare const LABEL_CLASS: string | undefined;
+/**
+ * Props for `Label` — identical to `SubheadingProps`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/LabelProps
+ */
 export interface LabelProps extends SubheadingProps {
 }
 /**
- * Label heading, a `<h3>` with a labelly apperance (UPPERCASE but with a smaller text size).
- * - This is the default style used by things like a `<th>` from a `<table>`
- * - Default text properties for all of these can be controlled with global variables: `--size-label`, `--font-label`, `--case-label`
+ * Label heading, a `<h3>` with a labelly appearance (UPPERCASE but with a smaller text size).
+ * - This is the default style used by things like a `<th>` from a `<table>`.
+ * - Default text properties for all of these can be controlled with global variables: `--size-label`, `--font-label`, `--case-label`.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h3>` label heading element.
+ * @example <Label>Email address</Label>
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/Label
  */
 export declare function Label({ level, children, ...props }: LabelProps): ReactElement;

package/ui/block/Label.js

@@ -4,11 +4,21 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import LABEL_CSS from "./Label.module.css";
+/**
+ * CSS class applied to the root element of every `Label`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/LABEL_CLASS
+ */
 export const LABEL_CLASS = getModuleClass(LABEL_CSS, "label");
 /**
- * Label heading, a `<h3>` with a labelly apperance (UPPERCASE but with a smaller text size).
- * - This is the default style used by things like a `<th>` from a `<table>`
- * - Default text properties for all of these can be controlled with global variables: `--size-label`, `--font-label`, `--case-label`
+ * Label heading, a `<h3>` with a labelly appearance (UPPERCASE but with a smaller text size).
+ * - This is the default style used by things like a `<th>` from a `<table>`.
+ * - Default text properties for all of these can be controlled with global variables: `--size-label`, `--font-label`, `--case-label`.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h3>` label heading element.
+ * @example <Label>Email address</Label>
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/Label
  */
 export function Label({ level = "3", children, ...props }) {
     const Element = `h${level}`;

package/ui/block/Label.tsx

@@ -6,14 +6,29 @@ import { getClass, getModuleClass } from "../util/css.js";
 import LABEL_CSS from "./Label.module.css";
 import type { SubheadingProps } from "./Subheading.js";
 
+/**
+ * CSS class applied to the root element of every `Label`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/LABEL_CLASS
+ */
 export const LABEL_CLASS = getModuleClass(LABEL_CSS, "label");
 
+/**
+ * Props for `Label` — identical to `SubheadingProps`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/LabelProps
+ */
 export interface LabelProps extends SubheadingProps {}
 
 /**
- * Label heading, a `<h3>` with a labelly apperance (UPPERCASE but with a smaller text size).
- * - This is the default style used by things like a `<th>` from a `<table>`
- * - Default text properties for all of these can be controlled with global variables: `--size-label`, `--font-label`, `--case-label`
+ * Label heading, a `<h3>` with a labelly appearance (UPPERCASE but with a smaller text size).
+ * - This is the default style used by things like a `<th>` from a `<table>`.
+ * - Default text properties for all of these can be controlled with global variables: `--size-label`, `--font-label`, `--case-label`.
+ *
+ * @param props Colour, space, and typography variants plus an optional `level` override and `children`.
+ * @returns Rendered `<h3>` label heading element.
+ * @example <Label>Email address</Label>
+ * @see https://dhoulb.github.io/shelving/ui/block/Label/Label
  */
 export function Label({ level = "3", children, ...props }: LabelProps): ReactElement {
 	const Element: `h${typeof level}` = `h${level}`;

package/ui/block/List.d.ts

@@ -3,11 +3,41 @@ import { type ColorVariants } from "../style/Color.js";
 import { type GapVariants } from "../style/Gap.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
+/**
+ * CSS class applied to an ordered `List` (`<ol>`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_ORDERED_CLASS
+ */
 export declare const LIST_ORDERED_CLASS: string | undefined;
+/**
+ * CSS class applied to an unordered `List` (`<ul>`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_UNORDERED_CLASS
+ */
 export declare const LIST_UNORDERED_CLASS: string | undefined;
+/**
+ * CSS class that styles a `List` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_PROSE_CLASS
+ */
 export declare const LIST_PROSE_CLASS: string | undefined;
+/**
+ * Props for `List` — colour, gap, space, and typography variants plus its list items and an `ordered` toggle.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/ListProps
+ */
 export interface ListProps extends ColorVariants, GapVariants, SpaceVariants, TypographyVariants {
     children: ReactNode[];
     ordered?: boolean;
 }
+/**
+ * List block — wraps each child in an `<li>` and renders an `<ul>` or `<ol>`.
+ * - Pass `ordered` to render an ordered `<ol>` instead of the default unordered `<ul>`.
+ *
+ * @param props Colour, gap, space, and typography variants plus the `children` items and `ordered` toggle.
+ * @returns Rendered `<ul>` or `<ol>` list element.
+ * @example <List>{["One", "Two", "Three"]}</List>
+ * @example <List ordered>{["First", "Second"]}</List>
+ * @see https://dhoulb.github.io/shelving/ui/block/List/List
+ */
 export declare function List({ children, ordered, ...props }: ListProps): ReactElement;

package/ui/block/List.js

@@ -5,9 +5,34 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import LIST_CSS from "./List.module.css";
+/**
+ * CSS class applied to an ordered `List` (`<ol>`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_ORDERED_CLASS
+ */
 export const LIST_ORDERED_CLASS = getModuleClass(LIST_CSS, "ordered");
+/**
+ * CSS class applied to an unordered `List` (`<ul>`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_UNORDERED_CLASS
+ */
 export const LIST_UNORDERED_CLASS = getModuleClass(LIST_CSS, "unordered");
+/**
+ * CSS class that styles a `List` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_PROSE_CLASS
+ */
 export const LIST_PROSE_CLASS = getModuleClass(LIST_CSS, "prose");
+/**
+ * List block — wraps each child in an `<li>` and renders an `<ul>` or `<ol>`.
+ * - Pass `ordered` to render an ordered `<ol>` instead of the default unordered `<ul>`.
+ *
+ * @param props Colour, gap, space, and typography variants plus the `children` items and `ordered` toggle.
+ * @returns Rendered `<ul>` or `<ol>` list element.
+ * @example <List>{["One", "Two", "Three"]}</List>
+ * @example <List ordered>{["First", "Second"]}</List>
+ * @see https://dhoulb.github.io/shelving/ui/block/List/List
+ */
 export function List({ children, ordered = false, ...props }) {
     const items = children.map((v, i) => _jsx("li", { children: v }, i.toString()));
     const className = getClass(ordered ? LIST_ORDERED_CLASS : LIST_UNORDERED_CLASS, getColorClass(props), getGapClass(props), getSpaceClass(props), getTypographyClass(props));

package/ui/block/List.tsx

@@ -6,15 +6,47 @@ import { getTypographyClass, type TypographyVariants } from "../style/Typography
 import { getClass, getModuleClass } from "../util/css.js";
 import LIST_CSS from "./List.module.css";
 
+/**
+ * CSS class applied to an ordered `List` (`<ol>`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_ORDERED_CLASS
+ */
 export const LIST_ORDERED_CLASS = getModuleClass(LIST_CSS, "ordered");
+
+/**
+ * CSS class applied to an unordered `List` (`<ul>`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_UNORDERED_CLASS
+ */
 export const LIST_UNORDERED_CLASS = getModuleClass(LIST_CSS, "unordered");
+
+/**
+ * CSS class that styles a `List` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/LIST_PROSE_CLASS
+ */
 export const LIST_PROSE_CLASS = getModuleClass(LIST_CSS, "prose");
 
+/**
+ * Props for `List` — colour, gap, space, and typography variants plus its list items and an `ordered` toggle.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/List/ListProps
+ */
 export interface ListProps extends ColorVariants, GapVariants, SpaceVariants, TypographyVariants {
 	children: ReactNode[];
 	ordered?: boolean;
 }
 
+/**
+ * List block — wraps each child in an `<li>` and renders an `<ul>` or `<ol>`.
+ * - Pass `ordered` to render an ordered `<ol>` instead of the default unordered `<ul>`.
+ *
+ * @param props Colour, gap, space, and typography variants plus the `children` items and `ordered` toggle.
+ * @returns Rendered `<ul>` or `<ol>` list element.
+ * @example <List>{["One", "Two", "Three"]}</List>
+ * @example <List ordered>{["First", "Second"]}</List>
+ * @see https://dhoulb.github.io/shelving/ui/block/List/List
+ */
 export function List({ children, ordered = false, ...props }: ListProps): ReactElement {
 	const items = children.map((v, i) => <li key={i.toString()}>{v}</li>);
 	const className = getClass(

package/ui/block/Panel.d.ts

@@ -3,8 +3,17 @@ import { type ColorVariants } from "../style/Color.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/props.js";
-/** Allowed semantic elements for a `<Panel>`. */
+/**
+ * Allowed semantic elements for a `<Panel>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelElement
+ */
 export type PanelElement = "section" | "header" | "footer" | "nav" | "aside" | "article" | "div";
+/**
+ * Props for `Panel` — colour, status, and typography variants plus optional `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelProps
+ */
 export interface PanelProps extends ColorVariants, StatusVariants, TypographyVariants, OptionalChildProps {
 }
 /**
@@ -14,7 +23,10 @@ export interface PanelProps extends ColorVariants, StatusVariants, TypographyVar
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
+ * @param props Colour, status, and typography variants plus `children`.
+ * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
  * @example <Panel as="header" color="primary"><Title>Welcome</Title></Panel>
+ * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
 export declare function Panel({ children, ...props }: PanelProps): ReactElement;

package/ui/block/Panel.js

@@ -12,8 +12,11 @@ const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
+ * @param props Colour, status, and typography variants plus `children`.
+ * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
  * @example <Panel as="header" color="primary"><Title>Welcome</Title></Panel>
+ * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
 export function Panel({ children, ...props }) {
     return (_jsx("div", { className: getClass(PANEL_CLASS, //

package/ui/block/Panel.tsx

@@ -8,9 +8,18 @@ import PANEL_CSS from "./Panel.module.css";
 
 const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
 
-/** Allowed semantic elements for a `<Panel>`. */
+/**
+ * Allowed semantic elements for a `<Panel>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelElement
+ */
 export type PanelElement = "section" | "header" | "footer" | "nav" | "aside" | "article" | "div";
 
+/**
+ * Props for `Panel` — colour, status, and typography variants plus optional `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelProps
+ */
 export interface PanelProps extends ColorVariants, StatusVariants, TypographyVariants, OptionalChildProps {}
 
 /**
@@ -20,8 +29,11 @@ export interface PanelProps extends ColorVariants, StatusVariants, TypographyVar
  *
  * Renders as a `<section>` by default; pass `as="header"` etc. for other semantic elements.
  *
+ * @param props Colour, status, and typography variants plus `children`.
+ * @returns Rendered full-width panel region.
  * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
  * @example <Panel as="header" color="primary"><Title>Welcome</Title></Panel>
+ * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
 export function Panel({ children, ...props }: PanelProps): ReactElement {
 	return (

package/ui/block/Paragraph.d.ts

@@ -3,8 +3,31 @@ 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 element of every `Paragraph`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/PARAGRAPH_CLASS
+ */
 export declare const PARAGRAPH_CLASS: string | undefined;
+/**
+ * CSS class that styles a `Paragraph` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/PARAGRAPH_PROSE_CLASS
+ */
 export declare const PARAGRAPH_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Paragraph` — colour, space, and typography variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/ParagraphProps
+ */
 export interface ParagraphProps extends ColorVariants, SpaceVariants, TypographyVariants, OptionalChildProps {
 }
+/**
+ * Paragraph block of body text — rendered as `<p>`.
+ *
+ * @param props Colour, space, and typography variants plus `children`.
+ * @returns Rendered `<p>` paragraph element.
+ * @example <Paragraph>Hello world.</Paragraph>
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/Paragraph
+ */
 export declare function Paragraph({ children, ...props }: ParagraphProps): ReactElement;

package/ui/block/Paragraph.js

@@ -4,8 +4,26 @@ import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import PARAGRAPH_CSS from "./Paragraph.module.css";
+/**
+ * CSS class applied to the root element of every `Paragraph`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/PARAGRAPH_CLASS
+ */
 export const PARAGRAPH_CLASS = getModuleClass(PARAGRAPH_CSS, "paragraph");
+/**
+ * CSS class that styles a `Paragraph` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/PARAGRAPH_PROSE_CLASS
+ */
 export const PARAGRAPH_PROSE_CLASS = getModuleClass(PARAGRAPH_CSS, "prose");
+/**
+ * Paragraph block of body text — rendered as `<p>`.
+ *
+ * @param props Colour, space, and typography variants plus `children`.
+ * @returns Rendered `<p>` paragraph element.
+ * @example <Paragraph>Hello world.</Paragraph>
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/Paragraph
+ */
 export function Paragraph({ children, ...props }) {
     return (_jsx("p", { className: getClass(PARAGRAPH_CLASS, //
         getColorClass(props), getSpaceClass(props), getTypographyClass(props)), children: children }));

package/ui/block/Paragraph.tsx

@@ -6,11 +6,35 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import PARAGRAPH_CSS from "./Paragraph.module.css";
 
+/**
+ * CSS class applied to the root element of every `Paragraph`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/PARAGRAPH_CLASS
+ */
 export const PARAGRAPH_CLASS = getModuleClass(PARAGRAPH_CSS, "paragraph");
+
+/**
+ * CSS class that styles a `Paragraph` when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/PARAGRAPH_PROSE_CLASS
+ */
 export const PARAGRAPH_PROSE_CLASS = getModuleClass(PARAGRAPH_CSS, "prose");
 
+/**
+ * Props for `Paragraph` — colour, space, and typography variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/ParagraphProps
+ */
 export interface ParagraphProps extends ColorVariants, SpaceVariants, TypographyVariants, OptionalChildProps {}
 
+/**
+ * Paragraph block of body text — rendered as `<p>`.
+ *
+ * @param props Colour, space, and typography variants plus `children`.
+ * @returns Rendered `<p>` paragraph element.
+ * @example <Paragraph>Hello world.</Paragraph>
+ * @see https://dhoulb.github.io/shelving/ui/block/Paragraph/Paragraph
+ */
 export function Paragraph({ children, ...props }: ParagraphProps): ReactElement {
 	return (
 		<p

package/ui/block/Preformatted.d.ts

@@ -5,8 +5,23 @@ 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 `Preformatted` block.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PREFORMATTED_CLASS
+ */
 export declare const PREFORMATTED_CLASS: string | undefined;
+/**
+ * CSS class that styles a `Preformatted` block when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PREFORMATTED_PROSE_CLASS
+ */
 export declare const PREFORMATTED_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Preformatted` — space, colour, typography, width, and padding variants plus a `wrap` toggle.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PreformattedProps
+ */
 export interface PreformattedProps extends SpaceVariants, ColorVariants, TypographyVariants, WidthVariants, PaddingVariants, OptionalChildProps {
     /** Enable line wrapping (default is nowrap). */
     wrap?: boolean | undefined;
@@ -15,5 +30,10 @@ export interface PreformattedProps extends SpaceVariants, ColorVariants, Typogra
  * Preformatted block of text — rendered as `<pre>`.
  * - Lines are not wrapped by default — overflowing content scrolls horizontally within the block.
  * - Pass `wrap` to wrap long lines instead; newlines and indentation are preserved either way.
+ *
+ * @param props Space, colour, typography, width, and padding variants plus the `wrap` toggle and `children`.
+ * @returns Rendered `<pre>` element.
+ * @example <Preformatted>{"line one\nline two"}</Preformatted>
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/Preformatted
  */
 export declare function Preformatted({ children, ...variants }: PreformattedProps): ReactElement;

package/ui/block/Preformatted.js

@@ -6,12 +6,27 @@ import { getTypographyClass } from "../style/Typography.js";
 import { getWidthClass } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import PREFORMATTED_CSS from "./Preformatted.module.css";
+/**
+ * CSS class applied to the root element of every `Preformatted` block.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PREFORMATTED_CLASS
+ */
 export const PREFORMATTED_CLASS = getModuleClass(PREFORMATTED_CSS, "preformatted");
+/**
+ * CSS class that styles a `Preformatted` block when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PREFORMATTED_PROSE_CLASS
+ */
 export const PREFORMATTED_PROSE_CLASS = getModuleClass(PREFORMATTED_CSS, "prose");
 /**
  * Preformatted block of text — rendered as `<pre>`.
  * - Lines are not wrapped by default — overflowing content scrolls horizontally within the block.
  * - Pass `wrap` to wrap long lines instead; newlines and indentation are preserved either way.
+ *
+ * @param props Space, colour, typography, width, and padding variants plus the `wrap` toggle and `children`.
+ * @returns Rendered `<pre>` element.
+ * @example <Preformatted>{"line one\nline two"}</Preformatted>
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/Preformatted
  */
 export function Preformatted({ children, ...variants }) {
     return (_jsx("pre", { className: getClass(getModuleClass(PREFORMATTED_CSS, "preformatted", variants), //

package/ui/block/Preformatted.tsx

@@ -8,9 +8,25 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import PREFORMATTED_CSS from "./Preformatted.module.css";
 
+/**
+ * CSS class applied to the root element of every `Preformatted` block.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PREFORMATTED_CLASS
+ */
 export const PREFORMATTED_CLASS = getModuleClass(PREFORMATTED_CSS, "preformatted");
+
+/**
+ * CSS class that styles a `Preformatted` block when it appears inside `Prose` longform content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PREFORMATTED_PROSE_CLASS
+ */
 export const PREFORMATTED_PROSE_CLASS = getModuleClass(PREFORMATTED_CSS, "prose");
 
+/**
+ * Props for `Preformatted` — space, colour, typography, width, and padding variants plus a `wrap` toggle.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/PreformattedProps
+ */
 export interface PreformattedProps
 	extends SpaceVariants,
 		ColorVariants,
@@ -26,6 +42,11 @@ export interface PreformattedProps
  * Preformatted block of text — rendered as `<pre>`.
  * - Lines are not wrapped by default — overflowing content scrolls horizontally within the block.
  * - Pass `wrap` to wrap long lines instead; newlines and indentation are preserved either way.
+ *
+ * @param props Space, colour, typography, width, and padding variants plus the `wrap` toggle and `children`.
+ * @returns Rendered `<pre>` element.
+ * @example <Preformatted>{"line one\nline two"}</Preformatted>
+ * @see https://dhoulb.github.io/shelving/ui/block/Preformatted/Preformatted
  */
 export function Preformatted({ children, ...variants }: PreformattedProps): ReactElement {
 	return (

package/ui/block/Prose.d.ts

@@ -1,6 +1,19 @@
 import type { ReactElement } from "react";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `Prose` — just the longform `children` to style.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Prose/ProseProps
+ */
 export interface ProseProps extends OptionalChildProps {
 }
-/** A section of longform text containing lots of `<p>` or `<ul>` style elements. */
+/**
+ * A section of longform text containing lots of `<p>` or `<ul>` style elements.
+ * - Applies the prose variant of every block and inline component so nested content picks up the right longform spacing and typography.
+ *
+ * @param props The longform `children` to render inside the prose container.
+ * @returns Rendered `<div>` wrapping the prose content.
+ * @example <Prose><Paragraph>First.</Paragraph><Paragraph>Second.</Paragraph></Prose>
+ * @see https://dhoulb.github.io/shelving/ui/block/Prose/Prose
+ */
 export declare function Prose({ children }: ProseProps): ReactElement;

package/ui/block/Prose.js

@@ -25,7 +25,15 @@ import { SUBHEADING_PROSE_CLASS } from "./Subheading.js";
 import { TABLE_PROSE_CLASS } from "./Table.js";
 import { TITLE_PROSE_CLASS } from "./Title.js";
 const PROSE_STYLES = getClass(PARAGRAPH_PROSE_CLASS, HEADING_PROSE_CLASS, SUBHEADING_PROSE_CLASS, ADDRESS_PROSE_CLASS, BLOCKQUOTE_PROSE_CLASS, SECTION_PROSE_CLASS, CODE_PROSE_CLASS, DEFINITIONS_PROSE_CLASS, DELETED_PROSE_CLASS, EMPHASIS_PROSE_CLASS, IMAGE_PROSE_CLASS, INSERTED_PROSE_CLASS, CAPTION_PROSE_CLASS, LIST_PROSE_CLASS, TITLE_PROSE_CLASS, LINK_PROSE_CLASS, MARK_PROSE_CLASS, PREFORMATTED_PROSE_CLASS, SMALL_PROSE_CLASS, STRONG_PROSE_CLASS, SUBSCRIPT_PROSE_CLASS, SUPERSCRIPT_PROSE_CLASS, TABLE_PROSE_CLASS, DIVIDER_PROSE_CLASS);
-/** A section of longform text containing lots of `<p>` or `<ul>` style elements. */
+/**
+ * A section of longform text containing lots of `<p>` or `<ul>` style elements.
+ * - Applies the prose variant of every block and inline component so nested content picks up the right longform spacing and typography.
+ *
+ * @param props The longform `children` to render inside the prose container.
+ * @returns Rendered `<div>` wrapping the prose content.
+ * @example <Prose><Paragraph>First.</Paragraph><Paragraph>Second.</Paragraph></Prose>
+ * @see https://dhoulb.github.io/shelving/ui/block/Prose/Prose
+ */
 export function Prose({ children }) {
     return _jsx("div", { className: PROSE_STYLES, children: children });
 }

package/ui/block/Prose.tsx

@@ -53,9 +53,22 @@ const PROSE_STYLES = getClass(
 	DIVIDER_PROSE_CLASS,
 );
 
+/**
+ * Props for `Prose` — just the longform `children` to style.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Prose/ProseProps
+ */
 export interface ProseProps extends OptionalChildProps {}
 
-/** A section of longform text containing lots of `<p>` or `<ul>` style elements. */
+/**
+ * A section of longform text containing lots of `<p>` or `<ul>` style elements.
+ * - Applies the prose variant of every block and inline component so nested content picks up the right longform spacing and typography.
+ *
+ * @param props The longform `children` to render inside the prose container.
+ * @returns Rendered `<div>` wrapping the prose content.
+ * @example <Prose><Paragraph>First.</Paragraph><Paragraph>Second.</Paragraph></Prose>
+ * @see https://dhoulb.github.io/shelving/ui/block/Prose/Prose
+ */
 export function Prose({ children }: ProseProps): ReactElement {
 	return <div className={PROSE_STYLES}>{children}</div>;
 }