shelving 1.284.0 → 1.285.1

package/package.json

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

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/README.md

@@ -10,7 +10,7 @@ The `ui` module exists so an app never hand-rolls the same form field, card, or
 
 A few conventions run through every component:
 
-- **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button strong>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in *one place* — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style`.
+- **Styling props are for one-off overrides.** Visual options are props on the component — enumerated props for the scales (`color="red"`, `size="large"`, `space="none"`, `width="narrow"`) and boolean props for on/off variants (`<Button plain>`, `<Title center>`, `<Flex wrap>`). Each maps to a class in a CSS Module. Reach for them when a component needs to look different in *one place* — the way the docs site tints its accents purple — not as the way to dress a whole app. You never pass `style`.
 - **`className` is the escape hatch.** Most components accept an optional `className`, merged *after* the classes the component computes for itself, so an app class reliably wins over the library's `@layer components` rules. It takes any `Classes` value — a string, an array, or a dictionary of `true` flags — and lands on the component's own root element. Use it for a composed one-off treatment that tokens and per-property hooks can't express (an animation, a bespoke gradient); tokens and hooks stay the primary theming surface. Formatting-only components (`<When>`, `<Prose>`, `<Scroll>`), the `*Layout` components, and `<Dialog>` deliberately don't take one — write a new layout, or style the content inside. See `ClassProps`.
 - **Composition.** Higher-level components — a `*Page`, a `*Card` — take their identity from library components like `<Card>`, `<Section>`, `<Button>`, and `<Tag>` rather than shipping their own styling.
 - **Sentence case.** Titles, headings, and button labels capitalise only the first word.

package/ui/button/Button.d.ts

@@ -10,12 +10,8 @@ import { type ClickableProps } from "./Clickable.js";
  * @see https://shelving.cc/ui/ButtonVariants
  */
 export interface ButtonVariants extends FlexVariants, StatusVariants, TypographyVariants {
-    /** This is the default button in a form and should be displayed stronger. */
-    strong?: boolean | undefined;
-    /** Add plain styling (background only appears on hover or focus). */
+    /** Add plain styling (no background or border until hover or focus). */
     plain?: boolean | undefined;
-    /** Add outline styling (has no background until hover or focus). */
-    outline?: boolean | undefined;
     /** Make the button appear smaller. */
     small?: boolean | undefined;
     /** Fill the available width instead of sizing to content (buttons are content-width by default). */
@@ -39,6 +35,7 @@ export interface ButtonProps extends ButtonVariants, ClickableProps, ClassProps
 /**
  * Render either a `<button>` or an `<a href="">` styled as a button, based on whether an `onClick` or `href` prop is provided.
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
+ * - Filled by default — use `color=` / `status=` for emphasis, or `plain` to de-emphasise.
  * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
  *
  * @kind component

package/ui/button/Button.js

@@ -18,6 +18,7 @@ export function getButtonClass(variants) {
 /**
  * Render either a `<button>` or an `<a href="">` styled as a button, based on whether an `onClick` or `href` prop is provided.
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
+ * - Filled by default — use `color=` / `status=` for emphasis, or `plain` to de-emphasise.
  * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
  *
  * @kind component

package/ui/button/Button.md

@@ -5,8 +5,9 @@ A clickable styled as a solid button. Renders an `<a href="">` when given `href`
 **Things to know:**
 
 - Content-width by default: it sizes to its label and never grows. Pass `full` to fill the available width (it then shrinks to share a row, down to the content floor).
-- `strong` marks the default action in a form — a filled background instead of an outline. `plain` and `outline` drop the background until hover/focus.
-- `color=` / `status=` move the tint anchor, so the background, border and label re-derive from the same ladder; `small` tightens the padding.
+- Every button is filled. Emphasis comes from colour: `color=` / `status=` move the tint anchor, so `color="primary"` marks the main action and a colourless button stays a neutral grey.
+- `plain` de-emphasises — no fill or border until hover/focus, for chrome-level actions like breadcrumbs and a dialog's close button. Set `--button-plain-border` to give plain buttons a resting edge when they need to hold their shape.
+- `small` tightens the padding.
 - `getButtonClass(variants)` returns the same `className` the component composes — use it to style a non-`<button>` element as a button when `Button` itself doesn't fit.
 - `className` attaches an app class to one button, merged after the computed classes so an app stylesheet wins — see `ClassProps`.
 
@@ -17,7 +18,7 @@ A clickable styled as a solid button. Renders an `<a href="">` when given `href`
 ```tsx
 import { Button } from "shelving/ui";
 
