@marianmeres/stuic 3.18.0 → 3.19.0

package/AGENTS.md

@@ -25,7 +25,7 @@
 src/lib/
 ├── components/     # 44 UI components
 ├── actions/        # 14 Svelte actions
-├── utils/          # 42 utility functions
+├── utils/          # 42 utility modules
 ├── themes/         # 29 theme definitions (.ts) + generated CSS (css/)
 ├── icons/          # Icon re-exports
 ├── index.css       # Centralized CSS imports
@@ -74,10 +74,10 @@ src/lib/
 
 ### Domain Docs
 
-- [Components](./docs/domains/components.md) — 44 components, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 44 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [Actions](./docs/domains/actions.md) — 14 Svelte directives
-- [Utils](./docs/domains/utils.md) — 42 utility functions
+- [Utils](./docs/domains/utils.md) — 42 utility modules
 
 ### Reference
 

package/dist/components/Checkout/CheckoutCompleteStep.svelte

@@ -24,6 +24,9 @@
 
 		// -- Progress --
 
+		/** Hide the built-in progress indicator (e.g. when rendered externally) */
+		hideProgress?: boolean;
+
 		currentStep?: string;
 		steps?: CheckoutStep[];
 		onStepNavigate?: (step: CheckoutStep) => void;
@@ -76,6 +79,7 @@
 		emailSent,
 		isLoading = false,
 		error,
+		hideProgress = false,
 		currentStep = "complete",
 		steps,
 		onStepNavigate,
@@ -102,13 +106,15 @@
 
 <div bind:this={el} class={_class} {...rest}>
 	<!-- Progress -->
