@nexub/patterns 1.3.0 → 1.4.0

package/README.md

@@ -0,0 +1,132 @@
+# @nexub/patterns
+
+Composite UI patterns for the Nexub Design System, built on `@nexub/react`.
+
+```bash
+pnpm add @nexub/patterns @nexub/react @nexub/icons @nexub/themes
+```
+
+Like `@nexub/react`, the patterns are styled with Tailwind classes your app compiles: add `node_modules/@nexub/patterns/dist/**/*.js` to your Tailwind `content`, use the `@nexub/tokens/tailwind` preset, and import `@nexub/themes/base` plus a palette (e.g. `@nexub/themes/light` and `@nexub/themes/dark`).
+
+## AppHeader
+
+The one top header every Nexub app shares. It is presentational: the app passes in its data and callbacks, and the header does no fetching.
+
+Left to right: an optional menu slot (below `md` only), the logo, search, the organization, a theme switch, the app launcher and the account menu. It is fixed to the top at `--app-header-height` (64px, from `@nexub/themes/base`) and renders a spacer of that height after itself, so content flows below it with no padding of your own.
+
+### Minimal
+
+```tsx
+import { ThemeProvider } from '@nexub/react';
+import { AppHeader } from '@nexub/patterns';
+
+<ThemeProvider>
+  <AppHeader productName="Account" />
+  <main>…</main>
+</ThemeProvider>
+```
+
+The theme switch uses `useTheme`, so it needs a `ThemeProvider`. Pass `showThemeSwitch={false}` to leave it out.
+
+### Full
+
+Search provider, two orgs, launcher and account menu:
+
+```tsx
+import { useRouter } from 'next/navigation';
+import { DropdownMenu } from '@nexub/react';
+import { AppHeader, type AppHeaderSearchGroup } from '@nexub/patterns';
+
+function Header({ session, currentOrgId, switchOrg, signOut, openPreferences }) {
+  const router = useRouter();
+
+  // Called (debounced) as the user types. Return groups of results.
+  const onSearch = async (query: string): Promise<AppHeaderSearchGroup[]> => {
+    const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
+    const { projects } = await res.json();
+    return [
+      {
+        label: 'Projects',
+        items: projects.map((p) => ({
+          id: p.id,
+          label: p.name,
+          hint: 'Project',
+          onSelect: () => router.push(`/projects/${p.id}`),
+        })),
+      },
+    ];
+  };
+
+  return (
+    <AppHeader
+      productName="Command Hub"
+      homeHref="/"
+      onNavigate={(href) => router.push(href)}
+      onSearch={onSearch}
+      orgs={[
+        { id: 'acme', name: 'Acme' },
+        { id: 'globex', name: 'Globex' },
+      ]}
+      currentOrgId={currentOrgId}
+      onOrgChange={switchOrg}
+      apps={[
+        { id: 'hub', name: 'Command Hub', href: '/', current: true },
+        { id: 'account', name: 'Account', href: 'https://account.example.com' },
+      ]}
+      user={{ name: session.name, email: session.email, avatarUrl: session.picture }}
+      accountHref="https://account.example.com"
+      privacyHref="/privacy"
+      termsHref="/terms"
+      onSignOut={signOut} // may return a promise; Sign out is disabled until it settles
+      accountMenuItems={<DropdownMenu.Item onSelect={openPreferences}>Preferences</DropdownMenu.Item>}
+    />
+  );
+}
+```
+
+### Props
+
+| Prop | Notes |
+| --- | --- |
+| `productName` | Shown after the wordmark (`<Logo size="sm" product={…} />`) and in the search field. |
+| `homeHref`, `onNavigate(href)` | The logo links to `homeHref` (default `/`). `onNavigate` takes over plain clicks on the logo and the launcher's tiles, for client-side routers. |
+| `menu` | Your navigation trigger, shown below `md` only. |
+| `searchItems` / `onSearch(query)` | A static list (filtered as you type) or an async search (debounced 200ms, with loading, empty and error states). Groups are `{ label, items: [{ id, label, hint?, icon?, onSelect }] }`. With neither, there is no search. |
+| `searchPlaceholder` | Default `Search <productName>`. |
+| `orgs`, `currentOrgId`, `onOrgChange(id)` | No orgs: nothing. One: its name as plain, truncated text. Two or more: a menu with the current org checked; on phones the trigger is a building icon. |
+| `showThemeSwitch` | Default `true`. |
+| `apps` | Passed to `AppLauncher`. |
+| `user`, `accountHref`, `privacyHref`, `termsHref`, `onSignOut`, `accountMenuItems` | The account menu (no `user`, no menu). Each link shows only when its href is set. `accountMenuItems` go above Sign out. |
+| `surface` | `'solid'` (default) or `'glass'` (needs `@nexub/themes/glass`). |
+
+Search opens with the button, **⌘K / Ctrl+K** anywhere, or **/** when focus isn't in a text field. Arrow keys move, Enter selects, Esc closes and returns focus.
+
+### Layouts
+
+- **Any page:** render it first; its spacer pushes content down. To offset something yourself (e.g. a sticky sidebar), use `top: var(--app-header-height)`.
+- **AppShell:** put it in `AppShell.Header`. The spacer gives the header row its height, so `AppShell.Body` starts below it.
+
+  ```tsx
+  <AppShell.Root>
+    <AppShell.Header>
+      <AppHeader productName="Command Hub" menu={<MobileNavButton />} />
+    </AppShell.Header>
+    <AppShell.Body>…</AppShell.Body>
+  </AppShell.Root>
+  ```
+
+- **SettingsLayout:** pass `header`. It replaces SettingsLayout's own top bar and hands you its phone section-menu button for the menu slot.
+
+  ```tsx
+  <SettingsLayout items={items} activeId={active} header={(menu) => <AppHeader menu={menu} productName="Account" />}>
+    …
+  </SettingsLayout>
+  ```
+
+### Strict CSP
+
+The header injects no `<style>` tags and sets no inline styles of its own: the search palette locks page scroll with a class (`scrollLock="class"`), and the org and account menus are non-modal. One known gap: the colour Nexub mark inside `Logo` still sets `style` on its gradient stops, so under `style-src 'self'` a server-rendered mark loses its colours until that is fixed.
+
+### Accessibility
+
+`<header role="banner">` with a `<nav aria-label="Account and apps">` for the right-hand group. Every icon button has a label; the search buttons expose their shortcut through `aria-keyshortcuts` and a description. The org switcher and account menu are Radix menus, operable from the keyboard.

package/dist/{chunk-7UPV63EW.js → chunk-5QFC4WFD.js}

@@ -26,7 +26,7 @@ function SectionNav({
   )) }) });
 }
 var Root = React.forwardRef(
-  ({ items, activeId, onSelect, logo, actions, title, description, navLabel = "Settings", className, children, ...props }, ref) => {
+  ({ items, activeId, onSelect, logo, actions, header, title, description, navLabel = "Settings", className, children, ...props }, ref) => {
     const [menuOpen, setMenuOpen] = React.useState(false);
     const onChoose = (e, item) => {
       if (!isPlainClick(e)) return;
@@ -36,9 +36,10 @@ var Root = React.forwardRef(
       }
       setMenuOpen(false);
     };
+    const menuButton = /* @__PURE__ */ jsx(IconButton, { label: `Open ${navLabel.toLowerCase()} menu`, className: "-ml-2 md:hidden", onClick: () => setMenuOpen(true), children: /* @__PURE__ */ jsx(Menu, { size: "md", "aria-hidden": "true" }) });
     return /* @__PURE__ */ jsxs("div", { ref, className: cn("flex min-h-screen flex-col bg-[var(--color-bg-default)]", className), ...props, children: [
-      /* @__PURE__ */ jsxs(TopNav.Root, { children: [
-        /* @__PURE__ */ jsx(IconButton, { label: `Open ${navLabel.toLowerCase()} menu`, className: "-ml-2 md:hidden", onClick: () => setMenuOpen(true), children: /* @__PURE__ */ jsx(Menu, { size: "md", "aria-hidden": "true" }) }),
+      header ? header(menuButton) : /* @__PURE__ */ jsxs(TopNav.Root, { className: "h-[var(--app-header-height,64px)]", children: [
+        menuButton,
         logo && /* @__PURE__ */ jsx(TopNav.Logo, { className: "min-w-0 shrink", children: logo }),
         actions && /* @__PURE__ */ jsx(TopNav.Actions, { children: actions })
       ] }),
@@ -50,7 +51,7 @@ var Root = React.forwardRef(
             activeId,
             onChoose,
             label: navLabel,
-            className: "sticky top-[var(--size-nav-header,64px)] hidden h-[calc(100vh-var(--size-nav-header,64px))] shrink-0 md:flex"
+            className: "sticky top-[var(--app-header-height,64px)] hidden h-[calc(100vh-var(--app-header-height,64px))] shrink-0 md:flex"
           }
         ),
         /* @__PURE__ */ jsx("main", { className: "min-w-0 flex-1 px-4 py-6 md:px-8 md:py-10", children: /* @__PURE__ */ jsxs("div", { className: "mx-auto flex w-full max-w-3xl flex-col gap-6", children: [

package/dist/chunk-OYSWFXRD.js

@@ -0,0 +1,329 @@
+'use client';
+import {
+  AppLauncher
+} from "./chunk-ZFHA46UX.js";
+
+// src/components/AppHeader/AppHeader.tsx
+import * as React from "react";
+import {
+  Avatar,
+  CommandPalette,
+  DropdownMenu,
+  IconButton,
+  Kbd,
+  Logo,
+  TopNav,
+  cn,
+  useTheme
+} from "@nexub/react";
+import { Building2, ChevronDown, Moon, Search, Sun } from "@nexub/icons";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var SEARCH_DEBOUNCE_MS = 200;
+var focusRing = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-ring-default)] focus-visible:ring-offset-2 ring-offset-[var(--color-ring-offset)]";
+var isPlainClick = (e) => e.button === 0 && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey;
+var isTextField = (t) => t instanceof HTMLElement && (t.isContentEditable || t.matches("input, textarea, select"));
+function HeaderSearch({
+  placeholder,
+  items,
+  onSearch
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [query, setQuery] = React.useState("");
+  const [results, setResults] = React.useState([]);
+  const [loading, setLoading] = React.useState(false);
+  const [failed, setFailed] = React.useState(false);
+  const [isMac, setIsMac] = React.useState(true);
+  const hintId = React.useId();
+  const onSearchRef = React.useRef(onSearch);
+  onSearchRef.current = onSearch;
+  const isAsync = Boolean(onSearch);
+  React.useEffect(() => {
+    setIsMac(/Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent));
+    const onKeyDown = (e) => {
+      if (e.defaultPrevented) return;
+      if ((e.metaKey || e.ctrlKey) && !e.altKey && !e.shiftKey && e.key.toLowerCase() === "k") {
+        e.preventDefault();
+        setOpen((o) => !o);
+      } else if (e.key === "/" && !e.metaKey && !e.ctrlKey && !e.altKey && !isTextField(e.target)) {
+        e.preventDefault();
+        setOpen(true);
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, []);
+  React.useEffect(() => {
+    if (!open || !isAsync) return;
+    let stale = false;
+    setLoading(true);
+    const timer = setTimeout(() => {
+      Promise.resolve().then(() => onSearchRef.current(query)).then(
+        (groups2) => {
+          if (stale) return;
+          setResults(groups2);
+          setFailed(false);
+        },
+        () => {
+          if (stale) return;
+          setResults([]);
+          setFailed(true);
+        }
+      ).finally(() => {
+        if (!stale) setLoading(false);
+      });
+    }, SEARCH_DEBOUNCE_MS);
+    return () => {
+      stale = true;
+      clearTimeout(timer);
+    };
+  }, [open, query, isAsync]);
+  const onOpenChange = (next) => {
+    setOpen(next);
+    if (!next) setQuery("");
+  };
+  const groups = isAsync ? results : items ?? [];
+  const triggerProps = {
+    onClick: () => setOpen(true),
+    "aria-keyshortcuts": "Meta+K Control+K /",
+    "aria-describedby": hintId,
+    "aria-haspopup": "dialog"
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("span", { id: hintId, className: "sr-only", children: [
+      "Keyboard shortcut: ",
+      isMac ? "Command" : "Control",
+      " K"
+    ] }),
+    /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        ...triggerProps,
+        className: cn(
+          "hidden h-9 w-full max-w-xl items-center gap-2 rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-subtle)] px-3 text-sm text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-bg-muted)] md:flex",
+          focusRing
+        ),
+        children: [
+          /* @__PURE__ */ jsx(Search, { size: "sm", "aria-hidden": "true", className: "shrink-0" }),
+          /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-left", children: placeholder }),
+          /* @__PURE__ */ jsx(Kbd, { "aria-hidden": "true", className: "shrink-0", children: isMac ? "\u2318K" : "Ctrl K" })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx(IconButton, { label: placeholder, ...triggerProps, className: "md:hidden", children: /* @__PURE__ */ jsx(Search, { size: "md", "aria-hidden": "true" }) }),
+    /* @__PURE__ */ jsxs(
+      CommandPalette.Root,
+      {
+        open,
+        onOpenChange,
+        label: placeholder,
+        scrollLock: "class",
+        shouldFilter: !isAsync,
+        children: [
+          /* @__PURE__ */ jsx(CommandPalette.Input, { placeholder, value: query, onValueChange: setQuery }),
+          /* @__PURE__ */ jsxs(CommandPalette.List, { children: [
+            loading && /* @__PURE__ */ jsx("div", { role: "status", className: "px-3 py-2 text-sm text-[var(--color-text-muted)]", children: "Searching\u2026" }),
+            !loading && /* @__PURE__ */ jsx(CommandPalette.Empty, { children: failed ? "Search failed. Try again." : query ? `No results for \u201C${query}\u201D` : "Type to search" }),
+            groups.map((group) => /* @__PURE__ */ jsx(CommandPalette.Group, { heading: group.label, children: group.items.map((item) => /* @__PURE__ */ jsxs(
+              CommandPalette.Item,
+              {
+                value: `${group.label}:${item.id}`,
+                keywords: [item.label],
+                onSelect: () => {
+                  onOpenChange(false);
+                  item.onSelect();
+                },
+                children: [
+                  item.icon && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: "mr-2 flex shrink-0 text-[var(--color-text-muted)]", children: item.icon }),
+                  /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate", children: item.label }),
+                  item.hint && /* @__PURE__ */ jsx("span", { className: "ml-auto shrink-0 pl-3 text-xs text-[var(--color-text-muted)]", children: item.hint })
+                ]
+              },
+              item.id
+            )) }, group.label))
+          ] })
+        ]
+      }
+    )
+  ] });
+}
+var orgLabelClass = "min-w-0 max-w-[6rem] truncate sm:max-w-[8rem] xl:max-w-[12rem]";
+function OrgSwitcher({
+  orgs,
+  currentOrgId,
+  onOrgChange
+}) {
+  const current = orgs.find((o) => o.id === currentOrgId) ?? orgs[0];
+  if (!current) return null;
+  if (orgs.length === 1) {
+    return /* @__PURE__ */ jsx("span", { title: current.name, className: cn("px-2 text-sm font-medium text-[var(--color-text-secondary)]", orgLabelClass), children: current.name });
+  }
+  return (
+    // modal={false}: Radix's modal menu injects a <style> scroll lock (strict CSP).
+    /* @__PURE__ */ jsxs(DropdownMenu.Root, { modal: false, children: [
+      /* @__PURE__ */ jsx(DropdownMenu.Trigger, { asChild: true, children: /* @__PURE__ */ jsxs(
+        "button",
+        {
+          type: "button",
+          "aria-label": `${current.name}, switch organization`,
+          title: current.name,
+          className: cn(
+            "inline-flex h-9 min-w-0 shrink-0 items-center gap-1 rounded-md px-2 text-sm sm:shrink font-medium text-[var(--color-text-primary)] transition-colors hover:bg-[var(--color-bg-subtle)]",
+            focusRing
+          ),
+          children: [
+            /* @__PURE__ */ jsx(Building2, { size: "md", "aria-hidden": "true", className: "shrink-0 sm:hidden" }),
+            /* @__PURE__ */ jsx("span", { className: cn("hidden sm:inline", orgLabelClass), children: current.name }),
+            /* @__PURE__ */ jsx(ChevronDown, { size: "sm", "aria-hidden": "true", className: "shrink-0 text-[var(--color-text-muted)]" })
+          ]
+        }
+      ) }),
+      /* @__PURE__ */ jsx(DropdownMenu.Portal, { children: /* @__PURE__ */ jsxs(DropdownMenu.Content, { align: "end", className: "max-w-[calc(100vw-1rem)]", children: [
+        /* @__PURE__ */ jsx(DropdownMenu.Label, { children: "Organizations" }),
+        /* @__PURE__ */ jsx(DropdownMenu.RadioGroup, { value: current.id, onValueChange: (id) => onOrgChange?.(id), children: orgs.map((org) => /* @__PURE__ */ jsx(DropdownMenu.RadioItem, { value: org.id, children: /* @__PURE__ */ jsx("span", { className: "truncate", children: org.name }) }, org.id)) })
+      ] }) })
+    ] })
+  );
+}
+function ThemeSwitch() {
+  const { resolvedTheme, setTheme } = useTheme();
+  const dark = resolvedTheme === "dark";
+  return /* @__PURE__ */ jsx(IconButton, { label: dark ? "Switch to light theme" : "Switch to dark theme", onClick: () => setTheme(dark ? "light" : "dark"), children: dark ? /* @__PURE__ */ jsx(Sun, { size: "md", "aria-hidden": "true" }) : /* @__PURE__ */ jsx(Moon, { size: "md", "aria-hidden": "true" }) });
+}
+var GLASS_LABELS = { clear: "Clear", balanced: "Balanced", tinted: "Tinted", off: "Solid" };
+function GlassItems() {
+  const { glass, setGlass } = useTheme();
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(DropdownMenu.Separator, {}),
+    /* @__PURE__ */ jsx(DropdownMenu.Label, { children: "Glass" }),
+    /* @__PURE__ */ jsx(DropdownMenu.RadioGroup, { value: glass, onValueChange: (v) => setGlass(v), children: Object.keys(GLASS_LABELS).map((mode) => /* @__PURE__ */ jsx(DropdownMenu.RadioItem, { value: mode, onSelect: (e) => e.preventDefault(), children: GLASS_LABELS[mode] }, mode)) })
+  ] });
+}
+function AccountMenu({
+  user,
+  accountHref,
+  privacyHref,
+  termsHref,
+  onSignOut,
+  accountMenuItems,
+  glassControl
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [signingOut, setSigningOut] = React.useState(false);
+  const signOut = (e) => {
+    e.preventDefault();
+    if (!onSignOut || signingOut) return;
+    setSigningOut(true);
+    Promise.resolve().then(onSignOut).finally(() => {
+      setSigningOut(false);
+      setOpen(false);
+    });
+  };
+  const link = (href, label) => /* @__PURE__ */ jsx(DropdownMenu.Item, { asChild: true, children: /* @__PURE__ */ jsx("a", { href, children: label }) });
+  const legal = (privacyHref || termsHref) && /* @__PURE__ */ jsxs(Fragment, { children: [
+    privacyHref && link(privacyHref, "Privacy policy"),
+    termsHref && link(termsHref, "Terms of service")
+  ] });
+  const last = (accountMenuItems || onSignOut) && /* @__PURE__ */ jsxs(Fragment, { children: [
+    accountMenuItems,
+    onSignOut && /* @__PURE__ */ jsx(DropdownMenu.Item, { disabled: signingOut, onSelect: signOut, children: signingOut ? "Signing out\u2026" : "Sign out" })
+  ] });
+  return (
+    // modal={false}: Radix's modal menu injects a <style> scroll lock (strict CSP).
+    /* @__PURE__ */ jsxs(DropdownMenu.Root, { open, onOpenChange: setOpen, modal: false, children: [
+      /* @__PURE__ */ jsx(DropdownMenu.Trigger, { asChild: true, children: /* @__PURE__ */ jsx("button", { type: "button", "aria-label": `Account: ${user.name}`, className: cn("ml-1 shrink-0 rounded-full", focusRing), children: /* @__PURE__ */ jsx(Avatar, { name: user.name, src: user.avatarUrl, size: "sm", "aria-hidden": "true" }) }) }),
+      /* @__PURE__ */ jsx(DropdownMenu.Portal, { children: /* @__PURE__ */ jsxs(DropdownMenu.Content, { align: "end", className: "w-72 max-w-[calc(100vw-1rem)]", children: [
+        /* @__PURE__ */ jsxs(DropdownMenu.Label, { className: "flex flex-col gap-0.5 py-2", children: [
+          /* @__PURE__ */ jsx("span", { className: "truncate text-title-sm text-[var(--color-on-surface)]", children: user.name }),
+          user.email && /* @__PURE__ */ jsx("span", { className: "truncate text-body-sm text-[var(--color-on-surface-muted)]", children: user.email })
+        ] }),
+        accountHref && link(accountHref, "Manage your Nexub Account"),
+        glassControl && /* @__PURE__ */ jsx(GlassItems, {}),
+        legal && /* @__PURE__ */ jsx(DropdownMenu.Separator, {}),
+        legal,
+        last && /* @__PURE__ */ jsx(DropdownMenu.Separator, {}),
+        last
+      ] }) })
+    ] })
+  );
+}
+var AppHeader = React.forwardRef(
+  ({
+    productName,
+    homeHref = "/",
+    onNavigate,
+    menu,
+    searchPlaceholder,
+    searchItems,
+    onSearch,
+    orgs = [],
+    currentOrgId,
+    onOrgChange,
+    showThemeSwitch = true,
+    apps,
+    user,
+    accountHref,
+    privacyHref,
+    termsHref,
+    onSignOut,
+    accountMenuItems,
+    surface = "solid",
+    className,
+    ...props
+  }, ref) => {
+    const placeholder = searchPlaceholder ?? (productName ? `Search ${productName}` : "Search");
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(
+        TopNav.Root,
+        {
+          ref,
+          role: "banner",
+          surface,
+          className: cn("fixed inset-x-0 top-0 h-[var(--app-header-height,64px)] px-2 sm:px-4", className),
+          ...props,
+          children: /* @__PURE__ */ jsxs("div", { className: "flex w-full min-w-0 items-center gap-1 sm:gap-2", children: [
+            menu && /* @__PURE__ */ jsx("div", { className: "flex shrink-0 md:hidden", children: menu }),
+            /* @__PURE__ */ jsx(
+              "a",
+              {
+                href: homeHref,
+                onClick: (e) => {
+                  if (onNavigate && isPlainClick(e)) {
+                    e.preventDefault();
+                    onNavigate(homeHref);
+                  }
+                },
+                className: cn("flex min-w-0 shrink items-center rounded-md p-1", focusRing),
+                children: /* @__PURE__ */ jsx(Logo, { size: "sm", product: productName })
+              }
+            ),
+            /* @__PURE__ */ jsx("div", { className: "ml-auto flex shrink-0 md:ml-0 md:min-w-0 md:flex-1 md:justify-center md:px-2 lg:px-4", children: (onSearch || searchItems) && /* @__PURE__ */ jsx(HeaderSearch, { placeholder, items: searchItems, onSearch }) }),
+            /* @__PURE__ */ jsxs("nav", { "aria-label": "Account and apps", className: "flex shrink-0 items-center gap-0.5 sm:gap-1", children: [
+              orgs.length > 0 && /* @__PURE__ */ jsx(OrgSwitcher, { orgs, currentOrgId, onOrgChange }),
+              showThemeSwitch && /* @__PURE__ */ jsx(ThemeSwitch, {}),
+              apps && /* @__PURE__ */ jsx(AppLauncher, { apps, surface, onNavigate: onNavigate && ((app) => onNavigate(app.href)) }),
+              user && /* @__PURE__ */ jsx(
+                AccountMenu,
+                {
+                  user,
+                  accountHref,
+                  privacyHref,
+                  termsHref,
+                  onSignOut,
+                  accountMenuItems,
+                  glassControl: showThemeSwitch && surface === "glass"
+                }
+              )
+            ] })
+          ] })
+        }
+      ),
+      /* @__PURE__ */ jsx("div", { "aria-hidden": "true", className: "h-[var(--app-header-height,64px)] shrink-0" })
+    ] });
+  }
+);
+AppHeader.displayName = "AppHeader";
+
+export {
+  AppHeader
+};

package/dist/chunk-VYMTTYPR.js

@@ -0,0 +1 @@
+'use client';

package/dist/components/AppHeader/index.js

@@ -0,0 +1,8 @@
+'use client';
+import {
+  AppHeader
+} from "../../chunk-OYSWFXRD.js";
+import "../../chunk-ZFHA46UX.js";
+export {
+  AppHeader
+};

package/dist/components/AppLauncher/index.js

@@ -1,7 +1,8 @@
 'use client';
+import "../../chunk-VYMTTYPR.js";
 import {
   AppLauncher
-} from "../../chunk-WQX5FFVK.js";
+} from "../../chunk-ZFHA46UX.js";
 export {
   AppLauncher
 };

package/dist/components/SettingsLayout/index.js

@@ -2,7 +2,7 @@
 import {
   SettingsLayout,
   SettingsRow
-} from "../../chunk-7UPV63EW.js";
+} from "../../chunk-5QFC4WFD.js";
 export {
   SettingsLayout,
   SettingsRow

package/dist/index.d.ts

@@ -152,6 +152,12 @@ interface SettingsLayoutProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     logo?: React.ReactNode;
     /** Top bar, right: theme switch, `<AppLauncher>`, account menu. */
     actions?: React.ReactNode;
+    /**
+     * Replaces the built-in top bar (and `logo`/`actions`), usually with an `AppHeader`.
+     * Gets the phone section-menu button to place in it:
+     * `header={(menu) => <AppHeader menu={menu} … />}`.
+     */
+    header?: (menuButton: React.ReactElement) => React.ReactNode;
     /** Page header. */
     title?: React.ReactNode;
     description?: React.ReactNode;
@@ -178,4 +184,66 @@ declare const SettingsLayout: React.ForwardRefExoticComponent<SettingsLayoutProp
     Row: React.ForwardRefExoticComponent<SettingsRowProps & React.RefAttributes<HTMLDivElement>>;
 };
 
-export { ActivityFeed, type ActivityItemProps, AppLauncher, type AppLauncherApp, type AppLauncherProps, AuthCard, type AuthCardProps, FilterBar, type FilterBarProps, InfoList, type InfoListItemProps, type InfoListRootProps, NotificationItem, type NotificationItemProps, PlanCard, type PlanCardProps, SettingsLayout, type SettingsLayoutItem, type SettingsLayoutProps, type SettingsLayoutSectionProps, SettingsRow, type SettingsRowProps, SettingsSection, type SettingsSectionProps, StatCard, type StatCardProps, StepIndicator, type StepIndicatorProps, type StepIndicatorStep, UserCard, type UserCardProps };
+interface AppHeaderSearchItem {
+    id: string;
+    label: string;
+    /** Shown muted on the right, e.g. "Project" or a shortcut. */
+    hint?: React.ReactNode;
+    icon?: React.ReactNode;
+    onSelect: () => void;
+}
+interface AppHeaderSearchGroup {
+    label: string;
+    items: AppHeaderSearchItem[];
+}
+interface AppHeaderOrg {
+    id: string;
+    name: string;
+}
+interface AppHeaderUser {
+    name: string;
+    email?: string;
+    avatarUrl?: string;
+}
+interface AppHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+    /** e.g. "Command Hub". Shown after the Nexub wordmark and in the search field. */
+    productName?: string;
+    /** Where the logo links. @default '/' */
+    homeHref?: string;
+    /** Client-side routing for the logo and launcher. When set, plain clicks call this instead of following the link. */
+    onNavigate?: (href: string) => void;
+    /** The app's own navigation trigger. Shown below `md` only. */
+    menu?: React.ReactNode;
+    /** @default `Search ${productName}` */
+    searchPlaceholder?: string;
+    /** Static results, filtered as the user types. */
+    searchItems?: AppHeaderSearchGroup[];
+    /** Async results (debounced). Takes precedence over `searchItems`. */
+    onSearch?: (query: string) => Promise<AppHeaderSearchGroup[]>;
+    orgs?: AppHeaderOrg[];
+    currentOrgId?: string;
+    onOrgChange?: (id: string) => void;
+    /** Needs a `ThemeProvider`. @default true */
+    showThemeSwitch?: boolean;
+    /** Passed to `AppLauncher`. No apps, no launcher. */
+    apps?: AppLauncherApp[];
+    /** No user, no account menu. */
+    user?: AppHeaderUser;
+    accountHref?: string;
+    privacyHref?: string;
+    termsHref?: string;
+    /** The menu stays open, with Sign out disabled, until the promise settles. */
+    onSignOut?: () => void | Promise<unknown>;
+    /** Extra `DropdownMenu.Item`s, shown above Sign out. */
+    accountMenuItems?: React.ReactNode;
+    surface?: 'solid' | 'glass';
+    /** `soft`: page content dissolves under the header instead of meeting a divider. */
+    scrollEdge?: 'soft' | 'hard';
+}
+/**
+ * The one top header every Nexub app shares. Fixed to the top; renders a
+ * spacer of `--app-header-height` after itself, so content starts below it.
+ */
+declare const AppHeader: React.ForwardRefExoticComponent<AppHeaderProps & React.RefAttributes<HTMLElement>>;
+
+export { ActivityFeed, type ActivityItemProps, AppHeader, type AppHeaderOrg, type AppHeaderProps, type AppHeaderSearchGroup, type AppHeaderSearchItem, type AppHeaderUser, AppLauncher, type AppLauncherApp, type AppLauncherProps, AuthCard, type AuthCardProps, FilterBar, type FilterBarProps, InfoList, type InfoListItemProps, type InfoListRootProps, NotificationItem, type NotificationItemProps, PlanCard, type PlanCardProps, SettingsLayout, type SettingsLayoutItem, type SettingsLayoutProps, type SettingsLayoutSectionProps, SettingsRow, type SettingsRowProps, SettingsSection, type SettingsSectionProps, StatCard, type StatCardProps, StepIndicator, type StepIndicatorProps, type StepIndicatorStep, UserCard, type UserCardProps };

