@marianmeres/stuic 3.96.0 → 3.97.0

package/AGENTS.md

@@ -23,15 +23,16 @@
 
 ```
 src/lib/
-├── components/     # 56 UI components
+├── components/     # 57 component directories
 ├── actions/        # 15 Svelte actions
-├── utils/          # 43 utility modules
-├── themes/         # Generated theme CSS (css/) — definitions from @marianmeres/design-tokens
-├── icons/          # Icon re-exports
+├── utils/          # 44 utility modules
+├── icons/          # Icon re-exports from @marianmeres/icons-fns
 ├── index.css       # Centralized CSS imports
 └── index.ts        # Main exports
 ```
 
+Theme CSS files are not bundled in this package — they're provided by `@marianmeres/design-tokens/css/*.css` (42 themes) and imported by `src/lib/index.css`.
+
 ---
 
 ## Critical Conventions
@@ -116,10 +117,10 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 
 ### Domain Docs
 
-- [Components](./docs/domains/components.md) — 56 component directories, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 57 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [Actions](./docs/domains/actions.md) — 15 Svelte directives
-- [Utils](./docs/domains/utils.md) — 43 utility modules
+- [Utils](./docs/domains/utils.md) — 44 utility modules
 
 ### Reference
 

package/API.md

@@ -132,20 +132,41 @@ Navigation wrapper component.
 
 #### `Header`
 
