shelving 1.253.2 → 1.253.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.253.2",
+	"version": "1.253.4",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -15,8 +15,8 @@
 		"@types/bun": "^1.3.14",
 		"@types/react": "^19.2.17",
 		"@types/react-dom": "^19.2.3",
-		"@typescript/native-preview": "^7.0.0-dev.20260613.1",
-		"firebase": "^12.14.0",
+		"@typescript/native-preview": "^7.0.0-dev.20260620.1",
+		"firebase": "^12.15.0",
 		"react": "^19.3.0-canary-fef12a01-20260413",
 		"react-dom": "^19.3.0-canary-fef12a01-20260413",
 		"typescript": "^5.9.3"

package/ui/README.md

@@ -19,13 +19,13 @@ A few conventions run through every component:
 
 The styling system lives in `style/` and has four moving parts: design tokens, the tint scale, cascade layers, and the styling props. Components compose them in a predictable shape; consumers theme by overriding CSS custom properties at `:root`.
 
-**Design tokens.** Every design-token constant is defined at `:root`, split across the themed token modules in `style/` — each module owns one domain, documents the variables it defines, and is the page a theme author overrides. `style/layers.css` is the cascade-layer anchor; every `*.module.css` `@import`s it plus the specific token modules it references, so the tokens and the layer order reach every component regardless of bundle order. The domains are: colours (`getColorClass()`), font sizes (`getSizeClass()`), font weights (`getWeightClass()`), font faces (`getFontClass()`), spacing (`getSpaceClass()`), widths (`getWidthClass()`), radii (`getRadiusClass()`), strokes (`getStrokeClass()`), shadows (`getShadowClass()`), and durations (`getDurationClass()`). Each also defines the semantic aliases a theme usually targets (`--color-primary`, `--color-link`, `--space-paragraph`, …). Components read tokens via `var(--token)`.
+**Design tokens.** Every design-token constant is defined at `:root`, split across the themed token modules in `style/` — each module owns one domain, documents the variables it defines, and is the page a theme author overrides. `style/layers.css` is the cascade-layer anchor; every `*.module.css` `@import`s it plus the specific token modules it references, so the tokens and the layer order reach every component regardless of bundle order. The domains are: colours (`getColorClass()`), typography — font size, weight, family, and case (`getTypographyClass()`), spacing (`getSpaceClass()`), widths (`getWidthClass()`), radii (`getRadiusClass()`), strokes (`getStrokeClass()`), shadows (`getShadowClass()`), and durations (`getDurationClass()`). Each also defines the semantic aliases a theme usually targets (`--color-primary`, `--color-link`, `--space-paragraph`, …). Components read tokens via `var(--token)`.
 
 **The tint scale.** All colour flows from one anchor variable, `--tint-50`, from which a 21-step ladder is computed and *recomputed* under `TINT_CLASS` — the heart of how `color=` and `status=` retint a whole subtree. The ladder, the recompute trick, the painting conventions, and the theming guide all live on the `TINT_CLASS` page.
 
 **Cascade layers.** Styles are ordered by `@layer`, lowest to highest priority: `defaults` (`:root` tokens, the tint ladder, body baseline) → `components` (the bulk of the CSS: `.card`, `.button`, …) → `variants` (cross-cutting opt-in modifiers, which always beat components) → `overrides` (top-priority structural fixes like `:first-child` / `:last-child` margin collapses). Unlayered rules beat all layered rules, so a theme should set tokens at `:root` or wrap its rules in `@layer`.
 
