@nqmcreative/ui 0.2.2 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @nqmcreative/ui
 
 Svelte 5 (runes) + Tailwind CSS v4 component library. One package, **three
-styles**, 65 components each — the same props, the same behaviour, a different
+styles**, 63 components each — the same props, the same behaviour, a different
 look. Eight tones, light and dark, no runtime dependencies.
 
 | style    | import                   | character                                                                                                                      |
@@ -131,9 +131,9 @@ Under SSR use `<LocaleProvider>` instead, so the locale is scoped to a request.
 
 ```
 src/lib/core/            behaviour, a11y, types — no markup, no classes
-src/lib/styles/matte/    65 components
-src/lib/styles/paper/    65 components
-src/lib/styles/sprout/   65 components
+src/lib/styles/matte/    63 components
+src/lib/styles/paper/    63 components
+src/lib/styles/sprout/   63 components
 scripts/catalogue.mjs    the list every style must implement
 ```
 
@@ -150,17 +150,17 @@ same.
 
 ## Components
 
-| group        | components                                                                                                                                                                                                                                                 |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Actions      | `Button`, `Link`                                                                                                                                                                                                                                           |
-| Forms        | `Input`, `Textarea`, `Select`, `Combobox`, `MultiSelect`, `DatePicker`, `Calendar`, `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `SegmentedControl`, `Switch`, `Slider`, `NumberInput`, `PasswordInput`, `InputGroup`, `Dropzone`, `Field`, `Label` |
-| Data display | `Badge`, `Avatar`, `AvatarGroup`, `Card`, `Stat`, `Table`, `Kbd`                                                                                                                                                                                           |
-| Feedback     | `Alert`, `Toaster` + `toast`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`                                                                                                                                                                              |
-| Layout & nav | `Divider`, `Tabs`, `Accordion`, `AccordionItem`, `Breadcrumb`, `Pagination`, `Steps`                                                                                                                                                                       |
-| App shell    | `Navbar`, `Sidebar`, `Footer`                                                                                                                                                                                                                              |
-| Overlay      | `Modal`, `ConfirmDialog`, `Drawer`, `Dropdown` + `MenuItem` + `MenuSeparator`, `ContextMenu`, `CommandPalette`, `Popover`, `Tooltip`                                                                                                                       |
-| Marketing    | `HeroSection`, `FeatureGrid`, `FeatureCard`, `PricingCard`, `Testimonial`, `LogoCloud`, `CTASection`, `StatsBand`                                                                                                                                          |
-| System       | `ThemeToggle`, `LocaleProvider`                                                                                                                                                                                                                            |
+| group        | components                                                                                                                                                                                                                 |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions      | `Button`, `Link`                                                                                                                                                                                                           |
+| Forms        | `Input`, `Textarea`, `Select`, `Combobox`, `MultiSelect`, `DatePicker`, `Calendar`, `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `SegmentedControl`, `Switch`, `Slider`, `InputGroup`, `Dropzone`, `Field`, `Label` |
+| Data display | `Badge`, `Avatar`, `AvatarGroup`, `Card`, `Stat`, `Table`, `Kbd`                                                                                                                                                           |
+| Feedback     | `Alert`, `Toaster` + `toast`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`                                                                                                                                              |
+| Layout & nav | `Divider`, `Tabs`, `Accordion`, `AccordionItem`, `Breadcrumb`, `Pagination`, `Steps`                                                                                                                                       |
+| App shell    | `Navbar`, `Sidebar`, `Footer`                                                                                                                                                                                              |
+| Overlay      | `Modal`, `ConfirmDialog`, `Drawer`, `Dropdown` + `MenuItem` + `MenuSeparator`, `ContextMenu`, `CommandPalette`, `Popover`, `Tooltip`                                                                                       |
+| Marketing    | `HeroSection`, `FeatureGrid`, `FeatureCard`, `PricingCard`, `Testimonial`, `LogoCloud`, `CTASection`, `StatsBand`                                                                                                          |
+| System       | `ThemeToggle`, `LocaleProvider`                                                                                                                                                                                            |
 
 Overlays are built on the native top layer and three in-house actions
 (`portal`, `focusTrap`, `anchored`) rather than a positioning dependency.

