@marianmeres/stuic 3.9.0 → 3.10.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 36 UI components
+├── components/     # 37 UI components
 ├── actions/        # 12 Svelte actions
 ├── utils/          # 42 utility functions
 ├── themes/         # 26 theme definitions (.ts) + generated CSS (css/)
@@ -72,7 +72,7 @@ src/lib/
 - [Tasks](./docs/tasks.md) — Common procedures
 
 ### Domain Docs
-- [Components](./docs/domains/components.md) — 36 components, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 37 components, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [Actions](./docs/domains/actions.md) — 12 Svelte directives
 - [Utils](./docs/domains/utils.md) — 42 utility functions

package/API.md

@@ -323,6 +323,56 @@ Loading placeholder with animation.
 
 ---
 
+### E-commerce
+
+#### `Cart`
+
+Shopping cart component with quantity controls, pricing, and summary. Supports interactive (full cart), readonly (checkout summary), and compact (popover preview) modes.
+
+| 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 |
+| `noThumbnails` | `boolean` | `false` | Hide all thumbnails |
+| `readonly` | `boolean` | `false` | Hide interactive controls |
+| `loading` | `boolean` | `false` | Show loading skeleton |
+| `updatingItems` | `Set<string>` | `new Set()` | Item IDs currently being updated (reduced opacity) |
+| `t` | `TranslateFn` | built-in | Translation function for i18n |
+
+**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) |
+
+```svelte
+<Cart
+  {items}
+  formatPrice={(v) => `$${(v / 100).toFixed(2)}`}
+  onQuantityChange={handleQuantityChange}
+  onRemove={handleRemove}
+/>
+
+<!-- Readonly mode (checkout summary) -->
+<Cart {items} readonly formatPrice={(v) => `$${(v / 100).toFixed(2)}`} />
+
+<!-- Compact variant (for popovers) -->
+<Cart {items} variant="compact" formatPrice={(v) => `$${(v / 100).toFixed(2)}`}>
+  {#snippet footer({ total, itemCount })}
+    <a href="/cart">View Cart</a>
+  {/snippet}
+</Cart>
+```
+
+---
+
 ### Display
 
 #### `Avatar`
@@ -356,6 +406,39 @@ Image/content slider with navigation.
 
 Animated loading dots ("...").
 
+#### `DataTable`
+
+Responsive data table with paging, row selection, batch actions, and mobile card view.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `DataTableColumn<T>[]` | required | Column definitions |
+| `data` | `T[]` | required | Row data objects |
+| `getRowId` | `(row: T, index: number) => string \| number` | index | Unique row ID extractor |
+| `paging` | `PagingCalcResult` | — | Paging calculation from `@marianmeres/paging-store` |
+| `onPageChange` | `(offset: number) => void` | — | Page navigation callback |
+| `selectable` | `boolean` | `false` | Enable row selection checkboxes |
+| `selected` | `Set<string \| number>` | — | Bindable set of selected row IDs |
+| `selectOnRowClick` | `boolean` | `false` | Toggle selection on row click |
+| `onRowClick` | `(row: T, index: number) => void` | — | Row click callback |
+| `loading` | `boolean` | `false` | Show loading overlay |
+| `t` | `TranslateFn` | built-in | Translation function for i18n |
+
+**Snippets:** `cell`, `batchActions`, `empty`, `mobileRow`
+
+```svelte
+<DataTable
+  columns={[
+    { key: "name", label: "Name" },
+    { key: "email", label: "Email" },
+    { key: "role", label: "Role", align: "center" },
+  ]}
+  data={users}
+  selectable
+  bind:selected={selectedIds}
+/>
+```
+
 #### `ThemePreview`
 
 Theme color swatch preview.
