shelving 1.199.2 → 1.200.0

package/index.js

@@ -12,6 +12,7 @@ export * from "./error/index.js";
 export * from "./markup/index.js";
 // export * from "./react/index.js"; // Not exported.
 export * from "./schema/index.js";
+// export * from "./ui/index.js"; // Not exported — shelving/ui requires a bundler (CSS Modules, JSX) and is consumed as source.
 export * from "./sequence/index.js";
 export * from "./store/index.js";
 // export * from "./test/index.js"; // Not exported.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.199.2",
+	"version": "1.200.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -11,16 +11,18 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.14",
 		"@google-cloud/firestore": "^8.5.0",
+		"@heroicons/react": "^2.2.0",
 		"@types/bun": "^1.3.13",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
 		"@typescript/native-preview": "^7.0.0-dev.20260502.1",
 		"firebase": "^12.12.1",
-		"react": "^19.2.5",
-		"react-dom": "^19.2.5"
+		"react": "canary",
+		"react-dom": "canary"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=7.0.0",
+		"@heroicons/react": ">=2.0.0",
 		"firebase": ">=11.0.0",
 		"react": ">=19.0.0"
 	},
@@ -41,6 +43,7 @@
 		"./sequence": "./sequence/index.js",
 		"./store": "./store/index.js",
 		"./test": "./test/index.js",
+		"./ui": "./ui/index.js",
 		"./util": "./util/index.js"
 	},
 	"description": "Toolkit for using data in JavaScript.",
@@ -68,12 +71,14 @@
 		"fix:0:lint": "biome check --write .",
 		"build": "bun run --sequential build:*",
 		"build:0:setup": "rm -rf ./dist && mkdir -p ./dist",
-		"build:1:copy": "cp package.json dist/package.json && cp LICENSE.md dist/LICENSE.md && cp README.md dist/README.md && cp .npmignore dist/.npmignore",
+		"build:1:copy": "cp package.json dist/package.json && cp LICENSE.md dist/LICENSE.md && cp README.md dist/README.md && cp .npmignore dist/.npmignore && cp -r modules/ui dist/ui",
 		"build:2:emit": "tsgo",
 		"build:3:syntax": "bun run ./dist/index.js",
 		"build:4:unit": "bun test ./dist/**/*.test.js --concurrent --only-failures --bail"
 	},
-	"sideEffects": false,
+	"sideEffects": [
+		"*.css"
+	],
 	"type": "module",
 	"types": "./index.d.ts"
 }

package/ui/app/App.d.ts

@@ -0,0 +1,11 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { PossibleMetaData } from "../util/meta.js";
+export interface AppProps extends PossibleMetaData {
+    children: ReactNode;
+}
+/**
+ * Root component for an application.
+ * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
+ * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ */
+export declare function App({ children, ...metadata }: AppProps): ReactElement;

package/ui/app/App.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { Meta } from "../misc/Meta.js";
+import APP_CSS from "./App.module.css";
+const _appClass = APP_CSS.app;
+/**
+ * Root component for an application.
+ * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
+ * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ */
+export function App({ children, ...metadata }) {
+    useEffect(() => {
+        if (!_appClass)
+            return;
+        document.body.classList.add(_appClass);
+        return () => {
+            document.body.classList.remove(_appClass);
+        };
+    }, []);
+    return _jsx(Meta, { ...metadata, children: children });
+}

package/ui/app/App.module.css

