@marianmeres/stuic 3.51.2 → 3.52.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 46 UI components
+├── components/     # 50 UI components
 ├── actions/        # 15 Svelte actions
 ├── utils/          # 43 utility modules
 ├── themes/         # Generated theme CSS (css/) — definitions from @marianmeres/design-tokens

package/API.md

@@ -130,6 +130,41 @@ Panel-based navigation with slide transitions.
 
 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            |
+
+```svelte
+<Header
+	projectName="My App"
+	items={[
+		{ id: "home", label: "Home", href: "/", active: true },
+		{ id: "about", label: "About", href: "/about" },
+	]}
+>
+	{#snippet avatar()}
+		<Avatar src="/me.jpg" alt="User" />
+	{/snippet}
+</Header>
+```
+
+**HeaderNavItem:** `{ id, label, href?, onclick?, icon?, active?, disabled?, class? }`
+
+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`.
+
 ---
 
 ### Interactive
@@ -316,6 +351,42 @@ Dual-mode JSON object editor with pretty-print and raw edit modes. Validates JSO
 <FieldObject bind:value={jsonStr} name="metadata" label="Metadata" />
 ```
 
+#### `CronInput`
+
+Cron expression editor with preset selector, manual 5-field editor, raw expression input, human-readable descriptions, and next-run calculation.
+
+| Prop              | Type                          | Default       | Description                     |
+| ----------------- | ----------------------------- | ------------- | ------------------------------- |
+| `value`           | `string`                      | `"* * * * *"` | Bindable cron expression        |
+| `mode`            | `CronInputMode`               | —             | Bindable; predefined or manual  |
+| `showPresets`     | `boolean`                     | `true`        | Show preset selector            |
+| `showFields`      | `boolean`                     | `true`        | Show 5-column field editor      |
+| `showRawInput`    | `boolean`                     | `true`        | Show raw expression input       |
+| `showDescription` | `boolean`                     | `true`        | Show human-readable description |
+| `showNextRun`     | `boolean`                     | `true`        | Show next run time              |
+| `presets`         | `CronPreset[]`                | default set   | Custom presets                  |
+| `onchange`        | `(expr: string, valid: boolean) => void` | — | Change callback                 |
+
+Integrates with `InputWrap` — supports `label`, `description`, `renderSize`, `required`, `disabled`, `validate`, `labelLeft`, `below`.
+
+```svelte
+<CronInput bind:value={cronExpr} label="Schedule" showNextRun />
+```
+
+Exports: `CronInput`, `CronInputProps`, `CronPreset`, `CronInputMode`, `CRON_DEFAULT_PRESETS`, `CronNextRun`.
+
+**CronNextRun** — reactive helper class for standalone next-run calculations:
+
+```ts
+const next = new CronNextRun("0 9 * * 1-5");
+next.nextRun;          // Date | null
+next.nextRunFormatted; // "YYYY-MM-DD HH:MM"
+next.valid;            // boolean
+next.destroy();        // cleanup timer
+```
+
+CSS tokens: `--stuic-cron-input-fields-gap`, `--stuic-cron-input-section-gap`, `--stuic-cron-input-field-label-text`, `--stuic-cron-input-summary-text`, `--stuic-cron-input-error-text`, `--stuic-cron-input-field-bg`, `--stuic-cron-input-field-border`, `--stuic-cron-input-field-border-focus`.
+
 #### `Fieldset`
 
 Form field grouping with legend.
