shelving 1.233.0 → 1.234.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.233.0",
+	"version": "1.234.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,14 +9,14 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.15",
+		"@biomejs/biome": "^2.4.16",
 		"@google-cloud/firestore": "^8.6.0",
 		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.3.14",
 		"@types/react": "^19.2.15",
 		"@types/react-dom": "^19.2.3",
-		"@typescript/native-preview": "^7.0.0-dev.20260523.1",
-		"firebase": "^12.13.0",
+		"@typescript/native-preview": "^7.0.0-dev.20260527.2",
+		"firebase": "^12.14.0",
 		"react": "^19.3.0-canary-fef12a01-20260413",
 		"react-dom": "^19.3.0-canary-fef12a01-20260413",
 		"typescript": "^5.9.3"

package/ui/README.md

@@ -155,6 +155,37 @@ Other tokens (`--*-padding`, `--*-spacing`, `--*-radius`, `--*-font`, `--*-size`
 
 This split is deliberate. The rebind is the right tool when an identity needs to propagate; for everything else, plain CSS inheritance (or no inheritance at all) is the right tool.
 
+### Retheming via the global scale
+
+The rebind pattern has a powerful consequence: because every surface component rebinds the scale from `inherit`, the page-level `:root` scale is the **cascade root they all fall back to**. Retinting a step at `:root` repaints every surface component at once — and *identically*, so a standalone `<Preformatted>` matches one nested in a `<Card>`, and both match the `<Card>` itself. This is almost always preferable to overriding each component's own hook (`--card-color-light`, `--preformatted-color-light`, …) one by one, which only themes that single component and leaves its siblings on the grey defaults.
+
+**But retint one step at a time, and know what else reads it.** The global scale isn't surfaces-only — the page baseline reads from it too. In `base.css`:
+
+```css
+body { color: var(--color-dark); background: var(--color-white); }
+```
+
+All body copy (Titles, Headings, Paragraphs, lists) has no `color` of its own; it inherits this baseline. So moving `--color-dark` at `:root` recolours **every word on the page**, not just text sitting on a card. Likewise `--color-vivid` tints borders and accents app-wide. Retint only the step whose reach you actually want:
+
+- `--color-light` — **surfaces** (Card / Preformatted / Tag / Code backgrounds). Safe to retint broadly; nothing paints page text or the page background from it.
+- `--color-vivid` — borders and accents everywhere. Retint only if you want app-wide accent recolouring.
+- `--color-dark` — **the page text colour**, via the `body` baseline above. Retinting this is a whole-page text recolour; usually not what a "themed surfaces" look wants.
+- `--color-black` / `--color-white` — the page extremes (max-contrast text, page background). Leave unless inverting (e.g. dark mode).
+
+The docs theme wants peach surfaces with normal near-black text, so it retints **only** `--color-light`:
+
+```css
+:root {
+  /* Surfaces go peach; text and the page background stay the library defaults. */
+  --color-light: color-mix(in srgb, #ff7a1a 14%, white);
+}
+```
+
+Two more rules keep a theme clean:
+
+- **If you do move a whole hue, move the anchor.** The `--light-<hue>` / `--dark-<hue>` tokens are defined in `base.css` as expressions over `--vivid-<hue>`, resolved lazily at use-time. Overriding `--vivid-orange` at `:root` re-tints the whole orange family for free, so `var(--light-orange)` / `var(--dark-orange)` stay coherent.
+- **Pin the exceptions back — and pin *every* step the component paints.** A component that should resist a global retint sets its own hooks. But a component rebinds the *whole* scale, and any step you leave unpinned still inherits the page colour. The docs site keeps Buttons purple by pinning both steps the default variant paints — `--button-color-light: var(--light-purple)` (background) and `--button-color-vivid: var(--vivid-purple)` (border/label) — plus `--button-color-white` for the `strong` label. Pinning only `vivid` would leave the default button's `bg=light` background inheriting the page peach: a purple-bordered peach button. Check which steps the variant in use actually paints (default = `light`+`vivid`, `strong` = `vivid`+`white`) and pin all of them.
+
 ### How `:first-child` / `:last-child` margin overrides work
 
 Every block-level component zeros its outer margins when it's the first or last child of its container — otherwise a Heading at the top of a Card would leave a strip of unwanted space. These rules live in `@layer overrides`, which beats every other layer including `variants`, so a `<Card space-large>` still collapses its abutting edges correctly.

package/ui/docs/DocumentationCard.js

@@ -6,9 +6,10 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Subheading } from "../block/Subheading.js";
 import { Code } from "../inline/Code.js";
 import { Flex } from "../style/Flex.js";
