@repraze/kernelkit 0.1.0-alpha.3 → 0.1.0-alpha.4

package/src/docs/docs-index.ts

@@ -0,0 +1,108 @@
+import type {DocDef, DocEntry} from "./doc-kit";
+
+/** What the nav, search and header need about a docs page, without loading its demos (`virtual:docs-meta`). */
+export interface DocMeta<Category extends string = string> {
+    slug: string;
+    title: string;
+    category: Category;
+    description: string;
+    order?: number;
+}
+
+/** A docs file's module: its `doc` and the demo components it exports. */
+export type DocModule<Category extends string = string> = {doc: DocDef<Category>} & Record<string, unknown>;
+
+/** What docsMetaPlugin serves for `<file>.tsx?demo-sources`: each top-level declaration's own source. */
+export interface DemoSources {
+    functions: Record<string, string>;
+}
+
+type Glob<T> = Record<string, () => Promise<T>>;
+
+export interface DocsIndexOptions<Category extends string> {
+    /** Category order: the sidebar, search groups and pager follow it. */
+    categories: readonly Category[];
+    /** `import META from "virtual:docs-meta"`. */
+    meta: readonly {slug: string; title: string; category: string; description: string; order?: number}[];
+    /** `import.meta.glob("../docs/*.tsx")`: each page is its own chunk, loaded when opened. */
+    modules: Glob<unknown>;
+    /** `import.meta.glob("../docs/*.tsx", {query: "?demo-sources", import: "default"})`. */
+    sources: Glob<unknown>;
+    /** Where docs pages live, for `slugOf` (default "/docs"). */
+    basePath?: string;
+}
+
+export interface DocsIndex<Category extends string = string> {
+    categories: readonly Category[];
+    /** Every page, in category order, then `order`, then title. */
+    docs: DocMeta<Category>[];
+    bySlug: Map<string, DocMeta<Category>>;
+    /** Non-empty categories with their pages, for the sidebar and search. */
+    byCategory: {category: Category; docs: DocMeta<Category>[]}[];
+    /** Load a page's module and its demos' sources; undefined for an unknown slug. */
+    loadDoc(slug: string): Promise<DocEntry<Category> | undefined>;
+    /** The pages before and after one, for the Pager. */
+    neighbours(slug: string): {prev?: DocMeta<Category>; next?: DocMeta<Category>};
+    /** The docs slug in a pathname ("/base/docs/button" → "button"), or undefined outside the docs. */
+    slugOf(pathname: string): string | undefined;
+}
+
+const slugOfFile = (path: string) => /([^/]+)\.tsx$/.exec(path)?.[1];
+
+/** The site's docs index, from the build-time manifest and the per-page globs. */
+export function createDocsIndex<Category extends string>({
+    categories,
+    meta,
+    modules,
+    sources,
+    basePath = "/docs",
+}: DocsIndexOptions<Category>): DocsIndex<Category> {
+    const moduleBySlug = new Map(Object.entries(modules).map(([path, load]) => [slugOfFile(path), load]));
+    const sourcesBySlug = new Map(Object.entries(sources).map(([path, load]) => [slugOfFile(path), load]));
+
+    const docs = (meta as DocMeta<Category>[]).toSorted(
+        (a, b) =>
+            categories.indexOf(a.category) - categories.indexOf(b.category) ||
+            (a.order ?? 50) - (b.order ?? 50) ||
+            a.title.localeCompare(b.title),
+    );
+    const bySlug = new Map(docs.map((d) => [d.slug, d]));
+    const byCategory = categories
+        .map((category) => ({category, docs: docs.filter((d) => d.category === category)}))
+        .filter((group) => group.docs.length > 0);
+    const pathRe = new RegExp(`${basePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/([^/]+)`);
+
+    return {
+        categories,
+        docs,
+        bySlug,
+        byCategory,
+        async loadDoc(slug) {
+            const load = moduleBySlug.get(slug);
+            const loadSources = sourcesBySlug.get(slug);
+            if (!load || !loadSources) {
+                return undefined;
+            }
+            const [mod, demoSources] = (await Promise.all([load(), loadSources()])) as [
+                DocModule<Category>,
+                DemoSources,
+            ];
+            // Match demos to their export by identity: function names don't survive minification.
+            const exportName = (component: unknown) => Object.keys(mod).find((key) => mod[key] === component) ?? "";
+            return {
+                ...mod.doc,
+                slug,
+                demoSources: mod.doc.demos.map((demo) => demoSources.functions[exportName(demo.component)] ?? ""),
+            };
+        },
+        neighbours(slug) {
+            const doc = bySlug.get(slug);
+            const index = doc ? docs.indexOf(doc) : -1;
+            return index < 0 ? {} : {prev: docs[index - 1], next: docs[index + 1]};
+        },
+        slugOf(pathname) {
+            const slug = pathRe.exec(pathname)?.[1];
+            return slug && bySlug.has(slug) ? slug : undefined;
+        },
+    };
+}