package/dist/index.js

@@ -2,7 +2,10 @@
 import {
   SettingsLayout,
   SettingsRow
-} from "./chunk-7UPV63EW.js";
+} from "./chunk-5QFC4WFD.js";
+import {
+  PlanCard
+} from "./chunk-QMYBXQG4.js";
 import {
   SettingsSection
 } from "./chunk-OTNHVOPC.js";
@@ -15,29 +18,31 @@ import {
 import {
   UserCard
 } from "./chunk-AEYLZU3F.js";
+import {
+  AppHeader
+} from "./chunk-OYSWFXRD.js";
 import {
   ActivityFeed
 } from "./chunk-YX7UO577.js";
+import "./chunk-VYMTTYPR.js";
 import {
   AppLauncher
-} from "./chunk-WQX5FFVK.js";
+} from "./chunk-ZFHA46UX.js";
 import {
   AuthCard
 } from "./chunk-AOE6GQSH.js";
-import {
-  InfoList
-} from "./chunk-74JVLMLE.js";
 import {
   FilterBar
 } from "./chunk-EOA5C3Q4.js";
+import {
+  InfoList
+} from "./chunk-74JVLMLE.js";
 import {
   NotificationItem
 } from "./chunk-Y3TNGDKC.js";
-import {
-  PlanCard
-} from "./chunk-QMYBXQG4.js";
 export {
   ActivityFeed,
+  AppHeader,
   AppLauncher,
   AuthCard,
   FilterBar,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexub/patterns",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Composite UI patterns for Nexub Design System — pre-built, production-ready layouts and widgets built on @nexub/react.",
   "type": "module",
   "license": "MIT",
@@ -36,9 +36,9 @@
   "peerDependencies": {
     "react": ">=18 <20",
     "react-dom": ">=18 <20",
-    "@nexub/react": "^1.3.0",
-    "@nexub/icons": "^1.3.0",
-    "@nexub/tokens": "^1.3.0"
+    "@nexub/react": "^1.4.0",
+    "@nexub/icons": "^1.4.0",
+    "@nexub/tokens": "^1.4.0"
   },
   "peerDependenciesMeta": {
     "@nexub/icons": {
@@ -58,9 +58,9 @@
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^2.1.8",
-    "@nexub/icons": "1.3.0",
-    "@nexub/react": "1.3.0",
-    "@nexub/tokens": "1.3.0"
+    "@nexub/icons": "1.4.0",
+    "@nexub/react": "1.4.0",
+    "@nexub/tokens": "1.4.0"
   },
   "scripts": {
     "build": "tsup",