package/cli/index.mjs

@@ -3,16 +3,19 @@
  * @nqmcreative/ui CLI
  *
  *   nqm-ui init            wire the design system into this project
+ *   nqm-ui update          rewrite that wiring after upgrading the package
  *   nqm-ui add <name...>   print (or insert) the import for a component
  *   nqm-ui list [category] every component and its subpath
  *   nqm-ui info <name>     what one component pulls in
  *
  * Node built-ins only, so `bunx @nqmcreative/ui init` needs nothing installed.
- * Every write is idempotent: running init twice changes nothing the second
- * time.
+ * Every write is idempotent: the lines this CLI owns are rewritten from
+ * scratch on every run, so running it twice changes nothing the second time —
+ * and running it after an upgrade picks up whatever those lines became.
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -76,27 +79,56 @@ function findComponent(list, query) {
  * The style to work in. There is no default on purpose: a component belongs to
  * a style, and picking one by accident is the mistake this package exists to
  * prevent. Asking once beats shipping the wrong look.
+ *
+ * `--style` answers it up front. Without it a terminal gets a numbered prompt;
+ * a pipe or a CI job gets the list and a non-zero exit, because there is
+ * nobody there to answer.
  */
-function pickStyle(styles) {
+async function pickStyle(styles) {
 	const index = argv.indexOf('--style');
 	const wanted = index !== -1 ? argv[index + 1] : null;
 
-	if (!wanted) {
-		log();
-		log('  which style?');
-		log();
-		for (const style of styles) {
-			log(`    ${c.cyan(style.name.padEnd(8))} ${c.dim(style.description)}`);
-		}
-		log();
-		log(`  ${c.dim(`e.g. ${command} --style ${styles[0].name}`)}`);
+	if (wanted) {
+		const named = styles.find((s) => s.name === wanted);
+		if (!named) fail(`unknown style "${wanted}" — try ${styles.map((s) => s.name).join(' or ')}`);
+		return named;
+	}
+
+	log();
+	log('  which style?');
+	log();
+	styles.forEach((style, i) => {
+		log(`    ${c.cyan(`${i + 1})`)} ${c.bold(style.name.padEnd(8))} ${c.dim(style.description)}`);
+	});
+	log();
+
+	if (!process.stdin.isTTY) {
+		log(`  ${c.dim(`not a terminal — pass it: ${command} --style ${styles[0].name}`)}`);
 		log();
 		process.exit(1);
 	}
 
-	const style = styles.find((s) => s.name === wanted);
-	if (!style) fail(`unknown style "${wanted}" — try ${styles.map((s) => s.name).join(' or ')}`);
-	return style;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const answer = (await rl.question(`  1-${styles.length}, or a name [1]: `)).trim();
+			if (!answer) return styles[0];
+
+			const number = Number(answer);
+			if (Number.isInteger(number) && number >= 1 && number <= styles.length) {
+				return styles[number - 1];
+			}
+
+			const named = styles.find((s) => s.name === answer.toLowerCase());
+			if (named) return named;
+
+			warn(`no style called "${answer}"`);
+		}
+	} finally {
+		rl.close();
+	}
+
+	fail(`try ${command} --style ${styles[0].name}`);
 }
 
 /* ------------------------------------------------------------ file edits -- */