package/src/docs/docs-nav.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import {
+    SidebarGroup,
+    SidebarGroupLabel,
+    SidebarMenu,
+    SidebarMenuButton,
+    SidebarMenuItem,
+} from "@repraze/kernelkit/components/sidebar";
+
+import type {DocLinkFor} from "./doc-page";
+import type {DocsIndex} from "./docs-index";
+
+export interface DocsNavProps {
+    index: DocsIndex;
+    /** The open page's slug (`index.slugOf(pathname)`), marked current. */
+    current?: string;
+    linkFor: DocLinkFor;
+    /** Called when a link is clicked (the phone menu closes). */
+    onNavigate?: () => void;
+}
+
+/** Docs navigation, one Sidebar group per category: the desktop SiteSidebar and the phone menu share it. */
+export function DocsNav({index, current, linkFor, onNavigate}: DocsNavProps) {
+    return (
+        <nav aria-label="Docs" className="flex flex-col">
+            {index.byCategory.map(({category, docs}) => (
+                <SidebarGroup key={category}>
+                    <SidebarGroupLabel className="font-mono uppercase">{category}</SidebarGroupLabel>
+                    <SidebarMenu>
+                        {docs.map((doc) => (
+                            <SidebarMenuItem key={doc.slug}>
+                                <SidebarMenuButton
+                                    isActive={doc.slug === current}
+                                    render={linkFor(doc.slug)}
+                                    onClick={onNavigate}
+                                >
+                                    <span>{doc.title}</span>
+                                </SidebarMenuButton>
+                            </SidebarMenuItem>
+                        ))}
+                    </SidebarMenu>
+                </SidebarGroup>
+            ))}
+        </nav>
+    );
+}

