@marianmeres/stuic 3.115.0 → 3.117.0

package/dist/components/Checkout/README.md

@@ -8,30 +8,30 @@ There is deliberately **no top-level `<Checkout>`** orchestrator. If you want a
 
 ### Step containers (one per route/screen)
 
-| Component | Purpose |
-| --- | --- |
-| `CheckoutReviewStep` | Guest/login + cart review (entry point) |
-| `CheckoutShippingStep` | Address + delivery option selection |
-| `CheckoutConfirmStep` | Final order review + place-order action |
-| `CheckoutCompleteStep` | Post-purchase confirmation screen |
+| Component              | Purpose                                 |
+| ---------------------- | --------------------------------------- |
+| `CheckoutReviewStep`   | Guest/login + cart review (entry point) |
+| `CheckoutShippingStep` | Address + delivery option selection     |
+| `CheckoutConfirmStep`  | Final order review + place-order action |
+| `CheckoutCompleteStep` | Post-purchase confirmation screen       |
 
 Each step container renders a `CheckoutProgress` indicator (unless `hideProgress`), its own heading, and exposes `onBack` / `onContinue` callbacks. The consumer maps those callbacks to route navigation or state changes.
 
 ### Building blocks (composed inside steps, or used standalone)
 
-| Component | Purpose |
-| --- | --- |
-| `CheckoutProgress` | Multi-step progress indicator (accessible stepper) |
-| `CheckoutCartReview` | Editable line-item list |
-| `CheckoutOrderSummary` | Totals (subtotal/tax/shipping/discount/total) |
-| `CheckoutOrderReview` | Read-only order dump (items + addresses + delivery) |
-| `CheckoutOrderConfirmation` | Completed-order summary with order number & next steps |
-| `CheckoutGuestOrLoginForm` | Guest / login switcher (segmented pill) |
-| `CheckoutGuestForm` | Guest-checkout fields |
-| `CheckoutLoginForm` | Login (adapts the generic `LoginForm` to checkout i18n) |
-| `CheckoutAddressForm` | Structured address input |
-| `CheckoutDeliveryOptions` | Delivery-method selector |
-| `CheckoutSectionHeader` | Consistent section heading |
+| Component                   | Purpose                                                 |
+| --------------------------- | ------------------------------------------------------- |
+| `CheckoutProgress`          | Multi-step progress indicator (accessible stepper)      |
+| `CheckoutCartReview`        | Editable line-item list                                 |
+| `CheckoutOrderSummary`      | Totals (subtotal/tax/shipping/discount/total)           |
+| `CheckoutOrderReview`       | Read-only order dump (items + addresses + delivery)     |
+| `CheckoutOrderConfirmation` | Completed-order summary with order number & next steps  |
+| `CheckoutGuestOrLoginForm`  | Guest / login switcher (segmented pill)                 |
+| `CheckoutGuestForm`         | Guest-checkout fields                                   |
+| `CheckoutLoginForm`         | Login (adapts the generic `LoginForm` to checkout i18n) |
+| `CheckoutAddressForm`       | Structured address input                                |
+| `CheckoutDeliveryOptions`   | Delivery-method selector                                |
+| `CheckoutSectionHeader`     | Consistent section heading                              |
 
 ## State ownership
 
@@ -39,25 +39,25 @@ The consumer owns the entire order shape — typically `CheckoutOrderData` from
 
 ```ts
 import type {
-    CheckoutOrderData,
-    CheckoutAddressData,
-    CheckoutCustomerFormData,
-    CheckoutLoginFormData,
-    CheckoutDeliveryOption,
+	CheckoutOrderData,
+	CheckoutAddressData,
+	CheckoutCustomerFormData,
+	CheckoutLoginFormData,
+	CheckoutDeliveryOption,
 } from "@marianmeres/stuic";
 ```
 
 **Field → owner table:**
 
