@marianmeres/stuic 3.35.0 → 3.36.0

package/AGENTS.md

@@ -25,7 +25,7 @@
 src/lib/
 ├── components/     # 45 UI components
 ├── actions/        # 14 Svelte actions
-├── utils/          # 42 utility modules
+├── utils/          # 43 utility modules
 ├── themes/         # 29 theme definitions (.ts) + generated CSS (css/)
 ├── icons/          # Icon re-exports
 ├── index.css       # Centralized CSS imports

package/API.md

@@ -76,7 +76,18 @@ Overlay container with backdrop. Controlled programmatically.
 
 #### `ModalDialog`
 
-Pre-styled modal dialog with title and action buttons.
+Pre-styled modal dialog with title and action buttons. Uses native `<dialog>` element with focus trap and backdrop.
+
+| Prop               | Type       | Default     | Description                                           |
+| ------------------ | ---------- | ----------- | ----------------------------------------------------- |
+| `classDialog`      | `string`   | `undefined` | CSS class for the dialog element                      |
+| `noClickOutsideClose` | `boolean` | `false`  | Disable close on outside click                        |
+| `noEscapeClose`    | `boolean`  | `false`     | Disable close on Escape key                           |
+| `noScrollLock`     | `boolean`  | `false`     | Disable body scroll lock when open                    |
+| `preEscapeClose`   | `() => any` | —          | Pre-close hook for Escape. Return false to prevent.   |
+| `preClose`         | `() => any` | —          | Pre-close hook. Return false to prevent.              |
+
+**Methods:** `open(openerOrEvent?)`, `close()`
 
 #### `Drawer`
 
@@ -714,7 +725,46 @@ Keyboard shortcut display.
 
 #### `Carousel`
 
-Image/content slider with navigation.
+Image/content slider with scroll snap, keyboard navigation, wheel scroll, optional arrows, and active item tracking via IntersectionObserver.
+
+| Prop                | Type                                              | Default     | Description                                        |
+| ------------------- | ------------------------------------------------- | ----------- | -------------------------------------------------- |
+| `items`             | `CarouselItem[]`                                  | required    | Array of carousel items                            |
+| `itemsPerView`      | `number`                                          | `1`         | Number of items visible per view                   |
+| `peekPercent`       | `number`                                          | `0`         | Percentage of next item to show as peek (0-50)     |
+| `gap`               | `number \| string`                                | `undefined` | Gap between items                                  |
+| `trackActive`       | `boolean`                                         | `false`     | Enable active item tracking                        |
+| `syncActiveOnScroll`| `boolean`                                         | `false`     | Sync active item based on scroll position          |
+| `activeIndex`       | `number`                                          | `0`         | Currently active item index (bindable)             |
+| `value`             | `string \| number`                                | `undefined` | Currently active item ID (bindable)                |
+| `snap`              | `boolean`                                         | `true`      | Enable scroll snap behavior                        |
+| `snapAlign`         | `"start" \| "center" \| "end"`                    | `"start"`   | Snap alignment                                     |
+| `keyboard`          | `boolean`                                         | `true`      | Enable keyboard navigation (arrows, Home, End)     |
+| `loop`              | `boolean`                                         | `false`     | Allow cycling from last to first and vice versa    |
+| `scrollBehavior`    | `ScrollBehavior`                                  | `"smooth"`  | Scroll behavior for programmatic navigation        |
+| `scrollbar`         | `boolean`                                         | `true`      | Show scrollbar on hover                            |
+| `wheelScroll`       | `boolean`                                         | `true`      | Enable horizontal scrolling via mouse wheel        |
+| `arrows`            | `boolean`                                         | `false`     | Show prev/next arrow buttons                       |
+| `minItemWidth`      | `number`                                          | `undefined` | Minimum item width (px) for auto-fit               |
+| `onActiveChange`    | `(item: CarouselItem, index: number) => void`     | —           | Callback when active item changes                  |
+| `renderItem`        | `Snippet<[{ item, index, active }]>`              | —           | Custom render snippet for items                    |
+
+**Methods:** `goTo(index)`, `goToId(id)`, `next()`, `previous()`
+
+```svelte
+<Carousel
+	items={slides}
+	itemsPerView={3}
+	gap={16}
+	arrows
+	trackActive
+	syncActiveOnScroll
+>
+	{#snippet renderItem({ item, index, active })}
+		<img src={item.data.src} alt={item.data.alt} />
+	{/snippet}
+</Carousel>
+```
 
 #### `AnimatedElipsis`
 
@@ -789,7 +839,65 @@ Theme color swatch preview.
 
 #### `Book`
 
