shelving 1.284.0 → 1.285.0

package/package.json

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

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/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>;
 ```