@marianmeres/stuic 3.95.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

@@ -37,17 +37,95 @@
 		label: THC;
 	}
 
+	export interface HeaderActionItem {
+		/** Unique identifier */
+		id: string | number;
+		/** 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 */
+		onclick?: () => void;
+		/** Render as a link instead of a button */
+		href?: string;
+		/** Link target (e.g., "_blank"). Only relevant when href is set. */
+		target?: string;
+		/** Active state styling (e.g., when a panel triggered by this action is open) */
+		active?: boolean;
+		/** Whether this action is disabled */
+		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
+	 *    locale switcher and an interactive avatar.
+	 *  - "hide": nav items are hidden entirely. No trailing hamburger renders.
+	 *    Avatar stays visible. Locale visibility is controlled by
+	 *    `keepLocaleOnCollapse`. */
+	export type HeaderCollapseMode = "hamburger" | "hide";
+
+	/** Visibility for the built-in leading hamburger button:
+	 *  - false/undefined: not rendered
+	 *  - true: always rendered
+	 *  - "collapsed": only rendered when the header is below the collapse threshold */
+	export type HeaderLeadingHamburger = boolean | "collapsed";
+
 	export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+		/** Leading (left-side) slot. Renders before the logo/title.
+		 *  Use for a hamburger button, back arrow, breadcrumbs, etc.
+		 *  When provided, overrides the built-in `leadingHamburger`. */
+		leading?: Snippet<[{ isCollapsed: boolean }]>;
+		/** Convenience: render a built-in hamburger button in the leading slot.
+		 *  Ignored when the `leading` snippet is provided. */
+		leadingHamburger?: HeaderLeadingHamburger;
+		/** Click handler for the built-in leading hamburger (typically opens a drawer) */
+		onLeadingHamburger?: () => void;
+		/** Icon for the built-in leading hamburger (defaults to a menu icon) */
+		leadingHamburgerIcon?: THC;
+		/** Aria-label for the built-in leading hamburger (defaults to "Open menu") */
+		leadingHamburgerLabel?: string;
 		/** Logo/brand snippet — full control over the left branding area */
 		logo?: Snippet;
-		/** Horizontal alignment of the nav items in expanded mode */
-		navAlign?: "left" | "right";
 		/** Button variant for nav items and locale trigger (defaults to "ghost") */
 		navVariant?: ButtonVariant;
 		/** Simple text alternative to the logo snippet */
 		projectName?: string;
 		/** Navigation items — inline when expanded, DropdownMenu when collapsed */
 		items?: HeaderNavItem[];
+		/** Action icon buttons displayed between the locale switcher and the avatar.
+		 *  Always visible — they do not fold into the trailing dropdown. */
+		actions?: HeaderActionItem[];
+		/** Called when an action is selected (in addition to the per-item onclick) */
+		onActionSelect?: (action: HeaderActionItem) => void;
 		/** Avatar/user snippet — rendered at the far right */
 		avatar?: Snippet;
 		/** When provided, makes the avatar interactive. In expanded mode wraps it in a
@@ -63,8 +141,21 @@
 		onLocaleChange?: (localeId: string) => void;
 		/** Section header label for locales in collapsed dropdown (defaults to "Language") */
 		localeLabel?: THC;
+		/** Max-width of the inner content row. The outer `<header>` stays 100%
+		 *  wide (background fills the parent); the inner content is centered and
+		 *  capped at this value. Accepts any CSS length: "1024px", "72rem",
+		 *  "100%", "none". Default: undefined → unbounded.
+		 *  Equivalent global override:
+		 *  `:root { --stuic-header-content-max-width: 72rem; }` */
+		contentMaxWidth?: string | number;
 		/** Element width (px) below which nav collapses to hamburger. 0 to disable. */
 		collapseThreshold?: number;
+		/** Collapse behavior when below threshold (defaults to "hamburger") */
+		collapseMode?: HeaderCollapseMode;
+		/** When `collapseMode === "hide"`, keep the locale switcher visible in
+		 *  collapsed mode. No effect when `collapseMode === "hamburger"`
+		 *  (locale already folds into the trailing dropdown there). */
+		keepLocaleOnCollapse?: boolean;
 		/** Fixed positioning (top of viewport) */
 		fixed?: boolean;
 		/** Bindable: whether the header is currently in collapsed (hamburger) mode */
@@ -81,6 +172,12 @@
 		unstyled?: boolean;
 		/** Additional CSS classes for the root <header> */
 		class?: string;
+		/** Classes for the inner content wrapper */
+		classContent?: string;
+		/** Classes for the leading area */
+		classLeading?: string;
+		/** Classes for the built-in leading hamburger button */
+		classLeadingHamburger?: string;
 		/** Classes for the logo area */
 		classLogo?: string;
 		/** Classes for the nav area (expanded mode) */
@@ -89,13 +186,19 @@
 		classNavItem?: string;
 		/** Classes for active nav items */
 		classNavItemActive?: string;
-		/** Classes for the end area (avatar + hamburger) */
+		/** Classes for the actions wrapper */
+		classActions?: string;
+		/** Classes for individual action buttons */
+		classAction?: string;
+		/** Classes for active action buttons */
+		classActionActive?: string;
+		/** Classes for the end area (locale + avatar + trailing hamburger) */
 		classEnd?: string;
 		/** Classes for the avatar container */
 		classAvatar?: string;
 		/** Classes for the locale switcher trigger (expanded mode) */
 		classLocale?: string;
-		/** Classes for the hamburger button */
+		/** Classes for the trailing (right-side) hamburger button */
 		classHamburger?: string;
 		/** Classes for the dropdown wrapper (collapsed mode) */
 		classDropdown?: string;
@@ -108,9 +211,14 @@
 	}
 
 	export const HEADER_BASE_CLASSES = "stuic-header";
