shelving 1.242.1 → 1.244.0

package/extract/TypescriptExtractor.js

@@ -56,9 +56,9 @@ function _mergeOverloads(existing, next) {
         // Keep first content encountered; fill in if `existing` had none.
         content: a.content ?? b.content,
         // Append incoming entries, skipping any already present (by field identity), preserving insertion order.
-        // Identity: signatures/examples/throws by rendered string; params by (name, type, description, optional); returns by (type, description).
+        // Identity: signatures/examples/throws by rendered string; params by (name, type, description, optional, default); returns by (type, description).
         signatures: _concatUnique(a.signatures, b.signatures, s => s),
-        params: _concatUnique(a.params, b.params, p => `${p.name}\0${p.type}\0${p.description}\0${p.optional}`),
+        params: _concatUnique(a.params, b.params, p => `${p.name}\0${p.type}\0${p.description}\0${p.optional}\0${p.default}`),
         returns: _concatUnique(a.returns, b.returns, r => `${r.type}\0${r.description}`),
         throws: _concatUnique(a.throws, b.throws, t => `${t.type}\0${t.description}`),
         examples: _concatUnique(a.examples, b.examples, e => e.description ?? ""),
@@ -260,7 +260,8 @@ function _getParams(statement, source, jsDocParams) {
         const type = p.type?.getText(source);
         const optional = !!p.questionToken || !!p.initializer;
         const description = jsDocParams?.find(d => d.name === name)?.description;
-        return { name, type, description, optional };
+        const def = p.initializer?.getText(source);
+        return { name, type, description, optional, default: def };
     });
     return params.length ? params : undefined;
 }
@@ -279,9 +280,10 @@ function _getConstructorParams(statement, source, classJsDocParams) {
             const optional = !!p.questionToken || !!p.initializer;
             // Constructor-level `@param` wins over the class-level `@param` on collision.
             const description = ctorJsDocParams?.find(d => d.name === name)?.description ?? classJsDocParams?.find(d => d.name === name)?.description;
-            return { name, type, description, optional };
+            const def = p.initializer?.getText(source);
+            return { name, type, description, optional, default: def };
         });
-        params = _concatUnique(params, next, p => `${p.name}\0${p.type}\0${p.description}\0${p.optional}`);
+        params = _concatUnique(params, next, p => `${p.name}\0${p.type}\0${p.description}\0${p.optional}\0${p.default}`);
     }
     return params?.length ? params : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.242.1",
+	"version": "1.244.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/README.md