-| Field | Owned by | Passed to |
-| --- | --- | --- |
-| `currentStep` (or equivalent) | Route/page state | `CheckoutProgress`, step visibility logic |
-| `CheckoutCustomerFormData` | Page `$state` | `CheckoutGuestForm` (two-way bind) |
-| `CheckoutLoginFormData` | Page `$state` | `CheckoutLoginForm` (two-way bind) |
-| `shippingAddress`, `billingAddress` | Page `$state` | `CheckoutShippingStep` (two-way bind) — re-used by `CheckoutConfirmStep` for display |
-| `selectedDeliveryId` | Page `$state` | `CheckoutShippingStep` (two-way bind) |
-| `CheckoutOrderData` (assembled) | Page `$state` / server | `CheckoutOrderReview`, `CheckoutConfirmStep`, `CheckoutCompleteStep` (read-only) |
-| Per-field validation errors | Page `$state` (derived from server response) | Forms via `errors` prop; merged with internal errors |
+| Field                               | Owned by                                     | Passed to                                                                            |
+| ----------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `currentStep` (or equivalent)       | Route/page state                             | `CheckoutProgress`, step visibility logic                                            |
+| `CheckoutCustomerFormData`          | Page `$state`                                | `CheckoutGuestForm` (two-way bind)                                                   |
+| `CheckoutLoginFormData`             | Page `$state`                                | `CheckoutLoginForm` (two-way bind)                                                   |
+| `shippingAddress`, `billingAddress` | Page `$state`                                | `CheckoutShippingStep` (two-way bind) — re-used by `CheckoutConfirmStep` for display |
+| `selectedDeliveryId`                | Page `$state`                                | `CheckoutShippingStep` (two-way bind)                                                |
+| `CheckoutOrderData` (assembled)     | Page `$state` / server                       | `CheckoutOrderReview`, `CheckoutConfirmStep`, `CheckoutCompleteStep` (read-only)     |
+| Per-field validation errors         | Page `$state` (derived from server response) | Forms via `errors` prop; merged with internal errors                                 |
 
 Each form exposes a bindable value plus an `errors` prop for server-driven validation messages. Internal client-side validation (via `validateCustomerForm` / `validateAddress` / `validateLoginForm`) fires on submit and populates internal error state, which is merged with the `errors` prop for display.
 
@@ -67,10 +67,10 @@ Client-side validation helpers live in `@marianmeres/stuic`:
 
 ```ts
 import {
-    validateCustomerForm,
-    validateAddress,
-    validateLoginForm,
-    validateEmail,
+	validateCustomerForm,
+	validateAddress,
+	validateLoginForm,
+	validateEmail,
 } from "@marianmeres/stuic";
 ```
 
@@ -78,8 +78,8 @@ Each returns `CheckoutValidationError[]`:
 
 ```ts
 interface CheckoutValidationError {
-    field: string; // e.g. "email" or "shipping.street"
-    message: string;
+	field: string; // e.g. "email" or "shipping.street"
+	message: string;
 }
 ```
 
