@marianmeres/stuic 3.37.0 → 3.38.1

package/AGENTS.md

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

package/API.md

@@ -280,6 +280,25 @@ Multi-language input field.
 
 Toggle button styled as a "like" action.
 
+#### `FieldPhoneNumber`
+
+International phone number input with country dial code picker. Parses and composes full phone numbers (e.g. `+421905123456`), handles paste with international prefix detection, supports country filtering and preferred countries.
+
+| Prop                 | Type                                | Default     | Description                                        |
+| -------------------- | ----------------------------------- | ----------- | -------------------------------------------------- |
+| `value`              | `string`                            | `""`        | Bindable full phone number (e.g. `"+421905123456"`) |
+| `country`            | `string`                            | `""`        | Bindable selected country ISO code (e.g. `"SK"`)   |
+| `dialCode`           | `string`                            | `""`        | Bindable dial code with `+` (e.g. `"+421"`)        |
+| `localNumber`        | `string`                            | `""`        | Bindable local number part                         |
+| `defaultCountry`     | `string`                            | —           | ISO code for initial country selection             |
+| `flags`              | `boolean`                           | `true`      | Show country flag emoji                            |
+| `countries`          | `string[]`                          | all         | Filtered list of country ISO codes to show         |
+| `preferredCountries` | `string[]`                          | —           | ISO codes pinned at top of dropdown                |
+| `name`               | `string`                            | —           | Hidden input name for form submission              |
+| `validate`           | `boolean \| ValidateOptions`        | —           | Enable phone validation                            |
+
+Exports: `FieldPhoneNumber`, `FieldPhoneNumberProps`, `validatePhoneNumber`, `Country`.
+
 #### `FieldObject`
 
 Dual-mode JSON object editor with pretty-print and raw edit modes. Validates JSON syntax, supports recursive depth display, auto-grow textarea, and form submission via hidden input.
@@ -405,7 +424,43 @@ Progress bar.
 
 #### `Spinner`
 
-Loading spinner indicator.
+Loading spinner indicator (default SVG spinner).
+
+#### `SpinnerCircle`
+
+CSS-only circular spinner.
+
+| Prop        | Type                              | Default    | Description                |
+| ----------- | --------------------------------- | ---------- | -------------------------- |
+| `duration`  | `number`                          | `750`      | One loop duration in ms    |
+| `thickness` | `"normal" \| "thin" \| "thick"`   | `"normal"` | Border thickness preset    |
+| `direction` | `"cw" \| "ccw"`                   | `"cw"`     | Rotation direction         |
+
+#### `SpinnerCircleOscillate`
+
+Animated Circle-based spinner with oscillating arc completeness.
+
+| Prop             | Type      | Default | Description                   |
+| ---------------- | --------- | ------- | ----------------------------- |
+| `bgStrokeColor`  | `string`  | —       | Background circle stroke      |
+| `strokeWidth`    | `number`  | —       | SVG stroke width              |
+| `noOscillate`    | `boolean` | —       | Fixed completeness (no anim)  |
+| `rotateDuration` | `string`  | —       | CSS animation duration        |
+
+#### `SpinnerUnicode`
+
+Unicode character frame animation with 17 built-in variants.
+
+| Prop       | Type                     | Default             | Description                  |
+| ---------- | ------------------------ | ------------------- | ---------------------------- |
+| `speed`    | `number`                 | `100`               | Frame interval in ms         |
+| `variant`  | `SpinnerUnicodeVariant`  | `"braille_bar_dot"` | Built-in animation variant   |
+| `reversed` | `boolean`                | `false`             | Reverse frame order          |
+| `frames`   | `string[]`               | —                   | Custom animation frames      |
+
+Variants: `braille_bar`, `braille_bar_dot`, `braille_dot_circle`, `braille_dot_bounce`, `half_circle`, `quarter_circle`, `ascii`, `bar_v`, `bar_h`, `shade`, `arrows`, `arrows2`, `asterix`, `asterix2`, `asterix3`, `asterix4`, `asterix5`.
+
+Helper: `spinnerCreateBackAndForthCharFrames(width, hiChar, loChar, glue?)` — create custom back-and-forth animation frames.
 
 #### `Skeleton`
 