+	export const HEADER_CONTENT_CLASSES = "stuic-header-content";
+	export const HEADER_LEADING_CLASSES = "stuic-header-leading";
+	export const HEADER_LEADING_HAMBURGER_CLASSES = "stuic-header-leading-hamburger";
 	export const HEADER_LOGO_CLASSES = "stuic-header-logo";
 	export const HEADER_NAV_CLASSES = "stuic-header-nav";
 	export const HEADER_NAV_ITEM_CLASSES = "stuic-header-nav-item";
+	export const HEADER_ACTIONS_CLASSES = "stuic-header-actions";
+	export const HEADER_ACTION_CLASSES = "stuic-header-action";
 	export const HEADER_END_CLASSES = "stuic-header-end";
 	export const HEADER_HAMBURGER_CLASSES = "stuic-header-hamburger";
 	export const HEADER_LOCALE_CLASSES = "stuic-header-locale";
@@ -125,11 +233,17 @@
 	import IconSwap from "../IconSwap/IconSwap.svelte";
 
 	let {
+		leading,
+		leadingHamburger = false,
+		onLeadingHamburger,
+		leadingHamburgerIcon,
+		leadingHamburgerLabel = "Open menu",
 		logo,
 		projectName,
-		navAlign = "right",
 		navVariant = "ghost",
 		items = [],
+		actions = [],
+		onActionSelect,
 		avatar,
 		avatarOnClick,
 		avatarLabel = "Account",
@@ -137,7 +251,10 @@
 		activeLocale,
 		onLocaleChange,
 		localeLabel = "Language",
+		contentMaxWidth,
 		collapseThreshold = 768,
+		collapseMode = "hamburger",
+		keepLocaleOnCollapse = false,
 		fixed = false,
 		isCollapsed = $bindable(false),
 		isMenuOpen = $bindable(false),
@@ -146,10 +263,16 @@
 		onSelect,
 		unstyled = false,
 		class: classProp,
+		classContent,
+		classLeading,
+		classLeadingHamburger,
 		classLogo,
 		classNav,
 		classNavItem,
 		classNavItemActive,
+		classActions,
+		classAction,
+		classActionActive,
 		classEnd,
 		classAvatar,
 		classLocale,
@@ -160,13 +283,19 @@
 		...rest
 	}: Props = $props();
 