-Interactive book/flipbook reader with 3D CSS page flip animation, zoom, pan, swipe, and responsive single-page mode.
+Interactive book/flipbook reader with 3D CSS page flip animation, zoom, pan, swipe, clickable areas, and responsive single-page mode.
+
+| Prop             | Type                                                          | Default        | Description                                   |
+| ---------------- | ------------------------------------------------------------- | -------------- | --------------------------------------------- |
+| `pages`          | `BookPage[]`                                                  | required       | Ordered array of book pages                   |
+| `baseUrl`        | `string`                                                      | `undefined`    | Fallback base URL for relative page src       |
+| `activeSpread`   | `number`                                                      | `0`            | Currently active spread index (bindable)      |
+| `keyboard`       | `boolean`                                                     | `true`         | Enable keyboard navigation                    |
+| `swipe`          | `boolean`                                                     | `true`         | Enable swipe gesture navigation               |
+| `duration`       | `number`                                                      | `500`          | Flip animation duration in ms                 |
+| `zoom`           | `boolean`                                                     | `true`         | Enable zoom capability                        |
+| `zoomLevels`     | `readonly number[]`                                           | `[1,1.5,2,3]`  | Discrete zoom levels                          |
+| `clampPan`       | `boolean`                                                     | `false`        | Clamp panning within bounds                   |
+| `singlePage`     | `boolean`                                                     | `false`        | Force single-page layout                      |
+| `responsive`     | `boolean`                                                     | `true`         | Auto-switch to single-page when narrow        |
+| `onSpreadChange` | `(spread: BookSpread, index: number) => void`                 | —              | Callback when active spread changes           |
+| `onPageClick`    | `(data: { page: BookPage; x: number; y: number }) => void`   | —              | Callback on page click (coordinates 0–1)      |
+| `onAreaClick`    | `(data: { area: BookPageArea; page: BookPage }) => void`      | —              | Callback when clickable area is clicked       |
+| `renderPage`     | `Snippet<[{ page, position }]>`                               | —              | Custom page render snippet                    |
+
+**Exported helpers:** `buildSpreads(pages)`, `buildSinglePageSpreads(pages)`, `buildSheets(spreads)`, `computeBookPageSize(pages)`
+
+**Types:** `BookPage`, `BookPageArea`, `BookSpread`, `BookSheet`, `BookCollection`
+
+```svelte
+<Book
+	pages={[
+		{ id: 1, src: "/cover.jpg", width: 800, height: 1100 },
+		{ id: 2, src: "/page1.jpg", width: 800, height: 1100 },
+		{ id: 3, src: "/page2.jpg", width: 800, height: 1100 },
+	]}
+	bind:activeSpread
+/>
+```
+
+#### `BookResponsive`
+
+Responsive wrapper around Book that intelligently switches between book mode (dual/single-page) and an inline asset preview mode based on container width. Inherits all Book props except `responsive` and `singlePage` (managed internally).
+
+| Prop              | Type                  | Default     | Description                                             |
+| ----------------- | --------------------- | ----------- | ------------------------------------------------------- |
+| `minPageWidth`    | `number`              | `150`       | Min page width (px) before switching to single-page     |
+| `debounce`        | `number`              | `150`       | Resize debounce delay in ms                             |
+| `inlineThreshold` | `number`              | `480`       | Container width (px) below which switches to inline (0 = disabled) |
+| `forceInline`     | `boolean`             | `false`     | Force inline asset preview mode                         |
+| `noPrevNext`      | `boolean`             | `false`     | Hide prev/next arrow buttons                            |
+| `classControls`   | `string`              | `undefined` | Custom class for prev/next buttons                      |
+| `noModeSwitch`    | `boolean`             | `false`     | Hide the book/inline toggle button                      |
+| `initialMode`     | `"book" \| "inline"`  | `undefined` | Override auto-detection on mount                        |
+
+**Exported utility:** `bookPagesToAssets(pages)` — Converts `BookPage[]` to `AssetPreview[]` for inline mode.
+
+```svelte
+<BookResponsive
+	pages={bookPages}
+	inlineThreshold={600}
+	onAreaClick={handleAreaClick}
+/>
+```
 
 #### `Circle`
 
@@ -831,7 +939,75 @@ Element that expands width on hover with delayed transitions and shadow effects.
 
 #### `AssetsPreview`
 
