@marianmeres/stuic 3.95.0 → 3.96.0

package/dist/components/Header/Header.svelte

@@ -37,17 +37,68 @@
 		label: THC;
 	}
 
+	export interface HeaderActionItem {
+		/** Unique identifier */
+		id: string | number;
+		/** Icon — THC (string/html/component/snippet). The visible content. */
+		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;
+	}
+
+	/** 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 +114,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 +145,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 +159,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 +184,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 +206,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 +224,10 @@
 		activeLocale,
 		onLocaleChange,
 		localeLabel = "Language",
+		contentMaxWidth,
 		collapseThreshold = 768,
+		collapseMode = "hamburger",
+		keepLocaleOnCollapse = false,
 		fixed = false,
 		isCollapsed = $bindable(false),
 		isMenuOpen = $bindable(false),
@@ -146,10 +236,16 @@
 		onSelect,
 		unstyled = false,
 		class: classProp,
+		classContent,
+		classLeading,
+		classLeadingHamburger,
 		classLogo,
 		classNav,
 		classNavItem,
 		classNavItemActive,
+		classActions,
+		classAction,
+		classActionActive,
 		classEnd,
 		classAvatar,
 		classLocale,
@@ -160,13 +256,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 +283,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 +330,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 +393,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 +422,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 +442,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 +517,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 +555,34 @@
 				</DropdownMenu>
 			{/if}
 
+			<!-- Actions (icon buttons, always visible) -->
+			{#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>
+					{/each}
+				</div>
+			{/if}
+
 			<!-- Avatar: hidden when collapsed + avatarOnClick (moves into dropdown) -->
 			{#if avatar && !(_isCollapsed && _avatarInDropdown)}
 				{#if avatarOnClick}
@@ -437,5 +627,6 @@
 				</DropdownMenu>
 			{/if}
 		</div>
+		</div>
 	{/if}
 </header>

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

@@ -29,17 +29,67 @@ export interface HeaderLocaleItem {
     /** Display label — supports THC (string, html, component, snippet) */
     label: THC;
 }
+export interface HeaderActionItem {
+    /** Unique identifier */
+    id: string | number;
+    /** Icon — THC (string/html/component/snippet). The visible content. */
+    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;
+}
+/** 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
@@ -55,8 +105,21 @@ export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
     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 */
@@ -73,6 +136,12 @@ export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
     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) */
@@ -81,13 +150,19 @@ export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
     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;
@@ -103,9 +178,14 @@ export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
     el?: HTMLElement;
 }
 export declare const HEADER_BASE_CLASSES = "stuic-header";
+export declare const HEADER_CONTENT_CLASSES = "stuic-header-content";
+export declare const HEADER_LEADING_CLASSES = "stuic-header-leading";
+export declare const HEADER_LEADING_HAMBURGER_CLASSES = "stuic-header-leading-hamburger";
 export declare const HEADER_LOGO_CLASSES = "stuic-header-logo";
 export declare const HEADER_NAV_CLASSES = "stuic-header-nav";
 export declare const HEADER_NAV_ITEM_CLASSES = "stuic-header-nav-item";
+export declare const HEADER_ACTIONS_CLASSES = "stuic-header-actions";
+export declare const HEADER_ACTION_CLASSES = "stuic-header-action";
 export declare const HEADER_END_CLASSES = "stuic-header-end";
 export declare const HEADER_HAMBURGER_CLASSES = "stuic-header-hamburger";
 export declare const HEADER_LOCALE_CLASSES = "stuic-header-locale";

package/dist/components/Header/index.css

@@ -11,9 +11,16 @@
 	--stuic-header-gap: 1rem;
 	--stuic-header-min-height: 3.5rem;
 
+	/* Content row max-width. `none` lets the inner row fill the parent.
+	   Override globally or per-instance via the `contentMaxWidth` prop. */
+	--stuic-header-content-max-width: none;
+
 	/* Nav items */
 	--stuic-header-nav-gap: 0.25rem;
 
+	/* Actions (icon buttons in the end region) */
+	--stuic-header-actions-gap: 0.25rem;
+
 	/* Project name */
 	--stuic-header-project-name-font-weight: var(--font-weight-semibold, 600);
 
@@ -27,14 +34,26 @@
 	   ============================================================================ */
 
 	.stuic-header {
+		width: 100%;
+		background: var(--stuic-header-bg, var(--color-background, inherit));
+		color: var(--stuic-header-text, inherit);
+	}
+
+	/* ============================================================================
+	   CONTENT ROW (inner wrapper — flex layout, padding, gap, optional max-width)
+	   The outer .stuic-header keeps full width / background; this inner row
+	   carries the layout so it can be capped via `contentMaxWidth` and centered.
+	   ============================================================================ */
+
+	.stuic-header-content {
 		display: flex;
 		align-items: center;
-		width: 100%;
+		gap: var(--stuic-header-gap);
 		min-height: var(--stuic-header-min-height);
 		padding: var(--stuic-header-padding-y) var(--stuic-header-padding-x);
-		gap: var(--stuic-header-gap);
-		background: var(--stuic-header-bg, var(--color-background, inherit));
-		color: var(--stuic-header-text, inherit);
+		width: 100%;
+		max-width: var(--stuic-header-content-max-width);
+		margin-inline: auto;
 	}
 
 	/* ============================================================================
@@ -50,15 +69,31 @@
 	}
 
 	/* ============================================================================
-	   LOGO
+	   LEADING (left-side slot — hamburger, back arrow, etc.)
 	   ============================================================================ */
 