@@ -829,6 +884,30 @@ Responsive data table with paging, row selection, batch actions, and mobile card
 />
 ```
 
+#### `ImageCycler`
+
+Auto-cycling image carousel with fade transitions. Preloads next image before displaying. Supports custom title/description snippets.
+
+| Prop                 | Type                | Default   | Description                              |
+| -------------------- | ------------------- | --------- | ---------------------------------------- |
+| `images`             | `ImageCyclerImage[]`| required  | Array of images to cycle through         |
+| `fit`                | `ImageCyclerFit`    | `"cover"` | CSS object-fit: `"cover"`, `"contain"`, `"fill"` |
+| `minWait`            | `number`            | `3000`    | Minimum wait (ms) before next image      |
+| `transitionDuration` | `number`            | `500`     | Fade transition duration (ms)            |
+| `onclick`            | `(image, index) => void` | —    | Click handler                            |
+| `title`              | `Snippet`           | —         | Custom title snippet `({ image, index, onclick })` |
+| `description`        | `Snippet`           | —         | Custom description snippet               |
+
+```ts
+interface ImageCyclerImage {
+	src: string;
+	alt?: string;
+	title?: string;
+	description?: string;
+	[key: string]: unknown;
+}
+```
+
 #### `ThemePreview`
 
 Theme color swatch preview.
@@ -1215,6 +1294,63 @@ Tooltip display from `aria-label`.
 <button use:tooltip aria-label="Save changes"> Save </button>
 ```
 
+### `createTour` / `tourStep` (onboarding)
+
+Multi-step onboarding tour built on the spotlight primitive. Define steps centrally, attach targets via `use:tourStep`.
+
+**`createTour(options)`**
+
+| Option            | Type                          | Default   | Description                                          |
+| ----------------- | ----------------------------- | --------- | ---------------------------------------------------- |
+| `steps`           | `TourStepDef[]`               | required  | Tour step definitions                                |
+| `waitForElement`  | `number`                      | `500`     | Max wait (ms) for step element to appear             |
+| `labels`          | `TourLabels`                  | defaults  | Default button labels (Next, Back, Skip, Finish)     |
+| `shell`           | `Snippet<[TourShellContext]>` | —         | Custom shell snippet replacing default UI            |
+| `closeOnEscape`   | `boolean`                     | `true`    | Press Escape to skip                                 |
+| `confirmSkip`     | `() => boolean \| Promise<boolean>` | —  | Guard before skipping (return `false` to cancel)     |
+| `storageKey`      | `string`                      | —         | Persist tour completion (skips on re-run)            |
+| `storage`         | `"local" \| "session"`        | `"local"` | Storage backend for persistence                      |
+| `onStart`         | `() => void`                  | —         | Called when tour starts                              |
+| `onEnd`           | `() => void`                  | —         | Called when tour completes                           |
+| `onSkip`          | `() => void`                  | —         | Called when tour is skipped                          |
+| `onStepChange`    | `(step, index) => void`       | —         | Called on every step change                          |
+
+**Returns:** `{ start(), stop(), next(), prev(), skip(), reset(), active, currentStep, currentIndex }`
+
+**`TourStepDef`:**
+
+| Field         | Type                | Description                               |
+| ------------- | ------------------- | ----------------------------------------- |
+| `id`          | `string`            | Unique ID (must match `use:tourStep`)     |
+| `title`       | `string`            | Step title                                |
+| `content`     | `THC`               | Step description (string/html/component)  |
+| `position`    | `SpotlightPosition` | Annotation placement                      |
+| `padding`     | `number`            | Cutout padding (px)                       |
+| `borderRadius`| `number`            | Cutout border radius (px)                 |
+| `onEnter`     | `() => void`        | Called when entering step                  |
+| `onLeave`     | `() => void`        | Called when leaving step                   |
+
+**`tourStep` action:** `use:tourStep={[tour, stepId]}`
+
+```svelte
+<script>
+	import { createTour, tourStep } from "@marianmeres/stuic";
+
+	const tour = createTour({
+		steps: [
+			{ id: "header", title: "Welcome", content: "This is the top." },
+			{ id: "save-btn", title: "Save", content: "Click here to save." },
+		],
+		storageKey: "intro-tour",
+		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>
+```
+
 ---
 
 ## Utilities

package/README.md

@@ -127,7 +127,7 @@ AppShell, Accordion, Backdrop, Modal, ModalDialog, Drawer, Collapsible, SlidingP
 
 ### Forms & Inputs
 
-FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, Fieldset, LoginForm, LoginFormModal
+FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, FieldPhoneNumber, Fieldset, LoginForm, LoginFormModal
 
 ### Buttons & Controls
 
@@ -135,7 +135,7 @@ Button, ButtonGroupRadio, Switch, TwCheck, ListItemButton, X
 
 ### Feedback & Notifications
 
-Notifications, AlertConfirmPrompt, DismissibleMessage, Progress, Spinner, Skeleton
+Notifications, AlertConfirmPrompt, DismissibleMessage, Progress, Spinner (SpinnerCircle, SpinnerCircleOscillate, SpinnerUnicode), Skeleton
 
 ### Navigation & Menus
 
@@ -143,7 +143,7 @@ CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
 
 ### Display & Utility
 
-Avatar, Book, BookResponsive, Carousel, Circle, AnimatedElipsis, H, IconSwap, Separator, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, AssetsPreviewInline, DataTable
+Avatar, Book, BookResponsive, Carousel, Circle, AnimatedElipsis, H, IconSwap, ImageCycler, Separator, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, AssetsPreviewInline, DataTable
 
 ### E-commerce
 
@@ -160,7 +160,7 @@ Cart, Checkout (CheckoutProgress, CheckoutOrderSummary, CheckoutCartReview, Chec
 <div use:fileDropzone={() => ({ onDrop: handleFiles })}>Drop here</div>
 ```
 
-`autogrow` · `validate` · `focusTrap` · `autoscroll` · `dimBehind` · `fileDropzone` · `highlightDragover` · `resizableWidth` · `spotlight` · `trim` · `typeahead` · `onSubmitValidityCheck` · `popover` · `tooltip`
+`autogrow` · `validate` · `focusTrap` · `autoscroll` · `dimBehind` · `fileDropzone` · `highlightDragover` · `resizableWidth` · `spotlight` · `trim` · `typeahead` · `onSubmitValidityCheck` · `popover` · `tooltip` · `createTour` / `tourStep` (onboarding)
 
 ## TypeScript
 

package/dist/components/ImageCycler/ImageCycler.svelte

@@ -0,0 +1,98 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+
+	export interface ImageCyclerImage {
+		src: string;
+		alt?: string;
+		title?: string;
+		description?: string;
+		[key: string]: unknown;
+	}
+
+	export type ImageCyclerFit = "cover" | "contain" | "fill";
+
+	export interface Props {
+		images: ImageCyclerImage[];
+		fit?: ImageCyclerFit;
+		minWait?: number;
+		transitionDuration?: number;
+		onclick?: (image: ImageCyclerImage, index: number) => void;
+		title?: Snippet<[{ image: ImageCyclerImage; index: number; onclick: (() => void) | undefined }]>;
+		description?: Snippet<[{ image: ImageCyclerImage; index: number; onclick: (() => void) | undefined }]>;
+		unstyled?: boolean;
+		class?: string;
+		el?: HTMLElement;
+	}
+</script>
+
+<script lang="ts">
+	import { fade } from "svelte/transition";
+	import { preloadImg } from "../../utils/preload-img.js";
+	import { twMerge } from "../../utils/tw-merge.js";
+
+	let {
+		images,
+		fit = "cover",
+		minWait = 3000,
+		transitionDuration = 500,
+		onclick,
+		title,
+		description,
+		unstyled = false,
+		class: classProp,
+		el = $bindable(),
+	}: Props = $props();
+
+	let currentIndex = $state(0);
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-image-cycler", classProp));
+
+	let _onclick = $derived(onclick ? () => onclick(images[currentIndex], currentIndex) : undefined);
+
+	$effect(() => {
+		const idx = currentIndex;
+		if (images.length <= 1) return;
+		let cancelled = false;
+		const nextIndex = (idx + 1) % images.length;
+		Promise.all([
+			preloadImg({ src: images[nextIndex].src }),
+			new Promise<void>((resolve) => setTimeout(resolve, minWait)),
+		]).then(() => {
+			if (!cancelled) currentIndex = nextIndex;
+		});
+		return () => {
+			cancelled = true;
+		};
+	});
+</script>
+
+<div bind:this={el} class={_class}>
+	{#key currentIndex}
+		<div
+			class="stuic-image-cycler-bg"
+			data-fit={!unstyled ? fit : undefined}
+			style:background-image="url({images[currentIndex].src})"
+			role="img"
+			aria-label={images[currentIndex].alt ?? images[currentIndex].title ?? ""}
+			in:fade={{ duration: transitionDuration }}
+			out:fade={{ duration: transitionDuration }}
+		></div>
+	{/key}
+
+	{#if title || description}
+		{#key currentIndex}
+			<div
+				class="stuic-image-cycler-meta"
+				in:fade={{ duration: transitionDuration }}
+				out:fade={{ duration: transitionDuration }}
+			>
+				{#if title}
+					{@render title({ image: images[currentIndex], index: currentIndex, onclick: _onclick })}
+				{/if}
+				{#if description}
+					{@render description({ image: images[currentIndex], index: currentIndex, onclick: _onclick })}
+				{/if}
+			</div>
+		{/key}
+	{/if}
+</div>

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

@@ -0,0 +1,32 @@
+import type { Snippet } from "svelte";
+export interface ImageCyclerImage {
+    src: string;
+    alt?: string;
+    title?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+export type ImageCyclerFit = "cover" | "contain" | "fill";
+export interface Props {
+    images: ImageCyclerImage[];
+    fit?: ImageCyclerFit;
+    minWait?: number;
+    transitionDuration?: number;
+    onclick?: (image: ImageCyclerImage, index: number) => void;
+    title?: Snippet<[{
+        image: ImageCyclerImage;
+        index: number;
+        onclick: (() => void) | undefined;
+    }]>;
+    description?: Snippet<[{
+        image: ImageCyclerImage;
+        index: number;
+        onclick: (() => void) | undefined;
+    }]>;
+    unstyled?: boolean;
+    class?: string;
+    el?: HTMLElement;
+}
+declare const ImageCycler: import("svelte").Component<Props, {}, "el">;
+type ImageCycler = ReturnType<typeof ImageCycler>;
+export default ImageCycler;

package/dist/components/ImageCycler/index.css

@@ -0,0 +1,28 @@
+:root {
+  --stuic-image-cycler-transition-duration: 500ms;
+}
+
+@layer components {
+  .stuic-image-cycler {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+  }
+
+  .stuic-image-cycler-bg {
+    position: absolute;
+    inset: 0;
+    background-position: center;
+    background-repeat: no-repeat;
+  }
+
+  .stuic-image-cycler-bg[data-fit="cover"]   { background-size: cover; }
+  .stuic-image-cycler-bg[data-fit="contain"] { background-size: contain; }
+  .stuic-image-cycler-bg[data-fit="fill"]    { background-size: 100% 100%; }
+
+  .stuic-image-cycler-meta {
+    position: absolute;
+    inset: 0;
+  }
+}

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

@@ -0,0 +1 @@
+export { default as ImageCycler, type Props as ImageCyclerProps, type ImageCyclerImage, type ImageCyclerFit, } from "./ImageCycler.svelte";

package/dist/components/ImageCycler/index.js

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

package/dist/index.css

@@ -41,6 +41,7 @@ In practice:
 @import "./components/DismissibleMessage/index.css";
 @import "./components/DropdownMenu/index.css";
 @import "./components/H/index.css";
+@import "./components/ImageCycler/index.css";
 @import "./components/IconSwap/index.css";
 @import "./components/Input/index.css";
 @import "./components/KbdShortcut/index.css";

package/dist/index.d.ts

@@ -42,6 +42,7 @@ export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/H/index.js";
+export * from "./components/ImageCycler/index.js";
 export * from "./components/HoverExpandableWidth/index.js";
 export * from "./components/IconSwap/index.js";
 export * from "./components/Input/index.js";

package/dist/index.js

@@ -43,6 +43,7 @@ export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/H/index.js";
+export * from "./components/ImageCycler/index.js";
 export * from "./components/HoverExpandableWidth/index.js";
 export * from "./components/IconSwap/index.js";
 export * from "./components/Input/index.js";

package/docs/architecture.md

@@ -32,19 +32,19 @@ Layer 3: Internal Vars (--_bg, --_text, --_border)
 
 ```
 src/lib/
-├── components/           # 45 UI components
+├── components/           # 46 UI components
 │   └── {Name}/
 │       ├── {Name}.svelte     # Main component
 │       ├── index.ts          # Exports
 │       ├── index.css         # CSS tokens (if styled)
 │       └── README.md         # Documentation
 │
-├── actions/              # 14 Svelte actions
+├── actions/              # 15 Svelte actions
 │   ├── *.svelte.ts           # Reactive actions
 │   ├── *.ts                  # Traditional actions
 │   └── index.ts              # Barrel export
 │
-├── utils/                # 42 utility modules
+├── utils/                # 43 utility modules
 │   ├── *.svelte.ts           # Reactive utilities
 │   ├── *.ts                  # Pure functions
 │   └── index.ts              # Barrel export

package/docs/domains/actions.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-14 Svelte actions (directives) for reusable DOM behavior.
+15 Svelte actions (directives) for reusable DOM behavior.
 
 ---
 
@@ -24,6 +24,7 @@
 | `popover`               | Popover positioning                                           | `popover/`                           |
 | `spotlight`             | Spotlight/coach mark overlay with cutout hole                 | `spotlight/`                         |
 | `tooltip`               | Tooltip positioning and display                               | `tooltip/`                           |
+| `createTour` / `tourStep` | Multi-step onboarding tour (built on spotlight)             | `onboarding/`                        |
 
 ---
 
@@ -115,6 +116,28 @@ Actions using `$effect()` accept a function returning options:
 <button use:tooltip={{ content: "Save changes", position: "top" }}> Save </button>
 ```
 
+### Onboarding Tour
+
+```svelte
+<script>
+	import { createTour, tourStep } from "@marianmeres/stuic";
+
+	const tour = createTour({
+		steps: [
+			{ id: "header", title: "Welcome", content: "This is the top." },
+			{ id: "save-btn", title: "Save", 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>
+```
+
+Features: step navigation (next/prev/skip), persistent state via `storageKey`, custom shell snippets, `confirmSkip` callback, wait-for-element mechanism, Escape key support, step lifecycle callbacks (`onEnter`/`onLeave`).
+
 ---
 
 ## Action File Patterns
@@ -163,3 +186,4 @@ export function focusTrap(el: HTMLElement, options?: Options) {
 | src/lib/actions/dim-behind/        | Simplified spotlight alternative |
 | src/lib/actions/spotlight/         | Spotlight/coach mark action      |
 | src/lib/actions/tooltip/           | Multi-file action example        |
+| src/lib/actions/onboarding/        | Multi-step onboarding tour       |

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-45 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+46 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -39,18 +39,22 @@
 
 | Component          | Purpose                               |
 | ------------------ | ------------------------------------- |
-| Notifications      | Toast notification system             |
-| AlertConfirmPrompt | Dialog factory (alert/confirm/prompt) |
-| DismissibleMessage | Closeable message banner              |
-| Progress           | Progress bar                          |
-| Spinner            | Loading indicator                     |
-| Skeleton           | Loading placeholder                   |
+| Notifications              | Toast notification system                                     |
+| AlertConfirmPrompt         | Dialog factory (alert/confirm/prompt)                         |
+| DismissibleMessage         | Closeable message banner                                      |
+| Progress                   | Progress bar                                                  |
+| Spinner                    | Loading indicator (default SVG spinner)                       |
+| SpinnerCircle              | CSS-only circular spinner with thickness/direction options     |
+| SpinnerCircleOscillate     | Animated Circle-based spinner with oscillating completeness   |
+| SpinnerUnicode             | Unicode character frame animation (17 variants)               |
+| Skeleton                   | Loading placeholder                                           |
 
 ### Form
 
 | Component                             | Purpose                                           |
 | ------------------------------------- | ------------------------------------------------- |
 | Input (FieldInput, FieldSelect, etc.) | Form fields                                       |
+| FieldPhoneNumber                      | International phone input with country picker      |
 | FieldObject                           | Dual-mode JSON object editor (pretty-print/raw)   |
 | Fieldset                              | Field grouping with legend                        |
 | FieldKeyValues                        | Key-value pair editor                             |
@@ -78,6 +82,7 @@
 | Separator       | Horizontal/vertical separator line                                  |
 | Thc             | Flexible renderer for text, HTML, components, or snippets           |
 | X               | Styled close/multiply SVG icon                                      |
+| ImageCycler     | Auto-cycling image carousel with fade transitions and preloading    |
 
 ### E-commerce
 

package/package.json

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