-import { DocumentationKind } from "./DocumentationKind.js";
+import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 /** Card renderer for a `tree-documentation` element — a summary card showing the heading, signatures, and description. */
 export function DocumentationCard({ path, title, name, kind, description, signatures }) {
     const href = joinPath(path, name);
-    return (_jsxs(Card, { href: href, children: [_jsx(Subheading, { children: _jsxs(Flex, { left: true, wrap: true, children: [_jsx(Code, { children: title ?? name }), kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), description && _jsx(Paragraph, { children: description })] }));
+    const color = kind ? getDocumentationKindColor(kind) : undefined;
+    return (_jsxs(Card, { href: href, ...(color ? { [color]: true } : {}), children: [_jsx(Subheading, { children: _jsxs(Flex, { left: true, wrap: true, children: [_jsx(Code, { children: title ?? name }), kind && _jsx(DocumentationKind, { kind: kind })] }) }), signatures?.map(sig => (_jsx(Preformatted, { children: sig }, sig))), description && _jsx(Paragraph, { children: description })] }));
 }

package/ui/docs/DocumentationCard.tsx

@@ -7,7 +7,7 @@ import { Preformatted } from "../block/Preformatted.js";
 import { Subheading } from "../block/Subheading.js";
 import { Code } from "../inline/Code.js";
 import { Flex } from "../style/Flex.js";
-import { DocumentationKind } from "./DocumentationKind.js";
+import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 
 interface DocumentationCardProps extends DocumentationElementProps {
 	path: AbsolutePath;
@@ -16,8 +16,9 @@ interface DocumentationCardProps extends DocumentationElementProps {
 /** Card renderer for a `tree-documentation` element — a summary card showing the heading, signatures, and description. */
 export function DocumentationCard({ path, title, name, kind, description, signatures }: DocumentationCardProps): ReactNode {
 	const href = joinPath(path, name);
+	const color = kind ? getDocumentationKindColor(kind) : undefined;
 	return (
-		<Card href={href}>
+		<Card href={href} {...(color ? { [color]: true } : {})}>
 			<Subheading>
 				<Flex left wrap>
 					<Code>{title ?? name}</Code>

package/ui/docs/DocumentationKind.d.ts

@@ -1,9 +1,15 @@
 import type { ReactElement } from "react";
+import type { Color } from "../style/Color.js";
 /** Props for `DocumentationKind`. */
 export interface DocumentationKindProps {
     /** The documentation kind (e.g. `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
     readonly kind: string;
 }
+/**
+ * Get the raw colour variant for a documented symbol's `kind`, or `undefined` for an unknown kind.
+ * - Shared source of truth so the kind tag and its surrounding card pick the same hue.
+ */
+export declare function getDocumentationKindColor(kind: string): Color | undefined;
 /**
  * Colour-coded tag for a documented symbol's kind.
  * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.

package/ui/docs/DocumentationKind.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Tag } from "../misc/Tag.js";
-/** Mapping from a documented symbol's `kind` to its tag colour. */
+/** Mapping from a documented symbol's `kind` to its raw colour variant. */
 const KIND_COLOR = {
     module: "red",
     function: "blue",
@@ -11,6 +11,13 @@ const KIND_COLOR = {
     method: "orange",
     property: "yellow",
 };
+/**
+ * Get the raw colour variant for a documented symbol's `kind`, or `undefined` for an unknown kind.
+ * - Shared source of truth so the kind tag and its surrounding card pick the same hue.
+ */
+export function getDocumentationKindColor(kind) {
+    return KIND_COLOR[kind];
+}
 /**
  * Colour-coded tag for a documented symbol's kind.
  * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
@@ -18,6 +25,6 @@ const KIND_COLOR = {
  * @example <DocumentationKind kind="function" />
  */
 export function DocumentationKind({ kind }) {
-    const color = KIND_COLOR[kind];
+    const color = getDocumentationKindColor(kind);
     return _jsx(Tag, { ...(color ? { [color]: true } : {}), children: kind });
 }

package/ui/docs/DocumentationKind.tsx

@@ -8,7 +8,7 @@ export interface DocumentationKindProps {
 	readonly kind: string;
 }
 
-/** Mapping from a documented symbol's `kind` to its tag colour. */
+/** Mapping from a documented symbol's `kind` to its raw colour variant. */
 const KIND_COLOR: { readonly [K in string]?: Color } = {
 	module: "red",
 	function: "blue",
@@ -20,6 +20,14 @@ const KIND_COLOR: { readonly [K in string]?: Color } = {
 	property: "yellow",
 };
 
+/**
+ * Get the raw colour variant for a documented symbol's `kind`, or `undefined` for an unknown kind.
+ * - Shared source of truth so the kind tag and its surrounding card pick the same hue.
+ */
+export function getDocumentationKindColor(kind: string): Color | undefined {
+	return KIND_COLOR[kind];
+}
+
 /**
  * Colour-coded tag for a documented symbol's kind.
  * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
@@ -27,6 +35,6 @@ const KIND_COLOR: { readonly [K in string]?: Color } = {
  * @example <DocumentationKind kind="function" />
  */
 export function DocumentationKind({ kind }: DocumentationKindProps): ReactElement {
-	const color = KIND_COLOR[kind];
+	const color = getDocumentationKindColor(kind);
 	return <Tag {...(color ? { [color]: true } : {})}>{kind}</Tag>;
 }

package/util/ansi.d.ts

@@ -14,12 +14,24 @@ export declare const ANSI_UNDERLINE: "\u001B[4m";
 export declare const ANSI_STRIKE: "\u001B[9m";
 export declare const ANSI_INVERSE: "\u001B[7m";
 export declare const ANSI_RESET = "\u001B[0m";
-/** Wrap a string in `ANSI_RED` or the ANSI color/style codes (at the start), and `ANSI_RESET` at the end. */
+/**
+ * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
+ *
+ * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ */
 export declare function ansiWrap(input: string, ...wrappers: ImmutableArray<string>): string;
-export declare const ANSI_WAITING: string;
-export declare const ANSI_SUCCESS: string;
-export declare const ANSI_FAILURE: string;
-export declare const ANSI_UP: string;
-export declare const ANSI_DOWN: string;
-export declare const ANSI_RIGHT: string;
-export declare const ANSI_LEFT: string;
+/**
+ * A lazily-coloured icon that re-evaluates its ANSI colouring against the live `NO_COLOR` environment variable every time it is converted to a string.
+ *
+ * - Used directly inside template literals (`${ANSI_SUCCESS}`), where JavaScript invokes `toString()` automatically, so the icon is coloured at use-time, not at module-load time.
+ */
+export type AnsiIcon = {
+    toString(): string;
+};
+export declare const ANSI_WAITING: AnsiIcon;
+export declare const ANSI_SUCCESS: AnsiIcon;
+export declare const ANSI_FAILURE: AnsiIcon;
+export declare const ANSI_UP: AnsiIcon;
+export declare const ANSI_DOWN: AnsiIcon;
+export declare const ANSI_RIGHT: AnsiIcon;
+export declare const ANSI_LEFT: AnsiIcon;

package/util/ansi.js

@@ -1,5 +1,5 @@
 import { DOWN, FAILURE, LEFT, RIGHT, SUCCESS, UP, WAITING } from "./constants.js";
-import { NO_COLOR } from "./env.js";
+import { getEnvBoolean } from "./env.js";
 // Colors.
 export const ANSI_DEFAULT = "\x1b[39m";
 export const ANSI_BLACK = "\x1b[30m";
@@ -18,17 +18,29 @@ export const ANSI_STRIKE = "\x1b[9m";
 export const ANSI_INVERSE = "\x1b[7m";
 // Reset.
 export const ANSI_RESET = "\x1b[0m";
-/** Wrap a string in `ANSI_RED` or the ANSI color/style codes (at the start), and `ANSI_RESET` at the end. */
+/**
+ * Wrap a string in the ANSI color/style codes (at the start), and `ANSI_RESET` at the end.
+ *
+ * - The `NO_COLOR` environment variable is read live on every call, so runtimes that populate `process.env` late (e.g. Cloudflare Workers, where `[vars]` bindings are only reliably available within the request scope) are honoured rather than baking in whatever `NO_COLOR` was at module-load time.
+ */
 export function ansiWrap(input, ...wrappers) {
-    if (NO_COLOR)
+    if (getEnvBoolean("NO_COLOR"))
         return input;
     return `${wrappers.join("")}${input}${ANSI_RESET}`;
 }
+/** Create a lazily-coloured {@link AnsiIcon} that wraps `icon` in `wrappers` on each `toString()`. */
+function _createAnsiIcon(icon, ...wrappers) {
+    return {
+        toString() {
+            return ansiWrap(icon, ...wrappers);
+        },
+    };
+}
 // Coloured icons.
-export const ANSI_WAITING = ansiWrap(WAITING, ANSI_BLUE);
-export const ANSI_SUCCESS = ansiWrap(SUCCESS, ANSI_GREEN);
-export const ANSI_FAILURE = ansiWrap(FAILURE, ANSI_RED);
-export const ANSI_UP = ansiWrap(UP, ANSI_BLUE);
-export const ANSI_DOWN = ansiWrap(DOWN, ANSI_BLUE);
-export const ANSI_RIGHT = ansiWrap(RIGHT, ANSI_BLUE);
-export const ANSI_LEFT = ansiWrap(LEFT, ANSI_BLUE);
+export const ANSI_WAITING = _createAnsiIcon(WAITING, ANSI_BLUE);
+export const ANSI_SUCCESS = _createAnsiIcon(SUCCESS, ANSI_GREEN);
+export const ANSI_FAILURE = _createAnsiIcon(FAILURE, ANSI_RED);
+export const ANSI_UP = _createAnsiIcon(UP, ANSI_BLUE);
+export const ANSI_DOWN = _createAnsiIcon(DOWN, ANSI_BLUE);
+export const ANSI_RIGHT = _createAnsiIcon(RIGHT, ANSI_BLUE);
+export const ANSI_LEFT = _createAnsiIcon(LEFT, ANSI_BLUE);

package/util/env.d.ts

@@ -19,5 +19,3 @@ export declare function getEnvBoolean(name: string): boolean | undefined;
  * @throws `RequiredError` if the env variable is any other value.
  */
 export declare function requireEnvBoolean(name: string, caller?: AnyCaller): boolean;
-/** The `NO_COLOR` environment variable is commonly used to indicate that ANSI output shouldn't have color. */
-export declare const NO_COLOR: boolean;

package/util/env.js

@@ -40,5 +40,3 @@ export function requireEnvBoolean(name, caller = requireEnvBoolean) {
         throw new RequiredError(`Environment variable "${name}" must be boolean`, { caller });
     return env;
 }
-/** The `NO_COLOR` environment variable is commonly used to indicate that ANSI output shouldn't have color. */
-export const NO_COLOR = getEnvBoolean("NO_COLOR") ?? false;