shelving 1.247.0 → 1.248.0

package/package.json

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

package/ui/block/Table.md

@@ -9,6 +9,7 @@ A data table — renders a `<table>`. Compose the usual `<thead>` / `<tbody>` /
 - 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.
+- Size columns with [`<TableHeader>`](/ui/TableHeader) / [`<TableCell>`](/ui/TableCell) and the `width` variant — `width="fit"` hugs the content, and `width="12x" grow` gives a column a hard minimum it can grow past (cells honour `min-width`, so the table scrolls rather than collapsing the column on a narrow screen). A column's width is the widest of its cells.
 - Inside [`Prose`](/ui/Prose) a raw `<table>` picks up the same styling, so Markdown-rendered tables match component ones.
 
 ## Usage
@@ -50,6 +51,7 @@ import { Table } from "shelving/ui";
 
 ## See also
 
+- [`TableHeader`](/ui/TableHeader) / [`TableCell`](/ui/TableCell) — `<th>` / `<td>` cells that set column widths and typography via variants.
 - [`Definitions`](/ui/Definitions) — term/value pairs when a two-column key/value layout fits better than a grid.
 - [`Prose`](/ui/Prose) — styles raw `<table>` inside longform content.
 - [`ui`](/ui) — the styling system: tint ladder, label tokens, and theming.

package/ui/block/TableCell.d.ts

@@ -0,0 +1,23 @@
+import type { ReactElement } from "react";
+import { type TypographyVariants } from "../style/Typography.js";
+import { type WidthVariants } from "../style/Width.js";
+import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `TableCell` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCellProps
+ */
+export interface TableCellProps extends WidthVariants, TypographyVariants, ChildProps {
+}
+/**
+ * Table body cell — rendered as `<td>`.
+ * - Sets its column's width via the `width` variant. Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum that fills the remaining space and keeps the table from collapsing the column on a narrow viewport.
+ * - A column's width is the widest of its cells, so use this to size a column that has no header to set the width on.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<td>` element.
+ * @example <TableCell width="12x" grow>A longer description that wants a sensible minimum width.</TableCell>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCell
+ */
+export declare function TableCell({ children, ...props }: TableCellProps): ReactElement;

package/ui/block/TableCell.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getTypographyClass } from "../style/Typography.js";
+import { getWidthClass } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+/**
+ * Table body cell — rendered as `<td>`.
+ * - Sets its column's width via the `width` variant. Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum that fills the remaining space and keeps the table from collapsing the column on a narrow viewport.
+ * - A column's width is the widest of its cells, so use this to size a column that has no header to set the width on.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<td>` element.
+ * @example <TableCell width="12x" grow>A longer description that wants a sensible minimum width.</TableCell>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCell
+ */
+export function TableCell({ children, ...props }) {
+    return _jsx("td", { className: getClass(getWidthClass(props), getTypographyClass(props)) || undefined, children: children });
+}

package/ui/block/TableCell.md

@@ -0,0 +1,35 @@
+# TableCell
+
+A table body cell — renders a `<td>`. Use it for the body rows of a [`Table`](/ui/Table); it sets the column's width and cell typography.
+
+**Things to know:**
+
+- Set the column's width with the `width` variant. Because a cell (unlike a `<col>`) honours `min-width`, `width="12x" grow` gives the column a *hard* minimum that fills the remaining space and keeps the table from collapsing the column on a narrow screen — the table scrolls instead. See [`getWidthClass`](/ui/getWidthClass).
+- A column's width is the widest of its cells, so this is how you size a column that has no header to set the width on (e.g. a trailing description column).
+- Carries the same [typography variants](/ui/getTypographyClass) as the prose components (`size`, `weight`, `font`, `tint`, alignment).
+- For a column that does have a header, prefer setting the width once on its [`TableHeader`](/ui/TableHeader).
+
+## Usage
+
+```tsx
+import { Table, TableCell } from "shelving/ui";
+
+<Table>
+  <tbody>
+    <tr>
+      <TableCell>name</TableCell>
+      <TableCell width="12x" grow>A longer description that should keep a sensible minimum width.</TableCell>
+    </tr>
+  </tbody>
+</Table>
+```
+
+## Styling
+
+`TableCell` paints nothing of its own — it composes the [`width`](/ui/getWidthClass) and [`typography`](/ui/getTypographyClass) variants onto a `<td>`, and inherits the cell styling (borders, padding) from the surrounding [`Table`](/ui/Table). It exposes no hooks of its own.
+
+## See also
+
+- [`TableHeader`](/ui/TableHeader) — the `<th>` equivalent for header cells.
+- [`Table`](/ui/Table) — the table the cells belong to.
+- [`getWidthClass`](/ui/getWidthClass) — the full `width` / `grow` variant reference.