@@ -0,0 +1,168 @@
+:root {
+	color-scheme: light;
+
+	/* Widths */
+	--width-narrow: min(100%, 22.5rem);
+	--width-wide: min(100%, 33.75rem);
+
+	/* Font weights */
+	--weight-normal: 400;
+	--weight-strong: 700;
+	--weight-label: var(--weight-strong);
+
+	/* Font faces */
+	--font-sans: system-ui;
+	--font-mono: "Courier New", "Courier", monospace;
+	--font-serif: "Palatino", "Garamond", serif;
+
+	/* Semantic font faces */
+	--font-body: var(--font-sans);
+	--font-code: var(--font-mono);
+
+	/* Font sizes */
+	--size-small: 0.875rem;
+	--size-normal: 1rem;
+	--size-large: 1.5rem;
+	--size-xlarge: 2.5rem;
+	--size-xxlarge: 5rem;
+	--size-icon: 1.5rem;
+
+	/* Line heights */
+	--leading-none: 0;
+	--leading-tight: 1.25;
+	--leading-normal: 1.5;
+
+	/* Spacings */
+	--spacing-small: 0.25rem;
+	--spacing-inline: 0.5rem;
+	--spacing-paragraph: 1rem;
+	--spacing-element: 0.75rem;
+	--spacing-block: 1rem;
+	--spacing-spacious: 3rem;
+
+	/* Border widths */
+	--border-element: 2px;
+	--border-block: 2px;
+	--border-focus: 3px;
+
+	/* Radii */
+	--radius-inline: 0.25rem;
+	--radius-element: 0.5rem;
+	--radius-block: 1rem;
+
+	/* Durations */
+	--duration-fast: 150ms;
+	--duration-normal: 300ms;
+	--duration-slow: 600ms;
+
+	/* Grows */
+	--grow-greedy: 1000000; /* Take up as much space as possible, unless other elements are greedy too. */
+	--grow-normal: 1000; /* Take up a normal amount of space. */
+	--grow-timid: 1; /* Take up minimal space, unless the only other elements are timid too. */
+	--grow-none: 0;
+
+	/* Colors */
+	--color-blue: #156ef4;
+	--color-cyan: #15edf4;
+	--color-green: #8ce814;
+	--color-orange: #ffb21a;
+	--color-pink: #e718a2;
+	--color-purple: #ad15f4;
+	--color-red: #e5352f;
+	--color-yellow: #ffe01a;
+	--color-black: black;
+	--color-gray: color-mix(var(--color-blue) 30%, rgb(128 128 128)); /* Used as the "tone" color for scale of grays. */
+	--color-white: white;
+
+	/* Grays */
+	--gray-05: color-mix(var(--color-gray) 10%, var(--color-white));
+	--gray-10: color-mix(var(--color-gray) 20%, var(--color-white));
+	--gray-20: color-mix(var(--color-gray) 40%, var(--color-white));
+	--gray-30: color-mix(var(--color-gray) 60%, var(--color-white));
+	--gray-40: color-mix(var(--color-gray) 80%, var(--color-white));
+	--gray-50: var(--color-gray);
+	--gray-60: color-mix(var(--color-gray) 80%, var(--color-black));
+	--gray-70: color-mix(var(--color-gray) 60%, var(--color-black));
+	--gray-80: color-mix(var(--color-gray) 40%, var(--color-black));
+	--gray-90: color-mix(var(--color-gray) 20%, var(--color-black));
+	--gray-95: color-mix(var(--color-gray) 10%, var(--color-black));
+
+	/* Named colors */
+	--color-text: var(--color-black);
+	--color-contrast: var(--color-white); /* Contrast color — must be readable on `--color-text` */
+	--color-quiet: var(--gray-40); /* Quiet color is grey, used for secondary text etc. */
+	--color-bg: var(--color-white); /* Background color is usually the opposite of text colour. */
+	--color-border: var(--gray-10);
+	--color-overlay: color-mix(in srgb, var(--color-text) 40%, transparent);
+	--color-link: var(--color-blue); /* Links are usually blue. */
+	--color-focus: var(--color-blue); /* Focus is usually blue. */
+	--color-surface: var(--gray-10); /* Surface color is used for notices and buttons — must be readable on `--color-text` */
+
+	/* Shadows */
+	--shadow-element: 0 3px 16px -8px var(--color-overlay);
+	--shadow-block: 0 4px 24px -12px var(--color-overlay);
+
+	/* Primary colors */
+	--primary-text: var(--color-blue);
+	--primary-contrast: var(--color-white);
+	--primary-surface: color-mix(in srgb, var(--primary-text) 12%, white);
+
+	/* Secondary colors */
+	--secondary-text: var(--color-purple);
+	--secondary-contrast: var(--color-white);
+	--secondary-surface: color-mix(in srgb, var(--secondary-text) 12%, white);
+
+	/* Tertiary colors */
+	--tertiary-text: var(--color-cyan);
+	--tertiary-contrast: var(--color-white);
+	--tertiary-surface: color-mix(in srgb, var(--tertiary-text) 12%, white);
+
+	/* Quiet colors */
+	--quiet-text: var(--color-quiet);
+	--quiet-contrast: var(--color-contrast);
+	--quiet-surface: var(--color-surface);
+
+	/* Focus colors */
+	--focus-text: var(--color-focus);
+	--focus-contrast: var(--color-white);
+	--focus-surface: color-mix(in srgb, var(--focus-text) 12%, white);
+
+	/* Loading colors */
+	--loading-text: var(--color-loading);
+	--loading-contrast: var(--color-contrast);
+	--loading-surface: var(--color-surface);
+
+	/* Info colors */
+	--info-text: var(--color-blue);
+	--info-contrast: var(--color-white);
+	--info-surface: color-mix(in srgb, var(--info-text) 12%, white);
+
+	/* Success colors */
+	--success-text: var(--color-green);
+	--success-contrast: var(--color-white);
+	--success-surface: color-mix(in srgb, var(--success-text) 12%, white);
+
+	/* Warning colors */
+	--warning-text: var(--color-orange);
+	--warning-contrast: var(--color-white);
+	--warning-surface: color-mix(in srgb, var(--warning-text) 12%, white);
+
+	/* Error colors */
+	--error-text: var(--color-red);
+	--error-contrast: var(--color-white);
+	--error-surface: color-mix(in srgb, var(--error-text) 12%, white);
+
+	/* Danger colors */
+	--danger-text: var(--color-red);
+	--danger-contrast: var(--color-white);
+	--danger-surface: color-mix(in srgb, var(--danger-text) 12%, white);
+
+	/* Highlight colors */
+	--highlight-text: var(--color-yellow);
+	--highlight-contrast: var(--color-black);
+	--highlight-surface: color-mix(in srgb, var(--highlight-text) 12%, white);
+}
+
+.app {
+	/* Empty */
+}