-Responsive navigation header with logo, nav items, avatar, and automatic hamburger collapse. Renders as `<header>`.
-
-| Prop                | Type              | Default               | Description                        |
-| ------------------- | ----------------- | --------------------- | ---------------------------------- |
-| `logo`              | `Snippet`         | —                     | Logo/brand snippet                 |
-| `projectName`       | `string`          | —                     | Simple text logo alternative       |
-| `items`             | `HeaderNavItem[]` | `[]`                  | Navigation items                   |
-| `avatar`            | `Snippet`         | —                     | Avatar snippet (far right)         |
-| `avatarOnClick`     | `() => void`      | —                     | Avatar click handler               |
-| `collapseThreshold` | `number`          | `768`                 | Width (px) to collapse; 0 disables |
-| `fixed`             | `boolean`         | `false`               | Fixed positioning at top           |
-| `isCollapsed`       | `boolean`         | —                     | Bindable: collapsed state          |
-| `isMenuOpen`        | `boolean`         | —                     | Bindable: hamburger menu open      |
-| `onSelect`          | `(item) => void`  | —                     | Item selection callback            |
+Responsive navigation header with leading slot, logo, nav items, locale switcher, action icon buttons, avatar, and configurable responsive collapse (`"hamburger"` fold or `"hide"` for app-like shells). Renders as `<header>`.
+
+| Prop                    | Type                                      | Default                | Description                                                                                                          |
+| ----------------------- | ----------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `leading`               | `Snippet<[{ isCollapsed }]>`              | —                      | Leading (left-side) slot. Overrides `leadingHamburger`.                                                              |
+| `leadingHamburger`      | `boolean \| "collapsed"`                  | `false`                | Built-in hamburger in the leading slot (`"collapsed"` = only below threshold). Ignored when `leading` is provided.   |
+| `onLeadingHamburger`    | `() => void`                              | —                      | Click handler for the built-in leading hamburger (typically opens a drawer).                                          |
+| `leadingHamburgerIcon`  | `THC`                                     | menu icon              | Icon override for the built-in leading hamburger.                                                                     |
+| `leadingHamburgerLabel` | `string`                                  | `"Open menu"`          | Aria-label for the leading hamburger.                                                                                 |
+| `logo`                  | `Snippet`                                 | —                      | Logo/brand snippet.                                                                                                   |
+| `projectName`           | `string`                                  | —                      | Simple text logo alternative.                                                                                         |
+| `navVariant`            | `ButtonVariant`                           | `"ghost"`              | Button variant for nav items and the locale switcher trigger.                                                         |
+| `items`                 | `HeaderNavItem[]`                         | `[]`                   | Navigation items — inline when expanded, dropdown when collapsed (hamburger mode).                                    |
+| `actions`               | `HeaderActionItem[]`                      | `[]`                   | Action icon buttons between the locale switcher and the avatar. Always visible — never fold into the dropdown.        |
+| `onActionSelect`        | `(action) => void`                        | —                      | Called after the per-item `onclick`.                                                                                  |
+| `avatar`                | `Snippet`                                 | —                      | Avatar snippet (far right).                                                                                           |
+| `avatarOnClick`         | `() => void`                              | —                      | Makes the avatar interactive. In `"hamburger"` collapse mode it moves into the dropdown.                              |
+| `avatarLabel`           | `THC`                                     | `"Account"`            | Label for the avatar entry inside the collapsed dropdown.                                                             |
+| `locales`               | `HeaderLocaleItem[]`                      | `[]`                   | Locale items. Switcher only renders when 2+.                                                                          |
+| `activeLocale`          | `string`                                  | —                      | Current locale id.                                                                                                    |
+| `onLocaleChange`        | `(localeId) => void`                      | —                      | Locale selection callback.                                                                                            |
+| `localeLabel`           | `THC`                                     | `"Language"`           | Section header inside the collapsed dropdown.                                                                         |
+| `contentMaxWidth`       | `string \| number`                        | —                      | Max-width of the inner content row (outer header stays 100%). Accepts any CSS length. Maps to `--stuic-header-content-max-width`. |
+| `collapseThreshold`     | `number`                                  | `768`                  | Width (px) to collapse; 0 disables.                                                                                   |
+| `collapseMode`          | `"hamburger" \| "hide"`                   | `"hamburger"`          | Collapse behavior. `"hide"` keeps avatar/actions visible and renders no trailing hamburger (app-shell pattern).        |
+| `keepLocaleOnCollapse`  | `boolean`                                 | `false`                | Keep the locale switcher visible in collapsed mode (only `collapseMode === "hide"`).                                   |
+| `fixed`                 | `boolean`                                 | `false`                | Fixed positioning at the top.                                                                                         |
+| `isCollapsed`           | `boolean`                                 | —                      | Bindable: collapsed state.                                                                                            |
+| `isMenuOpen`            | `boolean`                                 | —                      | Bindable: hamburger menu open.                                                                                        |
+| `dropdownPosition`      | `DropdownMenuPosition`                    | `"bottom-span-right"`  | Position of the collapsed dropdown.                                                                                   |
+| `iconSize`              | `number`                                  | `24`                   | Hamburger/X icon size in px.                                                                                          |
+| `onSelect`              | `(item) => void`                          | —                      | Item selection callback (both modes).                                                                                 |
+| `children`              | `Snippet<[{ isCollapsed, items, offsetWidth }]>` | —              | Escape hatch: override the entire inner layout.                                                                       |
+
+Class slots: `class`, `classContent`, `classLeading`, `classLeadingHamburger`, `classLogo`, `classNav`, `classNavItem`, `classNavItemActive`, `classActions`, `classAction`, `classActionActive`, `classEnd`, `classAvatar`, `classLocale`, `classHamburger`, `classDropdown`.
 
 ```svelte
 <Header
@@ -159,11 +180,32 @@ Responsive navigation header with logo, nav items, avatar, and automatic hamburg
 		<Avatar src="/me.jpg" alt="User" />
 	{/snippet}
 </Header>
+
+<!-- App-shell pattern: avatar + actions stay visible in collapsed mode,
+     nav items hide, leading hamburger opens a drawer. -->
+<Header
+	projectName="App"
+	items={navItems}
+	actions={[
+		{ id: "search", icon: { html: iconSearch() }, label: "Search", onclick: openSearch },
+		{ id: "cart", icon: { html: iconCart() }, label: "Cart", onclick: openCart },
+	]}
+	collapseMode="hide"
+	leadingHamburger="collapsed"
+	onLeadingHamburger={() => (drawerOpen = true)}
+	avatarOnClick={() => goto("/me")}
+>
+	{#snippet avatar()}<Avatar initials="MM" autoColor />{/snippet}
+</Header>
 ```
 
-**HeaderNavItem:** `{ id, label, href?, onclick?, icon?, active?, disabled?, class? }`
+**HeaderNavItem:** `{ id, label, href?, target?, onclick?, icon?, active?, disabled?, class? }`
+
+**HeaderActionItem:** `{ id, icon?, label, onclick?, href?, target?, active?, disabled?, class?, render? }` — `render` is an optional `Snippet<[{ action, class, isCollapsed, onclick }]>` that replaces the default `<Button>` for that action (useful for wrapping in a popover/tooltip directive or adding a count badge while keeping default positioning).
 
