@marianmeres/stuic 3.184.0 → 3.187.0

package/API.md

@@ -153,38 +153,38 @@ Navigation wrapper component.
 
 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.                                                                                                                                                                                            |
-| `safeArea`              | `boolean`                                        | `false`               | PWA: when installed/standalone, offset the **top app bar** below the device safe-area insets (top + side notch). No-op in a browser tab. Set only on the top bar — not in-page/detail/drawer headers. See Header README. |
-| `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.                                                                                                                                                                          |
+| 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`                                        | `true`                | Keep the locale switcher inline (next to the hamburger) when collapsed — in **both** collapse modes, and without duplicating it inside the dropdown. `false` folds it into the dropdown (`"hamburger"`) or hides it (`"hide"`). |
+| `fixed`                 | `boolean`                                        | `false`               | Fixed positioning at the top.                                                                                                                                                                                                   |
+| `safeArea`              | `boolean`                                        | `false`               | PWA: when installed/standalone, offset the **top app bar** below the device safe-area insets (top + side notch). No-op in a browser tab. Set only on the top bar — not in-page/detail/drawer headers. See Header README.        |
+| `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`.
 
@@ -223,9 +223,9 @@ Class slots: `class`, `classContent`, `classLeading`, `classLeadingHamburger`, `
 
 **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).
 
-**HeaderLocaleItem:** `{ id, label }`
+**HeaderLocaleItem:** `{ id, label, shortLabel? }` — `shortLabel` replaces `label` on the inline trigger **in collapsed mode only** (keeps a long name like "Slovenčina" from crowding a narrow header); the dropdown list always shows the full `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`.
+CSS tokens: `--stuic-header-padding-x`, `--stuic-header-padding-y`, `--stuic-header-gap`, `--stuic-header-end-gap-collapsed`, `--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`.
 
 ---
 

package/dist/components/Header/Header.svelte

@@ -35,6 +35,12 @@
 		id: string;
 		/** Display label — supports THC (string, html, component, snippet) */
 		label: THC;
+		/** Compact label for the inline trigger in COLLAPSED mode only.
+		 *  Falls back to `label`. Use it when the full label ("Slovenčina")
+		 *  would crowd the narrow header next to the hamburger — the dropdown
+		 *  list always shows the full `label`, so the long form stays
+		 *  available where there is room to read it. */
+		shortLabel?: THC;
 	}
 
 	export interface HeaderActionItem {
@@ -86,11 +92,13 @@
 	}
 
 	/** 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.
+	 *  - "hamburger": nav items fold into a trailing dropdown along with an
+	 *    interactive avatar.
 	 *  - "hide": nav items are hidden entirely. No trailing hamburger renders.
-	 *    Avatar stays visible. Locale visibility is controlled by
-	 *    `keepLocaleOnCollapse`. */
+	 *    Avatar stays visible.
+	 *
+	 *  In BOTH modes the locale switcher stays inline next to the hamburger
+	 *  by default — see `keepLocaleOnCollapse`. */
 	export type HeaderCollapseMode = "hamburger" | "hide";
 
 	/** Visibility for the built-in leading hamburger button:
@@ -152,9 +160,27 @@
 		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). */
+		/** Keep the locale switcher visible — inline, next to the hamburger —
+		 *  when the header is collapsed. Applies to BOTH collapse modes.
+		 *  Defaults to `true`.
+		 *
+		 *  Why it defaults on: the person who most needs this control is the
+		 *  one who landed in a language they cannot read. For them a visible
+		 *  "EN ▾" trigger is the only self-describing widget in the bar, while
+		 *  a locale entry folded into the hamburger — listed last, under a
+		 *  "Language" heading they also cannot read, often below the fold of a
+		 *  long menu — is effectively invisible.
+		 *
+		 *  When `true` in `"hamburger"` mode the locale section is NOT also
+		 *  appended to the trailing dropdown, so it is never reachable twice.
+		 *
+		 *  Set `false` for the alternative: folds into the trailing dropdown
+		 *  in `"hamburger"` mode, hidden entirely in `"hide"` mode (this was
+		 *  the behavior before the prop applied to both modes). Worth doing
+		 *  when the end area is already crowded with actions, or when the
+		 *  app's own drawer owns the language switch. See also
+		 *  `HeaderLocaleItem.shortLabel` for keeping the inline trigger
+		 *  narrow. */
 		keepLocaleOnCollapse?: boolean;
 		/** Fixed positioning (top of viewport) */
 		fixed?: boolean;
@@ -263,7 +289,7 @@
 		contentMaxWidth,
 		collapseThreshold = 768,
 		collapseMode = "hamburger",
-		keepLocaleOnCollapse = false,
+		keepLocaleOnCollapse = true,
 		fixed = false,
 		safeArea = false,
 		isCollapsed = $bindable(false),
@@ -336,17 +362,28 @@
 	// 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.
+	// Visibility of the inline (expanded-form) locale switcher. Always visible
+	// when expanded; when collapsed it stays inline unless explicitly opted out
+	// — in BOTH collapse modes. Deliberately mode-agnostic: a user who cannot
+	// read the current language must be able to find the switcher without
+	// opening a menu whose trigger tells them nothing.
 	let _showLocaleSwitcher = $derived(
-		_hasLocales && (!_isCollapsed || (collapseMode === "hide" && keepLocaleOnCollapse))
+		_hasLocales && (!_isCollapsed || keepLocaleOnCollapse)
 	);
 
 	// Active locale object (for trigger label); fallback to first
 	let _activeLocale = $derived(locales.find((l) => l.id === activeLocale) ?? locales[0]);
 
+	// Inline trigger label. `shortLabel` (when provided) is used ONLY in
+	// collapsed mode, where horizontal space next to the hamburger is scarce;
+	// expanded mode and the dropdown list always show the full `label`.
+	let _localeTriggerLabel = $derived.by((): THC | undefined => {
+		if (!_activeLocale) return undefined;
+		return _isCollapsed
+			? (_activeLocale.shortLabel ?? _activeLocale.label)
+			: _activeLocale.label;
+	});
+
 	// Locale items for the expanded-mode DropdownMenu
 	let _localeDropdownItems = $derived.by((): DropdownMenuItem[] => {
 		return locales.map(
@@ -389,8 +426,10 @@
 				}) satisfies DropdownMenuActionItem
 		);
 
-		// Append locale section when locales are available
-		if (_hasLocales) {
+		// Append the locale section ONLY when the inline switcher is hidden.
+		// With the inline trigger visible this would be a second, worse route
+		// to the same setting — and the one nobody finds.
+		if (_hasLocales && !_showLocaleSwitcher) {
 			if (navItems.length > 0) {
 				navItems.push({ type: "divider" });
 			}
@@ -556,7 +595,9 @@
 
 			<!-- End area: locale + actions + avatar + trailing hamburger -->
 			<div class={_classEnd}>
-				<!-- Locale switcher (shown when expanded, or in "hide" mode with keepLocaleOnCollapse) -->
+				<!-- Locale switcher — inline when expanded and, unless
+				     `keepLocaleOnCollapse={false}`, still inline when collapsed
+				     (both collapse modes) rather than folded into the dropdown -->
 				{#if _showLocaleSwitcher}
 					<DropdownMenu
 						items={_localeDropdownItems}
@@ -573,8 +614,8 @@
 								aria-label="Change language"
 								{...triggerProps}
 							>
-								{#if _activeLocale}
-									<Thc thc={_activeLocale.label} />
+								{#if _localeTriggerLabel !== undefined}
+									<Thc thc={_localeTriggerLabel} />
 								{/if}
 								<span
 									class={twMerge(

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

@@ -28,6 +28,12 @@ export interface HeaderLocaleItem {
     id: string;
     /** Display label — supports THC (string, html, component, snippet) */
     label: THC;
+    /** Compact label for the inline trigger in COLLAPSED mode only.
+     *  Falls back to `label`. Use it when the full label ("Slovenčina")
+     *  would crowd the narrow header next to the hamburger — the dropdown
+     *  list always shows the full `label`, so the long form stays
+     *  available where there is room to read it. */
+    shortLabel?: THC;
 }
 export interface HeaderActionItem {
     /** Unique identifier */
@@ -75,11 +81,13 @@ export interface HeaderActionItem {
     ]>;
 }
 /** 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.
+ *  - "hamburger": nav items fold into a trailing dropdown along with an
+ *    interactive avatar.
  *  - "hide": nav items are hidden entirely. No trailing hamburger renders.
- *    Avatar stays visible. Locale visibility is controlled by
- *    `keepLocaleOnCollapse`. */
+ *    Avatar stays visible.
+ *
+ *  In BOTH modes the locale switcher stays inline next to the hamburger
+ *  by default — see `keepLocaleOnCollapse`. */
 export type HeaderCollapseMode = "hamburger" | "hide";
 /** Visibility for the built-in leading hamburger button:
  *  - false/undefined: not rendered
@@ -141,9 +149,27 @@ export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
     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). */
+    /** Keep the locale switcher visible — inline, next to the hamburger —
+     *  when the header is collapsed. Applies to BOTH collapse modes.
+     *  Defaults to `true`.
+     *
+     *  Why it defaults on: the person who most needs this control is the
+     *  one who landed in a language they cannot read. For them a visible
+     *  "EN ▾" trigger is the only self-describing widget in the bar, while
+     *  a locale entry folded into the hamburger — listed last, under a
+     *  "Language" heading they also cannot read, often below the fold of a
+     *  long menu — is effectively invisible.
+     *
+     *  When `true` in `"hamburger"` mode the locale section is NOT also
+     *  appended to the trailing dropdown, so it is never reachable twice.
+     *
+     *  Set `false` for the alternative: folds into the trailing dropdown
+     *  in `"hamburger"` mode, hidden entirely in `"hide"` mode (this was
+     *  the behavior before the prop applied to both modes). Worth doing
+     *  when the end area is already crowded with actions, or when the
+     *  app's own drawer owns the language switch. See also
+     *  `HeaderLocaleItem.shortLabel` for keeping the inline trigger
+     *  narrow. */
     keepLocaleOnCollapse?: boolean;
     /** Fixed positioning (top of viewport) */
     fixed?: boolean;

package/dist/components/Header/README.md

@@ -4,17 +4,54 @@ Top-bar component with leading slot, project logo, nav items, locale switcher, o
 
 ## Examples
 
+### The locale switcher stays visible when collapsed
+
+When the header collapses, the locale switcher does **not** fold into the trailing hamburger. It stays inline, immediately before the actions / avatar / hamburger, in **both** collapse modes. Nothing to configure — it is the default.
+
+```svelte
+<Header
+	projectName="App"
+	items={navItems}
+	{locales}
+	{activeLocale}
+	onLocaleChange={(id) => (activeLocale = id)}
+/>
+<!-- collapsed:  [App]                              [EN ▾] [☰] -->
+```
+
+This is the one control `Header` deliberately treats differently from a nav item, and the reason is worth stating because it looks like an inconsistency:
+
+> The person who most needs the language switch is the person who landed in a language they cannot read. A visible `EN ▾` trigger is self-describing to them — it shows the current language and it is obviously a control. An entry inside the hamburger is not: the trigger is an unlabeled icon, the section heading says "Language" in a language they do not speak, and past a handful of nav items it sits below the fold of a menu they have to scroll with a finger. It is reliably never found.
+
+What follows from it:
+
+| Behavior                                                                                                                                  | Why                                                                                                                                                                |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| The trailing dropdown has **no** locale section while the inline trigger is visible.                                                      | Two routes to one setting, one of which nobody finds. `_dropdownItems` appends the locale section only when the inline switcher is hidden.                         |
+| A header whose only collapsible content was the locale switcher renders **no hamburger at all**.                                          | `_dropdownItems` comes back empty, and the trailing `DropdownMenu` is gated on it being non-empty.                                                                 |
+| The inline trigger shows `HeaderLocaleItem.shortLabel` (when set) **only** while collapsed.                                               | `"Slovenčina"` next to a hamburger on a 360px phone is what pushed the switcher into the menu in the first place. The dropdown list always shows the full `label`. |
+| `keepLocaleOnCollapse={false}` restores the alternative: folds into the dropdown in `"hamburger"` mode, hidden entirely in `"hide"` mode. | For an end area already crowded with actions, or an app whose own drawer owns the language switch.                                                                 |
+
+```ts
+// Long locale names on a narrow header: short form on the inline trigger,
+// full form in the dropdown list.
+const locales: HeaderLocaleItem[] = [
+	{ id: "en", label: "English", shortLabel: "EN" },
+	{ id: "sk", label: "Slovenčina", shortLabel: "SK" },
+];
+```
+
 ### 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).
+Common "app shell" pattern: when the header collapses below `collapseThreshold`, the avatar, the locale switcher and a few key actions (search, notifications, cart…) remain visible, the trailing hamburger is NOT shown, and the nav items 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.                                              |
+| Requirement                     | Where it's handled                                                                                 | How                                                                                                                                                      |
+| ------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Avatar stays visible**        | [Header.svelte:673](./Header.svelte#L673) — `{#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:632](./Header.svelte#L632) — `<!-- Actions (icon buttons, always visible) -->`      | The actions loop has no collapse gating — items render in both modes.                                                                                    |
+| **No trailing hamburger**       | [Header.svelte:689](./Header.svelte#L689) — `{#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:564](./Header.svelte#L564) — `{#if !_isCollapsed && items.length > 0}`              | Inline nav requires `!_isCollapsed`; combined with the empty `_dropdownItems` above, items don't reappear in a dropdown either.                          |
+| **Locale stays visible**        | [Header.svelte:369](./Header.svelte#L369) — `!_isCollapsed \|\| keepLocaleOnCollapse`              | `keepLocaleOnCollapse` defaults to `true` in both modes (see the section above). Pass `false` to hide it, e.g. when the drawer owns the language switch. |
 
 Minimal config:
 
@@ -26,7 +63,7 @@ Minimal config:
     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) -->
+    {locales} {activeLocale}    <!-- stays visible in collapsed (keepLocaleOnCollapse defaults to true) -->
     onLocaleChange={(id) => (activeLocale = id)}
     avatarOnClick={() => alert("Profile")}  <!-- safe in "hide" mode — won't move into dropdown -->
 >

package/dist/components/Header/index.css

@@ -21,6 +21,14 @@
 	/* Actions (icon buttons in the end region) */
 	--stuic-header-actions-gap: 0.25rem;
 
+	/* Gap between the end-area regions (locale / actions / avatar / hamburger)
+	   while collapsed. Expanded uses --stuic-header-gap; collapsed is tighter
+	   because the locale switcher stays inline there instead of folding into
+	   the hamburger, and at 320px the full gap pushes a locale + 3 actions +
+	   hamburger row past the content edge. Set to var(--stuic-header-gap) to
+	   keep both states equal. */
+	--stuic-header-end-gap-collapsed: 0.5rem;
+
 	/* 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
@@ -126,6 +134,14 @@
 		font-size: var(--stuic-header-project-name-font-size, var(--text-lg, 1.125rem));
 		font-weight: var(--stuic-header-project-name-font-weight);
 		white-space: nowrap;
+		/* Truncate instead of overflowing the row. `min-width: 0` lets this
+		   flex item shrink below its content width (auto minimum size would
+		   otherwise pin it), and `overflow: hidden` is what makes
+		   `text-overflow` apply. Matters most in collapsed mode, where the
+		   name shares the row with the locale trigger + hamburger. */
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
 	}
 
 	/* ============================================================================
@@ -193,6 +209,10 @@
 		flex-shrink: 0;
 	}
 
+	.stuic-header[data-collapsed] .stuic-header-end {
+		gap: var(--stuic-header-end-gap-collapsed);
+	}
+
 	.stuic-header-avatar {
 		display: flex;
 		align-items: center;

package/dist/components/Input/FieldSingleAsset.svelte

@@ -177,6 +177,14 @@
 		placeholder?: THC;
 		/** Hide the "Preview" action (the `AssetsPreview` lightbox). */
 		noPreview?: boolean;
+		/**
+		 * Never show the asset's `name` to the user — the tile's filename line, the
+		 * lightbox caption, the "… removed" / "… uploaded" announcements and toasts all
+		 * fall back to name-less wording (`replace_file_short`, `removed_short`, ...).
+		 * For stores that hand back a content-hash filename, which carries no meaning
+		 * worth reading. The type / size line (`metaText`) is unaffected.
+		 */
+		noFilename?: boolean;
 		/** Hide the lightbox's Download button. */
 		noDownload?: boolean;
 		/** See `AssetsPreview.onDownload`: replaces the default download of `url.original`. */
@@ -288,6 +296,7 @@
 		placeholder,
 		noPreview = false,
 		noDownload = false,
+		noFilename = false,
 		onDownload,
 		onChange,
 	}: Props = $props();
