shelving 1.236.0 → 1.236.2

package/test/basics.js

@@ -4,6 +4,11 @@ import { CHOICE } from "../schema/ChoiceSchema.js";
 import { DATA } from "../schema/DataSchema.js";
 import { NUMBER } from "../schema/NumberSchema.js";
 import { STRING } from "../schema/StringSchema.js";
+/**
+ * Schema for a test "basic" fixture, exercising string, number, choice, array, boolean, and nested-data props.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/BASIC_SCHEMA
+ */
 export const BASIC_SCHEMA = DATA({
     str: STRING,
     num: NUMBER,
@@ -13,6 +18,11 @@ export const BASIC_SCHEMA = DATA({
     even: BOOLEAN,
     sub: DATA({ str: STRING, num: NUMBER, odd: BOOLEAN, even: BOOLEAN }),
 });
+/**
+ * Test basic fixture: `str: "aaa"`, `num: 100`, group `a`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic1
+ */
 export const basic1 = {
     id: "basic1",
     str: "aaa",
@@ -23,6 +33,11 @@ export const basic1 = {
     tags: ["odd", "prime"],
     sub: { str: "aaa", num: 100, even: false, odd: true },
 };
+/**
+ * Test basic fixture: `str: "bbb"`, `num: 200`, group `a`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic2
+ */
 export const basic2 = {
     id: "basic2",
     str: "bbb",
@@ -33,6 +48,11 @@ export const basic2 = {
     tags: ["even", "prime"],
     sub: { str: "bbb", num: 200, even: true, odd: false },
 };
+/**
+ * Test basic fixture: `str: "ccc"`, `num: 300`, group `a`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic3
+ */
 export const basic3 = {
     id: "basic3",
     str: "ccc",
@@ -43,6 +63,11 @@ export const basic3 = {
     tags: ["odd", "prime"],
     sub: { str: "ccc", num: 300, even: false, odd: true },
 };
+/**
+ * Test basic fixture: `str: "ddd"`, `num: 400`, group `b`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic4
+ */
 export const basic4 = {
     id: "basic4",
     str: "ddd",
@@ -53,6 +78,11 @@ export const basic4 = {
     tags: ["even"],
     sub: { str: "ddd", num: 400, even: true, odd: false },
 };
+/**
+ * Test basic fixture: `str: "eee"`, `num: 500`, group `b`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic5
+ */
 export const basic5 = {
     id: "basic5",
     str: "eee",
@@ -63,6 +93,11 @@ export const basic5 = {
     tags: ["odd", "prime"],
     sub: { str: "eee", num: 500, even: false, odd: true },
 };
+/**
+ * Test basic fixture: `str: "fff"`, `num: 600`, group `b`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic6
+ */
 export const basic6 = {
     id: "basic6",
     str: "fff",
@@ -73,6 +108,11 @@ export const basic6 = {
     tags: ["even"],
     sub: { str: "fff", num: 600, even: true, odd: false },
 };
+/**
+ * Test basic fixture: `str: "ggg"`, `num: 700`, group `c`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic7
+ */
 export const basic7 = {
     id: "basic7",
     str: "ggg",
@@ -83,6 +123,11 @@ export const basic7 = {
     tags: ["odd", "prime"],
     sub: { str: "ggg", num: 700, even: false, odd: true },
 };
+/**
+ * Test basic fixture: `str: "hhh"`, `num: 800`, group `c`, even.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic8
+ */
 export const basic8 = {
     id: "basic8",
     str: "hhh",
@@ -93,6 +138,11 @@ export const basic8 = {
     tags: ["even"],
     sub: { str: "hhh", num: 800, even: true, odd: false },
 };
+/**
+ * Test basic fixture: `str: "iii"`, `num: 900`, group `c`, odd.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic9
+ */
 export const basic9 = {
     id: "basic9",
     str: "iii",
@@ -103,7 +153,17 @@ export const basic9 = {
     tags: ["odd"],
     sub: { str: "iii", num: 900, even: false, odd: true },
 };
+/**
+ * Array of all nine test basic fixtures in a deliberately shuffled order, for exercising sort/query behaviour.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basics
+ */
 export const basics = [basic3, basic5, basic7, basic4, basic1, basic2, basic8, basic6, basic9];
+/**
+ * Standalone test basic data (no `id`): `str: "zzz"`, `num: 999`, for use as new/unsaved data.
+ *
+ * @see https://dhoulb.github.io/shelving/test/basics/basic999
+ */
 export const basic999 = {
     str: "zzz",
     num: 999,

package/test/people.d.ts

@@ -1,5 +1,10 @@
 import type { Item } from "../util/item.js";
 import type { ValidatorType } from "../util/validate.js";
+/**
+ * Schema for a test "person" fixture, with a nested `name` and a nullable `birthday`.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/PERSON_SCHEMA
+ */
 export declare const PERSON_SCHEMA: import("../schema/DataSchema.js").DataSchema<{
     name: {
         first: /*elided*/ any;
@@ -7,11 +12,51 @@ export declare const PERSON_SCHEMA: import("../schema/DataSchema.js").DataSchema
     };
     birthday: string | null;
 }>;
+/**
+ * Validated data shape of a test person, inferred from `PERSON_SCHEMA`.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/PersonData
+ */
 export type PersonData = ValidatorType<typeof PERSON_SCHEMA>;
+/**
+ * A test person as a stored `Item` — `PersonData` plus a string `id`.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/PersonItem
+ */
 export type PersonItem = Item<string, PersonData>;
+/**
+ * Test person fixture: Dave Brook, born 1985-12-06.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person1
+ */
 export declare const person1: PersonItem;
+/**
+ * Test person fixture: Sally Callister, born 1973-11-19.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person2
+ */
 export declare const person2: PersonItem;
+/**
+ * Test person fixture: Sammy Canister, with no birthday (`null`).
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person3
+ */
 export declare const person3: PersonItem;
+/**
+ * Test person fixture: Jilly Jones, with no birthday (`null`).
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person4
+ */
 export declare const person4: PersonItem;
+/**
+ * Test person fixture: Terry Times, born 1964-08-01.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person5
+ */
 export declare const person5: PersonItem;
+/**
+ * Ordered array of all five test person fixtures (`person1` through `person5`).
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/people
+ */
 export declare const people: ReadonlyArray<PersonItem>;

package/test/people.js

@@ -1,13 +1,48 @@
 import { DATA } from "../schema/DataSchema.js";
 import { NULLABLE_DATE } from "../schema/DateSchema.js";
 import { REQUIRED_STRING } from "../schema/StringSchema.js";
+/**
+ * Schema for a test "person" fixture, with a nested `name` and a nullable `birthday`.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/PERSON_SCHEMA
+ */
 export const PERSON_SCHEMA = DATA({
     name: DATA({ first: REQUIRED_STRING, last: REQUIRED_STRING }),
     birthday: NULLABLE_DATE,
 });
+/**
+ * Test person fixture: Dave Brook, born 1985-12-06.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person1
+ */
 export const person1 = { id: "person1", name: { first: "Dave", last: "Brook" }, birthday: "1985-12-06" };
+/**
+ * Test person fixture: Sally Callister, born 1973-11-19.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person2
+ */
 export const person2 = { id: "person2", name: { first: "Sally", last: "Callister" }, birthday: "1973-11-19" };
+/**
+ * Test person fixture: Sammy Canister, with no birthday (`null`).
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person3
+ */
 export const person3 = { id: "person3", name: { first: "Sammy", last: "Canister" }, birthday: null };
+/**
+ * Test person fixture: Jilly Jones, with no birthday (`null`).
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person4
+ */
 export const person4 = { id: "person4", name: { first: "Jilly", last: "Jones" }, birthday: null };
+/**
+ * Test person fixture: Terry Times, born 1964-08-01.
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/person5
+ */
 export const person5 = { id: "person5", name: { first: "Terry", last: "Times" }, birthday: "1964-08-01" };
+/**
+ * Ordered array of all five test person fixtures (`person1` through `person5`).
+ *
+ * @see https://dhoulb.github.io/shelving/test/people/people
+ */
 export const people = [person1, person2, person3, person4, person5];

package/test/util.d.ts

@@ -1,9 +1,36 @@
 import type { Data } from "../util/data.js";
 import type { Identifier, Item } from "../util/item.js";
 import type { NotString } from "../util/string.js";
-/** Expect that an object matches `PromiseLike` */
+/**
+ * Asymmetric matcher that expects an object matching `PromiseLike` (i.e. has a `.then()` method).
+ *
+ * @example expect(value).toEqual(EXPECT_PROMISELIKE)
+ * @see https://dhoulb.github.io/shelving/test/util/EXPECT_PROMISELIKE
+ */
 export declare const EXPECT_PROMISELIKE: any;
-/** Expect `Item` objects with an `.id` prop in any order. */
+/**
+ * Assert that a set of `Item` objects has exactly the expected `.id` values, in any order.
+ *
+ * - Sorts both sides before comparing, so iteration order is ignored.
+ * - On failure, rewrites the stack trace to point at the call site.
+ *
+ * @param items The items to check, each carrying an `.id` prop.
+ * @param keys The exact set of `.id` values expected (order ignored).
+ * @throws {Error} If the items' ids don't match `keys`.
+ * @example expectUnorderedItems(results, ["person1", "person2"])
+ * @see https://dhoulb.github.io/shelving/test/util/expectUnorderedItems
+ */
 export declare function expectUnorderedItems<I extends Identifier, T extends Data>(items: Iterable<Item<I, T>>, keys: Iterable<string> & NotString): void;
-/** Expect `Item` objects with an `.id` prop in a specified order. */
+/**
+ * Assert that a set of `Item` objects has exactly the expected `.id` values, in the exact given order.
+ *
+ * - Compares ids positionally, so order is significant.
+ * - On failure, rewrites the stack trace to point at the call site.
+ *
+ * @param items The items to check, each carrying an `.id` prop.
+ * @param keys The exact ordered sequence of `.id` values expected.
+ * @throws {Error} If the items' ids don't match `keys` in order.
+ * @example expectOrderedItems(results, ["person1", "person2"])
+ * @see https://dhoulb.github.io/shelving/test/util/expectOrderedItems
+ */
 export declare function expectOrderedItems<I extends Identifier, T extends Data>(items: Iterable<Item<I, T>>, keys: Iterable<string> & NotString): void;

package/test/util.js

@@ -1,10 +1,26 @@
 import { expect } from "bun:test";
 import { getIdentifiers } from "../util/item.js";
-/** Expect that an object matches `PromiseLike` */
+/**
+ * Asymmetric matcher that expects an object matching `PromiseLike` (i.e. has a `.then()` method).
+ *
+ * @example expect(value).toEqual(EXPECT_PROMISELIKE)
+ * @see https://dhoulb.github.io/shelving/test/util/EXPECT_PROMISELIKE
+ */
 export const EXPECT_PROMISELIKE = expect.objectContaining({
     then: expect.any(Function),
 });
-/** Expect `Item` objects with an `.id` prop in any order. */
+/**
+ * Assert that a set of `Item` objects has exactly the expected `.id` values, in any order.
+ *
+ * - Sorts both sides before comparing, so iteration order is ignored.
+ * - On failure, rewrites the stack trace to point at the call site.
+ *
+ * @param items The items to check, each carrying an `.id` prop.
+ * @param keys The exact set of `.id` values expected (order ignored).
+ * @throws {Error} If the items' ids don't match `keys`.
+ * @example expectUnorderedItems(results, ["person1", "person2"])
+ * @see https://dhoulb.github.io/shelving/test/util/expectUnorderedItems
+ */
 export function expectUnorderedItems(items, keys) {
     try {
         expect(items).toBeInstanceOf(Object);
@@ -16,7 +32,18 @@ export function expectUnorderedItems(items, keys) {
         throw thrown;
     }
 }
-/** Expect `Item` objects with an `.id` prop in a specified order. */
+/**
+ * Assert that a set of `Item` objects has exactly the expected `.id` values, in the exact given order.
+ *
+ * - Compares ids positionally, so order is significant.
+ * - On failure, rewrites the stack trace to point at the call site.
+ *
+ * @param items The items to check, each carrying an `.id` prop.
+ * @param keys The exact ordered sequence of `.id` values expected.
+ * @throws {Error} If the items' ids don't match `keys` in order.
+ * @example expectOrderedItems(results, ["person1", "person2"])
+ * @see https://dhoulb.github.io/shelving/test/util/expectOrderedItems
+ */
 export function expectOrderedItems(items, keys) {
     try {
         expect(items).toBeInstanceOf(Object);

package/ui/app/App.d.ts

@@ -2,10 +2,22 @@ import type { ReactElement } from "react";
 import "../style/base.css";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `<App>` — the root `Meta` plus the application `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/app/App/AppProps
+ */
 export interface AppProps extends PossibleMeta, ChildProps {
 }
 /**
- * Root component for an application. Provides a `Meta` context to its children so descendants can read
- * or update metadata. Design tokens and body baseline typography are set globally via `style/base.css`.
+ * Root component for an application, providing the top-level `Meta` context and global styles.
+ * - Descendants can read or update metadata via the provided `<Meta>` context.
+ * - Design tokens and body baseline typography are set globally via `style/base.css`.
+ *
+ * @param children The application content.
+ * @param meta The root meta (app name, root URL, language, etc.).
+ * @returns The app root element wrapping `children`.
+ * @example <App app="My App" root="https://example.com/"><Navigation>…</Navigation></App>
+ * @see https://dhoulb.github.io/shelving/ui/app/App/App
  */
 export declare function App({ children, ...meta }: AppProps): ReactElement;

package/ui/app/App.js

@@ -2,8 +2,15 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
 import "../style/base.css";
 /**
- * Root component for an application. Provides a `Meta` context to its children so descendants can read
- * or update metadata. Design tokens and body baseline typography are set globally via `style/base.css`.
+ * Root component for an application, providing the top-level `Meta` context and global styles.
+ * - Descendants can read or update metadata via the provided `<Meta>` context.
+ * - Design tokens and body baseline typography are set globally via `style/base.css`.
+ *
+ * @param children The application content.
+ * @param meta The root meta (app name, root URL, language, etc.).
+ * @returns The app root element wrapping `children`.
+ * @example <App app="My App" root="https://example.com/"><Navigation>…</Navigation></App>
+ * @see https://dhoulb.github.io/shelving/ui/app/App/App
  */
 export function App({ children, ...meta }) {
     return _jsx(MetaContext, { value: requireMeta(meta), children: children });

package/ui/app/App.tsx

@@ -4,11 +4,23 @@ import "../style/base.css";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
 
+/**
+ * Props for `<App>` — the root `Meta` plus the application `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/app/App/AppProps
+ */
 export interface AppProps extends PossibleMeta, ChildProps {}
 
 /**
- * Root component for an application. Provides a `Meta` context to its children so descendants can read
- * or update metadata. Design tokens and body baseline typography are set globally via `style/base.css`.
+ * Root component for an application, providing the top-level `Meta` context and global styles.
+ * - Descendants can read or update metadata via the provided `<Meta>` context.
+ * - Design tokens and body baseline typography are set globally via `style/base.css`.
+ *
+ * @param children The application content.
+ * @param meta The root meta (app name, root URL, language, etc.).
+ * @returns The app root element wrapping `children`.
+ * @example <App app="My App" root="https://example.com/"><Navigation>…</Navigation></App>
+ * @see https://dhoulb.github.io/shelving/ui/app/App/App
  */
 export function App({ children, ...meta }: AppProps): ReactElement {
 	return <MetaContext value={requireMeta(meta)}>{children}</MetaContext>;

package/ui/block/Address.d.ts

@@ -5,21 +5,63 @@ 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 `<address>` element of every `Address`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/ADDRESS_CLASS
+ */
 export declare const ADDRESS_CLASS: string | undefined;
+/**
+ * CSS class that styles `<address>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/ADDRESS_PROSE_CLASS
+ */
 export declare const ADDRESS_PROSE_CLASS: string | undefined;
+/**
+ * Props for `Address` — colour, space, and typography variants plus required children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/AddressProps
+ */
 export interface AddressProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {
 }
+/**
+ * Props for `PhysicalAddress` — an optional name and a nullable `AddressData` object.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/PhysicalAddressProps
+ */
 export interface PhysicalAddressProps {
     name?: Nullish<string>;
     address: Nullish<AddressData>;
 }
+/**
+ * Props for `EmailAddress` — an optional name and a nullable email string.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/EmailAddressProps
+ */
 export interface EmailAddressProps {
     name?: Nullish<string>;
     email: Nullish<string>;
 }
-/** Show any kind of contact data. */
+/**
+ * Show any kind of contact data, rendered as an `<address>`.
+ *
+ * @example <Address><Strong>Acme</Strong>{"\n"}1 Example St</Address>
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/Address
+ */
 export declare function Address({ children, ...props }: AddressProps): import("react").JSX.Element;
-/** Show an optional `AddressData` object correctly on screen. */
+/**
+ * Show an optional `AddressData` object correctly on screen.
+ * - Renders an optional `name` in bold, followed by the formatted address; shows "No address" when `address` is empty.
+ *
+ * @example <PhysicalAddress name="Acme" address={addressData} />
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/PhysicalAddress
+ */
 export declare function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement;
-/** Show an optional email address string correctly on screen. */
+/**
+ * Show an optional email address string correctly on screen.
+ * - Renders an optional `name` in bold, followed by a `mailto:` link; shows "No email" when `email` is empty.
+ *
+ * @example <EmailAddress name="Acme" email="hi@example.com" />
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/EmailAddress
+ */
 export declare function EmailAddress({ name, email }: EmailAddressProps): ReactElement;

package/ui/block/Address.js

@@ -8,18 +8,45 @@ import { TINT_CLASS } from "../style/Tint.js";
 import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import ADDRESS_CSS from "./Address.module.css";
+/**
+ * CSS class applied to the root `<address>` element of every `Address`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/ADDRESS_CLASS
+ */
 export const ADDRESS_CLASS = getModuleClass(ADDRESS_CSS, "address");
+/**
+ * CSS class that styles `<address>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/ADDRESS_PROSE_CLASS
+ */
 export const ADDRESS_PROSE_CLASS = getModuleClass(ADDRESS_CSS, "prose");
-/** Show any kind of contact data. */
+/**
+ * Show any kind of contact data, rendered as an `<address>`.
+ *
+ * @example <Address><Strong>Acme</Strong>{"\n"}1 Example St</Address>
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/Address
+ */
 export function Address({ children, ...props }) {
     return (_jsx("address", { className: getClass(ADDRESS_CLASS, //
         TINT_CLASS, getColorClass(props), getSpaceClass(props), getTypographyClass(props)), children: children }));
 }
-/** Show an optional `AddressData` object correctly on screen. */
+/**
+ * Show an optional `AddressData` object correctly on screen.
+ * - Renders an optional `name` in bold, followed by the formatted address; shows "No address" when `address` is empty.
+ *
+ * @example <PhysicalAddress name="Acme" address={addressData} />
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/PhysicalAddress
+ */
 export function PhysicalAddress({ name, address }) {
     return (_jsxs(Address, { children: [name && _jsx(Strong, { children: name }), name && "\n", address ? formatAddress(address) : _jsx(Small, { children: "No address" })] }));
 }
-/** Show an optional email address string correctly on screen. */
+/**
+ * Show an optional email address string correctly on screen.
+ * - Renders an optional `name` in bold, followed by a `mailto:` link; shows "No email" when `email` is empty.
+ *
+ * @example <EmailAddress name="Acme" email="hi@example.com" />
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/EmailAddress
+ */
 export function EmailAddress({ name, email }) {
     return (_jsxs(Address, { children: [name && _jsx(Strong, { children: name }), name && "\n", email ? _jsx("a", { href: `mailto:${email}`, children: email }) : _jsx(Small, { children: "No email" })] }));
 }

package/ui/block/Address.tsx

@@ -11,22 +11,53 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { ChildProps } from "../util/props.js";
 import ADDRESS_CSS from "./Address.module.css";
 
+/**
+ * CSS class applied to the root `<address>` element of every `Address`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/ADDRESS_CLASS
+ */
 export const ADDRESS_CLASS = getModuleClass(ADDRESS_CSS, "address");
+
+/**
+ * CSS class that styles `<address>` elements when they appear inside `Prose`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/ADDRESS_PROSE_CLASS
+ */
 export const ADDRESS_PROSE_CLASS = getModuleClass(ADDRESS_CSS, "prose");
 
+/**
+ * Props for `Address` — colour, space, and typography variants plus required children.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/AddressProps
+ */
 export interface AddressProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {}
 
+/**
+ * Props for `PhysicalAddress` — an optional name and a nullable `AddressData` object.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/PhysicalAddressProps
+ */
 export interface PhysicalAddressProps {
 	name?: Nullish<string>;
 	address: Nullish<AddressData>;
 }
 
+/**
+ * Props for `EmailAddress` — an optional name and a nullable email string.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/EmailAddressProps
+ */
 export interface EmailAddressProps {
 	name?: Nullish<string>;
 	email: Nullish<string>;
 }
 
-/** Show any kind of contact data. */
+/**
+ * Show any kind of contact data, rendered as an `<address>`.
+ *
+ * @example <Address><Strong>Acme</Strong>{"\n"}1 Example St</Address>
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/Address
+ */
 export function Address({ children, ...props }: AddressProps) {
 	return (
 		<address
@@ -43,7 +74,13 @@ export function Address({ children, ...props }: AddressProps) {
 	);
 }
 
-/** Show an optional `AddressData` object correctly on screen. */
+/**
+ * Show an optional `AddressData` object correctly on screen.
+ * - Renders an optional `name` in bold, followed by the formatted address; shows "No address" when `address` is empty.
+ *
+ * @example <PhysicalAddress name="Acme" address={addressData} />
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/PhysicalAddress
+ */
 export function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement {
 	return (
 		<Address>
@@ -54,7 +91,13 @@ export function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactE
 	);
 }
 
-/** Show an optional email address string correctly on screen. */
+/**
+ * Show an optional email address string correctly on screen.
+ * - Renders an optional `name` in bold, followed by a `mailto:` link; shows "No email" when `email` is empty.
+ *
+ * @example <EmailAddress name="Acme" email="hi@example.com" />
+ * @see https://dhoulb.github.io/shelving/ui/block/Address/EmailAddress
+ */
 export function EmailAddress({ name, email }: EmailAddressProps): ReactElement {
 	return (
 		<Address>

package/ui/block/Block.d.ts

@@ -4,10 +4,32 @@ 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 `Block`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/Block/BLOCK_CLASS
+ */
 export declare const BLOCK_CLASS: string | undefined;
+/**
+ * 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 declare function Block({ as: Component, children, ...props }: BlockProps): ReactElement;

package/ui/block/Block.js

@@ -6,8 +6,20 @@ import { getTypographyClass } from "../style/Typography.js";
 import { getWidthClass } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.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");
-/** 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 }) {
     return (_jsx(Component, { className: getClass(BLOCK_CLASS, TINT_CLASS, getColorClass(props), getSpaceClass(props), getTypographyClass(props), getWidthClass(props)), children: children }));
 }