package/src/docs/docs-search.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import {Command, CommandEmpty, CommandGroup, CommandInput, CommandList} from "@repraze/kernelkit/components/command";
+import {SearchDialog, SearchFooter, SearchItem, substringFilter} from "@repraze/kernelkit/components/search-dialog";
+import {SearchTrigger, useSearchHotkeys} from "@repraze/kernelkit/components/search-trigger";
+import {FileTextIcon, type LucideIcon} from "lucide-react";
+import {useCallback, useState} from "react";
+
+import type {DocsIndex} from "./docs-index";
+
+export interface DocsSearchProps {
+    index: DocsIndex;
+    /** One icon per category, so a result's kind reads at a glance; `fallbackIcon` for the others. */
+    icons?: Record<string, LucideIcon>;
+    fallbackIcon?: LucideIcon;
+    /** Slugs shown before the first keystroke, in a "Suggested" group. */
+    suggested?: string[];
+    placeholder?: string;
+    /** Go to a page (the router's navigate). */
+    onSelect: (slug: string) => void;
+}
+
+/**
+ * The suite's docs search: SearchTrigger + hotkeys (Ctrl/⌘ K, `/`) opening a SearchDialog over the docs
+ * index, grouped by category, with a plain substring filter.
+ */
+export function DocsSearch({
+    index,
+    icons = {},
+    fallbackIcon = FileTextIcon,
+    suggested = [],
+    placeholder = "Search the docs…",
+    onSelect,
+}: DocsSearchProps) {
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState("");
+    useSearchHotkeys(useCallback((toggle: boolean) => setOpen((o) => (toggle ? !o : true)), []));
+
+    const groups = query.trim()
+        ? index.byCategory
+        : [{category: "Suggested", docs: suggested.flatMap((slug) => index.docs.filter((d) => d.slug === slug))}];
+
+    return (
+        <>
+            <SearchTrigger onClick={() => setOpen(true)} aria-label="Search docs" />
+            <SearchDialog
+                open={open}
+                onOpenChange={(next) => {
+                    setOpen(next);
+                    if (!next) {
+                        setQuery("");
+                    }
+                }}
+                description="Search the docs"
+            >
+                <Command filter={substringFilter} loop>
+                    <CommandInput value={query} onValueChange={setQuery} placeholder={placeholder} />
+                    <CommandList>
+                        <CommandEmpty>No results for “{query}”.</CommandEmpty>
+                        {groups.map(({category, docs}) => (
+                            <CommandGroup key={category} heading={category}>
+                                {docs.map((doc) => {
+                                    const Icon = icons[doc.category] ?? fallbackIcon;
+                                    return (
+                                        <SearchItem
+                                            key={doc.slug}
+                                            value={doc.title}
+                                            keywords={[doc.category, doc.slug]}
+                                            icon={<Icon />}
+                                            title={doc.title}
+                                            description={doc.description}
+                                            onSelect={() => {
+                                                setOpen(false);
+                                                setQuery("");
+                                                onSelect(doc.slug);
+                                            }}
+                                        />
+                                    );
+                                })}
+                            </CommandGroup>
+                        ))}
+                    </CommandList>
+                    <SearchFooter />
+                </Command>
+            </SearchDialog>
+        </>
+    );
+}

package/src/docs/index.ts

@@ -0,0 +1,6 @@
+export * from "./doc-kit";
+export * from "./doc-page";
+export * from "./docs-index";
+export * from "./docs-nav";
+export * from "./docs-search";
+export * from "./review-matrix";

package/src/docs/review-matrix.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import type {Accent, Radius, ResolvedMode} from "@repraze/kernelkit/provider";
+import {ThemeScope, type ThemeScopeProps} from "@repraze/kernelkit/provider";
+import {cn} from "cn";
+
+import type {DocEntry} from "./doc-kit";
+
+export interface ReviewScope {
+    label: string;
+    scope: Omit<ThemeScopeProps, "children">;
+}
+
+/**
+ * The GUIDELINES §8 scopes: dark, light and both high-contrast modes in the site's own accent and radius,
+ * then two variants (by default dark · radius-none · cyan and light · radius-xl · yellow).
+ */
+export function reviewScopes(
+    site: {accent: Accent; radius: Radius},
+    variants: {mode: ResolvedMode; accent: Accent; radius: Radius}[] = [
+        {mode: "dark", accent: "cyan", radius: "none"},
+        {mode: "light", accent: "yellow", radius: "xl"},
+    ],
+): ReviewScope[] {
+    return [
+        {label: "dark", scope: {mode: "dark", contrast: "normal", ...site}},
+        {label: "light", scope: {mode: "light", contrast: "normal", ...site}},
+        {label: "dark · hc", scope: {mode: "dark", contrast: "high", ...site}},
+        {label: "light · hc", scope: {mode: "light", contrast: "high", ...site}},
+        ...variants.map(({mode, accent, radius}) => ({
+            label: `${mode} · radius-${radius} · ${accent}`,
+            scope: {mode, contrast: "normal" as const, accent, radius},
+        })),
+    ];
+}
+
+/** Every demo of a page in each scope, side by side, for visual review (GUIDELINES §8). */
+export function ReviewMatrix({doc, scopes}: {doc: DocEntry; scopes: ReviewScope[]}) {
+    return (
+        <div className="flex flex-col gap-6 p-6" data-slot="review">
+            <h1 className="font-mono text-lg font-semibold">{doc.title} · review</h1>
+            {doc.demos.map((demo) => {
+                const Component = demo.component;
+                return (
+                    <section key={demo.title} className="flex flex-col gap-2">
+                        <h2 className="font-mono text-sm text-muted-foreground">{demo.title}</h2>
+                        <div className="grid grid-cols-2 gap-px overflow-hidden border bg-border">
+                            {scopes.map(({label, scope}) => (
+                                <ThemeScope key={label} {...scope} className="flex flex-col gap-3 p-4">
+                                    <span className="font-mono text-[10px] text-muted-foreground">{label}</span>
+                                    <div
+                                        className={cn(
+                                            "flex min-h-24 flex-1",
+                                            demo.layout === "full" ? "" : "items-center justify-center",
+                                        )}
+                                    >
+                                        <Component />
+                                    </div>
+                                </ThemeScope>
+                            ))}
+                        </div>
+                    </section>
+                );
+            })}
+        </div>
+    );
+}