package/ui/app/App.tsx

@@ -0,0 +1,26 @@
+import { type ReactElement, type ReactNode, useEffect } from "react";
+import { Meta } from "../misc/Meta.js";
+import type { PossibleMetaData } from "../util/meta.js";
+import APP_CSS from "./App.module.css";
+
+export interface AppProps extends PossibleMetaData {
+	children: ReactNode;
+}
+
+const _appClass = APP_CSS.app;
+
+/**
+ * Root component for an application.
+ * - Adds the theme CSS class (which sets CSS token variables on `:root`) to `document.body` on mount and removes it on unmount.
+ * - Provides a `Meta` context to its children so descendants can read or update metadata.
+ */
+export function App({ children, ...metadata }: AppProps): ReactElement {
+	useEffect(() => {
+		if (!_appClass) return;
+		document.body.classList.add(_appClass);
+		return () => {
+			document.body.classList.remove(_appClass);
+		};
+	}, []);
+	return <Meta {...metadata}>{children}</Meta>;
+}

package/ui/app/index.d.ts

@@ -0,0 +1 @@
+export * from "./App.js";

package/ui/app/index.js

@@ -0,0 +1 @@
+export * from "./App.js";

package/ui/app/index.ts

@@ -0,0 +1 @@
+export * from "./App.js";