-	.stuic-header-logo {
+	.stuic-header-leading {
 		display: flex;
 		align-items: center;
 		flex-shrink: 0;
 	}
 
+	.stuic-header-leading-hamburger {
+		/* Ghost Button handles hover/focus — only override sizing if needed */
+	}
+
+	/* ============================================================================
+	   LOGO / TITLE (takes available space — flex-1 with min-width: 0 so long
+	   content can shrink/ellipsize instead of overflowing the row)
+	   ============================================================================ */
+
+	.stuic-header-logo {
+		display: flex;
+		align-items: center;
+		flex: 1;
+		min-width: 0;
+	}
+
 	.stuic-header-project-name {
 		font-size: var(--stuic-header-project-name-font-size, var(--text-lg, 1.125rem));
 		font-weight: var(--stuic-header-project-name-font-weight);
@@ -91,6 +126,26 @@
 		flex-shrink: 0;
 	}
 
+	/* ============================================================================
+	   ACTIONS (icon buttons in the end region — search, notifications, etc.)
+	   ============================================================================ */
+
+	.stuic-header-actions {
+		display: flex;
+		align-items: center;
+		gap: var(--stuic-header-actions-gap);
+		flex-shrink: 0;
+	}
+
+	.stuic-header-action {
+		/* Ghost iconButton handles base styling — placeholder hook for consumer overrides */
+	}
+
+	.stuic-header-action[data-active] {
+		color: var(--stuic-header-action-text-active, var(--color-foreground, inherit));
+		background: var(--stuic-header-action-bg-active, var(--color-muted, transparent));
+	}
+
 	/* ============================================================================
 	   SPACER
 	   ============================================================================ */

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

@@ -1 +1 @@
-export { default as Header, type Props as HeaderProps, type HeaderNavItem, type HeaderLocaleItem, HEADER_BASE_CLASSES, HEADER_LOGO_CLASSES, HEADER_NAV_CLASSES, HEADER_NAV_ITEM_CLASSES, HEADER_END_CLASSES, HEADER_HAMBURGER_CLASSES, HEADER_LOCALE_CLASSES, } from "./Header.svelte";
+export { default as Header, type Props as HeaderProps, type HeaderNavItem, type HeaderLocaleItem, type HeaderActionItem, type HeaderLeadingHamburger, type HeaderCollapseMode, HEADER_BASE_CLASSES, HEADER_CONTENT_CLASSES, HEADER_LEADING_CLASSES, HEADER_LEADING_HAMBURGER_CLASSES, HEADER_LOGO_CLASSES, HEADER_NAV_CLASSES, HEADER_NAV_ITEM_CLASSES, HEADER_ACTIONS_CLASSES, HEADER_ACTION_CLASSES, HEADER_END_CLASSES, HEADER_HAMBURGER_CLASSES, HEADER_LOCALE_CLASSES, } from "./Header.svelte";

package/dist/components/Header/index.js

@@ -1 +1 @@
-export { default as Header, HEADER_BASE_CLASSES, HEADER_LOGO_CLASSES, HEADER_NAV_CLASSES, HEADER_NAV_ITEM_CLASSES, HEADER_END_CLASSES, HEADER_HAMBURGER_CLASSES, HEADER_LOCALE_CLASSES, } from "./Header.svelte";
+export { default as Header, HEADER_BASE_CLASSES, HEADER_CONTENT_CLASSES, HEADER_LEADING_CLASSES, HEADER_LEADING_HAMBURGER_CLASSES, HEADER_LOGO_CLASSES, HEADER_NAV_CLASSES, HEADER_NAV_ITEM_CLASSES, HEADER_ACTIONS_CLASSES, HEADER_ACTION_CLASSES, HEADER_END_CLASSES, HEADER_HAMBURGER_CLASSES, HEADER_LOCALE_CLASSES, } from "./Header.svelte";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.95.0",
+	"version": "3.96.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",
@@ -62,19 +62,19 @@
 		"@tailwindcss/forms": "^0.5.11",
 		"@tailwindcss/typography": "^0.5.19",
 		"@tailwindcss/vite": "^4.3.0",
-		"@types/node": "^25.8.0",
+		"@types/node": "^25.9.1",
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.4",
 		"globals": "^16.5.0",
 		"prettier": "^3.8.3",
 		"prettier-plugin-svelte": "^3.5.2",
 		"publint": "^0.3.21",
-		"svelte": "^5.55.7",
+		"svelte": "^5.55.9",
 		"svelte-check": "^4.4.8",
 		"tailwindcss": "^4.3.0",
-		"tsx": "^4.22.1",
+		"tsx": "^4.22.3",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.59.3",
+		"typescript-eslint": "^8.59.4",
 		"vite": "^7.3.3",
 		"vitest": "^3.2.4"
 	},