package/src/hooks/use-theme-palette.ts

@@ -0,0 +1,25 @@
+import {useResolvedTheme} from "@repraze/kernelkit/provider";
+import {allModes, createPalette, type Mode} from "@repraze/termicolor";
+import {useMemo} from "react";
+
+const cache = new Map<string, Mode>();
+
+/**
+ * The TermiColor mode that applies here (nearest ThemeScope, else the ThemeProvider): neutrals, accents
+ * and roles as hex strings, with `roles.accent` & co. in the current accent. For canvas, chart and WebGPU
+ * code that can't read CSS variables. Memoised per mode, contrast and accent.
+ */
+export function useThemePalette(): Mode {
+    const {mode, contrast, accent} = useResolvedTheme();
+    return useMemo(() => {
+        const id = `${mode}${contrast === "high" ? "-hc" : ""}`;
+        const key = `${id}:${accent}`;
+        let found = cache.get(key);
+        if (!found) {
+            const modes = allModes(createPalette({accent}));
+            found = modes.find((m) => m.id === id) ?? modes[0]!;
+            cache.set(key, found);
+        }
+        return found;
+    }, [mode, contrast, accent]);
+}

package/src/provider/theme-provider.tsx

@@ -40,6 +40,9 @@ export interface ThemeContextValue extends ThemeState {
 
 const ThemeContext = createContext<ThemeContextValue | null>(null);
 
+/** The nearest ThemeScope's resolved theme, so code that paints (canvas, charts) can follow a scope. */
+const ScopeContext = createContext<ResolvedTheme | null>(null);
+
 /** Element overlays portal into, so popups inside a ThemeScope keep its theme. */
 const PortalContainerContext = createContext<HTMLElement | null>(null);
 
@@ -181,6 +184,23 @@ export function useTheme(): ThemeContextValue {
     return ctx;
 }
 
+/** A theme with its mode resolved (never "system"). */
+export type ResolvedTheme = Omit<ThemeState, "mode"> & {mode: ResolvedMode};
+
+/**
+ * The theme that applies here: the nearest ThemeScope's, else the provider's with "system" resolved.
+ * Use it for things CSS can't reach (canvas, WebGL/WebGPU, charts) so they follow review scopes too.
+ */
+export function useResolvedTheme(): ResolvedTheme {
+    const scope = useContext(ScopeContext);
+    const ctx = useContext(ThemeContext);
+    const mode = scope?.mode ?? ctx?.resolvedMode ?? "light";
+    const contrast = scope?.contrast ?? ctx?.contrast ?? DEFAULT_THEME.contrast;
+    const accent = scope?.accent ?? ctx?.accent ?? DEFAULT_THEME.accent;
+    const radius = scope?.radius ?? ctx?.radius ?? DEFAULT_THEME.radius;
+    return useMemo(() => ({mode, contrast, accent, radius}), [mode, contrast, accent, radius]);
+}
+
 /** Renders the pre-paint script. Place in <head> (Next.js: in the root layout). */
 export function ThemeScript({nonce, ...options}: ThemeScriptOptions & {nonce?: string}) {
     return <script nonce={nonce} suppressHydrationWarning dangerouslySetInnerHTML={{__html: themeScript(options)}} />;
@@ -188,7 +208,7 @@ export function ThemeScript({nonce, ...options}: ThemeScriptOptions & {nonce?: s
 
 export interface ThemeScopeProps extends Omit<React.ComponentProps<"div">, "children"> {
     children?: ReactNode;
-    /** Values not given inherit from the surrounding <ThemeProvider> (or the defaults). */
+    /** Values not given inherit from the surrounding ThemeScope or <ThemeProvider> (or the defaults). */
     mode?: ResolvedMode;
     contrast?: ThemeState["contrast"];
     accent?: ThemeState["accent"];
@@ -200,14 +220,17 @@ export interface ThemeScopeProps extends Omit<React.ComponentProps<"div">, "chil
  * the scope, so they keep its colors and radius.
  */
 export function ThemeScope({mode, contrast, accent, radius, className, children, ...props}: ThemeScopeProps) {
-    const parent = useContext(ThemeContext);
+    const parent = useResolvedTheme();
     const [container, setContainer] = useState<HTMLDivElement | null>(null);
-    const theme = {
-        mode: mode ?? parent?.resolvedMode ?? "light",
-        contrast: contrast ?? parent?.contrast ?? DEFAULT_THEME.contrast,
-        accent: accent ?? parent?.accent ?? DEFAULT_THEME.accent,
-        radius: radius ?? parent?.radius ?? DEFAULT_THEME.radius,
-    };
+    const theme = useMemo(
+        () => ({
+            mode: mode ?? parent.mode,
+            contrast: contrast ?? parent.contrast,
+            accent: accent ?? parent.accent,
+            radius: radius ?? parent.radius,
+        }),
+        [mode, contrast, accent, radius, parent],
+    );
     const classes = themeClassName(theme);
     return (
         <div
@@ -215,7 +238,9 @@ export function ThemeScope({mode, contrast, accent, radius, className, children,
             className={[classes, "bg-background text-foreground", className].filter(Boolean).join(" ")}
             {...props}
         >
-            <PortalContainerContext.Provider value={container}>{children}</PortalContainerContext.Provider>
+            <ScopeContext.Provider value={theme}>
+                <PortalContainerContext.Provider value={container}>{children}</PortalContainerContext.Provider>
+            </ScopeContext.Provider>
             <div ref={setContainer} data-slot="theme-scope-portal" className={classes} />
         </div>
     );

package/src/site/brand.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import {cn} from "cn";
+
+/**
+ * A site's brand mark (an SVG string from its `brand/mark.ts`), inlined. Size it in multiples of 32px
+ * (default `size-8`) so it stays pixel-sharp (GUIDELINES §7b).
+ */
+export function BrandMark({svg, className}: {svg: string; className?: string}) {
+    return (
+        <span
+            aria-hidden
+            className={cn("inline-block size-8 shrink-0 leading-0", className)}
+            // Static markup generated by the site from its own mark shapes, never from user input.
+            dangerouslySetInnerHTML={{__html: svg}}
+        />
+    );
+}
+
+export interface BrandLogoProps {
+    /** The mark's SVG markup. */
+    svg: string;
+    /** The wordmark's first word, in the foreground ("Kernel"). */
+    first: string;
+    /** Its second word, in the accent text tier ("Kit"). */
+    second: string;
+    className?: string;
+}
+
+/** Mark + two-tone wordmark in mono semibold: Kernel**Kit**, Termi**Color** (the suite's brand pattern). */
+export function BrandLogo({svg, first, second, className}: BrandLogoProps) {
+    return (
+        <span className={cn("inline-flex items-center gap-2", className)}>
+            <BrandMark svg={svg} />
+            <span className="font-mono text-sm font-semibold tracking-tight">
+                {first}
+                <span className="text-primary-text">{second}</span>
+            </span>
+        </span>
+    );
+}

package/src/site/github-icon.tsx

@@ -0,0 +1,10 @@
+import type * as React from "react";
+
+/** GitHub mark (lucide no longer ships brand icons). */
+export function GithubIcon(props: React.SVGProps<SVGSVGElement>) {
+    return (
+        <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden {...props}>
+            <path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 0-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-6 0-1.2.5-2.3 1.3-3.1-.2-.4-.6-1.6 0-3.2 0 0 1-.3 3.4 1.2a11.5 11.5 0 0 1 6 0c2.3-1.5 3.3-1.2 3.3-1.2.6 1.6.2 2.8.1 3.2.8.8 1.3 1.9 1.3 3.1 0 4.6-2.8 5.6-5.5 5.9.5.4.9 1.1.9 2.2v3.3c0 .3.1.7.8.6A12 12 0 0 0 12 .3" />
+        </svg>
+    );
+}

package/src/site/index.ts

@@ -0,0 +1,5 @@
+export * from "./brand";
+export * from "./github-icon";
+export * from "./suite-footer";
+export * from "./suite-header";
+export * from "./use-page-title";

package/src/site/suite-footer.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import {SiteFooter, SiteFooterLink, SiteFooterLinks} from "@repraze/kernelkit/components/site-footer";
+import type * as React from "react";
+import {Fragment} from "react";
+
+export interface SuiteFooterLinkItem {
+    label: string;
+    /** A router link as a `render` element; or `href` for a plain anchor. */
+    render?: React.ReactElement;
+    href?: string;
+}
+
+/** Suite projects a site can credit, in this order: "built with KernelKit", "themed by TermiColor". */
+export type SuiteCredit = "kernelkit" | "termicolor";
+
+const CREDITS: Record<SuiteCredit, {text: string; name: string; href: string}> = {
+    kernelkit: {text: "built with", name: "KernelKit", href: "https://repraze.github.io/kernelkit/"},
+    termicolor: {text: "themed by", name: "TermiColor", href: "https://repraze.github.io/termicolor/"},
+};
+
+export interface SuiteFooterProps {
+    links: SuiteFooterLinkItem[];
+    /** Which suite projects to credit (default `["termicolor"]`). */
+    credits?: SuiteCredit[];
+    /** A phrase of the site's own after the credits ("built from one palette"). */
+    tagline?: React.ReactNode;
+    /** Default "MIT". */
+    license?: string;
+}
+
+/**
+ * The suite's footer (GUIDELINES §7b): "MIT · themed by TermiColor · a repraze.com project" on the left,
+ * the site's links on the right.
+ */
+export function SuiteFooter({links, credits = ["termicolor"], tagline, license = "MIT"}: SuiteFooterProps) {
+    return (
+        <SiteFooter>
+            <span>
+                {license}
+                {credits.map((key) => {
+                    const credit = CREDITS[key];
+                    return (
+                        <Fragment key={key}>
+                            {" "}
+                            · {credit.text}{" "}
+                            <SiteFooterLink href={credit.href} className="underline underline-offset-4">
+                                {credit.name}
+                            </SiteFooterLink>
+                        </Fragment>
+                    );
+                })}
+                {tagline ? <> · {tagline}</> : null} · a{" "}
+                <SiteFooterLink href="https://repraze.com" className="underline underline-offset-4">
+                    repraze.com
+                </SiteFooterLink>{" "}
+                project
+            </span>
+            <SiteFooterLinks aria-label="Footer">
+                {links.map((link) => (
+                    <SiteFooterLink key={link.label} href={link.href} render={link.render}>
+                        {link.label}
+                    </SiteFooterLink>
+                ))}
+            </SiteFooterLinks>
+        </SiteFooter>
+    );
+}

package/src/site/suite-header.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import {Button} from "@repraze/kernelkit/components/button";
+import {Separator} from "@repraze/kernelkit/components/separator";
+import {
+    SiteHeader,
+    SiteHeaderActions,
+    SiteHeaderBrand,
+    SiteHeaderContent,
+    SiteHeaderMenu,
+    SiteNav,
+    SiteNavLink,
+} from "@repraze/kernelkit/components/site-header";
+import {ThemeMenu} from "@repraze/kernelkit/components/theme-menu";
+import type * as React from "react";
+import {useEffect, useState} from "react";
+
+import {GithubIcon} from "./github-icon";
+
+export interface SuiteNavItem {
+    label: string;
+    /** A router link as a `render` element (`<Link to="/ports" />`); or `href` for a plain anchor. */
+    render?: React.ReactElement;
+    href?: string;
+    /** Marks the entry current (`aria-current="page"`): the section the open page belongs to. */
+    current?: boolean;
+}
+
+export interface SuiteHeaderProps {
+    /** The brand (a BrandLogo), in the header and as the phone menu's title. */
+    brand: React.ReactNode;
+    /** Accessible name of the home link, e.g. "KernelKit home". */
+    brandLabel: string;
+    /** The home link as a `render` element (`<Link to="/" />`); a plain "/" anchor otherwise. */
+    home?: React.ReactElement;
+    nav: SuiteNavItem[];
+    /** Accessible name of the nav (default "Main"). */
+    navLabel?: string;
+    /** The search (DocsSearch, or the site's own), before the separator. */
+    search?: React.ReactNode;
+    /** Replaces the default `<ThemeMenu />`. */
+    themeMenu?: React.ReactNode;
+    /** The repository button (a GitHub icon). */
+    repository?: {href: string; label?: string; icon?: React.ReactNode};
+    /** The phone menu's content after the nav links (the docs nav, a tree). */
+    menu?: React.ReactNode;
+    /** Closes the phone menu when it changes: pass the pathname. */
+    locationKey?: string;
+}
+
+/**
+ * The suite's site header (GUIDELINES §7b): phone menu, brand, mono nav, then search · theme · repository.
+ * Every site renders this; only the brand, nav and menu content differ.
+ */
+export function SuiteHeader({
+    brand,
+    brandLabel,
+    home,
+    nav,
+    navLabel = "Main",
+    search,
+    themeMenu,
+    repository,
+    menu,
+    locationKey,
+}: SuiteHeaderProps) {
+    const [menuOpen, setMenuOpen] = useState(false);
+    useEffect(() => setMenuOpen(false), [locationKey]);
+
+    const navLinks = nav.map((item) => (
+        <SiteNavLink
+            key={item.label}
+            href={item.href}
+            aria-current={item.current ? "page" : undefined}
+            render={item.render}
+        >
+            {item.label}
+        </SiteNavLink>
+    ));
+
+    return (
+        <SiteHeader>
+            <SiteHeaderContent>
+                <SiteHeaderMenu title={brand} open={menuOpen} onOpenChange={setMenuOpen}>
+                    <nav aria-label={navLabel} className="flex flex-col gap-1 px-2 pt-2">
+                        {navLinks}
+                    </nav>
+                    {menu}
+                </SiteHeaderMenu>
+                <SiteHeaderBrand aria-label={brandLabel} href={home ? undefined : "/"} render={home}>
+                    {brand}
+                </SiteHeaderBrand>
+                <SiteNav aria-label={navLabel}>{navLinks}</SiteNav>
+                <SiteHeaderActions>
+                    {search}
+                    <Separator
+                        orientation="vertical"
+                        className="mx-1 hidden data-vertical:h-5 data-vertical:self-center sm:block"
+                    />
+                    {themeMenu ?? <ThemeMenu />}
+                    {repository ? (
+                        <Button
+                            variant="ghost"
+                            size="icon"
+                            render={<a href={repository.href} aria-label={repository.label ?? "GitHub"} />}
+                        >
+                            {repository.icon ?? <GithubIcon className="size-4" />}
+                        </Button>
+                    ) : null}
+                </SiteHeaderActions>
+            </SiteHeaderContent>
+        </SiteHeader>
+    );
+}