-Modal-based asset/file preview gallery with zoom, pan, pinch-zoom, and download controls.
+Modal-based asset/file preview gallery with zoom, pan, pinch-zoom, swipe navigation, clickable area overlays, and download controls. Opens in a full-screen ModalDialog.
+
+| Prop              | Type                                                              | Default     | Description                                  |
+| ----------------- | ----------------------------------------------------------------- | ----------- | -------------------------------------------- |
+| `assets`          | `string[] \| AssetPreview[]`                                      | required    | Asset URLs or asset objects                  |
+| `baseUrl`         | `string`                                                          | `undefined` | Fallback base URL for relative asset URLs    |
+| `modalClassDialog`| `string`                                                          | `undefined` | CSS class for the modal dialog               |
+| `modalClass`      | `string`                                                          | `undefined` | CSS class for the modal container            |
+| `classControls`   | `string`                                                          | `undefined` | CSS class for control buttons                |
+| `t`               | `TranslateFn`                                                     | built-in    | Translation function                         |
+| `onDelete`        | `(asset: AssetPreview, index: number, { close }) => void`         | —           | Delete handler (shows delete button)         |
+| `onAreaClick`     | `(data: { area: AssetArea; asset: AssetPreviewNormalized }) => void` | —        | Callback for clickable area on image         |
+| `noName`          | `boolean`                                                         | `false`     | Hide file name display                       |
+| `clampPan`        | `boolean`                                                         | `true`      | Clamp panning within image bounds            |
+| `noDownload`      | `boolean`                                                         | `false`     | Hide download button                         |
+| `noPrevNext`      | `boolean`                                                         | `false`     | Hide prev/next arrows                        |
+| `noZoom`          | `boolean`                                                         | `false`     | Disable all zooming                          |
+| `noZoomButtons`   | `boolean`                                                         | `false`     | Hide zoom buttons (gestures still work)      |
+| `noDots`          | `boolean`                                                         | `false`     | Never show pagination dots                   |
+| `noCurrentOfTotal`| `boolean`                                                         | `false`     | Never show "x / y" counter                   |
+
+**Methods:** `open(index?)`, `close()`
+
+**Types:** `AssetPreview`, `AssetPreviewUrlObj`, `AssetArea`
+
+**Utility:** `getAssetIcon(ext)` — Returns icon function for file extension.
+
+```svelte
+<AssetsPreview
+	assets={[
+		{ url: { full: "/photo.jpg", thumb: "/photo-thumb.jpg" }, name: "Photo", type: "image/jpeg" },
+		"/document.pdf",
+	]}
+	onDelete={(asset, i, { close }) => { deleteAsset(i); close(); }}
+/>
+```
+
+#### `AssetsPreviewInline`
+
+Always-visible (non-modal) variant of AssetsPreview with the same zoom, pan, swipe, and area clicking features. For embedding asset galleries directly in layouts.
+
+| Prop              | Type                                                              | Default     | Description                                  |
+| ----------------- | ----------------------------------------------------------------- | ----------- | -------------------------------------------- |
+| `assets`          | `string[] \| AssetPreview[]`                                      | required    | Asset URLs or asset objects                  |
+| `baseUrl`         | `string`                                                          | `undefined` | Fallback base URL for relative asset URLs    |
+| `initialIndex`    | `number`                                                          | `0`         | Starting asset index                         |
+| `currentIndex`    | `number`                                                          | `0`         | Current display index (bindable)             |
+| `class`           | `string`                                                          | `undefined` | Container CSS class                          |
+| `classControls`   | `string`                                                          | `undefined` | CSS class for control buttons                |
+| `t`               | `TranslateFn`                                                     | built-in    | Translation function                         |
+| `onDelete`        | `(asset, index, { close }) => void`                               | —           | Delete handler                               |
+| `onAreaClick`     | `(data: { area: AssetArea; asset: AssetPreviewNormalized }) => void` | —        | Callback for clickable area on image         |
+| `noName`          | `boolean`                                                         | `false`     | Hide file name display                       |
+| `clampPan`        | `boolean`                                                         | `true`      | Clamp panning within bounds                  |
+| `noDownload`      | `boolean`                                                         | `false`     | Hide download button                         |
+| `noPrevNext`      | `boolean`                                                         | `false`     | Hide prev/next arrows                        |
+| `noZoom`          | `boolean`                                                         | `false`     | Disable all zooming                          |
+| `noZoomButtons`   | `boolean`                                                         | `false`     | Hide zoom buttons (gestures still work)      |
+| `noDots`          | `boolean`                                                         | `false`     | Never show pagination dots                   |
+| `noCurrentOfTotal`| `boolean`                                                         | `false`     | Never show "x / y" counter                   |
+
+**Methods:** `goTo(index)`, `next()`, `previous()`
+
+```svelte
+<AssetsPreviewInline
+	assets={imageUrls}
+	bind:currentIndex
+/>
+```
 
 #### `X`
 
@@ -1289,6 +1465,36 @@ Generate SVG circle path data.
 
 Value oscillation for animations.
 
+### URL
+
+#### `resolveUrl(url, baseUrl?)`
+
+Resolve a possibly relative URL against an optional base URL. Returns the original URL if no baseUrl or on error.
+
+**Parameters:**
+
+- `url` (string) — URL to resolve
+- `baseUrl` (string, optional) — Base URL to resolve against
+
+**Returns:** `string`
+
+```ts
+import { resolveUrl } from "@marianmeres/stuic";
+resolveUrl("images/photo.jpg", "https://example.com/books/1/");
+// => "https://example.com/books/1/images/photo.jpg"
+```
+
+#### `resolveSrcset(srcset, baseUrl?)`
+
+Resolve all URLs within a srcset string against an optional base URL.
+
+**Parameters:**
+
+- `srcset` (string) — Srcset string with relative URLs
+- `baseUrl` (string, optional) — Base URL to resolve against
+
+**Returns:** `string`
+
 ### Files
 
 #### `fileFromBlobUrl(blobUrl, filename)`