@@ -886,6 +969,8 @@ import type {
 Naming pattern: `{ComponentName}Props`
 
 Additional exported types include:
+- `CartComponentItem`, `CartVariant` — Cart component types
+- `DataTableColumn` — DataTable column definition type
 - `FieldAsset`, `FieldAssetUrlObj`, `FieldAssetWithBlobUrl` — Asset field types
 - `FieldOption` — Option type for FieldOptions
 - `KeyValueEntry` — Entry type for FieldKeyValues
@@ -969,6 +1054,7 @@ Each component defines customization tokens. Override globally in `:root {}` or
 | Tooltip | `--stuic-tooltip-*` | `bg`, `text` |
 | Popover | `--stuic-popover-*` | `bg`, `text`, `border` |
 | Skeleton | `--stuic-skeleton-*` | `bg`, `bg-highlight`, `duration` |
+| Cart | `--stuic-cart-*` | `gap`, `item-padding`, `item-radius`, `item-border-color`, `item-bg`, `thumbnail-size`, `quantity-border-color`, `remove-color`, `summary-border-color`, `compact-max-height`, `transition` |
 
 ### CSS Variable Naming Convention
 

package/README.md

@@ -141,7 +141,10 @@ Notifications, AlertConfirmPrompt, DismissibleMessage, Progress, Spinner, Skelet
 CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
 
 ### Display & Utility
-Avatar, Carousel, AnimatedElipsis, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview
+Avatar, Carousel, AnimatedElipsis, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, DataTable
+
+### E-commerce
+Cart
 
 ## Actions
 

package/dist/components/Checkout/CheckoutAddressForm.svelte

@@ -0,0 +1,227 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { TranslateFn } from "../../types.js";
+	import type {
+		CheckoutAddressData,
+		CheckoutValidationError,
+	} from "./_internal/checkout-types.js";
+
+	export interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, "children"> {
+		/** Bindable address data. Default: createEmptyAddress() */
+		address?: CheckoutAddressData;
+
+		/**
+		 * Label prefix used for:
+		 * - Accessible field IDs (e.g., "shipping-name", "billing-street")
+		 * - Error field matching (errors with field "shipping.name" match when label="shipping")
+		 * Default: "address"
+		 */
+		label?: string;
+
+		/** External validation errors */
+		errors?: CheckoutValidationError[];
+
+		/** Which fields to display. All default to true. */
+		fields?: {
+			name?: boolean;
+			street?: boolean;
+			city?: boolean;
+			postal_code?: boolean;
+			country?: boolean;
+			phone?: boolean;
+		};
+
+		/**
+		 * Which fields are required (shown with * marker, included in built-in validation).
+		 * Default: ["name", "street", "city", "postal_code", "country"]
+		 */
+		requiredFields?: string[];
+
+		/**
+		 * Override the country field with a custom selector.
+		 * When provided, replaces the default text input for country.
+		 */
+		countryField?: Snippet<
+			[
+				{
+					/** Current country value */
+					value: string;
+					/** Called when country changes */
+					onchange: (value: string) => void;
+					/** Error message for this field (if any) */
+					error?: string;
+					/** Field label text */
+					label: string;
+					/** HTML id attribute for the input */
+					id: string;
+				},
+			]
+		>;
+
+		t?: TranslateFn;
+		unstyled?: boolean;
+		class?: string;
+		el?: HTMLFieldSetElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { t_default } from "./_internal/checkout-i18n-defaults.js";
+	import { createEmptyAddress } from "./_internal/checkout-utils.js";
+	import FieldInput from "../Input/FieldInput.svelte";
+
+	const DEFAULT_REQUIRED = ["name", "street", "city", "postal_code", "country"];
+
+	let {
+		address = $bindable(createEmptyAddress()),
+		label = "address",
+		errors: externalErrors = [],
+		fields,
+		requiredFields = DEFAULT_REQUIRED,
+		countryField,
+		t: tProp,
+		unstyled = false,
+		class: classProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	let t = $derived(tProp ?? t_default);
+
+	function fieldError(field: string): string | undefined {
+		return externalErrors.find((e) => e.field.endsWith(`.${field}`))?.message;
+	}
+
+	function isRequired(field: string): boolean {
+		return requiredFields.includes(field);
+	}
+
+	let _class = $derived(
+		unstyled ? classProp : twMerge("stuic-checkout-address", classProp)
+	);
+</script>
+
+<fieldset bind:this={el} class={_class} {...rest}>
+	<!-- Name (full width, block label) -->
+	{#if fields?.name !== false}
+		<FieldInput
+			bind:value={address.name}
+			label={t("checkout.address.name_label")}
+			placeholder={t("checkout.address.name_placeholder")}
+			required={isRequired("name")}
+			name="{label}-name"
+			id="{label}-name"
+			labelLeftBreakpoint={0}
+			validate={{
+				customValidator(val) {
+					return fieldError("name") || "";
+				},
+			}}
+		/>
+	{/if}
+
+	<!-- Street (full width, block label) -->
+	{#if fields?.street !== false}
+		<FieldInput
+			bind:value={address.street}
+			label={t("checkout.address.street_label")}
+			placeholder={t("checkout.address.street_placeholder")}
+			required={isRequired("street")}
+			name="{label}-street"
+			id="{label}-street"
+			labelLeftBreakpoint={0}
+			validate={{
+				customValidator(val) {
+					return fieldError("street") || "";
+				},
+			}}
+		/>
+	{/if}
+
+	<!-- City + Postal Code (2-column grid) -->
+	{#if fields?.city !== false || fields?.postal_code !== false}
+		<div class={unstyled ? undefined : "stuic-checkout-address-row"}>
+			{#if fields?.city !== false}
+				<FieldInput
+					bind:value={address.city}
+					label={t("checkout.address.city_label")}
+					placeholder={t("checkout.address.city_placeholder")}
+					required={isRequired("city")}
+					name="{label}-city"
+					id="{label}-city"
+					validate={{
+						customValidator(val) {
+							return fieldError("city") || "";
+						},
+					}}
+				/>
+			{/if}
+			{#if fields?.postal_code !== false}
+				<FieldInput
+					bind:value={address.postal_code}
+					label={t("checkout.address.postal_code_label")}
+					placeholder={t("checkout.address.postal_code_placeholder")}
+					required={isRequired("postal_code")}
+					name="{label}-postal_code"
+					id="{label}-postal_code"
+					validate={{
+						customValidator(val) {
+							return fieldError("postal_code") || "";
+						},
+					}}
+				/>
+			{/if}
+		</div>
+	{/if}
+
+	<!-- Country (full width, block label) -->
+	{#if fields?.country !== false}
+		{#if countryField}
+			{@render countryField({
+				value: address.country,
+				onchange: (v) => {
+					address.country = v;
+				},
+				error: fieldError("country"),
+				label: t("checkout.address.country_label"),
+				id: `${label}-country`,
+			})}
+		{:else}
+			<FieldInput
+				bind:value={address.country}
+				label={t("checkout.address.country_label")}
+				placeholder={t("checkout.address.country_placeholder")}
+				required={isRequired("country")}
+				name="{label}-country"
+				id="{label}-country"
+				labelLeftBreakpoint={0}
+				validate={{
+					customValidator(val) {
+						return fieldError("country") || "";
+					},
+				}}
+			/>
+		{/if}
+	{/if}
+
+	<!-- Phone (full width, block label) -->
+	{#if fields?.phone !== false}
+		<FieldInput
+			bind:value={address.phone}
+			label={t("checkout.address.phone_label")}
+			type="tel"
+			placeholder={t("checkout.address.phone_placeholder")}
+			required={isRequired("phone")}
+			name="{label}-phone"
+			id="{label}-phone"
+			labelLeftBreakpoint={0}
+			validate={{
+				customValidator(val) {
+					return fieldError("phone") || "";
+				},
+			}}
+		/>
+	{/if}
+</fieldset>

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

@@ -0,0 +1,56 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import type { TranslateFn } from "../../types.js";
+import type { CheckoutAddressData, CheckoutValidationError } from "./_internal/checkout-types.js";
+export interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, "children"> {
+    /** Bindable address data. Default: createEmptyAddress() */
+    address?: CheckoutAddressData;
+    /**
+     * Label prefix used for:
+     * - Accessible field IDs (e.g., "shipping-name", "billing-street")
+     * - Error field matching (errors with field "shipping.name" match when label="shipping")
+     * Default: "address"
+     */
+    label?: string;
+    /** External validation errors */
+    errors?: CheckoutValidationError[];
+    /** Which fields to display. All default to true. */
+    fields?: {
+        name?: boolean;
+        street?: boolean;
+        city?: boolean;
+        postal_code?: boolean;
+        country?: boolean;
+        phone?: boolean;
+    };
+    /**
+     * Which fields are required (shown with * marker, included in built-in validation).
+     * Default: ["name", "street", "city", "postal_code", "country"]
+     */
+    requiredFields?: string[];
+    /**
+     * Override the country field with a custom selector.
+     * When provided, replaces the default text input for country.
+     */
+    countryField?: Snippet<[
+        {
+            /** Current country value */
+            value: string;
+            /** Called when country changes */
+            onchange: (value: string) => void;
+            /** Error message for this field (if any) */
+            error?: string;
+            /** Field label text */
+            label: string;
+            /** HTML id attribute for the input */
+            id: string;
+        }
+    ]>;
+    t?: TranslateFn;
+    unstyled?: boolean;
+    class?: string;
+    el?: HTMLFieldSetElement;
+}
+declare const CheckoutAddressForm: import("svelte").Component<Props, {}, "address" | "el">;
+type CheckoutAddressForm = ReturnType<typeof CheckoutAddressForm>;
+export default CheckoutAddressForm;

package/dist/components/Checkout/CheckoutCartReview.svelte

@@ -0,0 +1,132 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { TranslateFn } from "../../types.js";
+	import type { CartComponentItem } from "../Cart/Cart.svelte";
+
+	export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> {
+		/** Cart items in stuic CartComponentItem format */
+		items: CartComponentItem[];
+
+		/**
+		 * Format a number (in cents) to a display string.
+		 * Default: defaultFormatPrice (cents / 100, 2 decimal places)
+		 */
+		formatPrice?: (value: number) => string;
+
+		/**
+		 * Called when "Edit Cart" is clicked.
+		 * If undefined, the edit action is not rendered.
+		 */
+		onEditCart?: () => void;
+
+		/** Override thumbnail rendering (passed through to Cart) */
+		thumbnail?: Snippet<[{ item: CartComponentItem }]>;
+
+		/**
+		 * Override the Cart's summary section.
+		 * Passed through to Cart's `summary` snippet.
+		 */
+		summary?: Snippet<
+			[{
+				items: CartComponentItem[];
+				total: number;
+				itemCount: number;
+				formatPrice: (v: number) => string;
+			}]
+		>;
+
+		/** Override the title (default: "Order Summary") */
+		title?: Snippet | string;
+
+		/** Override the edit action */
+		editAction?: Snippet<[{ onEditCart?: () => void }]>;
+
+		t?: TranslateFn;
+		unstyled?: boolean;
+		class?: string;
+		el?: HTMLDivElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { t_default } from "./_internal/checkout-i18n-defaults.js";
+	import { defaultFormatPrice } from "./_internal/checkout-utils.js";
+	import Cart from "../Cart/Cart.svelte";
+	import Button from "../Button/Button.svelte";
+
+	let {
+		items,
+		formatPrice: formatPriceProp,
+		onEditCart,
+		thumbnail,
+		summary: summaryProp,
+		title: titleProp,
+		editAction,
+		t: tProp,
+		unstyled = false,
+		class: classProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	let t = $derived(tProp ?? t_default);
+	let fp = $derived(formatPriceProp ?? defaultFormatPrice);
+
+	let total = $derived(items.reduce((sum, item) => sum + item.lineTotal, 0));
+	let itemCount = $derived(items.reduce((sum, item) => sum + item.quantity, 0));
+
+	let _class = $derived(
+		unstyled ? classProp : twMerge("stuic-checkout-cart-review", classProp)
+	);
+</script>
+
+<div bind:this={el} class={_class} {...rest}>
+	<!-- Header bar -->
+	<div class={unstyled ? undefined : "stuic-checkout-cart-review-header"}>
+		{#if typeof titleProp === "function"}
+			{@render titleProp()}
+		{:else}
+			<h3 class={unstyled ? undefined : "stuic-checkout-cart-review-title"}>
+				{typeof titleProp === "string" ? titleProp : t("checkout.cart.title")}
+			</h3>
+		{/if}
+
+		{#if editAction}
+			{@render editAction({ onEditCart })}
+		{:else if onEditCart}
+			<Button variant="outline" size="sm" onclick={onEditCart}>
+				{t("checkout.cart.edit")}
+			</Button>
+		{/if}
+	</div>
+
+	<!-- Cart (readonly) -->
+	<Cart
+		{items}
+		readonly
+		formatPrice={fp}
+		{thumbnail}
+		t={tProp}
+		{unstyled}
+	>
+		{#snippet summary({ items: _items, total: _total, itemCount: _itemCount, formatPrice: _fp })}
+			{#if summaryProp}
+				{@render summaryProp({ items: _items, total: _total, itemCount: _itemCount, formatPrice: _fp })}
+			{:else}
+				<div class={unstyled ? undefined : "stuic-checkout-cart-review-summary"}>
+					<span>
+						{t("checkout.cart.subtotal")}
+						({_itemCount === 1
+							? t("checkout.cart.item_count_1")
+							: t("checkout.cart.item_count_n", { count: _itemCount })})
+					</span>
+					<span class={unstyled ? undefined : "stuic-checkout-cart-review-summary-total"}>
+						{_fp(_total)}
+					</span>
+				</div>
+			{/if}
+		{/snippet}
+	</Cart>
+</div>

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

@@ -0,0 +1,47 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import type { TranslateFn } from "../../types.js";
+import type { CartComponentItem } from "../Cart/Cart.svelte";
+export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> {
+    /** Cart items in stuic CartComponentItem format */
+    items: CartComponentItem[];
+    /**
+     * Format a number (in cents) to a display string.
+     * Default: defaultFormatPrice (cents / 100, 2 decimal places)
+     */
+    formatPrice?: (value: number) => string;
+    /**
+     * Called when "Edit Cart" is clicked.
+     * If undefined, the edit action is not rendered.
+     */
+    onEditCart?: () => void;
+    /** Override thumbnail rendering (passed through to Cart) */
+    thumbnail?: Snippet<[{
+        item: CartComponentItem;
+    }]>;
+    /**
+     * Override the Cart's summary section.
+     * Passed through to Cart's `summary` snippet.
+     */
+    summary?: Snippet<[
+        {
+            items: CartComponentItem[];
+            total: number;
+            itemCount: number;
+            formatPrice: (v: number) => string;
+        }
+    ]>;
+    /** Override the title (default: "Order Summary") */
+    title?: Snippet | string;
+    /** Override the edit action */
+    editAction?: Snippet<[{
+        onEditCart?: () => void;
+    }]>;
+    t?: TranslateFn;
+    unstyled?: boolean;
+    class?: string;
+    el?: HTMLDivElement;
+}
+declare const CheckoutCartReview: import("svelte").Component<Props, {}, "el">;
+type CheckoutCartReview = ReturnType<typeof CheckoutCartReview>;
+export default CheckoutCartReview;