package/ui/block/TableCell.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+import { getWidthClass, type WidthVariants } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+import type { ChildProps } from "../util/props.js";
+
+/**
+ * Props for `TableCell` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCellProps
+ */
+export interface TableCellProps extends WidthVariants, TypographyVariants, ChildProps {}
+
+/**
+ * Table body cell — rendered as `<td>`.
+ * - Sets its column's width via the `width` variant. Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum that fills the remaining space and keeps the table from collapsing the column on a narrow viewport.
+ * - A column's width is the widest of its cells, so use this to size a column that has no header to set the width on.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<td>` element.
+ * @example <TableCell width="12x" grow>A longer description that wants a sensible minimum width.</TableCell>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableCell/TableCell
+ */
+export function TableCell({ children, ...props }: TableCellProps): ReactElement {
+	return <td className={getClass(getWidthClass(props), getTypographyClass(props)) || undefined}>{children}</td>;
+}

package/ui/block/TableHeader.d.ts

@@ -0,0 +1,23 @@
+import type { ReactElement } from "react";
+import { type TypographyVariants } from "../style/Typography.js";
+import { type WidthVariants } from "../style/Width.js";
+import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `TableHeader` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeaderProps
+ */
+export interface TableHeaderProps extends WidthVariants, TypographyVariants, ChildProps {
+}
+/**
+ * Table header cell — rendered as `<th>`.
+ * - Sets its column's width via the `width` variant (e.g. `width="fit"` to hug the content). Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum it can grow past.
+ * - A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<th>` element.
+ * @example <TableHeader width="fit">Parameter</TableHeader>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeader
+ */
+export declare function TableHeader({ children, ...props }: TableHeaderProps): ReactElement;

package/ui/block/TableHeader.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getTypographyClass } from "../style/Typography.js";
+import { getWidthClass } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+/**
+ * Table header cell — rendered as `<th>`.
+ * - Sets its column's width via the `width` variant (e.g. `width="fit"` to hug the content). Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum it can grow past.
+ * - A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<th>` element.
+ * @example <TableHeader width="fit">Parameter</TableHeader>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeader
+ */
+export function TableHeader({ children, ...props }) {
+    return _jsx("th", { className: getClass(getWidthClass(props), getTypographyClass(props)) || undefined, children: children });
+}

package/ui/block/TableHeader.md

@@ -0,0 +1,43 @@
+# TableHeader
+
+A table header cell — renders a `<th>`. Use it for the header row of a [`Table`](/ui/Table); it sets the column's width and label typography.
+
+**Things to know:**
+
+- Set the column's width with the `width` variant — `width="fit"` hugs the content. Because a cell (unlike a `<col>`) honours `min-width`, `width="12x" grow` gives the column a *hard* minimum it can grow past, so the table scrolls rather than collapsing the column on a narrow screen. See [`getWidthClass`](/ui/getWidthClass).
+- A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column — set the width once on the header instead of on every body cell.
+- Carries the same [typography variants](/ui/getTypographyClass) as the prose components (`size`, `weight`, `font`, `tint`, alignment), though the `Table` already styles header cells in the label style by default.
+- For a column that has no header, set the width on its [`TableCell`](/ui/TableCell)s instead.
+
+## Usage
+
+```tsx
+import { Table, TableCell, TableHeader } from "shelving/ui";
+
+<Table>
+  <thead>
+    <tr>
+      <TableHeader width="fit">Parameter</TableHeader>
+      <TableHeader width="fit">Type</TableHeader>
+      <TableHeader width="12x" grow>Description</TableHeader>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <TableCell>name</TableCell>
+      <TableCell>string</TableCell>
+      <TableCell>The name of the thing.</TableCell>
+    </tr>
+  </tbody>
+</Table>
+```
+
+## Styling
+
+`TableHeader` paints nothing of its own — it composes the [`width`](/ui/getWidthClass) and [`typography`](/ui/getTypographyClass) variants onto a `<th>`, and inherits the header styling (label font, borders, padding) from the surrounding [`Table`](/ui/Table). It exposes no hooks of its own.
+
+## See also
+
+- [`TableCell`](/ui/TableCell) — the `<td>` equivalent for body cells.
+- [`Table`](/ui/Table) — the table the cells belong to.
+- [`getWidthClass`](/ui/getWidthClass) — the full `width` / `grow` variant reference.