-CSS tokens: `--stuic-header-padding-x`, `--stuic-header-padding-y`, `--stuic-header-gap`, `--stuic-header-min-height`, `--stuic-header-nav-gap`, `--stuic-header-bg`, `--stuic-header-text`, `--stuic-header-border-width`, `--stuic-header-border-color`, `--stuic-header-nav-item-bg-active`, `--stuic-header-nav-item-text-active`, `--stuic-header-z-index`.
+**HeaderLocaleItem:** `{ id, label }`
+
+CSS tokens: `--stuic-header-padding-x`, `--stuic-header-padding-y`, `--stuic-header-gap`, `--stuic-header-min-height`, `--stuic-header-nav-gap`, `--stuic-header-content-max-width`, `--stuic-header-bg`, `--stuic-header-text`, `--stuic-header-border-width`, `--stuic-header-border-color`, `--stuic-header-nav-item-bg-active`, `--stuic-header-nav-item-text-active`, `--stuic-header-z-index`.
 
 ---
 
@@ -334,6 +376,38 @@ International phone number input with country dial code picker. Parses and compo
 
 Exports: `FieldPhoneNumber`, `FieldPhoneNumberProps`, `validatePhoneNumber`, `Country`.
 
+#### `FieldCountry`
+
+Country picker dropdown with searchable, optionally flag-prefixed list. Submits a country ISO alpha-2 code via a hidden input. Pairs naturally with `FieldPhoneNumber` and with checkout/address forms.
+
+| Prop                 | Type                              | Default     | Description                                                                |
+| -------------------- | --------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| `value`              | `string`                          | `""`        | Bindable ISO alpha-2 code (e.g. `"SK"`). Empty = unselected.               |
+| `onChange`           | `(iso: string) => void`           | —           | Called when selection changes.                                             |
+| `countryList`        | `Country[] \| string[]`           | all         | Restrict the list to specific countries (objects or ISO codes).            |
+| `preferredCountries` | `string[]`                        | —           | ISO codes pinned at the top of the dropdown.                               |
+| `countryNames`       | `Record<string, string>`          | English     | Override displayed country names (keyed by ISO code).                      |
+| `flags`              | `boolean`                         | `true`      | Show country flag emoji.                                                   |
+| `name`               | `string`                          | —           | Hidden input name (enables form submission + native validation).           |
+| `placeholder`        | `string`                          | —           | Trigger placeholder text when nothing is selected.                         |
+| `required`           | `boolean`                         | `false`     | Required indicator + validation.                                           |
+| `disabled`           | `boolean`                         | `false`     | Disable the trigger and dropdown.                                          |
+| `validate`           | `boolean \| ValidateOptions`      | enabled     | Validation behavior (default-on, see Imperative validate API).             |
+
+Integrates with `InputWrap` — supports `label`, `description`, `renderSize`, `labelLeft`, `labelLeftWidth`, `labelLeftBreakpoint`, `inputBefore`, `inputAfter`, `inputBelow`, `below`, `classInput`, `classDropdown`.
+
+```svelte
+<FieldCountry
+	bind:value={address.country}
+	name="country"
+	label="Country"
+	preferredCountries={["SK", "CZ", "AT", "DE"]}
+	required
+/>
+```
+
+Exports: `FieldCountry`, `FieldCountryProps`, `Country`, `COUNTRIES`, `ISO_MAP`.
+
 #### `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.

package/README.md

@@ -148,7 +148,7 @@ AppShell, Accordion, Backdrop, Modal, ModalDialog, Drawer, Collapsible, Header,
 
 ### Forms & Inputs
 
-FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, FieldPhoneNumber, CronInput, Fieldset, LoginForm, LoginFormModal, RegisterForm, LoginOrRegisterForm, LoginOrRegisterFormModal, EmailVerifyForm, OtpInput
+FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, FieldPhoneNumber, FieldCountry, CronInput, Fieldset, LoginForm, LoginFormModal, RegisterForm, RegisterFormModal, LoginOrRegisterForm, LoginOrRegisterFormModal, EmailVerifyForm, OtpInput
 
 ### Buttons & Controls
 

package/dist/components/Header/Header.svelte