@@ -87,36 +87,41 @@ interface CheckoutValidationError {
 
 ```svelte
 <script lang="ts">
-    import {
-        CheckoutShippingStep,
-        CheckoutAddressForm,
-        validateAddress,
-        type CheckoutAddressData,
-        type CheckoutValidationError,
-    } from "@marianmeres/stuic";
-
-    let shippingAddress = $state<CheckoutAddressData>(/* ... */);
-    let errors = $state<CheckoutValidationError[]>([]);
-
-    async function onContinue() {
-        // 1) Client-side gate
-        const clientErrors = validateAddress(shippingAddress, "shipping", t);
-        if (clientErrors.length) {
-            errors = clientErrors;
-            return;
-        }
-        // 2) Server round-trip; merge any server errors
-        const res = await submitShipping(shippingAddress);
-        if (!res.ok) {
-            errors = res.errors;
-            return;
-        }
-        // 3) Advance
-        goto("/checkout/confirm");
-    }
+	import {
+		CheckoutShippingStep,
+		CheckoutAddressForm,
+		validateAddress,
+		type CheckoutAddressData,
+		type CheckoutValidationError,
+	} from "@marianmeres/stuic";
+
+	let shippingAddress = $state<CheckoutAddressData>(/* ... */);
+	let errors = $state<CheckoutValidationError[]>([]);
+
+	async function onContinue() {
+		// 1) Client-side gate
+		const clientErrors = validateAddress(shippingAddress, "shipping", t);
+		if (clientErrors.length) {
+			errors = clientErrors;
+			return;
+		}
+		// 2) Server round-trip; merge any server errors
+		const res = await submitShipping(shippingAddress);
+		if (!res.ok) {
+			errors = res.errors;
+			return;
+		}
+		// 3) Advance
+		goto("/checkout/confirm");
+	}
 </script>
 
-<CheckoutShippingStep bind:shippingAddress {errors} {onContinue} onBack={() => history.back()} />
+<CheckoutShippingStep
+	bind:shippingAddress
+	{errors}
+	{onContinue}
+	onBack={() => history.back()}
+/>
 ```
 
 The step component **does not auto-advance**. It calls `onContinue` when the user clicks "Continue"; the consumer decides whether to actually advance, retry, or show errors.
@@ -129,8 +134,9 @@ The built-in `defaultFormatPrice(cents)` returns `"12.99"`. Replace it via each
 
 ```ts
 const formatPrice = (cents: number) =>
-    new Intl.NumberFormat("sk-SK", { style: "currency", currency: "EUR" })
-        .format(cents / 100);
+	new Intl.NumberFormat("sk-SK", { style: "currency", currency: "EUR" }).format(
+		cents / 100
+	);
 ```
 
 ## i18n
@@ -147,67 +153,74 @@ By default `CheckoutGuestOrLoginForm` in tabbed mode renders an inline `<Checkou
 
 ```svelte
 <script lang="ts">
-    import {
-        CheckoutGuestOrLoginForm,
-        createEmptyCustomerFormData,
-        createEmptyLoginFormData,
-        type LoginOrRegisterFormMode,
-        type LoginFormData,
-        type RegisterFormData,
-    } from "@marianmeres/stuic";
-
-    let formData = $state(createEmptyCustomerFormData());
-    let loginFormData = $state(createEmptyLoginFormData());
-
-    let mode = $state<LoginOrRegisterFormMode>("login");
-    let verifyEmail = $state("");
-    let isSubmitting = $state(false);
-    let formError = $state<string | null>(null);
-
-    const loginProps = $derived({ error: formError ?? undefined, showRememberMe: true });
-    const registerProps = $derived({ error: formError ?? undefined });
-    const verifyProps = $derived({ error: formError ?? undefined, heading: false as const });
-
-    async function onLogin(d: LoginFormData) {
-        // ... call API; on `requiresVerification`, flip:
-        //     verifyEmail = d.email; mode = "verify";
-    }
-    async function onRegister(d: RegisterFormData) {
-        // ... call API; on success, flip to verify:
-        //     verifyEmail = d.email; mode = "verify";
-    }
-    async function onVerify(code: string) {
-        // ... call API; on success, modal closes via consumer-managed state.
-    }
-    async function onResendCode() { /* ... */ }
+	import {
+		CheckoutGuestOrLoginForm,
+		createEmptyCustomerFormData,
+		createEmptyLoginFormData,
+		type LoginOrRegisterFormMode,
+		type LoginFormData,
+		type RegisterFormData,
+	} from "@marianmeres/stuic";
+
+	let formData = $state(createEmptyCustomerFormData());
+	let loginFormData = $state(createEmptyLoginFormData());
+
+	let mode = $state<LoginOrRegisterFormMode>("login");
+	let verifyEmail = $state("");
+	let isSubmitting = $state(false);
+	let formError = $state<string | null>(null);
+
+	const loginProps = $derived({ error: formError ?? undefined, showRememberMe: true });
+	const registerProps = $derived({ error: formError ?? undefined });
+	const verifyProps = $derived({
+		error: formError ?? undefined,
+		heading: false as const,
+	});
+
+	async function onLogin(d: LoginFormData) {
+		// ... call API; on `requiresVerification`, flip:
+		//     verifyEmail = d.email; mode = "verify";
+	}
+	async function onRegister(d: RegisterFormData) {
+		// ... call API; on success, flip to verify:
+		//     verifyEmail = d.email; mode = "verify";
+	}
+	async function onVerify(code: string) {
+		// ... call API; on success, modal closes via consumer-managed state.
+	}
+	async function onResendCode() {
+		/* ... */
+	}
 </script>
 
 <CheckoutGuestOrLoginForm
-    formMode="tabbed"
-    guestForm={{ formData, onSubmit: handleStartCheckout, isSubmitting, errors: [] }}
-    loginForm={{ formData: loginFormData, onSubmit: onLogin, isSubmitting }}
-    loginOrRegisterModal={{
-        mode,
-        verifyEmail,
-        onLogin,
-        onRegister,
-        onVerify,
-        onResendCode,
-        onForgotPassword: () => {/* ... */},
-        onModeChange: (next) => {
-            // mirror mode changes back into our local state and clear errors
-            mode = next;
-            formError = null;
-        },
-        isSubmitting,
-        loginProps,
-        registerProps,
-        verifyProps,
-        onClose: () => {
-            formError = null;
-            mode = "login";
-        },
-    }}
+	formMode="tabbed"
+	guestForm={{ formData, onSubmit: handleStartCheckout, isSubmitting, errors: [] }}
+	loginForm={{ formData: loginFormData, onSubmit: onLogin, isSubmitting }}
+	loginOrRegisterModal={{
+		mode,
+		verifyEmail,
+		onLogin,
+		onRegister,
+		onVerify,
+		onResendCode,
+		onForgotPassword: () => {
+			/* ... */
+		},
+		onModeChange: (next) => {
+			// mirror mode changes back into our local state and clear errors
+			mode = next;
+			formError = null;
+		},
+		isSubmitting,
+		loginProps,
+		registerProps,
+		verifyProps,
+		onClose: () => {
+			formError = null;
+			mode = "login";
+		},
+	}}
 />
 ```
 
@@ -237,9 +250,9 @@ Returns `true` when either address is missing or when every `CheckoutAddressData
 
 ```ts
 import {
-    createEmptyAddress,
-    createEmptyCustomerFormData,
-    createEmptyLoginFormData,
+	createEmptyAddress,
+	createEmptyCustomerFormData,
+	createEmptyLoginFormData,
 } from "@marianmeres/stuic";
 ```
 

package/dist/components/CommandMenu/CommandMenu.fixture.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+	// Conventions escape hatch (docs/component-testing/02-test-conventions.md):
+	// CommandMenu is imperative-only (open()/close() via a ref; it builds on
+	// ModalDialog which has no bindable `visible` prop), so a `.svelte.test.ts`
+	// file can't drive it directly. This fixture holds the `bind:this` ref and
+	// exposes an opener button that calls `.open()`. `getOptions` (a required
+	// async prop) is forwarded; `value` is bound so a test can inspect the
+	// selected option after a pick.
+	import CommandMenu from "./CommandMenu.svelte";
+
+	let cmd = $state<CommandMenu>();
+	let { getOptions, value = $bindable() } = $props();
+</script>
+
+<button data-testid="opener" onclick={() => cmd?.open()}>open</button>
+
+<!--
+	Mirror the bound `value` into the DOM so a test can observe what the menu
+	selected (render() from vitest-browser-svelte does not hand back bound props).
+	The selected option is an item-collection Item; we surface its `id`.
+-->
+<span data-testid="selected">{value?.id ?? ""}</span>
+
+<CommandMenu bind:this={cmd} bind:value {getOptions} />

package/dist/components/CommandMenu/CommandMenu.fixture.svelte.d.ts

@@ -0,0 +1,7 @@
+import CommandMenu from "./CommandMenu.svelte";
+declare const CommandMenu: import("svelte").Component<{
+    getOptions: any;
+    value?: any;
+}, {}, "value">;
+type CommandMenu = ReturnType<typeof CommandMenu>;
+export default CommandMenu;

package/dist/components/CommandMenu/CommandMenu.svelte

@@ -65,6 +65,11 @@
 
 <script lang="ts">
 	import Button from "../Button/Button.svelte";
+	import {
+		normalizeAndGroupOptions,
+		renderOptionLabelOf,
+		sortByOptgroupLabel,
+	} from "./_internal/command-menu-utils.js";
 
 	const clog = createClog("CommandMenu");
 
@@ -86,15 +91,14 @@
 		unstyled = false,
 	}: Props = $props();
 
