shelving 1.199.3 → 1.200.1

package/api/cache/APICache.js

@@ -1,3 +1,4 @@
+import { AVOID_REFRESH } from "../../store/FetchStore.js";
 import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { EndpointCache } from "./EndpointCache.js";
@@ -23,7 +24,7 @@ export class APICache {
      * - Waits for the in-flight fetch if the store is loading.
      * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
      */
-    async call(endpoint, payload, maxAge, caller = this.call) {
+    async call(endpoint, payload, maxAge = AVOID_REFRESH, caller = this.call) {
         return this.get(endpoint).call(payload, maxAge, caller);
     }
     /** Invalidate a specific store for an endpoint. */

package/api/cache/EndpointCache.d.ts

@@ -18,6 +18,8 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
      * - Returns the cached value immediately if one exists.
      * - Waits for the in-flight fetch if the store is loading.
      * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     *
+     * @param maxAge The maximum age (defaults to only refreshing if the value is still in a loading state).
      */
     call(payload: P, maxAge?: number, caller?: AnyCaller): Promise<R>;
     /** Invalidate a specific store. */

package/api/cache/EndpointCache.js

@@ -1,3 +1,4 @@
+import { AVOID_REFRESH } from "../../store/FetchStore.js";
 import { awaitValues } from "../../util/async.js";
 import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
@@ -24,8 +25,10 @@ export class EndpointCache {
      * - Returns the cached value immediately if one exists.
      * - Waits for the in-flight fetch if the store is loading.
      * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     *
+     * @param maxAge The maximum age (defaults to only refreshing if the value is still in a loading state).
      */
-    async call(payload, maxAge, caller = this.call) {
+    async call(payload, maxAge = AVOID_REFRESH, caller = this.call) {
         const store = this.get(payload, caller);
         await store.refresh(maxAge);
         return store.value;

package/api/provider/CachedAPIProvider.d.ts

@@ -1,4 +1,5 @@
 import type { AnyCaller } from "../../util/function.js";
+import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "./APIProvider.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
@@ -7,12 +8,16 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - Constructor accepts a `source` provider and an optional default `maxAge`.
  * - On `call(...)`, triggers `cache.refresh(maxAge)` for the endpoint+payload before awaiting `cache.call(...)`.
  * - `invalidate`, `invalidateAll`, `refresh`, and `refreshAll` pass through to the underlying cache and use `this.maxAge` as the default refresh timing.
+ *
+ * @param `maxAge` The maximum age used when calling `call()` (defaults to `AVOID_REFRESH`, i.e. only refresh if the value is invalidated or still loading).
+ * - Note: This is not used for `refresh()` calls — when you call `refresh()` you likely mean "do it now".
+ * - When we are using `call()` on a cache, the entire point of the cache is to "cache", so the default isn't `0` like it is for `refresh()`
  */
 export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
     readonly maxAge: number | undefined;
     private readonly _cache;
     constructor(source: APIProvider<P, R>, maxAge?: number);
-    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number | undefined, caller?: AnyCaller): Promise<RR>;
+    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, _options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
     invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
     invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;

package/api/provider/CachedAPIProvider.js

@@ -1,3 +1,4 @@
+import { AVOID_REFRESH } from "../../store/FetchStore.js";
 import { APICache } from "../cache/APICache.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
@@ -5,19 +6,22 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - Constructor accepts a `source` provider and an optional default `maxAge`.
  * - On `call(...)`, triggers `cache.refresh(maxAge)` for the endpoint+payload before awaiting `cache.call(...)`.
  * - `invalidate`, `invalidateAll`, `refresh`, and `refreshAll` pass through to the underlying cache and use `this.maxAge` as the default refresh timing.
+ *
+ * @param `maxAge` The maximum age used when calling `call()` (defaults to `AVOID_REFRESH`, i.e. only refresh if the value is invalidated or still loading).
+ * - Note: This is not used for `refresh()` calls — when you call `refresh()` you likely mean "do it now".
+ * - When we are using `call()` on a cache, the entire point of the cache is to "cache", so the default isn't `0` like it is for `refresh()`
  */
 export class CachedAPIProvider extends ThroughAPIProvider {
     maxAge;
     _cache;
-    constructor(source, maxAge) {
+    constructor(source, maxAge = AVOID_REFRESH) {
         super(source);
         this.maxAge = maxAge;
         this._cache = new APICache(source);
     }
-    // @ts-expect-error TS2416: intentionally diverges from `APIProvider.call` — `RequestOptions` are not used by the cache, so the third arg is repurposed as `maxAge`.
-    call(endpoint, payload, maxAge = this.maxAge, caller = this.call) {
-        this._cache.refresh(endpoint, payload, maxAge);
-        return this._cache.call(endpoint, payload, maxAge, caller);
+    // Override call to use the cache racther than calling fresh each time.
+    call(endpoint, payload, _options, caller = this.call) {
+        return this._cache.call(endpoint, payload, this.maxAge, caller);
     }
     invalidate(endpoint, payload) {
         this._cache.invalidate(endpoint, payload);

package/index.js

@@ -12,6 +12,7 @@ export * from "./error/index.js";
 export * from "./markup/index.js";
 // export * from "./react/index.js"; // Not exported.
 export * from "./schema/index.js";
+// export * from "./ui/index.js"; // Not exported — shelving/ui requires a bundler (CSS Modules, JSX) and is consumed as source.
 export * from "./sequence/index.js";
 export * from "./store/index.js";
 // export * from "./test/index.js"; // Not exported.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.199.3",
+	"version": "1.200.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -11,16 +11,18 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.14",
 		"@google-cloud/firestore": "^8.5.0",
+		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.3.13",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
 		"@typescript/native-preview": "^7.0.0-dev.20260502.1",
 		"firebase": "^12.12.1",
-		"react": "^19.2.5",
-		"react-dom": "^19.2.5"
+		"react": "canary",
+		"react-dom": "canary"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=7.0.0",
+		"@heroicons/react": ">=2.0.0",
 		"firebase": ">=11.0.0",
 		"react": ">=19.0.0"
 	},
@@ -41,6 +43,7 @@
 		"./sequence": "./sequence/index.js",
 		"./store": "./store/index.js",
 		"./test": "./test/index.js",
+		"./ui": "./ui/index.js",
 		"./util": "./util/index.js"
 	},
 	"description": "Toolkit for using data in JavaScript.",
@@ -68,12 +71,14 @@
 		"fix:0:lint": "biome check --write .",
 		"build": "bun run --sequential build:*",
 		"build:0:setup": "rm -rf ./dist && mkdir -p ./dist",
-		"build:1:copy": "cp package.json dist/package.json && cp LICENSE.md dist/LICENSE.md && cp README.md dist/README.md && cp .npmignore dist/.npmignore",
+		"build:1:copy": "cp package.json dist/package.json && cp LICENSE.md dist/LICENSE.md && cp README.md dist/README.md && cp .npmignore dist/.npmignore && cp -r modules/ui dist/ui",
 		"build:2:emit": "tsgo",
 		"build:3:syntax": "bun run ./dist/index.js",
 		"build:4:unit": "bun test ./dist/**/*.test.js --concurrent --only-failures --bail"
 	},
-	"sideEffects": false,
+	"sideEffects": [
+		"*.css"
+	],
 	"type": "module",
 	"types": "./index.d.ts"
 }

package/store/FetchStore.d.ts

@@ -1,6 +1,10 @@
 import { type NONE } from "../util/constants.js";
 import { BusyStore } from "./BusyStore.js";
 import type { AsyncStoreInput, StoreInput } from "./Store.js";
+/** Zero passed to `refresh()` means "always refresh this value" (this is the default). */
+export declare const ALWAYS_REFRESH = 0;
+/** Infinity passed to `refresh()` means "only refresh if this value is not loaded or invalid". */
+export declare const AVOID_REFRESH: number;
 /** Callback for a callback fetch store. */
 export type FetchCallback<T> = (signal: AbortSignal) => StoreInput<T> | PromiseLike<StoreInput<T>>;
 /**
@@ -21,6 +25,11 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      * - Triggered automatically when someone reads `value` or `loading`.
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
+     *
+     * @param maxAge The maximum age for whether we refresh or not.
+     * - `0` zero means "always refresh" (this is the default).
+     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - Any other value may or may not be stale based on `this.age`
      */
     refresh(maxAge?: number): Promise<boolean> | boolean;
     private _pendingRefresh;

package/store/FetchStore.js

@@ -2,6 +2,10 @@ import { RequiredError } from "../error/RequiredError.js";
 import { isAsync } from "../util/async.js";
 import { ABORT, SKIP } from "../util/constants.js";
 import { BusyStore } from "./BusyStore.js";
+/** Zero passed to `refresh()` means "always refresh this value" (this is the default). */
+export const ALWAYS_REFRESH = 0;
+/** Infinity passed to `refresh()` means "only refresh if this value is not loaded or invalid". */
+export const AVOID_REFRESH = Infinity;
 /**
  * Store that fetches its values from a remote source.
  *
@@ -47,8 +51,13 @@ export class FetchStore extends BusyStore {
      * - Triggered automatically when someone reads `value` or `loading`.
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
+     *
+     * @param maxAge The maximum age for whether we refresh or not.
+     * - `0` zero means "always refresh" (this is the default).
+     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - Any other value may or may not be stale based on `this.age`
      */
-    refresh(maxAge) {
+    refresh(maxAge = ALWAYS_REFRESH) {
         if (this._pendingRefresh)
             return this._pendingRefresh;
         if (!this.stale(maxAge))

package/store/Store.d.ts

@@ -99,10 +99,10 @@ export declare class Store<T, TT = T> implements AsyncIterable<T, void, void>, A
      *
      * @param maxAge The maximum age for the stale check.
      * - `0` zero means "always refresh" (this is the default).
-     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - `Infinity` means "refresh only if store is still in a loading state"
      * - Any other value may or may not be stale based on `this.age`
      */
-    stale(maxAge?: number): boolean;
+    stale(maxAge: number): boolean;
     /** Current error of this store, or `undefined` if there is no error. */
     get reason(): unknown;
     set reason(reason: unknown);

package/store/Store.js

@@ -137,10 +137,10 @@ export class Store {
      *
      * @param maxAge The maximum age for the stale check.
      * - `0` zero means "always refresh" (this is the default).
-     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - `Infinity` means "refresh only if store is still in a loading state"
      * - Any other value may or may not be stale based on `this.age`
      */
-    stale(maxAge = 0) {
+    stale(maxAge) {
         return this.age >= maxAge;
     }
     /** Current error of this store, or `undefined` if there is no error. */

package/ui/app/App.d.ts

@@ -0,0 +1,11 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { PossibleMetaData } from "../util/meta.js";
+export interface AppProps extends PossibleMetaData {
+    children: ReactNode;
+}
+/**
+ * Root component for an application.
+ * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
+ * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ */
+export declare function App({ children, ...metadata }: AppProps): ReactElement;

package/ui/app/App.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { Meta } from "../misc/Meta.js";
+import APP_CSS from "./App.module.css";
+const _appClass = APP_CSS.app;
+/**
+ * Root component for an application.
+ * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
+ * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ */
+export function App({ children, ...metadata }) {
+    useEffect(() => {
+        if (!_appClass)
+            return;
+        document.body.classList.add(_appClass);
+        return () => {
+            document.body.classList.remove(_appClass);
+        };
+    }, []);
+    return _jsx(Meta, { ...metadata, children: children });
+}

package/ui/app/App.module.css

@@ -0,0 +1,168 @@
+:root {
+	color-scheme: light;
+
+	/* Widths */
+	--width-narrow: min(100%, 22.5rem);
+	--width-wide: min(100%, 33.75rem);
+
+	/* Font weights */
+	--weight-normal: 400;
+	--weight-strong: 700;
+	--weight-label: var(--weight-strong);
+
+	/* Font faces */
+	--font-sans: system-ui;
+	--font-mono: "Courier New", "Courier", monospace;
+	--font-serif: "Palatino", "Garamond", serif;
+
+	/* Semantic font faces */
+	--font-body: var(--font-sans);
+	--font-code: var(--font-mono);
+
+	/* Font sizes */
+	--size-small: 0.875rem;
+	--size-normal: 1rem;
+	--size-large: 1.5rem;
+	--size-xlarge: 2.5rem;
+	--size-xxlarge: 5rem;
+	--size-icon: 1.5rem;
+
+	/* Line heights */
+	--leading-none: 0;
+	--leading-tight: 1.25;
+	--leading-normal: 1.5;
+
+	/* Spacings */
+	--spacing-small: 0.25rem;
+	--spacing-inline: 0.5rem;
+	--spacing-paragraph: 1rem;
+	--spacing-element: 0.75rem;
+	--spacing-block: 1rem;
+	--spacing-spacious: 3rem;
+
+	/* Border widths */
+	--border-element: 2px;
+	--border-block: 2px;
+	--border-focus: 3px;
+
+	/* Radii */
+	--radius-inline: 0.25rem;
+	--radius-element: 0.5rem;
+	--radius-block: 1rem;
+
+	/* Durations */
+	--duration-fast: 150ms;
+	--duration-normal: 300ms;
+	--duration-slow: 600ms;
+
+	/* Grows */
+	--grow-greedy: 1000000; /* Take up as much space as possible, unless other elements are greedy too. */
+	--grow-normal: 1000; /* Take up a normal amount of space. */
+	--grow-timid: 1; /* Take up minimal space, unless the only other elements are timid too. */
+	--grow-none: 0;
+
+	/* Colors */
+	--color-blue: #156ef4;
+	--color-cyan: #15edf4;
+	--color-green: #8ce814;
+	--color-orange: #ffb21a;
+	--color-pink: #e718a2;
+	--color-purple: #ad15f4;
+	--color-red: #e5352f;
+	--color-yellow: #ffe01a;
+	--color-black: black;
+	--color-gray: color-mix(var(--color-blue) 30%, rgb(128 128 128)); /* Used as the "tone" color for scale of grays. */
+	--color-white: white;
+
+	/* Grays */
+	--gray-05: color-mix(var(--color-gray) 10%, var(--color-white));
+	--gray-10: color-mix(var(--color-gray) 20%, var(--color-white));
+	--gray-20: color-mix(var(--color-gray) 40%, var(--color-white));
+	--gray-30: color-mix(var(--color-gray) 60%, var(--color-white));
+	--gray-40: color-mix(var(--color-gray) 80%, var(--color-white));
+	--gray-50: var(--color-gray);
+	--gray-60: color-mix(var(--color-gray) 80%, var(--color-black));
+	--gray-70: color-mix(var(--color-gray) 60%, var(--color-black));
+	--gray-80: color-mix(var(--color-gray) 40%, var(--color-black));
+	--gray-90: color-mix(var(--color-gray) 20%, var(--color-black));
+	--gray-95: color-mix(var(--color-gray) 10%, var(--color-black));
+
+	/* Named colors */
+	--color-text: var(--color-black);
+	--color-contrast: var(--color-white); /* Contrast color — must be readable on `--color-text` */
+	--color-quiet: var(--gray-40); /* Quiet color is grey, used for secondary text etc. */
+	--color-bg: var(--color-white); /* Background color is usually the opposite of text colour. */
+	--color-border: var(--gray-10);
+	--color-overlay: color-mix(in srgb, var(--color-text) 40%, transparent);
+	--color-link: var(--color-blue); /* Links are usually blue. */
+	--color-focus: var(--color-blue); /* Focus is usually blue. */
+	--color-surface: var(--gray-10); /* Surface color is used for notices and buttons — must be readable on `--color-text` */
+
+	/* Shadows */
+	--shadow-element: 0 3px 16px -8px var(--color-overlay);
+	--shadow-block: 0 4px 24px -12px var(--color-overlay);
+
+	/* Primary colors */
+	--primary-text: var(--color-blue);
+	--primary-contrast: var(--color-white);
+	--primary-surface: color-mix(in srgb, var(--primary-text) 12%, white);
+
+	/* Secondary colors */
+	--secondary-text: var(--color-purple);
+	--secondary-contrast: var(--color-white);
+	--secondary-surface: color-mix(in srgb, var(--secondary-text) 12%, white);
+
+	/* Tertiary colors */
+	--tertiary-text: var(--color-cyan);
+	--tertiary-contrast: var(--color-white);
+	--tertiary-surface: color-mix(in srgb, var(--tertiary-text) 12%, white);
+
+	/* Quiet colors */
+	--quiet-text: var(--color-quiet);
+	--quiet-contrast: var(--color-contrast);
+	--quiet-surface: var(--color-surface);
+
+	/* Focus colors */
+	--focus-text: var(--color-focus);
+	--focus-contrast: var(--color-white);
+	--focus-surface: color-mix(in srgb, var(--focus-text) 12%, white);
+
+	/* Loading colors */
+	--loading-text: var(--color-loading);
+	--loading-contrast: var(--color-contrast);
+	--loading-surface: var(--color-surface);
+
+	/* Info colors */
+	--info-text: var(--color-blue);
+	--info-contrast: var(--color-white);
+	--info-surface: color-mix(in srgb, var(--info-text) 12%, white);
+
+	/* Success colors */
+	--success-text: var(--color-green);
+	--success-contrast: var(--color-white);
+	--success-surface: color-mix(in srgb, var(--success-text) 12%, white);
+
+	/* Warning colors */
+	--warning-text: var(--color-orange);
+	--warning-contrast: var(--color-white);
+	--warning-surface: color-mix(in srgb, var(--warning-text) 12%, white);
+
+	/* Error colors */
+	--error-text: var(--color-red);
+	--error-contrast: var(--color-white);
+	--error-surface: color-mix(in srgb, var(--error-text) 12%, white);
+
+	/* Danger colors */
+	--danger-text: var(--color-red);
+	--danger-contrast: var(--color-white);
+	--danger-surface: color-mix(in srgb, var(--danger-text) 12%, white);
+
+	/* Highlight colors */
+	--highlight-text: var(--color-yellow);
+	--highlight-contrast: var(--color-black);
+	--highlight-surface: color-mix(in srgb, var(--highlight-text) 12%, white);
+}
+
+.app {
+	/* Empty */
+}

package/ui/app/App.tsx

@@ -0,0 +1,26 @@
+import { type ReactElement, type ReactNode, useEffect } from "react";
+import { Meta } from "../misc/Meta.js";
+import type { PossibleMetaData } from "../util/meta.js";
+import APP_CSS from "./App.module.css";
+
+export interface AppProps extends PossibleMetaData {
+	children: ReactNode;
+}
+
+const _appClass = APP_CSS.app;
+
+/**
+ * Root component for an application.
+ * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
+ * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ */
+export function App({ children, ...metadata }: AppProps): ReactElement {
+	useEffect(() => {
+		if (!_appClass) return;
+		document.body.classList.add(_appClass);
+		return () => {
+			document.body.classList.remove(_appClass);
+		};
+	}, []);
+	return <Meta {...metadata}>{children}</Meta>;
+}

package/ui/app/index.d.ts

@@ -0,0 +1 @@
+export * from "./App.js";

package/ui/app/index.js

@@ -0,0 +1 @@
+export * from "./App.js";

package/ui/app/index.ts

@@ -0,0 +1 @@
+export * from "./App.js";

package/ui/block/Address.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement, ReactNode } from "react";
+import { type AddressData } from "../../schema/AddressSchema.js";
+import type { Nullish } from "../../util/null.js";
+export interface AddressProps {
+    children: ReactNode;
+}
+export interface PhysicalAddressProps {
+    name?: Nullish<string>;
+    address: Nullish<AddressData>;
+}
+export interface EmailAddressProps {
+    name?: Nullish<string>;
+    email: Nullish<string>;
+}
+/** Show any kind of contact data. */
+export declare function Address({ children }: AddressProps): import("react/jsx-runtime").JSX.Element;
+/** Show an optional `AddressData` object correctly on screen. */
+export declare function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement;
+/** Show an optional email address string correctly on screen. */
+export declare function EmailAddress({ name, email }: EmailAddressProps): ReactElement;

package/ui/block/Address.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatAddress } from "../../schema/AddressSchema.js";
+import { Small } from "../inline/Small.js";
+import { Strong } from "../inline/Strong.js";
+import styles from "./Address.module.css";
+/** Show any kind of contact data. */
+export function Address({ children }) {
+    return _jsx("address", { className: styles.address, children: children });
+}
+/** Show an optional `AddressData` object correctly on screen. */
+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. */
+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.module.css

@@ -0,0 +1,20 @@
+.address,
+.prose address {
+	/* Box */
+	display: block;
+	margin-inline: 0;
+	margin-block: var(--address-spacing, var(--spacing-block));
+
+	/* Contents */
+	white-space: pre-line;
+	font-style: normal;
+	text-align: left;
+
+	/* Styles */
+	&:first-child {
+		margin-block-start: 0;
+	}
+	&:last-child {
+		margin-block-end: 0;
+	}
+}

package/ui/block/Address.tsx

@@ -0,0 +1,47 @@
+import type { ReactElement, ReactNode } from "react";
+import { type AddressData, formatAddress } from "../../schema/AddressSchema.js";
+import type { Nullish } from "../../util/null.js";
+import { Small } from "../inline/Small.js";
+import { Strong } from "../inline/Strong.js";
+import styles from "./Address.module.css";
+
+export interface AddressProps {
+	children: ReactNode;
+}
+
+export interface PhysicalAddressProps {
+	name?: Nullish<string>;
+	address: Nullish<AddressData>;
+}
+
+export interface EmailAddressProps {
+	name?: Nullish<string>;
+	email: Nullish<string>;
+}
+
+/** Show any kind of contact data. */
+export function Address({ children }: AddressProps) {
+	return <address className={styles.address}>{children}</address>;
+}
+
+/** Show an optional `AddressData` object correctly on screen. */
+export function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement {
+	return (
+		<Address>
+			{name && <Strong>{name}</Strong>}
+			{name && "\n"}
+			{address ? formatAddress(address) : <Small>No address</Small>}
+		</Address>
+	);
+}
+
+/** Show an optional email address string correctly on screen. */
+export function EmailAddress({ name, email }: EmailAddressProps): ReactElement {
+	return (
+		<Address>
+			{name && <Strong>{name}</Strong>}
+			{name && "\n"}
+			{email ? <a href={`mailto:${email}`}>{email}</a> : <Small>No email</Small>}
+		</Address>
+	);
+}

package/ui/block/Blockquote.d.ts

@@ -0,0 +1,5 @@
+import type { ReactElement, ReactNode } from "react";
+export interface BlockquoteProps {
+    children?: ReactNode;
+}
+export declare function Blockquote({ children }: BlockquoteProps): ReactElement;

package/ui/block/Blockquote.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import styles from "./Blockquote.module.css";
+export function Blockquote({ children }) {
+    return _jsx("blockquote", { className: styles.blockquote, children: children });
+}

package/ui/block/Blockquote.module.css

@@ -0,0 +1,21 @@
+.blockquote,
+.prose blockquote {
+	/* Box */
+	display: block;
+	margin-inline: 0;
+	margin-block: var(--blockquote-spacing, var(--spacing-block));
+	border-inline-start: var(--blockquote-border, var(--border-focus)) solid var(--blockquote-color-border, var(--color-border));
+	padding-inline-start: var(--blockquote-padding, var(--spacing-paragraph));
+	padding-block: var(--spacing-inline);
+
+	/* Style */
+	color: var(--blockquote-color-text, inherit);
+
+	/* Styles */
+	&:first-child {
+		margin-block-start: 0;
+	}
+	&:last-child {
+		margin-block-end: 0;
+	}
+}

package/ui/block/Blockquote.tsx

@@ -0,0 +1,10 @@
+import type { ReactElement, ReactNode } from "react";
+import styles from "./Blockquote.module.css";
+
+export interface BlockquoteProps {
+	children?: ReactNode;
+}
+
+export function Blockquote({ children }: BlockquoteProps): ReactElement {
+	return <blockquote className={styles.blockquote}>{children}</blockquote>;
+}

package/ui/block/Card.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement, ReactNode } from "react";
+export interface CardProps {
+    children: ReactNode;
+    /** Constrain the section to narrow width (defaults to full-width). */
+    narrow?: boolean;
+    /** Constrain the section to wide width (defaults to full-width). */
+    wide?: boolean;
+}
+/** Cards are boxed areas for content to sit within. */
+export declare function Card({ children, ...variants }: CardProps): ReactElement;