package/ui/block/TableHeader.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
+import { getWidthClass, type WidthVariants } from "../style/Width.js";
+import { getClass } from "../util/css.js";
+import type { ChildProps } from "../util/props.js";
+
+/**
+ * Props for `TableHeader` — width and typography variants plus `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeaderProps
+ */
+export interface TableHeaderProps extends WidthVariants, TypographyVariants, ChildProps {}
+
+/**
+ * Table header cell — rendered as `<th>`.
+ * - Sets its column's width via the `width` variant (e.g. `width="fit"` to hug the content). Unlike a `<col>`, a cell honours `min-width`, so `width="12x" grow` gives the column a hard minimum it can grow past.
+ * - A column's width is the widest of its cells, so sizing the `<th>` sizes the whole column.
+ *
+ * @kind component
+ * @param props Width and typography variant props plus `children`.
+ * @returns Rendered `<th>` element.
+ * @example <TableHeader width="fit">Parameter</TableHeader>
+ * @see https://dhoulb.github.io/shelving/ui/block/TableHeader/TableHeader
+ */
+export function TableHeader({ children, ...props }: TableHeaderProps): ReactElement {
+	return <th className={getClass(getWidthClass(props), getTypographyClass(props)) || undefined}>{children}</th>;
+}

package/ui/block/index.d.ts

@@ -14,5 +14,7 @@ export * from "./Preformatted.js";
 export * from "./Prose.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./TableCell.js";
+export * from "./TableHeader.js";
 export * from "./Title.js";
 export * from "./Video.js";

package/ui/block/index.js

@@ -14,5 +14,7 @@ export * from "./Preformatted.js";
 export * from "./Prose.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./TableCell.js";
+export * from "./TableHeader.js";
 export * from "./Title.js";
 export * from "./Video.js";

package/ui/block/index.ts

@@ -14,5 +14,7 @@ export * from "./Preformatted.js";
 export * from "./Prose.js";
 export * from "./Subheading.js";
 export * from "./Table.js";
+export * from "./TableCell.js";
+export * from "./TableHeader.js";
 export * from "./Title.js";
 export * from "./Video.js";

package/ui/docs/DocumentationPage.js

@@ -8,6 +8,8 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Table } from "../block/Table.js";
+import { TableCell } from "../block/TableCell.js";
+import { TableHeader } from "../block/TableHeader.js";
 import { Title } from "../block/Title.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
@@ -79,9 +81,9 @@ function DocumentationChildren({ elements }) {
  */
 export function DocumentationPage({ title, name, kind = "unknown", description, content, signatures, params, returns, throws, types, examples, children, ...props }) {
     const map = useTreeMap();
-    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), signatures?.length || params?.length || returns?.length || throws?.length || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), params?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Parameter" }), _jsx("th", { children: "Type" }), _jsx("th", { children: "Default" })] }) }), _jsx("tbody", { children: params.map(({ name, type = DEFAULT_TYPE, description, default: def }) => {
+    return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), signatures?.length || params?.length || returns?.length || throws?.length || types?.length ? (_jsxs(Section, { children: [_jsx(DocumentationSignatures, { signatures: signatures }), params?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx(TableHeader, { width: "fit", children: "Param" }), _jsx(TableHeader, { width: "fit", children: "Type" }), _jsx(TableHeader, { width: "fit", children: "Default" })] }) }), _jsx("tbody", { children: params.map(({ name, type = DEFAULT_TYPE, description, default: def }) => {
                                                 // An options-bag param whose type resolves to a documented interface/object type is flattened into its individual fields as indented child rows.
                                                 const resolved = getTreeElement(map, type)?.props;
-                                                return (_jsxs(Fragment, { children: [_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { children: name }) }), _jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: def ? _jsx(Code, { children: def }) : "-" }), _jsx("td", { children: description || resolved?.description || "" })] }), resolved?.properties?.map(prop => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(Code, { children: `.${prop.name}` }) }), _jsx("td", { children: _jsx(TreeLink, { name: prop.type ?? DEFAULT_TYPE }) }), _jsx("td", { children: prop.default ? _jsx(Code, { children: prop.default }) : "-" }), _jsx("td", { children: _getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description) })] }, `${name}.${prop.name}`)))] }, `${name}-${type}`));
-                                            }) })] }) }) })), returns?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx("th", { children: "Return" }) }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: _getRowDescription(map, type, description) })] }, `${type}-${description}`))) })] }) }) })), throws?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx("th", { children: "Throws" }) }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: _getRowDescription(map, type, description) })] }, `${type}-${description}`))) })] }) }) })), types?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx("th", { children: "Type" }) }) }), _jsx("tbody", { children: types.map(type => (_jsxs("tr", { children: [_jsx("td", { children: _jsx(TreeLink, { name: type }) }), _jsx("td", { children: _getRowDescription(map, type) })] }, type))) })] }) }) }))] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(DocumentationChildren, { elements: children })] }) }));
+                                                return (_jsxs(Fragment, { children: [_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(Code, { children: name }) }), _jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { children: def ? _jsx(Code, { children: def }) : "-" }), _jsx(TableCell, { width: "20x", grow: true, children: description || resolved?.description || "" })] }), resolved?.properties?.map(prop => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(Code, { children: `.${prop.name}` }) }), _jsx(TableCell, { children: _jsx(TreeLink, { name: prop.type ?? DEFAULT_TYPE }) }), _jsx(TableCell, { children: prop.default ? _jsx(Code, { children: prop.default }) : "-" }), _jsx(TableCell, { width: "20x", grow: true, children: _getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description) })] }, `${name}.${prop.name}`)))] }, `${name}-${type}`));
+                                            }) })] }) }) })), returns?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx(TableHeader, { width: "fit", children: "Return" }) }) }), _jsx("tbody", { children: returns.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { width: "20x", grow: true, children: _getRowDescription(map, type, description) })] }, `${type}-${description}`))) })] }) }) })), throws?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx(TableHeader, { width: "fit", children: "Throws" }) }) }), _jsx("tbody", { children: throws.map(({ type = DEFAULT_TYPE, description }) => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { width: "20x", grow: true, children: _getRowDescription(map, type, description) })] }, `${type}-${description}`))) })] }) }) })), types?.length && (_jsx(Section, { children: _jsx(Scroll, { horizontal: true, children: _jsxs(Table, { children: [_jsx("thead", { children: _jsx("tr", { children: _jsx(TableHeader, { width: "fit", children: "Type" }) }) }), _jsx("tbody", { children: types.map(type => (_jsxs("tr", { children: [_jsx(TableCell, { children: _jsx(TreeLink, { name: type }) }), _jsx(TableCell, { width: "20x", grow: true, children: _getRowDescription(map, type) })] }, type))) })] }) }) }))] })) : null, content && (_jsx(Section, { children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), examples?.length && (_jsxs(Section, { children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), _jsx(DocumentationChildren, { elements: children })] }) }));
 }