-**Styling props.** The cross-cutting visual options are props, each backed by a helper in `style/` that maps the prop to a class. Colour and status move the tint anchor — `getColorClass()` and `getStatusClass()`; font size, weight, and family come from `getSizeClass()`, `getWeightClass()`, and `getFontClass()`, which `getTypographyClass()` combines with text alignment and tint; spacing, padding, and gap from `getSpaceClass()`, `getPaddingClass()`, and `getGapClass()`; width constraints from `getWidthClass()`; flex layout from `getFlexClass()`; and opt-in scrolling from `getScrollClass()`. Each helper's page lists its exact prop values and what they set. A component opts into the props it wants by extending the matching `*Props` interfaces and composing the `getXxxClass(props)` calls.
+**Styling props.** The cross-cutting visual options are props, each backed by a helper in `style/` that maps the prop to a class. Colour and status move the tint anchor — `getColorClass()` and `getStatusClass()`; font size, weight, family, and case, plus text alignment, tint, and wrapping, all come from `getTypographyClass()`; spacing, padding, and gap from `getSpaceClass()`, `getPaddingClass()`, and `getGapClass()`; width constraints from `getWidthClass()`; flex layout from `getFlexClass()`; and opt-in scrolling from `getScrollClass()`. Each helper's page lists its exact prop values and what they set. A component opts into the props it wants by extending the matching `*Props` interfaces and composing the `getXxxClass(props)` calls.
 
 Each painting component also exposes its own theme hooks — a single tint hook (`--card-tint`) to recolour the whole component, plus per-property hooks (`--card-background`, `--card-radius`, …) for surgical overrides. Those are documented in each component's own **Styling** section (see `<Card>` for the precedent).
 