@@ -40,8 +40,10 @@
 	export interface HeaderActionItem {
 		/** Unique identifier */
 		id: string | number;
-		/** Icon — THC (string/html/component/snippet). The visible content. */
-		icon: THC;
+		/** Icon — THC (string/html/component/snippet). The visible content.
+		 *  Required for the default rendering; ignored when `render` is provided
+		 *  (the snippet owns its own DOM). */
+		icon?: THC;
 		/** Accessible label (aria-label). */
 		label: THC;
 		/** Click handler */
@@ -56,6 +58,31 @@
 		disabled?: boolean;
 		/** Additional CSS classes */
 		class?: string;
+		/** Optional custom renderer. When provided, replaces the default
+		 *  `<Button>` rendering for this action. The Header still owns
+		 *  positioning (slot in the actions row) and the collapse decision.
+		 *
+		 *  Use this when an action needs custom DOM around its trigger —
+		 *  e.g. a popover/tooltip directive, or a count/dot badge overlay.
+		 *
+		 *  Snippet args:
+		 *  - `action`     — the item itself (lets a snippet be reused across items)
+		 *  - `class`      — the same merged class the default `<Button>` would receive,
+		 *                   so consumers can opt into the default look
+		 *  - `isCollapsed`— current collapse state
+		 *  - `onclick`    — pre-wired handler that calls `action.onclick` and
+		 *                   `onActionSelect`; consumers can wire it to their
+		 *                   button or ignore it. */
+		render?: Snippet<
+			[
+				{
+					action: HeaderActionItem;
+					class: string;
+					isCollapsed: boolean;
+					onclick: () => void;
+				},
+			]
+		>;
 	}
 
 	/** Collapse behavior when the header drops below `collapseThreshold`:
@@ -559,26 +586,38 @@
 			{#if actions.length > 0}
 				<div class={_classActions}>
 					{#each actions as action (action.id)}
-						<Button
-							variant="ghost"
-							iconButton
-							size="sm"
-							href={action.href}
-							target={action.target}
-							disabled={action.disabled}
-							{unstyled}
-							class={twMerge(
-								!unstyled && HEADER_ACTION_CLASSES,
-								!unstyled && action.active && classActionActive,
-								classAction,
-								action.class
-							)}
-							data-active={!unstyled && action.active ? "" : undefined}
-							aria-label={typeof action.label === "string" ? action.label : undefined}
-							onclick={() => handleActionClick(action)}
-						>
-							<Thc thc={action.icon} />
-						</Button>
+						{@const actionClass = twMerge(
+							!unstyled && HEADER_ACTION_CLASSES,
+							!unstyled && action.active && classActionActive,
+							classAction,
+							action.class
+						)}
+						{#if action.render}
+							{@render action.render({
+								action,
+								class: actionClass,
+								isCollapsed: _isCollapsed,
+								onclick: () => handleActionClick(action),
+							})}
+						{:else}
+							<Button
+								variant="ghost"
+								iconButton
+								size="sm"
+								href={action.href}
+								target={action.target}
+								disabled={action.disabled}
+								{unstyled}
+								class={actionClass}
+								data-active={!unstyled && action.active ? "" : undefined}
+								aria-label={typeof action.label === "string" ? action.label : undefined}
+								onclick={() => handleActionClick(action)}
+							>
+								{#if action.icon !== undefined}
+									<Thc thc={action.icon} />
+								{/if}
+							</Button>
+						{/if}
 					{/each}
 				</div>
 			{/if}

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

@@ -32,8 +32,10 @@ export interface HeaderLocaleItem {
 export interface HeaderActionItem {
     /** Unique identifier */
     id: string | number;
-    /** Icon — THC (string/html/component/snippet). The visible content. */
-    icon: THC;
+    /** Icon — THC (string/html/component/snippet). The visible content.
+     *  Required for the default rendering; ignored when `render` is provided
+     *  (the snippet owns its own DOM). */
+    icon?: THC;
     /** Accessible label (aria-label). */
     label: THC;
     /** Click handler */