package/ui/docs/DocumentationPage.md

@@ -6,7 +6,7 @@ The full detail page for a documented symbol — the default renderer for `tree-
 
 - Above the title it renders an ancestor trail via [`TreeBreadcrumbs`](/ui/TreeBreadcrumbs), so it needs a [`TreeProvider`](/ui/TreeProvider) above it to resolve the ancestors.
 - The title carries a [`DocumentationKind`](/ui/DocumentationKind) tag, and below it [`DocumentationButtons`](/ui/DocumentationButtons) lists the symbol's relations (`member of`, `extends`, `implements`) as links.
-- It renders the signature(s) via [`DocumentationSignatures`](/ui/DocumentationSignatures) (one block per overload, each carrying the symbol's name), then prose content, then conditional `Parameters` / `Returns` / `Throws` / `Examples` sections — each only appears when it has entries. Parameters render as a [`Table`](/ui/Table) (`Parameter` / `Type` / `Default` / `Description` columns, a `-` standing in where a parameter has no default); Returns and Throws render as two-column tables (`Return` / `Throws` plus `Description`), with the type in the first column.
+- It renders the signature(s) via [`DocumentationSignatures`](/ui/DocumentationSignatures) (one block per overload, each carrying the symbol's name), then prose content, then conditional `Parameters` / `Returns` / `Throws` / `Examples` sections — each only appears when it has entries. Parameters render as a [`Table`](/ui/Table) (`Param` / `Type` / `Default` / `Description` columns, a `-` standing in where a parameter has no default); Returns and Throws render as two-column tables (`Return` / `Throws` plus `Description`), with the type in the first column.
 - Child symbols follow, grouped by `kind` into card sections (`Components`, `Functions`, `Classes`, `Interfaces`, `Types`, `Constants`, `Methods`, `Properties`) rendered as [`DocumentationCard`](/ui/DocumentationCard)s inside a [`TreeCards`](/ui/TreeCards) listing. A new documented kind needs an entry in `KIND_SECTIONS` here (and a colour in [`DocumentationKind`](/ui/DocumentationKind)).
 
 ## Usage

package/ui/docs/DocumentationPage.test.tsx

@@ -57,7 +57,7 @@ describe("DocumentationPage", () => {
 			"./makeThing",
 		);
 		// Parameters table headers — name, type, default, description in separate columns.
-		expect(html).toContain("<th>Parameter</th>");
+		expect(html).toContain("<th>Param</th>");
 		expect(html).toContain("<th>Type</th>");
 		expect(html).toContain("<th>Default</th>");
 		// A param with a default renders it; one without gets a hyphen.

package/ui/docs/DocumentationPage.tsx

@@ -8,6 +8,8 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Prose } from "../block/Prose.js";
 import { Header, Section } from "../block/Section.js";
 import { Table } from "../block/Table.js";
+import { TableCell } from "../block/TableCell.js";
+import { TableHeader } from "../block/TableHeader.js";
 import { Title } from "../block/Title.js";
 import { Code } from "../inline/Code.js";
 import { Markup } from "../misc/Markup.js";
@@ -129,9 +131,9 @@ export function DocumentationPage({
 									<Table>
 										<thead>
 											<tr>
-												<th>Parameter</th>
-												<th>Type</th>
-												<th>Default</th>
+												<TableHeader width="fit">Param</TableHeader>
+												<TableHeader width="fit">Type</TableHeader>
+												<TableHeader width="fit">Default</TableHeader>
 											</tr>
 										</thead>
 										<tbody>
@@ -141,25 +143,29 @@ export function DocumentationPage({
 												return (
 													<Fragment key={`${name}-${type}`}>
 														<tr>
-															<td>
+															<TableCell>
 																<Code>{name}</Code>
-															</td>
-															<td>
+															</TableCell>
+															<TableCell>
 																<TreeLink name={type} />
-															</td>
-															<td>{def ? <Code>{def}</Code> : "-"}</td>
-															<td>{description || resolved?.description || ""}</td>
+															</TableCell>
+															<TableCell>{def ? <Code>{def}</Code> : "-"}</TableCell>
+															<TableCell width="20x" grow>
+																{description || resolved?.description || ""}
+															</TableCell>
 														</tr>
 														{resolved?.properties?.map(prop => (
 															<tr key={`${name}.${prop.name}`}>
-																<td>
+																<TableCell>
 																	<Code>{`.${prop.name}`}</Code>
-																</td>
-																<td>
+																</TableCell>
+																<TableCell>
 																	<TreeLink name={prop.type ?? DEFAULT_TYPE} />
-																</td>
-																<td>{prop.default ? <Code>{prop.default}</Code> : "-"}</td>
-																<td>{_getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description)}</td>
+																</TableCell>
+																<TableCell>{prop.default ? <Code>{prop.default}</Code> : "-"}</TableCell>
+																<TableCell width="20x" grow>
+																	{_getRowDescription(map, prop.type ?? DEFAULT_TYPE, prop.description)}
+																</TableCell>
 															</tr>
 														))}
 													</Fragment>
@@ -176,16 +182,18 @@ export function DocumentationPage({
 									<Table>
 										<thead>
 											<tr>
-												<th>Return</th>
+												<TableHeader width="fit">Return</TableHeader>
 											</tr>
 										</thead>
 										<tbody>
 											{returns.map(({ type = DEFAULT_TYPE, description }) => (
 												<tr key={`${type}-${description}`}>
-													<td>
+													<TableCell>
 														<TreeLink name={type} />
-													</td>
-													<td>{_getRowDescription(map, type, description)}</td>
+													</TableCell>
+													<TableCell width="20x" grow>
+														{_getRowDescription(map, type, description)}
+													</TableCell>
 												</tr>
 											))}
 										</tbody>
@@ -199,16 +207,18 @@ export function DocumentationPage({
 									<Table>
 										<thead>
 											<tr>
-												<th>Throws</th>
+												<TableHeader width="fit">Throws</TableHeader>
 											</tr>
 										</thead>
 										<tbody>
 											{throws.map(({ type = DEFAULT_TYPE, description }) => (
 												<tr key={`${type}-${description}`}>
-													<td>
+													<TableCell>
 														<TreeLink name={type} />
-													</td>
-													<td>{_getRowDescription(map, type, description)}</td>
+													</TableCell>
+													<TableCell width="20x" grow>
+														{_getRowDescription(map, type, description)}
+													</TableCell>
 												</tr>
 											))}
 										</tbody>
@@ -222,16 +232,18 @@ export function DocumentationPage({
 									<Table>
 										<thead>
 											<tr>
-												<th>Type</th>
+												<TableHeader width="fit">Type</TableHeader>
 											</tr>
 										</thead>
 										<tbody>
 											{types.map(type => (
 												<tr key={type}>
-													<td>
+													<TableCell>
 														<TreeLink name={type} />
-													</td>
-													<td>{_getRowDescription(map, type)}</td>
+													</TableCell>
+													<TableCell width="20x" grow>
+														{_getRowDescription(map, type)}
+													</TableCell>
 												</tr>
 											))}
 										</tbody>

package/ui/style/Width.d.ts

@@ -1,27 +1,34 @@
 /**
- * Enumerated max-inline-size constraints selectable via the `width` variant prop.
- * - `narrow` / `normal` / `wide` — fixed max-widths from the `--width-*` tokens.
- * - `full` — take the full available width, removing any default max-width constraint.
+ * Enumerated inline-size selectable via the `width` variant prop.
+ * - `narrow` / `normal` / `wide` — fixed widths from the `--width-*` tokens (capped at 100%).
+ * - `full` — take the full available width.
  * - `fit` — shrink to fit the content's intrinsic width (`fit-content`).
+ * - `1x` … `128x` — exact widths that are multiples of `--space-normal` (16px), following the spacing scale (`1x`–`8x` in single steps, then `10x`/`12x`/`14x`/`16x`, `20x`/`24x`/`28x`/`32x`, then `40x` … `128x` in eights).
  *
  * @see https://dhoulb.github.io/shelving/ui/style/Width/UIWidth
  */
-export type UIWidth = "narrow" | "normal" | "wide" | "full" | "fit";
+export type UIWidth = "narrow" | "normal" | "wide" | "full" | "fit" | "1x" | "2x" | "3x" | "4x" | "5x" | "6x" | "7x" | "8x" | "10x" | "12x" | "14x" | "16x" | "20x" | "24x" | "28x" | "32x" | "40x" | "48x" | "56x" | "64x" | "72x" | "80x" | "88x" | "96x" | "104x" | "112x" | "120x" | "128x";
 /**
- * Variant props that constrain (or unconstrain) a block-level component's max-width, e.g. `width="narrow"`.
+ * Variant props that set (or unconstrain) a component's inline-size, e.g. `width="narrow"` or `width="12x"`.
  *
  * @see https://dhoulb.github.io/shelving/ui/style/Width/WidthVariants
  */
 export interface WidthVariants {
-    /** Max-inline-size constraint of the element. */
+    /** Inline-size of the element. */
     width?: UIWidth | undefined;
+    /**
+     * Let the element grow past its `width` instead of staying exact.
+     * - Turns the chosen `width` into a floor (`min-inline-size`) and adds `flex-grow: 1` so the element expands to fill the available space when it's a flex item or table column.
+     */
+    grow?: boolean | undefined;
 }
 /**
- * Get the max-width class for a component from its `width` variant prop.
+ * Get the inline-size class for a component from its `width` / `grow` variant props.
  *
- * @param variants Variant props containing the optional `width` constraint.
- * @returns The width class string, or `undefined` when no `width` is set.
- * @example getWidthClass({ width: "narrow" }) // "narrow"
+ * @param variants Variant props containing the optional `width` value and `grow` flag.
+ * @returns The width class string, or `undefined` when neither `width` nor `grow` is set.
+ * @example getWidthClass({ width: "narrow" }) // "width narrow"
+ * @example getWidthClass({ width: "12x", grow: true }) // "width 12x grow"
  * @see https://dhoulb.github.io/shelving/ui/style/Width/getWidthClass
  */
-export declare function getWidthClass({ width }: WidthVariants): string | undefined;
+export declare function getWidthClass({ width, grow }: WidthVariants): string | undefined;

package/ui/style/Width.js

@@ -1,13 +1,16 @@
 import { getModuleClass } from "../util/css.js";
 import WIDTH_CSS from "./Width.module.css";
 /**
- * Get the max-width class for a component from its `width` variant prop.
+ * Get the inline-size class for a component from its `width` / `grow` variant props.
  *
- * @param variants Variant props containing the optional `width` constraint.
- * @returns The width class string, or `undefined` when no `width` is set.
- * @example getWidthClass({ width: "narrow" }) // "narrow"
+ * @param variants Variant props containing the optional `width` value and `grow` flag.
+ * @returns The width class string, or `undefined` when neither `width` nor `grow` is set.
+ * @example getWidthClass({ width: "narrow" }) // "width narrow"
+ * @example getWidthClass({ width: "12x", grow: true }) // "width 12x grow"
  * @see https://dhoulb.github.io/shelving/ui/style/Width/getWidthClass
  */
-export function getWidthClass({ width }) {
-    return width && getModuleClass(WIDTH_CSS, width);
+export function getWidthClass({ width, grow }) {
+    if (!width && !grow)
+        return undefined;
+    return getModuleClass(WIDTH_CSS, "width", width, { grow });
 }

package/ui/style/Width.module.css

@@ -1,4 +1,5 @@
 @import "layers.css";
+@import "Space.module.css";
 
 @layer defaults {
 	:root {
@@ -8,11 +9,8 @@
 		--width-wide: 75rem;
 	}
 
-	.narrow,
-	.normal,
-	.wide,
-	.full,
-	.fit {
+	/* Frame shared by every width value (weak default — a component's own margin can still beat the centering). */
+	.width {
 		box-sizing: border-box;
 		max-inline-size: 100%;
 		margin-inline: auto;
@@ -20,21 +18,119 @@
 }
 
 @layer variants {
-	/* Width variants — constrain a block-level component's max-inline-size. */
+	/* Apply the chosen value (set as `--width` by the value classes below). */
+	.width {
+		inline-size: var(--width, auto);
+	}
+
+	/* Semantic widths. */
 	.narrow {
-		inline-size: var(--width-narrow);
+		--width: var(--width-narrow);
 	}
 	.normal {
-		inline-size: var(--width-normal);
+		--width: var(--width-normal);
 	}
 	.wide {
-		inline-size: var(--width-wide);
+		--width: var(--width-wide);
 	}
 	.full {
+		--width: 100%;
 		margin-inline: 0;
-		inline-size: 100%;
 	}
 	.fit {
-		inline-size: fit-content;
+		--width: fit-content;
+	}
+
+	/* Numeric exact widths — multiples of `--space-normal` (16px). */
+	.\31 x {
+		--width: calc(var(--space-normal) * 1);
+	}
+	.\32 x {
+		--width: calc(var(--space-normal) * 2);
+	}
+	.\33 x {
+		--width: calc(var(--space-normal) * 3);
+	}
+	.\34 x {
+		--width: calc(var(--space-normal) * 4);
+	}
+	.\35 x {
+		--width: calc(var(--space-normal) * 5);
+	}
+	.\36 x {
+		--width: calc(var(--space-normal) * 6);
+	}
+	.\37 x {
+		--width: calc(var(--space-normal) * 7);
+	}
+	.\38 x {
+		--width: calc(var(--space-normal) * 8);
+	}
+	.\31 0x {
+		--width: calc(var(--space-normal) * 10);
+	}
+	.\31 2x {
+		--width: calc(var(--space-normal) * 12);
+	}
+	.\31 4x {
+		--width: calc(var(--space-normal) * 14);
+	}
+	.\31 6x {
+		--width: calc(var(--space-normal) * 16);
+	}
+	.\32 0x {
+		--width: calc(var(--space-normal) * 20);
+	}
+	.\32 4x {
+		--width: calc(var(--space-normal) * 24);
+	}
+	.\32 8x {
+		--width: calc(var(--space-normal) * 28);
+	}
+	.\33 2x {
+		--width: calc(var(--space-normal) * 32);
+	}
+	.\34 0x {
+		--width: calc(var(--space-normal) * 40);
+	}
+	.\34 8x {
+		--width: calc(var(--space-normal) * 48);
+	}
+	.\35 6x {
+		--width: calc(var(--space-normal) * 56);
+	}
+	.\36 4x {
+		--width: calc(var(--space-normal) * 64);
+	}
+	.\37 2x {
+		--width: calc(var(--space-normal) * 72);
+	}
+	.\38 0x {
+		--width: calc(var(--space-normal) * 80);
+	}
+	.\38 8x {
+		--width: calc(var(--space-normal) * 88);
+	}
+	.\39 6x {
+		--width: calc(var(--space-normal) * 96);
+	}
+	.\31 04x {
+		--width: calc(var(--space-normal) * 104);
+	}
+	.\31 12x {
+		--width: calc(var(--space-normal) * 112);
+	}
+	.\31 20x {
+		--width: calc(var(--space-normal) * 120);
+	}
+	.\31 28x {
+		--width: calc(var(--space-normal) * 128);
+	}
+
+	/* Grow modifier — turn the chosen width into a floor and expand to fill (flex items + table columns). */
+	.grow {
+		margin-inline: 0;
+		min-inline-size: var(--width);
+		flex-grow: 1;
 	}
 }

package/ui/style/Width.tsx

@@ -2,33 +2,74 @@ import { getModuleClass } from "../util/css.js";
 import WIDTH_CSS from "./Width.module.css";
 
 /**
- * Enumerated max-inline-size constraints selectable via the `width` variant prop.
- * - `narrow` / `normal` / `wide` — fixed max-widths from the `--width-*` tokens.
- * - `full` — take the full available width, removing any default max-width constraint.
+ * Enumerated inline-size selectable via the `width` variant prop.
+ * - `narrow` / `normal` / `wide` — fixed widths from the `--width-*` tokens (capped at 100%).
+ * - `full` — take the full available width.
  * - `fit` — shrink to fit the content's intrinsic width (`fit-content`).
+ * - `1x` … `128x` — exact widths that are multiples of `--space-normal` (16px), following the spacing scale (`1x`–`8x` in single steps, then `10x`/`12x`/`14x`/`16x`, `20x`/`24x`/`28x`/`32x`, then `40x` … `128x` in eights).
  *
  * @see https://dhoulb.github.io/shelving/ui/style/Width/UIWidth
  */
-export type UIWidth = "narrow" | "normal" | "wide" | "full" | "fit";
+export type UIWidth =
+	| "narrow"
+	| "normal"
+	| "wide"
+	| "full"
+	| "fit"
+	| "1x"
+	| "2x"
+	| "3x"
+	| "4x"
+	| "5x"
+	| "6x"
+	| "7x"
+	| "8x"
+	| "10x"
+	| "12x"
+	| "14x"
+	| "16x"
+	| "20x"
+	| "24x"
+	| "28x"
+	| "32x"
+	| "40x"
+	| "48x"
+	| "56x"
+	| "64x"
+	| "72x"
+	| "80x"
+	| "88x"
+	| "96x"
+	| "104x"
+	| "112x"
+	| "120x"
+	| "128x";
 
 /**
- * Variant props that constrain (or unconstrain) a block-level component's max-width, e.g. `width="narrow"`.
+ * Variant props that set (or unconstrain) a component's inline-size, e.g. `width="narrow"` or `width="12x"`.
  *
  * @see https://dhoulb.github.io/shelving/ui/style/Width/WidthVariants
  */
 export interface WidthVariants {
-	/** Max-inline-size constraint of the element. */
+	/** Inline-size of the element. */
 	width?: UIWidth | undefined;
+	/**
+	 * Let the element grow past its `width` instead of staying exact.
+	 * - Turns the chosen `width` into a floor (`min-inline-size`) and adds `flex-grow: 1` so the element expands to fill the available space when it's a flex item or table column.
+	 */
+	grow?: boolean | undefined;
 }
 
 /**
- * Get the max-width class for a component from its `width` variant prop.
+ * Get the inline-size class for a component from its `width` / `grow` variant props.
  *
- * @param variants Variant props containing the optional `width` constraint.
- * @returns The width class string, or `undefined` when no `width` is set.
- * @example getWidthClass({ width: "narrow" }) // "narrow"
+ * @param variants Variant props containing the optional `width` value and `grow` flag.
+ * @returns The width class string, or `undefined` when neither `width` nor `grow` is set.
+ * @example getWidthClass({ width: "narrow" }) // "width narrow"
+ * @example getWidthClass({ width: "12x", grow: true }) // "width 12x grow"
  * @see https://dhoulb.github.io/shelving/ui/style/Width/getWidthClass
  */
-export function getWidthClass({ width }: WidthVariants): string | undefined {
-	return width && getModuleClass(WIDTH_CSS, width);
+export function getWidthClass({ width, grow }: WidthVariants): string | undefined {
+	if (!width && !grow) return undefined;
+	return getModuleClass(WIDTH_CSS, "width", width, { grow });
 }

package/ui/style/getWidthClass.md

@@ -1,8 +1,17 @@
 # getWidthClass
 
-The `width` variant prop (`"narrow"`, `"normal"`, `"wide"`, `"full"`, `"fit"`) constrains a block-level component's max-inline-size — `<Card width="narrow">`, `<Block width="wide">`. It's an **override** for one-off layout; for an app-wide change, retune the width variables below in a theme file. `Section` already defaults to the `--width-normal` constraint, so most pages never set `width` at all.
+The `width` variant prop sets a component's inline-size — `<Card width="narrow">`, `<Block width="wide">`, `<TableCell width="12x">`. It's an **override** for one-off layout; for an app-wide change, retune the width variables below in a theme file. `Section` already defaults to the `--width-normal` width, so most pages never set `width` at all.
 
-`getWidthClass({ width })` maps the prop to a width class. The `narrow`, `normal`, and `wide` constraints read the variables below; `full` takes the full available width and `fit` shrinks to the content.
+`getWidthClass({ width, grow })` maps the props to a width class. Every value is capped at 100% of the container.
+
+**Values:**
+
+- `narrow` / `normal` / `wide` — fixed widths from the variables below.
+- `full` — the full available width.
+- `fit` — shrink to the content's intrinsic width (`fit-content`).
+- `1x` … `128x` — exact widths that are multiples of [`--space-normal`](/ui/getSpaceClass) (16px), following the spacing scale: `1x`–`8x` in single steps, then `10x`/`12x`/`14x`/`16x`, `20x`/`24x`/`28x`/`32x`, then `40x` … `128x` in eights. So `12x` is 192px.
+
+**The `grow` flag** turns the chosen `width` into a floor rather than an exact size: it applies the value as `min-inline-size` and adds `flex-grow: 1`, so the element expands to fill the available space when it's a flex item. Set it on a [`TableHeader`](/ui/TableHeader) or [`TableCell`](/ui/TableCell) (`width="12x" grow`) to give that column a 192px minimum that absorbs the remaining width and keeps the table from collapsing the column on a narrow viewport — cells honour `min-width`, so the table scrolls instead.
 
 ## Theme variables