@@ -151,7 +183,7 @@ function sourcePath(cssRel) {
 
 async function init() {
 	const { styles } = await registry();
-	const style = pickStyle(styles);
+	const style = await pickStyle(styles);
 	const project = await detectProject();
 
 	log();
@@ -185,28 +217,31 @@ async function init() {
 
 	const css = await readOr(project.css);
 
-	// Matched against *this* style's theme, not any of them. A file left over
-	// from an older layout — or wired to a different style — has to be reported,
-	// not skipped as already done.
-	if (css.includes(`@nqmcreative/ui/${style.name}/theme.css`)) {
-		skip(`${project.cssRel} already imports the theme`);
+	// The block above belongs to this package, so it is rewritten on every run
+	// rather than left alone once it is there. That is what makes an upgrade
+	// land: when a release changes which files a style imports, or where
+	// `@source` has to point, the old lines would otherwise sit here and the
+	// new components would come up unstyled.
+	//
+	// Only those lines. Everything below is the project's own CSS and is
+	// carried over untouched — including an `@import` of another package, which
+	// is why the match is anchored to this one.
+	const stale =
+		/^@import ['"]@nqmcreative\/ui\/[^'"]+\.css['"];$|^@source ['"][^'"]*@nqmcreative\/ui[^'"]*['"];$/;
+
+	const kept = css
+		.split('\n')
+		.filter((line) => !stale.test(line.trim()))
+		.join('\n')
+		.replace(/@import ['"]tailwindcss['"];\n?/, '')
+		.replace(/\/\* Tailwind v4 skips node_modules[\s\S]*?\*\/\n?/, '')
+		.replace(/\n{3,}/g, '\n\n')
+		.trim();
+
+	const body = kept ? `${lines.join('\n')}\n\n${kept}\n` : `${lines.join('\n')}\n`;
+	if (body === css) {
+		skip(`${project.cssRel} already up to date`);
 	} else {
-		// Drop whatever this package left here before — an older layout's
-		// `@nqmcreative/ui/theme.css`, another style's, and the `@source` that
-		// went with them. Keeping those would either fight the new tokens or fail
-		// to resolve, so a rewrite is cleaner than an append.
-		const stale =
-			/^@import ['"]@nqmcreative\/ui\/[^'"]+\.css['"];$|^@source ['"][^'"]*@nqmcreative\/ui[^'"]*['"];$/;
-
-		const kept = css
-			.split('\n')
-			.filter((line) => !stale.test(line.trim()))
-			.join('\n')
-			.replace(/@import ['"]tailwindcss['"];\n?/, '')
-			.replace(/\n{3,}/g, '\n\n')
-			.trim();
-
-		const body = kept ? `${lines.join('\n')}\n\n${kept}\n` : `${lines.join('\n')}\n`;
 		await write(project.css, body, project.cssRel);
 	}
 
@@ -321,7 +356,7 @@ async function init() {
 
 async function add() {
 	const { components, styles } = await registry();
-	const style = pickStyle(styles);
+	const style = await pickStyle(styles);
 	const names = args.slice(1);
 	if (names.length === 0) fail('which component? e.g. `nqm-ui add button dialog`');
 
@@ -435,22 +470,26 @@ function help() {
 	log(`
   ${c.bold('@nqmcreative/ui')}
 
-    ${c.cyan('init --style <s>')}      wire one style into this project
+    ${c.cyan('init')}                  wire one style into this project
+    ${c.cyan('update')}                rewrite that wiring after upgrading the package
     ${c.cyan('add <name...>')}         print the import for a component
-      ${c.dim('--style <s>')}         which style to import from (required)
       ${c.dim('--to <file>')}         …and insert it into that file instead
     ${c.cyan('list [category]')}       every component in the catalogue
     ${c.cyan('info <name>')}           what one component pulls in, in every style
 
+    ${c.dim('--style <s>')}           skip the picker: matte, paper or sprout
     ${c.dim('--dry-run')}             show the writes without making them
 
-  ${c.dim('Every style implements every component. Run init once per project.')}
+  ${c.dim('Every style implements every component. Run init once per project,')}
+  ${c.dim('then update after each upgrade — it overwrites the lines it owns.')}
 `);
 }
 
 /* ------------------------------------------------------------------ main -- */
 
-const commands = { init, add, list, info };
+// `update` is `init` under the name people reach for after an upgrade: both
+// rewrite the lines this CLI owns and leave the rest of the file alone.
+const commands = { init, update: init, add, list, info };
 if (!command || flags.has('--help') || command === 'help') {
 	help();
 } else if (commands[command]) {

package/dist/core/index.d.ts

@@ -15,7 +15,7 @@ export type { Placement, AnchorOptions } from './actions/anchor.js';
 export { clickOutside, focusTrap, focusable, navigateList, portal } from './actions/dismissable.js';
 export type { ClickOutsideOptions, FocusTrapOptions } from './actions/dismissable.js';
 export { syncDialog, isBackdropClick } from './dialog.svelte.js';
-export { popupTrigger, describeTrigger, menuItems, HOVER_GRACE } from './trigger.js';
+export { popupTrigger, describeTrigger, menuItems, isTypingTarget, HOVER_GRACE } from './trigger.js';
 export type { PopupTriggerOptions } from './trigger.js';
 export { ListCursor, groupItems, matchQuery, revealIndex } from './list.svelte.js';
 export type { ListItem } from './list.svelte.js';

package/dist/core/index.js

@@ -15,7 +15,7 @@ export { anchored } from './actions/anchor.js';
 export { clickOutside, focusTrap, focusable, navigateList, portal } from './actions/dismissable.js';
 /* --- overlays --- */
 export { syncDialog, isBackdropClick } from './dialog.svelte.js';
-export { popupTrigger, describeTrigger, menuItems, HOVER_GRACE } from './trigger.js';
+export { popupTrigger, describeTrigger, menuItems, isTypingTarget, HOVER_GRACE } from './trigger.js';
 /* --- lists --- */
 export { ListCursor, groupItems, matchQuery, revealIndex } from './list.svelte.js';
 /* --- data --- */

package/dist/core/toast.svelte.d.ts

@@ -8,6 +8,7 @@
  *   const id = toast.loading('Rendering…');
  *   toast.dismiss(id);
  */
+import type { Snippet } from 'svelte';
 import type { Tone } from './tones.js';
 export interface ToastAction {
     label: string;
@@ -19,6 +20,8 @@ export interface ToastOptions {
     /** Milliseconds on screen. `0` keeps it until dismissed. Default 5000. */
     duration?: number;
     action?: ToastAction;
+    /** Replaces the tone's own glyph. */
+    icon?: Snippet;
     /** Swaps the glyph for a spinner and defaults `duration` to 0. */
     loading?: boolean;
 }

package/dist/core/trigger.d.ts

@@ -33,3 +33,9 @@ export declare function popupTrigger(node: HTMLElement, options: PopupTriggerOpt
 export declare function describeTrigger(wrapper: HTMLElement | null, kind: 'menu' | 'dialog' | 'listbox', open: boolean): void;
 /** The menu items a roving-focus menu should walk, in DOM order. */
 export declare function menuItems(menu: HTMLElement | null): HTMLElement[];
+/**
+ * Whether a keystroke landed in something the reader is typing into. A
+ * bare-key shortcut — `/` for search — has to stand down for those, or it
+ * eats the character instead of opening anything.
+ */
+export declare function isTypingTarget(target: EventTarget | null): boolean;

package/dist/core/trigger.js

@@ -75,3 +75,16 @@ export function describeTrigger(wrapper, kind, open) {
 export function menuItems(menu) {
     return menu ? [...menu.querySelectorAll('[role="menuitem"]:not([disabled])')] : [];
 }
+/**
+ * Whether a keystroke landed in something the reader is typing into. A
+ * bare-key shortcut — `/` for search — has to stand down for those, or it
+ * eats the character instead of opening anything.
+ */
+export function isTypingTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    return (target.isContentEditable ||
+        target.tagName === 'INPUT' ||
+        target.tagName === 'TEXTAREA' ||
+        target.tagName === 'SELECT');
+}

package/dist/styles/matte/AccordionItem.svelte

@@ -2,6 +2,7 @@
 	import type { Snippet } from 'svelte';
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { toneText, type Tone } from '../../core/tones.js';
+	import { iconMd } from './icon.js';
 
 	interface Props extends HTMLAttributes<HTMLDetailsElement> {
 		title: string;
@@ -9,6 +10,8 @@
 		tone?: Tone;
 		/** Short text on the right of the summary row. */
 		meta?: string;
+		/** Leading icon on the summary row. */
+		icon?: Snippet;
 		children: Snippet;
 	}
 
@@ -17,6 +20,7 @@
 		open = $bindable(false),
 		tone = 'brand',
 		meta,
+		icon,
 		class: className = '',
 		children,
 		...rest
@@ -27,6 +31,7 @@
 	<summary
 		class="flex cursor-pointer list-none items-center gap-4 py-4 font-sans text-[15px] text-text transition-colors duration-150 ease-brand-out select-none hover:text-text-secondary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current [&::-webkit-details-marker]:hidden"
 	>
+		{#if icon}<span class={iconMd}>{@render icon()}</span>{/if}
 		<span class="flex-1 font-medium">{title}</span>
 		{#if meta}<span class="font-mono text-xs text-text-muted">{meta}</span>{/if}
 		<svg

package/dist/styles/matte/AccordionItem.svelte.d.ts

@@ -7,6 +7,8 @@ interface Props extends HTMLAttributes<HTMLDetailsElement> {
     tone?: Tone;
     /** Short text on the right of the summary row. */
     meta?: string;
+    /** Leading icon on the summary row. */
+    icon?: Snippet;
     children: Snippet;
 }
 declare const AccordionItem: import("svelte").Component<Props, {}, "open">;

package/dist/styles/matte/Avatar.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import type { Snippet } from 'svelte';
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { toneSoft, type Tone } from '../../core/tones.js';
 
@@ -13,6 +14,8 @@
 		tone?: Tone;
 		/** Square instead of the default circle. */
 		squared?: boolean;
+		/** Drawn instead of the initials when there is no `src` — a user mark. */
+		fallback?: Snippet;
 	}
 
 	let {
@@ -22,6 +25,7 @@
 		size = 'md',
 		tone = 'brand',
 		squared = false,
+		fallback,
 		class: className = '',
 		...rest
 	}: Props = $props();
@@ -34,6 +38,15 @@
 		xl: 'size-16 text-lg'
 	};
 
+	// The mark tracks the initials: about half the circle, whatever the size.
+	const glyphs: Record<AvatarSize, string> = {
+		xs: 'grid place-items-center *:size-3',
+		sm: 'grid place-items-center *:size-4',
+		md: 'grid place-items-center *:size-5',
+		lg: 'grid place-items-center *:size-6',
+		xl: 'grid place-items-center *:size-8'
+	};
+
 	const initials = $derived(
 		name
 			.trim()
@@ -52,6 +65,8 @@
 >
 	{#if src}
 		<img {src} alt={alt ?? name} class="size-full object-cover" />
+	{:else if fallback}
+		<span class={glyphs[size]}>{@render fallback()}</span>
 	{:else}
 		{initials}
 	{/if}

package/dist/styles/matte/Avatar.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import { type Tone } from '../../core/tones.js';
 export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
@@ -10,6 +11,8 @@ interface Props extends HTMLAttributes<HTMLSpanElement> {
     tone?: Tone;
     /** Square instead of the default circle. */
     squared?: boolean;
+    /** Drawn instead of the initials when there is no `src` — a user mark. */
+    fallback?: Snippet;
 }
 declare const Avatar: import("svelte").Component<Props, {}, "">;
 type Avatar = ReturnType<typeof Avatar>;

package/dist/styles/matte/Badge.svelte

@@ -9,6 +9,7 @@
 		toneText,
 		type Tone
 	} from '../../core/tones.js';
+	import { iconSm } from './icon.js';
 
 	export type BadgeVariant = 'soft' | 'solid' | 'outline';
 	export type BadgeSize = 'sm' | 'md';
@@ -19,6 +20,8 @@
 		size?: BadgeSize;
 		/** Small filled circle before the label. */
 		dot?: boolean;
+		/** Leading icon, 14px — sits where the dot would. */
+		icon?: Snippet;
 		children: Snippet;
 	}
 
@@ -27,6 +30,7 @@
 		variant = 'soft',
 		size = 'md',
 		dot = false,
+		icon,
 		class: className = '',
 		children,
 		...rest
@@ -54,5 +58,6 @@
 			class="size-1.5 shrink-0 rounded-full {variant === 'solid' ? 'bg-current' : toneFill[tone]}"
 		></span>
 	{/if}
+	{#if icon}<span class={iconSm}>{@render icon()}</span>{/if}
 	{@render children()}
 </span>

package/dist/styles/matte/Badge.svelte.d.ts

@@ -9,6 +9,8 @@ interface Props extends HTMLAttributes<HTMLSpanElement> {
     size?: BadgeSize;
     /** Small filled circle before the label. */
     dot?: boolean;
+    /** Leading icon, 14px — sits where the dot would. */
+    icon?: Snippet;
     children: Snippet;
 }
 declare const Badge: import("svelte").Component<Props, {}, "">;

package/dist/styles/matte/Breadcrumb.svelte

@@ -1,11 +1,15 @@
 <script lang="ts">
+	import type { Snippet } from 'svelte';
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { toneHoverText, type Tone } from '../../core/tones.js';
 	import { useLocale } from '../../core/locale.svelte.js';
+	import { iconMd } from './icon.js';
 
 	export interface BreadcrumbItem {
 		label: string;
 		href?: string;
+		/** Leading icon — a home mark on the first crumb, say. */
+		icon?: Snippet;
 	}
 
 	interface Props extends HTMLAttributes<HTMLElement> {
@@ -29,15 +33,18 @@
 				{#if item.href && i < items.length - 1}
 					<a
 						href={item.href}
-						class="text-text-secondary transition-colors duration-150 ease-brand-out {toneHoverText[
+						class="inline-flex items-center gap-1.5 text-text-secondary transition-colors duration-150 ease-brand-out {toneHoverText[
 							tone
 						]}"
 					>
-						{item.label}
+						{#if item.icon}<span class={iconMd}>{@render item.icon()}</span>{/if}{item.label}
 					</a>
 				{:else}
-					<span class="text-text" aria-current={i === items.length - 1 ? 'page' : undefined}>
-						{item.label}
+					<span
+						class="inline-flex items-center gap-1.5 text-text"
+						aria-current={i === items.length - 1 ? 'page' : undefined}
+					>
+						{#if item.icon}<span class={iconMd}>{@render item.icon()}</span>{/if}{item.label}
 					</span>
 				{/if}
 			</li>

package/dist/styles/matte/Breadcrumb.svelte.d.ts

@@ -1,8 +1,11 @@
+import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import { type Tone } from '../../core/tones.js';
 export interface BreadcrumbItem {
     label: string;
     href?: string;
+    /** Leading icon — a home mark on the first crumb, say. */
+    icon?: Snippet;
 }
 interface Props extends HTMLAttributes<HTMLElement> {
     items: BreadcrumbItem[];

package/dist/styles/matte/Button.svelte

@@ -2,6 +2,7 @@
 	import type { Snippet } from 'svelte';
 	import type { HTMLButtonAttributes } from 'svelte/elements';
 	import Spinner from './Spinner.svelte';
+	import { iconMd, iconSm } from './icon.js';
 	import {
 		focusRing,
 		toneBorder,
@@ -17,7 +18,7 @@
 	export type ButtonVariant = 'solid' | 'soft' | 'outline' | 'ghost' | 'link' | 'primary';
 	export type ButtonSize = 'sm' | 'md' | 'lg' | 'xl';
 
-	interface Props extends HTMLButtonAttributes {
+	interface Props extends Omit<HTMLButtonAttributes, 'onclick'> {
 		variant?: ButtonVariant;
 		tone?: Tone;
 		size?: ButtonSize;
@@ -28,7 +29,19 @@
 		loading?: boolean;
 		/** Stretch to the container's full width. */
 		block?: boolean;
-		children: Snippet;
+		/** Leading icon. The spinner takes its place while the button is busy. */
+		icon?: Snippet;
+		/** Trailing icon. */
+		iconEnd?: Snippet;
+		/** Square button with no label — pass an `aria-label`. */
+		iconOnly?: boolean;
+		/**
+		 * Return a promise — a save, a submit, a fetch — and the button spins and
+		 * locks itself until it settles, without any state in the parent. It
+		 * unlocks on a rejection too, so catch failures inside the handler.
+		 */
+		onclick?: (event: MouseEvent) => unknown;
+		children?: Snippet;
 	}
 
 	let {
@@ -38,6 +51,10 @@
 		href,
 		loading = false,
 		block = false,
+		icon,
+		iconEnd,
+		iconOnly = false,
+		onclick,
 		disabled = false,
 		type = 'button',
 		class: className = '',
@@ -49,10 +66,17 @@
 		'inline-flex items-center justify-center gap-2 border font-sans font-medium whitespace-nowrap transition-all duration-150 ease-brand-out disabled:opacity-50 disabled:pointer-events-none aria-disabled:opacity-50 aria-disabled:pointer-events-none';
 
 	const sizes: Record<ButtonSize, string> = {
-		sm: 'h-9 px-4 text-[13px]',
-		md: 'h-11 px-7 text-[15px]',
-		lg: 'h-12 px-8 text-base',
-		xl: 'h-14 px-10 text-base'
+		sm: 'h-8 px-3.5 text-[13px]',
+		md: 'h-10 px-5 text-[15px]',
+		lg: 'h-11 px-6 text-base',
+		xl: 'h-12 px-8 text-base'
+	};
+
+	const squares: Record<ButtonSize, string> = {
+		sm: 'size-8',
+		md: 'size-10',
+		lg: 'size-11',
+		xl: 'size-12'
 	};
 
 	const variantClass = $derived.by(() => {
@@ -72,7 +96,24 @@
 	});
 
 	const isLink = $derived(variant === 'link');
-	const inert = $derived(disabled || loading);
+
+	/** Set by an `onclick` that returned a promise, on top of the `loading` prop. */
+	let pending = $state(false);
+	const busy = $derived(loading || pending);
+	const inert = $derived(disabled || busy);
+
+	const iconClass = $derived(size === 'sm' ? iconSm : iconMd);
+
+	async function handleClick(event: MouseEvent) {
+		const result = onclick?.(event);
+		// Anything else is a plain handler: nothing to wait for, nothing to lock.
+		if (!(result instanceof Promise)) return;
+		pending = true;
+		// The handler owns its own errors — catch them there to show a message.
+		// All the button needs to know is that the work has settled.
+		await result.catch(() => {});
+		pending = false;
+	}
 </script>
 
 <svelte:element
@@ -81,14 +122,24 @@
 	type={href ? undefined : type}
 	disabled={href ? undefined : inert}
 	aria-disabled={href && inert ? 'true' : undefined}
-	aria-busy={loading ? 'true' : undefined}
+	aria-busy={busy ? 'true' : undefined}
 	role={href ? 'button' : undefined}
-	class="{base} {focusRing} {toneRing[tone]} {variantClass} {isLink ? '' : sizes[size]}
+	class="{base} {focusRing} {toneRing[tone]} {variantClass} {isLink
+		? ''
+		: iconOnly
+			? squares[size]
+			: sizes[size]}
 		{block ? 'w-full' : ''} {className}"
 	{...rest}
+	onclick={handleClick}
 >
-	{#if loading}
+	{#if busy}
 		<Spinner size={size === 'sm' ? 'xs' : 'sm'} label="" />
+	{:else if icon}
+		<span class={iconClass} aria-hidden="true">{@render icon()}</span>
+	{/if}
+	{@render children?.()}
+	{#if iconEnd && !iconOnly}
+		<span class={iconClass} aria-hidden="true">{@render iconEnd()}</span>
 	{/if}
-	{@render children()}
 </svelte:element>