@marianmeres/stuic 3.66.1 → 3.68.0

package/dist/actions/autoscroll.d.ts

@@ -30,6 +30,13 @@ export type AutoscrollOptions = ScrollOptions & {
  * - Observes child mutations and resize events
  * - Supports reactive store dependencies for manual trigger
  *
+ * @remarks
+ * This action intentionally uses the Svelte-4-style `(node, options)` signature with a
+ * `{ destroy }` return shape rather than the newer `.svelte.ts` + `$effect` pattern used
+ * by other actions in this library. It's legacy code imported from a pre-Svelte-5 project
+ * and is kept as-is for backwards compatibility. Svelte 5 still supports this pattern as a
+ * first-class API, so there's no rush to convert.
+ *
  * @param node - The scrollable container element
  * @param options - Configuration options
  * @param options.behavior - Scroll behavior: 'smooth' | 'instant' | 'auto' (default: 'smooth')

package/dist/actions/autoscroll.js

@@ -14,6 +14,13 @@ const DEFAULTS = {
  * - Observes child mutations and resize events
  * - Supports reactive store dependencies for manual trigger
  *
+ * @remarks
+ * This action intentionally uses the Svelte-4-style `(node, options)` signature with a
+ * `{ destroy }` return shape rather than the newer `.svelte.ts` + `$effect` pattern used
+ * by other actions in this library. It's legacy code imported from a pre-Svelte-5 project
+ * and is kept as-is for backwards compatibility. Svelte 5 still supports this pattern as a
+ * first-class API, so there's no rush to convert.
+ *
  * @param node - The scrollable container element
  * @param options - Configuration options
  * @param options.behavior - Scroll behavior: 'smooth' | 'instant' | 'auto' (default: 'smooth')

package/dist/actions/focus-trap.d.ts

@@ -17,6 +17,13 @@ export interface FocusTrapOptions {
  * - Handles dynamically added/removed elements via MutationObserver
  * - Excludes disabled elements and negative tabindexes
  *
+ * @remarks
+ * This action intentionally uses the Svelte-4-style `(node, options)` signature with an
+ * `{ update, destroy }` return shape rather than the newer `.svelte.ts` + `$effect` pattern
+ * used by other actions in this library. It's legacy code imported from a pre-Svelte-5
+ * project and is kept as-is for backwards compatibility. Svelte 5 still supports this
+ * pattern as a first-class API, so there's no rush to convert.
+ *
  * @param node - The container element to trap focus within
  * @param options - Configuration options
  * @param options.enabled - Whether the trap is active (default: true)

package/dist/actions/focus-trap.js

@@ -11,6 +11,13 @@ const defaults = { enabled: true, autoFocusFirst: true };
  * - Handles dynamically added/removed elements via MutationObserver
  * - Excludes disabled elements and negative tabindexes
  *
+ * @remarks
+ * This action intentionally uses the Svelte-4-style `(node, options)` signature with an
+ * `{ update, destroy }` return shape rather than the newer `.svelte.ts` + `$effect` pattern
+ * used by other actions in this library. It's legacy code imported from a pre-Svelte-5
+ * project and is kept as-is for backwards compatibility. Svelte 5 still supports this
+ * pattern as a first-class API, so there's no rush to convert.
+ *
  * @param node - The container element to trap focus within
  * @param options - Configuration options
  * @param options.enabled - Whether the trap is active (default: true)
@@ -32,9 +39,7 @@ const defaults = { enabled: true, autoFocusFirst: true };
  * ```
  */
 export function focusTrap(node, options = {}) {
-    let enabled;
-    const { enabled: _enabled, autoFocusFirst } = { ...defaults, ...(options || {}) };
-    enabled = _enabled ?? true;
+    let { enabled = true, autoFocusFirst } = { ...defaults, ...(options ?? {}) };
     const focusableSelectors = [
         "[contentEditable=true]",
         //

package/dist/actions/typeahead.svelte.js

@@ -32,6 +32,12 @@ export function typeahead(el, fn) {
     let debounceTimer = null;
     let previousKey = "";
     let allowListAll = false;
+    // Monotonic token — used to discard stale async results when a newer search has started.
+    let searchSeq = 0;
+    // Captures parent's inline position value before we mutate it, so cleanup can restore.
+    // `null` means we did not mutate the parent (e.g. it wasn't static to begin with).
+    let parentOriginalPosition = null;
+    let parentEl = null;
     // Current resolved options
     let currentOpts = { getOptions: async () => [] };
     // Helper: render option label
@@ -60,11 +66,12 @@ export function typeahead(el, fn) {
         const hint = currentOpts.appendHint ?? DEFAULT_APPEND_HINT;
         return suggestion ? suggestion + hint : "";
     }
-    // Update ghost input value
+    // Update ghost input value + reflect expanded state for assistive tech
     function updateGhost() {
         if (ghostEl) {
             ghostEl.value = getVisibleSuggestion();
         }
+        el.setAttribute("aria-expanded", options?.active ? "true" : "false");
     }
     // Create ghost input element
     function createGhost() {
@@ -76,11 +83,13 @@ export function typeahead(el, fn) {
         ghostEl.readOnly = true;
         ghostEl.setAttribute("aria-hidden", "true");
         ghostEl.setAttribute("autocomplete", "off");
-        // Ensure parent has relative positioning
+        // Ensure parent has relative positioning; remember original so cleanup can restore it
         const parent = el.parentElement;
         if (parent) {
+            parentEl = parent;
             const parentPos = getComputedStyle(parent).position;
             if (parentPos === "static") {
+                parentOriginalPosition = parent.style.position; // typically "" when not previously set inline
                 parent.style.position = "relative";
             }
         }
@@ -128,6 +137,8 @@ export function typeahead(el, fn) {
     async function performSearch(query) {
         if (!options || !currentOpts.getOptions)
             return;
+        // Tag this call — if a newer one starts before we finish, we'll drop our result.
+        const mySeq = ++searchSeq;
         options.clear();
         if (!allowListAll && !query) {
             updateGhost();
@@ -136,6 +147,9 @@ export function typeahead(el, fn) {
         currentOpts.onFetchingChange?.(true);
         try {
             const results = await currentOpts.getOptions(query, []);
+            // Stale response — a newer search has started; discard silently.
+            if (mySeq !== searchSeq)
+                return;
             if (!results.length) {
                 updateGhost();
                 return;
@@ -160,7 +174,10 @@ export function typeahead(el, fn) {
             clog.error(err);
         }
         finally {
-            currentOpts.onFetchingChange?.(false);
+            // Only the latest in-flight call should toggle the fetching state back off.
+            if (mySeq === searchSeq) {
+                currentOpts.onFetchingChange?.(false);
+            }
         }
     }
     // Submit handler
@@ -225,6 +242,13 @@ export function typeahead(el, fn) {
             options?.clear();
             handleSubmit(value);
         }
+        else if (e.key === "Escape" && options?.active) {
+            // Dismiss suggestion; stop propagation so we don't e.g. close a surrounding Modal
+            options?.clear();
+            updateGhost();
+            e.preventDefault();
+            e.stopPropagation();
+        }
         else if (e.key === "Backspace" && cursorPos === 0) {
             currentOpts.onDeleteRequest?.();
         }
@@ -261,6 +285,12 @@ export function typeahead(el, fn) {
         el.style.position = "";
         el.style.zIndex = "";
         el.style.background = "";
+        // Restore parent's position if we mutated it
+        if (parentEl && parentOriginalPosition !== null) {
+            parentEl.style.position = parentOriginalPosition;
+        }
+        parentEl = null;
+        parentOriginalPosition = null;
     }
     // Main effect for setup/cleanup
     $effect(() => {
@@ -313,13 +343,19 @@ export function typeahead(el, fn) {
         el.addEventListener("keydown", onKeyDown);
         el.addEventListener("input", onInput);
         el.addEventListener("blur", onBlur);
-        // Set autocomplete off
+        // Set autocomplete off + combobox semantics for assistive tech
         el.setAttribute("autocomplete", "off");
+        el.setAttribute("role", "combobox");
+        el.setAttribute("aria-autocomplete", "inline");
+        el.setAttribute("aria-expanded", "false");
         return () => {
             // Cleanup
             el.removeEventListener("keydown", onKeyDown);
             el.removeEventListener("input", onInput);
             el.removeEventListener("blur", onBlur);
+            el.removeAttribute("role");
+            el.removeAttribute("aria-autocomplete");
+            el.removeAttribute("aria-expanded");
             destroyGhost();
             if (debounceTimer)
                 clearTimeout(debounceTimer);

package/dist/components/Carousel/Carousel.svelte

@@ -98,6 +98,7 @@
 <script lang="ts">
 	import { ItemCollection } from "@marianmeres/item-collection";
 	import { twMerge } from "../../utils/tw-merge.js";
+	import { prefersReducedMotion } from "../../utils/prefers-reduced-motion.svelte.js";
 	import Thc from "../Thc/Thc.svelte";
 	import Button from "../Button/Button.svelte";
 	import {
@@ -139,6 +140,12 @@
 	let trackEl: HTMLDivElement | undefined = $state();
 	let itemEls: Record<string | number, HTMLDivElement> = $state({});
 
+	// Respect user's reduced-motion preference — when set, skip smooth scrolling.
+	const reducedMotion = prefersReducedMotion();
+	const effectiveScrollBehavior = $derived<ScrollBehavior>(
+		reducedMotion.current ? "instant" : scrollBehavior
+	);
+
 	// ItemCollection for managing items and active state
 	const coll: ItemColl = $derived.by(() => {
 		const out = new ItemCollection(
@@ -233,7 +240,7 @@
 			const activeItem = coll.active;
 			if (activeItem && itemEls[activeItem.id]) {
 				itemEls[activeItem.id]?.scrollIntoView({
-					behavior: scrollBehavior,
+					behavior: effectiveScrollBehavior,
 					block: "nearest",
 					inline:
 						snapAlign === "center" ? "center" : snapAlign === "end" ? "end" : "start",
@@ -245,7 +252,7 @@
 				() => {
 					isScrollingProgrammatically = false;
 				},
-				scrollBehavior === "instant" ? 0 : 300
+				effectiveScrollBehavior === "instant" ? 0 : 300
 			);
 		}, 0);
 	}

package/dist/components/Carousel/README.md

@@ -11,14 +11,20 @@ keyboard navigation, snap scrolling, and flexible content rendering via THC.
 | `itemsPerView`    | `number`                                                            | `1`        | Number of items visible per view       |
 | `peekPercent`     | `number`                                                            | `0`        | Percentage of next item to show (0-50) |
 | `gap`             | `number \| string`                                                  | -          | Gap between items                      |
+| `minItemWidth`    | `number`                                                            | `150`      | Minimum item width in px (auto-fit floor) |
 | `trackActive`     | `boolean`                                                           | `false`    | Enable active item tracking            |
+| `syncActiveOnScroll` | `boolean`                                                        | `false`    | Update active item based on scroll position (requires `trackActive`) |
 | `activeIndex`     | `number`                                                            | `0`        | Active item index (bindable)           |
 | `value`           | `string \| number`                                                  | -          | Active item id (bindable)              |
 | `snap`            | `boolean`                                                           | `true`     | Enable scroll snap                     |
 | `snapAlign`       | `"start" \| "center" \| "end"`                                      | `"start"`  | Snap alignment                         |
 | `keyboard`        | `boolean`                                                           | `true`     | Enable keyboard navigation             |
-| `loop`            | `boolean`                                                           | `false`    | Loop navigation                        |
-| `scrollBehavior`  | `ScrollBehavior`                                                    | `"smooth"` | Scroll behavior                        |
+| `wheelScroll`     | `boolean`                                                           | `true`     | Enable horizontal scrolling via mouse wheel |
+| `loop`            | `boolean`                                                           | `false`    | Loop navigation (arrows / keyboard only — wheel never loops) |
+| `scrollBehavior`  | `ScrollBehavior`                                                    | `"smooth"` | Scroll behavior (overridden to `"instant"` when `prefers-reduced-motion: reduce`) |
+| `scrollbar`       | `boolean`                                                           | `true`     | Show the scrollbar on hover (set `false` when using nav buttons) |
+| `arrows`          | `boolean`                                                           | `false`    | Show prev/next arrow buttons overlaid on left/right edges |
+| `classArrow`      | `string`                                                            | -          | Custom class for arrow buttons         |
 | `class`           | `string`                                                            | -          | Custom class for container             |
 | `classTrack`      | `string`                                                            | -          | Custom class for scroll track          |
 | `classItem`       | `string`                                                            | -          | Custom class for items                 |

package/dist/components/Cart/Cart.svelte

@@ -17,6 +17,7 @@
 			unit_price_each: "{price} each",
 			quantity_label: "Qty: {quantity}",
 			remove_item: "Remove",
+			remove_item_aria: "Remove {name}",
 			total_label: "Total",
 			item_count_1: "1 item",
 			item_count_n: "{count} items",
@@ -376,6 +377,7 @@
 												step={item.quantityStep ?? 1}
 												class={!unstyled ? "stuic-cart-quantity-input" : undefined}
 												value={item.quantity}
+												aria-label={t("quantity_label", { quantity: item.quantity })}
 												onblur={(e) =>
 													handleQuantityInputCommit(
 														item.id,
@@ -425,6 +427,7 @@
 										type="button"
 										class={!unstyled ? "stuic-cart-remove" : undefined}
 										disabled={isUpdating}
+										aria-label={t("remove_item_aria", { name: item.name }) || t("remove_item")}
 										onclick={() => onRemove?.(item.id)}
 									>
 										{t("remove_item")}

package/dist/components/Cart/README.md

@@ -46,12 +46,28 @@ summary) modes, plus a compact variant suitable for popover previews.
 />
 ```
 
+### Keeping `lineTotal` in sync
+
+**`lineTotal` is caller-computed**, not derived from `unitPrice × quantity`. This is intentional — it lets you encode per-line discounts, bulk pricing, or any formula you want. But it also means:
+
+> Whenever you respond to `onQuantityChange` or `onRemove`, you must recompute `lineTotal` alongside `quantity` before passing the new `items`. The cart total is summed from `lineTotal` values; if they go stale, the summary is wrong.
+
+Simple rule-of-thumb: in your quantity-change handler, if you have no special pricing, set `lineTotal = unitPrice * newQuantity`.
+
 ### Readonly Mode (checkout summary)
 
 ```svelte
 <Cart {items} readonly formatPrice={(v) => `$${(v / 100).toFixed(2)}`} />
 ```
 
+### Summary Variant (receipt-style)
+
+Minimal, dense read-only list for order confirmation screens or invoices. Each line is just `name ×qty` plus the line total — no thumbnails, no +/− controls, no footer.
+
+```svelte
+<Cart {items} variant="summary" formatPrice={(v) => `$${(v / 100).toFixed(2)}`} />
+```
+
 ### Compact Variant (for popovers)
 
 ```svelte
@@ -105,7 +121,7 @@ summary) modes, plus a compact variant suitable for popover previews.
 | Prop               | Type                                | Default                       | Description                                                         |
 | ------------------ | ----------------------------------- | ----------------------------- | ------------------------------------------------------------------- |
 | `items`            | `CartComponentItem[]`               | required                      | Cart items to display                                               |
-| `variant`          | `"default" \| "compact"`            | `"default"`                   | Layout variant. Compact is smaller, scrollable, implicitly readonly |
+| `variant`          | `"default" \| "compact" \| "summary"` | `"default"`                 | Layout variant. `compact` = smaller/scrollable (implicit readonly); `summary` = receipt-style list with name ×qty + line total, no thumbnails/controls/footer (implicit readonly) |
 | `formatPrice`      | `(value: number) => string`         | `(v) => (v / 100).toFixed(2)` | Format numeric price for display                                    |
 | `onQuantityChange` | `(id: string, qty: number) => void` | —                             | Called when quantity changes                                        |
 | `onRemove`         | `(id: string) => void`              | —                             | Called when remove is clicked                                       |
@@ -174,6 +190,7 @@ summary) modes, plus a compact variant suitable for popover previews.
 | `unit_price_each`   | "{price} each"       | Unit price label          |
 | `quantity_label`    | "Qty: {quantity}"    | Readonly quantity display |
 | `remove_item`       | "Remove"             | Remove button text        |
+| `remove_item_aria`  | "Remove {name}"      | Accessible label on the remove button (announces item name) |
 | `total_label`       | "Total"              | Summary label             |
 | `item_count_1`      | "1 item"             | Singular item count       |
 | `item_count_n`      | "{count} items"      | Plural item count         |

package/dist/components/Checkout/CheckoutOrderReview.svelte

@@ -93,7 +93,7 @@
 	import Button from "../Button/Button.svelte";
 	import H, { type HLevel } from "../H/H.svelte";
 	import { t_default } from "./_internal/checkout-i18n-defaults.js";
-	import { defaultFormatPrice } from "./_internal/checkout-utils.js";
+	import { defaultFormatPrice, addressesEqual } from "./_internal/checkout-utils.js";
 	import CheckoutSectionHeader from "./CheckoutSectionHeader.svelte";
 
 	let {
@@ -124,19 +124,9 @@
 		unstyled ? classProp : twMerge("stuic-checkout-review", classProp)
 	);
 
-	let isBillingSameAsShipping = $derived.by(() => {
-		const s = order.shipping_address;
-		const b = order.billing_address;
-		if (!b || !s) return true;
-		return (
-			s.name === b.name &&
-			s.street === b.street &&
-			s.city === b.city &&
-			s.postal_code === b.postal_code &&
-			s.country === b.country &&
-			(s.phone ?? "") === (b.phone ?? "")
-		);
-	});
+	let isBillingSameAsShipping = $derived(
+		addressesEqual(order.shipping_address, order.billing_address)
+	);
 </script>
 
 <div bind:this={el} class={_class} {...rest}>

package/dist/components/Checkout/README.md

@@ -0,0 +1,184 @@
+# Checkout
+
+A **kit of composable checkout components** — not a monolithic wizard. STUIC provides 15 self-contained pieces (step containers, forms, reviews, progress indicator, complete screen) and the consumer owns the composition: which steps run, in what order, and how state flows between them.
+
+There is deliberately **no top-level `<Checkout>`** orchestrator. If you want a linear wizard, wire it together in a single page component. If you want a single-page checkout or a novel flow, use the same parts differently.
+
+## Components
+
+### 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 |
+
+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` | Tabbed guest / login |
+| `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
+
+The consumer owns the entire order shape — typically `CheckoutOrderData` from the exported types:
+
+```ts
+import type {
+    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 |
+
+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.
+
+## Validation flow
+
+Client-side validation helpers live in `@marianmeres/stuic`:
+
+```ts
+import {
+    validateCustomerForm,
+    validateAddress,
+    validateLoginForm,
+    validateEmail,
+} from "@marianmeres/stuic";
+```
+
+Each returns `CheckoutValidationError[]`:
+
+```ts
+interface CheckoutValidationError {
+    field: string; // e.g. "email" or "shipping.street"
+    message: string;
+}
+```
+
+### Pattern for a step
+
+```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");
+    }
+</script>
+
+<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.
+
+## Price arithmetic
+
+**All monetary values are integers in the smallest currency unit (cents).** This applies to `CheckoutOrderLineItem.price`, `CheckoutDeliveryOption.price`, `CheckoutDeliveryOption.free_above`, and every field in `CheckoutOrderTotals`.
+
+The built-in `defaultFormatPrice(cents)` returns `"12.99"`. Replace it via each component's `formatPrice` prop for locale-aware formatting:
+
+```ts
+const formatPrice = (cents: number) =>
+    new Intl.NumberFormat("sk-SK", { style: "currency", currency: "EUR" })
+        .format(cents / 100);
+```
+
+## i18n
+
+Every component accepts an optional `t?: TranslateFn` prop. Sensible English defaults are provided — see `_internal/checkout-i18n-defaults.ts` for the full key set (~140 keys, all prefixed `checkout.*`). Override by passing your own `t` function on each component, or at the step-container level (step containers forward `t` to their children).
+
+`CheckoutLoginForm` internally bridges `checkout.login.*` keys to the generic `LoginForm` component's `login_form.*` keys, so you only need one consistent prefix.
+
+## Accessibility
+
+- `CheckoutProgress` renders past/current/future steps with `aria-current="step"` on the active step.
+- Form submissions do **not** automatically move focus to the first error field. Consumers wanting this behavior should do it in their `onContinue` handler after receiving validation errors.
+- `CheckoutGuestOrLoginForm` uses the underlying `TabbedMenu` semantics; focus does not auto-move to the tab-panel heading on tab switch.
+
+## Address equality (advanced)
+
+```ts
+import { addressesEqual } from "@marianmeres/stuic";
+
+addressesEqual(order.shipping_address, order.billing_address);
+```
+
+Returns `true` when either address is missing or when every `CheckoutAddressData` field matches (nullish values treated as empty strings). Used internally by `CheckoutOrderReview` to decide whether to show a separate billing block.
+
+## Empty-state factories
+
+```ts
+import {
+    createEmptyAddress,
+    createEmptyCustomerFormData,
+    createEmptyLoginFormData,
+} from "@marianmeres/stuic";
+```
+
+Use these to initialize `$state` with the correct shape.
+
+## Conventions
+
+Every component in this family:
+
+- Exposes `unstyled?: boolean`, `class?: string`, `el?: HTMLElement` (bindable).
+- Accepts `t?: TranslateFn` for i18n.
+- Uses cents-integer price values.
+- Uses `stuic-checkout-*` CSS classes; tokens live in the individual `_*.css` files in this directory.
+
+## Limitations
+
+- **No top-level orchestrator.** By design; consumers wire up step navigation.
+- **No generic `<T>` for line items.** `CheckoutOrderLineItem` is a fixed shape; use `itemsSection` / `cell` snippets for custom rendering.
+- **No automatic focus-on-error management.** Left to the consumer.
+- **No example route in `/src/routes`** yet — see the step-pattern snippet above for the shape consumers generally follow.

package/dist/components/Checkout/_internal/checkout-utils.d.ts

@@ -7,6 +7,12 @@ import type { TranslateFn } from "../../../types.js";
 export declare function defaultFormatPrice(cents: number): string;
 export declare function validateEmail(email: string, t: TranslateFn): string | null;
 export declare function validateCustomerForm(data: CheckoutCustomerFormData, t: TranslateFn): CheckoutValidationError[];
+/**
+ * Structural equality for two addresses. Nullish values are treated as empty strings.
+ * If either address is missing, returns true (the UI convention is "don't render a
+ * separate billing block").
+ */
+export declare function addressesEqual(a: CheckoutAddressData | undefined, b: CheckoutAddressData | undefined): boolean;
 export declare function validateAddress(address: CheckoutAddressData, prefix: string, t: TranslateFn): CheckoutValidationError[];
 export declare function validateLoginForm(data: CheckoutLoginFormData, t: TranslateFn): CheckoutValidationError[];
 export declare function createEmptyAddress(): CheckoutAddressData;

package/dist/components/Checkout/_internal/checkout-utils.js

@@ -44,6 +44,30 @@ const REQUIRED_ADDRESS_FIELDS = [
     "postal_code",
     "country",
 ];
+const ALL_ADDRESS_FIELDS = [
+    "name",
+    "street",
+    "city",
+    "postal_code",
+    "country",
+    "phone",
+    "label",
+    "is_default",
+];
+/**
+ * Structural equality for two addresses. Nullish values are treated as empty strings.
+ * If either address is missing, returns true (the UI convention is "don't render a
+ * separate billing block").
+ */
+export function addressesEqual(a, b) {
+    if (!a || !b)
+        return true;
+    for (const field of ALL_ADDRESS_FIELDS) {
+        if ((a[field] ?? "") !== (b[field] ?? ""))
+            return false;
+    }
+    return true;
+}
 export function validateAddress(address, prefix, t) {
     const errors = [];
     for (const field of REQUIRED_ADDRESS_FIELDS) {

package/dist/components/Checkout/index.d.ts

@@ -13,4 +13,4 @@ export { default as CheckoutShippingStep, type Props as CheckoutShippingStepProp
 export { default as CheckoutConfirmStep, type Props as CheckoutConfirmStepProps, } from "./CheckoutConfirmStep.svelte";
 export { default as CheckoutCompleteStep, type Props as CheckoutCompleteStepProps, } from "./CheckoutCompleteStep.svelte";
 export type { CheckoutStep, CheckoutAddressData, CheckoutCustomerFormData, CheckoutLoginFormData, CheckoutOrderLineItem, CheckoutOrderTotals, CheckoutDeliveryOption, CheckoutDeliverySnapshot, CheckoutOrderData, CheckoutValidationError, } from "./_internal/checkout-types.js";
-export { defaultFormatPrice, validateEmail, validateAddress, validateCustomerForm, validateLoginForm, createEmptyAddress, createEmptyCustomerFormData, createEmptyLoginFormData, } from "./_internal/checkout-utils.js";
+export { defaultFormatPrice, validateEmail, validateAddress, validateCustomerForm, validateLoginForm, createEmptyAddress, createEmptyCustomerFormData, createEmptyLoginFormData, addressesEqual, } from "./_internal/checkout-utils.js";

package/dist/components/Checkout/index.js

@@ -14,4 +14,4 @@ export { default as CheckoutShippingStep, } from "./CheckoutShippingStep.svelte"
 export { default as CheckoutConfirmStep, } from "./CheckoutConfirmStep.svelte";
 export { default as CheckoutCompleteStep, } from "./CheckoutCompleteStep.svelte";
 // Utilities
-export { defaultFormatPrice, validateEmail, validateAddress, validateCustomerForm, validateLoginForm, createEmptyAddress, createEmptyCustomerFormData, createEmptyLoginFormData, } from "./_internal/checkout-utils.js";
+export { defaultFormatPrice, validateEmail, validateAddress, validateCustomerForm, validateLoginForm, createEmptyAddress, createEmptyCustomerFormData, createEmptyLoginFormData, addressesEqual, } from "./_internal/checkout-utils.js";