-<Button onClick={save} color="primary" strong>Save</Button>
+<Button onClick={save} color="primary">Save</Button>
 <Button href="/about">About</Button>
 <Button onClick={remove} status="error">Delete</Button>
 ```
@@ -30,7 +31,7 @@ import { Row } from "shelving/ui";
 
 <Row gap="small" right>
   <Button plain onClick={cancel}>Cancel</Button>
-  <Button strong onClick={submit}>Continue</Button>
+  <Button color="primary" onClick={submit}>Continue</Button>
 </Row>
 ```
 
@@ -40,7 +41,7 @@ import { Row } from "shelving/ui";
 import { Button } from "shelving/ui";
 
 // `.spongy-press` lives in the app's own stylesheet — use it for what the theme hooks below can't express.
-<Button className="spongy-press" strong onClick={claim}>Claim</Button>
+<Button className="spongy-press" onClick={claim}>Claim</Button>
 ```
 
 ### Reusing the button class
@@ -60,16 +61,20 @@ import { getButtonClass } from "shelving/ui";
 
 `--button-padding` and `--button-small-padding` set the `padding` shorthand, so a single value pads both axes equally and a two-value override pads block and inline separately (e.g. `var(--space-small) var(--space-normal)`).
 
-`--button-shadow`, `--button-hover-transform` and the `--button-active-*` pressed-state hooks are static and apply to every button, with one exception: `plain` and `outline` never paint a box shadow in any state — they have no fill until hover, so a raised edge under them reads broken. The hover and pressed transforms still apply to them, so all buttons move together. `--button-transition` already covers animating the press and release.
+`--button-shadow`, `--button-hover-transform` and the `--button-active-*` pressed-state hooks are static and apply to every button, with one exception: `plain` never paints a box shadow in any state — it has no fill until hover, so a raised edge under it reads broken. The hover and pressed transforms still apply to it, so all buttons move together. `--button-transition` already covers animating the press and release.
+
+`plain` carries its own hooks for where it differs: `--button-plain-text` recolours the label, `--button-plain-hover-background` / `--button-plain-hover-border` paint the hover and focus state, the `--button-plain-active-*` pair paints the pressed state (falling back to the plain hover hooks), and `--button-plain-border` sets the resting border — transparent by default, so a theme where plain buttons should keep a visible edge (an "outline" button) sets it once. The hover border falls back through `--button-hover-border`, so a theme that borders every hovered button also borders hovered plain ones.
+
+Backgrounds paint to the button's true edge: `background-origin` is set to `border-box`, so a gradient or image background in any state reaches through the transparent border instead of stopping 2px short at the padding box.
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--button-background` | Surface fill | `var(--tint-90)` |
-| `--button-hover-background` | Surface fill on hover / focus | `var(--tint-95)` |
-| `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid var(--tint-90)` |
+| `--button-background` | Surface fill | `var(--tint-50)` |
+| `--button-hover-background` | Surface fill on hover / focus | `var(--tint-55)` |
+| `--button-hover-border` | Border on hover / focus | `var(--button-stroke) solid transparent` |
 | `--button-hover-transform` | Transform on hover / focus | `none` |
-| `--button-text` | Label colour | `var(--tint-50)` |
-| `--button-border` | Border shorthand | `var(--button-stroke) solid var(--tint-80)` |
+| `--button-text` | Label colour | `var(--tint-100)` |
+| `--button-border` | Border shorthand | `var(--button-stroke) solid transparent` |
 | `--button-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
 | `--button-radius` | Corner radius | `var(--radius-xsmall)` (8px) |
 | `--button-padding` | Inner padding | `var(--space-small)` (12px) |
@@ -81,7 +86,7 @@ import { getButtonClass } from "shelving/ui";
 | `--button-weight` | Font weight | `var(--weight-strong)` (700) |
 | `--button-size` | Font size | `var(--size-normal)` |
 | `--button-leading` | Line height | `var(--leading)` |
-| `--button-shadow` | Box shadow (never on `plain` / `outline`) | `none` |
+| `--button-shadow` | Box shadow (never on `plain`) | `none` |
 | `--button-active-background` | Surface fill while pressed | `var(--button-hover-background)` |
 | `--button-active-border` | Border while pressed | `var(--button-hover-border)` |
 | `--button-active-shadow` | Box shadow while pressed | `var(--button-shadow)` |
@@ -89,11 +94,14 @@ import { getButtonClass } from "shelving/ui";
 | `--button-transition` | Transition | `all var(--duration-fast)` (150ms) |
 | `--button-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
 | `--button-disabled-opacity` | Opacity when disabled | `0.5` |