@@ -10,7 +10,7 @@ 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"`) and boolean props for on/off variants (`<Button strong>`, `<Section narrow>`, `<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` or raw `className`.
 - **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like [`Card`](/ui/Card), [`Section`](/ui/Section), [`Button`](/ui/Button), and [`Tag`](/ui/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/app/App.md

@@ -15,7 +15,7 @@ function HelloApp() {
   return (
     <App app="My app">
       <CenteredLayout>
-        <Section narrow>
+        <Section width="narrow">
           <Title>Hello</Title>
           <Paragraph>Welcome to the app.</Paragraph>
         </Section>

package/ui/block/Block.d.ts

@@ -34,7 +34,7 @@ export declare function getBlockClass(variants: BlockProps): string;
  * - 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>
+ * @example <Block as="aside" width="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

@@ -25,7 +25,7 @@ export function getBlockClass(variants) {
  * - 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>
+ * @example <Block as="aside" width="narrow"><Paragraph>Sidebar</Paragraph></Block>
  * @see https://dhoulb.github.io/shelving/ui/block/Block/Block
  */
 export function Block({ as: Component = "div", children, ...props }) {

package/ui/block/Block.tsx

@@ -52,7 +52,7 @@ export function getBlockClass(variants: BlockProps): string {
  * - 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>
+ * @example <Block as="aside" width="narrow"><Paragraph>Sidebar</Paragraph></Block>
  * @see https://dhoulb.github.io/shelving/ui/block/Block/Block
  */
 export function Block({ as: Component = "div", children, ...props }: BlockProps): ReactElement {

package/ui/block/Card.js

@@ -21,6 +21,6 @@ import CARD_CSS from "./Card.module.css";
  * @see https://dhoulb.github.io/shelving/ui/block/Card/Card
  */
 export function Card({ children, href, onClick, title = "Open", ...props }) {
-    const overlay = (href || onClick) && _jsx(Clickable, { title: title, href: href, onClick: onClick, ...props, className: CARD_CSS.overlay });
+    const overlay = (href || onClick) && (_jsx(Clickable, { title: title, href: href, onClick: onClick, ...props, className: getModuleClass(CARD_CSS, "overlay") }));
     return (_jsxs("article", { className: getClass(getModuleClass(CARD_CSS, "card"), getStatusClass(props), getColorClass(props), getPaddingClass(props), getSpaceClass(props), getTypographyClass(props), getWidthClass(props)), children: [overlay, overlay ? _jsx("div", { children: children }) : children] }));
 }

package/ui/block/Card.tsx

@@ -36,7 +36,9 @@ export interface CardProps
  * @see https://dhoulb.github.io/shelving/ui/block/Card/Card
  */
 export function Card({ children, href, onClick, title = "Open", ...props }: CardProps): ReactElement {
-	const overlay = (href || onClick) && <Clickable title={title} href={href} onClick={onClick} {...props} className={CARD_CSS.overlay} />;
+	const overlay = (href || onClick) && (
+		<Clickable title={title} href={href} onClick={onClick} {...props} className={getModuleClass(CARD_CSS, "overlay")} />
+	);
 	return (
 		<article
 			className={getClass(

package/ui/block/Image.d.ts

@@ -15,7 +15,7 @@ export interface ImageProps extends SpaceVariants, WidthVariants {
  *
  * @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" />
+ * @example <Image src="/logo.png" alt="Logo" width="narrow" />
  * @see https://dhoulb.github.io/shelving/ui/block/Image/Image
  */
 export declare function Image({ src, alt, ...variants }: ImageProps): ReactElement;

package/ui/block/Image.js

@@ -9,7 +9,7 @@ const IMAGE_CLASS = getModuleClass(styles, "image");
  *
  * @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" />
+ * @example <Image src="/logo.png" alt="Logo" width="narrow" />
  * @see https://dhoulb.github.io/shelving/ui/block/Image/Image
  */
 export function Image({ src, alt, ...variants }) {

package/ui/block/Image.tsx

@@ -21,7 +21,7 @@ export interface ImageProps extends SpaceVariants, WidthVariants {
  *
  * @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" />
+ * @example <Image src="/logo.png" alt="Logo" width="narrow" />
  * @see https://dhoulb.github.io/shelving/ui/block/Image/Image
  */
 export function Image({ src, alt, ...variants }: ImageProps): ReactElement {

package/ui/block/Panel.d.ts

@@ -27,7 +27,7 @@ export interface PanelProps extends ColorVariants, PaddingVariants, StatusVarian
  * @kind component
  * @param props Colour, padding, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
- * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
+ * @example <Panel><Block width="narrow"><Title>Welcome</Title></Block></Panel>
  * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */

package/ui/block/Panel.js

@@ -16,7 +16,7 @@ const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
  * @kind component
  * @param props Colour, padding, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
- * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
+ * @example <Panel><Block width="narrow"><Title>Welcome</Title></Block></Panel>
  * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */

package/ui/block/Panel.md

@@ -4,7 +4,7 @@ A full-width vertical region that paints the current surface colour. Use panels
 
 **Things to know:**
 
-- A panel always spans the full width of its container. To constrain the content inside, compose a [`Block`](/ui/Block) `narrow` (or `wide`) within it.
+- A panel always spans the full width of its container. To constrain the content inside, compose a [`Block`](/ui/Block) `width="narrow"` (or `width="wide"`) within it.
 - Block margin is always zero so panels stack flush; control the vertical breathing room with the `padding` variant (`<Panel padding="large">`, `<Panel padding="none">`). Inline padding is fixed.
 - `color=` / `status=` move the tint anchor for the whole panel scope, so the surface, border, and text re-derive together and cascade into nested content.
 - The top and bottom borders are dropped on the first and last panel so the page doesn't gain stray edge lines.
@@ -17,12 +17,12 @@ A full-width vertical region that paints the current surface colour. Use panels
 import { Panel, Block, Title, Paragraph } from "shelving/ui";
 
 <Panel as="header" color="primary">
-  <Block narrow>
+  <Block width="narrow">
     <Title>Welcome</Title>
   </Block>
 </Panel>
 <Panel padding="large">
-  <Block narrow>
+  <Block width="narrow">
     <Paragraph>Each panel is a full-width band; the inner block constrains the content.</Paragraph>
   </Block>
 </Panel>

package/ui/block/Panel.tsx

@@ -33,7 +33,7 @@ export interface PanelProps extends ColorVariants, PaddingVariants, StatusVarian
  * @kind component
  * @param props Colour, padding, status, and typography variants plus `children`.
  * @returns Rendered full-width panel region.
- * @example <Panel><Block narrow><Title>Welcome</Title></Block></Panel>
+ * @example <Panel><Block width="narrow"><Title>Welcome</Title></Block></Panel>
  * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */

package/ui/block/Prose.js

@@ -9,7 +9,7 @@ import SMALL_CSS from "../inline/Small.module.css";
 import STRONG_CSS from "../inline/Strong.module.css";
 import SUBSCRIPT_CSS from "../inline/Subscript.module.css";
 import SUPERSCRIPT_CSS from "../inline/Superscript.module.css";
-import { getClass } from "../util/css.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import ADDRESS_CSS from "./Address.module.css";
 import BLOCKQUOTE_CSS from "./Blockquote.module.css";
 import CAPTION_CSS from "./Caption.module.css";
@@ -25,7 +25,7 @@ import SUBHEADING_CSS from "./Subheading.module.css";
 import TABLE_CSS from "./Table.module.css";
 import TITLE_CSS from "./Title.module.css";
 // Combine the `.prose` class from every block and inline component's CSS module into a single string.
-const PROSE_STYLES = getClass(PARAGRAPH_CSS.prose, HEADING_CSS.prose, SUBHEADING_CSS.prose, ADDRESS_CSS.prose, BLOCKQUOTE_CSS.prose, SECTION_CSS.prose, CODE_CSS.prose, DEFINITIONS_CSS.prose, DELETED_CSS.prose, EMPHASIS_CSS.prose, IMAGE_CSS.prose, INSERTED_CSS.prose, CAPTION_CSS.prose, LIST_CSS.prose, TITLE_CSS.prose, LINK_CSS.prose, MARK_CSS.prose, PREFORMATTED_CSS.prose, SMALL_CSS.prose, STRONG_CSS.prose, SUBSCRIPT_CSS.prose, SUPERSCRIPT_CSS.prose, TABLE_CSS.prose, DIVIDER_CSS.prose);
+const PROSE_STYLES = getClass(getModuleClass(PARAGRAPH_CSS, "prose"), getModuleClass(HEADING_CSS, "prose"), getModuleClass(SUBHEADING_CSS, "prose"), getModuleClass(ADDRESS_CSS, "prose"), getModuleClass(BLOCKQUOTE_CSS, "prose"), getModuleClass(SECTION_CSS, "prose"), getModuleClass(CODE_CSS, "prose"), getModuleClass(DEFINITIONS_CSS, "prose"), getModuleClass(DELETED_CSS, "prose"), getModuleClass(EMPHASIS_CSS, "prose"), getModuleClass(IMAGE_CSS, "prose"), getModuleClass(INSERTED_CSS, "prose"), getModuleClass(CAPTION_CSS, "prose"), getModuleClass(LIST_CSS, "prose"), getModuleClass(TITLE_CSS, "prose"), getModuleClass(LINK_CSS, "prose"), getModuleClass(MARK_CSS, "prose"), getModuleClass(PREFORMATTED_CSS, "prose"), getModuleClass(SMALL_CSS, "prose"), getModuleClass(STRONG_CSS, "prose"), getModuleClass(SUBSCRIPT_CSS, "prose"), getModuleClass(SUPERSCRIPT_CSS, "prose"), getModuleClass(TABLE_CSS, "prose"), getModuleClass(DIVIDER_CSS, "prose"));
 /**
  * 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.

package/ui/block/Prose.tsx

@@ -9,7 +9,7 @@ import SMALL_CSS from "../inline/Small.module.css";
 import STRONG_CSS from "../inline/Strong.module.css";
 import SUBSCRIPT_CSS from "../inline/Subscript.module.css";
 import SUPERSCRIPT_CSS from "../inline/Superscript.module.css";
-import { getClass } from "../util/css.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import ADDRESS_CSS from "./Address.module.css";
 import BLOCKQUOTE_CSS from "./Blockquote.module.css";
@@ -28,30 +28,30 @@ import TITLE_CSS from "./Title.module.css";
 
 // Combine the `.prose` class from every block and inline component's CSS module into a single string.
 const PROSE_STYLES = getClass(
-	PARAGRAPH_CSS.prose,
-	HEADING_CSS.prose,
-	SUBHEADING_CSS.prose,
-	ADDRESS_CSS.prose,
-	BLOCKQUOTE_CSS.prose,
-	SECTION_CSS.prose,
-	CODE_CSS.prose,
-	DEFINITIONS_CSS.prose,
-	DELETED_CSS.prose,
-	EMPHASIS_CSS.prose,
-	IMAGE_CSS.prose,
-	INSERTED_CSS.prose,
-	CAPTION_CSS.prose,
-	LIST_CSS.prose,
-	TITLE_CSS.prose,
-	LINK_CSS.prose,
-	MARK_CSS.prose,
-	PREFORMATTED_CSS.prose,
-	SMALL_CSS.prose,
-	STRONG_CSS.prose,
-	SUBSCRIPT_CSS.prose,
-	SUPERSCRIPT_CSS.prose,
-	TABLE_CSS.prose,
-	DIVIDER_CSS.prose,
+	getModuleClass(PARAGRAPH_CSS, "prose"),
+	getModuleClass(HEADING_CSS, "prose"),
+	getModuleClass(SUBHEADING_CSS, "prose"),
+	getModuleClass(ADDRESS_CSS, "prose"),
+	getModuleClass(BLOCKQUOTE_CSS, "prose"),
+	getModuleClass(SECTION_CSS, "prose"),
+	getModuleClass(CODE_CSS, "prose"),
+	getModuleClass(DEFINITIONS_CSS, "prose"),
+	getModuleClass(DELETED_CSS, "prose"),
+	getModuleClass(EMPHASIS_CSS, "prose"),
+	getModuleClass(IMAGE_CSS, "prose"),
+	getModuleClass(INSERTED_CSS, "prose"),
+	getModuleClass(CAPTION_CSS, "prose"),
+	getModuleClass(LIST_CSS, "prose"),
+	getModuleClass(TITLE_CSS, "prose"),
+	getModuleClass(LINK_CSS, "prose"),
+	getModuleClass(MARK_CSS, "prose"),
+	getModuleClass(PREFORMATTED_CSS, "prose"),
+	getModuleClass(SMALL_CSS, "prose"),
+	getModuleClass(STRONG_CSS, "prose"),
+	getModuleClass(SUBSCRIPT_CSS, "prose"),
+	getModuleClass(SUPERSCRIPT_CSS, "prose"),
+	getModuleClass(TABLE_CSS, "prose"),
+	getModuleClass(DIVIDER_CSS, "prose"),
 );
 
 /**

package/ui/block/Section.d.ts

@@ -76,7 +76,7 @@ export declare function Nav(props: SectionProps): ReactElement;
  * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<aside>` element.
- * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
+ * @example <Aside width="narrow"><Paragraph>Sidebar</Paragraph></Aside>
  * @see https://dhoulb.github.io/shelving/ui/block/Section/Aside
  */
 export declare function Aside(props: SectionProps): ReactElement;

package/ui/block/Section.js

@@ -77,7 +77,7 @@ export function Nav(props) {
  * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<aside>` element.
- * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
+ * @example <Aside width="narrow"><Paragraph>Sidebar</Paragraph></Aside>
  * @see https://dhoulb.github.io/shelving/ui/block/Section/Aside
  */
 export function Aside(props) {

package/ui/block/Section.md

@@ -6,7 +6,7 @@ A landmark content region — renders a `<section>` with block-level spacing and
 
 - Pick the component whose HTML element matches the semantic meaning rather than reaching for a generic [`Block`](/ui/Block). `<Section>` is a `<section>`, `<Nav>` a `<nav>`, `<Figure>` a `<figure>`, and so on.
 - Every section centres its content and caps the line length so text never touches the viewport edges. Nested sections relax that cap so they can fill their parent.
-- Pass `narrow` / `wide` / `full` to constrain or unconstrain the width, and the usual `color` / `space` / typography variants to retint and respace.
+- Sections default to the `--width-normal` content width, so most of the time you set no width at all. Pass `width="narrow"` / `"wide"` / `"full"` (or `"fit"`) to change that, and the usual `color` / `space` / typography variants to retint and respace.
 - Pair [`Figure`](/ui/Section) with [`Caption`](/ui/Caption) for a `<figure>` / `<figcaption>` pair.
 
 ## Usage
@@ -16,7 +16,7 @@ A landmark content region — renders a `<section>` with block-level spacing and
 ```tsx
 import { Section, Heading, Definitions } from "shelving/ui";
 
-<Section narrow>
+<Section width="narrow">
   <Heading>Account details</Heading>
   <Definitions>
     <dt>Name</dt><dd>Alice Smith</dd>
@@ -42,11 +42,11 @@ import { Header, Nav, Footer } from "shelving/ui";
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--section-width` | Content width | `100%` |
+| `--section-width` | Content width | `var(--width-normal)` (55rem) |
 | `--section-indent` | Inline gutter kept on each side so text doesn't touch the edges | `var(--space-normal)` (16px) |
 | `--section-space` | Outer block margin (top + bottom) | `var(--space-section)` (2rem) |
 
-**Global tokens it reads:** [`--space-normal`](/ui/getSpaceClass) and [`--space-section`](/ui/getSpaceClass). The `narrow` / `wide` / `full` width variants come from the shared [`ui`](/ui) styling system.
+**Global tokens it reads:** [`--space-normal`](/ui/getSpaceClass), [`--space-section`](/ui/getSpaceClass), and [`--width-normal`](/ui/getWidthClass) (the default content width). The `width` variant (`narrow` / `normal` / `wide` / `full` / `fit`) comes from the shared [`ui`](/ui) styling system.
 
 ## See also
 

package/ui/block/Section.module.css

@@ -1,5 +1,6 @@
 @import "../style/layers.css";
 @import "../style/Space.module.css";
+@import "../style/Width.module.css";
 
 @layer components {
 	.prose :where(section, article, aside, nav, header, footer, figure),
@@ -9,7 +10,7 @@
 		display: block;
 		box-sizing: border-box;
 		max-inline-size: calc(100% - (var(--section-indent, var(--space-normal)) * 2)); /* Stop text touching the sides. */
-		inline-size: var(--section-width, 100%);
+		inline-size: var(--section-width, var(--width-normal)); /* Default to the normal content width; override with the `width` variant. */
 		margin-inline: auto;
 		margin-block: var(--section-space, var(--space-section));
 

package/ui/block/Section.tsx

@@ -105,7 +105,7 @@ export function Nav(props: SectionProps): ReactElement {
  * @kind component
  * @param props Colour, space, typography, and width variants plus optional `as` override and `children`.
  * @returns Rendered `<aside>` element.
- * @example <Aside narrow><Paragraph>Sidebar</Paragraph></Aside>
+ * @example <Aside width="narrow"><Paragraph>Sidebar</Paragraph></Aside>
  * @see https://dhoulb.github.io/shelving/ui/block/Section/Aside
  */
 export function Aside(props: SectionProps): ReactElement {

package/ui/block/Table.d.ts

@@ -2,13 +2,14 @@ import type { ReactElement } from "react";
 import { type ColorVariants } from "../style/Color.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
+import { type WidthVariants } from "../style/Width.js";
 import type { ChildProps } from "../util/props.js";
 /**
- * Props for `Table` — colour, space, and typography variants plus `children`.
+ * Props for `Table` — colour, space, typography, and width variants plus `children`.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Table/TableProps
  */
-export interface TableProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {
+export interface TableProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, ChildProps {
 }
 /**
  * Table block — rendered as `<table>`.
@@ -16,7 +17,7 @@ export interface TableProps extends ColorVariants, SpaceVariants, TypographyVari
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
  *
  * @kind component
- * @param props Colour, space, and typography variants plus `children`.
+ * @param props Colour, space, typography, and width variants plus `children`.
  * @returns Rendered `<table>` element.
  * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>
  * @see https://dhoulb.github.io/shelving/ui/block/Table/Table

package/ui/block/Table.js

@@ -2,21 +2,22 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { getColorClass } from "../style/Color.js";
 import { getSpaceClass } from "../style/Space.js";
 import { getTypographyClass } from "../style/Typography.js";
+import { getWidthClass } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import TABLE_CSS from "./Table.module.css";
-const TABLE_CLASS = getModuleClass(TABLE_CSS, "divider");
+const TABLE_CLASS = getModuleClass(TABLE_CSS, "table");
 /**
  * Table block — rendered as `<table>`.
  * - Wrap in a `<Scroll horizontal>` if the table may exceed the container width on small screens.
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
  *
  * @kind component
- * @param props Colour, space, and typography variants plus `children`.
+ * @param props Colour, space, typography, and width variants plus `children`.
  * @returns Rendered `<table>` element.
  * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>
  * @see https://dhoulb.github.io/shelving/ui/block/Table/Table
  */
 export function Table({ children, ...props }) {
     return (_jsx("table", { className: getClass(TABLE_CLASS, //
-        getColorClass(props), getSpaceClass(props), getTypographyClass(props)), children: children }));
+        getColorClass(props), getSpaceClass(props), getTypographyClass(props), getWidthClass(props)), children: children }));
 }

package/ui/block/Table.md

@@ -8,6 +8,7 @@ A data table — renders a `<table>`. Compose the usual `<thead>` / `<tbody>` /
 - First and last cells in a row drop their outer inline padding so the table aligns flush with the surrounding text column.
 - Wrap a wide table in a horizontally scrollable container if it may exceed the content width on small screens.
 - Like the other block components it collapses its outer block margin when it is the first or last child.
+- Spans the full width of its container by default; set the `width` variant (`narrow` / `normal` / `wide` / `full` / `fit`) to constrain it.
 - Inside [`Prose`](/ui/Prose) a raw `<table>` picks up the same styling, so Markdown-rendered tables match component ones.
 
 ## Usage

package/ui/block/Table.module.css

@@ -11,6 +11,7 @@
 	.prose table {
 		/* Box */
 		display: table;
+		inline-size: 100%;
 		margin-inline: 0;
 		margin-block: var(--table-space, var(--space-paragraph));
 		text-indent: 0;

package/ui/block/Table.tsx

@@ -2,18 +2,19 @@ import type { ReactElement } from "react";
 import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { getSpaceClass, type SpaceVariants } from "../style/Space.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+import { getWidthClass, type WidthVariants } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { ChildProps } from "../util/props.js";
 import TABLE_CSS from "./Table.module.css";
 
-const TABLE_CLASS = getModuleClass(TABLE_CSS, "divider");
+const TABLE_CLASS = getModuleClass(TABLE_CSS, "table");
 
 /**
- * Props for `Table` — colour, space, and typography variants plus `children`.
+ * Props for `Table` — colour, space, typography, and width variants plus `children`.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Table/TableProps
  */
-export interface TableProps extends ColorVariants, SpaceVariants, TypographyVariants, ChildProps {}
+export interface TableProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, ChildProps {}
 
 /**
  * Table block — rendered as `<table>`.
@@ -21,7 +22,7 @@ export interface TableProps extends ColorVariants, SpaceVariants, TypographyVari
  * - `<th>` / `<td>` cells draw the borders (the `<table>` element itself has none); override their weight via the `--table-border` / `--table-stroke` hooks.
  *
  * @kind component
- * @param props Colour, space, and typography variants plus `children`.
+ * @param props Colour, space, typography, and width variants plus `children`.
  * @returns Rendered `<table>` element.
  * @example <Table><tbody><tr><td>Cell</td></tr></tbody></Table>
  * @see https://dhoulb.github.io/shelving/ui/block/Table/Table
@@ -34,6 +35,7 @@ export function Table({ children, ...props }: TableProps): ReactElement {
 				getColorClass(props),
 				getSpaceClass(props),
 				getTypographyClass(props),
+				getWidthClass(props),
 			)}
 		>
 			{children}

package/ui/block/Title.md

@@ -26,7 +26,7 @@ import { Title, Paragraph } from "shelving/ui";
 import { Panel, Block, Title } from "shelving/ui";
 
 <Panel as="header" color="primary">
-  <Block narrow>
+  <Block width="narrow">
     <Title>Welcome</Title>
   </Block>
 </Panel>

package/ui/dialog/Dialog.js

@@ -18,7 +18,7 @@ export const Dialog = memo(({ children, onClose, ...props }) => {
     useEffect(() => {
         ref.current?.showModal();
     }, []);
-    return (_jsx(Suspense, { fallback: null, children: _jsxs("dialog", { ref: ref, className: styles.dialog, onClick: _closeOnBackdropClick, onClose: onClose, ...props, children: [children, _jsx("div", { className: styles.close, children: _jsx(DialogCloseButton, { plain: true }) })] }) }));
+    return (_jsx(Suspense, { fallback: null, children: _jsxs("dialog", { ref: ref, className: getModuleClass(styles, "dialog"), onClick: _closeOnBackdropClick, onClose: onClose, ...props, children: [children, _jsx("div", { className: getModuleClass(styles, "close"), children: _jsx(DialogCloseButton, { plain: true }) })] }) }));
 });
 /** When the user clicks anywhere on a `<dialog>` element (and the click isn't on a link etc), then close the dialog. */
 function _closeOnBackdropClick({ currentTarget, target }) {

package/ui/dialog/Dialog.tsx

@@ -35,9 +35,9 @@ export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
 	return (
 		<Suspense fallback={null}>
 			{/** biome-ignore lint/a11y/useKeyWithClickEvents: Dialogs also show a close button. */}
-			<dialog ref={ref} className={styles.dialog} onClick={_closeOnBackdropClick} onClose={onClose} {...props}>
+			<dialog ref={ref} className={getModuleClass(styles, "dialog")} onClick={_closeOnBackdropClick} onClose={onClose} {...props}>
 				{children}
-				<div className={styles.close}>
+				<div className={getModuleClass(styles, "close")}>
 					<DialogCloseButton plain />
 				</div>
 			</dialog>

package/ui/dialog/Modal.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { getModuleClass } from "../util/css.js";
 import styles from "./Modal.module.css";
 /**
  * Styled `<aside>` overlay container for modal content.
@@ -10,5 +11,5 @@ import styles from "./Modal.module.css";
  * @see https://dhoulb.github.io/shelving/ui/dialog/Modal/Modal
  */
 export function Modal({ children }) {
-    return _jsx("aside", { className: styles.modal, children: children });
+    return _jsx("aside", { className: getModuleClass(styles, "modal"), children: children });
 }

package/ui/dialog/Modal.tsx

@@ -1,4 +1,5 @@
 import type { ReactElement } from "react";
+import { getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import styles from "./Modal.module.css";
 
@@ -19,5 +20,5 @@ export interface ModalProps extends OptionalChildProps {}
  * @see https://dhoulb.github.io/shelving/ui/dialog/Modal/Modal
  */
 export function Modal({ children }: ModalProps): ReactElement {
-	return <aside className={styles.modal}>{children}</aside>;
+	return <aside className={getModuleClass(styles, "modal")}>{children}</aside>;
 }

package/ui/docs/DocumentationHomePage.js

@@ -20,5 +20,5 @@ import { TreeCards } from "../tree/TreeCards.js";
  * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationHomePage/DocumentationHomePage
  */
 export function DocumentationHomePage({ title, name, description, content, children }) {
-    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: "red", children: [_jsx(Panel, { padding: "5x", children: _jsx(Title, { center: true, children: title ?? name }) }), content && (_jsx(Section, { wide: true, children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), _jsx(Section, { wide: true, children: _jsx(TreeCards, { children: children }) })] }) }));
+    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: "red", children: [_jsx(Panel, { padding: "5x", children: _jsx(Title, { center: true, children: title ?? name }) }), content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), _jsx(Section, { children: _jsx(TreeCards, { children: children }) })] }) }));
 }

package/ui/docs/DocumentationHomePage.tsx

@@ -29,13 +29,13 @@ export function DocumentationHomePage({ title, name, description, content, child
 					<Title center>{title ?? name}</Title>
 				</Panel>
 				{content && (
-					<Section wide>
+					<Section>
 						<Prose>
 							<Markup>{content}</Markup>
 						</Prose>
 					</Section>
 				)}
-				<Section wide>
+				<Section>
 					<TreeCards>{children}</TreeCards>
 				</Section>
 			</Block>

package/ui/docs/DocumentationPage.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/tree.js";
 /**
  * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.