@marianmeres/stuic 3.10.1 → 3.11.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 37 UI components
+├── components/     # 39 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) — 37 components, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 38 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

@@ -371,6 +371,223 @@ Shopping cart component with quantity controls, pricing, and summary. Supports i
 </Cart>
 ```
 
+#### Checkout
+
+Multi-step checkout flow with 13 sub-components: 9 atomic building blocks and 4 composite step pages.
+
+**Atomic Components:**
+
+##### `CheckoutProgress`
+
+Step indicator with navigation for past steps.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `CheckoutStep[]` | 4-step flow | Step definitions |
+| `currentStep` | `string` | required | Active step ID |
+| `onNavigate` | `(step: CheckoutStep) => void` | — | Past step click callback |
+| `separator` | `Snippet \| string` | `"→"` | Step separator |
+| `t` | `TranslateFn` | built-in | Translation function |
+
+##### `CheckoutOrderSummary`
+
+Price totals display (subtotal, shipping, tax, discount, total).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `totals` | `CheckoutOrderTotals` | required | Price totals |
+| `hasShipping` | `boolean` | `true` | Show shipping row |
+| `formatPrice` | `(value: number) => string` | `defaultFormatPrice` | Price formatter |
+| `row` | `Snippet` | — | Custom row rendering |
+| `extraRows` | `Snippet` | — | Extra content before total |
+
+##### `CheckoutCartReview`
+
+Readonly cart display with summary.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `CartComponentItem[]` | required | Cart items |
+| `formatPrice` | `(value: number) => string` | `defaultFormatPrice` | Price formatter |
+| `onEditCart` | `() => void` | — | Edit cart callback |
+| `thumbnail` | `Snippet` | — | Custom thumbnail |
+| `title` | `Snippet \| string` | `"Order Summary"` | Header title |
+
+##### `CheckoutGuestForm`
+
+Guest checkout form with email, name, phone, and optional B2B fields.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `formData` | `CheckoutCustomerFormData` | empty | Bindable form data |
+| `onSubmit` | `(data: CheckoutCustomerFormData) => void` | required | Submit callback |
+| `isSubmitting` | `boolean` | `false` | Disables CTA |
+| `errors` | `CheckoutValidationError[]` | `[]` | Server validation errors |
+| `showB2bFields` | `boolean` | `true` | Show B2B section |
+| `fields` | `object` | all visible | Field visibility overrides |
+| `validate` | `(data) => CheckoutValidationError[]` | — | Custom validator |
+
+##### `CheckoutLoginForm`
+
+Login form with email and password.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `formData` | `CheckoutLoginFormData` | empty | Bindable login data |
+| `onSubmit` | `(data: CheckoutLoginFormData) => void` | required | Submit callback |
+| `isSubmitting` | `boolean` | `false` | Disables CTA |
+| `errors` | `CheckoutValidationError[]` | `[]` | Field errors |
+| `error` | `string` | — | General error message |
+| `onForgotPassword` | `() => void` | — | Forgot password callback |
+| `footer` | `Snippet` | — | Content below form |
+
+##### `CheckoutAddressForm`
+
+Address input fieldset with configurable required fields.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `address` | `CheckoutAddressData` | empty | Bindable address data |
+| `label` | `string` | `"address"` | Prefix for field IDs |
+| `errors` | `CheckoutValidationError[]` | `[]` | Validation errors |
+| `requiredFields` | `string[]` | name, street, city, postal_code, country | Required fields |
+| `countryField` | `Snippet` | — | Custom country field (replaces text input) |
+
+##### `CheckoutDeliveryOptions`
+
+Delivery method radio selection with free shipping threshold logic.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `CheckoutDeliveryOption[]` | required | Available delivery options |
+| `selectedId` | `string` | — | Bindable selected option ID |
+| `onSelect` | `(optionId: string) => void` | — | Selection callback |
+| `subtotal` | `number` | `0` | Order subtotal (for free shipping calc) |
+| `isUpdating` | `boolean` | `false` | Reduced opacity during API calls |
+| `formatPrice` | `(value: number) => string` | `defaultFormatPrice` | Price formatter |
+| `option` | `Snippet` | — | Custom option card |
+
+##### `CheckoutOrderReview`
+
+Full order review display with per-section edit callbacks.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `order` | `CheckoutOrderData` | required | Order data |
+| `formatPrice` | `(value: number) => string` | `defaultFormatPrice` | Price formatter |
+| `onEditItems` | `() => void` | — | Edit items callback |
+| `onEditShippingAddress` | `() => void` | — | Edit shipping callback |
+| `onEditBillingAddress` | `() => void` | — | Edit billing callback |
+| `onEditDelivery` | `() => void` | — | Edit delivery callback |
+
+##### `CheckoutOrderConfirmation`
+
+Order success screen with details and continue shopping CTA.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `order` | `CheckoutOrderData` | required | Completed order |
+| `orderId` | `string` | required | Order ID for display |
+| `emailSent` | `boolean` | `false` | Show email confirmation |
+| `formatPrice` | `(value: number) => string` | `defaultFormatPrice` | Price formatter |
+| `onContinueShopping` | `() => void` | — | Continue shopping callback |
+
+**Composite Step Components:**
+
+##### `CheckoutReviewStep`
+
+Cart review + guest/login forms in 2-column layout.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `CartComponentItem[]` | required | Cart items |
+| `guestForm` | `object` | — | Guest form config (`formData`, `onSubmit`, `isSubmitting`, `errors`) |
+| `loginForm` | `object` | — | Login form config (`formData`, `onSubmit`, `isSubmitting`, `errors`, `onForgotPassword`) |
+| `formMode` | `"guest-only" \| "login-only" \| "tabbed" \| "stacked"` | `"tabbed"` | Form display mode |
+| `onEditCart` | `() => void` | — | Edit cart callback |
+| `formatPrice` | `(v: number) => string` | `defaultFormatPrice` | Price formatter |
+| `leftColumn` | `Snippet` | — | Override left column |
+| `rightColumn` | `Snippet` | — | Override right column |
+
+##### `CheckoutShippingStep`
+
+Shipping/billing addresses + delivery selection with sidebar summary.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `order` | `CheckoutOrderData` | required | Order data for totals |
+| `deliveryOptions` | `CheckoutDeliveryOption[]` | required | Available delivery options |
+| `shippingAddress` | `CheckoutAddressData` | — | Bindable shipping address |
+| `billingAddress` | `CheckoutAddressData` | — | Bindable billing address |
+| `billingSameAsShipping` | `boolean` | `true` | Bindable toggle |
+| `selectedDeliveryId` | `string` | — | Bindable delivery selection |
+| `onContinue` | `() => void` | — | Continue callback |
+| `onBack` | `() => void` | — | Back callback |
+| `countryField` | `Snippet` | — | Custom country field |
+
+##### `CheckoutConfirmStep`
+
+Order review + place order CTA with sidebar summary.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `order` | `CheckoutOrderData` | required | Order to confirm |
+| `validationErrors` | `CheckoutValidationError[]` | `[]` | Validation errors |
+| `isValid` | `boolean` | `true` | Enable/disable place order |
+| `isSubmitting` | `boolean` | `false` | Processing state |
+| `onPlaceOrder` | `() => void` | — | Place order callback |
+| `onBack` | `() => void` | — | Back callback |
+| `onEditItems` | `() => void` | — | Edit items callback |
+| `onEditShippingAddress` | `() => void` | — | Edit shipping callback |
+
+##### `CheckoutCompleteStep`
+
+Order confirmation with loading/error/success states.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `order` | `CheckoutOrderData` | required | Completed order |
+| `orderId` | `string` | required | Order ID |
+| `emailSent` | `boolean` | `false` | Email confirmation flag |
+| `isLoading` | `boolean` | `false` | Show loading skeleton |
+| `error` | `string \| null` | — | Error message |
+| `onContinueShopping` | `() => void` | — | Continue shopping callback |
+| `onReturnToCheckout` | `() => void` | — | Return callback (error state) |
+
+All composite step components also accept `currentStep`, `steps`, `onStepNavigate` (for CheckoutProgress), and `t` (TranslateFn).
+
+**Checkout Utilities:**
+
+```ts
+import {
+  defaultFormatPrice,      // (cents: number) => string — "12.99"
+  validateEmail,           // (email, t) => string | null
+  validateAddress,         // (address, prefix, t) => CheckoutValidationError[]
+  validateCustomerForm,    // (data, t) => CheckoutValidationError[]
+  validateLoginForm,       // (data, t) => CheckoutValidationError[]
+  createEmptyAddress,      // () => CheckoutAddressData
+  createEmptyCustomerFormData,  // () => CheckoutCustomerFormData
+  createEmptyLoginFormData,     // () => CheckoutLoginFormData
+} from "@marianmeres/stuic";
+```
+
+**Checkout Types:**
+
+```ts
+import type {
+  CheckoutStep,
+  CheckoutAddressData,
+  CheckoutCustomerFormData,
+  CheckoutLoginFormData,
+  CheckoutOrderLineItem,
+  CheckoutOrderTotals,
+  CheckoutDeliveryOption,
+  CheckoutDeliverySnapshot,
+  CheckoutOrderData,
+  CheckoutValidationError,
+} from "@marianmeres/stuic";
+```
+
 ---
 
 ### Display
@@ -406,6 +623,32 @@ Image/content slider with navigation.
 
 Animated loading dots ("...").
 
+#### `IconSwap`
+
+Swap visibility between N states with opacity transitions. Commonly used for hamburger/X icon toggle, but supports any content.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `states` | `Array<string \| Snippet>` | required | Array of visual states (HTML strings or Snippets) |
+| `active` | `number` | `0` | Index of the currently visible state (bindable) |
+| `duration` | `number` | `300` | Transition duration in ms |
+| `easing` | `string` | `"ease"` | CSS transition-timing-function |
+| `stateClass` | `string` | — | Additional CSS classes for each state wrapper |
+
+**CSS Variables:** `--stuic-icon-swap-duration`, `--stuic-icon-swap-easing`
+
+```svelte
+<script>
+  import { IconSwap } from "@marianmeres/stuic";
+  import { iconMenu, iconX } from "@marianmeres/stuic";
+  let isOpen = $state(false);
+</script>
+
+<button onclick={() => (isOpen = !isOpen)}>
+  <IconSwap active={isOpen ? 1 : 0} states={[iconMenu(), iconX()]} />
+</button>
+```
+
 #### `DataTable`
 
 Responsive data table with paging, row selection, batch actions, and mobile card view.
@@ -970,6 +1213,7 @@ Naming pattern: `{ComponentName}Props`
 
 Additional exported types include:
 - `CartComponentItem`, `CartVariant` — Cart component types
+- `CheckoutStep`, `CheckoutAddressData`, `CheckoutCustomerFormData`, `CheckoutLoginFormData`, `CheckoutOrderLineItem`, `CheckoutOrderTotals`, `CheckoutDeliveryOption`, `CheckoutDeliverySnapshot`, `CheckoutOrderData`, `CheckoutValidationError` — Checkout types
 - `DataTableColumn` — DataTable column definition type
 - `FieldAsset`, `FieldAssetUrlObj`, `FieldAssetWithBlobUrl` — Asset field types
 - `FieldOption` — Option type for FieldOptions
@@ -1055,6 +1299,7 @@ Each component defines customization tokens. Override globally in `:root {}` or
 | 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` |