@@ -48,6 +50,29 @@ export interface HeaderActionItem {
     disabled?: boolean;
     /** Additional CSS classes */
     class?: string;
+    /** Optional custom renderer. When provided, replaces the default
+     *  `<Button>` rendering for this action. The Header still owns
+     *  positioning (slot in the actions row) and the collapse decision.
+     *
+     *  Use this when an action needs custom DOM around its trigger —
+     *  e.g. a popover/tooltip directive, or a count/dot badge overlay.
+     *
+     *  Snippet args:
+     *  - `action`     — the item itself (lets a snippet be reused across items)
+     *  - `class`      — the same merged class the default `<Button>` would receive,
+     *                   so consumers can opt into the default look
+     *  - `isCollapsed`— current collapse state
+     *  - `onclick`    — pre-wired handler that calls `action.onclick` and
+     *                   `onActionSelect`; consumers can wire it to their
+     *                   button or ignore it. */
+    render?: Snippet<[
+        {
+            action: HeaderActionItem;
+            class: string;
+            isCollapsed: boolean;
+            onclick: () => void;
+        }
+    ]>;
 }
 /** Collapse behavior when the header drops below `collapseThreshold`:
  *  - "hamburger": nav items fold into a trailing dropdown along with the

package/dist/components/Header/README.md

@@ -0,0 +1,35 @@
+# Header
+
+Top-bar component with leading slot, project logo, nav items, locale switcher, optional action buttons, avatar, and responsive collapse (either fold into a trailing hamburger dropdown OR hide nav entirely).
+
+## Examples
+
+### App-like collapse: avatar + actions visible, everything else hidden
+
+Common "app shell" pattern: when the header collapses below `collapseThreshold`, the avatar and a few key actions (search, notifications, cart…) remain visible, the trailing hamburger is NOT shown, and the nav items + locale switcher are hidden entirely (the nav typically lives in a drawer triggered by the leading hamburger instead).
+
+| Requirement | Where it's handled | How |
+| --- | --- | --- |
+| **Avatar stays visible** | [Header.svelte:626](./Header.svelte#L626) — `{#if avatar && !(_isCollapsed && _avatarInDropdown)}` | `_avatarInDropdown` requires `collapseMode === "hamburger"`. In `"hide"` mode it's always `false`, so the avatar always renders. |
+| **Action buttons stay visible** | [Header.svelte:585](./Header.svelte#L585) — `<!-- Actions (icon buttons, always visible) -->` | The actions loop has no collapse gating — items render in both modes. |
+| **No trailing hamburger** | [Header.svelte:642](./Header.svelte#L642) — `{#if _isCollapsed && _dropdownItems.length > 0}` | In `"hide"` mode, `_dropdownItems` short-circuits to `[]`, so the `{#if}` is false → no trailing hamburger. |
+| **Nav items hidden** | [Header.svelte:516](./Header.svelte#L516) — `{#if !_isCollapsed && items.length > 0}` | Inline nav requires `!_isCollapsed`; combined with the empty `_dropdownItems` above, items don't reappear in a dropdown either. |
+| **Locale hidden** | [Header.svelte:335](./Header.svelte#L335) — `!_isCollapsed \|\| (collapseMode === "hide" && keepLocaleOnCollapse)` | Default `keepLocaleOnCollapse={false}` hides the locale switcher in collapsed mode. |
+
+Minimal config:
+
+```svelte
+<Header
+    projectName="App"
+    items={navItems}            <!-- shown expanded, hidden collapsed -->
+    actions={[...]}             <!-- always visible -->
+    collapseMode="hide"         <!-- no trailing hamburger; avatar stays -->
+    leadingHamburger            <!-- optional: drives a drawer for the hidden nav -->
+    onLeadingHamburger={() => (drawerOpen = true)}
+    {locales} {activeLocale}    <!-- hidden in collapsed (keepLocaleOnCollapse defaults to false) -->
+    onLocaleChange={(id) => (activeLocale = id)}
+    avatarOnClick={() => alert("Profile")}  <!-- safe in "hide" mode — won't move into dropdown -->
+>
+    {#snippet avatar()}<Avatar initials="MM" autoColor />{/snippet}
+</Header>
+```

package/dist/components/Header/index.css

@@ -21,6 +21,29 @@
 	/* Actions (icon buttons in the end region) */
 	--stuic-header-actions-gap: 0.25rem;
 
