shelving 1.285.0 → 1.285.2

package/db/provider/CacheDBProvider.js

@@ -89,7 +89,10 @@ export class CacheDBProvider extends ThroughDBProvider {
      */
     async transact(callback) {
         let transaction;
-        const result = await this.source.transact(provider => callback((transaction = new RecordingDBProvider(this.cloneWith(provider)))));
+        const result = await this.source.transact(provider => {
+            transaction = new RecordingDBProvider(this.cloneWith(provider));
+            return callback(transaction);
+        });
         if (transaction)
             await transaction.replayWrites(this.memory); // Commit the recorded writes into the cache.
         return result;

package/extract/TypescriptExtractor.js

@@ -89,7 +89,7 @@ function _getServer() {
     return _server;
 }
 /** Close the shared compiler server after a short idle, so the process can exit without callers managing the lifecycle. */
-function _scheduleClose() {
+async function _scheduleClose() {
     if (_timer)
         clearTimeout(_timer);
     _timer = setTimeout(() => {
@@ -98,7 +98,7 @@ function _scheduleClose() {
         _previous = undefined;
         _timer = undefined;
         try {
-            server?.api.close();
+            void server?.api.close();
         }
         catch {
             // Closing can reject in-flight bookkeeping requests — harmless on shutdown.
@@ -135,8 +135,8 @@ function _parseSourceFile(text) {
             return source;
         }
         finally {
-            snapshot.dispose();
-            _scheduleClose();
+            await snapshot.dispose();
+            await _scheduleClose();
         }
     };
     const result = _queue.then(task, task);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.285.0",
+	"version": "1.285.2",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,21 +9,17 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.8",
+		"@biomejs/biome": "^2.5.13",
 		"@heroicons/react": "^2.2.0",
-		"@types/bun": "^1.3.14",
-		"@types/react": "^19.2.18",
-		"@types/react-dom": "^19.2.4",
-		"react": "^19.3.0-canary-fef12a01-20260413",
-		"react-dom": "^19.3.0-canary-fef12a01-20260413",
-		"stylelint": "^17.14.1",
+		"@types/bun": "^1.4.2",
+		"@types/react": "^19.3.0",
+		"@types/react-dom": "^19.3.0",
+		"stylelint": "^17.15.0",
 		"stylelint-config-standard": "^40.0.0",
 		"typescript": "^7.0.2"
 	},
 	"peerDependencies": {
-		"@heroicons/react": ">=2.0.0",
-		"react": ">=19.0.0",
-		"react-dom": ">=19.0.0"
+		"@heroicons/react": ">=2.0.0"
 	},
 	"exports": {
 		".": "./index.js",
@@ -83,5 +79,9 @@
 		"*.css"
 	],
 	"type": "module",
-	"types": "./index.d.ts"
+	"types": "./index.d.ts",
+	"dependencies": {
+		"react": "^19.3.0",
+		"react-dom": "^19.3.0"
+	}
 }

package/schema/PasswordSchema.d.ts

@@ -3,15 +3,13 @@ import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
  * Schema that defines a valid password string.
  *
  * - Defaults the `<input />` hint to `"password"`, but a caller can override it (e.g. `"text"` for a show-password toggle).
- * - Never formats the value for display (`format()` always returns `""`).
+ * - Formats the value unchanged (like `StringSchema`) so a password `<input />` can hold and mask it — hiding the value is the input's job, not the schema's.
  *
  * @example new PasswordSchema({}).validate("hunter2"); // Returns "hunter2"
  * @see https://shelving.cc/schema/PasswordSchema
  */
 export declare class PasswordSchema extends StringSchema {
     constructor({ one, title, min, input, ...options }?: StringSchemaOptions);
-    /** Always returns `""` — passwords are never shown. */
-    format(): string;
 }
 /**
  * Sugar instance of `PasswordSchema` for a password string. Equivalent to `new PasswordSchema({})`.

package/schema/PasswordSchema.js

@@ -3,7 +3,7 @@ import { StringSchema } from "./StringSchema.js";
  * Schema that defines a valid password string.
  *
  * - Defaults the `<input />` hint to `"password"`, but a caller can override it (e.g. `"text"` for a show-password toggle).
- * - Never formats the value for display (`format()` always returns `""`).
+ * - Formats the value unchanged (like `StringSchema`) so a password `<input />` can hold and mask it — hiding the value is the input's job, not the schema's.
  *
  * @example new PasswordSchema({}).validate("hunter2"); // Returns "hunter2"
  * @see https://shelving.cc/schema/PasswordSchema
@@ -12,10 +12,6 @@ export class PasswordSchema extends StringSchema {
     constructor({ one = "password", title = "Password", min = 6, input = "password", ...options } = {}) {
         super({ one, title, min, input, ...options });
     }
-    /** Always returns `""` — passwords are never shown. */
-    format() {
-        return ""; // Never format a password for display.
-    }
 }
 /**
  * Sugar instance of `PasswordSchema` for a password string. Equivalent to `new PasswordSchema({})`.

package/ui/input/SchemaInput.d.ts

@@ -115,13 +115,14 @@ export interface StringSchemaInputProps extends SchemaInputProps<StringSchema, u
 }
 /**
  * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
+ * - Publishes the sanitized value through `onValue`; the schema's `format()` only shapes what the input displays (on first render and on blur).
  *
  * @returns A `TextInput` element bound to the schema.
  * @kind component
  * @example <StringSchemaInput name="email" schema={EMAIL} />
  * @see https://shelving.cc/ui/StringSchemaInput
  */
-export declare function StringSchemaInput({ schema, value, ...props }: StringSchemaInputProps): ReactElement;
+export declare function StringSchemaInput({ schema, value, onValue, ...props }: StringSchemaInputProps): ReactElement;
 /**
  * Props for `ArraySchemaInput`, the `ArraySchema` input variant.
  *

package/ui/input/SchemaInput.js

@@ -123,14 +123,15 @@ export function BooleanSchemaInput({ schema, value, ...props }) {
 }
 /**
  * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
+ * - Publishes the sanitized value through `onValue`; the schema's `format()` only shapes what the input displays (on first render and on blur).
  *
  * @returns A `TextInput` element bound to the schema.
  * @kind component
  * @example <StringSchemaInput name="email" schema={EMAIL} />
  * @see https://shelving.cc/ui/StringSchemaInput
  */
-export function StringSchemaInput({ schema, value, ...props }) {
-    return _jsx(TextInput, { ...schema, value: getString(value), formatter: str => schema.format(schema.sanitize(str)), ...props });
+export function StringSchemaInput({ schema, value, onValue, ...props }) {
+    return (_jsx(TextInput, { ...schema, value: getString(value), onValue: str => onValue(str === undefined ? undefined : schema.sanitize(str)), formatter: str => schema.format(schema.sanitize(str)), ...props }));
 }
 /**
  * Show an `ArrayInput` for an `ArraySchema`.

package/ui/input/SchemaInput.test.tsx

@@ -1,9 +1,34 @@
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
-import { StringSchema } from "shelving/schema";
-import { StringSchemaInput } from "shelving/ui";
+import { PASSWORD, StringSchema, URL_SCHEMA } from "shelving/schema";
+import { StringSchemaInput, TextInput, type TextInputProps } from "shelving/ui";
 import { PASSTHROUGH } from "shelving/util/function";
 
+/** A `StringSchema` with a non-identity `format()` (wraps in brackets) so display and published values differ. */
+class BracketSchema extends StringSchema {
+	override format(str: string): string {
+		return str ? `[${str}]` : str;
+	}
+}
+
+/**
+ * Render a `StringSchemaInput` down to its `<input>` element's props, so the event handlers can be called directly.
+ * - Neither component uses hooks, so calling them as plain functions is safe without a DOM.
+ */
+function _getInputProps(schema: StringSchema, onValue: (value: string | undefined) => void, value?: string): _InputProps {
+	const props: { schema: StringSchema; name: string; onValue: typeof onValue; value?: string } = { schema, name: "field", onValue };
+	if (value !== undefined) props.value = value;
+	return TextInput(StringSchemaInput(props).props as TextInputProps).props as _InputProps;
+}
+
+/** The `<input>` props the tests read and call. */
+interface _InputProps {
+	readonly type?: string;
+	readonly defaultValue?: string;
+	onInput(e: { currentTarget: { value: string } }): void;
+	onBlur(e: { currentTarget: { value: string } }): void;
+}
+
 describe("StringSchemaInput", () => {
 	test("formats the initial value to its clean sanitized value", () => {
 		// The `formatter` runs `schema.sanitize()` then `schema.format()`, so runs of whitespace collapse and the value trims.
@@ -23,14 +48,55 @@ describe("StringSchemaInput", () => {
 
 	test("applies a subclass `format()` after sanitizing", () => {
 		// A subclass `format()` is non-identity (here wrapping in brackets), so the clean value is sanitized then formatted.
-		class BracketSchema extends StringSchema {
-			override format(str: string): string {
-				return str ? `[${str}]` : str;
-			}
-		}
 		const schema = new BracketSchema({});
 		const html = renderToStaticMarkup(<StringSchemaInput name="tag" schema={schema} value="  abc  " onValue={PASSTHROUGH} />);
 
 		expect(html).toContain('value="[abc]"');
 	});
+
+	test("publishes the sanitized value, not the formatted one", () => {
+		// `format()` is for display only — the store must receive a value that re-validates.
+		const values: (string | undefined)[] = [];
+		const input = _getInputProps(new BracketSchema({}), v => void values.push(v));
+		input.onInput({ currentTarget: { value: "  abc  " } });
+
+		expect(values).toEqual(["abc"]);
+	});
+
+	test("reformats the displayed value on blur without publishing it", () => {
+		const values: (string | undefined)[] = [];
+		const input = _getInputProps(new BracketSchema({}), v => void values.push(v));
+		const currentTarget = { value: "  abc  " };
+		input.onBlur({ currentTarget });
+
+		expect(currentTarget.value).toBe("[abc]");
+		expect(values).toEqual([]);
+	});
+
+	test("publishes a password unchanged and keeps it displayed on blur", () => {
+		// A `PasswordSchema` field must submit the typed password; masking is the `type="password"` input's job.
+		const values: (string | undefined)[] = [];
+		const input = _getInputProps(PASSWORD, v => void values.push(v), "hunter2");
+		input.onInput({ currentTarget: { value: "hunter22" } });
+		const currentTarget = { value: "hunter22" };
+		input.onBlur({ currentTarget });
+
+		expect(input.type).toBe("password");
+		expect(input.defaultValue).toBe("hunter2");
+		expect(values).toEqual(["hunter22"]);
+		expect(currentTarget.value).toBe("hunter22");
+	});
+
+	test("publishes a URL that still validates while displaying its friendly form", () => {
+		// `URLSchema.format()` strips the scheme for display; publishing that form would fail re-validation.
+		const values: (string | undefined)[] = [];
+		const input = _getInputProps(URL_SCHEMA, v => void values.push(v));
+		input.onInput({ currentTarget: { value: " https://example.com/path " } });
+		const currentTarget = { value: "https://example.com/path" };
+		input.onBlur({ currentTarget });
+
+		expect(values).toEqual(["https://example.com/path"]);
+		expect(URL_SCHEMA.validate(values[0])).toBe("https://example.com/path");
+		expect(currentTarget.value).toBe("example.com/path");
+	});
 });

package/ui/input/SchemaInput.tsx

@@ -192,14 +192,23 @@ export interface StringSchemaInputProps extends SchemaInputProps<StringSchema, u
 
 /**
  * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
+ * - Publishes the sanitized value through `onValue`; the schema's `format()` only shapes what the input displays (on first render and on blur).
  *
  * @returns A `TextInput` element bound to the schema.
  * @kind component
  * @example <StringSchemaInput name="email" schema={EMAIL} />
  * @see https://shelving.cc/ui/StringSchemaInput
  */
-export function StringSchemaInput({ schema, value, ...props }: StringSchemaInputProps): ReactElement {
-	return <TextInput {...schema} value={getString(value)} formatter={str => schema.format(schema.sanitize(str))} {...props} />;
+export function StringSchemaInput({ schema, value, onValue, ...props }: StringSchemaInputProps): ReactElement {
+	return (
+		<TextInput
+			{...schema}
+			value={getString(value)}
+			onValue={str => onValue(str === undefined ? undefined : schema.sanitize(str))}
+			formatter={str => schema.format(schema.sanitize(str))}
+			{...props}
+		/>
+	);
 }
 
 /**

package/ui/input/TextInput.d.ts

@@ -13,12 +13,12 @@ export interface TextInputProps extends ValueInputProps<string>, InputVariants {
     input?: StringInputType;
     min?: number | undefined;
     max?: number | undefined;
-    /** Optional formatter — when provided the value is reformatted on blur and when initially displayed. */
+    /** Optional formatter — when provided the value is reformatted on blur and when initially displayed (the value published through `onValue` is never formatted). */
     formatter?: TextFormatter | undefined;
 }
 /**
  * Text input bound to a `string` value, rendered as an `<input>` or a `<textarea>` when `rows > 1`.
- * - Applies an optional `formatter` on initial display and on blur.
+ * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
  * - Multiline mode auto-grows the textarea to fit its content.
  *
  * @returns A text `<input>` or `<textarea>` element.

package/ui/input/TextInput.js

@@ -5,7 +5,7 @@ import { getClass, getModuleClass } from "../util/css.js";
 import INPUT_CSS from "./Input.module.css";
 /**
  * Text input bound to a `string` value, rendered as an `<input>` or a `<textarea>` when `rows > 1`.
- * - Applies an optional `formatter` on initial display and on blur.
+ * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
  * - Multiline mode auto-grows the textarea to fit its content.
  *
  * @returns A text `<input>` or `<textarea>` element.
@@ -19,13 +19,13 @@ required = false, disabled = false, message = "", value, onValue, input = "text"
     };
     if (rows > 1) {
         const onChange = (e) => {
-            onValue?.(formatter(e.currentTarget.value));
+            onValue?.(e.currentTarget.value);
             _resize(e.currentTarget, rows);
         };
         return (_jsx("textarea", { ref: el => void (el && _resize(el, rows)), name: name, defaultValue: value !== undefined ? formatter(value) : "", minLength: Number.isFinite(min) ? min : 0, maxLength: Number.isFinite(max) ? max : undefined, rows: rows, required: required && min > 0, disabled: disabled, placeholder: placeholder || " ", className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "text"), getModuleClass(INPUT_CSS, "multiline"), className), onInput: onChange, onChange: onChange, onBlur: onBlur, title: message, "aria-invalid": !!message }));
     }
     const onChange = (e) => {
-        onValue?.(formatter(e.currentTarget.value));
+        onValue?.(e.currentTarget.value);
     };
     return (_jsx("input", { name: name, type: input, defaultValue: value !== undefined ? formatter(value) : "", minLength: Number.isFinite(min) ? min : 0, maxLength: Number.isFinite(max) ? max : undefined, required: required && min > 0, disabled: disabled, placeholder: placeholder || " ", className: getClass(getInputClass(variants), getModuleClass(INPUT_CSS, "text"), className), onInput: onChange, onChange: onChange, onBlur: onBlur, title: message, "aria-invalid": !!message }));
 }

package/ui/input/TextInput.tsx

@@ -18,13 +18,13 @@ export interface TextInputProps extends ValueInputProps<string>, InputVariants {
 	input?: StringInputType;
 	min?: number | undefined;
 	max?: number | undefined;
-	/** Optional formatter — when provided the value is reformatted on blur and when initially displayed. */
+	/** Optional formatter — when provided the value is reformatted on blur and when initially displayed (the value published through `onValue` is never formatted). */
 	formatter?: TextFormatter | undefined;
 }
 
 /**
  * Text input bound to a `string` value, rendered as an `<input>` or a `<textarea>` when `rows > 1`.
- * - Applies an optional `formatter` on initial display and on blur.
+ * - Applies an optional `formatter` on initial display and on blur — the raw typed value is published through `onValue`.
  * - Multiline mode auto-grows the textarea to fit its content.
  *
  * @returns A text `<input>` or `<textarea>` element.
@@ -54,7 +54,7 @@ export function TextInput({
 
 	if (rows > 1) {
 		const onChange = (e: SyntheticEvent<HTMLTextAreaElement>) => {
-			onValue?.(formatter(e.currentTarget.value));
+			onValue?.(e.currentTarget.value);
 			_resize(e.currentTarget, rows);
 		};
 
@@ -80,7 +80,7 @@ export function TextInput({
 	}
 
 	const onChange = (e: SyntheticEvent<HTMLInputElement>) => {
-		onValue?.(formatter(e.currentTarget.value));
+		onValue?.(e.currentTarget.value);
 	};
 
 	return (