-	// Width measurement (same pattern as Card)
-	let _offsetWidth = $state(0);
+	// Width measurement. We bind both outer and inner because:
+	//  - Default layout renders an inner wrapper; the inner row width is what
+	//    actually determines whether nav items fit, so collapse should key off it.
+	//  - With the `children` escape hatch there is no inner wrapper, so we
+	//    fall back to the outer measurement.
+	let _outerWidth = $state(0);
+	let _innerWidth = $state(0);
+	let _measuredWidth = $derived(_innerWidth || _outerWidth);
 
 	// Collapsed state based on threshold
 	let _isCollapsed = $derived.by(() => {
 		if (!collapseThreshold) return false;
-		return _offsetWidth > 0 && _offsetWidth < collapseThreshold;
+		return _measuredWidth > 0 && _measuredWidth < collapseThreshold;
 	});
 
 	// Sync bindable
@@ -181,12 +310,31 @@
 		}
 	});
 
-	// Whether the avatar moves into the dropdown when collapsed
-	let _avatarInDropdown = $derived(!!(avatar && avatarOnClick));
+	// Whether the avatar moves into the dropdown when collapsed.
+	// In "hide" mode the avatar always stays visible (never folds).
+	let _avatarInDropdown = $derived(
+		collapseMode === "hamburger" && !!(avatar && avatarOnClick)
+	);
+
+	// Whether to render the built-in leading hamburger (ignored when `leading` snippet is set)
+	let _showLeadingHamburger = $derived.by(() => {
+		if (leading) return false;
+		if (leadingHamburger === "collapsed") return _isCollapsed;
+		return !!leadingHamburger;
+	});
 
 	// Locale switcher: only render when 2+ locales
 	let _hasLocales = $derived(locales.length > 1);
 
+	// Visibility of the inline (expanded-form) locale switcher.
+	// In "hamburger" mode: visible only when not collapsed (it folds into the
+	// trailing dropdown when collapsed). In "hide" mode: visible when not
+	// collapsed, or when collapsed and `keepLocaleOnCollapse` is set.
+	let _showLocaleSwitcher = $derived(
+		_hasLocales &&
+			(!_isCollapsed || (collapseMode === "hide" && keepLocaleOnCollapse))
+	);
+
 	// Active locale object (for trigger label); fallback to first
 	let _activeLocale = $derived(locales.find((l) => l.id === activeLocale) ?? locales[0]);
 
@@ -209,8 +357,11 @@
 		);
 	});
 