-| `--button-strong-background` | Fill when `strong` | `var(--tint-50)` |
-| `--button-strong-text` | Label colour when `strong` | `var(--tint-100)` |
-| `--button-strong-hover-background` | Hover fill when `strong` | `var(--tint-55)` |
+| `--button-plain-text` | Label colour when `plain` | `var(--tint-50)` |
+| `--button-plain-border` | Resting border when `plain` | `var(--button-stroke) solid transparent` |
+| `--button-plain-hover-background` | Fill on hover / focus when `plain` | `var(--tint-95)` |
+| `--button-plain-hover-border` | Border on hover / focus when `plain` | `var(--button-hover-border)` (transparent) |
+| `--button-plain-active-background` | Fill while pressed when `plain` | `var(--button-plain-hover-background)` |
+| `--button-plain-active-border` | Border while pressed when `plain` | `var(--button-plain-hover-border)` |
 
-**Global tokens it reads:** the tint ladder `--tint-50` / `--tint-80` / `--tint-90` / `--tint-95` / `--tint-100` / `--tint-55`, plus `--space-small`, `--space-xxsmall`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--font-body`, `--weight-strong`, `--size-normal`, `--leading`, and `--duration-fast`.
+**Global tokens it reads:** the tint ladder `--tint-50` / `--tint-55` / `--tint-95` / `--tint-100`, plus `--space-small`, `--space-xxsmall`, `--radius-xsmall`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, `--font-body`, `--weight-strong`, `--size-normal`, `--leading`, and `--duration-fast`.
 
 ```css
 /* Theme: pill-shaped buttons, with roomier inline padding. */
@@ -104,11 +112,19 @@ import { getButtonClass } from "shelving/ui";
 ```
 
 ```css