@@ -1090,6 +1161,86 @@ Always-visible (non-modal) variant of AssetsPreview with the same zoom, pan, swi
 />
 ```
 
+#### `Card`
+
+Flexible, responsive card with image, title, description, footer, and interactive states. Renders as `<a>`, `<button>`, or `<div>` depending on props.
+
+| Prop                  | Type          | Default      | Description                                       |
+| --------------------- | ------------- | ------------ | ------------------------------------------------- |
+| `image`               | `string`      | —            | Image URL                                         |
+| `imageAlt`            | `string`      | `""`         | Alt text                                          |
+| `eyebrow`             | `THC`         | —            | Small label above title                           |
+| `title`               | `THC`         | —            | Card title                                        |
+| `description`         | `THC`         | —            | Short description                                 |
+| `variant`             | `CardVariant` | `"vertical"` | `"vertical"` or `"horizontal"` layout             |
+| `href`                | `string`      | —            | Renders as `<a>`                                  |
+| `onclick`             | `(e) => void` | —            | Renders as `<button>`                             |
+| `disabled`            | `boolean`     | `false`      | Disable interaction                               |
+| `horizontalThreshold` | `number`      | `480`        | Width (px) to auto-switch to vertical; 0 disables |
+
+```svelte
+<Card
+	image="/photo.jpg"
+	eyebrow="New"
+	title="Product Name"
+	description="A brief description."
+	href="/products/1"
+>
+	{#snippet renderFooter()}
+		<Button variant="ghost" size="sm">Details</Button>
+	{/snippet}
+</Card>
+```
+
+Snippets: `children`, `renderImage({ image, imageAlt })`, `renderBadge`, `renderContent({ eyebrow?, title?, description? })`, `renderFooter`.
+
+Exports: `Card`, `CardProps`, `CardVariant`.
+
+CSS tokens: `--stuic-card-bg`, `--stuic-card-bg-hover`, `--stuic-card-border`, `--stuic-card-border-hover`, `--stuic-card-padding`, `--stuic-card-content-gap`, `--stuic-card-image-aspect-ratio`, `--stuic-card-image-object-fit`, `--stuic-card-image-width-horizontal`, `--stuic-card-radius`, `--stuic-card-shadow`, `--stuic-card-shadow-hover`, `--stuic-card-ring-width`, `--stuic-card-ring-color`, `--stuic-card-eyebrow-font-size`, `--stuic-card-title-font-size`, `--stuic-card-title-font-weight`, `--stuic-card-description-font-size`, `--stuic-card-opacity-disabled`.
+
+#### `Tree`
+
+Accessible, keyboard-navigable hierarchical tree view with optional drag-and-drop reordering, expand/collapse, and localStorage persistence.
+
+| Prop              | Type                                     | Default      | Description                          |
+| ----------------- | ---------------------------------------- | ------------ | ------------------------------------ |
+| `items`           | `TreeNodeDTO<T>[]`                       | required     | Tree data                            |
+| `renderItem`      | `Snippet<[item, depth, isExpanded]>`     | —            | Custom item content                  |
+| `renderIcon`      | `Snippet<[item, depth, isExpanded]>`     | —            | Custom item icon                     |
+| `activeId`        | `string`                                 | —            | Selected item ID                     |
+| `isActive`        | `(item) => boolean`                      | —            | Custom active check                  |
+| `onSelect`        | `(item) => void`                         | —            | Item selection callback              |
+| `onToggle`        | `(item, expanded) => void`               | —            | Branch toggle callback               |
+| `sort`            | `(a, b) => number`                       | —            | Sort comparator (per-level)          |
+| `defaultExpanded` | `boolean`                                | `false`      | Default expand state                 |
+| `expandedIds`     | `Set<string>`                            | —            | Initially expanded IDs               |
+| `persistState`    | `boolean`                                | `false`      | Save expand state to localStorage    |
+| `draggable`       | `boolean`                                | `false`      | Enable drag-and-drop                 |
+| `isDraggable`     | `(item) => boolean`                      | —            | Per-item drag control                |
+| `isDropTarget`    | `(item) => boolean`                      | —            | Per-item drop target control         |
+| `onMove`          | `(event: TreeMoveEvent) => void \| false`| —            | Drop handler; return false to reject |
+| `dragExpandDelay` | `number`                                 | `800`        | Auto-expand delay (ms) on drag hover |
+
+```svelte
+<Tree
+	items={treeData}
+	activeId={selectedId}
+	onSelect={(item) => (selectedId = item.id)}
+	draggable
+	onMove={handleMove}
+>
+	{#snippet renderItem(item, depth, isExpanded)}
+		<span>{item.value}</span>
+	{/snippet}
+</Tree>
+```
+
+Keyboard: Arrow keys (up/down/left/right), Enter/Space, Home/End.
+
+Exports: `Tree`, `TreeProps`, `TreeMoveEvent`, `TreeDropPosition`, `TreeNodeDTO`, `TREE_BASE_CLASSES`, `TREE_ITEM_CLASSES`, `TREE_CHILDREN_CLASSES`.
+
+CSS tokens: `--stuic-tree-indent`, `--stuic-tree-item-padding-x`, `--stuic-tree-item-padding-y`, `--stuic-tree-item-height`, `--stuic-tree-item-font-size`, `--stuic-tree-item-gap`, `--stuic-tree-chevron-opacity`, `--stuic-tree-icon-opacity`, `--stuic-tree-item-opacity-dragging`, `--stuic-tree-item-bg`, `--stuic-tree-item-text`, `--stuic-tree-item-bg-hover`, `--stuic-tree-item-text-hover`, `--stuic-tree-item-bg-active`, `--stuic-tree-item-text-active`, `--stuic-tree-item-bg-focus`, `--stuic-tree-item-text-focus`, `--stuic-tree-drop-indicator-color`, `--stuic-tree-drop-indicator-height`, `--stuic-tree-item-bg-dragover`.
+
 #### `X`
 
 Styled SVG close/multiply icon with configurable stroke width.

package/README.md

@@ -144,11 +144,11 @@ See [API.md](API.md) for the full list of exported theme types (`ThemeSchema`, `
 
 ### Layout & Overlays
 
-AppShell, Accordion, Backdrop, Modal, ModalDialog, Drawer, Collapsible, SlidingPanels, Nav, WithSidePanel
+AppShell, Accordion, Backdrop, Modal, ModalDialog, Drawer, Collapsible, Header, SlidingPanels, Nav, WithSidePanel
 
 ### Forms & Inputs
 
-FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, FieldPhoneNumber, Fieldset, LoginForm, LoginFormModal
+FieldInput, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios, FieldFile, FieldAssets, FieldOptions, FieldKeyValues, FieldObject, FieldSwitch, FieldInputLocalized, FieldLikeButton, FieldPhoneNumber, CronInput, Fieldset, LoginForm, LoginFormModal
 
 ### Buttons & Controls
 
@@ -164,7 +164,7 @@ CommandMenu, DropdownMenu, TabbedMenu, TypeaheadInput, KbdShortcut
 
 ### Display & Utility
 
-Avatar, Book, BookResponsive, Carousel, Circle, AnimatedElipsis, H, IconSwap, ImageCycler, Separator, ThemePreview, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, AssetsPreviewInline, DataTable
+Avatar, Book, BookResponsive, Card, Carousel, Circle, AnimatedElipsis, H, IconSwap, ImageCycler, Separator, ThemePreview, Tree, ColorScheme, Thc, HoverExpandableWidth, AssetsPreview, AssetsPreviewInline, DataTable
 
 ### E-commerce
 

package/dist/components/Header/Header.svelte

@@ -0,0 +1,315 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { THC } from "../Thc/Thc.svelte";
+	import type {
+		DropdownMenuPosition,
+		DropdownMenuItem,
+		DropdownMenuActionItem,
+	} from "../DropdownMenu/DropdownMenu.svelte";
+
+	export interface HeaderNavItem {
+		/** Unique identifier */
+		id: string | number;
+		/** Display label — supports THC (string, html, component, snippet) */
+		label: THC;
+		/** Navigation URL (renders as <a> in expanded mode) */
+		href?: string;
+		/** Click handler (alternative to href) */
+		onclick?: () => void;
+		/** Icon before the label — supports THC */
+		icon?: THC;
+		/** Whether this item is the current/active page */
+		active?: boolean;
+		/** Whether this item is disabled */
+		disabled?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+	}
+
+	export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+		/** Logo/brand snippet — full control over the left branding area */
+		logo?: Snippet;
+		/** Simple text alternative to the logo snippet */
+		projectName?: string;
+		/** Navigation items — inline when expanded, DropdownMenu when collapsed */
+		items?: HeaderNavItem[];
+		/** Avatar/user snippet — rendered at the far right */
+		avatar?: Snippet;
+		/** When provided, makes the avatar interactive. In expanded mode wraps it in a
+		 *  button; in collapsed mode moves it into the dropdown as an action item. */
+		avatarOnClick?: () => void;
+		/** Label for the avatar dropdown item in collapsed mode (defaults to "Account") */
+		avatarLabel?: THC;
+		/** Element width (px) below which nav collapses to hamburger. 0 to disable. */
+		collapseThreshold?: number;
+		/** Fixed positioning (top of viewport) */
+		fixed?: boolean;
+		/** Bindable: whether the header is currently in collapsed (hamburger) mode */
+		isCollapsed?: boolean;
+		/** Bindable: whether the hamburger dropdown is currently open */
+		isMenuOpen?: boolean;
+		/** Position for the collapsed dropdown menu */
+		dropdownPosition?: DropdownMenuPosition;
+		/** Hamburger/X icon size in px */
+		iconSize?: number;
+		/** Called when a nav item is selected (both modes) */
+		onSelect?: (item: HeaderNavItem) => void;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes for the root <header> */
+		class?: string;
+		/** Classes for the logo area */
+		classLogo?: string;
+		/** Classes for the nav area (expanded mode) */
+		classNav?: string;
+		/** Classes for individual nav items (expanded mode) */
+		classNavItem?: string;
+		/** Classes for active nav items */
+		classNavItemActive?: string;
+		/** Classes for the end area (avatar + hamburger) */
+		classEnd?: string;
+		/** Classes for the avatar container */
+		classAvatar?: string;
+		/** Classes for the hamburger button */
+		classHamburger?: string;
+		/** Classes for the dropdown wrapper (collapsed mode) */
+		classDropdown?: string;
+		/** Escape hatch: override the entire inner layout */
+		children?: Snippet<
+			[{ isCollapsed: boolean; items: HeaderNavItem[]; offsetWidth: number }]
+		>;
+		/** Bindable root element reference */
+		el?: HTMLElement;
+	}
+
+	export const HEADER_BASE_CLASSES = "stuic-header";
+	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_END_CLASSES = "stuic-header-end";
+	export const HEADER_HAMBURGER_CLASSES = "stuic-header-hamburger";
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { iconMenu, iconX } from "../../icons/index.js";
+	import Thc from "../Thc/Thc.svelte";
+	import Button from "../Button/Button.svelte";
+	import DropdownMenu from "../DropdownMenu/DropdownMenu.svelte";
+	import IconSwap from "../IconSwap/IconSwap.svelte";
+
+	let {
+		logo,
+		projectName,
+		items = [],
+		avatar,
+		avatarOnClick,
+		avatarLabel = "Account",
+		collapseThreshold = 768,
+		fixed = false,
+		isCollapsed = $bindable(false),
+		isMenuOpen = $bindable(false),
+		dropdownPosition = "bottom-span-right",
+		iconSize = 24,
+		onSelect,
+		unstyled = false,
+		class: classProp,
+		classLogo,
+		classNav,
+		classNavItem,
+		classNavItemActive,
+		classEnd,
+		classAvatar,
+		classHamburger,
+		classDropdown,
+		children,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	// Width measurement (same pattern as Card)
+	let _offsetWidth = $state(0);
+
+	// Collapsed state based on threshold
+	let _isCollapsed = $derived.by(() => {
+		if (!collapseThreshold) return false;
+		return _offsetWidth > 0 && _offsetWidth < collapseThreshold;
+	});
+
+	// Sync bindable
+	$effect(() => {
+		isCollapsed = _isCollapsed;
+	});
+
+	// Close menu when switching from collapsed to expanded
+	$effect(() => {
+		if (!_isCollapsed && isMenuOpen) {
+			isMenuOpen = false;
+		}
+	});
+
+	// Whether the avatar moves into the dropdown when collapsed
+	let _avatarInDropdown = $derived(!!(avatar && avatarOnClick));
+
+	// Map HeaderNavItem[] to DropdownMenuItem[] for collapsed mode
+	let _dropdownItems = $derived.by((): DropdownMenuItem[] => {
+		const navItems: DropdownMenuItem[] = items.map(
+			(item) =>
+				({
+					type: "action" as const,
+					id: item.id,
+					label: item.label,
+					contentBefore: item.icon,
+					disabled: item.disabled,
+					class: item.class,
+					onSelect: () => {
+						if (item.href) window.location.href = item.href;
+						item.onclick?.();
+						onSelect?.(item);
+					},
+				}) satisfies DropdownMenuActionItem
+		);
+
+		// Append avatar as a dropdown item when avatarOnClick is set
+		if (_avatarInDropdown) {
+			if (navItems.length > 0) {
+				navItems.push({ type: "divider" });
+			}
+			navItems.push({
+				type: "action",
+				id: "__avatar__",
+				label: avatarLabel!,
+				onSelect: () => avatarOnClick!(),
+			} satisfies DropdownMenuActionItem);
+		}
+
+		return navItems;
+	});
+
+	// CSS classes
+	let _class = $derived(unstyled ? classProp : twMerge(HEADER_BASE_CLASSES, classProp));
+	let _classLogo = $derived(
+		unstyled ? classLogo : twMerge(HEADER_LOGO_CLASSES, classLogo)
+	);
+	let _classNav = $derived(unstyled ? classNav : twMerge(HEADER_NAV_CLASSES, classNav));
+	let _classEnd = $derived(unstyled ? classEnd : twMerge(HEADER_END_CLASSES, classEnd));
+
+	function handleItemClick(item: HeaderNavItem) {
+		if (item.disabled) return;
+		item.onclick?.();
+		onSelect?.(item);
+	}
+</script>
+
+<header
+	bind:this={el}
+	bind:offsetWidth={_offsetWidth}
+	class={_class}
+	data-fixed={!unstyled && fixed ? "" : undefined}
+	data-collapsed={!unstyled && _isCollapsed ? "" : undefined}
+	{...rest}
+>
+	{#if children}
+		{@render children({
+			isCollapsed: _isCollapsed,
+			items,
+			offsetWidth: _offsetWidth,
+		})}
+	{: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>
+		{/if}
+
+		<!-- Nav items (expanded mode) -->
+		{#if !_isCollapsed && items.length > 0}
+			<nav class={_classNav}>
+				{#each items as item (item.id)}
+					<Button
+						variant="ghost"
+						size="sm"
+						href={item.href}
+						disabled={item.disabled}
+						{unstyled}
+						class={twMerge(
+							!unstyled && HEADER_NAV_ITEM_CLASSES,
+							!unstyled && item.active && classNavItemActive,
+							classNavItem,
+							item.class
+						)}
+						data-active={!unstyled && item.active ? "" : undefined}
+						aria-current={item.active ? "page" : undefined}
+						onclick={() => handleItemClick(item)}
+					>
+						{#if item.icon}
+							<span class={unstyled ? undefined : "stuic-header-nav-icon"}>
+								<Thc thc={item.icon} />
+							</span>
+						{/if}
+						<Thc thc={item.label} />
+					</Button>
+				{/each}
+			</nav>
+		{/if}
+
+		<!-- Spacer -->
+		<div class={unstyled ? undefined : "stuic-header-spacer"}></div>
+
+		<!-- End area: avatar + hamburger -->
+		<div class={_classEnd}>
+			<!-- Avatar: hidden when collapsed + avatarOnClick (moves into dropdown) -->
+			{#if avatar && !(_isCollapsed && _avatarInDropdown)}
+				{#if avatarOnClick}
+					<button
+						type="button"
+						class={twMerge(!unstyled && "stuic-header-avatar", classAvatar)}
+						onclick={avatarOnClick}
+					>
+						{@render avatar()}
+					</button>
+				{:else}
+					<div class={twMerge(!unstyled && "stuic-header-avatar", classAvatar)}>
+						{@render avatar()}
+					</div>
+				{/if}
+			{/if}
+
+			{#if _isCollapsed && _dropdownItems.length > 0}
+				<DropdownMenu
+					items={_dropdownItems}
+					bind:isOpen={isMenuOpen}
+					position={dropdownPosition}
+					class={classDropdown}
+				>
+					{#snippet trigger({ isOpen, toggle, triggerProps })}
+						<Button
+							variant="ghost"
+							roundedFull
+							aspect1
+							size="sm"
+							{unstyled}
+							class={twMerge(!unstyled && HEADER_HAMBURGER_CLASSES, classHamburger)}
+							onclick={toggle}
+							aria-label={isOpen ? "Close menu" : "Open menu"}
+							{...triggerProps}
+						>
+							<IconSwap
+								active={isOpen ? 1 : 0}
+								states={[iconMenu({ size: iconSize }), iconX({ size: iconSize })]}
+							/>
+						</Button>
+					{/snippet}
+				</DropdownMenu>
+			{/if}
+		</div>
+	{/if}
+</header>

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

@@ -0,0 +1,90 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import type { THC } from "../Thc/Thc.svelte";
+import type { DropdownMenuPosition } from "../DropdownMenu/DropdownMenu.svelte";
+export interface HeaderNavItem {
+    /** Unique identifier */
+    id: string | number;
+    /** Display label — supports THC (string, html, component, snippet) */
+    label: THC;
+    /** Navigation URL (renders as <a> in expanded mode) */
+    href?: string;
+    /** Click handler (alternative to href) */
+    onclick?: () => void;
+    /** Icon before the label — supports THC */
+    icon?: THC;
+    /** Whether this item is the current/active page */
+    active?: boolean;
+    /** Whether this item is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+}
+export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** Logo/brand snippet — full control over the left branding area */
+    logo?: Snippet;
+    /** Simple text alternative to the logo snippet */
+    projectName?: string;
+    /** Navigation items — inline when expanded, DropdownMenu when collapsed */
+    items?: HeaderNavItem[];
+    /** Avatar/user snippet — rendered at the far right */
+    avatar?: Snippet;
+    /** When provided, makes the avatar interactive. In expanded mode wraps it in a
+     *  button; in collapsed mode moves it into the dropdown as an action item. */
+    avatarOnClick?: () => void;
+    /** Label for the avatar dropdown item in collapsed mode (defaults to "Account") */
+    avatarLabel?: THC;
+    /** Element width (px) below which nav collapses to hamburger. 0 to disable. */
+    collapseThreshold?: number;
+    /** Fixed positioning (top of viewport) */
+    fixed?: boolean;
+    /** Bindable: whether the header is currently in collapsed (hamburger) mode */
+    isCollapsed?: boolean;
+    /** Bindable: whether the hamburger dropdown is currently open */
+    isMenuOpen?: boolean;
+    /** Position for the collapsed dropdown menu */
+    dropdownPosition?: DropdownMenuPosition;
+    /** Hamburger/X icon size in px */
+    iconSize?: number;
+    /** Called when a nav item is selected (both modes) */
+    onSelect?: (item: HeaderNavItem) => void;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes for the root <header> */
+    class?: string;
+    /** Classes for the logo area */
+    classLogo?: string;
+    /** Classes for the nav area (expanded mode) */
+    classNav?: string;
+    /** Classes for individual nav items (expanded mode) */
+    classNavItem?: string;
+    /** Classes for active nav items */
+    classNavItemActive?: string;
+    /** Classes for the end area (avatar + hamburger) */
+    classEnd?: string;
+    /** Classes for the avatar container */
+    classAvatar?: string;
+    /** Classes for the hamburger button */
+    classHamburger?: string;
+    /** Classes for the dropdown wrapper (collapsed mode) */
+    classDropdown?: string;
+    /** Escape hatch: override the entire inner layout */
+    children?: Snippet<[
+        {
+            isCollapsed: boolean;
+            items: HeaderNavItem[];
+            offsetWidth: number;
+        }
+    ]>;
+    /** Bindable root element reference */
+    el?: HTMLElement;
+}
+export declare const HEADER_BASE_CLASSES = "stuic-header";
+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_END_CLASSES = "stuic-header-end";
+export declare const HEADER_HAMBURGER_CLASSES = "stuic-header-hamburger";
+declare const Header: import("svelte").Component<Props, {}, "el" | "isCollapsed" | "isMenuOpen">;
+type Header = ReturnType<typeof Header>;
+export default Header;

package/dist/components/Header/index.css

@@ -0,0 +1,135 @@
+/* ============================================================================
+   HEADER COMPONENT TOKENS
+   Override globally: :root { --stuic-header-bg: red; }
+   Override locally:  <Header style="--stuic-header-bg: red;">
+   ============================================================================ */
+
+:root {
+	/* Structure */
+	--stuic-header-padding-x: 1rem;
+	--stuic-header-padding-y: 0.75rem;
+	--stuic-header-gap: 1rem;
+	--stuic-header-min-height: 3.5rem;
+
+	/* Nav items */
+	--stuic-header-nav-gap: 0.25rem;
+
+	/* Project name */
+	--stuic-header-project-name-font-weight: var(--font-weight-semibold, 600);
+
+	/* Fixed mode */
+	--stuic-header-z-index: 40;
+}
+
+@layer components {
+	/* ============================================================================
+	   BASE
+	   ============================================================================ */
+
+	.stuic-header {
+		display: flex;
+		align-items: center;
+		width: 100%;
+		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);
+		border-bottom: var(--stuic-header-border-width, var(--stuic-border-width)) solid
+			var(--stuic-header-border-color, var(--color-border, transparent));
+	}
+
+	/* ============================================================================
+	   FIXED
+	   ============================================================================ */
+
+	.stuic-header[data-fixed] {
+		position: fixed;
+		top: 0;
+		left: 0;
+		right: 0;
+		z-index: var(--stuic-header-z-index);
+	}
+
+	/* ============================================================================
+	   LOGO
+	   ============================================================================ */
+
+	.stuic-header-logo {
+		display: flex;
+		align-items: center;
+		flex-shrink: 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);
+		white-space: nowrap;
+	}
+
+	/* ============================================================================
+	   NAV (expanded mode) — items are ghost Buttons
+	   ============================================================================ */
+
+	.stuic-header-nav {
+		display: flex;
+		align-items: center;
+		gap: var(--stuic-header-nav-gap);
+	}
+
+	/* Active state highlight for nav Buttons */
+	.stuic-header-nav-item[data-active] {
+		color: var(--stuic-header-nav-item-text-active, var(--color-foreground, inherit));
+		background: var(--stuic-header-nav-item-bg-active, var(--color-muted, transparent));
+	}
+
+	/* ============================================================================
+	   NAV ICON (inline icon before label)
+	   ============================================================================ */
+
+	.stuic-header-nav-icon {
+		display: inline-flex;
+		align-items: center;
+		flex-shrink: 0;
+	}
+
+	/* ============================================================================
+	   SPACER
+	   ============================================================================ */
+
+	.stuic-header-spacer {
+		flex: 1;
+	}
+
+	/* ============================================================================
+	   END AREA (avatar + hamburger)
+	   ============================================================================ */
+
+	.stuic-header-end {
+		display: flex;
+		align-items: center;
+		gap: var(--stuic-header-gap);
+		flex-shrink: 0;
+	}
+
+	.stuic-header-avatar {
+		display: flex;
+		align-items: center;
+	}
+
+	button.stuic-header-avatar {
+		border: none;
+		background: none;
+		padding: 0;
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+	}
+
+	/* ============================================================================
+	   HAMBURGER
+	   ============================================================================ */
+
+	.stuic-header-hamburger {
+		/* Ghost Button handles hover/focus — only override sizing */
+	}
+}

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

@@ -0,0 +1 @@
+export { default as Header, type Props as HeaderProps, type HeaderNavItem, HEADER_BASE_CLASSES, HEADER_LOGO_CLASSES, HEADER_NAV_CLASSES, HEADER_NAV_ITEM_CLASSES, HEADER_END_CLASSES, HEADER_HAMBURGER_CLASSES, } from "./Header.svelte";

package/dist/components/Header/index.js

@@ -0,0 +1 @@
+export { default as Header, HEADER_BASE_CLASSES, HEADER_LOGO_CLASSES, HEADER_NAV_CLASSES, HEADER_NAV_ITEM_CLASSES, HEADER_END_CLASSES, HEADER_HAMBURGER_CLASSES, } from "./Header.svelte";

package/dist/index.css

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/docs/domains/components.md

@@ -2,24 +2,25 @@
 
 ## Overview
 
-46 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+50 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
 ### Layout
 
-| Component                | Purpose                                            |
-| ------------------------ | -------------------------------------------------- |
-| AppShell, AppShellSimple | Page layouts with header/sidebar/content           |
-| Modal, ModalDialog       | Overlay containers                                 |
-| Drawer                   | Side panel overlay                                 |
-| Backdrop                 | Semi-transparent overlay with escape/focus trap    |
-| Collapsible              | Expandable sections                                |
-| Accordion                | Exclusive/multi-open expandable sections           |
-| SlidingPanels            | Panel transitions                                  |
-| TabbedMenu               | Tab navigation                                     |
-| Nav                      | Navigation wrapper                                 |
-| WithSidePanel            | Two-column layout with collapsible/resizable panel |
+| Component                | Purpose                                              |
+| ------------------------ | ---------------------------------------------------- |
+| AppShell, AppShellSimple | Page layouts with header/sidebar/content             |
+| Header                   | Responsive nav header with hamburger collapse        |
+| Modal, ModalDialog       | Overlay containers                                   |
+| Drawer                   | Side panel overlay                                   |
+| Backdrop                 | Semi-transparent overlay with escape/focus trap      |
+| Collapsible              | Expandable sections                                  |
+| Accordion                | Exclusive/multi-open expandable sections             |
+| SlidingPanels            | Panel transitions                                    |
+| TabbedMenu               | Tab navigation                                       |
+| Nav                      | Navigation wrapper                                   |
+| WithSidePanel            | Two-column layout with collapsible/resizable panel   |
 
 ### Interactive
 
@@ -56,6 +57,7 @@
 | Input (FieldInput, FieldSelect, etc.) | Form fields                                       |
 | FieldPhoneNumber                      | International phone input with country picker      |
 | FieldObject                           | Dual-mode JSON object editor (pretty-print/raw)   |
+| CronInput                             | Cron expression editor with presets and validation |
 | Fieldset                              | Field grouping with legend                        |
 | FieldKeyValues                        | Key-value pair editor                             |
 | FieldAssets                           | File/asset management                             |
@@ -81,6 +83,8 @@
 | H               | Semantic heading (h1-h6) with separate visual/semantic levels       |
 | Separator       | Horizontal/vertical separator line                                  |
 | Thc             | Flexible renderer for text, HTML, components, or snippets           |
+| Card            | Flexible card with image, title, footer; vertical/horizontal layout |
+| Tree            | Hierarchical tree view with keyboard nav and drag-and-drop          |
 | X               | Styled close/multiply SVG icon                                      |
 | ImageCycler     | Auto-cycling image carousel with fade transitions and preloading    |
 
@@ -373,6 +377,199 @@ Components use private CSS vars (`--_*`) set by intent/variant:
 
 ---
 
+## Card
+
+Flexible, responsive card for displaying content in a contained box. Supports images (top or side), titles, descriptions, footers, and interactive states.
+
+### Exports
+
+| Export        | Kind      | Description                          |
+| ------------- | --------- | ------------------------------------ |
+| `Card`        | component | Main card component                  |
+| `CardProps`   | type      | Props type                           |
+| `CardVariant` | type      | `"vertical" \| "horizontal"`        |
+
+### Key Props
+
+| Prop                   | Type                     | Default      | Description                                  |
+| ---------------------- | ------------------------ | ------------ | -------------------------------------------- |
+| `image`                | `string`                 | —            | Image URL                                    |
+| `eyebrow`              | `THC`                    | —            | Small label above title                      |
+| `title`                | `THC`                    | —            | Card title                                   |
+| `description`          | `THC`                    | —            | Short description                            |
+| `variant`              | `CardVariant`            | `"vertical"` | Layout direction                             |
+| `href`                 | `string`                 | —            | Renders as `<a>`                             |
+| `onclick`              | `(e) => void`            | —            | Renders as `<button>`                        |
+| `disabled`             | `boolean`                | `false`      | Disable interaction                          |
+| `horizontalThreshold`  | `number`                 | `480`        | Width (px) to auto-switch to vertical; 0 disables |
+
+Snippets: `children`, `renderImage`, `renderBadge`, `renderContent`, `renderFooter`.
+
+### CSS Tokens
+
+Prefix: `--stuic-card-*`
+
+`bg`, `bg-hover`, `border`, `border-hover`, `padding`, `content-gap`, `image-aspect-ratio`, `image-object-fit`, `image-width-horizontal`, `radius`, `shadow`, `shadow-hover`, `ring-width`, `ring-color`, `eyebrow-font-size`, `eyebrow-text`, `title-font-size`, `title-font-weight`, `title-text`, `description-font-size`, `description-text`, `opacity-disabled`
+
+---
+
+## CronInput
+
+Cron expression editor with preset selector, manual 5-field editor, raw expression input, human-readable descriptions, and next-run calculation.
+
+### Exports
+
+| Export                 | Kind      | Description                              |
+| ---------------------- | --------- | ---------------------------------------- |
+| `CronInput`            | component | Main cron editor                         |
+| `CronInputProps`       | type      | Props type                               |
+| `CronPreset`           | type      | Preset interface `{ label, value }`      |
+| `CronInputMode`        | type      | `"predefined" \| "manual"`              |
+| `CRON_DEFAULT_PRESETS`  | constant  | Default preset array (11 common schedules) |
+| `CronNextRun`          | class     | Reactive helper for standalone cron calculations |
+
+### Key Props
+
+| Prop              | Type              | Default       | Description                       |
+| ----------------- | ----------------- | ------------- | --------------------------------- |
+| `value`           | `string`          | `"* * * * *"` | Bindable cron expression          |
+| `mode`            | `CronInputMode`   | —             | Bindable; predefined or manual    |
+| `showPresets`     | `boolean`         | `true`        | Show preset selector              |
+| `showFields`      | `boolean`         | `true`        | Show 5-column field editor        |
+| `showRawInput`    | `boolean`         | `true`        | Show raw expression input         |
+| `showDescription` | `boolean`         | `true`        | Show human-readable description   |
+| `showNextRun`     | `boolean`         | `true`        | Show next run time                |
+| `presets`         | `CronPreset[]`    | default set   | Custom presets                    |
+| `onchange`        | `(expr, valid) => void` | —       | Change callback                   |
+
+Integrates with `InputWrap` — supports `label`, `description`, `renderSize`, `required`, `disabled`, `validate`, `labelLeft`, `below`.
+
+### CronNextRun Class
+
+Reactive helper for standalone cron calculations:
+
+```ts
+const next = new CronNextRun("0 9 * * 1-5");
+next.nextRun;          // Date | null
+next.nextRunFormatted; // "YYYY-MM-DD HH:MM"
+next.valid;            // boolean
+next.destroy();        // cleanup timer
+```
+
+### CSS Tokens
+
+Prefix: `--stuic-cron-input-*`
+
+`fields-gap`, `section-gap`, `field-label-text`, `summary-text`, `error-text`, `field-bg`, `field-border`, `field-border-focus`
+
+---
+
+## Header
+
+Responsive navigation header with logo, nav items, avatar, and automatic hamburger collapse.
+
+### Exports
+
+| Export                     | Kind     | Description               |
+| -------------------------- | -------- | ------------------------- |
+| `Header`                   | component | Main header component    |
+| `HeaderProps`              | type     | Props type                |
+| `HeaderNavItem`            | type     | Nav item interface        |
+| `HEADER_BASE_CLASSES`      | constant | `"stuic-header"`          |
+| `HEADER_LOGO_CLASSES`      | constant | `"stuic-header-logo"`     |
+| `HEADER_NAV_CLASSES`       | constant | `"stuic-header-nav"`      |
+| `HEADER_NAV_ITEM_CLASSES`  | constant | `"stuic-header-nav-item"` |
+| `HEADER_END_CLASSES`       | constant | `"stuic-header-end"`      |
+| `HEADER_HAMBURGER_CLASSES` | constant | `"stuic-header-hamburger"` |
+
+### HeaderNavItem
+
+```ts
+interface HeaderNavItem {
+  id: string | number;
+  label: THC;
+  href?: string;
+  onclick?: () => void;
+  icon?: THC;
+  active?: boolean;
+  disabled?: boolean;
+  class?: string;
+}
+```
+
+### Key Props
+
+| 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              |
+
+Snippets: `logo`, `avatar`, `children({ isCollapsed, items, offsetWidth })`.
+
+### CSS Tokens
+
+Prefix: `--stuic-header-*`
+
+`padding-x`, `padding-y`, `gap`, `min-height`, `nav-gap`, `project-name-font-weight`, `z-index`, `bg`, `text`, `border-width`, `border-color`, `nav-item-bg-active`, `nav-item-text-active`
+
+---
+
+## Tree
+
+Accessible, keyboard-navigable hierarchical tree view with optional drag-and-drop reordering and localStorage persistence.
+
+### Exports
+
+| Export              | Kind      | Description                                |
+| ------------------- | --------- | ------------------------------------------ |
+| `Tree`              | component | Main tree component                        |
+| `TreeProps`         | type      | Props type                                 |
+| `TreeMoveEvent`     | type      | Drag-drop event interface                  |
+| `TreeDropPosition`  | type      | `"before" \| "after" \| "inside"`         |
+| `TREE_BASE_CLASSES` | constant  | `"stuic-tree"`                             |
+| `TREE_ITEM_CLASSES` | constant  | `"stuic-tree-item"`                        |
+| `TREE_CHILDREN_CLASSES` | constant | `"stuic-tree-children"`                 |
+| `TreeNodeDTO`       | type      | Re-exported from `@marianmeres/tree`       |
+
+### Key Props
+
+| Prop              | Type                       | Default        | Description                             |
+| ----------------- | -------------------------- | -------------- | --------------------------------------- |
+| `items`           | `TreeNodeDTO<T>[]`         | required       | Tree data                               |
+| `renderItem`      | `Snippet<[item, depth, isExpanded]>` | —   | Custom item content                     |
+| `renderIcon`      | `Snippet<[item, depth, isExpanded]>` | —   | Custom item icon                        |
+| `activeId`        | `string`                   | —              | Selected item ID                        |
+| `isActive`        | `(item) => boolean`        | —              | Custom active check                     |
+| `onSelect`        | `(item) => void`           | —              | Item selection callback                 |
+| `onToggle`        | `(item, expanded) => void` | —              | Branch toggle callback                  |
+| `sort`            | `(a, b) => number`         | —              | Sort comparator (per-level)             |
+| `defaultExpanded` | `boolean`                  | `false`        | Default expand state                    |
+| `expandedIds`     | `Set<string>`              | —              | Initially expanded IDs                  |
+| `persistState`    | `boolean`                  | `false`        | Save expand state to localStorage       |
+| `draggable`       | `boolean`                  | `false`        | Enable drag-and-drop                    |
+| `isDraggable`     | `(item) => boolean`        | —              | Per-item drag control                   |
+| `isDropTarget`    | `(item) => boolean`        | —              | Per-item drop target control            |
+| `onMove`          | `(event) => void \| false` | —              | Drop handler; return false to reject    |
+| `dragExpandDelay` | `number`                   | `800`          | Auto-expand delay (ms) on drag hover   |
+
+Features: arrow-key navigation, Home/End, Enter/Space, roving tabindex, slide transitions (respects `prefers-reduced-motion`).
+
+### CSS Tokens
+
+Prefix: `--stuic-tree-*`
+
+`indent`, `item-padding-x`, `item-padding-y`, `item-height`, `item-font-size`, `item-gap`, `chevron-opacity`, `icon-opacity`, `item-opacity-dragging`, `item-bg`, `item-text`, `item-bg-hover`, `item-text-hover`, `item-bg-active`, `item-text-active`, `item-bg-focus`, `item-text-focus`, `drop-indicator-color`, `drop-indicator-height`, `item-bg-dragover`
+
+---
+
 ## Key Files
 
 | File                          | Purpose                                               |
@@ -382,4 +579,6 @@ Components use private CSS vars (`--_*`) set by intent/variant:
 | src/lib/components/Input/     | Form field patterns (incl. FieldObject)               |
 | src/lib/components/LoginForm/ | Standalone login form + modal variant                 |
 | src/lib/components/Checkout/  | E-commerce checkout flow (14 exported sub-components) |
+| src/lib/components/Card/      | Card with image/title/footer variants                 |
+| src/lib/components/Tree/      | Hierarchical tree with drag-and-drop                  |
 | src/lib/index.ts              | All component exports                                 |

package/package.json

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