@@ -356,9 +365,13 @@
 	let tileActionText = $derived(
 		canUpload
 			? shown
-				? t("replace_file", { name: shown.name })
+				? noFilename
+					? t("replace_file_short")
+					: t("replace_file", { name: shown.name })
 				: t("pick_file")
-			: (shown?.name ?? "")
+			: noFilename
+				? ""
+				: (shown?.name ?? "")
 	);
 	let metaText = $derived.by(() => {
 		if (!shown) return "";
@@ -540,7 +553,7 @@
 		assetsPreview?.close?.();
 		pending = { asset: optimistic, file, progress: 0, error: null };
 		const seq = ++uploadSeq;
-		announce(t("uploading", { name: file.name }));
+		announce(noFilename ? t("uploading_short") : t("uploading", { name: file.name }));
 
 		const onProgress = (p: number) => {
 			if (seq === uploadSeq && pending && !pending.error) {
@@ -564,14 +577,20 @@
 				}
 				pending = null;
 				commit(uploaded);
-				announce(t("uploaded", { name: uploaded.name ?? file.name }));
+				announce(
+					noFilename
+						? t("uploaded_short")
+						: t("uploaded", { name: uploaded.name ?? file.name })
+				);
 			})
 			.catch((e) => {
 				if (seq !== uploadSeq) return;
 				const error = `${e?.message ?? e}`;
 				clog.error(error);
 				if (pending) pending.error = error;
-				const msg = t("upload_failed_named", { name: file.name, error });
+				const msg = noFilename
+					? t("upload_failed_error", { error })
+					: t("upload_failed_named", { name: file.name, error });
 				announce(msg);
 				// the consumer may own the report (a quota panel it already renders):
 				// `false` skips only the toast, the tile's Retry / Discard stay
@@ -609,7 +628,7 @@
 		}
 		assetsPreview?.close?.();
 		commit(null);
-		announce(t("removed", { name: current.name }));
+		announce(noFilename ? t("removed_short") : t("removed", { name: current.name }));
 		if (undoTtl > 0) {
 			removed = current;
 			undoTimer = setTimeout(() => clear_removed(), undoTtl);
@@ -622,7 +641,7 @@
 		if (!back) return;
 		clear_removed();
 		commit(back);
-		announce(t("restored", { name: back.name }));
+		announce(noFilename ? t("restored_short") : t("restored", { name: back.name }));
 		focus_tile();
 	}
 
@@ -823,13 +842,17 @@
 			{#if isLoading}
 				<Skeleton variant="text" lines={2} width="60%" />
 			{:else if shown}
-				<div class="truncate font-medium" title={shown.name}>{shown.name}</div>
+				{#if !noFilename}
+					<div class="truncate font-medium" title={shown.name}>{shown.name}</div>
+				{/if}
 				{#if metaText}
 					<div class="text-xs stuic-field-single-asset-meta">{metaText}</div>
 				{/if}
 			{:else if undoOffer}
 				<div class="stuic-field-single-asset-meta">
-					<span>{t("removed", { name: undoOffer.name })}</span>
+					<span>
+						{noFilename ? t("removed_short") : t("removed", { name: undoOffer.name })}
+					</span>
 					<button type="button" class="stuic-field-single-asset-undo" onclick={undo}>
 						{@html iconUndo({ size: 14 })}
 						<span>{t("undo")}</span>
@@ -925,6 +948,7 @@
 	noPrevNext
 	noDots
 	noCurrentOfTotal
+	noName={noFilename}
 	{noDownload}
 	onDelete={(_, _index, controls) => {
 		controls.close();

package/dist/components/Input/FieldSingleAsset.svelte.d.ts

@@ -133,6 +133,14 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
     placeholder?: THC;
     /** Hide the "Preview" action (the `AssetsPreview` lightbox). */
     noPreview?: boolean;
+    /**
+     * Never show the asset's `name` to the user — the tile's filename line, the
+     * lightbox caption, the "… removed" / "… uploaded" announcements and toasts all
+     * fall back to name-less wording (`replace_file_short`, `removed_short`, ...).
+     * For stores that hand back a content-hash filename, which carries no meaning
+     * worth reading. The type / size line (`metaText`) is unaffected.
+     */
+    noFilename?: boolean;
     /** Hide the lightbox's Download button. */
     noDownload?: boolean;
     /** See `AssetsPreview.onDownload`: replaces the default download of `url.original`. */

package/dist/components/Input/README.md

@@ -937,6 +937,7 @@ a dialog and resolves with the cropped file.
 | `size`                                                     | `"sm" \| "md" \| "lg" \| string`                       | `"md"`             | Tile height: preset or CSS length                                       |
 | `placeholder`                                              | `THC`                                                  | -                  | Empty-tile content (e.g. an `Avatar` with initials)                     |
 | `noPreview`, `noDownload`                                  | `boolean`                                              | `false`            | Hide the Preview action / the lightbox's Download                       |
+| `noFilename`                                               | `boolean`                                              | `false`            | Never show the asset's name (hash filenames); name-less wording instead |
 | `onDownload`                                               | `(asset) => void \| Promise<void>`                     | -                  | Replaces the lightbox's default download (auth-gated bytes)             |
 | `onChange`                                                 | `(asset \| null) => void`                              | -                  | After every user-driven change of `value`                               |
 | `parseValue`, `serializeValue`                             | see Value                                              | JSON               | Custom `value` shape                                                    |

package/dist/components/Input/field-single-asset-i18n-sk.js

@@ -21,12 +21,15 @@ export const FIELD_SINGLE_ASSET_MESSAGES_SK = {
     field_req_att: "Toto pole vyžaduje pozornosť. Skontrolujte ho a skúste to znova.",
     pick_file: "Vybrať súbor",
     replace_file: "Nahradiť {{name}}",
+    replace_file_short: "Nahradiť súbor",
     empty_hint: "Presuňte sem súbor alebo kliknite a vyberte ho",
     remove: "Odstrániť",
     removing_short: "Odstraňuje sa…",
     removed: "Súbor {{name}} bol odstránený",
+    removed_short: "Súbor bol odstránený",
     undo: "Vrátiť späť",
     restored: "Súbor {{name}} bol obnovený",
+    restored_short: "Súbor bol obnovený",
     preview: "Náhľad",
     retry: "Skúsiť nahrať znova",
     discard: "Zahodiť",
@@ -35,8 +38,10 @@ export const FIELD_SINGLE_ASSET_MESSAGES_SK = {
     uploading_short: "Nahráva sa…",
     uploading_progress: "Nahráva sa… {{percent}} %",
     uploaded: "Súbor {{name}} bol nahraný",
+    uploaded_short: "Súbor bol nahraný",
     upload_failed: "Nahrávanie zlyhalo",
     upload_failed_named: "Nahrávanie súboru {{name}} zlyhalo: {{error}}",
+    upload_failed_error: "Nahrávanie zlyhalo: {{error}}",
     invalid_type: "Tento typ súboru nie je podporovaný. Povolené: „{{accept}}“.",
     too_large: "Súbor je príliš veľký ({{size}}). Maximum je {{max}}.",
     single_only: "Sem je možné umiestniť iba jeden súbor. Presuňte alebo prilepte jeden súbor.",

package/dist/components/Input/field-single-asset-i18n.d.ts

@@ -10,12 +10,15 @@ export declare const FIELD_SINGLE_ASSET_MESSAGES_EN: {
     field_req_att: string;
     pick_file: string;
     replace_file: string;
+    replace_file_short: string;
     empty_hint: string;
     remove: string;
     removing_short: string;
     removed: string;
+    removed_short: string;
     undo: string;
     restored: string;
+    restored_short: string;
     preview: string;
     retry: string;
     discard: string;
@@ -24,8 +27,10 @@ export declare const FIELD_SINGLE_ASSET_MESSAGES_EN: {
     uploading_short: string;
     uploading_progress: string;
     uploaded: string;
+    uploaded_short: string;
     upload_failed: string;
     upload_failed_named: string;
+    upload_failed_error: string;
     invalid_type: string;
     too_large: string;
     single_only: string;

package/dist/components/Input/field-single-asset-i18n.js

@@ -11,12 +11,15 @@ export const FIELD_SINGLE_ASSET_MESSAGES_EN = {
     field_req_att: "This field requires attention. Please review and try again.",
     pick_file: "Choose a file",
     replace_file: "Replace {{name}}",
+    replace_file_short: "Replace file",
     empty_hint: "Drop a file here or click to browse",
     remove: "Remove",
     removing_short: "Removing…",
     removed: "{{name}} removed",
+    removed_short: "File removed",
     undo: "Undo",
     restored: "{{name}} restored",
+    restored_short: "File restored",
     preview: "Preview",
     retry: "Retry upload",
     discard: "Discard",
@@ -25,8 +28,10 @@ export const FIELD_SINGLE_ASSET_MESSAGES_EN = {
     uploading_short: "Uploading…",
     uploading_progress: "Uploading… {{percent}}%",
     uploaded: "{{name}} uploaded",
+    uploaded_short: "File uploaded",
     upload_failed: "Upload failed",
     upload_failed_named: "Upload of {{name}} failed: {{error}}",
+    upload_failed_error: "Upload failed: {{error}}",
     invalid_type: 'This file type is not supported. Allowed: "{{accept}}".',
     too_large: "The file is too large ({{size}}). The maximum is {{max}}.",
     single_only: "Only one file can be placed here. Drop or paste a single file.",

package/docs/domains/components.md

@@ -1515,6 +1515,18 @@ interface HeaderActionItem {
 }
 ```
 
+### HeaderLocaleItem
+
+```ts
+interface HeaderLocaleItem {
+	id: string;
+	label: THC;
+	/** Compact label for the inline trigger in COLLAPSED mode only
+	 *  (falls back to `label`); the dropdown list always shows `label`. */
+	shortLabel?: THC;
+}
+```
+
 ### Key Props
 
 | Prop                    | Type                         | Default               | Description                                                                                |
@@ -1540,7 +1552,7 @@ interface HeaderActionItem {
 | `contentMaxWidth`       | `string \| number`           | —                     | Inner content row max-width (outer header stays 100%).                                     |
 | `collapseThreshold`     | `number`                     | `768`                 | Width (px) to collapse; 0 disables.                                                        |
 | `collapseMode`          | `"hamburger" \| "hide"`      | `"hamburger"`         | Collapse behavior. See top of section.                                                     |
-| `keepLocaleOnCollapse`  | `boolean`                    | `false`               | Keep locale switcher visible when collapsed (only `collapseMode === "hide"`).              |
+| `keepLocaleOnCollapse`  | `boolean`                    | `true`                | Keep the locale switcher inline when collapsed (both modes). See below.                    |
 | `fixed`                 | `boolean`                    | `false`               | Fixed positioning at top.                                                                  |
 | `isCollapsed`           | `boolean`                    | —                     | Bindable: collapsed state.                                                                 |
 | `isMenuOpen`            | `boolean`                    | —                     | Bindable: hamburger menu open.                                                             |
@@ -1575,11 +1587,24 @@ Common pattern for app interfaces: the leading hamburger opens a side drawer for
 
 See [Header/README.md](../../src/lib/components/Header/README.md) for the breakdown of which markup branch handles each requirement of this pattern.
 
+### The locale switcher never folds into the hamburger
+
+By default (`keepLocaleOnCollapse`) the locale switcher stays **inline** when the header collapses, in both collapse modes — it sits just before the actions/avatar/hamburger instead of becoming the last section of the dropdown.
+
+This is the one control `Header` deliberately treats differently from nav items. The user who most needs the language switch is the one who landed in a language they cannot read, and for them a visible `EN ▾` trigger is self-describing while a hamburger entry is not: the trigger is an unlabeled icon, the section heading says "Language" in a language they do not speak, and with more than a few nav items it sits below the fold of a menu they must scroll.
+
+Consequences worth knowing:
+
+- The dropdown never carries a duplicate locale section while the inline trigger is visible.
+- If the locales were the only thing the trailing dropdown would have held, no hamburger renders at all.
+- `HeaderLocaleItem.shortLabel` keeps the inline trigger narrow on phones (`"Slovenčina"` → `"SK"`) without shortening the dropdown entries.
+- Set `keepLocaleOnCollapse={false}` when the end area is already crowded with actions, or when the app's own drawer owns the language switch.
+
 ### CSS Tokens
 
 Prefix: `--stuic-header-*`
 
-`padding-x`, `padding-y`, `gap`, `min-height`, `nav-gap`, `content-max-width`, `project-name-font-weight`, `z-index`, `bg`, `text`, `border-width`, `border-color`, `nav-item-bg-active`, `nav-item-text-active`
+`padding-x`, `padding-y`, `gap`, `end-gap-collapsed`, `min-height`, `nav-gap`, `content-max-width`, `project-name-font-weight`, `z-index`, `bg`, `text`, `border-width`, `border-color`, `nav-item-bg-active`, `nav-item-text-active`
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.184.0",
+	"version": "3.187.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",