-/* Theme: buttons are raised and press down flat — `plain` and `outline` press down too but never cast a shadow. */
+/* Theme: plain buttons keep an edge, so a quiet button holds its shape next to a filled one. */
+:root {
+  --button-plain-border: var(--stroke-normal) solid var(--tint-80);
+  --button-plain-hover-border: var(--stroke-normal) solid var(--tint-80);
+}
+```
+
+```css
+/* Theme: buttons are raised and press down flat — `plain` presses down too but never casts a shadow. */
 :root {
-  --button-shadow: 0 0.25rem 0 var(--tint-80);
+  --button-shadow: 0 0.25rem 0 var(--tint-30);
   --button-active-transform: translateY(0.2rem);
-  --button-active-shadow: 0 0.05rem 0 var(--tint-80);
+  --button-active-shadow: 0 0.05rem 0 var(--tint-30);
   --button-transition: all var(--duration-fast) cubic-bezier(0.34, 1.56, 0.64, 1);
 }
 ```

package/ui/button/Button.module.css

@@ -16,7 +16,7 @@
 		min-inline-size: fit-content;
 		max-inline-size: 100%;
 		border-radius: var(--button-radius, var(--radius-xsmall));
-		border: var(--button-border, var(--button-stroke, var(--stroke-normal)) solid var(--tint-80));
+		border: var(--button-border, var(--button-stroke, var(--stroke-normal)) solid transparent);
 		padding: var(--button-padding, var(--space-small));
 		margin-inline: 0;
 		margin-block: var(--button-space, var(--space-small));
@@ -29,8 +29,8 @@
 		align-items: center;
 
 		/* Style. */
-		background: var(--button-background, var(--tint-90));
-		color: var(--button-text, var(--tint-50));
+		background: var(--button-background, var(--tint-50));
+		color: var(--button-text, var(--tint-100));
 		box-shadow: var(--button-shadow, none);
 		transition: var(--button-transition, all var(--duration-fast));
 		cursor: pointer;
@@ -54,15 +54,15 @@
 		&:enabled:hover,
 		&:any-link:hover,
 		&:focus:not(:focus-visible) {
-			border: var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid var(--tint-90));
-			background: var(--button-hover-background, var(--tint-95));
+			border: var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid transparent);
+			background: var(--button-hover-background, var(--tint-55));
 			transform: var(--button-hover-transform, none);
 		}
 
 		&:enabled:active,
 		&:any-link:active {
-			border: var(--button-active-border, var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid var(--tint-90)));
-			background: var(--button-active-background, var(--button-hover-background, var(--tint-95)));
+			border: var(--button-active-border, var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid transparent));
+			background: var(--button-active-background, var(--button-hover-background, var(--tint-55)));
 			transform: var(--button-active-transform, var(--button-hover-transform, none));
 			box-shadow: var(--button-active-shadow, var(--button-shadow, none));
 		}
@@ -78,14 +78,24 @@
 			inline-size: 100%;
 		}
 
-		&.strong {
-			background: var(--button-strong-background, var(--tint-50));
-			color: var(--button-strong-text, var(--tint-100));
+		&.plain {
+			color: var(--button-plain-text, var(--tint-50));
 
+			/* Plain includes plain `:focus` so a keyboard-focused button paints its fill and stays legible. */
 			&:enabled:hover,
 			&:any-link:hover,
-			&:focus:not(:focus-visible) {
-				background: var(--button-strong-hover-background, var(--tint-55));
+			&:focus {
+				border: var(--button-plain-hover-border, var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid transparent));
+				background: var(--button-plain-hover-background, var(--tint-95));
+			}
+
+			&:enabled:active,
+			&:any-link:active {
+				border: var(
+					--button-plain-active-border,
+					var(--button-plain-hover-border, var(--button-hover-border, var(--button-stroke, var(--stroke-normal)) solid transparent))
+				);
+				background: var(--button-plain-active-background, var(--button-plain-hover-background, var(--tint-95)));
 			}
 		}
 	}
@@ -93,6 +103,9 @@
 
 @layer overrides {
 	.button {
+		/* The border is transparent by default, so background images/gradients must size to the border box to reach the button's edge. Lives in the overrides layer because every state's `background` shorthand resets the origin to `padding-box`. */
+		background-origin: border-box;
+
 		&:first-child {
 			margin-block-start: 0;
 		}
@@ -107,23 +120,11 @@
 		}
 
 		/* Variants */
-		&.strong {
-			border-color: transparent;
-		}
-
 		&.plain {
 			box-shadow: none;
 
-			&:not(:enabled:hover, :any-link:hover, :focus) {
-				border-color: transparent;
-				background: transparent;
-			}
-		}
-
-		&.outline {
-			box-shadow: none;
-
-			&:not(:enabled:hover, :any-link:hover, :focus) {
+			&:not(:enabled:hover, :any-link:hover, :active, :focus) {
+				border: var(--button-plain-border, var(--button-stroke, var(--stroke-normal)) solid transparent);
 				background: transparent;
 			}
 		}

package/ui/button/Button.tsx

@@ -13,12 +13,8 @@ import { Clickable, type ClickableProps } from "./Clickable.js";
  * @see https://shelving.cc/ui/ButtonVariants
  */
 export interface ButtonVariants extends FlexVariants, StatusVariants, TypographyVariants {
-	/** This is the default button in a form and should be displayed stronger. */
-	strong?: boolean | undefined;
-	/** Add plain styling (background only appears on hover or focus). */
+	/** Add plain styling (no background or border until hover or focus). */
 	plain?: boolean | undefined;
-	/** Add outline styling (has no background until hover or focus). */
-	outline?: boolean | undefined;
 	/** Make the button appear smaller. */
 	small?: boolean | undefined;
 	/** Fill the available width instead of sizing to content (buttons are content-width by default). */
@@ -51,6 +47,7 @@ export interface ButtonProps extends ButtonVariants, ClickableProps, ClassProps
 /**
  * Render either a `<button>` or an `<a href="">` styled as a button, based on whether an `onClick` or `href` prop is provided.
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
+ * - Filled by default — use `color=` / `status=` for emphasis, or `plain` to de-emphasise.
  * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
  *
  * @kind component

package/ui/button/SubmitButton.d.ts

@@ -5,7 +5,6 @@ import { type ButtonVariants } from "./Button.js";
  * Component props for `<SubmitButton>`, a form submit button.
  *
  * @property children - The content of the button. Defaults to `"Save"` with a right-pointing arrow icon.
- * @property strong - Whether the button should have strong styling. Defaults to `true`
  * @property color - The color variant of the button. Defaults to `"primary"`
  *
  * @see https://shelving.cc/ui/SubmitButtonProps
@@ -14,10 +13,10 @@ export interface SubmitButtonProps extends ButtonVariants, OptionalChildProps, C
 }
 /**
  * Submit button for a form that disables itself and shows a spinner while the form is busy.
- * - Defaults to strong, full-width, primary styling and a "Save" label.
+ * - Defaults to full-width, primary styling and a "Save" label.
  *
  * @returns A `<button type="submit">` element bound to the current form.
  * @example <SubmitButton>Save changes</SubmitButton>
  * @see https://shelving.cc/ui/SubmitButton
  */
-export declare function SubmitButton({ children, strong, color, full, className, ...props }: SubmitButtonProps): ReactElement;
+export declare function SubmitButton({ children, color, full, className, ...props }: SubmitButtonProps): ReactElement;

package/ui/button/SubmitButton.js

@@ -8,14 +8,14 @@ import { getButtonClass } from "./Button.js";
 const _SUBMIT_CHILDREN = (_jsxs(_Fragment, { children: ["Save", _jsx(ArrowRightIcon, {})] }));
 /**
  * Submit button for a form that disables itself and shows a spinner while the form is busy.
- * - Defaults to strong, full-width, primary styling and a "Save" label.
+ * - Defaults to full-width, primary styling and a "Save" label.
  *
  * @returns A `<button type="submit">` element bound to the current form.
  * @example <SubmitButton>Save changes</SubmitButton>
  * @see https://shelving.cc/ui/SubmitButton
  */
-export function SubmitButton({ children = _SUBMIT_CHILDREN, strong = true, color = "primary", full = true, className, ...props }) {
+export function SubmitButton({ children = _SUBMIT_CHILDREN, color = "primary", full = true, className, ...props }) {
     const form = requireForm();
     const busy = useStore(form.busy).value;
-    return (_jsx("button", { type: "submit", disabled: busy, className: getClass(getButtonClass({ strong, color, full, ...props }), className), children: busy ? LOADING : children }));
+    return (_jsx("button", { type: "submit", disabled: busy, className: getClass(getButtonClass({ color, full, ...props }), className), children: busy ? LOADING : children }));
 }

package/ui/button/SubmitButton.tsx

@@ -11,7 +11,6 @@ import { type ButtonVariants, getButtonClass } from "./Button.js";
  * Component props for `<SubmitButton>`, a form submit button.
  *
  * @property children - The content of the button. Defaults to `"Save"` with a right-pointing arrow icon.
- * @property strong - Whether the button should have strong styling. Defaults to `true`
  * @property color - The color variant of the button. Defaults to `"primary"`
  *
  * @see https://shelving.cc/ui/SubmitButtonProps
@@ -27,7 +26,7 @@ const _SUBMIT_CHILDREN = (
 
 /**
  * Submit button for a form that disables itself and shows a spinner while the form is busy.
- * - Defaults to strong, full-width, primary styling and a "Save" label.
+ * - Defaults to full-width, primary styling and a "Save" label.
  *
  * @returns A `<button type="submit">` element bound to the current form.
  * @example <SubmitButton>Save changes</SubmitButton>
@@ -35,7 +34,6 @@ const _SUBMIT_CHILDREN = (
  */
 export function SubmitButton({
 	children = _SUBMIT_CHILDREN,
-	strong = true,
 	color = "primary",
 	full = true,
 	className,
@@ -44,7 +42,7 @@ export function SubmitButton({
 	const form = requireForm();
 	const busy = useStore(form.busy).value;
 	return (
-		<button type="submit" disabled={busy} className={getClass(getButtonClass({ strong, color, full, ...props }), className)}>
+		<button type="submit" disabled={busy} className={getClass(getButtonClass({ color, full, ...props }), className)}>
 			{busy ? LOADING : children}
 		</button>
 	);

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 (

package/ui/style/TINT_CLASS.md

@@ -29,9 +29,9 @@ Components paint from the ladder by convention:
 | Step | Used for |
 |---|---|
 | `--tint-00` | Body text, headings — maximum contrast |
-| `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `strong` button backgrounds |
+| `--tint-50` | The hue itself — accents, labels, `Tag` backgrounds, `<Button>` backgrounds |
 | `--tint-80` | Borders |
-| `--tint-90` | Surfaces — `<Card>`, `Preformatted`, `<Button>` backgrounds |
+| `--tint-90` | Surfaces — `<Card>`, `Preformatted` backgrounds |
 | `--tint-95` | Hover state of those surfaces |
 | `--tint-100` | The page background; text on `--tint-50` backgrounds |
 

package/ui/util/ClassProps.md

@@ -19,7 +19,7 @@ The shared `className` prop most components accept — an app class merged *afte
 import { Button } from "shelving/ui";
 
 // `.spongy-press` lives in the app's own global stylesheet.
-<Button className="spongy-press" strong onClick={claim}>
+<Button className="spongy-press" onClick={claim}>
 	Claim
 </Button>;
 ```