+	/* Hamburger offsets — outdent the built-in hamburger buttons on both
+	   inline sides so the *icon* (not the invisible iconButton hit area)
+	   sits flush with the header's content padding on one side and tightens
+	   against its neighbor (logo / avatar) on the other side. The flex
+	   `gap` between header regions kicks in *after* the button's invisible
+	   padding, so without these the perceived gap is `--stuic-header-gap` +
+	   one button padding.
+	   Default magnitude is derived from the iconButton's own padding so the
+	   alignment stays correct if button padding ever changes. Set to 0 to
+	   disable; override each side independently if needed. */
+	--stuic-header-leading-hamburger-offset-inline-start: calc(
+		-1 * var(--stuic-button-padding-y-sm)
+	);
+	--stuic-header-leading-hamburger-offset-inline-end: calc(
+		-1 * var(--stuic-button-padding-y-sm)
+	);
+	--stuic-header-trailing-hamburger-offset-inline-start: calc(
+		-1 * var(--stuic-button-padding-y-sm)
+	);
+	--stuic-header-trailing-hamburger-offset-inline-end: calc(
+		-1 * var(--stuic-button-padding-y-sm)
+	);
+
 	/* Project name */
 	--stuic-header-project-name-font-weight: var(--font-weight-semibold, 600);
 
@@ -79,7 +102,12 @@
 	}
 
 	.stuic-header-leading-hamburger {
-		/* Ghost Button handles hover/focus — only override sizing if needed */
+		/* Outdent on both inline sides so the icon (not the iconButton hit
+		   area) aligns with the header's content padding on the start and
+		   tightens against the logo on the end. Override each side via its
+		   own token. */
+		margin-inline-start: var(--stuic-header-leading-hamburger-offset-inline-start);
+		margin-inline-end: var(--stuic-header-leading-hamburger-offset-inline-end);
 	}
 
 	/* ============================================================================
@@ -214,6 +242,11 @@
 	   ============================================================================ */
 
 	.stuic-header-hamburger {
-		/* Ghost Button handles hover/focus — only override sizing */
+		/* Symmetric counterpart to the leading hamburger — outdent on both
+		   inline sides so the icon tightens against its left neighbor
+		   (avatar) on the start and aligns with the header's content padding
+		   on the end. Override each side via its own token. */
+		margin-inline-start: var(--stuic-header-trailing-hamburger-offset-inline-start);
+		margin-inline-end: var(--stuic-header-trailing-hamburger-offset-inline-end);
 	}
 }

package/dist/components/IconSwap/README.md

@@ -0,0 +1,69 @@
+# IconSwap
+
+Cross-fades between N visual states (HTML strings or Snippets) at a single position. Commonly used for hamburger ⇄ X toggles, play ⇄ pause, sun ⇄ moon, etc. Respects `prefers-reduced-motion` (animation duration is forced to 0).
+
+## Props
+
+| Prop         | Type                       | Default  | Description                                                                |
+| ------------ | -------------------------- | -------- | -------------------------------------------------------------------------- |
+| `states`     | `Array<string \| Snippet>` | required | The visual states to swap between. Strings are rendered with `{@html}`.    |
+| `active`     | `number`                   | `0`      | Bindable index of the currently visible state.                              |
+| `duration`   | `number`                   | `300`    | Transition duration in ms. Set `0` to disable.                              |
+| `easing`     | `string`                   | `"ease"` | CSS `transition-timing-function`.                                           |
+| `unstyled`   | `boolean`                  | `false`  | Skip default styling.                                                       |
+| `class`      | `string`                   | -        | Additional CSS classes for the root `<span>`.                              |
+| `stateClass` | `string`                   | -        | Additional CSS classes for each state wrapper.                              |
+| `el`         | `HTMLSpanElement`          | -        | Bindable root element.                                                      |
+
+## Usage
+
+### Hamburger ⇄ X
+
+```svelte
+<script lang="ts">
+	import { IconSwap, iconMenu, iconX } from "@marianmeres/stuic";
+
+	let isOpen = $state(false);
+</script>
+
+<button onclick={() => (isOpen = !isOpen)}>
+	<IconSwap active={isOpen ? 1 : 0} states={[iconMenu(), iconX()]} />
+</button>
+```
+
+### With snippets
+
+```svelte
+<IconSwap active={tab}>
+	{#snippet states_0()}<span>A</span>{/snippet}
+	{#snippet states_1()}<strong>B</strong>{/snippet}
+	{#snippet states_2()}<em>C</em>{/snippet}
+</IconSwap>
+
+<!-- equivalent with an array of snippets -->
+<IconSwap active={tab} states={[stateA, stateB, stateC]} />
+```
+
+### Custom easing/duration
+
+```svelte
+<IconSwap states={frames} active={i} duration={500} easing="cubic-bezier(0.4, 0, 0.2, 1)" />
+```
+
+## CSS Variables
+
+| Variable                      | Default | Description                |
+| ----------------------------- | ------- | -------------------------- |
+| `--stuic-icon-swap-duration`  | (prop)  | Transition duration         |
+| `--stuic-icon-swap-easing`    | (prop)  | Transition timing function  |
+
+## Data Attributes
+
+- `data-active` (root) — current active index
+- `data-visible="true"` (state wrapper) — present on the visible state
+
+## Behavior
+
+- All states render concurrently; the inactive ones have `opacity: 0` and `aria-hidden="true"`.
+- The root is positioned so all states stack at the same coordinates.
+- `active` is clamped to `[0, states.length - 1]`.