package/ui/block/Address.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement, ReactNode } from "react";
+import { type AddressData } from "../../schema/AddressSchema.js";
+import type { Nullish } from "../../util/null.js";
+export interface AddressProps {
+    children: ReactNode;
+}
+export interface PhysicalAddressProps {
+    name?: Nullish<string>;
+    address: Nullish<AddressData>;
+}
+export interface EmailAddressProps {
+    name?: Nullish<string>;
+    email: Nullish<string>;
+}
+/** Show any kind of contact data. */
+export declare function Address({ children }: AddressProps): import("react/jsx-runtime").JSX.Element;
+/** Show an optional `AddressData` object correctly on screen. */
+export declare function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement;
+/** Show an optional email address string correctly on screen. */
+export declare function EmailAddress({ name, email }: EmailAddressProps): ReactElement;

package/ui/block/Address.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatAddress } from "../../schema/AddressSchema.js";
+import { Small } from "../inline/Small.js";
+import { Strong } from "../inline/Strong.js";
+import styles from "./Address.module.css";
+/** Show any kind of contact data. */
+export function Address({ children }) {
+    return _jsx("address", { className: styles.address, children: children });
+}
+/** Show an optional `AddressData` object correctly on screen. */
+export function PhysicalAddress({ name, address }) {
+    return (_jsxs(Address, { children: [name && _jsx(Strong, { children: name }), name && "\n", address ? formatAddress(address) : _jsx(Small, { children: "No address" })] }));
+}
+/** Show an optional email address string correctly on screen. */
+export function EmailAddress({ name, email }) {
+    return (_jsxs(Address, { children: [name && _jsx(Strong, { children: name }), name && "\n", email ? _jsx("a", { href: `mailto:${email}`, children: email }) : _jsx(Small, { children: "No email" })] }));
+}

package/ui/block/Address.module.css

@@ -0,0 +1,20 @@
+.address,
+.prose address {
+	/* Box */
+	display: block;
+	margin-inline: 0;
+	margin-block: var(--address-spacing, var(--spacing-block));
+
+	/* Contents */
+	white-space: pre-line;
+	font-style: normal;
+	text-align: left;
+
+	/* Styles */
+	&:first-child {
+		margin-block-start: 0;
+	}
+	&:last-child {
+		margin-block-end: 0;
+	}
+}

package/ui/block/Address.tsx

@@ -0,0 +1,47 @@
+import type { ReactElement, ReactNode } from "react";
+import { type AddressData, formatAddress } from "../../schema/AddressSchema.js";
+import type { Nullish } from "../../util/null.js";
+import { Small } from "../inline/Small.js";
+import { Strong } from "../inline/Strong.js";
+import styles from "./Address.module.css";
+
+export interface AddressProps {
+	children: ReactNode;
+}
+
+export interface PhysicalAddressProps {
+	name?: Nullish<string>;
+	address: Nullish<AddressData>;
+}
+
+export interface EmailAddressProps {
+	name?: Nullish<string>;
+	email: Nullish<string>;
+}
+
+/** Show any kind of contact data. */
+export function Address({ children }: AddressProps) {
+	return <address className={styles.address}>{children}</address>;
+}
+
+/** Show an optional `AddressData` object correctly on screen. */
+export function PhysicalAddress({ name, address }: PhysicalAddressProps): ReactElement {
+	return (
+		<Address>
+			{name && <Strong>{name}</Strong>}
+			{name && "\n"}
+			{address ? formatAddress(address) : <Small>No address</Small>}
+		</Address>
+	);
+}
+
+/** Show an optional email address string correctly on screen. */
+export function EmailAddress({ name, email }: EmailAddressProps): ReactElement {
+	return (
+		<Address>
+			{name && <Strong>{name}</Strong>}
+			{name && "\n"}
+			{email ? <a href={`mailto:${email}`}>{email}</a> : <Small>No email</Small>}
+		</Address>
+	);
+}

package/ui/block/Blockquote.d.ts

@@ -0,0 +1,5 @@
+import type { ReactElement, ReactNode } from "react";
+export interface BlockquoteProps {
+    children?: ReactNode;
+}
+export declare function Blockquote({ children }: BlockquoteProps): ReactElement;