@@ -38,8 +38,8 @@ The recommended way to give an app its own look is a **theme stylesheet**, not s
 :root {
 	--color-primary: oklch(58% 0.25 300); /* purple brand */
 	--font-body: "Inter", system-ui;
-	--radius: 0.5rem; /* tighter corners everywhere */
-	--space: 1.125rem; /* roomier spacing scale */
+	--radius-normal: 0.5rem; /* tighter corners everywhere */
+	--space-normal: 1.125rem; /* roomier spacing scale */
 }
 ```
 

package/ui/app/App.d.ts

@@ -1,16 +1,4 @@
 import type { ReactElement } from "react";
-import "../style/layers.css";
-import "../style/Color.module.css";
-import "../style/Duration.module.css";
-import "../style/Font.module.css";
-import "../style/Radius.module.css";
-import "../style/Shadow.module.css";
-import "../style/Size.module.css";
-import "../style/Space.module.css";
-import "../style/Stroke.module.css";
-import "../style/Tint.module.css";
-import "../style/Weight.module.css";
-import "../style/Width.module.css";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
 /**

package/ui/app/App.js

@@ -1,19 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
-// Load the global design tokens, cascade-layer order, and body baseline. Each module owns its own
-// `:root` tokens (and body rules where relevant); see `modules/ui/README.md` for the styling system.
-import "../style/layers.css";
-import "../style/Color.module.css";
-import "../style/Duration.module.css";
-import "../style/Font.module.css";
-import "../style/Radius.module.css";
-import "../style/Shadow.module.css";
-import "../style/Size.module.css";
-import "../style/Space.module.css";
-import "../style/Stroke.module.css";
-import "../style/Tint.module.css";
-import "../style/Weight.module.css";
-import "../style/Width.module.css";
 /**
  * Root component for an application, providing the top-level `Meta` context and global styles.
  * - Descendants can read or update metadata via the provided `<Meta>` context.

package/ui/app/App.tsx

@@ -1,19 +1,5 @@
 import type { ReactElement } from "react";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
-// Load the global design tokens, cascade-layer order, and body baseline. Each module owns its own
-// `:root` tokens (and body rules where relevant); see `modules/ui/README.md` for the styling system.
-import "../style/layers.css";
-import "../style/Color.module.css";
-import "../style/Duration.module.css";
-import "../style/Font.module.css";
-import "../style/Radius.module.css";
-import "../style/Shadow.module.css";
-import "../style/Size.module.css";
-import "../style/Space.module.css";
-import "../style/Stroke.module.css";
-import "../style/Tint.module.css";
-import "../style/Weight.module.css";
-import "../style/Width.module.css";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
 

package/ui/block/Address.module.css

@@ -1,5 +1,7 @@
 @import "../style/layers.css";
+@import "../style/Color.module.css";
 @import "../style/Space.module.css";
+@import "../style/Typography.module.css";
 
 @layer components {
 	.address,

package/ui/block/Block.d.ts

@@ -5,17 +5,21 @@ import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
 import type { OptionalChildProps } from "../util/props.js";
 /**
- * Semantic element names a `Block` may render as via its `as` prop.
+ * Semantic element names a block element may render as via its `as` prop.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Block/BlockElement
  */
-export type BlockElement = "div" | "section" | "header" | "footer" | "nav" | "aside" | "figure";
+export type BlockElement = "div" | "section" | "header" | "footer" | "article" | "nav" | "aside" | "figure";
 /**
  * Props for `Block` — colour, space, typography, and width variants plus an optional `as` element override.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Block/BlockProps
  */
 export interface BlockProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+    /**
+     * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
+     * @default "div"
+     */
     as?: BlockElement | undefined;
 }
 /**
@@ -38,4 +42,4 @@ export declare function getBlockClass(variants: BlockProps): string;
  * @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;
+export declare function Block({ as: Element, children, ...props }: BlockProps): ReactElement;

package/ui/block/Block.js

@@ -29,6 +29,6 @@ export function getBlockClass(variants) {
  * @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 }) {
-    return _jsx(Component, { className: getBlockClass(props), children: children });
+export function Block({ as: Element = "div", children, ...props }) {
+    return _jsx(Element, { className: getBlockClass(props), children: children });
 }

package/ui/block/Block.module.css

@@ -1,4 +1,8 @@
 @import "../style/layers.css";
+@import "../style/Color.module.css";
+@import "../style/Space.module.css";
+@import "../style/Typography.module.css";
+@import "../style/Width.module.css";
 
 @layer components {
 	.block {

package/ui/block/Block.tsx

@@ -10,11 +10,11 @@ import BLOCK_CSS from "./Block.module.css";
 const BLOCK_CLASS = getModuleClass(BLOCK_CSS, "block");
 
 /**
- * Semantic element names a `Block` may render as via its `as` prop.
+ * Semantic element names a block element may render as via its `as` prop.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Block/BlockElement
  */
-export type BlockElement = "div" | "section" | "header" | "footer" | "nav" | "aside" | "figure";
+export type BlockElement = "div" | "section" | "header" | "footer" | "article" | "nav" | "aside" | "figure";
 
 /**
  * Props for `Block` — colour, space, typography, and width variants plus an optional `as` element override.
@@ -22,6 +22,10 @@ export type BlockElement = "div" | "section" | "header" | "footer" | "nav" | "as
  * @see https://dhoulb.github.io/shelving/ui/block/Block/BlockProps
  */
 export interface BlockProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
+	/**
+	 * Element this `<Block>` renders as, e.g. "header" to output a "<header>"
+	 * @default "div"
+	 */
 	as?: BlockElement | undefined;
 }
 
@@ -54,6 +58,6 @@ export function getBlockClass(variants: BlockProps): string {
  * @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 {
-	return <Component className={getBlockClass(props)}>{children}</Component>;
+export function Block({ as: Element = "div", children, ...props }: BlockProps): ReactElement {
+	return <Element className={getBlockClass(props)}>{children}</Element>;
 }

package/ui/block/Blockquote.module.css

@@ -2,7 +2,7 @@
 @import "../style/Space.module.css";
 @import "../style/Stroke.module.css";
 @import "../style/Tint.module.css";
-@import "../style/Weight.module.css";
+@import "../style/Typography.module.css";
 
 @layer components {
 	.blockquote,

package/ui/block/Caption.module.css

@@ -1,7 +1,7 @@
 @import "../style/layers.css";
-@import "../style/Size.module.css";
+@import "../style/Typography.module.css";
 @import "../style/Space.module.css";
-@import "../style/Weight.module.css";
+@import "../style/Color.module.css";
 
 @layer components {
 	.caption,

package/ui/block/Card.d.ts

@@ -6,15 +6,22 @@ import { type SpaceVariants } from "../style/Space.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
+import type { BlockElement } from "./Block.js";
 /**
  * Props for `Card` — combines `ClickableProps` (for navigable cards) with colour, status, padding, space, typography, and width variants.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Card/CardProps
  */
 export interface CardProps extends ClickableProps, ColorVariants, StatusVariants, PaddingVariants, SpaceVariants, TypographyVariants, WidthVariants {
+    /**
+     * Element this `<Card>` renders as, e.g. "header" to output a "<header>"
+     * @default "article"
+     */
+    as?: BlockElement | undefined;
 }
 /**
- * Cards are boxed areas for content to sit within — rendered as `<article>` since each card represents a self-contained piece of content.
+ * Cards are boxed areas for content to sit within.
+ * - Rendered as `<article>`  since each card represents a self-contained piece of content (override with `props.as`).
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
@@ -25,4 +32,4 @@ export interface CardProps extends ClickableProps, ColorVariants, StatusVariants
  * @example <Card status="error"><Subheading>Not found</Subheading></Card>
  * @see https://dhoulb.github.io/shelving/ui/block/Card/Card
  */
-export declare function Card({ children, href, onClick, title, ...props }: CardProps): ReactElement;
+export declare function Card({ as: Element, children, href, onClick, title, ...props }: CardProps): ReactElement;

package/ui/block/Card.js

@@ -9,7 +9,8 @@ import { getWidthClass } from "../style/Width.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import CARD_CSS from "./Card.module.css";
 /**
- * Cards are boxed areas for content to sit within — rendered as `<article>` since each card represents a self-contained piece of content.
+ * Cards are boxed areas for content to sit within.
+ * - Rendered as `<article>`  since each card represents a self-contained piece of content (override with `props.as`).
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
@@ -20,7 +21,7 @@ import CARD_CSS from "./Card.module.css";
  * @example <Card status="error"><Subheading>Not found</Subheading></Card>
  * @see https://dhoulb.github.io/shelving/ui/block/Card/Card
  */
-export function Card({ children, href, onClick, title = "Open", ...props }) {
+export function Card({ as: Element = "article", children, href, onClick, title = "Open", ...props }) {
     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] }));
+    return (_jsxs(Element, { 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

@@ -7,6 +7,7 @@ import { getStatusClass, type StatusVariants } from "../style/Status.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 { BlockElement } from "./Block.js";
 import CARD_CSS from "./Card.module.css";
 
 /**
@@ -21,10 +22,17 @@ export interface CardProps
 		PaddingVariants,
 		SpaceVariants,
 		TypographyVariants,
-		WidthVariants {}
+		WidthVariants {
+	/**
+	 * Element this `<Card>` renders as, e.g. "header" to output a "<header>"
+	 * @default "article"
+	 */
+	as?: BlockElement | undefined;
+}
 
 /**
- * Cards are boxed areas for content to sit within — rendered as `<article>` since each card represents a self-contained piece of content.
+ * Cards are boxed areas for content to sit within.
+ * - Rendered as `<article>`  since each card represents a self-contained piece of content (override with `props.as`).
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
@@ -35,12 +43,12 @@ export interface CardProps
  * @example <Card status="error"><Subheading>Not found</Subheading></Card>
  * @see https://dhoulb.github.io/shelving/ui/block/Card/Card
  */
-export function Card({ children, href, onClick, title = "Open", ...props }: CardProps): ReactElement {
+export function Card({ as: Element = "article", children, href, onClick, title = "Open", ...props }: CardProps): ReactElement {
 	const overlay = (href || onClick) && (
 		<Clickable title={title} href={href} onClick={onClick} {...props} className={getModuleClass(CARD_CSS, "overlay")} />
 	);
 	return (
-		<article
+		<Element
 			className={getClass(
 				getModuleClass(CARD_CSS, "card"),
 				getStatusClass(props),
@@ -53,6 +61,6 @@ export function Card({ children, href, onClick, title = "Open", ...props }: Card
 		>
 			{overlay}
 			{overlay ? <div>{children}</div> : children}
-		</article>
+		</Element>
 	);
 }

package/ui/block/Definitions.module.css

@@ -1,9 +1,8 @@
 @import "../style/layers.css";
-@import "../style/Font.module.css";
-@import "../style/Size.module.css";
 @import "../style/Space.module.css";
-@import "../style/Tint.module.css";
-@import "../style/Weight.module.css";
+@import "../style/Typography.module.css";
+@import "../style/Color.module.css";
+@import "../style/Gap.module.css";
 
 @layer components {
 	.definitions,

package/ui/block/Divider.module.css

@@ -1,7 +1,7 @@
 @import "../style/layers.css";
 @import "../style/Space.module.css";
 @import "../style/Stroke.module.css";
-@import "../style/Tint.module.css";
+@import "../style/Color.module.css";
 
 @layer components {
 	.divider,

package/ui/block/Heading.module.css

@@ -1,8 +1,7 @@
 @import "../style/layers.css";
-@import "../style/Font.module.css";
-@import "../style/Size.module.css";
+@import "../style/Color.module.css";
 @import "../style/Space.module.css";
-@import "../style/Weight.module.css";
+@import "../style/Typography.module.css";
 
 @layer components {
 	.heading,

package/ui/block/Label.module.css

@@ -1,9 +1,7 @@
 @import "../style/layers.css";
-@import "../style/Font.module.css";
-@import "../style/Size.module.css";
 @import "../style/Space.module.css";
-@import "../style/Tint.module.css";
-@import "../style/Weight.module.css";
+@import "../style/Color.module.css";
+@import "../style/Typography.module.css";
 
 @layer components {
 	.label {

package/ui/block/List.module.css

@@ -1,6 +1,8 @@
 @import "../style/layers.css";
 @import "../style/Space.module.css";
-@import "../style/Tint.module.css";
+@import "../style/Color.module.css";
+@import "../style/Gap.module.css";
+@import "../style/Typography.module.css";
 
 @layer components {
 	.unordered,

package/ui/block/List.tsx

@@ -7,7 +7,6 @@ import { getClass, getModuleClass } from "../util/css.js";
 import LIST_CSS from "./List.module.css";
 
 const LIST_ORDERED_CLASS = getModuleClass(LIST_CSS, "ordered");
-
 const LIST_UNORDERED_CLASS = getModuleClass(LIST_CSS, "unordered");
 
 /**

package/ui/block/Panel.d.ts

@@ -4,18 +4,18 @@ import { type PaddingVariants } from "../style/Padding.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import type { OptionalChildProps } from "../util/props.js";
-/**
- * Allowed semantic elements for a `<Panel>`.
- *
- * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelElement
- */
-export type PanelElement = "section" | "header" | "footer" | "nav" | "aside" | "article" | "div";
+import type { BlockElement } from "./Block.js";
 /**
  * Props for `Panel` — colour, status, and typography variants plus optional `children`.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelProps
  */
 export interface PanelProps extends ColorVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {
+    /**
+     * Element this `<Panel>` renders as, e.g. "header" to output a "<header>"
+     * @default "section"
+     */
+    as?: BlockElement | undefined;
 }
 /**
  * Full-width vertical region that paints the current surface colour. Use to break a page into stacked
@@ -30,4 +30,4 @@ export interface PanelProps extends ColorVariants, PaddingVariants, StatusVarian
  * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
-export declare function Panel({ children, ...props }: PanelProps): ReactElement;
+export declare function Panel({ as: Element, children, ...props }: PanelProps): ReactElement;

package/ui/block/Panel.js

@@ -19,7 +19,7 @@ const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
  * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
-export function Panel({ children, ...props }) {
-    return (_jsx("div", { className: getClass(PANEL_CLASS, //
+export function Panel({ as: Element = "section", children, ...props }) {
+    return (_jsx(Element, { className: getClass(PANEL_CLASS, //
         getStatusClass(props), getColorClass(props), getPaddingClass(props), getTypographyClass(props)), children: children }));
 }

package/ui/block/Panel.module.css

@@ -1,6 +1,9 @@
 @import "../style/layers.css";
 @import "../style/Stroke.module.css";
-@import "../style/Tint.module.css";
+@import "../style/Typography.module.css";
+@import "../style/Status.module.css";
+@import "../style/Color.module.css";
+@import "../style/Padding.module.css";
 
 /*
  * Full-width vertical region that paints the current surface. Panels always have zero block-space

package/ui/block/Panel.tsx

@@ -5,23 +5,23 @@ import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getTypographyClass, type TypographyVariants } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
+import type { BlockElement } from "./Block.js";
 import PANEL_CSS from "./Panel.module.css";
 
 const PANEL_CLASS = getModuleClass(PANEL_CSS, "panel");
 
-/**
- * Allowed semantic elements for a `<Panel>`.
- *
- * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelElement
- */
-export type PanelElement = "section" | "header" | "footer" | "nav" | "aside" | "article" | "div";
-
 /**
  * Props for `Panel` — colour, status, and typography variants plus optional `children`.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/PanelProps
  */
-export interface PanelProps extends ColorVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {}
+export interface PanelProps extends ColorVariants, PaddingVariants, StatusVariants, TypographyVariants, OptionalChildProps {
+	/**
+	 * Element this `<Panel>` renders as, e.g. "header" to output a "<header>"
+	 * @default "section"
+	 */
+	as?: BlockElement | undefined;
+}
 
 /**
  * Full-width vertical region that paints the current surface colour. Use to break a page into stacked
@@ -36,9 +36,9 @@ export interface PanelProps extends ColorVariants, PaddingVariants, StatusVarian
  * @example <Panel padding="xlarge" color="primary"><Title>Welcome</Title></Panel>
  * @see https://dhoulb.github.io/shelving/ui/block/Panel/Panel
  */
-export function Panel({ children, ...props }: PanelProps): ReactElement {
+export function Panel({ as: Element = "section", children, ...props }: PanelProps): ReactElement {
 	return (
-		<div
+		<Element
 			className={getClass(
 				PANEL_CLASS, //
 				getStatusClass(props),
@@ -48,6 +48,6 @@ export function Panel({ children, ...props }: PanelProps): ReactElement {
 			)}
 		>
 			{children}
-		</div>
+		</Element>
 	);
 }

package/ui/block/Paragraph.module.css

@@ -1,5 +1,7 @@
 @import "../style/layers.css";
 @import "../style/Space.module.css";
+@import "../style/Color.module.css";
+@import "../style/Typography.module.css";
 
 @layer components {
 	.paragraph,

package/ui/block/Preformatted.module.css

@@ -1,13 +1,11 @@
 @import "../style/layers.css";
 @import "../style/Color.module.css";
 @import "../style/Duration.module.css";
-@import "../style/Font.module.css";
 @import "../style/Radius.module.css";
-@import "../style/Size.module.css";
 @import "../style/Space.module.css";
 @import "../style/Stroke.module.css";
-@import "../style/Tint.module.css";
-@import "../style/Weight.module.css";
+@import "../style/Width.module.css";
+@import "../style/Typography.module.css";
 
 @layer components {
 	.preformatted,

package/ui/block/Section.d.ts

@@ -4,19 +4,18 @@ import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type WidthVariants } from "../style/Width.js";
 import type { OptionalChildProps } from "../util/props.js";
-/**
- * Semantic element names a `Section` may render as via its `as` prop.
- *
- * @see https://dhoulb.github.io/shelving/ui/block/Section/SectionElement
- */
-export type SectionElement = "section" | "header" | "footer" | "nav" | "aside" | "figure";
+import type { BlockElement } from "./Block.js";
 /**
  * Props for `Section` and its semantic siblings — colour, space, typography, and width variants plus an optional `as` element override.
  *
  * @see https://dhoulb.github.io/shelving/ui/block/Section/SectionProps
  */
 export interface SectionProps extends ColorVariants, SpaceVariants, TypographyVariants, WidthVariants, OptionalChildProps {
-    as?: SectionElement | undefined;
+    /**
+     * Element this `<Section>` renders as, e.g. "header" to output a "<header>"
+     * @default "section"
+     */
+    as?: BlockElement | undefined;
 }
 /**
  * Get the combined `className` string for a section from its styling variants.
@@ -30,7 +29,7 @@ export interface SectionProps extends ColorVariants, SpaceVariants, TypographyVa
  */
 export declare function getSectionClass(variants: SectionProps): string;
 /**
- * `<section>` block with block-level spacing.
+ * `<section>` block with section-level spacing.
  * - Pass `as` to render a different semantic element.
  *
  * @kind component
@@ -38,49 +37,41 @@ export declare function getSectionClass(variants: SectionProps): string;
  * @example <Section><Heading>About</Heading></Section>
  * @see https://dhoulb.github.io/shelving/ui/block/Section/Section
  */
-export declare function Section(props: SectionProps): ReactElement;
+export declare function Section({ as: Element, children, ...variants }: SectionProps): ReactElement;
 /**
- * `<header>` block with block-level spacing.
+ * `<header>` block with section-level spacing.
  *
  * @kind component
  * @returns Rendered `<header>` element.
  * @example <Header><Title>Welcome</Title></Header>
  * @see https://dhoulb.github.io/shelving/ui/block/Section/Header
  */
-export declare function Header(props: SectionProps): ReactElement;
+export declare function Header({ as: Element, children, ...variants }: SectionProps): ReactElement;
 /**
- * `<footer>` block with block-level spacing.
+ * `<footer>` block with section-level spacing.
  *
  * @kind component
  * @returns Rendered `<footer>` element.
  * @example <Footer><Small>© 2026</Small></Footer>
  * @see https://dhoulb.github.io/shelving/ui/block/Section/Footer
  */
-export declare function Footer(props: SectionProps): ReactElement;
-/**
- * `<nav>` block with block-level spacing.
- *
- * @kind component
- * @returns Rendered `<nav>` element.
- * @example <Nav><Link href="/">Home</Link></Nav>
- * @see https://dhoulb.github.io/shelving/ui/block/Section/Nav
- */
-export declare function Nav(props: SectionProps): ReactElement;
+export declare function Footer({ as: Element, children, ...variants }: SectionProps): ReactElement;
 /**
- * `<aside>` block with block-level spacing.
+ * `<article>` block with section-level spacing.
+ * - Use a `<Card>` instead to display boxed content.
  *
  * @kind component
- * @returns Rendered `<aside>` element.
- * @example <Aside width="narrow"><Paragraph>Sidebar</Paragraph></Aside>
- * @see https://dhoulb.github.io/shelving/ui/block/Section/Aside
+ * @returns Rendered `<article>` element.
+ * @see https://dhoulb.github.io/shelving/ui/block/Section/Article
  */
-export declare function Aside(props: SectionProps): ReactElement;
+export declare function Article({ as: Element, children, ...variants }: SectionProps): ReactElement;
 /**
- * `<figure>` block with block-level spacing. Pair with `<Caption>` for `<figcaption>` content.
+ * `<figure>` block with section-level spacing.
+ * - Pair with `<Caption>` for `<figcaption>` content.
  *
  * @kind component
  * @returns Rendered `<figure>` element.
  * @example <Figure><Image src="/cat.jpg" /><Caption>A cat</Caption></Figure>
  * @see https://dhoulb.github.io/shelving/ui/block/Section/Figure
  */
-export declare function Figure(props: SectionProps): ReactElement;
+export declare function Figure({ as: Element, children, ...variants }: SectionProps): ReactElement;