@@ -1388,6 +1594,10 @@ Re-exported icon render functions from `@marianmeres/icons-fns`. Import from `@m
 
 `iconFile`, `iconFileBinary`, `iconFileCode`, `iconFileImage`, `iconFileMusic`, `iconFilePdf`, `iconFileRichtext`, `iconFileSlides`, `iconFileSpreadsheet`, `iconFileText`, `iconFileWord`, `iconFileZip`
 
+### Book Icons
+
+`iconBookOpen`
+
 ### Alert Icons
 
 `iconAlertSuccess`, `iconAlertInfo`, `iconAlertError`, `iconAlertWarning`, `iconRefresh`
@@ -1398,7 +1608,11 @@ Re-exported icon render functions from `@marianmeres/icons-fns`. Import from `@m
 
 ### UI Control Icons
 
-`iconCheck`, `iconChevronDown`, `iconChevronLeft`, `iconChevronRight`, `iconChevronUp`, `iconCircle`, `iconDot`, `iconEllipsisVertical`, `iconLanguages`, `iconMenu`, `iconSearch`, `iconSettings`, `iconSquare`, `iconUser`, `iconX`
+`iconCheck`, `iconChevronDown`, `iconChevronLeft`, `iconChevronRight`, `iconChevronUp`, `iconCircle`, `iconCircleCheckBig`, `iconDot`, `iconEllipsisVertical`, `iconGrip`, `iconGripHorizontal`, `iconGripVertical`, `iconLanguages`, `iconMenu`, `iconPencil`, `iconSearch`, `iconSettings`, `iconSquare`, `iconUser`, `iconX`
+
+### Brand Icons
+
+`iconApple`, `iconFacebook`, `iconGithub`, `iconGoogle`, `iconInstagram`, `iconMicrosoft`, `iconTwitterX`, `iconXbox`, `iconYoutube`
 
 ---
 
@@ -1419,6 +1633,9 @@ Naming pattern: `{ComponentName}Props`
 
 Additional exported types include:
 
+- `BookPage`, `BookPageArea`, `BookSpread`, `BookSheet`, `BookCollection` — Book component types
+- `AssetPreview`, `AssetPreviewUrlObj`, `AssetArea` — AssetPreview types
+- `CarouselItem` — Carousel item type
 - `LoginFormData`, `LoginFormValidationError` — Login form types
 - `CartComponentItem`, `CartVariant` — Cart component types
 - `CheckoutStep`, `CheckoutAddressData`, `CheckoutCustomerFormData`, `CheckoutLoginFormData`, `CheckoutOrderLineItem`, `CheckoutOrderTotals`, `CheckoutDeliveryOption`, `CheckoutDeliverySnapshot`, `CheckoutOrderData`, `CheckoutValidationError`, `CheckoutFormMode` — Checkout types

package/README.md

@@ -143,7 +143,7 @@ CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
 
 ### Display & Utility
 
-Avatar, Book, Carousel, Circle, AnimatedElipsis, H, IconSwap, Separator, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, DataTable
+Avatar, Book, BookResponsive, Carousel, Circle, AnimatedElipsis, H, IconSwap, Separator, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, AssetsPreviewInline, DataTable
 
 ### E-commerce
 

package/dist/actions/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./autogrow.svelte.js";
+export * from "./onboarding/onboarding.svelte.js";
 export * from "./autoscroll.js";
 export * from "./dim-behind/dim-behind.svelte.js";
 export * from "./file-dropzone.svelte.js";

package/dist/actions/index.js

@@ -1,4 +1,5 @@
 export * from "./autogrow.svelte.js";
+export * from "./onboarding/onboarding.svelte.js";
 export * from "./autoscroll.js";
 export * from "./dim-behind/dim-behind.svelte.js";
 export * from "./file-dropzone.svelte.js";

package/dist/actions/onboarding/OnboardingShell.svelte

