shelving 1.282.2 → 1.283.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.282.2",
+	"version": "1.283.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,7 +9,7 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.7",
+		"@biomejs/biome": "^2.5.8",
 		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.3.14",
 		"@types/react": "^19.2.18",

package/ui/README.md

@@ -10,7 +10,8 @@ The `ui` module exists so an app never hand-rolls the same form field, card, or
 
 A few conventions run through every component:
 
-- **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button strong>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in *one place* — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style` or raw `className`.
+- **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button strong>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in *one place* — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style`.
+- **`className` is the escape hatch.** Most components accept an optional `className`, merged *after* the classes the component computes for itself, so an app class reliably wins over the library's `@layer components` rules. It takes any `Classes` value — a string, an array, or a dictionary of `true` flags — and lands on the component's own root element. Use it for a composed one-off treatment that tokens and per-property hooks can't express (an animation, a bespoke gradient); tokens and hooks stay the primary theming surface. Formatting-only components (`<When>`, `<Prose>`, `<Scroll>`), the `*Layout` components, and `<Dialog>` deliberately don't take one — write a new layout, or style the content inside. See `ClassProps`.
 - **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like `<Card>`, `<Section>`, `<Button>`, and `<Tag>` rather than shipping their own styling.
 - **Sentence case.** Titles, headings, and button labels capitalise only the first word.
 - **Theme with CSS.** An app-wide custom look is a CSS file, not a wall of props. Write a `theme.css` that overrides the base design-token variables (and, where needed, per-component hooks) at `:root`, and import it after the library styles. The recommended workflow is to spend time tuning those variables to match your design — see [Theming](#theming) below.

package/ui/block/Address.d.ts

@@ -2,20 +2,20 @@ import type { ReactElement } from "react";
 import { type AddressData } from "../../schema/AddressSchema.js";
 import type { Nullish } from "../../util/null.js";
 import { type BlockVariants } from "../style/Block.js";
-import type { ChildProps } from "../util/props.js";
+import type { ChildProps, ClassProps } from "../util/props.js";
 /**
  * Props for `Address` — colour, space, and typography variants plus required children.
  *
  * @see https://shelving.cc/ui/AddressProps
  */
-export interface AddressProps extends BlockVariants, ChildProps {
+export interface AddressProps extends BlockVariants, ChildProps, ClassProps {
 }
 /**
  * Props for `PhysicalAddress` — an optional name and a nullable `AddressData` object.
  *
  * @see https://shelving.cc/ui/PhysicalAddressProps
  */
-export interface PhysicalAddressProps {
+export interface PhysicalAddressProps extends ClassProps {
     name?: Nullish<string>;
     address: Nullish<AddressData>;
 }
@@ -24,7 +24,7 @@ export interface PhysicalAddressProps {
  *
  * @see https://shelving.cc/ui/EmailAddressProps
  */
-export interface EmailAddressProps {
+export interface EmailAddressProps extends ClassProps {
     name?: Nullish<string>;
     email: Nullish<string>;
 }
@@ -34,7 +34,7 @@ export interface EmailAddressProps {
  * @example <Address><Strong>Acme</Strong>{"\n"}1 Example St</Address>
  * @see https://shelving.cc/ui/Address
  */
-export declare function Address({ children, ...props }: AddressProps): import("react").JSX.Element;
+export declare function Address({ children, className, ...props }: AddressProps): import("react").JSX.Element;
 /**
  * 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.
@@ -43,7 +43,7 @@ export declare function Address({ children, ...props }: AddressProps): import("r
  * @example <PhysicalAddress name="Acme" address={addressData} />
  * @see https://shelving.cc/ui/PhysicalAddress
  */
-export declare function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement;
+export declare function PhysicalAddress({ name, address, className }: PhysicalAddressProps): ReactElement;
 /**
  * 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.
@@ -52,4 +52,4 @@ export declare function PhysicalAddress({ name, address }: PhysicalAddressProps)
  * @example <EmailAddress name="Acme" email="hi@example.com" />
  * @see https://shelving.cc/ui/EmailAddress
  */
-export declare function EmailAddress({ name, email }: EmailAddressProps): ReactElement;
+export declare function EmailAddress({ name, email, className }: EmailAddressProps): ReactElement;

package/ui/block/Address.js

@@ -12,9 +12,9 @@ const ADDRESS_CLASS = getModuleClass(ADDRESS_CSS, "address");
  * @example <Address><Strong>Acme</Strong>{"\n"}1 Example St</Address>
  * @see https://shelving.cc/ui/Address
  */
-export function Address({ children, ...props }) {
+export function Address({ children, className, ...props }) {
     return (_jsx("address", { className: getClass(ADDRESS_CLASS, //
-        getBlockClass(props)), children: children }));
+        getBlockClass(props), className), children: children }));
 }
 /**
  * Show an optional `AddressData` object correctly on screen.
@@ -24,8 +24,8 @@ export function Address({ children, ...props }) {
  * @example <PhysicalAddress name="Acme" address={addressData} />
  * @see https://shelving.cc/ui/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" })] }));
+export function PhysicalAddress({ name, address, className }) {
+    return (_jsxs(Address, { className: className, 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.
@@ -35,6 +35,6 @@ export function PhysicalAddress({ name, address }) {
  * @example <EmailAddress name="Acme" email="hi@example.com" />
  * @see https://shelving.cc/ui/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" })] }));
+export function EmailAddress({ name, email, className }) {
+    return (_jsxs(Address, { className: className, 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

@@ -5,7 +5,7 @@ import { Small } from "../inline/Small.js";
 import { Strong } from "../inline/Strong.js";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { getClass, getModuleClass } from "../util/css.js";
-import type { ChildProps } from "../util/props.js";
+import type { ChildProps, ClassProps } from "../util/props.js";
 import ADDRESS_CSS from "./Address.module.css";
 
 const ADDRESS_CLASS = getModuleClass(ADDRESS_CSS, "address");
@@ -15,14 +15,14 @@ const ADDRESS_CLASS = getModuleClass(ADDRESS_CSS, "address");
  *
  * @see https://shelving.cc/ui/AddressProps
  */
-export interface AddressProps extends BlockVariants, ChildProps {}
+export interface AddressProps extends BlockVariants, ChildProps, ClassProps {}
 
 /**
  * Props for `PhysicalAddress` — an optional name and a nullable `AddressData` object.
  *
  * @see https://shelving.cc/ui/PhysicalAddressProps
  */
-export interface PhysicalAddressProps {
+export interface PhysicalAddressProps extends ClassProps {
 	name?: Nullish<string>;
 	address: Nullish<AddressData>;
 }
@@ -32,7 +32,7 @@ export interface PhysicalAddressProps {
  *
  * @see https://shelving.cc/ui/EmailAddressProps
  */
-export interface EmailAddressProps {
+export interface EmailAddressProps extends ClassProps {
 	name?: Nullish<string>;
 	email: Nullish<string>;
 }
@@ -43,12 +43,13 @@ export interface EmailAddressProps {
  * @example <Address><Strong>Acme</Strong>{"\n"}1 Example St</Address>
  * @see https://shelving.cc/ui/Address
  */
-export function Address({ children, ...props }: AddressProps) {
+export function Address({ children, className, ...props }: AddressProps) {
 	return (
 		<address
 			className={getClass(
 				ADDRESS_CLASS, //
 				getBlockClass(props),
+				className,
 			)}
 		>
 			{children}
@@ -64,9 +65,9 @@ export function Address({ children, ...props }: AddressProps) {
  * @example <PhysicalAddress name="Acme" address={addressData} />
  * @see https://shelving.cc/ui/PhysicalAddress
  */
-export function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement {
+export function PhysicalAddress({ name, address, className }: PhysicalAddressProps): ReactElement {
 	return (
-		<Address>
+		<Address className={className}>
 			{name && <Strong>{name}</Strong>}
 			{name && "\n"}
 			{address ? formatAddress(address) : <Small>No address</Small>}
@@ -82,9 +83,9 @@ export function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactE
  * @example <EmailAddress name="Acme" email="hi@example.com" />
  * @see https://shelving.cc/ui/EmailAddress
  */
-export function EmailAddress({ name, email }: EmailAddressProps): ReactElement {
+export function EmailAddress({ name, email, className }: EmailAddressProps): ReactElement {
 	return (
-		<Address>
+		<Address className={className}>
 			{name && <Strong>{name}</Strong>}
 			{name && "\n"}
 			{email ? <a href={`mailto:${email}`}>{email}</a> : <Small>No email</Small>}

package/ui/block/Block.d.ts

@@ -1,6 +1,6 @@
 import type { ReactElement } from "react";
 import { type BlockVariants } from "../style/Block.js";
-import type { OptionalChildProps } from "../util/props.js";
+import type { ClassProps, OptionalChildProps } from "../util/props.js";
 /**
  * Semantic element names a block element may render as via its `as` prop.
  *
@@ -12,7 +12,7 @@ export type BlockElement = "div" | "section" | "header" | "footer" | "article" |
  *
  * @see https://shelving.cc/ui/BlockProps
  */
-export interface BlockProps extends BlockVariants, OptionalChildProps {
+export interface BlockProps extends BlockVariants, OptionalChildProps, ClassProps {
     /**
      * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
      * @default "div"
@@ -27,4 +27,4 @@ export interface BlockProps extends BlockVariants, OptionalChildProps {
  * @example <Block as="aside" width="narrow"><Paragraph>Sidebar</Paragraph></Block>
  * @see https://shelving.cc/ui/Block
  */
-export declare function Block({ as: Element, children, ...props }: BlockProps): ReactElement;
+export declare function Block({ as: Element, children, className, ...props }: BlockProps): ReactElement;

package/ui/block/Block.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { getBlockClass } from "../style/Block.js";
+import { getClass } from "../util/css.js";
 /**
  * Plain `<div>` block with block-level spacing.
  * - Pass `as` to render a different semantic element (`section`, `header`, `footer`, `nav`, `aside`, `figure`).
@@ -8,6 +9,6 @@ import { getBlockClass } from "../style/Block.js";
  * @example <Block as="aside" width="narrow"><Paragraph>Sidebar</Paragraph></Block>
  * @see https://shelving.cc/ui/Block
  */
-export function Block({ as: Element = "div", children, ...props }) {
-    return _jsx(Element, { className: getBlockClass(props), children: children });
+export function Block({ as: Element = "div", children, className, ...props }) {
+    return _jsx(Element, { className: getClass(getBlockClass(props), className), children: children });
 }

package/ui/block/Block.tsx

@@ -1,6 +1,7 @@
 import type { ReactElement } from "react";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
-import type { OptionalChildProps } from "../util/props.js";
+import { getClass } from "../util/css.js";
+import type { ClassProps, OptionalChildProps } from "../util/props.js";
 
 /**
  * Semantic element names a block element may render as via its `as` prop.
@@ -14,7 +15,7 @@ export type BlockElement = "div" | "section" | "header" | "footer" | "article" |
  *
  * @see https://shelving.cc/ui/BlockProps
  */
-export interface BlockProps extends BlockVariants, OptionalChildProps {
+export interface BlockProps extends BlockVariants, OptionalChildProps, ClassProps {
 	/**
 	 * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
 	 * @default "div"
@@ -30,6 +31,6 @@ export interface BlockProps extends BlockVariants, OptionalChildProps {
  * @example <Block as="aside" width="narrow"><Paragraph>Sidebar</Paragraph></Block>
  * @see https://shelving.cc/ui/Block
  */
-export function Block({ as: Element = "div", children, ...props }: BlockProps): ReactElement {
-	return <Element className={getBlockClass(props)}>{children}</Element>;
+export function Block({ as: Element = "div", children, className, ...props }: BlockProps): ReactElement {
+	return <Element className={getClass(getBlockClass(props), className)}>{children}</Element>;
 }

package/ui/block/Blockquote.d.ts

@@ -1,12 +1,12 @@
 import type { ReactElement } from "react";
 import { type BlockVariants } from "../style/Block.js";
-import type { OptionalChildProps } from "../util/props.js";
+import type { ClassProps, OptionalChildProps } from "../util/props.js";
 /**
  * Props for `Blockquote` — colour, space, and typography variants plus optional children.
  *
  * @see https://shelving.cc/ui/BlockquoteProps
  */
-export interface BlockquoteProps extends BlockVariants, OptionalChildProps {
+export interface BlockquoteProps extends BlockVariants, OptionalChildProps, ClassProps {
 }
 /**
  * Quoted block of text — rendered as `<blockquote>`.
@@ -15,4 +15,4 @@ export interface BlockquoteProps extends BlockVariants, OptionalChildProps {
  * @example <Blockquote>To be or not to be.</Blockquote>
  * @see https://shelving.cc/ui/Blockquote
  */
-export declare function Blockquote({ children, ...props }: BlockquoteProps): ReactElement;
+export declare function Blockquote({ children, className, ...props }: BlockquoteProps): ReactElement;

package/ui/block/Blockquote.js

@@ -10,7 +10,7 @@ const BLOCKQUOTE_CLASS = getModuleClass(BLOCKQUOTE_CSS, "blockquote");
  * @example <Blockquote>To be or not to be.</Blockquote>
  * @see https://shelving.cc/ui/Blockquote
  */
-export function Blockquote({ children, ...props }) {
+export function Blockquote({ children, className, ...props }) {
     return (_jsx("blockquote", { className: getClass(BLOCKQUOTE_CLASS, //
-        getBlockClass(props)), children: children }));
+        getBlockClass(props), className), children: children }));
 }

package/ui/block/Blockquote.tsx

@@ -1,7 +1,7 @@
 import type { ReactElement } from "react";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { getClass, getModuleClass } from "../util/css.js";
-import type { OptionalChildProps } from "../util/props.js";
+import type { ClassProps, OptionalChildProps } from "../util/props.js";
 import BLOCKQUOTE_CSS from "./Blockquote.module.css";
 
 const BLOCKQUOTE_CLASS = getModuleClass(BLOCKQUOTE_CSS, "blockquote");
@@ -11,7 +11,7 @@ const BLOCKQUOTE_CLASS = getModuleClass(BLOCKQUOTE_CSS, "blockquote");
  *
  * @see https://shelving.cc/ui/BlockquoteProps
  */
-export interface BlockquoteProps extends BlockVariants, OptionalChildProps {}
+export interface BlockquoteProps extends BlockVariants, OptionalChildProps, ClassProps {}
 
 /**
  * Quoted block of text — rendered as `<blockquote>`.
@@ -20,12 +20,13 @@ export interface BlockquoteProps extends BlockVariants, OptionalChildProps {}
  * @example <Blockquote>To be or not to be.</Blockquote>
  * @see https://shelving.cc/ui/Blockquote
  */
-export function Blockquote({ children, ...props }: BlockquoteProps): ReactElement {
+export function Blockquote({ children, className, ...props }: BlockquoteProps): ReactElement {
 	return (
 		<blockquote
 			className={getClass(
 				BLOCKQUOTE_CLASS, //
 				getBlockClass(props),
+				className,
 			)}
 		>
 			{children}

package/ui/block/Caption.d.ts

@@ -1,12 +1,12 @@
 import type { ReactElement } from "react";
 import { type BlockVariants } from "../style/Block.js";
-import type { OptionalChildProps } from "../util/index.js";
+import type { ClassProps, OptionalChildProps } from "../util/index.js";
 /**
  * Props for `Caption` — colour, space, and typography variants plus optional children.
  *
  * @see https://shelving.cc/ui/CaptionProps
  */
-export interface CaptionProps extends BlockVariants, OptionalChildProps {
+export interface CaptionProps extends BlockVariants, OptionalChildProps, ClassProps {
 }
 /**
  * `<figcaption>` block — caption text for a `<Figure>`.
@@ -15,4 +15,4 @@ export interface CaptionProps extends BlockVariants, OptionalChildProps {
  * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
  * @see https://shelving.cc/ui/Caption
  */
-export declare function Caption({ children, ...props }: CaptionProps): ReactElement;
+export declare function Caption({ children, className, ...props }: CaptionProps): ReactElement;

package/ui/block/Caption.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { getBlockClass } from "../style/Block.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import CAPTION_CSS from "./Caption.module.css";
-const CAPTION_CLASS = getModuleClass(CAPTION_CSS, "divider");
+const CAPTION_CLASS = getModuleClass(CAPTION_CSS, "caption");
 /**
  * `<figcaption>` block — caption text for a `<Figure>`.
  *
@@ -10,7 +10,7 @@ const CAPTION_CLASS = getModuleClass(CAPTION_CSS, "divider");
  * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
  * @see https://shelving.cc/ui/Caption
  */
-export function Caption({ children, ...props }) {
+export function Caption({ children, className, ...props }) {
     return (_jsx("figcaption", { className: getClass(CAPTION_CLASS, //
-        getBlockClass(props)), children: children }));
+        getBlockClass(props), className), children: children }));
 }

package/ui/block/Caption.tsx

@@ -1,17 +1,17 @@
 import type { ReactElement } from "react";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { getClass, getModuleClass } from "../util/css.js";
-import type { OptionalChildProps } from "../util/index.js";
+import type { ClassProps, OptionalChildProps } from "../util/index.js";
 import CAPTION_CSS from "./Caption.module.css";
 
-const CAPTION_CLASS = getModuleClass(CAPTION_CSS, "divider");
+const CAPTION_CLASS = getModuleClass(CAPTION_CSS, "caption");
 
 /**
  * Props for `Caption` — colour, space, and typography variants plus optional children.
  *
  * @see https://shelving.cc/ui/CaptionProps
  */
-export interface CaptionProps extends BlockVariants, OptionalChildProps {}
+export interface CaptionProps extends BlockVariants, OptionalChildProps, ClassProps {}
 
 /**
  * `<figcaption>` block — caption text for a `<Figure>`.
@@ -20,12 +20,13 @@ export interface CaptionProps extends BlockVariants, OptionalChildProps {}
  * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
  * @see https://shelving.cc/ui/Caption
  */
-export function Caption({ children, ...props }: CaptionProps): ReactElement {
+export function Caption({ children, className, ...props }: CaptionProps): ReactElement {
 	return (
 		<figcaption
 			className={getClass(
 				CAPTION_CLASS, //
 				getBlockClass(props),
+				className,
 			)}
 		>
 			{children}

package/ui/block/Card.d.ts

@@ -3,13 +3,14 @@ import { type ClickableProps } from "../button/Clickable.js";
 import { type BlockVariants } from "../style/Block.js";
 import { type ShadowVariants } from "../style/Shadow.js";
 import { type StatusVariants } from "../style/Status.js";
+import type { ClassProps } from "../util/props.js";
 import type { BlockElement } from "./Block.js";
 /**
  * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, width, and shadow variants.
  *
  * @see https://shelving.cc/ui/CardProps
  */
-export interface CardProps extends ClickableProps, StatusVariants, BlockVariants, ShadowVariants {
+export interface CardProps extends ClickableProps, StatusVariants, BlockVariants, ShadowVariants, ClassProps {
     /**
      * Element this `<Card>` renders as, e.g. "header" to output a "<header>"
      * @default "article"
@@ -27,4 +28,4 @@ export interface CardProps extends ClickableProps, StatusVariants, BlockVariants
  * @kind component
  * @see https://shelving.cc/ui/Card
  */
-export declare function Card({ as: Element, children, href, onClick, title, ...props }: CardProps): ReactElement;
+export declare function Card({ as: Element, children, href, onClick, title, className, ...props }: CardProps): ReactElement;

package/ui/block/Card.js

@@ -16,8 +16,8 @@ import CARD_CSS from "./Card.module.css";
  * @kind component
  * @see https://shelving.cc/ui/Card
  */
-export function Card({ as: Element = "article", children, href, onClick, title = "Open", ...props }) {
+export function Card({ as: Element = "article", children, href, onClick, title = "Open", className, ...props }) {
     const overlay = (href || onClick) && (_jsx(Clickable, { title: title, href: href, onClick: onClick, ...props, className: getModuleClass(CARD_CSS, "overlay") }));
     return (_jsxs(Element, { className: getClass(getModuleClass(CARD_CSS, "card"), //
-        getStatusClass(props), getBlockClass(props), getShadowClass(props)), children: [overlay, overlay ? _jsx("div", { children: children }) : children] }));
+        getStatusClass(props), getBlockClass(props), getShadowClass(props), className), children: [overlay, overlay ? _jsx("div", { children: children }) : children] }));
 }

package/ui/block/Card.tsx

@@ -4,6 +4,7 @@ import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { getShadowClass, type ShadowVariants } from "../style/Shadow.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getClass, getModuleClass } from "../util/css.js";
+import type { ClassProps } from "../util/props.js";
 import type { BlockElement } from "./Block.js";
 import CARD_CSS from "./Card.module.css";
 
@@ -12,7 +13,7 @@ import CARD_CSS from "./Card.module.css";
  *
  * @see https://shelving.cc/ui/CardProps
  */
-export interface CardProps extends ClickableProps, StatusVariants, BlockVariants, ShadowVariants {
+export interface CardProps extends ClickableProps, StatusVariants, BlockVariants, ShadowVariants, ClassProps {
 	/**
 	 * Element this `<Card>` renders as, e.g. "header" to output a "<header>"
 	 * @default "article"
@@ -31,7 +32,7 @@ export interface CardProps extends ClickableProps, StatusVariants, BlockVariants
  * @kind component
  * @see https://shelving.cc/ui/Card
  */
-export function Card({ as: Element = "article", children, href, onClick, title = "Open", ...props }: CardProps): ReactElement {
+export function Card({ as: Element = "article", children, href, onClick, title = "Open", className, ...props }: CardProps): ReactElement {
 	const overlay = (href || onClick) && (
 		<Clickable title={title} href={href} onClick={onClick} {...props} className={getModuleClass(CARD_CSS, "overlay")} />
 	);
@@ -42,6 +43,7 @@ export function Card({ as: Element = "article", children, href, onClick, title =
 				getStatusClass(props),
 				getBlockClass(props),
 				getShadowClass(props),
+				className,
 			)}
 		>
 			{overlay}

package/ui/block/Column.d.ts

@@ -1,14 +1,14 @@
 import type { ReactElement } from "react";
 import { type BlockVariants } from "../style/Block.js";
 import { type FlexVariants } from "../style/Flex.js";
-import type { OptionalChildProps } from "../util/index.js";
+import type { ClassProps, OptionalChildProps } from "../util/index.js";
 import type { BlockElement } from "./Block.js";
 /**
  * Props for the `<Column>` component.
  *
  * @see https://shelving.cc/ui/ColumnProps
  */
-export interface ColumnProps extends BlockVariants, FlexVariants, OptionalChildProps {
+export interface ColumnProps extends BlockVariants, FlexVariants, OptionalChildProps, ClassProps {
     /**
      * Element this `<Column>` renders as, e.g. "header" to output a "<header>"
      * @default "div"
@@ -22,4 +22,4 @@ export interface ColumnProps extends BlockVariants, FlexVariants, OptionalChildP
  * @example <Column gap="small">{items}</Column>
  * @see https://shelving.cc/ui/Column
  */
-export declare function Column({ as: Element, children, column, ...props }: ColumnProps): ReactElement;
+export declare function Column({ as: Element, children, column, className, ...props }: ColumnProps): ReactElement;

package/ui/block/Column.js

@@ -9,7 +9,7 @@ import { getClass } from "../util/css.js";
  * @example <Column gap="small">{items}</Column>
  * @see https://shelving.cc/ui/Column
  */
-export function Column({ as: Element = "div", children, column = true, ...props }) {
+export function Column({ as: Element = "div", children, column = true, className, ...props }) {
     return (_jsx(Element, { className: getClass(getBlockClass(props), //
-        getFlexClass({ column, ...props })), children: children }));
+        getFlexClass({ column, ...props }), className), children: children }));
 }

package/ui/block/Column.tsx

@@ -2,7 +2,7 @@ import type { ReactElement } from "react";
 import { type BlockVariants, getBlockClass } from "../style/Block.js";
 import { type FlexVariants, getFlexClass } from "../style/Flex.js";
 import { getClass } from "../util/css.js";
-import type { OptionalChildProps } from "../util/index.js";
+import type { ClassProps, OptionalChildProps } from "../util/index.js";
 import type { BlockElement } from "./Block.js";
 
 /**
@@ -10,7 +10,7 @@ import type { BlockElement } from "./Block.js";
  *
  * @see https://shelving.cc/ui/ColumnProps
  */
-export interface ColumnProps extends BlockVariants, FlexVariants, OptionalChildProps {
+export interface ColumnProps extends BlockVariants, FlexVariants, OptionalChildProps, ClassProps {
 	/**
 	 * Element this `<Column>` renders as, e.g. "header" to output a "<header>"
 	 * @default "div"
@@ -25,12 +25,13 @@ export interface ColumnProps extends BlockVariants, FlexVariants, OptionalChildP
  * @example <Column gap="small">{items}</Column>
  * @see https://shelving.cc/ui/Column
  */
-export function Column({ as: Element = "div", children, column = true, ...props }: ColumnProps): ReactElement {
+export function Column({ as: Element = "div", children, column = true, className, ...props }: ColumnProps): ReactElement {
 	return (
 		<Element
 			className={getClass(
 				getBlockClass(props), //
 				getFlexClass({ column, ...props }),
+				className,
 			)}
 		>
 			{children}

package/ui/block/Definitions.d.ts

@@ -2,13 +2,13 @@ import type { ReactElement } from "react";
 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";
+import type { ClassProps, OptionalChildProps } from "../util/props.js";
 /**
  * Props for `Definitions` — colour, gap, space, and typography variants plus optional children.
  *
  * @see https://shelving.cc/ui/DefinitionsProps
  */
-export interface DefinitionsProps extends GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {
+export interface DefinitionsProps extends GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps, ClassProps {
 }
 /**
  * Description list — a sequence of term/value pairs rendered as a `<dl>`.
@@ -19,4 +19,4 @@ export interface DefinitionsProps extends GapVariants, SpaceVariants, Typography
  * @example <Definitions><dt>Name</dt><dd>Acme</dd></Definitions>
  * @see https://shelving.cc/ui/Definitions
  */
-export declare function Definitions({ children, ...props }: DefinitionsProps): ReactElement;
+export declare function Definitions({ children, className, ...props }: DefinitionsProps): ReactElement;

package/ui/block/Definitions.js

@@ -12,7 +12,7 @@ const DEFINITIONS_CLASS = getModuleClass(DEFINITIONS_CSS, "definitions");
  * @example <Definitions><dt>Name</dt><dd>Acme</dd></Definitions>
  * @see https://shelving.cc/ui/Definitions
  */
-export function Definitions({ children, ...props }) {
+export function Definitions({ children, className, ...props }) {
     return (_jsx("dl", { className: getClass(DEFINITIONS_CLASS, //
-        getBlockClass(props)), children: children }));
+        getBlockClass(props), className), children: children }));
 }

package/ui/block/Definitions.tsx

@@ -4,7 +4,7 @@ import type { GapVariants } from "../style/Gap.js";
 import type { SpaceVariants } from "../style/Space.js";
 import type { TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
-import type { OptionalChildProps } from "../util/props.js";
+import type { ClassProps, OptionalChildProps } from "../util/props.js";
 import DEFINITIONS_CSS from "./Definitions.module.css";
 
 const DEFINITIONS_CLASS = getModuleClass(DEFINITIONS_CSS, "definitions");
@@ -14,7 +14,7 @@ const DEFINITIONS_CLASS = getModuleClass(DEFINITIONS_CSS, "definitions");
  *
  * @see https://shelving.cc/ui/DefinitionsProps
  */
-export interface DefinitionsProps extends GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps {}
+export interface DefinitionsProps extends GapVariants, SpaceVariants, TypographyVariants, OptionalChildProps, ClassProps {}
 
 /**
  * Description list — a sequence of term/value pairs rendered as a `<dl>`.
@@ -25,12 +25,13 @@ export interface DefinitionsProps extends GapVariants, SpaceVariants, Typography
  * @example <Definitions><dt>Name</dt><dd>Acme</dd></Definitions>
  * @see https://shelving.cc/ui/Definitions
  */
-export function Definitions({ children, ...props }: DefinitionsProps): ReactElement {
+export function Definitions({ children, className, ...props }: DefinitionsProps): ReactElement {
 	return (
 		<dl
 			className={getClass(
 				DEFINITIONS_CLASS, //
 				getBlockClass(props),
+				className,
 			)}
 		>
 			{children}

package/ui/block/Details.d.ts

@@ -1,7 +1,8 @@
 import type { ReactElement, ReactNode } from "react";
 import { type BlockVariants } from "../style/Block.js";
+import type { ClassProps } from "../util/props.js";
 /** Props for `DetailsItem` — a single collapsible disclosure. */
-export interface DetailsProps extends BlockVariants {
+export interface DetailsProps extends BlockVariants, ClassProps {
     /** Content of the always-visible summary (e.g. a question). */
     title: ReactNode;
     /** Whether the item starts expanded. */
@@ -18,4 +19,4 @@ export interface DetailsProps extends BlockVariants {
  *
  * @kind component
  */
-export declare function Details({ title, open, name, children, ...props }: DetailsProps): ReactElement;
+export declare function Details({ title, open, name, children, className, ...props }: DetailsProps): ReactElement;

package/ui/block/Details.js

@@ -12,6 +12,6 @@ const DETAILS_SUMMARY_CLASS = DETAILS_CSS.summary;
  *
  * @kind component
  */
-export function Details({ title, open = false, name, children, ...props }) {
-    return (_jsxs("details", { className: getClass(DETAILS_CLASS, getBlockClass(props)), open: open, name: name, children: [_jsxs("summary", { className: DETAILS_SUMMARY_CLASS, children: [_jsx("span", { children: title }), _jsx(ChevronUpIcon, {})] }), children] }));
+export function Details({ title, open = false, name, children, className, ...props }) {
+    return (_jsxs("details", { className: getClass(DETAILS_CLASS, getBlockClass(props), className), open: open, name: name, children: [_jsxs("summary", { className: DETAILS_SUMMARY_CLASS, children: [_jsx("span", { children: title }), _jsx(ChevronUpIcon, {})] }), children] }));
 }