@marianmeres/stuic 3.8.1 → 3.9.0

package/AGENTS.md

@@ -94,3 +94,16 @@ src/lib/
 | `src/lib/themes/css/stone.css` | Default theme (generated) |
 | `src/lib/components/Button/` | Reference component |
 | `scripts/generate-theme.ts` | CLI: `pnpm run build:theme:all` |
+
+---
+
+## Svelte MCP Server
+
+You have access to the Svelte MCP server providing comprehensive Svelte 5 documentation.
+This is a **component library**, not a SvelteKit application — skip SvelteKit-specific guidance (routing, load functions, hooks, adapters, etc.).
+
+### Available Tools
+1. **list-sections**: Call FIRST to discover available documentation sections.
+2. **get-documentation**: Fetch full docs for specific sections (runes, lifecycle, snippets, etc.).
+3. **svelte-autofixer**: Validate Svelte code for correctness — always run before finalizing component changes.
+4. **playground-link**: Generate a Svelte Playground link — only after user confirms they want one.

package/dist/components/Cart/Cart.svelte

@@ -0,0 +1,513 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { TranslateFn } from "../../types.js";
+	import { isPlainObject } from "../../utils/is-plain-object.js";
+	import { replaceMap } from "../../utils/replace-map.js";
+
+	// i18n ready
+	function t_default(
+		k: string,
+		values: false | null | undefined | Record<string, string | number> = null,
+		fallback: string | boolean = "",
+		_i18nSpanWrap: boolean = true
+	) {
+		const m: Record<string, string> = {
+			empty_cart: "Your cart is empty",
+			unit_price_each: "{price} each",
+			quantity_label: "Qty: {quantity}",
+			remove_item: "Remove",
+			total_label: "Total",
+			item_count_1: "1 item",
+			item_count_n: "{count} items",
+			decrease_quantity: "Decrease quantity",
+			increase_quantity: "Increase quantity",
+		};
+		let out = m[k] ?? fallback ?? k;
+		return isPlainObject(values)
+			? replaceMap(out, values as any, {
+					preSearchKeyTransform: (k) => `{${k}}`,
+				})
+			: out;
+	}
+
+	/** A single item in the cart */
+	export interface CartComponentItem {
+		/** Unique item identifier */
+		id: string;
+		/** Product name (displayed, used as link text) */
+		name: string;
+		/** Link to product page */
+		href?: string;
+		/** Short description (shown below name if provided) */
+		description?: string;
+		/** Image URL for product thumbnail */
+		thumbnailSrc?: string;
+		/** Image alt text (defaults to name) */
+		thumbnailAlt?: string;
+		/** Price per unit (cents integer recommended) */
+		unitPrice: number;
+		/** Current quantity */
+		quantity: number;
+		/** Pre-computed total for this line */
+		lineTotal: number;
+		/** Unit label: "pcs", "kg", etc. */
+		unit?: string;
+		/** Increment/decrement step (default 1) */
+		quantityStep?: number;
+		/** Floor for decrement (default 0) */
+		minQuantity?: number;
+		/** Ceiling for increment */
+		maxQuantity?: number;
+	}
+
+	/** Layout variant */
+	export type CartVariant = "default" | "compact";
+
+	export interface Props
+		extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+		/** Cart items to display */
+		items: CartComponentItem[];
+
+		/** Layout variant. "compact" = smaller thumbnails, tighter spacing, scrollable, implicitly readonly */
+		variant?: CartVariant;
+
+		/** Format a numeric price for display. Default: (v) => (v / 100).toFixed(2) */
+		formatPrice?: (value: number) => string;
+
+		/** Called when quantity changes (not called in readonly/compact mode) */
+		onQuantityChange?: (id: string, newQuantity: number) => void;
+		/** Called when remove is clicked (not called in readonly/compact mode) */
+		onRemove?: (id: string) => void;
+
+		/** Hide all thumbnails */
+		noThumbnails?: boolean;
+		/** Hide all interactive controls — used for checkout summary */
+		readonly?: boolean;
+		/** Show loading skeleton instead of content */
+		loading?: boolean;
+		/** Set of item IDs currently being updated (shown with reduced opacity) */
+		updatingItems?: Set<string>;
+
+		/** Override thumbnail rendering */
+		thumbnail?: Snippet<[{ item: CartComponentItem }]>;
+		/** Override entire item row rendering */
+		itemRow?: Snippet<
+			[{
+				item: CartComponentItem;
+				isUpdating: boolean;
+				readonly: boolean;
+				formatPrice: (v: number) => string;
+			}]
+		>;
+		/** Override/extend summary section */
+		summary?: Snippet<
+			[{
+				items: CartComponentItem[];
+				total: number;
+				itemCount: number;
+				formatPrice: (v: number) => string;
+			}]
+		>;
+		/** Custom empty state */
+		empty?: Snippet;
+		/** Content after the summary (e.g., CTA buttons) */
+		footer?: Snippet<
+			[{
+				items: CartComponentItem[];
+				total: number;
+				itemCount: number;
+			}]
+		>;
+
+		/** Optional translate function */
+		t?: TranslateFn;
+
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes for the root container */
+		class?: string;
+		/** Bindable element reference */
+		el?: HTMLDivElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { Breakpoint } from "../../utils/breakpoint.svelte.js";
+	import Skeleton from "../Skeleton/Skeleton.svelte";
+
+	let {
+		items,
+		variant = "default",
+		formatPrice = (v: number) => (v / 100).toFixed(2),
+		onQuantityChange,
+		onRemove,
+		noThumbnails = false,
+		readonly: readonlyProp = false,
+		loading = false,
+		updatingItems = new Set<string>(),
+		thumbnail,
+		itemRow,
+		summary,
+		empty,
+		footer,
+		t = t_default,
+		unstyled = false,
+		class: classProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	// --- Responsive ---
+	const bp = Breakpoint.instance;
+	let isDesktop = $derived(bp.md);
+	let isCompact = $derived(variant === "compact");
+	let isReadonly = $derived(readonlyProp || isCompact);
+
+	// --- Derived ---
+	let total = $derived(items.reduce((sum, i) => sum + i.lineTotal, 0));
+	let itemCount = $derived(items.reduce((sum, i) => sum + i.quantity, 0));
+
+	// --- Inline editing ---
+	let editingItemId = $state<string | null>(null);
+
+	function handleQuantityInputCommit(
+		itemId: string,
+		currentQty: number,
+		inputValue: string
+	) {
+		editingItemId = null;
+		const newQty = parseInt(inputValue, 10);
+		if (!isNaN(newQty) && newQty !== currentQty && newQty >= 0) {
+			onQuantityChange?.(itemId, newQty);
+		}
+	}
+
+	function decrementQuantity(item: CartComponentItem) {
+		const step = item.quantityStep ?? 1;
+		const min = item.minQuantity ?? 0;
+		const newQty = Math.max(min, item.quantity - step);
+		if (newQty !== item.quantity) {
+			onQuantityChange?.(item.id, newQty);
+		}
+	}
+
+	function incrementQuantity(item: CartComponentItem) {
+		const step = item.quantityStep ?? 1;
+		const newQty = item.quantity + step;
+		if (item.maxQuantity != null && newQty > item.maxQuantity) return;
+		onQuantityChange?.(item.id, newQty);
+	}
+
+	// --- Auto-focus action (avoids a11y autofocus warning) ---
+	function autoFocusAndSelect(node: HTMLInputElement) {
+		node.focus();
+		node.select();
+	}
+
+	// --- CSS ---
+	let rootClass = $derived(
+		unstyled ? classProp : twMerge("stuic-cart", classProp)
+	);
+</script>
+
+<!-- Root container -->
+<div
+	bind:this={el}
+	class={rootClass}
+	data-variant={!unstyled ? variant : undefined}
+	data-loading={!unstyled && loading ? "" : undefined}
+	data-readonly={!unstyled && isReadonly ? "" : undefined}
+	{...rest}
+>
+	{#if loading}
+		<!-- Loading skeleton -->
+		<div class={!unstyled ? "stuic-cart-skeleton" : undefined}>
+			{#each [1, 2, 3] as _, i (i)}
+				<div class={!unstyled ? "stuic-cart-skeleton-item" : undefined}>
+					<Skeleton
+						variant="rectangle"
+						width={isCompact ? "3rem" : "4rem"}
+						height={isCompact ? "3rem" : "4rem"}
+						rounded="0.375rem"
+					/>
+					<div class={!unstyled ? "stuic-cart-skeleton-content" : undefined}>
+						<Skeleton height="1.25rem" width="60%" />
+						<Skeleton height="0.875rem" width="30%" />
+						{#if !isReadonly}
+							<Skeleton height="2rem" width="8rem" class="mt-2" />
+						{/if}
+					</div>
+					<Skeleton height="1.5rem" width="4rem" />
+				</div>
+			{/each}
+		</div>
+	{:else if items.length === 0}
+		<!-- Empty state -->
+		<div class={!unstyled ? "stuic-cart-empty" : undefined}>
+			{#if empty}
+				{@render empty()}
+			{:else}
+				<p>{t("empty_cart")}</p>
+			{/if}
+		</div>
+	{:else}
+		<!-- Item list -->
+		<div
+			class={!unstyled ? "stuic-cart-items" : undefined}
+			data-variant={!unstyled ? variant : undefined}
+		>
+			{#each items as item (item.id)}
+				{@const isUpdating = updatingItems.has(item.id)}
+				{#if itemRow}
+					{@render itemRow({
+						item,
+						isUpdating,
+						readonly: isReadonly,
+						formatPrice,
+					})}
+				{:else}
+					<div
+						class={!unstyled ? "stuic-cart-item" : undefined}
+						data-variant={!unstyled ? variant : undefined}
+						data-updating={!unstyled && isUpdating ? "" : undefined}
+					>
+						<!-- Thumbnail -->
+						{#if !noThumbnails}
+							<div class={!unstyled ? "stuic-cart-item-thumbnail" : undefined}
+								data-variant={!unstyled ? variant : undefined}
+							>
+								{#if thumbnail}
+									{@render thumbnail({ item })}
+								{:else if item.thumbnailSrc}
+									{#if item.href}
+										<a href={item.href}>
+											<img
+												src={item.thumbnailSrc}
+												alt={item.thumbnailAlt ?? item.name}
+												class={!unstyled ? "stuic-cart-item-image" : undefined}
+											/>
+										</a>
+									{:else}
+										<img
+											src={item.thumbnailSrc}
+											alt={item.thumbnailAlt ?? item.name}
+											class={!unstyled ? "stuic-cart-item-image" : undefined}
+										/>
+									{/if}
+								{:else}
+									<div
+										class={!unstyled ? "stuic-cart-item-placeholder" : undefined}
+									></div>
+								{/if}
+							</div>
+						{/if}
+
+						<!-- Info section -->
+						<div class={!unstyled ? "stuic-cart-item-info" : undefined}>
+							{#if item.href}
+								<a
+									href={item.href}
+									class={!unstyled
+										? "stuic-cart-item-name"
+										: undefined}
+								>
+									{item.name}
+								</a>
+							{:else}
+								<span
+									class={!unstyled
+										? "stuic-cart-item-name"
+										: undefined}
+								>
+									{item.name}
+								</span>
+							{/if}
+
+							{#if item.description && !isCompact}
+								<div
+									class={!unstyled
+										? "stuic-cart-item-description"
+										: undefined}
+								>
+									{item.description}
+								</div>
+							{/if}
+
+							<div
+								class={!unstyled
+									? "stuic-cart-item-unit-price"
+									: undefined}
+							>
+								{t("unit_price_each", {
+									price: formatPrice(item.unitPrice),
+								})}
+							</div>
+
+							{#if isReadonly}
+								<!-- Readonly quantity display -->
+								<div
+									class={!unstyled
+										? "stuic-cart-item-quantity-readonly"
+										: undefined}
+								>
+									{t("quantity_label", {
+										quantity: item.quantity,
+									})}{#if item.unit}&nbsp;{item.unit}{/if}
+								</div>
+							{:else}
+								<!-- Interactive quantity controls -->
+								<div
+									class={!unstyled
+										? "stuic-cart-item-controls"
+										: undefined}
+								>
+									<div
+										class={!unstyled
+											? "stuic-cart-quantity"
+											: undefined}
+									>
+										<button
+											type="button"
+											class={!unstyled
+												? "stuic-cart-quantity-button"
+												: undefined}
+											disabled={isUpdating ||
+												item.quantity <=
+													(item.minQuantity ?? 0)}
+											onclick={() =>
+												decrementQuantity(item)}
+											aria-label={t(
+												"decrease_quantity"
+											)}
+										>
+											&minus;
+										</button>
+										{#if editingItemId === item.id}
+											<input
+												type="number"
+												min={item.minQuantity ?? 0}
+												max={item.maxQuantity}
+												step={item.quantityStep ?? 1}
+												class={!unstyled
+													? "stuic-cart-quantity-input"
+													: undefined}
+												value={item.quantity}
+												onblur={(e) =>
+													handleQuantityInputCommit(
+														item.id,
+														item.quantity,
+														e.currentTarget.value
+													)}
+												onkeydown={(e) => {
+													if (e.key === "Enter") {
+														handleQuantityInputCommit(
+															item.id,
+															item.quantity,
+															e.currentTarget.value
+														);
+													} else if (
+														e.key === "Escape"
+													) {
+														editingItemId = null;
+													}
+												}}
+												use:autoFocusAndSelect
+											/>
+										{:else}
+											<button
+												type="button"
+												class={!unstyled
+													? "stuic-cart-quantity-value"
+													: undefined}
+												onclick={() =>
+													(editingItemId = item.id)}
+												disabled={isUpdating}
+											>
+												{item.quantity}
+											</button>
+										{/if}
+										<button
+											type="button"
+											class={!unstyled
+												? "stuic-cart-quantity-button"
+												: undefined}
+											disabled={isUpdating ||
+												(item.maxQuantity != null &&
+													item.quantity >=
+														item.maxQuantity)}
+											onclick={() =>
+												incrementQuantity(item)}
+											aria-label={t(
+												"increase_quantity"
+											)}
+										>
+											+
+										</button>
+									</div>
+									{#if item.unit}
+										<span
+											class={!unstyled
+												? "stuic-cart-item-unit"
+												: undefined}
+										>
+											{item.unit}
+										</span>
+									{/if}
+									<button
+										type="button"
+										class={!unstyled
+											? "stuic-cart-remove"
+											: undefined}
+										disabled={isUpdating}
+										onclick={() => onRemove?.(item.id)}
+									>
+										{t("remove_item")}
+									</button>
+								</div>
+							{/if}
+						</div>
+
+						<!-- Line total -->
+						<div
+							class={!unstyled
+								? "stuic-cart-item-total"
+								: undefined}
+						>
+							{formatPrice(item.lineTotal)}
+						</div>
+					</div>
+				{/if}
+			{/each}
+		</div>
+
+		<!-- Summary -->
+		{#if summary}
+			{@render summary({ items, total, itemCount, formatPrice })}
+		{:else}
+			<div class={!unstyled ? "stuic-cart-summary" : undefined}
+				data-variant={!unstyled ? variant : undefined}
+			>
+				<span class={!unstyled ? "stuic-cart-summary-label" : undefined}>
+					{t("total_label")}
+					({itemCount === 1
+						? t("item_count_1")
+						: t("item_count_n", { count: itemCount })})
+				</span>
+				<span class={!unstyled ? "stuic-cart-summary-total" : undefined}
+					data-variant={!unstyled ? variant : undefined}
+				>
+					{formatPrice(total)}
+				</span>
+			</div>
+		{/if}
+
+		<!-- Footer -->
+		{#if footer}
+			<div class={!unstyled ? "stuic-cart-footer" : undefined}>
+				{@render footer({ items, total, itemCount })}
+			</div>
+		{/if}
+	{/if}
+</div>

package/dist/components/Cart/Cart.svelte.d.ts

@@ -0,0 +1,97 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import type { TranslateFn } from "../../types.js";
+/** A single item in the cart */
+export interface CartComponentItem {
+    /** Unique item identifier */
+    id: string;
+    /** Product name (displayed, used as link text) */
+    name: string;
+    /** Link to product page */
+    href?: string;
+    /** Short description (shown below name if provided) */
+    description?: string;
+    /** Image URL for product thumbnail */
+    thumbnailSrc?: string;
+    /** Image alt text (defaults to name) */
+    thumbnailAlt?: string;
+    /** Price per unit (cents integer recommended) */
+    unitPrice: number;
+    /** Current quantity */
+    quantity: number;
+    /** Pre-computed total for this line */
+    lineTotal: number;
+    /** Unit label: "pcs", "kg", etc. */
+    unit?: string;
+    /** Increment/decrement step (default 1) */
+    quantityStep?: number;
+    /** Floor for decrement (default 0) */
+    minQuantity?: number;
+    /** Ceiling for increment */
+    maxQuantity?: number;
+}
+/** Layout variant */
+export type CartVariant = "default" | "compact";
+export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Cart items to display */
+    items: CartComponentItem[];
+    /** Layout variant. "compact" = smaller thumbnails, tighter spacing, scrollable, implicitly readonly */
+    variant?: CartVariant;
+    /** Format a numeric price for display. Default: (v) => (v / 100).toFixed(2) */
+    formatPrice?: (value: number) => string;
+    /** Called when quantity changes (not called in readonly/compact mode) */
+    onQuantityChange?: (id: string, newQuantity: number) => void;
+    /** Called when remove is clicked (not called in readonly/compact mode) */
+    onRemove?: (id: string) => void;
+    /** Hide all thumbnails */
+    noThumbnails?: boolean;
+    /** Hide all interactive controls — used for checkout summary */
+    readonly?: boolean;
+    /** Show loading skeleton instead of content */
+    loading?: boolean;
+    /** Set of item IDs currently being updated (shown with reduced opacity) */
+    updatingItems?: Set<string>;
+    /** Override thumbnail rendering */
+    thumbnail?: Snippet<[{
+        item: CartComponentItem;
+    }]>;
+    /** Override entire item row rendering */
+    itemRow?: Snippet<[
+        {
+            item: CartComponentItem;
+            isUpdating: boolean;
+            readonly: boolean;
+            formatPrice: (v: number) => string;
+        }
+    ]>;
+    /** Override/extend summary section */
+    summary?: Snippet<[
+        {
+            items: CartComponentItem[];
+            total: number;
+            itemCount: number;
+            formatPrice: (v: number) => string;
+        }
+    ]>;
+    /** Custom empty state */
+    empty?: Snippet;
+    /** Content after the summary (e.g., CTA buttons) */
+    footer?: Snippet<[
+        {
+            items: CartComponentItem[];
+            total: number;
+            itemCount: number;
+        }
+    ]>;
+    /** Optional translate function */
+    t?: TranslateFn;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes for the root container */
+    class?: string;
+    /** Bindable element reference */
+    el?: HTMLDivElement;
+}
+declare const Cart: import("svelte").Component<Props, {}, "el">;
+type Cart = ReturnType<typeof Cart>;
+export default Cart;

package/dist/components/Cart/README.md

@@ -0,0 +1,185 @@
+# Cart
+
+A reusable shopping cart component for displaying cart items with quantity controls,
+pricing, and a summary section. Supports interactive (full cart) and readonly (checkout
+summary) modes, plus a compact variant suitable for popover previews.
+
+## Usage
+
+```svelte
+<script>
+  import { Cart } from "@marianmeres/stuic";
+
+  let items = [
+    {
+      id: "prod-1",
+      name: "Widget Pro",
+      href: "/products/widget-pro",
+      thumbnailSrc: "/images/widget.jpg",
+      unitPrice: 1999, // cents
+      quantity: 2,
+      lineTotal: 3998,
+    },
+    {
+      id: "prod-2",
+      name: "Gadget Lite",
+      unitPrice: 499,
+      quantity: 1,
+      lineTotal: 499,
+    },
+  ];
+
+  function handleQuantityChange(id, newQuantity) {
+    // sync with server, then update items
+  }
+
+  function handleRemove(id) {
+    // remove from server, then update items
+  }
+</script>
+
+<Cart
+  {items}
+  formatPrice={(v) => `$${(v / 100).toFixed(2)}`}
+  onQuantityChange={handleQuantityChange}
+  onRemove={handleRemove}
+/>
+```
+
+### Readonly Mode (checkout summary)
+
+```svelte
+<Cart {items} readonly formatPrice={(v) => `$${(v / 100).toFixed(2)}`} />
+```
+
+### Compact Variant (for popovers)
+
+```svelte
+<Cart
+  {items}
+  variant="compact"
+  formatPrice={(v) => `$${(v / 100).toFixed(2)}`}
+>
+  {#snippet footer({ total, itemCount })}
+    <div class="flex gap-2">
+      <a href="/cart">View Cart</a>
+      <a href="/checkout">Checkout</a>
+    </div>
+  {/snippet}
+</Cart>
+```
+
+### Integration with @marianmeres/ecsuite
+
+```svelte
+<script>
+  import { Cart } from "@marianmeres/stuic";
+  import type { EnrichedCartItem } from "@marianmeres/ecsuite";
+  import type { CartComponentItem } from "@marianmeres/stuic";
+
+  // Map from ecsuite's EnrichedCartItem to Cart's CartComponentItem
+  function toCartItems(enriched: EnrichedCartItem[]): CartComponentItem[] {
+    return enriched.map((ei) => ({
+      id: ei.product_id,
+      name: ei.product?.name ?? "Unknown Product",
+      href: ei.product?.slug ? `/products/${ei.product.slug}` : undefined,
+      description: ei.product?.short_description,
+      thumbnailSrc: getProductImage(ei.product), // your image helper
+      unitPrice: ei.product?.price ?? 0,
+      quantity: ei.quantity,
+      lineTotal: ei.lineTotal,
+    }));
+  }
+
+  // Use with ecsuite's CartManager
+  async function handleQuantityChange(id: string, qty: number) {
+    await suite.cart.updateItemQuantity(id, qty);
+    items = toCartItems(await suite.cart.getEnrichedItems(suite.product));
+  }
+
+  async function handleRemove(id: string) {
+    await suite.cart.removeItem(id);
+    items = toCartItems(await suite.cart.getEnrichedItems(suite.product));
+  }
+</script>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `CartComponentItem[]` | required | Cart items to display |
+| `variant` | `"default" \| "compact"` | `"default"` | Layout variant. Compact is smaller, scrollable, implicitly 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 |
+| `readonly` | `boolean` | `false` | Hide interactive controls |
+| `loading` | `boolean` | `false` | Show loading skeleton |
+| `updatingItems` | `Set<string>` | `new Set()` | Item IDs currently being updated |
+| `t` | `TranslateFn` | built-in | Translation function |
+| `unstyled` | `boolean` | `false` | Skip all default styling |
+| `class` | `string` | — | Additional CSS classes |
+| `el` | `HTMLDivElement` | — | Bindable element reference |
+
+### CartComponentItem
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | yes | Unique identifier |
+| `name` | `string` | yes | Product name |
+| `href` | `string` | — | Link to product page |
+| `description` | `string` | — | Short description |
+| `thumbnailSrc` | `string` | — | Image URL |
+| `thumbnailAlt` | `string` | — | Image alt (defaults to name) |
+| `unitPrice` | `number` | yes | Price per unit (cents) |
+| `quantity` | `number` | yes | Current quantity |
+| `lineTotal` | `number` | yes | Pre-computed line total |
+| `unit` | `string` | — | Unit label ("pcs", "kg") |
+| `quantityStep` | `number` | — | +/- step (default 1) |
+| `minQuantity` | `number` | — | Min quantity (default 0) |
+| `maxQuantity` | `number` | — | Max quantity |
+
+### Snippets
+
+| Snippet | Params | Description |
+|---------|--------|-------------|
+| `thumbnail` | `{ item }` | Override thumbnail rendering |
+| `itemRow` | `{ item, isUpdating, readonly, formatPrice }` | Override entire item row |
+| `summary` | `{ items, total, itemCount, formatPrice }` | Override summary section |
+| `empty` | — | Custom empty state |
+| `footer` | `{ items, total, itemCount }` | Content after summary (CTAs) |
+
+## CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--stuic-cart-gap` | `1rem` | Gap between items |
+| `--stuic-cart-item-padding` | `1rem` | Item card padding |
+| `--stuic-cart-item-radius` | `var(--radius-lg)` | Item border radius |
+| `--stuic-cart-item-border-color` | `var(--stuic-color-border)` | Item border color |
+| `--stuic-cart-item-bg` | `var(--stuic-color-background)` | Item background |
+| `--stuic-cart-thumbnail-size` | `4rem` | Thumbnail dimensions |
+| `--stuic-cart-thumbnail-size-sm` | `3rem` | Compact thumbnail dimensions |
+| `--stuic-cart-thumbnail-radius` | `var(--radius-md)` | Thumbnail border radius |
+| `--stuic-cart-thumbnail-bg` | `var(--stuic-color-muted)` | Thumbnail placeholder bg |
+| `--stuic-cart-quantity-border-color` | `var(--stuic-color-border)` | Quantity control border |
+| `--stuic-cart-quantity-button-size` | `2rem` | Quantity button dimensions |
+| `--stuic-cart-remove-color` | `var(--stuic-color-destructive)` | Remove button color |
+| `--stuic-cart-summary-border-color` | `var(--stuic-color-border)` | Summary separator |
+| `--stuic-cart-compact-max-height` | `12rem` | Compact variant scroll height |
+| `--stuic-cart-compact-item-padding` | `0.5rem` | Compact item padding |
+| `--stuic-cart-transition` | `150ms` | Transition duration |
+
+## Translation Keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `empty_cart` | "Your cart is empty" | Empty state text |
+| `unit_price_each` | "{price} each" | Unit price label |
+| `quantity_label` | "Qty: {quantity}" | Readonly quantity display |
+| `remove_item` | "Remove" | Remove button text |
+| `total_label` | "Total" | Summary label |
+| `item_count_1` | "1 item" | Singular item count |
+| `item_count_n` | "{count} items" | Plural item count |
+| `decrease_quantity` | "Decrease quantity" | Aria label for − button |
+| `increase_quantity` | "Increase quantity" | Aria label for + button |

package/dist/components/Cart/index.css

@@ -0,0 +1,409 @@
+/* ============================================================================
+   CART COMPONENT TOKENS
+   Override globally: :root { --stuic-cart-item-padding: 0.5rem; }
+   Override locally:  <Cart style="--stuic-cart-item-padding: 0.5rem;">
+   ============================================================================ */
+
+:root {
+	/* Layout */
+	--stuic-cart-gap: 1rem;
+	--stuic-cart-transition: 150ms;
+
+	/* Item card */
+	--stuic-cart-item-padding: 1rem;
+	--stuic-cart-item-radius: var(--radius-lg);
+	--stuic-cart-item-border-color: var(--stuic-color-border);
+	--stuic-cart-item-bg: var(--stuic-color-background);
+
+	/* Thumbnail */
+	--stuic-cart-thumbnail-size: 4rem;
+	--stuic-cart-thumbnail-size-sm: 3rem;
+	--stuic-cart-thumbnail-radius: var(--radius-md);
+	--stuic-cart-thumbnail-bg: var(--stuic-color-muted);
+
+	/* Quantity controls */
+	--stuic-cart-quantity-border-color: var(--stuic-color-border);
+	--stuic-cart-quantity-button-size: 2rem;
+	--stuic-cart-quantity-button-bg-hover: var(--stuic-color-muted);
+	--stuic-cart-quantity-input-bg: var(--stuic-color-input);
+
+	/* Remove button */
+	--stuic-cart-remove-color: var(--stuic-color-destructive);
+	--stuic-cart-remove-color-hover: var(--stuic-color-destructive-hover);
+
+	/* Summary */
+	--stuic-cart-summary-border-color: var(--stuic-color-border);
+
+	/* Compact variant */
+	--stuic-cart-compact-max-height: 12rem;
+	--stuic-cart-compact-item-padding: 0.5rem;
+}
+
+@layer components {
+	/* ============================================================================
+	   BASE STYLES
+	   ============================================================================ */
+
+	.stuic-cart {
+		display: flex;
+		flex-direction: column;
+	}
+
+	/* ============================================================================
+	   SKELETON (loading state)
+	   ============================================================================ */
+
+	.stuic-cart-skeleton {
+		display: flex;
+		flex-direction: column;
+		gap: var(--stuic-cart-gap);
+	}
+
+	.stuic-cart-skeleton-item {
+		display: flex;
+		align-items: flex-start;
+		gap: 1rem;
+		padding: var(--stuic-cart-item-padding);
+		border: 1px solid var(--stuic-cart-item-border-color);
+		border-radius: var(--stuic-cart-item-radius);
+		background: var(--stuic-cart-item-bg);
+	}
+
+	.stuic-cart-skeleton-content {
+		flex: 1;
+		min-width: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 0.5rem;
+	}
+
+	/* ============================================================================
+	   EMPTY STATE
+	   ============================================================================ */
+
+	.stuic-cart-empty {
+		text-align: center;
+		padding: 3rem 1rem;
+		opacity: 0.7;
+	}
+
+	/* ============================================================================
+	   ITEMS LIST
+	   ============================================================================ */
+
+	.stuic-cart-items {
+		display: flex;
+		flex-direction: column;
+		gap: var(--stuic-cart-gap);
+	}
+
+	.stuic-cart-items[data-variant="compact"] {
+		max-height: var(--stuic-cart-compact-max-height);
+		overflow-y: auto;
+		gap: 0;
+	}
+
+	/* ============================================================================
+	   ITEM CARD
+	   ============================================================================ */
+
+	.stuic-cart-item {
+		display: flex;
+		align-items: flex-start;
+		gap: 1rem;
+		padding: var(--stuic-cart-item-padding);
+		border: 1px solid var(--stuic-cart-item-border-color);
+		border-radius: var(--stuic-cart-item-radius);
+		background: var(--stuic-cart-item-bg);
+		transition: opacity var(--stuic-cart-transition);
+	}
+
+	.stuic-cart-item[data-variant="compact"] {
+		padding: var(--stuic-cart-compact-item-padding);
+		border-radius: 0;
+		border-left: 0;
+		border-right: 0;
+		border-bottom: 0;
+	}
+
+	.stuic-cart-item[data-variant="compact"]:first-child {
+		border-top: 0;
+	}
+
+	.stuic-cart-item[data-updating] {
+		opacity: 0.5;
+		pointer-events: none;
+	}
+
+	/* ============================================================================
+	   THUMBNAIL
+	   ============================================================================ */
+
+	.stuic-cart-item-thumbnail {
+		flex-shrink: 0;
+		width: var(--stuic-cart-thumbnail-size);
+		height: var(--stuic-cart-thumbnail-size);
+		border-radius: var(--stuic-cart-thumbnail-radius);
+		background: var(--stuic-cart-thumbnail-bg);
+		overflow: hidden;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+
+	.stuic-cart-item-thumbnail[data-variant="compact"] {
+		width: var(--stuic-cart-thumbnail-size-sm);
+		height: var(--stuic-cart-thumbnail-size-sm);
+	}
+
+	.stuic-cart-item-image {
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+	}
+
+	.stuic-cart-item-placeholder {
+		width: 100%;
+		height: 100%;
+		background: var(--stuic-cart-thumbnail-bg);
+		opacity: 0.3;
+	}
+
+	/* ============================================================================
+	   ITEM INFO
+	   ============================================================================ */
+
+	.stuic-cart-item-info {
+		flex: 1;
+		min-width: 0;
+	}
+
+	a.stuic-cart-item-name {
+		font-weight: var(--font-weight-medium);
+		display: block;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		text-decoration: none;
+		color: inherit;
+	}
+
+	a.stuic-cart-item-name:hover {
+		text-decoration: underline;
+	}
+
+	span.stuic-cart-item-name {
+		font-weight: var(--font-weight-medium);
+		display: block;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.stuic-cart-item-description {
+		font-size: var(--text-sm);
+		opacity: 0.6;
+		margin-top: 0.125rem;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.stuic-cart-item-unit-price {
+		font-size: var(--text-sm);
+		opacity: 0.6;
+		margin-top: 0.25rem;
+	}
+
+	.stuic-cart-item-quantity-readonly {
+		font-size: var(--text-sm);
+		opacity: 0.6;
+		margin-top: 0.25rem;
+	}
+
+	/* ============================================================================
+	   QUANTITY CONTROLS
+	   ============================================================================ */
+
+	.stuic-cart-item-controls {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		margin-top: 0.75rem;
+		flex-wrap: wrap;
+	}
+
+	.stuic-cart-quantity {
+		display: inline-flex;
+		align-items: center;
+		border: 1px solid var(--stuic-cart-quantity-border-color);
+		border-radius: var(--radius-md);
+		overflow: hidden;
+	}
+
+	.stuic-cart-quantity-button {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: var(--stuic-cart-quantity-button-size);
+		height: var(--stuic-cart-quantity-button-size);
+		background: transparent;
+		border: none;
+		cursor: pointer;
+		font-size: 1rem;
+		line-height: 1;
+		color: inherit;
+		transition: background var(--stuic-cart-transition);
+		-webkit-tap-highlight-color: transparent;
+	}
+
+	.stuic-cart-quantity-button:hover:not(:disabled) {
+		background: var(--stuic-cart-quantity-button-bg-hover);
+	}
+
+	.stuic-cart-quantity-button:disabled {
+		opacity: 0.3;
+		cursor: not-allowed;
+	}
+
+	.stuic-cart-quantity-value {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		min-width: 2.5rem;
+		height: var(--stuic-cart-quantity-button-size);
+		background: transparent;
+		border: none;
+		cursor: text;
+		font-size: var(--text-sm);
+		font-weight: var(--font-weight-medium);
+		text-align: center;
+		color: inherit;
+		transition: background var(--stuic-cart-transition);
+		-webkit-tap-highlight-color: transparent;
+	}
+
+	.stuic-cart-quantity-value:hover:not(:disabled) {
+		background: var(--stuic-cart-quantity-input-bg);
+	}
+
+	.stuic-cart-quantity-value:disabled {
+		cursor: default;
+	}
+
+	.stuic-cart-quantity-input {
+		width: 3rem;
+		height: var(--stuic-cart-quantity-button-size);
+		text-align: center;
+		font-size: var(--text-sm);
+		font-weight: var(--font-weight-medium);
+		border: none;
+		background: var(--stuic-cart-quantity-input-bg);
+		color: inherit;
+		outline: none;
+		-moz-appearance: textfield;
+	}
+
+	.stuic-cart-quantity-input::-webkit-inner-spin-button,
+	.stuic-cart-quantity-input::-webkit-outer-spin-button {
+		-webkit-appearance: none;
+		margin: 0;
+	}
+
+	.stuic-cart-item-unit {
+		font-size: var(--text-sm);
+		opacity: 0.6;
+	}
+
+	/* ============================================================================
+	   REMOVE BUTTON
+	   ============================================================================ */
+
+	.stuic-cart-remove {
+		background: none;
+		border: none;
+		cursor: pointer;
+		font-size: var(--text-sm);
+		color: var(--stuic-cart-remove-color);
+		padding: 0;
+		-webkit-tap-highlight-color: transparent;
+		transition: color var(--stuic-cart-transition);
+	}
+
+	.stuic-cart-remove:hover:not(:disabled) {
+		text-decoration: underline;
+		color: var(--stuic-cart-remove-color-hover);
+	}
+
+	.stuic-cart-remove:disabled {
+		opacity: 0.3;
+		cursor: not-allowed;
+	}
+
+	/* ============================================================================
+	   LINE TOTAL
+	   ============================================================================ */
+
+	.stuic-cart-item-total {
+		flex-shrink: 0;
+		text-align: right;
+		font-weight: var(--font-weight-bold);
+		font-size: var(--text-lg);
+		white-space: nowrap;
+	}
+
+	.stuic-cart-item[data-variant="compact"] .stuic-cart-item-total {
+		font-size: var(--text-base);
+	}
+
+	/* ============================================================================
+	   SUMMARY
+	   ============================================================================ */
+
+	.stuic-cart-summary {
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		margin-top: 1.5rem;
+		padding-top: 1.5rem;
+		border-top: 1px solid var(--stuic-cart-summary-border-color);
+	}
+
+	.stuic-cart-summary[data-variant="compact"] {
+		margin-top: 0;
+		padding: var(--stuic-cart-compact-item-padding);
+		padding-top: calc(var(--stuic-cart-compact-item-padding) + 0.25rem);
+		border-top: 1px solid var(--stuic-cart-summary-border-color);
+	}
+
+	.stuic-cart-summary-label {
+		font-size: var(--text-lg);
+	}
+
+	.stuic-cart-summary[data-variant="compact"] .stuic-cart-summary-label {
+		font-size: var(--text-base);
+	}
+
+	.stuic-cart-summary-total {
+		font-size: var(--text-2xl);
+		font-weight: var(--font-weight-bold);
+	}
+
+	.stuic-cart-summary-total[data-variant="compact"] {
+		font-size: var(--text-lg);
+	}
+
+	/* ============================================================================
+	   FOOTER
+	   ============================================================================ */
+
+	.stuic-cart-footer {
+		margin-top: 1.5rem;
+	}
+
+	.stuic-cart-summary[data-variant="compact"] + .stuic-cart-footer {
+		margin-top: 0;
+		padding: var(--stuic-cart-compact-item-padding);
+		border-top: 1px solid var(--stuic-cart-summary-border-color);
+	}
+}

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

@@ -0,0 +1 @@
+export { default as Cart, type Props as CartProps, type CartComponentItem, type CartVariant, } from "./Cart.svelte";

package/dist/components/Cart/index.js

@@ -0,0 +1 @@
+export { default as Cart, } from "./Cart.svelte";

package/dist/components/DataTable/DataTable.svelte

@@ -23,7 +23,11 @@
 			select_row: "Select row",
 		};
 		let out = m[k] ?? fallback ?? k;
-		return isPlainObject(values) ? replaceMap(out, values as any) : out;
+		return isPlainObject(values)
+			? replaceMap(out, values as any, {
+					preSearchKeyTransform: (k) => `{${k}}`,
+				})
+			: out;
 	}
 
 	export interface DataTableColumn<T = Record<string, any>> {

package/dist/components/DataTable/index.css

@@ -7,6 +7,7 @@
 /* prettier-ignore */
 :root {
 	/* Structure */
+	--stuic-data-table-layout: fixed;
 	--stuic-data-table-radius: var(--radius-md);
 	--stuic-data-table-border-width: 1px;
 	--stuic-data-table-border-color: var(--stuic-color-border);
@@ -83,7 +84,7 @@
 	.stuic-data-table table {
 		width: 100%;
 		border-collapse: collapse;
-		table-layout: fixed;
+		table-layout: var(--stuic-data-table-layout);
 	}
 
 	/* ============================================================================

package/dist/components/DropdownMenu/DropdownMenu.svelte

@@ -605,17 +605,23 @@
 		isOpen ? BodyScroll.lock() : BodyScroll.unlock();
 	});
 
-	// Click outside handler
-	onClickOutside(
+	// Click outside handler — only active when open (prevents stale refs on destroy)
+	const _clickOutside = onClickOutside(
 		() => wrapperEl,
 		() => {
 			if (closeOnClickOutside && isOpen) {
 				isOpen = false;
 				triggerEl?.focus();
 			}
-		}
+		},
+		{ immediate: false }
 	);
 
+	$effect(() => {
+		if (isOpen && wrapperEl) _clickOutside.start();
+		else _clickOutside.stop();
+	});
+
 	// Helper to generate item IDs
 	function itemId(id: string | number): string {
 		return `${dropdownId}-item-${id}`;

package/dist/components/ModalDialog/ModalDialog.svelte

@@ -106,11 +106,18 @@
 		};
 	}
 
-	onClickOutside(
+	// Click outside handler — only active when visible (prevents stale refs on destroy)
+	const _clickOutside = onClickOutside(
 		() => box,
-		() => !noClickOutsideClose && close()
+		() => !noClickOutsideClose && close(),
+		{ immediate: false }
 	);
 
+	$effect(() => {
+		if (visible && box) _clickOutside.start();
+		else _clickOutside.stop();
+	});
+
 	$effect(() => {
 		// noop if we're undefined ($effect runs immediately as onMount)
 		if (visible === undefined || noScrollLock) return;

package/dist/index.css

@@ -30,6 +30,7 @@ In practice:
 @import "./components/Button/index.css";
 @import "./components/ButtonGroupRadio/index.css";
 @import "./components/Collapsible/index.css";
+@import "./components/Cart/index.css";
 @import "./components/Carousel/index.css";
 @import "./components/CommandMenu/index.css";
 @import "./components/DataTable/index.css";

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export * from "./components/Avatar/index.js";
 export * from "./components/Backdrop/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";
+export * from "./components/Cart/index.js";
 export * from "./components/Carousel/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";

package/dist/index.js

@@ -30,6 +30,7 @@ export * from "./components/Avatar/index.js";
 export * from "./components/Backdrop/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";
+export * from "./components/Cart/index.js";
 export * from "./components/Carousel/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",
@@ -46,14 +46,14 @@
     "@tailwindcss/forms": "^0.5.11",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.1.18",
-    "@types/node": "^25.2.1",
+    "@types/node": "^25.2.2",
     "dotenv": "^16.6.1",
     "eslint": "^9.39.2",
     "globals": "^16.5.0",
     "prettier": "^3.8.1",
     "prettier-plugin-svelte": "^3.4.1",
     "publint": "^0.3.17",
-    "svelte": "^5.49.2",
+    "svelte": "^5.50.0",
     "svelte-check": "^4.3.6",
     "tailwindcss": "^4.1.18",
     "tsx": "^4.21.0",