package/dist/components/ImageCycler/README.md

@@ -0,0 +1,83 @@
+# ImageCycler
+
+Auto-cycling background-image carousel with fade transitions. Preloads the next image before swapping, so transitions never reveal a half-loaded asset. Optional `title` and `description` snippets render an absolutely-positioned meta layer on top of the image.
+
+## Props
+
+| Prop                 | Type                                                              | Default   | Description                                                            |
+| -------------------- | ----------------------------------------------------------------- | --------- | ---------------------------------------------------------------------- |
+| `images`             | `ImageCyclerImage[]`                                              | required  | Images to cycle through.                                               |
+| `fit`                | `"cover" \| "contain" \| "fill"`                                  | `"cover"` | Background-size mode. Set via `data-fit` on the image layer.            |
+| `minWait`            | `number`                                                          | `3000`    | Minimum wait (ms) on each image before advancing.                       |
+| `transitionDuration` | `number`                                                          | `500`     | Fade duration in ms (for both the image and the meta layer).            |
+| `onclick`            | `(image, index) => void`                                          | -         | Click handler. The snippets receive a forwarded version.                |
+| `title`              | `Snippet<[{ image, index, onclick }]>`                            | -         | Title overlay snippet.                                                  |
+| `description`        | `Snippet<[{ image, index, onclick }]>`                            | -         | Description overlay snippet.                                            |
+| `unstyled`           | `boolean`                                                         | `false`   | Skip default styling.                                                   |
+| `class`              | `string`                                                          | -         | Additional CSS classes.                                                 |
+| `el`                 | `HTMLElement`                                                     | -         | Bindable root element.                                                  |
+
+## `ImageCyclerImage`
+
+```ts
+interface ImageCyclerImage {
+	src: string;
+	alt?: string;
+	title?: string;
+	description?: string;
+	[key: string]: unknown; // arbitrary extra fields are preserved
+}
+```
+
+## Usage
+
+### Minimal
+
+```svelte
+<script lang="ts">
+	import { ImageCycler } from "@marianmeres/stuic";
+
+	const slides = [
+		{ src: "/hero/a.jpg", alt: "A" },
+		{ src: "/hero/b.jpg", alt: "B" },
+		{ src: "/hero/c.jpg", alt: "C" },
+	];
+</script>
+
+<div style="aspect-ratio: 16/9;">
+	<ImageCycler images={slides} />
+</div>
+```
+
+### With overlay + click
+
+```svelte
+<ImageCycler
+	images={slides}
+	minWait={5000}
+	transitionDuration={800}
+	onclick={(img, i) => console.log("clicked", i, img)}
+>
+	{#snippet title({ image, onclick })}
+		<button type="button" {onclick} class="absolute bottom-12 left-6 text-white">
+			{image.title}
+		</button>
+	{/snippet}
+	{#snippet description({ image })}
+		<p class="absolute bottom-4 left-6 text-white/80">{image.description}</p>
+	{/snippet}
+</ImageCycler>
+```
+
+## CSS Variables
+
+| Variable                                    | Default | Description           |
+| ------------------------------------------- | ------- | --------------------- |
+| `--stuic-image-cycler-transition-duration`  | `500ms` | (informational; the active transition duration comes from the `transitionDuration` prop) |
+
+## Notes
+
+- The root has `position: relative; overflow: hidden`. The parent must define a height (`aspect-ratio`, fixed height, etc.) since the image layer is absolutely positioned.
+- Only the next image is preloaded; earlier images aren't kept warm.
+- A single-image `images` array disables the cycler effect.
+- The `aria-label` for the background layer falls back to `alt → title → ""`.