-	<CheckoutProgress
-		{steps}
-		{currentStep}
-		onNavigate={onStepNavigate}
-		t={tProp}
-		{unstyled}
-	/>
+	{#if !hideProgress}
+		<CheckoutProgress
+			{steps}
+			{currentStep}
+			onNavigate={onStepNavigate}
+			t={tProp}
+			{unstyled}
+		/>
+	{/if}
 
 	{#if isLoading}
 		<div class={unstyled ? undefined : "stuic-checkout-complete-step-loading"}>

package/dist/components/Checkout/CheckoutCompleteStep.svelte.d.ts

@@ -13,6 +13,8 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
     isLoading?: boolean;
     /** Error message */
     error?: string | null;
+    /** Hide the built-in progress indicator (e.g. when rendered externally) */
+    hideProgress?: boolean;
     currentStep?: string;
     steps?: CheckoutStep[];
     onStepNavigate?: (step: CheckoutStep) => void;

package/dist/components/Checkout/CheckoutConfirmStep.svelte

@@ -34,6 +34,9 @@
 
 		// -- Progress --
 
+		/** Hide the built-in progress indicator (e.g. when rendered externally) */
+		hideProgress?: boolean;
+
 		currentStep?: string;
 		steps?: CheckoutStep[];
 		onStepNavigate?: (step: CheckoutStep) => void;
@@ -99,6 +102,7 @@
 		validationErrors,
 		isValid = true,
 		isSubmitting = false,
+		hideProgress = false,
 		currentStep = "confirm",
 		steps,
 		onStepNavigate,
@@ -132,13 +136,15 @@
 
 <div bind:this={el} class={_class} {...rest}>
 	<!-- Progress -->
-	<CheckoutProgress
-		{steps}
-		{currentStep}
-		onNavigate={onStepNavigate}
-		t={tProp}
-		{unstyled}
-	/>
+	{#if !hideProgress}
+		<CheckoutProgress
+			{steps}
+			{currentStep}
+			onNavigate={onStepNavigate}
+			t={tProp}
+			{unstyled}
+		/>
+	{/if}
 
 	{#if isLoading}
 		<!-- Skeleton grid -->

package/dist/components/Checkout/CheckoutConfirmStep.svelte.d.ts

@@ -18,6 +18,8 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
     isValid?: boolean;
     /** Whether payment is being initiated */
     isSubmitting?: boolean;
+    /** Hide the built-in progress indicator (e.g. when rendered externally) */
+    hideProgress?: boolean;
     currentStep?: string;
     steps?: CheckoutStep[];
     onStepNavigate?: (step: CheckoutStep) => void;

package/dist/components/Checkout/CheckoutReviewStep.svelte

@@ -22,6 +22,9 @@
 
 		// -- Progress --
 
+		/** Hide the built-in progress indicator (e.g. when rendered externally) */
+		hideProgress?: boolean;
+
 		/** Current step ID for the progress indicator. Default: "review" */
 		currentStep?: string;
 
@@ -111,6 +114,7 @@
 		items,
 		isLoading = false,
 		error,
+		hideProgress = false,
 		currentStep = "review",
 		steps,
 		onStepNavigate,
@@ -140,13 +144,15 @@
 
 <div bind:this={el} class={_class} {...rest}>
 	<!-- Progress -->
-	<CheckoutProgress
-		{steps}
-		{currentStep}
-		onNavigate={onStepNavigate}
-		t={tProp}
-		{unstyled}
-	/>
+	{#if !hideProgress}
+		<CheckoutProgress
+			{steps}
+			{currentStep}
+			onNavigate={onStepNavigate}
+			t={tProp}
+			{unstyled}
+		/>
+	{/if}
 
 	{#if isLoading}
 		<!-- Skeleton grid -->

package/dist/components/Checkout/CheckoutReviewStep.svelte.d.ts

@@ -10,6 +10,8 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
     isLoading?: boolean;
     /** Error message to display */
     error?: string | null;
+    /** Hide the built-in progress indicator (e.g. when rendered externally) */
+    hideProgress?: boolean;
     /** Current step ID for the progress indicator. Default: "review" */
     currentStep?: string;
     /** Step definitions for progress. Default: standard 4-step flow */

package/dist/components/Checkout/CheckoutShippingStep.svelte

@@ -30,6 +30,9 @@
 
 		// -- Progress --
 
+		/** Hide the built-in progress indicator (e.g. when rendered externally) */
+		hideProgress?: boolean;
+
 		currentStep?: string;
 		steps?: CheckoutStep[];
 		onStepNavigate?: (step: CheckoutStep) => void;
@@ -127,6 +130,7 @@
 		isLoading = false,
 		error,
 		isSubmitting = false,
+		hideProgress = false,
 		currentStep = "shipping",
 		steps,
 		onStepNavigate,
@@ -164,13 +168,15 @@
 
 <div bind:this={el} class={_class} {...rest}>
 	<!-- Progress -->
-	<CheckoutProgress
-		{steps}
-		{currentStep}
-		onNavigate={onStepNavigate}
-		t={tProp}
-		{unstyled}
-	/>
+	{#if !hideProgress}
+		<CheckoutProgress
+			{steps}
+			{currentStep}
+			onNavigate={onStepNavigate}
+			t={tProp}
+			{unstyled}
+		/>
+	{/if}
 
 	{#if isLoading}
 		<!-- Skeleton grid -->

package/dist/components/Checkout/CheckoutShippingStep.svelte.d.ts

@@ -13,6 +13,8 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
     error?: string | null;
     /** Whether the continue action is in progress */
     isSubmitting?: boolean;
+    /** Hide the built-in progress indicator (e.g. when rendered externally) */
+    hideProgress?: boolean;
     currentStep?: string;
     steps?: CheckoutStep[];
     onStepNavigate?: (step: CheckoutStep) => void;

package/dist/components/ModalDialog/ModalDialog.svelte

@@ -128,6 +128,26 @@
 	// Note, that this will also reset if nested... (which is not desired, but ignoring)
 	onDestroy(BodyScroll.unlock);
 
+	async function _onEscapeKeydown(e: KeyboardEvent) {
+		if (e.key === "Escape" && visible) {
+			// do not allow built-in close on escape
+			e.preventDefault();
+			// do not bubble
+			e.stopPropagation();
+			// do not allow additional onkeydown listeners on this dialog
+			e.stopImmediatePropagation();
+
+			if (!noEscapeClose) {
+				// explicit false prevents close
+				let allowed = await preEscapeClose?.();
+				if (allowed !== false) {
+					// `preClose` will be handled next
+					close();
+				}
+			}
+		}
+	}
+
 	// $inspect("Modal dialog mounted, is visible:", visible).with(clog);
 </script>
 
@@ -156,27 +176,7 @@
 				close();
 			}
 		}}
-		onkeydown={async (e) => {
-			if (e.key === "Escape" && visible) {
-				// clog("on Escape keydown, preventing default and stopping propagation");
-
-				// do not allow built-in close on escape
-				e.preventDefault();
-				// do not bubble
-				e.stopPropagation();
-				// ???: do not allow additional onkeydown listeners on this dialog (should there be any...)
-				e.stopImmediatePropagation();
-
-				if (!noEscapeClose) {
-					// explicit false prevents close
-					let allowed = await preEscapeClose?.();
-					if (allowed !== false) {
-						// `preClose` will be handled next
-						close();
-					}
-				}
-			}
-		}}
+		onkeydown={_onEscapeKeydown}
 	>
 		<!-- svelte-ignore a11y_click_events_have_key_events -->
 		<!-- svelte-ignore a11y_no_static_element_interactions -->

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-44 Svelte 5 components with consistent API patterns. All use runes-based reactivity.
+44 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -79,45 +79,66 @@
 
 | Component | Purpose                                                                                   |
 | --------- | ----------------------------------------------------------------------------------------- |
-| Cart      | Shopping cart with quantity controls, pricing, summary; default/compact/readonly variants |
-| Checkout  | Multi-step checkout flow (13 sub-components: atomic + composite steps)                    |
+| Cart      | Shopping cart with quantity controls, pricing, summary; default/compact/summary variants |
+| Checkout  | Multi-step checkout flow (14 exported sub-components: atomic + composite steps)            |
 
 ---
 
 ## Checkout Components
 
-13 sub-components organized as atomic building blocks + composite step pages.
+14 exported sub-components organized as atomic building blocks + composite step pages.
+CSS is split into modular partials (`_*.css`) imported by `index.css`.
 
 ### Atomic Components
 
-| Component                 | Purpose                                                         | Key Props                                            |
-| ------------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
-| CheckoutProgress          | Step indicator with navigation                                  | `currentStep`, `steps`, `onNavigate`, `separator`    |
-| CheckoutOrderSummary      | Price totals display (subtotal, shipping, tax, discount, total) | `totals`, `formatPrice`, `row`, `extraRows`          |
-| CheckoutCartReview        | Readonly cart display with summary                              | `items`, `onEditCart`, `thumbnail`, `title`          |
-| CheckoutGuestForm         | Guest checkout form (email, name, phone, B2B fields)            | `formData`, `onSubmit`, `showB2bFields`, `fields`    |
-| CheckoutLoginForm         | Login form (email + password)                                   | `formData`, `onSubmit`, `onForgotPassword`, `footer` |
-| CheckoutAddressForm       | Address input fieldset                                          | `address`, `label`, `requiredFields`, `countryField` |
-| CheckoutDeliveryOptions   | Delivery method radio selection with free shipping logic        | `options`, `selectedId`, `onSelect`, `subtotal`      |
-| CheckoutOrderReview       | Full order review with edit callbacks per section               | `order`, `onEditItems`, `onEditShippingAddress`      |
-| CheckoutOrderConfirmation | Order success screen with details                               | `order`, `orderId`, `onContinueShopping`             |
+| Component                  | Purpose                                                         | Key Props                                                  |
+| -------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
+| CheckoutProgress           | Step indicator with navigation                                  | `currentStep`, `steps`, `onNavigate`, `separator`          |
+| CheckoutOrderSummary       | Price totals display (subtotal, shipping, tax, discount, total) | `totals`, `formatPrice`, `row`, `extraRows`                |
+| CheckoutCartReview         | Readonly cart display with summary                              | `items`, `onEditCart`, `thumbnail`, `title`                 |
+| CheckoutGuestForm          | Guest checkout form (email, name, phone, B2B fields)            | `formData`, `onSubmit`, `showB2bFields`, `fields`          |
+| CheckoutLoginForm          | Login form (email + password)                                   | `formData`, `onSubmit`, `onForgotPassword`, `footer`       |
+| CheckoutGuestOrLoginForm   | Composite guest/login with tabbed/stacked/single modes          | `guestForm`, `loginForm`, `formMode`, `activeTab`          |
+| CheckoutAddressForm        | Address input fieldset                                          | `address`, `label`, `requiredFields`, `countryField`       |
+| CheckoutDeliveryOptions    | Delivery method radio selection with free shipping logic        | `options`, `selectedId`, `onSelect`, `subtotal`            |
+| CheckoutOrderReview        | Full order review with edit callbacks per section               | `order`, `onEditItems`, `onEditShippingAddress`            |
+| CheckoutOrderConfirmation  | Order success screen with details                               | `order`, `orderId`, `onContinueShopping`                   |
+
+**Internal (not exported):** `CheckoutSectionHeader` — reusable section header with left/right layout.
 
 ### Composite Step Components
 
+All step components support `hideProgress?: boolean` to hide the built-in progress indicator (e.g. when rendered externally).
+
 | Component            | Purpose                                           | Combines                                                      |
 | -------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
-| CheckoutReviewStep   | Cart review + guest/login forms (2-column layout) | CartReview + GuestForm/LoginForm (tabbed/stacked/single mode) |
+| CheckoutReviewStep   | Cart review + guest/login forms (2-column layout) | CartReview + GuestOrLoginForm (tabbed/stacked/single mode)    |
 | CheckoutShippingStep | Shipping + billing addresses + delivery selection | AddressForm (×2) + DeliveryOptions + OrderSummary sidebar     |
 | CheckoutConfirmStep  | Order review + place order CTA                    | OrderReview + OrderSummary sidebar + validation errors        |
 | CheckoutCompleteStep | Order confirmation with loading/error states      | Progress + OrderConfirmation (or error/loading fallback)      |
 
+### CheckoutGuestOrLoginForm
+
+Composite component combining guest and login forms with multiple display modes:
+
+| FormMode       | Behavior                                                     |
+| -------------- | ------------------------------------------------------------ |
+| `"tabbed"`     | Pill-style tab switcher between guest/login (default)        |
+| `"stacked"`    | Both forms vertically stacked with "or" divider              |
+| `"guest-only"` | Only guest form                                              |
+| `"login-only"` | Only login form                                              |
+
+Key props: `guestForm`, `loginForm` (pass-through config objects), `activeTab` (bindable: `"guest"` | `"login"`), `formMode`, `heading`, `hLevel`.
+
+Exported type: `CheckoutFormMode` (`"guest-only" | "login-only" | "tabbed" | "stacked"`).
+
 ### Checkout Architecture
 
 - **i18n**: Full translation support via `t?: TranslateFn` on every component; 100+ default English keys
 - **Validation**: Built-in validators (`validateEmail`, `validateAddress`, `validateCustomerForm`, `validateLoginForm`)
 - **Factory helpers**: `createEmptyAddress()`, `createEmptyCustomerFormData()`, `createEmptyLoginFormData()`
 - **Price formatting**: `defaultFormatPrice(cents)` — all prices in smallest currency unit (cents)
-- **CSS tokens**: `--stuic-checkout-*` prefix; extensive design tokens in `Checkout/index.css`
+- **CSS tokens**: `--stuic-checkout-*` prefix; modular CSS partials (`_shared.css`, `_*.css`) in `Checkout/`
 - **Data types**: `CheckoutOrderData`, `CheckoutAddressData`, `CheckoutDeliveryOption`, `CheckoutOrderTotals`, etc.
 - **Snippet overrides**: Every component offers snippet props to replace default sections
 
@@ -270,5 +291,5 @@ Components use private CSS vars (`--_*`) set by intent/variant:
 | src/lib/components/Button/   | Reference implementation                     |
 | src/lib/components/Modal/    | Complex component example                    |
 | src/lib/components/Input/    | Form field patterns                          |
-| src/lib/components/Checkout/ | E-commerce checkout flow (13 sub-components) |
+| src/lib/components/Checkout/ | E-commerce checkout flow (14 exported sub-components) |
 | src/lib/index.ts             | All component exports                        |

package/docs/domains/utils.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-42 utility functions for common tasks. Organized by category.
+42 utility modules for common tasks. Organized by category.
 
 ---
 
@@ -35,12 +35,11 @@ theme.value = "dark";
 
 ## DOM Utilities
 
-| Util               | Purpose                               |
-| ------------------ | ------------------------------------- |
-| `qsa`              | querySelectorAll wrapper              |
-| `bodyScrollLocker` | Lock/unlock body scroll               |
-| `anchorName`       | Generate CSS anchor-positioning names |
-| `getId`            | Generate unique IDs                   |
+| Util               | Purpose                  |
+| ------------------ | ------------------------ |
+| `qsa`              | querySelectorAll wrapper |
+| `bodyScrollLocker` | Lock/unlock body scroll  |
+| `getId`            | Generate unique IDs      |
 
 ---
 
@@ -83,26 +82,23 @@ const search = debounce((query: string) => {
 
 ## Type Checks
 
-| Util            | Purpose                   |
-| --------------- | ------------------------- |
-| `isNullish`     | Check null/undefined      |
-| `isPlainObject` | Check plain object        |
-| `isImage`       | Check if file is image    |
-| `isBrowser`     | Check browser environment |
-| `isMac`         | Check macOS               |
+| Util        | Purpose                   |
+| ----------- | ------------------------- |
+| `isNullish` | Check null/undefined      |
+| `isImage`   | Check if file is image    |
+| `isBrowser` | Check browser environment |
+| `isMac`     | Check macOS               |
 
 ---
 
 ## Data Handling
 
-| Util                 | Purpose                 |
-| -------------------- | ----------------------- |
-| `maybeJsonParse`     | Safe JSON.parse         |
-| `maybeJsonStringify` | Safe JSON.stringify     |
-| `toInteger`          | Safe integer conversion |
-| `omit`               | Omit object keys        |
-| `pick`               | Pick object keys        |
-| `moveArrayItem`      | Reorder array items     |
+| Util                 | Purpose             |
+| -------------------- | ------------------- |
+| `maybeJsonParse`     | Safe JSON.parse     |
+| `maybeJsonStringify` | Safe JSON.stringify |
+| `omit`               | Omit object keys    |
+| `pick`               | Pick object keys    |
 
 ---
 
@@ -139,6 +135,28 @@ twMerge("px-4 py-2", "px-6"); // => "py-2 px-6"
 
 ---
 
+## Storage
+
+| Util                  | Purpose                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `StorageAbstraction`  | Unified class over localStorage/sessionStorage/memory      |
+| `MemoryStorage`       | In-memory storage fallback (SSR-safe)                      |
+| `localStorageValue`   | Non-reactive value backed by localStorage (get/set/remove) |
+| `sessionStorageValue` | Non-reactive value backed by sessionStorage                |
+| `memoryStorageValue`  | Non-reactive value backed by in-memory storage             |
+
+### Example: Storage Abstraction
+
+```ts
+import { StorageAbstraction } from "@marianmeres/stuic";
+
+const storage = new StorageAbstraction("local");
+storage.set("user", { name: "John" });
+storage.get("user"); // { name: 'John' }
+```
+
+---
+
 ## Design Tokens
 
 | Util                 | Purpose                      |
@@ -151,9 +169,10 @@ twMerge("px-4 py-2", "px-6"); // => "py-2 px-6"
 
 ## Key Files
 
-| File                                     | Purpose                    |
-| ---------------------------------------- | -------------------------- |
-| src/lib/utils/index.ts                   | All utility exports        |
-| src/lib/utils/tw-merge.ts                | Critical for class merging |
-| src/lib/utils/persistent-state.svelte.ts | Reactive storage pattern   |
-| src/lib/utils/design-tokens.ts           | Theme token types          |
+| File                                     | Purpose                                   |
+| ---------------------------------------- | ----------------------------------------- |
+| src/lib/utils/index.ts                   | All utility exports                       |
+| src/lib/utils/tw-merge.ts                | Critical for class merging                |
+| src/lib/utils/persistent-state.svelte.ts | Reactive storage pattern (runes-based)    |
+| src/lib/utils/storage-abstraction.ts     | Non-reactive storage (localStorage, etc.) |
+| src/lib/utils/design-tokens.ts           | Theme token types                         |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",
@@ -39,7 +39,7 @@
     "@marianmeres/icons-fns": "^5.0.0",
     "@marianmeres/random-human-readable": "^1.6.1",
     "@sveltejs/adapter-auto": "^4.0.0",
-    "@sveltejs/kit": "^2.51.0",
+    "@sveltejs/kit": "^2.52.0",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@tailwindcss/cli": "^4.1.18",
@@ -53,8 +53,8 @@
     "prettier": "^3.8.1",
     "prettier-plugin-svelte": "^3.4.1",
     "publint": "^0.3.17",
-    "svelte": "^5.50.3",
-    "svelte-check": "^4.3.6",
+    "svelte": "^5.51.1",
+    "svelte-check": "^4.4.0",
     "tailwindcss": "^4.1.18",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",