@@ -0,0 +1,71 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { TourStepDef, TourLabels, TourShellContext } from "./onboarding.svelte.js";
+
+	export interface Props {
+		step: TourStepDef;
+		/** 0-based index of this step */
+		index: number;
+		total: number;
+		isFirst: boolean;
+		isLast: boolean;
+		labels: Required<TourLabels>;
+		/** Optional custom shell snippet — replaces the entire default layout */
+		shell?: Snippet<[TourShellContext]>;
+		next: () => void;
+		prev: () => void;
+		skip: () => void;
+	}
+</script>
+
+<script lang="ts">
+	import Thc from "../../components/Thc/Thc.svelte";
+
+	let { step, index, total, isFirst, isLast, labels, shell, next, prev, skip }: Props = $props();
+
+	const context: TourShellContext = $derived({
+		step,
+		index,
+		total,
+		isFirst,
+		isLast,
+		next,
+		prev,
+		skip,
+	});
+</script>
+
+{#if shell}
+	{@render shell(context)}
+{:else}
+	<div class="stuic-onboarding-shell">
+		{#if step.title}
+			<div class="stuic-onboarding-title">{step.title}</div>
+		{/if}
+		{#if step.content}
+			<div class="stuic-onboarding-content">
+				<Thc thc={step.content} />
+			</div>
+		{/if}
+		<div class="stuic-onboarding-footer">
+			<span class="stuic-onboarding-steps">{index + 1} / {total}</span>
+			<div class="stuic-onboarding-actions">
+				{#if !isLast}
+					<button class="stuic-onboarding-btn-skip" onclick={skip}>
+						{step.skipLabel ?? labels.skip}
+					</button>
+				{/if}
+				{#if !isFirst}
+					<button class="stuic-onboarding-btn-prev" onclick={prev}>
+						{step.prevLabel ?? labels.prev}
+					</button>
+				{/if}
+				<button class="stuic-onboarding-btn-next" onclick={next}>
+					{isLast
+						? (step.finishLabel ?? labels.finish)
+						: (step.nextLabel ?? labels.next)}
+				</button>
+			</div>
+		</div>
+	</div>
+{/if}

package/dist/actions/onboarding/OnboardingShell.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Snippet } from "svelte";
+import type { TourStepDef, TourLabels, TourShellContext } from "./onboarding.svelte.js";
+export interface Props {
+    step: TourStepDef;
+    /** 0-based index of this step */
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    labels: Required<TourLabels>;
+    /** Optional custom shell snippet — replaces the entire default layout */
+    shell?: Snippet<[TourShellContext]>;
+    next: () => void;
+    prev: () => void;
+    skip: () => void;
+}
+declare const OnboardingShell: import("svelte").Component<Props, {}, "">;
+type OnboardingShell = ReturnType<typeof OnboardingShell>;
+export default OnboardingShell;

package/dist/actions/onboarding/index.css

@@ -0,0 +1,93 @@
+/* Onboarding shell tokens */
+:root {
+	--stuic-onboarding-shell-padding: calc(var(--spacing) * 3);
+	--stuic-onboarding-shell-gap: calc(var(--spacing) * 2);
+	--stuic-onboarding-shell-min-width: 200px;
+	--stuic-onboarding-shell-max-width: 320px;
+	--stuic-onboarding-title-size: var(--text-base);
+	--stuic-onboarding-content-size: var(--text-sm);
+	--stuic-onboarding-footer-gap: calc(var(--spacing) * 1.5);
+	--stuic-onboarding-steps-size: var(--text-xs);
+	--stuic-onboarding-btn-padding-x: calc(var(--spacing) * 2.5);
+	--stuic-onboarding-btn-padding-y: calc(var(--spacing) * 1);
+	--stuic-onboarding-btn-radius: calc(var(--spacing) * 1);
+	--stuic-onboarding-btn-font-size: var(--text-xs);
+	--stuic-onboarding-btn-primary-bg: var(--stuic-color-primary, #737373);
+	--stuic-onboarding-btn-primary-fg: var(--stuic-color-primary-foreground, #fff);
+	--stuic-onboarding-btn-secondary-bg: oklch(from currentColor l c h / 0.08);
+}
+
+.stuic-onboarding-shell {
+	display: flex;
+	flex-direction: column;
+	gap: var(--stuic-onboarding-shell-gap);
+	padding: var(--stuic-onboarding-shell-padding);
+	min-width: var(--stuic-onboarding-shell-min-width);
+	max-width: var(--stuic-onboarding-shell-max-width);
+}
+
+.stuic-onboarding-title {
+	font-weight: 600;
+	font-size: var(--stuic-onboarding-title-size);
+}
+
+.stuic-onboarding-content {
+	font-size: var(--stuic-onboarding-content-size);
+	opacity: 0.85;
+}
+
+.stuic-onboarding-footer {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: calc(var(--spacing) * 2);
+	padding-top: calc(var(--spacing) * 2);
+	margin-top: calc(var(--spacing) * 1);
+	border-top: 1px solid var(--stuic-spotlight-annotation-border, rgba(0, 0, 0, 0.1));
+}
+
+.stuic-onboarding-steps {
+	font-size: var(--stuic-onboarding-steps-size);
+	opacity: 0.5;
+}
+
+.stuic-onboarding-actions {
+	display: flex;
+	align-items: center;
+	gap: var(--stuic-onboarding-footer-gap);
+}
+
+/* Shared button base */
+.stuic-onboarding-btn-skip,
+.stuic-onboarding-btn-prev,
+.stuic-onboarding-btn-next {
+	font-size: var(--stuic-onboarding-btn-font-size);
+	padding: var(--stuic-onboarding-btn-padding-y) var(--stuic-onboarding-btn-padding-x);
+	border-radius: var(--stuic-onboarding-btn-radius);
+	line-height: 1.5;
+	transition:
+		opacity 0.15s,
+		filter 0.15s;
+}
+
+.stuic-onboarding-btn-skip {
+	opacity: 0.45;
+	&:hover {
+		opacity: 0.85;
+	}
+}
+
+.stuic-onboarding-btn-prev {
+	background: var(--stuic-onboarding-btn-secondary-bg);
+	&:hover {
+		filter: brightness(0.9);
+	}
+}
+
+.stuic-onboarding-btn-next {
+	background: var(--stuic-onboarding-btn-primary-bg);
+	color: var(--stuic-onboarding-btn-primary-fg);
+	&:hover {
+		filter: brightness(0.9);
+	}
+}

package/dist/actions/onboarding/onboarding.svelte.d.ts

@@ -0,0 +1,138 @@
+import type { Snippet } from "svelte";
+import type { SpotlightPosition } from "../spotlight/spotlight.svelte.js";
+import type { THC } from "../../components/Thc/Thc.svelte";
+/**
+ * Definition of a single step in an onboarding tour.
+ */
+export interface TourStepDef {
+    /** Unique identifier — must match the `id` passed to `use:tourStep` */
+    id: string;
+    /** Short title shown in the default shell header */
+    title?: string;
+    /** Rich step description (any THC value: string, html, component, snippet) */
+    content?: THC;
+    /** Spotlight annotation position relative to the target element */
+    position?: SpotlightPosition;
+    /** Spotlight cutout padding in px */
+    padding?: number;
+    /** Spotlight cutout border radius in px */
+    borderRadius?: number;
+    /** Override "Next" button label for this step */
+    nextLabel?: string;
+    /** Override "Back" button label for this step */
+    prevLabel?: string;
+    /** Override "Skip" button label for this step */
+    skipLabel?: string;
+    /** Override "Finish" button label for the last step */
+    finishLabel?: string;
+    /** Called when tour enters this step */
+    onEnter?: () => void;
+    /** Called when tour leaves this step */
+    onLeave?: () => void;
+}
+/**
+ * Default label overrides for the navigation shell buttons.
+ */
+export interface TourLabels {
+    next?: string;
+    prev?: string;
+    skip?: string;
+    finish?: string;
+}
+/**
+ * Context passed to a custom `shell` snippet.
+ */
+export interface TourShellContext {
+    step: TourStepDef;
+    /** 0-based index of the current step */
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    next: () => void;
+    prev: () => void;
+    skip: () => void;
+}
+/**
+ * Options for `createTour`.
+ */
+export interface TourOptions {
+    steps: TourStepDef[];
+    /** How long to wait (ms) for a step's element to appear before skipping it. Default: 500 */
+    waitForElement?: number;
+    /** Default button labels (per-step overrides take precedence) */
+    labels?: TourLabels;
+    /** Replace the entire default shell with a custom Svelte snippet */
+    shell?: Snippet<[TourShellContext]>;
+    /** Press Escape to skip the tour. Default: true */
+    closeOnEscape?: boolean;
+    /** Called when tour starts */
+    onStart?: () => void;
+    /** Called when tour reaches the end naturally (after last step) */
+    onEnd?: () => void;
+    /** Called when tour is skipped by the user */
+    onSkip?: () => void;
+    /** Called on every step change */
+    onStepChange?: (step: TourStepDef, index: number) => void;
+    /**
+     * If set, the tour result ('completed' or 'skipped') is persisted under this key.
+     * On subsequent `start()` calls, the tour will silently skip if the key exists.
+     * Use `tour.reset()` to clear the persisted state and allow the tour to run again.
+     */
+    storageKey?: string;
+    /** Storage backend for persistence. Default: 'local' */
+    storage?: "local" | "session";
+}
+/**
+ * Creates a multi-step onboarding tour on top of the spotlight primitive.
+ *
+ * Define all steps centrally here, then attach `use:tourStep={[tour, stepId]}`
+ * to each target element in your markup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createTour, tourStep } from '../..';
+ *
+ *   const tour = createTour({
+ *     steps: [
+ *       { id: 'header', title: 'Welcome', content: 'This is the top of the page.' },
+ *       { id: 'save-btn', title: 'Save your work', content: 'Click here to save.' },
+ *     ],
+ *     onEnd: () => console.log('Tour complete!'),
+ *   });
+ * </script>
+ *
+ * <header use:tourStep={[tour, 'header']}>...</header>
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * <button onclick={tour.start}>Start Tour</button>
+ * ```
+ */
+export declare function createTour(options: TourOptions): {
+    readonly active: boolean;
+    readonly currentStep: TourStepDef;
+    readonly currentIndex: number;
+    readonly seen: boolean;
+    start: () => void;
+    next: () => void;
+    prev: () => void;
+    skip: () => void;
+    reset: () => void;
+    _register: (id: string, el: HTMLElement) => void;
+    _unregister: (id: string) => void;
+    _isCurrentStep: (id: string) => boolean;
+    _getShellContent: (id: string) => THC;
+};
+export type TourInstance = ReturnType<typeof createTour>;
+/**
+ * Svelte action that registers a DOM element as the target for a specific tour step.
+ *
+ * @param el - The target element
+ * @param args - Tuple of `[TourInstance, stepId]`
+ *
+ * @example
+ * ```svelte
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * ```
+ */
+export declare function tourStep(el: HTMLElement, args: [TourInstance, string]): void;

package/dist/actions/onboarding/onboarding.svelte.js

@@ -0,0 +1,247 @@
+import { spotlight } from "../spotlight/spotlight.svelte.js";
+import OnboardingShell from "./OnboardingShell.svelte";
+import { StorageAbstraction } from "../../utils/storage-abstraction.js";
+/**
+ * Creates a multi-step onboarding tour on top of the spotlight primitive.
+ *
+ * Define all steps centrally here, then attach `use:tourStep={[tour, stepId]}`
+ * to each target element in your markup.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createTour, tourStep } from '../..';
+ *
+ *   const tour = createTour({
+ *     steps: [
+ *       { id: 'header', title: 'Welcome', content: 'This is the top of the page.' },
+ *       { id: 'save-btn', title: 'Save your work', content: 'Click here to save.' },
+ *     ],
+ *     onEnd: () => console.log('Tour complete!'),
+ *   });
+ * </script>
+ *
+ * <header use:tourStep={[tour, 'header']}>...</header>
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * <button onclick={tour.start}>Start Tour</button>
+ * ```
+ */
+export function createTour(options) {
+    let currentIndex = $state(-1);
+    const active = $derived(currentIndex >= 0);
+    const currentStep = $derived(options.steps[currentIndex] ?? null);
+    // Optional persistence store
+    const store = options.storageKey
+        ? new StorageAbstraction(options.storage ?? "local")
+        : null;
+    // Element registry: stepId -> HTMLElement
+    const registry = new Map();
+    // Wait-for-element mechanism (one pending wait at a time)
+    let pendingStepId = null;
+    let pendingResolve = null;
+    // Guard against concurrent navigation calls
+    let advancing = false;
+    const resolvedLabels = {
+        next: "Next",
+        prev: "Back",
+        skip: "Skip",
+        finish: "Finish",
+        ...options.labels,
+    };
+    // Escape key listener — active only while tour is running
+    $effect(() => {
+        if (active && options.closeOnEscape !== false) {
+            const handler = (e) => {
+                if (e.key === "Escape") {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    e.stopImmediatePropagation();
+                    skip();
+                }
+            };
+            document.addEventListener("keydown", handler);
+            return () => document.removeEventListener("keydown", handler);
+        }
+    });
+    // -- Internal API (used by tourStep action) -----------------------------------------
+    function _register(id, el) {
+        registry.set(id, el);
+        // If we were waiting for this element, resolve immediately
+        if (pendingStepId === id && pendingResolve) {
+            pendingResolve(true);
+            pendingStepId = null;
+            pendingResolve = null;
+        }
+    }
+    function _unregister(id) {
+        registry.delete(id);
+        // If the active step's element unmounts mid-tour, end gracefully
+        if (active && currentStep?.id === id) {
+            console.warn(`[createTour] Active step "${id}" element unmounted — ending tour`);
+            _end();
+        }
+    }
+    function _isCurrentStep(id) {
+        return active && currentStep?.id === id;
+    }
+    function _getShellContent(id) {
+        const step = options.steps.find((s) => s.id === id);
+        const index = options.steps.indexOf(step);
+        const total = options.steps.length;
+        return {
+            component: OnboardingShell,
+            props: {
+                step,
+                index,
+                total,
+                isFirst: index === 0,
+                isLast: index === total - 1,
+                labels: resolvedLabels,
+                shell: options.shell,
+                next,
+                prev,
+                skip,
+            },
+        };
+    }
+    // -- Navigation ---------------------------------------------------------------------
+    function waitForElement(id) {
+        // Cancel any previous pending wait
+        if (pendingResolve) {
+            pendingResolve(false);
+            pendingResolve = null;
+            pendingStepId = null;
+        }
+        return new Promise((resolve) => {
+            pendingStepId = id;
+            pendingResolve = resolve;
+            setTimeout(() => {
+                if (pendingStepId === id) {
+                    console.warn(`[createTour] Step "${id}" element not found after ${options.waitForElement ?? 500}ms — skipping`);
+                    pendingStepId = null;
+                    pendingResolve = null;
+                    resolve(false);
+                }
+            }, options.waitForElement ?? 500);
+        });
+    }
+    async function advanceTo(targetIndex) {
+        if (advancing)
+            return;
+        advancing = true;
+        try {
+            // Call onLeave for the step we're leaving
+            currentStep?.onLeave?.();
+            const direction = targetIndex >= currentIndex ? 1 : -1;
+            let index = targetIndex;
+            // Find the nearest available step in the direction of travel
+            while (index >= 0 && index < options.steps.length) {
+                const step = options.steps[index];
+                if (!registry.has(step.id)) {
+                    const found = await waitForElement(step.id);
+                    if (!found) {
+                        index += direction;
+                        continue;
+                    }
+                }
+                // Step element is available — navigate here
+                currentIndex = index;
+                step.onEnter?.();
+                options.onStepChange?.(step, index);
+                return;
+            }
+            // Exhausted all steps in the direction of travel
+            _end();
+        }
+        finally {
+            advancing = false;
+        }
+    }
+    function _end() {
+        currentIndex = -1;
+        store?.set(options.storageKey, "completed");
+        options.onEnd?.();
+    }
+    // -- Public API ---------------------------------------------------------------------
+    function start() {
+        if (store && store.has(options.storageKey))
+            return;
+        options.onStart?.();
+        advanceTo(0);
+    }
+    function next() {
+        advanceTo(currentIndex + 1);
+    }
+    function prev() {
+        if (currentIndex > 0)
+            advanceTo(currentIndex - 1);
+    }
+    function skip() {
+        currentIndex = -1;
+        store?.set(options.storageKey, "skipped");
+        options.onSkip?.();
+    }
+    function reset() {
+        store?.remove(options.storageKey);
+    }
+    return {
+        get active() {
+            return active;
+        },
+        get currentStep() {
+            return currentStep;
+        },
+        get currentIndex() {
+            return currentIndex;
+        },
+        get seen() {
+            return store ? store.has(options.storageKey) : false;
+        },
+        start,
+        next,
+        prev,
+        skip,
+        reset,
+        // Internal — used by tourStep action
+        _register,
+        _unregister,
+        _isCurrentStep,
+        _getShellContent,
+    };
+}
+/**
+ * Svelte action that registers a DOM element as the target for a specific tour step.
+ *
+ * @param el - The target element
+ * @param args - Tuple of `[TourInstance, stepId]`
+ *
+ * @example
+ * ```svelte
+ * <button use:tourStep={[tour, 'save-btn']}>Save</button>
+ * ```
+ */
+export function tourStep(el, args) {
+    const [tour, id] = args;
+    tour._register(id, el);
+    spotlight(el, () => {
+        const isActive = tour._isCurrentStep(id);
+        if (!isActive) {
+            return { open: false };
+        }
+        return {
+            open: true,
+            content: tour._getShellContent(id),
+            position: tour.currentStep?.position ?? "bottom",
+            padding: tour.currentStep?.padding,
+            borderRadius: tour.currentStep?.borderRadius,
+            closeOnEscape: false,
+            closeOnBackdropClick: false,
+            scrollIntoView: true,
+        };
+    });
+    $effect(() => {
+        return () => {
+            tour._unregister(id);
+        };
+    });
+}

package/dist/index.css

@@ -62,6 +62,7 @@ In practice:
 
 /* Action CSS */
 @import "./actions/dim-behind/index.css";
+@import "./actions/onboarding/index.css";
 @import "./actions/popover/index.css";
 @import "./actions/spotlight/index.css";
 @import "./actions/tooltip/index.css";

package/docs/domains/components.md

@@ -63,14 +63,16 @@
 | --------------- | ------------------------------------------------------------------- |
 | Avatar          | User avatars with fallback                                          |
 | KbdShortcut     | Keyboard shortcut hints                                             |
-| Carousel        | Image/content slider                                                |
+| Carousel        | Image/content slider with snap, keyboard nav, wheel scroll, arrows  |
 | ListItemButton  | List item with actions                                              |
 | AnimatedElipsis | Loading dots animation                                              |
 | IconSwap        | N-state visibility swap with opacity transitions (e.g. hamburger/X) |
 | DataTable       | Responsive data table with paging, selection, batch actions         |
 | ThemePreview    | Theme color swatches                                                |
-| AssetsPreview   | Modal-based asset/file preview with zoom, pan, download             |
-| Book            | Interactive book/flipbook reader with 3D page-flip animation        |
+| AssetsPreview       | Modal-based asset/file preview with zoom, pan, swipe, area clicking |
+| AssetsPreviewInline | Always-visible (non-modal) asset preview with same feature set      |
+| Book                | Interactive book/flipbook with 3D page-flip, zoom, pan, areas      |
+| BookResponsive      | Responsive Book wrapper: auto single/dual-page + inline mode       |
 | Circle          | SVG circular progress indicator                                     |
 | H               | Semantic heading (h1-h6) with separate visual/semantic levels       |
 | Separator       | Horizontal/vertical separator line                                  |

package/docs/domains/utils.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-42 utility modules for common tasks. Organized by category.
+43 utility modules for common tasks. Organized by category.
 
 ---
 
@@ -124,6 +124,15 @@ twMerge("px-4 py-2", "px-6"); // => "py-2 px-6"
 
 ---
 
+## URL
+
+| Util            | Purpose                                      |
+| --------------- | -------------------------------------------- |
+| `resolveUrl`    | Resolve relative URL against base URL        |
+| `resolveSrcset` | Resolve all URLs within a srcset string      |
+
+---
+
 ## Files
 
 | Util               | Purpose                  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "3.35.0",
+  "version": "3.36.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",