@jelinek/ui 0.3.0

package/dist/components/SiteHeader.svelte

@@ -0,0 +1,613 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn } from '../utils/cn.js';
+	import Button from './Button.svelte';
+	import { createChapterNavDock } from '../utils/chapter-nav-dock.svelte.js';
+	import { DEER_MARK_PATH } from './deer-mark-path.js';
+	import { isActive, type NavItem } from './nav.js';
+
+	interface Props {
+		/**
+		 * Escape hatch: a snippet rendering custom mark content in place of the
+		 * bundled, re-theming deer mark (e.g. a division-specific logo). Most
+		 * consumers should leave this unset and get the guide's own mark.
+		 */
+		logo?: Snippet;
+		logoAlt?: string;
+		/**
+		 * Where the logo/mark links to. Defaults to `/`, the guide's own
+		 * literal href (partials/header.html:3) — set this when the consuming
+		 * app is not rooted at `/`, e.g. mounted under a base path.
+		 */
+		logoHref?: string;
+		subtitle?: string;
+		items?: NavItem[];
+		active?: string;
+		/**
+		 * Set when a `ChapterNav` is rendered directly below this header, to
+		 * reproduce the guide's joined-panel seam (jelinek.css:604-620): the
+		 * header loses its bottom border/corners/shadow so it flows into the
+		 * nav strip, until the reader scrolls past 50px and it detaches into
+		 * its own rounded, shadowed bar (assets/js/jelinek.js:354). SiteHeader
+		 * tracks that scroll threshold itself — a consumer never has to wire
+		 * up a listener. Leave unset (default `false`) for the normal,
+		 * always-detached header, e.g. the rozcestník, which has no chapter
+		 * nav at all.
+		 */
+		hasChapterNav?: boolean;
+		/**
+		 * Accessible name for the `<nav>` landmark holding the top-level
+		 * links. Czech by default, like every other user-facing string this
+		 * kit ships (see Pager's `prevLabel`/`nextLabel`).
+		 */
+		navLabel?: string;
+		/**
+		 * Chapter links to repeat inside the phone menu panel. Below 640px the
+		 * guide's chapter bar is `display: none` (see ChapterNav.svelte), so the
+		 * chapters have nowhere else to live on a phone; the guide's own script
+		 * clones them out of the rendered bar, and this prop is that same content
+		 * passed declaratively instead. Leave unset on pages with no chapter nav
+		 * (the rozcestník) — the divider and the block disappear with it. They
+		 * are hidden again from 640px up, where the bar itself is back.
+		 */
+		chapterItems?: NavItem[];
+		/**
+		 * Accessible name for the phone hamburger button while the menu is SHUT.
+		 * It has no visible text — it is three bars that fold into a cross — so
+		 * this is the only name a screen reader gets. See BURGER below.
+		 */
+		menuLabel?: string;
+		/** Accessible name for the same button while the menu is OPEN. */
+		menuLabelClose?: string;
+		/**
+		 * Task 37 — TRAILING CONTENT INSIDE THE NAV, which the guide requires and
+		 * this component previously refused.
+		 *
+		 * partials/header.html:6-13 nests the theme toggle as the LAST CHILD of
+		 * `.site-header__nav`, so it sits in the nav row on a desktop and moves
+		 * into the burger panel on a phone along with the links. The earlier
+		 * decision here was to keep ThemeToggle separate and let a consumer
+		 * "render both together in its own layout" — but a consumer cannot put
+		 * anything inside this component's nav from outside it, so what that
+		 * actually produced was a toggle stranded in the page body, at a different
+		 * place from the guide and gone from the phone menu entirely.
+		 *
+		 * Rendered into BOTH navs, after the links, exactly like `items`. Keep it
+		 * to controls that belong to the header (the toggle, a division switch) —
+		 * it is not a general slot.
+		 */
+		actions?: Snippet;
+		class?: string;
+	}
+
+	let {
+		logo,
+		logoAlt = 'JELÍNEK',
+		logoHref = '/',
+		subtitle,
+		items = [],
+		active,
+		hasChapterNav = false,
+		chapterItems = [],
+		navLabel = 'Hlavní navigace',
+		menuLabel = 'Otevřít menu',
+		menuLabelClose = 'Zavřít menu',
+		actions,
+		class: className,
+		...rest
+	}: Props & HTMLAttributes<HTMLElement> = $props();
+
+	// Task 15 — see chapter-nav-dock.svelte.ts for the full reasoning (the
+	// :root:has()/scroll-linked-<html>-class trick this replaces, and why the
+	// scroll tracking lives in its own module). `dock.docked` is true only
+	// while BOTH a chapter nav is present (hasChapterNav) AND the page hasn't
+	// scrolled past 50px — reproduces
+	// `:root:has(.chapter-nav):not(.is-subnav-scrolled)` without reaching
+	// outside this component.
+	const dock = createChapterNavDock(() => hasChapterNav);
+
+	// Task 26 — phone disclosure state. See MENU_BUTTON below for why the
+	// links collapse at all. `$props.id()` gives the panel a per-instance id
+	// so `aria-controls` still resolves when a page renders more than one
+	// header (a showcase or a docs page embedding the component).
+	const uid = $props.id();
+	const panelId = `${uid}-links`;
+	let menuOpen = $state(false);
+	let menuButton = $state<HTMLButtonElement | null>(null);
+	let linksEl = $state<HTMLElement | null>(null);
+
+	// Closing the panel while focus is still inside it would drop focus onto
+	// <body>, restarting keyboard navigation from the top of the page. Every
+	// close path goes through here so that cannot happen — Escape, a click
+	// outside, and the breakpoint crossing below.
+	function closeMenu() {
+		if (linksEl?.contains(document.activeElement)) {
+			const button = menuButton;
+			button?.focus();
+			// A pointerdown-driven close is not finished when this runs: the
+			// browser's own mousedown focus handling comes next and overwrites
+			// what we just set — with the clicked element if it is focusable, or
+			// with <body> if it is not. Reclaim focus on the following task, but
+			// only from <body>: that is the actual defect (keyboard navigation
+			// restarting from the top of the document), and a real click on a
+			// real control should keep the focus it earned.
+			setTimeout(() => {
+				if (document.activeElement === document.body) button?.focus();
+			}, 0);
+		}
+		menuOpen = false;
+	}
+
+	// Dismissal, matching assets/js/jelinek.js's own initHeaderMenu().
+	// `pointerdown`, not `click`: iOS Safari does not propagate a click from an
+	// element that is not itself clickable up to `document`, so a tap on body
+	// text would leave the panel open. Listeners exist only while the menu is
+	// open — nothing is attached on a desktop render, or on a phone render with
+	// the menu shut.
+	$effect(() => {
+		if (!menuOpen) return;
+		function onPointerDown(event: PointerEvent) {
+			const target = event.target as Node | null;
+			if (target && (linksEl?.contains(target) || menuButton?.contains(target))) return;
+			closeMenu();
+		}
+		function onKeyDown(event: KeyboardEvent) {
+			if (event.key !== 'Escape') return;
+			menuButton?.focus();
+			menuOpen = false;
+		}
+		document.addEventListener('pointerdown', onPointerDown);
+		document.addEventListener('keydown', onKeyDown);
+		return () => {
+			document.removeEventListener('pointerdown', onPointerDown);
+			document.removeEventListener('keydown', onKeyDown);
+		};
+	});
+
+	// From 640px up the button is display:none and the links are back in the
+	// row. Leaving `menuOpen` true across that boundary means the panel springs
+	// open again unasked on the way back down, and `aria-expanded="true"`
+	// lingers on a hidden button in between.
+	$effect(() => {
+		const wide = window.matchMedia('(min-width: 640px)');
+		// Plain write, not closeMenu(), for the mount case: on mount nothing can
+		// have focus inside a panel that has never been open, and calling
+		// closeMenu() here would read `linksEl`/`menuButton` inside the effect
+		// body and make this effect re-run every time those bindings settle.
+		if (wide.matches) menuOpen = false;
+		function onChange() {
+			if (wide.matches) closeMenu();
+		}
+		wide.addEventListener('change', onChange);
+		return () => wide.removeEventListener('change', onChange);
+	});
+
+	// jelinek.css:442-476 (.site-header and its descendants) plus the dark
+	// treatment at :276-278. Per direction, the guide is reproduced as this
+	// component's own default — floating positioning, blur and all — not
+	// softened into something a consumer must opt into. A consumer who needs
+	// different positioning has `class` (merged last via cn()) to override
+	// `absolute`/`fixed`/`top-0`/etc.
+	//
+	// The `min-[620.02px]:` epsilon this file used to carry is GONE, and has been
+	// since Task 26: it only ever existed to convert the guide's INCLUSIVE
+	// `@media (max-width: 620px)` into a mobile-first `min-width` without leaving
+	// a gap (Tailwind's `max-[620px]:` compiles to the exclusive
+	// `width < 620px`). The guide declares the phone layout unconditionally and
+	// enhances it in `@media (min-width: 640px)`, so `min-[640px]:` is an EXACT
+	// translation. Task 30 moved the boundary from 621 to 640, onto the
+	// designer's 640/1024/1440 ladder.
+	//
+	// TASK 33 — THE PHONE HEADER IS THE DESIGNER'S, AND IT IS A DIFFERENT SHAPE.
+	// Three of his commits land here (36354b9, 6750ee8, 74ef043, a430f9c) and
+	// they supersede this component's previous phone treatment wholesale:
+	//
+	// POSITION. `absolute inset-x-0 top-0 z-50`, not `sticky`. His 74ef043 made
+	// this change deliberately and says why: with the bar in flow (or sticky at
+	// the top) the hero's grey band started BELOW it, leaving a visible seam in
+	// the page background right above the bar. Absolute takes the bar out of
+	// flow so the band runs under it. The cost is that the bar scrolls away on a
+	// phone (it did not while it was sticky) and that the hero must now reserve
+	// `--header-h` at every width — both accepted with the design; PageHero and
+	// +layout.svelte carry the matching padding change.
+	//
+	// SIZE. There is no separate smaller phone bar any more. `--logo-mark` is
+	// 46px at EVERY width (it was 36px on a phone), the outer gutter is ZERO on a
+	// phone (`p-0`, so the bar spans the full viewport edge to edge) and 12px/24px
+	// from 640px up, and the inner padding is a flat `12px 24px` throughout. Bar
+	// height on a phone is therefore 46 + 2×12 + 1 (bottom border) = 71px, which
+	// is what `--header-h: 70px` reserves.
+	//
+	// FRAME. On a phone the bar is a full-width strip, not a floating card: no
+	// max-width (`max-w-none`), square corners, and only a BOTTOM hairline
+	// (`border-x-0 border-t-0`) — his a430f9c. From 640px up it becomes the
+	// floating card again: `max-w-page`, all four borders, `rounded-card`.
+	//
+	// INNER (.site-header__inner): flex gap computed from --logo-mark
+	// (`calc(var(--logo-mark) * 107 / 400)` — the mark's own right-paroh
+	// margin), centred with `mx-auto`, its OWN padding (a distinct box from the
+	// outer gutter — both are real), and the glass.
+	//
+	// Task 31 — THE GLASS IS THE SHARED TOKEN SET, not this component's own
+	// values: `background: var(--glass-fill); backdrop-filter:
+	// var(--glass-filter); border: 1px solid var(--glass-border)`, the same three
+	// tokens .glassmorphism, .chapter-nav__inner and .is-sticky use. Every value
+	// moved there (fill from a hand-written rgba pair per theme to one flipping
+	// token, filter from `blur(20px) brightness(150%)`/`brightness(40%)` to
+	// `blur(25px) saturate(140%)` in both themes, border from --border-subtle to
+	// the deliberately lighter --glass-border). See Glass.svelte for why the
+	// filter is written as an arbitrary property pair rather than
+	// backdrop-blur-*/backdrop-saturate-* (token tracking — a literal here would
+	// drift with no gate to catch it). The dark hairline got softer again in his
+	// 54082b9 (--glass-border 25% white in dark); that is inside the token, so
+	// nothing changes here.
+	//
+	// THE JOINED-PANEL SEAM IS NOW ≥640px ONLY. jelinek.css:611-628 moved the
+	// whole `:root:has(.chapter-nav):not(.is-subnav-scrolled)` block inside
+	// `@media (min-width: 640px)`, because on a phone there is nothing to join
+	// to: the chapter bar is hidden and the header is already a square-cornered
+	// full-width strip. So INNER_JOINED/INNER_DETACHED are min-[640px]-scoped,
+	// and the phone frame above is unconditional.
+	//
+	// The dark inset top highlight (`inset 0 2px 1px -1px var(--box-primary)`,
+	// :278) still applies in EITHER case at every width — see :627, where the
+	// dark joined case keeps this same inset instead of dropping to
+	// `shadow: none`. TASK 33: --box-primary is now a real passthrough token
+	// (his 4ec82cd promoted it to one neutral `:root` value, hsl(0,0%,50%), and
+	// deleted the `.site-header__inner { --box-primary: var(--JELINEK-BLACK) }`
+	// local this file used to substitute). The old stand-in,
+	// var(--color-jelinek-black), is now WRONG rather than equivalent:
+	// --JELINEK-BLACK inverts to hsl(0,0%,95%) in dark mode, so it would paint a
+	// near-white hairline where the guide asks for 50% grey.
+	//
+	// Space reservation below this header is still the consuming app's job —
+	// SiteHeader/ChapterNav never add `padding-top` to a sibling
+	// (`--header-h`/`--subnav-h` are exported passthrough tokens precisely so a
+	// consumer's own layout can do that). PageHero and the showcase's
+	// `+layout.svelte` model exactly that.
+	const OUTER =
+		'absolute inset-x-0 top-0 z-50 p-0 [--logo-mark:46px] ' +
+		'min-[640px]:fixed min-[640px]:px-6 min-[640px]:py-3';
+	const INNER_BASE =
+		'mx-auto flex max-w-none items-center gap-[calc(var(--logo-mark)*107/400)] ' +
+		'border border-x-0 border-t-0 border-[var(--glass-border)] rounded-none ' +
+		'bg-[var(--glass-fill)] px-6 py-3 shadow-resting ' +
+		'dark:shadow-[var(--shadow-resting),inset_0_2px_1px_-1px_var(--box-primary)] ' +
+		'[-webkit-backdrop-filter:var(--glass-filter)] [backdrop-filter:var(--glass-filter)] ' +
+		'min-[640px]:max-w-page min-[640px]:border-x min-[640px]:border-t ' +
+		'min-[640px]:rounded-card';
+	const INNER_JOINED =
+		'min-[640px]:rounded-b-none min-[640px]:border-b-0 min-[640px]:shadow-none ' +
+		'min-[640px]:dark:shadow-[inset_0_2px_1px_-1px_var(--box-primary)]';
+	const INNER_DETACHED = '';
+	const inner = $derived(cn(INNER_BASE, dock.docked ? INNER_JOINED : INNER_DETACHED));
+
+	// jelinek.css:444-445 (.site-header__logo, .site-header__logo img /
+	// .site-header__mark): inline-flex, no shrink/grow, line-height:0
+	// (leading-none), border-radius:radius-button, overflow hidden — the
+	// mark itself is a square var(--logo-mark) box.
+	const LOGO_LINK = 'inline-flex flex-none leading-none rounded-button overflow-hidden';
+	const MARK = 'block h-[var(--logo-mark)] w-[var(--logo-mark)]';
+
+	// jelinek.css:447 (.site-header__title): font-primary (GT Walsheim),
+	// weight 700, line-height 1, size proportional to the mark
+	// (calc(logo-mark * 71/170)), letter-spacing -0.01em. The brief's draft
+	// dropped this text entirely and rendered only the subtitle — the real
+	// markup (partials/header.html:5) is always `JELÍNEK<span>{subtitle}</span>`,
+	// the brand name is never itself a prop (every real usage renders the
+	// same literal word), so it's hardcoded here and only the trailing
+	// <span> is conditional on the `subtitle` prop. No whitespace is placed
+	// between "JELÍNEK" and the {#if} block in the markup below — Svelte
+	// collapses template whitespace, and the source has none there either
+	// (the visual line break between them comes entirely from the span's
+	// own `display:block`, not from a text-level space).
+	//
+	// jelinek.css:448-454 (.site-header__title span, the subtitle): colour
+	// text-muted1, an explicit "Avenir Next LT Pro"/"Avenir Next" stack —
+	// NOT the --font-secondary token (which currently also resolves to GT
+	// Walsheim Pro in this guide's fonts, see tokens.css) — kept as a literal
+	// inline `style`, same technique Tag.svelte uses for its own
+	// custom-property values, since Tailwind's bracket syntax for a
+	// comma-separated, quoted font stack is fragile. Weight 600 (Avenir
+	// Demi), size calc(logo-mark*35/170), tracking 0.064em, uppercase,
+	// margin-top 0.3em, line-height 1.1, display block.
+	//
+	// Task 26 added `min-w-0` here, reproducing the guide's
+	// `:root.has-js .site-header__title { min-width: 0 }`. TASK 33 REMOVES IT,
+	// because the guide's rule is gone with the layout that needed it: it existed
+	// only so the lockup could shrink instead of pushing a `flex-nowrap` row of
+	// three link pills plus a theme toggle onto a second line. The phone row now
+	// holds the lockup and a 44px hamburger and nothing else — measured at a
+	// 320px viewport: 46px mark + 12px gap + ~75px min-content lockup + 44px
+	// button + 48px inner padding = 225px, with 95px to spare — so nothing needs
+	// to be crushed, and keeping `min-w-0` would shrink the lockup for no reason
+	// on the narrowest phones. Verify at 320px if the burger ever grows a label.
+	const TITLE = 'font-primary text-[calc(var(--logo-mark)*71/170)] leading-none font-bold tracking-[-0.01em]';
+	const SUBTITLE =
+		'mt-[0.3em] block text-[calc(var(--logo-mark)*35/170)] leading-[1.1] font-semibold ' +
+		'tracking-[0.064em] text-fg-muted1 uppercase';
+	const SUBTITLE_STYLE = "font-family: 'Avenir Next LT Pro', 'Avenir Next', Arial, sans-serif;";
+
+	// TASK 33 — THE PHONE MENU IS THE DESIGNER'S HAMBURGER PANEL, AND THE NAV
+	// ITEMS ARE BUTTONS. Both halves are his (6750ee8, 36354b9) and both replace
+	// what this component did before, rather than sitting alongside it.
+	//
+	// WHY IT EXISTS AT ALL. Below 640px the top-level links do not fit beside the
+	// mark. Measured in the guide, in-browser, at the real font: the three pills
+	// come to 273px and the theme toggle to another 60px, against 270px of usable
+	// width inside the bar at a 320px viewport. There is no one-row arrangement,
+	// so the links collapse — that finding (audit M3) still stands; only the
+	// mechanism changed.
+	//
+	// WHAT REPLACED THE "Menu" BUTTON + DROPDOWN. His version is a labelless
+	// 44px hamburger (three 2px bars that fold into a cross) and a FULL-WIDTH
+	// GLASS PANEL hanging off the bottom edge of the bar, not a 200px solid
+	// dropdown inset inside it. This component's previous panel was a deliberate
+	// deviation — a solid `bg-surface` sheet, because the header's own 60%-white
+	// glass left links unreadable over page text. That deviation is dropped: he
+	// solved the same problem differently, by hanging the panel off the OUTER
+	// header rather than nesting it inside the glass bar (glass inside glass has
+	// nothing to blur, so content showed through sharp), and by using the shared
+	// --glass-fill, which is a heavier 50%/60% fill than the value that was
+	// unreadable. His arrangement is the live one and it is his call.
+	//
+	// `display: contents` IS GONE TOO. It was how the panel dissolved back into
+	// the nav row from 640px up. His CSS instead styles the `<nav>` ITSELF as the
+	// panel and returns it to a plain `position: static` flex row at 640px, so
+	// there is no wrapper element to dissolve. That is why NAV below carries two
+	// completely different rule sets rather than a wrapper plus a modifier.
+	//
+	// HIS REPARENTING IS REPRODUCED AS TWO ELEMENTS, NOT AS DOM SURGERY, and this
+	// is the one place the kit's shape differs from his markup. His script moves
+	// the single `<nav>` between `.site-header__inner` (≥640px) and
+	// `.site-header` (phone) on a matchMedia change, and that move is LOAD-
+	// BEARING, not tidiness: `.site-header__inner` has `backdrop-filter`, which
+	// makes it a BACKDROP ROOT, and a `backdrop-filter` descendant of a backdrop
+	// root has nothing left to filter. MEASURED, after a first attempt that
+	// nested the panel inside `__inner` and reasoned it would be fine because
+	// `backdrop-filter` also makes an element a containing block: at 375px, over
+	// scrolled page content, the nested panel rendered with NO blur AND NO
+	// visible fill — page text read straight through the links. Moving that exact
+	// same element onto `<header>` in the same page, with no CSS change, restored
+	// both. His comment says as much ("sklo vnořené ve skle nemá co rozostřovat")
+	// and it is right.
+	//
+	// A component cannot do the move itself. Svelte owns this subtree; relocating
+	// a node it created out from under its `{#if}` block leaves the block's
+	// first/last node range pointing into a sibling chain the node has left, so
+	// teardown either misses it or throws. So the panel and the row are two
+	// separate `<nav>` elements in their two correct parents, and only ever ONE of
+	// them is displayed:
+	//   - the ROW lives inside `__inner`, `hidden` below 640px;
+	//   - the PANEL is a sibling of `__inner`, hidden FROM 640px up.
+	// The `display: none` one is out of the accessibility tree entirely, so there
+	// is exactly one nav landmark at any width, and the link markup is not
+	// duplicated either — both render the same `{#snippet navLinks}`.
+	//
+	// NO `.has-js` EQUIVALENT, and that is deliberate rather than an omission.
+	// The guide gates its whole collapse on a `.has-js` class its inline header
+	// script sets, so a visitor without JS keeps the links in the bar instead of
+	// behind a button that cannot open — this merge added that guard to the
+	// guide, since his version locked the menu shut without JS. A Svelte
+	// component only renders interactively where JS runs, so there is nothing to
+	// guard here. A consumer server-rendering this kit and caring about the no-JS
+	// case must mirror the guide's own `.has-js` rules.
+	//
+	// PANEL (the phone half of jelinek.css:498-509): `absolute`, hung off
+	// `top-full` on the outer `<header>` (which is `absolute`, so it is the
+	// containing block), full viewport width, column layout, 12px padding,
+	// bottom-rounded, the shared glass, the resting shadow.
+	//
+	// ROW (the ≥640px half, jelinek.css:589-596): a plain right-aligned flex row
+	// with an 8px gap and none of the panel chrome. It carries no phone styling at
+	// all — it is simply not displayed there — which is why this is two constants
+	// rather than one with a pile of `min-[640px]:` resets.
+	// Task 37 — THE PANEL HAS TO SCROLL, and until now it silently could not.
+	// It is `absolute`, so its height is whatever its content needs and nothing
+	// clips it. With three top-level links, ten chapters and the theme toggle it
+	// measured 674px tall on a 375×720 phone, starting at y=71 — bottom edge at
+	// 745, i.e. the toggle and the last chapter were 25px BELOW the fold with no
+	// way to reach them: the page behind cannot scroll the panel, because the
+	// panel is not part of its flow.
+	//
+	// `max-h` is the space between the header and the bottom of the viewport
+	// (minus 12px so it never sits flush against the edge), and `overflow-y-auto`
+	// makes the surplus reachable. `dvh` rather than `vh` because on iOS Safari
+	// `vh` is the tallest-possible viewport, which is exactly the amount by which
+	// the URL bar would hide the end of the list. `overscroll-contain` keeps a
+	// flick at the end of the list from scrolling the page underneath instead.
+	const NAV_PANEL =
+		'absolute top-full inset-x-0 z-[48] flex-col items-stretch gap-1 p-3 ' +
+		'rounded-b-card border border-x-0 border-t-0 border-[var(--glass-border)] ' +
+		'bg-[var(--glass-fill)] shadow-resting min-[640px]:hidden ' +
+		'max-h-[calc(100dvh_-_var(--header-h)_-_12px)] overflow-y-auto overscroll-contain ' +
+		'[-webkit-backdrop-filter:var(--glass-filter)] [backdrop-filter:var(--glass-filter)]';
+	const NAV_ROW = 'hidden ml-auto items-center gap-2 min-[640px]:flex';
+	const navPanel = $derived(cn(NAV_PANEL, menuOpen ? 'flex' : 'hidden'));
+
+	// NAV LINKS (jelinek.css:472 + partials/header.html:6-8). His 36354b9 turned
+	// them into TERTIARY BUTTONS: the markup is literally
+	// `class="btn btn--ghost btn--black"` with `is-active` for the current page,
+	// so appearance, hover and the full-fill active state all come from the
+	// button system now. The previous bespoke pill (`rounded-pill px-3.5 py-2`,
+	// `bg-surface-black` when active) is deleted rather than kept — reproducing it
+	// alongside would leave the kit with a nav-link style the guide no longer has.
+	//
+	// Rendered through this kit's own <Button href variant="ghost" color="black">
+	// for the same reason: it IS `.btn--ghost.btn--black`, and duplicating those
+	// classes by hand here is exactly the drift the css-lock gate exists to
+	// catch. `active` maps to `is-active`.
+	//
+	// The three declarations left in the guide's own rule are the size trim, and
+	// they are passed as the external `class` (cn() merges it last, so it beats
+	// Button's own `px-[26px] py-[11px] text-[0.98rem]`): `padding: 9px
+	// var(--space-2)` → `px-4 py-[9px]`, `font-size: 0.95rem`, and
+	// `text-align: left` — which is invisible on a content-width row but does
+	// matter in the phone panel, where `items-stretch` makes every link
+	// full-width.
+	// `justify-start` carries the guide's `text-align: left` across this kit's
+	// one documented Button deviation: the guide's `.btn` is `display:
+	// inline-block; text-align: center`, Button.svelte is `inline-flex ...
+	// justify-center` (so it can hold an icon), and on a flex box
+	// `text-align` no longer moves the label — `justify-*` does. Both are
+	// invisible on the ≥640px row, where the button is content-width; it only
+	// shows in the panel, where `items-stretch` makes every entry full-width.
+	// `leading-[1.2]` is re-asserted here even though Button's BASE already has
+	// it: tailwind-merge treats a font-size utility as also owning line-height
+	// (Tailwind's text-* sizes set both), so the `text-[0.95rem]` override
+	// silently strips Button's `leading-[1.2]` and the link falls back to the
+	// inherited 1.6 — six extra pixels of height vs. the guide's header.
+	const NAV_LINK = 'justify-start px-4 py-[9px] text-[0.95rem] leading-[1.2] text-left';
+
+	// BURGER (jelinek.css:481-497). A 44px square — his comment calls it out as
+	// a comfortable finger target — holding three 2px bars with a 5px gap, no
+	// border, no background. Open, the outer two rotate 45° into a cross and the
+	// middle one fades out. `ml-auto` pushes it to the right of the lockup, the
+	// job the nav row's own `ml-auto` does from 640px up. Hidden from 640px up.
+	//
+	// It has NO VISIBLE LABEL — the previous version's "Menu" text is gone with
+	// his design — so `aria-label` is the only accessible name it has, and it
+	// changes with state exactly as his script changes it (`Otevřít menu` /
+	// `Zavřít menu`, the `menuLabel`/`menuLabelClose` props).
+	const BURGER =
+		'ml-auto inline-flex h-11 w-11 flex-none cursor-pointer flex-col justify-center gap-[5px] ' +
+		'rounded-button border-0 bg-transparent px-2.5 min-[640px]:hidden';
+	const BAR =
+		'block h-0.5 rounded-[2px] bg-fg ' +
+		'transition-[transform,opacity] duration-[var(--dur-base)] ease-[var(--ease)]';
+	const bar1 = $derived(cn(BAR, menuOpen && 'translate-y-[7px] rotate-45'));
+	const bar2 = $derived(cn(BAR, menuOpen && 'opacity-0'));
+	const bar3 = $derived(cn(BAR, menuOpen && '-translate-y-[7px] -rotate-45'));
+
+	// CHAPTERS INSIDE THE PANEL (jelinek.css:504-509, `.site-menu__chapters`).
+	// The chapter bar is `display: none` below 640px now (ChapterNav.svelte), so
+	// without this a phone reader has no route to the chapters at all. The guide
+	// solves it in script, by cloning the anchors out of the rendered
+	// `.chapter-nav__inner` and appending them to the panel; the kit takes them as
+	// the `chapterItems` prop instead — same content, declared rather than
+	// cloned, and it works under SSR where there is no rendered bar to read.
+	//
+	// A 1px divider above, 8px of separation, 2px between entries, and a smaller
+	// size trim on the buttons (`font-size: 0.9rem; padding: 7px var(--space-2)`).
+	// Hidden from 640px up, where the bar itself is back.
+	const CHAPTERS =
+		'mt-2 flex flex-col gap-0.5 border-t border-[var(--glass-border)] pt-2 min-[640px]:hidden';
+	// Same leading-[1.2] re-assertion as NAV_LINK — text-[0.9rem] would strip it.
+	const CHAPTER_LINK = 'justify-start px-4 py-[7px] text-[0.9rem] leading-[1.2] text-left';
+
+	// The `actions` block inside the phone panel. Its own divider, matching the
+	// one CHAPTERS draws above the chapter list, so the toggle reads as a separate
+	// control rather than as one more menu entry. Left-aligned with the links.
+	const PANEL_ACTIONS =
+		'mt-2 flex items-center border-t border-[var(--glass-border)] px-4 pt-3 min-[640px]:hidden';
+
+	// The theme toggle (and anything else that belongs in the nav) arrives
+	// through the `actions` snippet — see its prop doc for why this stopped being
+	// "render it yourself outside the component".
+</script>
+
+<!-- One definition of the top-level links, rendered into both navs. `linkClass`
+     exists only so a future caller of this snippet can trim differently; today
+     both call sites pass NAV_LINK. -->
+{#snippet navLinks(linkClass: string)}
+	{#each items as item (item.href)}
+		<Button
+			href={item.href}
+			variant="ghost"
+			color="black"
+			active={isActive(item, active)}
+			aria-current={isActive(item, active) ? 'page' : undefined}
+			class={linkClass}
+		>
+			{item.label}
+		</Button>
+	{/each}
+{/snippet}
+
+<header {...rest} class={cn(OUTER, className)}>
+	<div class={inner}>
+		<a href={logoHref} aria-label={logoAlt} class={LOGO_LINK}>
+			{#if logo}
+				{@render logo()}
+			{:else}
+				<!-- Path data from the shared deer-mark-path.js module (Task 23 —
+				     extracted so this and ContentLogo.svelte's own copy of the
+				     SVG mark can't silently drift apart; see that module's own
+				     comment for the verification that both were byte-identical to
+				     partials/header.html:4 before the extraction). The source
+				     re-themes via inline style="fill:var(--JELINEK-BLACK)" (plus a
+				     static fill="#000" fallback attribute); reproduced here with the
+				     kit's own fill-jelinek-black/fill-jelinek-white utilities
+				     instead — they resolve to the exact same
+				     var(--JELINEK-BLACK)/var(--JELINEK-WHITE), and every other
+				     token-driven colour in this kit goes through a Tailwind utility
+				     rather than an inline style, so the static fallback attribute
+				     (meaningful only without CSS custom-property support) is dropped
+				     as unneeded for this target stack. -->
+				<svg
+					class={MARK}
+					viewBox="0 0 400 400"
+					xmlns="http://www.w3.org/2000/svg"
+					aria-hidden="true"
+				>
+					<rect width="400" height="400" class="fill-jelinek-black" />
+					<path d={DEER_MARK_PATH} class="fill-jelinek-white" />
+				</svg>
+			{/if}
+		</a>
+		<div class={TITLE}>JELÍNEK{#if subtitle}<span class={SUBTITLE} style={SUBTITLE_STYLE}>{subtitle}</span>{/if}</div>
+		{#if items.length > 0}
+			<!-- The burger precedes the panel in source order so Tab from it lands on
+			     the first link it just revealed, and because that is the order in
+			     partials/header.html:6-7. -->
+			<button
+				type="button"
+				bind:this={menuButton}
+				class={BURGER}
+				aria-expanded={menuOpen}
+				aria-controls={panelId}
+				aria-label={menuOpen ? menuLabelClose : menuLabel}
+				onclick={() => (menuOpen = !menuOpen)}
+			>
+				<span class={bar1}></span>
+				<span class={bar2}></span>
+				<span class={bar3}></span>
+			</button>
+			<!-- The ≥640px row. Inside the glass bar, so it is a flex item of it. -->
+			<nav class={NAV_ROW} aria-label={navLabel}>
+				{@render navLinks(NAV_LINK)}
+				{#if actions}{@render actions()}{/if}
+			</nav>
+		{/if}
+	</div>
+	{#if items.length > 0}
+		<!-- The phone panel. A SIBLING of the glass bar, not a child — see
+		     NAV_PANEL's comment for the measurement that forced that. Hidden from
+		     640px up, so only one of the two navs is ever in the a11y tree. -->
+		<nav id={panelId} bind:this={linksEl} class={navPanel} aria-label={navLabel}>
+			{@render navLinks(NAV_LINK)}
+			{#if chapterItems.length > 0}
+				<div class={CHAPTERS}>
+					{#each chapterItems as chapter (chapter.href)}
+						<Button
+							href={chapter.href}
+							variant="ghost"
+							color="black"
+							active={isActive(chapter, active)}
+							aria-current={isActive(chapter, active) ? 'page' : undefined}
+							class={CHAPTER_LINK}
+						>
+							{chapter.label}
+						</Button>
+					{/each}
+				</div>
+			{/if}
+			<!-- Last in the panel, as in the guide's nav: on a phone the toggle is
+			     inside the burger menu, not floating in the page. -->
+			{#if actions}
+				<div class={PANEL_ACTIONS}>{@render actions()}</div>
+			{/if}
+		</nav>
+	{/if}
+</header>