-	// Map HeaderNavItem[] to DropdownMenuItem[] for collapsed mode
+	// Map HeaderNavItem[] to DropdownMenuItem[] for collapsed mode.
+	// In "hide" mode the trailing hamburger is suppressed entirely — return
+	// an empty list so no dropdown trigger renders.
 	let _dropdownItems = $derived.by((): DropdownMenuItem[] => {
+		if (collapseMode === "hide") return [];
 		const navItems: DropdownMenuItem[] = items.map(
 			(item) =>
 				({
@@ -269,10 +420,25 @@
 
 	// CSS classes
 	let _class = $derived(unstyled ? classProp : twMerge(HEADER_BASE_CLASSES, classProp));
+	let _classContent = $derived(
+		unstyled ? classContent : twMerge(HEADER_CONTENT_CLASSES, classContent)
+	);
+	let _styleContent = $derived.by(() => {
+		if (contentMaxWidth == null) return undefined;
+		const value =
+			typeof contentMaxWidth === "number" ? `${contentMaxWidth}px` : contentMaxWidth;
+		return `--stuic-header-content-max-width: ${value}`;
+	});
+	let _classLeading = $derived(
+		unstyled ? classLeading : twMerge(HEADER_LEADING_CLASSES, classLeading)
+	);
 	let _classLogo = $derived(
 		unstyled ? classLogo : twMerge(HEADER_LOGO_CLASSES, classLogo)
 	);
 	let _classNav = $derived(unstyled ? classNav : twMerge(HEADER_NAV_CLASSES, classNav));
+	let _classActions = $derived(
+		unstyled ? classActions : twMerge(HEADER_ACTIONS_CLASSES, classActions)
+	);
 	let _classEnd = $derived(unstyled ? classEnd : twMerge(HEADER_END_CLASSES, classEnd));
 	let _classLocale = $derived(
 		unstyled ? classLocale : twMerge(HEADER_LOCALE_CLASSES, classLocale)
@@ -283,11 +449,17 @@
 		item.onclick?.();
 		onSelect?.(item);
 	}
+
+	function handleActionClick(action: HeaderActionItem) {
+		if (action.disabled) return;
+		action.onclick?.();
+		onActionSelect?.(action);
+	}
 </script>
 
 <header
 	bind:this={el}
-	bind:offsetWidth={_offsetWidth}
+	bind:offsetWidth={_outerWidth}
 	class={_class}
 	data-fixed={!unstyled && fixed ? "" : undefined}
 	data-collapsed={!unstyled && _isCollapsed ? "" : undefined}
@@ -297,26 +469,48 @@
 		{@render children({
 			isCollapsed: _isCollapsed,
 			items,
-			offsetWidth: _offsetWidth,
+			offsetWidth: _measuredWidth,
 		})}
 	{:else}
-		<!-- Logo / Brand -->
-		{#if logo || projectName}
-			<div class={_classLogo}>
-				{#if logo}
-					{@render logo()}
-				{:else if projectName}
-					<span class={unstyled ? undefined : "stuic-header-project-name"}>
-						{projectName}
-					</span>
-				{/if}
+		<div bind:offsetWidth={_innerWidth} class={_classContent} style={_styleContent}>
+		<!-- Leading slot (left-side) -->
+		{#if leading}
+			<div class={_classLeading}>
+				{@render leading({ isCollapsed: _isCollapsed })}
+			</div>
+		{:else if _showLeadingHamburger}
+			<div class={_classLeading}>
+				<Button
+					variant="ghost"
+					iconButton
+					size="sm"
+					{unstyled}
+					class={twMerge(
+						!unstyled && HEADER_LEADING_HAMBURGER_CLASSES,
+						classLeadingHamburger
+					)}
+					onclick={onLeadingHamburger}
+					aria-label={leadingHamburgerLabel}
+				>
+					{#if leadingHamburgerIcon}
+						<Thc thc={leadingHamburgerIcon} />
+					{:else}
+						{@html iconMenu({ size: iconSize })}
+					{/if}
+				</Button>
 			</div>
 		{/if}
 
-		<!-- Spacer (before nav when right-aligned) -->
-		{#if navAlign !== "left"}
-			<div class={unstyled ? undefined : "stuic-header-spacer"}></div>
-		{/if}
+		<!-- Logo / Title (flex-1) -->
+		<div class={_classLogo}>
+			{#if logo}
+				{@render logo()}
+			{:else if projectName}
+				<span class={unstyled ? undefined : "stuic-header-project-name"}>
+					{projectName}
+				</span>
+			{/if}
+		</div>
 
 		<!-- Nav items (expanded mode) -->
 		{#if !_isCollapsed && items.length > 0}
@@ -350,15 +544,10 @@
 			</nav>
 		{/if}
 
-		<!-- Spacer (after nav when left-aligned) -->
-		{#if navAlign === "left"}
-			<div class={unstyled ? undefined : "stuic-header-spacer"}></div>
-		{/if}
-
-		<!-- End area: locale + avatar + hamburger -->
+		<!-- End area: locale + actions + avatar + trailing hamburger -->
 		<div class={_classEnd}>
-			<!-- Locale switcher (expanded mode only) -->
-			{#if !_isCollapsed && _hasLocales}
+			<!-- Locale switcher (shown when expanded, or in "hide" mode with keepLocaleOnCollapse) -->
+			{#if _showLocaleSwitcher}
 				<DropdownMenu
 					items={_localeDropdownItems}
 					position="bottom-span-right"
@@ -393,6 +582,46 @@
 				</DropdownMenu>
 			{/if}
 
+			<!-- Actions (icon buttons, always visible) -->
+			{#if actions.length > 0}
+				<div class={_classActions}>
+					{#each actions as action (action.id)}
+						{@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}
+
 			<!-- Avatar: hidden when collapsed + avatarOnClick (moves into dropdown) -->
 			{#if avatar && !(_isCollapsed && _avatarInDropdown)}
 				{#if avatarOnClick}
@@ -437,5 +666,6 @@
 				</DropdownMenu>
 			{/if}
 		</div>
+		</div>
 	{/if}
 </header>