package/ui/block/Blockquote.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import styles from "./Blockquote.module.css";
+export function Blockquote({ children }) {
+    return _jsx("blockquote", { className: styles.blockquote, children: children });
+}

package/ui/block/Blockquote.module.css

@@ -0,0 +1,21 @@
+.blockquote,
+.prose blockquote {
+	/* Box */
+	display: block;
+	margin-inline: 0;
+	margin-block: var(--blockquote-spacing, var(--spacing-block));
+	border-inline-start: var(--blockquote-border, var(--border-focus)) solid var(--blockquote-color-border, var(--color-border));
+	padding-inline-start: var(--blockquote-padding, var(--spacing-paragraph));
+	padding-block: var(--spacing-inline);
+
+	/* Style */
+	color: var(--blockquote-color-text, inherit);
+
+	/* Styles */
+	&:first-child {
+		margin-block-start: 0;
+	}
+	&:last-child {
+		margin-block-end: 0;
+	}
+}

package/ui/block/Blockquote.tsx

@@ -0,0 +1,10 @@
+import type { ReactElement, ReactNode } from "react";
+import styles from "./Blockquote.module.css";
+
+export interface BlockquoteProps {
+	children?: ReactNode;
+}
+
+export function Blockquote({ children }: BlockquoteProps): ReactElement {
+	return <blockquote className={styles.blockquote}>{children}</blockquote>;
+}

package/ui/block/Card.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement, ReactNode } from "react";
+export interface CardProps {
+    children: ReactNode;
+    /** Constrain the section to narrow width (defaults to full-width). */
+    narrow?: boolean;
+    /** Constrain the section to wide width (defaults to full-width). */
+    wide?: boolean;
+}
+/** Cards are boxed areas for content to sit within. */
+export declare function Card({ children, ...variants }: CardProps): ReactElement;

package/ui/block/Card.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getModuleClass } from "../util/css.js";
+import styles from "./Card.module.css";
+/** Cards are boxed areas for content to sit within. */
+export function Card({ children, ...variants }) {
+    return _jsx("section", { className: getModuleClass(styles, "card", variants), children: children });
+}

package/ui/block/Card.module.css

@@ -0,0 +1,32 @@
+.card {
+	/* Box */
+	position: relative;
+	margin-inline: 0;
+	margin-block: var(--card-spacing, var(--spacing-block));
+
+	/* Style */
+	background: var(--card-color-bg, var(--color-surface));
+	border: var(--card-border, var(--border-block)) solid var(--card-color-border, var(--color-border));
+	padding: var(--card-padding, var(--spacing-block));
+	color: var(--card-color-text, var(--color-text));
+	border-radius: var(--card-radius, var(--radius-block));
+	box-shadow: var(--card-shadow, none);
+
+	/* Psuedo-classes */
+	&:first-child {
+		margin-block-start: 0;
+	}
+	&:last-child {
+		margin-block-end: 0;
+	}
+
+	/* Variants */
+	&.narrow {
+		margin-inline: auto;
+		max-width: var(--section-width-narrow, var(--width-narrow));
+	}
+	&.wide {
+		margin-inline: auto;
+		max-width: var(--section-width-wide, var(--width-wide));
+	}
+}

package/ui/block/Card.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement, ReactNode } from "react";
+import { getModuleClass } from "../util/css.js";
+import styles from "./Card.module.css";
+
+export interface CardProps {
+	children: ReactNode;
+
+	/** Constrain the section to narrow width (defaults to full-width). */
+	narrow?: boolean;
+
+	/** Constrain the section to wide width (defaults to full-width). */
+	wide?: boolean;
+}
+
+/** Cards are boxed areas for content to sit within. */
+export function Card({ children, ...variants }: CardProps): ReactElement {
+	return <section className={getModuleClass(styles, "card", variants)}>{children}</section>;
+}

package/ui/block/Divider.d.ts