+	// Pure helpers extracted to _internal/command-menu-utils.ts (node-tested). These
+	// thin wrappers keep reading the live props/closures and delegate the logic.
 	function _renderOptionLabel(item: Item): string {
-		return renderOptionLabel?.(item) || `${item[itemIdPropName]}`;
+		return renderOptionLabelOf(item, renderOptionLabel, itemIdPropName);
 	}
 
 	function sortFn(a: Item, b: Item) {
-		const withOptGroup = (i: Item) => `${i.optgroup || ""}__${_renderOptionLabel(i)}`;
-		return withOptGroup(a).localeCompare(withOptGroup(b), undefined, {
-			sensitivity: "base",
-		});
+		return sortByOptgroupLabel(a, b, _renderOptionLabel);
 	}
 
 	let modalDialog: ModalDialog = $state()!;
@@ -155,14 +159,7 @@
 
 	//
 	function _normalize_and_group_options(opts: Item[]): Map<string, Item[]> {
-		const groupped = new Map<string, Item[]>();
-		opts.forEach((o) => {
-			const optgLabel = renderOptionGroup(o.optgroup || "");
-			if (!groupped.has(optgLabel)) groupped.set(optgLabel, []);
-			const optgroup = groupped.get(optgLabel);
-			optgroup!.push(o);
-		});
-		return groupped;
+		return normalizeAndGroupOptions(opts, renderOptionGroup);
 	}
 
 	export function close() {

package/dist/components/CommandMenu/_internal/command-menu-utils.d.ts

@@ -0,0 +1,22 @@
+import type { Item } from "@marianmeres/item-collection";
+/**
+ * Pure option/result helpers for CommandMenu, extracted from the component so they
+ * can be unit-tested in the fast node project (no DOM). The actual searchable
+ * matching is delegated to `@marianmeres/item-collection`; these are the structural
+ * pieces around the results — how a result's label is derived, how results sort, and
+ * how they group by optgroup for rendering.
+ */
+/** Derive an option's display label: the consumer renderer, else its id prop. */
+export declare function renderOptionLabelOf(item: Item, renderOptionLabel: ((item: Item) => string) | undefined, itemIdPropName: string): string;
+/**
+ * Compare two options by "{optgroup}__{label}" using a case-insensitive locale
+ * compare, so options sort grouped-then-alphabetical. `renderLabel` derives the
+ * label part (typically `renderOptionLabelOf` bound to the component's props).
+ */
+export declare function sortByOptgroupLabel(a: Item, b: Item, renderLabel: (item: Item) => string): number;
+/**
+ * Group options into a Map keyed by their (rendered) optgroup label, preserving
+ * input order within each group. `renderOptionGroup` maps a raw optgroup key to its
+ * display label (e.g. underscores → spaces).
+ */
+export declare function normalizeAndGroupOptions(opts: Item[], renderOptionGroup: (s: string) => string): Map<string, Item[]>;

package/dist/components/CommandMenu/_internal/command-menu-utils.js

@@ -0,0 +1,37 @@
+/**
+ * Pure option/result helpers for CommandMenu, extracted from the component so they
+ * can be unit-tested in the fast node project (no DOM). The actual searchable
+ * matching is delegated to `@marianmeres/item-collection`; these are the structural
+ * pieces around the results — how a result's label is derived, how results sort, and
+ * how they group by optgroup for rendering.
+ */
+/** Derive an option's display label: the consumer renderer, else its id prop. */
+export function renderOptionLabelOf(item, renderOptionLabel, itemIdPropName) {
+    return renderOptionLabel?.(item) || `${item[itemIdPropName]}`;
+}
+/**
+ * Compare two options by "{optgroup}__{label}" using a case-insensitive locale
+ * compare, so options sort grouped-then-alphabetical. `renderLabel` derives the
+ * label part (typically `renderOptionLabelOf` bound to the component's props).
+ */
+export function sortByOptgroupLabel(a, b, renderLabel) {
+    const withOptGroup = (i) => `${i.optgroup || ""}__${renderLabel(i)}`;
+    return withOptGroup(a).localeCompare(withOptGroup(b), undefined, {
+        sensitivity: "base",
+    });
+}
+/**
+ * Group options into a Map keyed by their (rendered) optgroup label, preserving
+ * input order within each group. `renderOptionGroup` maps a raw optgroup key to its
+ * display label (e.g. underscores → spaces).
+ */
+export function normalizeAndGroupOptions(opts, renderOptionGroup) {
+    const groupped = new Map();
+    opts.forEach((o) => {
+        const optgLabel = renderOptionGroup(o.optgroup || "");
+        if (!groupped.has(optgLabel))
+            groupped.set(optgLabel, []);
+        groupped.get(optgLabel).push(o);
+    });
+    return groupped;
+}