+| Checkout | `--stuic-checkout-*` | `input-border`, `input-bg`, `input-focus-ring`, `input-radius`, `card-border`, `card-bg`, `card-radius`, `step-gap`, `progress-*`, `summary-*`, `guest-*`, `login-*`, `address-*`, `delivery-*`, `review-*`, `confirmation-*` |
 
 ### CSS Variable Naming Convention
 

package/README.md

@@ -144,7 +144,7 @@ CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
 Avatar, Carousel, AnimatedElipsis, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, DataTable
 
 ### E-commerce
-Cart
+Cart, Checkout (CheckoutProgress, CheckoutOrderSummary, CheckoutCartReview, CheckoutGuestForm, CheckoutLoginForm, CheckoutAddressForm, CheckoutDeliveryOptions, CheckoutOrderReview, CheckoutOrderConfirmation, CheckoutReviewStep, CheckoutShippingStep, CheckoutConfirmStep, CheckoutCompleteStep)
 
 ## Actions
 

package/dist/actions/resizable-width.svelte.d.ts

@@ -7,6 +7,8 @@ export interface ResizableWidthOptions {
     min?: number;
     max?: number;
     units?: "px" | "%";
+    /** Reverses handle position (left instead of right) and drag direction */
+    reverse?: boolean;
     key?: string | number | null | undefined;
     storage?: "local" | "session";
     handleClass?: string;
@@ -21,7 +23,8 @@ export interface ResizableWidthOptions {
 /**
  * A Svelte action that makes an element's width resizable via drag handle.
  *
- * Adds a draggable handle to the right edge of the element. Supports mouse and touch input.
+ * Adds a draggable handle to the right (or left with `reverse`) edge of the element.
+ * Supports mouse and touch input.
  * Optionally persists the width to localStorage/sessionStorage.
  *
  * Features:

package/dist/actions/resizable-width.svelte.js

@@ -3,7 +3,8 @@ import { twMerge } from "../utils/tw-merge.js";
 /**
  * A Svelte action that makes an element's width resizable via drag handle.
  *
- * Adds a draggable handle to the right edge of the element. Supports mouse and touch input.
+ * Adds a draggable handle to the right (or left with `reverse`) edge of the element.
+ * Supports mouse and touch input.
  * Optionally persists the width to localStorage/sessionStorage.
  *
  * Features:
@@ -43,9 +44,9 @@ import { twMerge } from "../utils/tw-merge.js";
  * ```
  */
 export function resizableWidth(el, fn) {
-    const DEFAULT_HANDLE_CLS = [
+    const HANDLE_CLS_BASE = [
         "group",
-        "absolute top-0 right-0 bottom-0",
+        "absolute top-0 bottom-0",
         "w-[1px]",
         "bg-black/20 hover:bg-black/30",
         "dark:bg-white/10 dark:hover:bg-white/20",
@@ -61,7 +62,7 @@ export function resizableWidth(el, fn) {
         "transition-colors duration-200",
         "touch-none cursor-ew-resize",
     ].join(" ");
-    function create_handle(el, handleClass, handleDragClass) {
+    function create_handle(el, handleClass, handleDragClass, reverse) {
         const handle = document.createElement("div");
         handle.setAttribute("data-handle", "true");
         const dragHandle = document.createElement("div");
@@ -69,11 +70,12 @@ export function resizableWidth(el, fn) {
         handle.appendChild(dragHandle);
         el.appendChild(handle);
         //
-        handle.classList.add(...twMerge(DEFAULT_HANDLE_CLS, handleClass).split(" "));
+        const positionCls = reverse ? "left-0" : "right-0";
+        handle.classList.add(...twMerge(HANDLE_CLS_BASE, positionCls, handleClass).split(" "));
         return handle;
     }
     $effect(() => {
-        const { enabled = true, initial: initialValue = 0, min = 0, max = 0, units = "px", key, storage = "session", handleClass = "", handleDragClass = "", onResize, debug, } = fn?.() || {};
+        const { enabled = true, initial: initialValue = 0, min = 0, max = 0, units = "px", reverse = false, key, storage = "session", handleClass = "", handleDragClass = "", onResize, debug, } = fn?.() || {};
         let initial = initialValue;
         const _debug = (...args) => debug?.("[resizable-width]", ...args);
         _debug("$effect");
@@ -86,7 +88,7 @@ export function resizableWidth(el, fn) {
         let startWidth = 0;
         let containerW = undefined;
         //
-        const handle = create_handle(el, handleClass, handleDragClass);
+        const handle = create_handle(el, handleClass, handleDragClass, reverse);
         const container = el.parentElement;
         // do we have a storage? if so, adjust the initial value...
         const initialBackup = initial;
@@ -149,7 +151,7 @@ export function resizableWidth(el, fn) {
             //
             const clientX = "touches" in e ? e.touches[0].clientX : e.clientX;
             const deltaX = clientX - startX;
-            const width = startWidth + deltaX;
+            const width = reverse ? startWidth - deltaX : startWidth + deltaX;
             set_width_px(width);
         }
         function resize_stop() {

package/dist/components/IconSwap/IconSwap.svelte

@@ -0,0 +1,67 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+
+	export interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+		/** Array of visual states (HTML strings or Snippets) */
+		states: Array<string | Snippet>;
+		/** Index of the currently visible state (0-based) */
+		active?: number;
+		/** Transition duration in ms (default: 300). Set 0 to disable. */
+		duration?: number;
+		/** CSS transition-timing-function (default: "ease") */
+		easing?: string;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes for the container */
+		class?: string;
+		/** Additional CSS classes for each state wrapper */
+		stateClass?: string;
+		/** Bindable root element reference */
+		el?: HTMLSpanElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { prefersReducedMotion } from "../../utils/prefers-reduced-motion.svelte.js";
+
+	let {
+		states,
+		active = $bindable(0),
+		duration: durationProp = 300,
+		easing = "ease",
+		unstyled = false,
+		class: classProp,
+		stateClass,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	const prefersReduced = prefersReducedMotion();
+	let duration = $derived(prefersReduced.current ? 0 : durationProp);
+	let _active = $derived(Math.max(0, Math.min(active, states.length - 1)));
+</script>
+
+<span
+	bind:this={el}
+	class={unstyled ? classProp : twMerge("stuic-icon-swap", classProp)}
+	style:--stuic-icon-swap-duration="{duration}ms"
+	style:--stuic-icon-swap-easing={easing}
+	data-active={_active}
+	{...rest}
+>
+	{#each states as state, i (i)}
+		<span
+			class={unstyled ? stateClass : twMerge("stuic-icon-swap-state", stateClass)}
+			data-visible={i === _active ? "true" : undefined}
+			aria-hidden={i !== _active}
+		>
+			{#if typeof state === "string"}
+				{@html state}
+			{:else}
+				{@render state()}
+			{/if}
+		</span>
+	{/each}
+</span>

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

@@ -0,0 +1,23 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+export interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    /** Array of visual states (HTML strings or Snippets) */
+    states: Array<string | Snippet>;
+    /** Index of the currently visible state (0-based) */
+    active?: number;
+    /** Transition duration in ms (default: 300). Set 0 to disable. */
+    duration?: number;
+    /** CSS transition-timing-function (default: "ease") */
+    easing?: string;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes for the container */
+    class?: string;
+    /** Additional CSS classes for each state wrapper */
+    stateClass?: string;
+    /** Bindable root element reference */
+    el?: HTMLSpanElement;
+}
+declare const IconSwap: import("svelte").Component<Props, {}, "active" | "el">;
+type IconSwap = ReturnType<typeof IconSwap>;
+export default IconSwap;

package/dist/components/IconSwap/index.css

@@ -0,0 +1,33 @@
+/* ============================================================================
+   ICON SWAP COMPONENT TOKENS
+   Override globally: :root { --stuic-icon-swap-duration: 500ms; }
+   Override locally:  <IconSwap style="--stuic-icon-swap-duration: 500ms;">
+   ============================================================================ */
+
+:root {
+	--stuic-icon-swap-duration: 150ms;
+	--stuic-icon-swap-easing: ease;
+}
+
+@layer components {
+	.stuic-icon-swap {
+		display: grid;
+		width: fit-content;
+	}
+
+	.stuic-icon-swap > .stuic-icon-swap-state {
+		grid-column: 1 / -1;
+		grid-row: 1 / -1;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		opacity: 0;
+		pointer-events: none;
+		transition: opacity var(--stuic-icon-swap-duration) var(--stuic-icon-swap-easing);
+	}
+
+	.stuic-icon-swap > .stuic-icon-swap-state[data-visible="true"] {
+		opacity: 1;
+		pointer-events: auto;
+	}
+}

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

@@ -0,0 +1 @@
+export { default as IconSwap, type Props as IconSwapProps } from "./IconSwap.svelte";

package/dist/components/IconSwap/index.js

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

package/dist/components/WithSidePanel/README.md

@@ -0,0 +1,107 @@
+# WithSidePanel
+
+A flex layout component with a collapsible side panel and main content area.
+Both panels consume full height with independent scrolling. The side panel
+auto-hides when the container width falls below a configurable threshold
+(container-based, not viewport-based), behaving like a mobile drawer.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `Snippet` | — | Main content |
+| `side` | `Snippet` | — | Side panel content |
+| `position` | `"left" \| "right"` | `"left"` | Side panel position |
+| `width` | `string` | `"300px"` | Side panel width (CSS value, px or %) |
+| `threshold` | `number` | `768` | Container width (px) below which side auto-hides |
+| `transition` | `boolean` | `true` | Enable Svelte slide transition |
+| `transitionDuration` | `number` | `200` | Transition duration in ms |
+| `open` | `boolean` | `true` | Desktop visibility state (bindable) |
+| `resizable` | `boolean \| Partial<ResizableWidthOptions>` | `false` | Enable drag-resizable side panel |
+| `classMain` | `string` | — | Custom class for main content div |
+| `classSide` | `string` | — | Custom class for side panel div |
+| `class` | `string` | — | Custom class for wrapper div |
+| `unstyled` | `boolean` | `false` | Skip all default styling |
+| `el` | `HTMLDivElement` | — | Bindable wrapper element reference |
+
+## API (via `bind:this`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `show()` | `void` | Show the side panel |
+| `hide()` | `void` | Hide the side panel |
+| `toggle()` | `void` | Toggle the side panel |
+| `setWidth(w: string)` | `void` | Set side panel width dynamically |
+| `current()` | `{ open: boolean, small: boolean }` | Current state |
+
+## Usage
+
+### Basic
+
+```svelte
+<WithSidePanel>
+    {#snippet side()}
+        <nav>Navigation</nav>
+    {/snippet}
+    Main content
+</WithSidePanel>
+```
+
+### Programmatic control
+
+```svelte
+<script>
+    import { WithSidePanel } from '@marianmeres/stuic';
+    let panel;
+</script>
+
+<button onclick={() => panel.toggle()}>Toggle</button>
+
+<WithSidePanel bind:this={panel} width="250px" position="right">
+    {#snippet side()}
+        Side content
+    {/snippet}
+    Main content
+</WithSidePanel>
+```
+
+### Resizable
+
+```svelte
+<WithSidePanel resizable={{ min: 200, max: 500, key: 'sidebar', storage: 'local' }}>
+    {#snippet side()}
+        Drag the edge to resize
+    {/snippet}
+    Main content
+</WithSidePanel>
+```
+
+### Tracking state
+
+```svelte
+<script>
+    let isOpen = $state(true);
+</script>
+
+<WithSidePanel bind:open={isOpen} threshold={600}>
+    {#snippet side()}
+        Panel is {isOpen ? 'open' : 'closed'}
+    {/snippet}
+    Main content
+</WithSidePanel>
+```
+
+## CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--stuic-with-side-panel-border-color` | `gray-200` / `gray-700` (dark) | Border between panels |
+| `--stuic-with-side-panel-border-width` | `1px` | Border width |
+
+## Data Attributes (on wrapper)
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `data-position` | `"left"` \| `"right"` | Current side panel position |
+| `data-small` | present/absent | Container is below threshold |
+| `data-open` | present/absent | Side panel is visible |