@@ -0,0 +1,6 @@
+declare const _componentProps: unique symbol;
+export interface DividerProps {
+    readonly [_componentProps]?: never;
+}
+export declare function Divider(): import("react/jsx-runtime").JSX.Element;
+export {};

package/ui/block/Divider.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import styles from "./Divider.module.css";
+export function Divider() {
+    return _jsx("hr", { className: styles.divider });
+}

package/ui/block/Divider.module.css

@@ -0,0 +1,19 @@
+.divider,
+.prose hr {
+	/* Box */
+	display: block;
+	border: 0;
+	margin-inline: 0;
+	margin-block: var(--divider-spacing, var(--spacing-block));
+
+	/* Style */
+	border-block-start: var(--divider-border, var(--border-block)) solid var(--divider-color, var(--color-border));
+
+	/* Psuedo-classes */
+	&:first-child {
+		margin-block-start: 0;
+	}
+	&:last-child {
+		margin-block-end: 0;
+	}
+}

package/ui/block/Divider.tsx

@@ -0,0 +1,11 @@
+import styles from "./Divider.module.css";
+
+declare const _componentProps: unique symbol;
+
+export interface DividerProps {
+	readonly [_componentProps]?: never;
+}
+
+export function Divider() {
+	return <hr className={styles.divider} />;
+}

package/ui/block/Element.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement, ReactNode } from "react";
+import ELEMENT_CSS from "./Element.module.css";
+/** Variants for elements. */
+export interface ElementProps {
+    children?: ReactNode;
+}
+/** A single element with element spacing. */
+export declare function Element({ children }: ElementProps): ReactElement;
+export { ELEMENT_CSS };

package/ui/block/Element.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import ELEMENT_CSS from "./Element.module.css";
+/** A single element with element spacing. */
+export function Element({ children }) {
+    return _jsx("div", { className: ELEMENT_CSS.element, children: children });
+}
+export { ELEMENT_CSS };

package/ui/block/Element.module.css

@@ -0,0 +1,12 @@
+.element {
+	/* Box */
+	margin: var(--element-spacing, var(--spacing-element)) 0;
+
+	/* Psuedo-classes */
+	&:first-child {
+		margin-top: 0;
+	}
+	&:last-child {
+		margin-bottom: 0;
+	}
+}

package/ui/block/Element.tsx

@@ -0,0 +1,14 @@
+import type { ReactElement, ReactNode } from "react";
+import ELEMENT_CSS from "./Element.module.css";
+
+/** Variants for elements. */
+export interface ElementProps {
+	children?: ReactNode;
+}
+
+/** A single element with element spacing. */
+export function Element({ children }: ElementProps): ReactElement {
+	return <div className={ELEMENT_CSS.element}>{children}</div>;
+}
+
+export { ELEMENT_CSS };

package/ui/block/Elements.d.ts

@@ -0,0 +1,27 @@
+import type { ReactElement, ReactNode } from "react";
+import ELEMENTS_CSS from "./Elements.module.css";
+/** Variants for elements. */
+export interface ElementsVariants {
+    /** Wrap overflowing elements onto the next line (defaults to no wrapping). */
+    wrap?: boolean | undefined;
+    /** Display the elements as a column (defaults to row). */
+    column?: boolean | undefined;
+    /** Align the elements to the left (defaults to stretch). */
+    left?: boolean | undefined;
+    /** Align the elements to the center (defaults to stretch). */
+    center?: boolean | undefined;
+    /** Align the elements to the right (defaults to stretch). */
+    right?: boolean | undefined;
+    /** Align the elements stretch (defaults to stretch). */
+    stretch?: boolean | undefined;
+    /** Remove the gap between elements. */
+    flush?: boolean | undefined;
+    /** Reverse the order of the elements. */
+    reverse?: boolean | undefined;
+}
+export interface ElementsProps extends ElementsVariants {
+    children?: ReactNode | undefined;
+}
+/** Block with element spacing and flex children. */
+export declare function Elements({ children, ...variants }: ElementsProps): ReactElement;
+export { ELEMENTS_CSS };