@djangocfg/layouts 2.1.275 → 2.1.277

package/README.md

@@ -8,18 +8,14 @@
 
 Layouts, app shell, and providers for **Next.js App Router**. Part of **[DjangoCFG](https://djangocfg.com)**.
 
-## Install & CSS
-
 ```bash
 pnpm add @djangocfg/layouts
 ```
 
 ```css
-/* Before @import "tailwindcss" */
+/* before @import "tailwindcss" */
 @import "@djangocfg/ui-nextjs/styles";
 @import "@djangocfg/layouts/styles";
-@import "@djangocfg/ui-tools/styles";
-@import "@djangocfg/debuger/styles";
 @import "tailwindcss";
 ```
 
@@ -29,11 +25,9 @@ Peers: `@djangocfg/ui-core`, `@djangocfg/ui-nextjs`, React 19, Next.js 16+, Tail
 
 ## BaseApp
 
-Root provider (theme, auth, analytics, SWR, toasts, …). Use when you **do not** need route-based layout switching.
+Root provider (theme, auth, analytics, SWR, toasts). Use when you **don't** need route-based layout switching.
 
 ```tsx
-import { BaseApp } from '@djangocfg/layouts';
-
 <BaseApp
   project="my-app"
   theme={{ defaultTheme: 'system', storageKey: 'my-theme' }}
@@ -44,67 +38,39 @@ import { BaseApp } from '@djangocfg/layouts';
 ```
 
 | Prop | Role |
-|------|------|
-| `project` | Name for monitor / debug |
-| `theme` | `defaultTheme`, `storageKey`, optional **`style`** (see below) |
-| `auth`, `analytics`, `centrifugo`, `errorTracking`, `errorBoundary`, `swr`, `pwaInstall`, `monitor`, `debug` | Optional integrations |
+|---|---|
+| `project` | Name for monitor / debug. Enables `window.monitor`. |
+| `theme` | `defaultTheme`, `storageKey`, and optional **`style`** (preset + CSS-var overrides). |
+| `auth`, `analytics`, `centrifugo`, `errorTracking`, `errorBoundary`, `swr`, `pwaInstall`, `monitor`, `debug` | Optional integrations. |
 
-### Theme: `theme.style` + `ThemeStyleBridge`
+### `theme.style`
 
-`BaseApp` passes theme to **next-themes** and mounts **`ThemeStyleBridge`**, which injects `<style id="djangocfg-baseapp-theme-style">` with **`--*`** variables (same naming as `@djangocfg/ui-core` `theme/light.css` & `dark.css`).
+Mounts `ThemeStyleBridge` → injects `<style id="djangocfg-baseapp-theme-style">` with `--*` variables. Merge order: imported globals → preset → `vars` (strongest).
 
 | Piece | Meaning |
-|--------|---------|
-| **`preset`** | One of **`THEME_STYLE_PRESET_ORDER`** — curated bundles in **`THEME_STYLE_PRESETS`** |
-| **`vars.light` / `vars.dark`** | Partial **`ThemeCssVarMap`** — HSL triplets (e.g. `192 90% 35%`); **`radius`** accepts any CSS length (`0.75rem`, …) |
-
-Merge order: **imported globals → preset → `vars`** (strongest).
-
-**Presets (summary)**
+|---|---|
+| `preset` | One of `THEME_STYLE_PRESET_ORDER`. Bundles live in `THEME_STYLE_PRESETS`. |
+| `vars.light` / `vars.dark` | Partial `ThemeCssVarMap` — HSL triplets (`192 90% 35%`); `radius` accepts any CSS length. |
 
-| ID | Role |
-|----|------|
-| `default` | No extra rules (globals only) |
-| `django-cfg` | Brand cyan primary + sidebar/chart alignment |
-| `ios` | System blue, hairline borders, **0.75rem** radius (Apple-like) |
-| `soft` | **1rem** radius, softer borders / surfaces |
-| `dense` | **0.25rem** radius, stronger borders (data / admin) |
-| `high-contrast` | Stronger borders & text contrast |
+Presets: `default` · `django-cfg` · `ios` · `soft` · `dense` · `high-contrast`.
 
-**Typing:** keys are grouped in source as **`ThemeCssVarColorKey`**, **`ThemeCssVarChromeKey`** (includes **`radius`**), **`ThemeCssVarSidebarKey`**, **`ThemeCssVarChartKey`** — together **`ThemeCssVarKey`**. Same semantics as the **Theme Configurator** playground’s `ThemeData.colors` / `radius` / `sidebar` / `charts`, mapped to kebab-case **`--`** names. Playground-only buckets (**shadows**, **typography**, **spacing**, …) are **not** injected here — export **full CSS** from the configurator when you need them.
+Playground-only buckets (shadows, typography, spacing) are **not** injected — export full CSS from the Theme Configurator when you need them.
 
-**Exports:** `ThemeStyleConfig`, `ThemeCssVarKey`, `ThemeCssVarMap`, `ThemeStylePresetId`, `THEME_STYLE_PRESETS`, `THEME_STYLE_PRESET_ORDER`, `buildThemeStyleSheet`, `ThemeStyleBridge`.
-
-```tsx
-<BaseApp
-  theme={{
-    defaultTheme: 'system',
-    storageKey: 'my-app-theme',
-    style: {
-      preset: 'django-cfg',
-      vars: { light: { ring: '200 85% 40%' }, dark: { 'muted-foreground': '0 0% 70%' } },
-    },
-  }}
->
-  {children}
-</BaseApp>
-```
+Exports: `ThemeStyleConfig`, `ThemeCssVarKey`, `ThemeCssVarMap`, `ThemeStylePresetId`, `THEME_STYLE_PRESETS`, `THEME_STYLE_PRESET_ORDER`, `buildThemeStyleSheet`, `ThemeStyleBridge`.
 
 ---
 
 ## AppLayout
 
-Wraps **BaseApp** and picks **admin → private → public** layout by path (`matchesPath` / `enabledPath`). **`noLayoutPaths`** skips the shell (fullscreen / embeds). **`publicChrome`** merges navbar/footer/main spacing defaults (see types **`AppLayoutPublicChrome`**, **`mergeAppLayoutPublicChrome`**).
+Wraps `BaseApp` and picks **admin → private → public** layout by path (`matchesPath` / `enabledPath`). `noLayoutPaths` skips the shell entirely (fullscreen / embeds). `publicChrome` merges navbar/footer/main spacing defaults.
 
 ```tsx
-import { AppLayout } from '@djangocfg/layouts';
-
 <AppLayout
   layouts={{
-    public: { component: PublicLayout, enabledPath: ['/', '/legal', '/contact'] },
+    public:  { component: PublicLayout,  enabledPath: ['/', '/legal', '/contact'] },
     private: { component: PrivateLayout, enabledPath: ['/dashboard'] },
-    admin: { component: AdminLayout, enabledPath: '/admin' },
-    noLayoutPaths: ['/embed', '/ui'],  // fullscreen, no navbar/footer
+    admin:   { component: AdminLayout,   enabledPath: '/admin' },
+    noLayoutPaths: ['/embed', '/ui'],
   }}
   baseApp={{ project: 'my-app', theme: { defaultTheme: 'system' }, auth: { apiUrl: '…' } }}
   i18n={{ locale, locales, onLocaleChange }}
@@ -113,133 +79,39 @@ import { AppLayout } from '@djangocfg/layouts';
 </AppLayout>
 ```
 
-> **`i18n` is required for correct path matching.**
-> `AppLayout` strips the locale prefix from the pathname before matching `enabledPath` / `noLayoutPaths`.
-> It uses `i18n.locale` for exact stripping — without it the fallback regex can misfire on
-> 2-letter path segments (e.g. `/ui/*` being treated as locale `ui`).
-> Always pass `i18n` when using next-intl or any locale-prefixed routing.
+> **`i18n` is required** for correct path matching when using `next-intl` or any locale-prefixed routing. Without it the fallback regex can mis-strip 2-letter path segments (e.g. `/ui/*` treated as locale `ui`).
 
 ---
 
-## Layouts (import from `@djangocfg/layouts`)
+## Layouts
 
 | Component | Use |
-|-----------|-----|
-| **PublicLayout** | Marketing / docs — slots: **`navbar`**, **`footer`**, **`backgroundSlot`**, **`contentTopSpacing`**, **`contentBottomSpacing`** |
-| **PublicNavbar** / **PublicFooter** | See `PublicNavbarConfig` below |
-| **PrivateLayout** | App shell — sidebar + header |
-| **AuthLayout** | Sign-in flows |
-| **AdminLayout** | Admin console |
-| **ProfileLayout** | Profile page with avatar, editable fields, 2FA, and slot/tab system |
-
-**`PublicLayout` — `backgroundSlot`**
-
-Pass any `ReactNode` as `backgroundSlot` to render a full-viewport layer *behind* the sticky navbar and all page content — without affecting layout flow.
-The recommended pattern is `fixed inset-0 -z-10 pointer-events-none`:
-
-```tsx
-<PublicLayout
-  contentTopSpacing="none"
-  contentBottomSpacing="none"
-  backgroundSlot={
-    <div
-      className="pointer-events-none fixed inset-0 -z-10"
-      style={{
-        background:
-          'radial-gradient(ellipse 55% 50% at 10% 0%, rgba(139,92,246,0.13) 0%, transparent 55%),' +
-          'radial-gradient(ellipse 40% 30% at 85% 75%, rgba(6,182,212,0.06) 0%, transparent 55%)',
-      }}
-    />
-  }
-  navbar={<PublicNavbar config={…} />}
->
-  <HeroSection />
-</PublicLayout>
-```
-
-Because the element is `fixed`, it covers the full viewport including the sticky navbar area, and `backdrop-blur` on the navbar lets the gradient show through.
-
----
-
-**Brand:** `ThemeBrandMark` / **`ThemeBrandMarkImg`** for logo slots.
-
-### PublicNavbar — layout variants & scroll behaviour
-
-```tsx
-<PublicNavbar config={{
-  brand: <Logo />,
-  navigation: navItems,
-  userMenu,
-
-  // Visual
-  navbarVariant: 'floating',   // 'floating' | 'flush'
-  navbarPosition: 'sticky',    // 'sticky' | 'fixed' | 'static'
-  navbarHeight: 'md',          // 'sm' | 'md' | 'lg'
-
-  // Desktop nav arrangement
-  navLayout: 'default',
-  // 'default'    → brand left | nav centered (absolute) | actions right
-  // 'brand-left' → brand left | nav after brand | actions pushed right
-  // 'centered'   → brand + nav + actions all centered in one row
-  // 'split'      → brand left | actions right | no desktop nav (drawer only)
-
-  // Scroll behaviour
-  hideNavOnScroll: true,       // slide up on scroll-down, back on scroll-up
-  transparent: true,           // transparent at page top, opaque after threshold
-  transparentThreshold: 40,    // px, default 40
-}} />
-```
-
-**Exported hooks** (for custom navbars):
-
-| Hook | Role |
-|------|------|
-| `useNavbarScroll(opts)` | Returns `{ hidden, scrolled }` driven by scroll position |
-| `useDropdownMenu()` | Hover open/close timers for desktop dropdowns |
-| `useNavbarViewportVars(ref, deps)` | Sets `--public-navbar-mobile-drawer-top/max-height` CSS vars |
+|---|---|
+| **`PublicLayout`** | Marketing / docs. Slots for navbar + footer. **[See PublicLayout README](./src/layouts/PublicLayout/README.md)** for full props, navbar variants (`FloatingNavbar` / `FlushNavbar` / `MinimalNavbar`), `DefaultFooter`, `NavAction`, and hooks. |
+| **`PrivateLayout`** | App shell — sidebar + header. |
+| **`AuthLayout`** | Sign-in flows. |
+| **`AdminLayout`** | Admin console. |
+| **`ProfileLayout`** | Profile page — avatar, editable fields, 2FA, tabs, slots (see below). |
 
-### ProfileLayout — slots & tabs
+### `ProfileLayout`
 
 ```tsx
-import { ProfileLayout } from '@djangocfg/layouts';
-import type { ProfileTab, ProfileSlots } from '@djangocfg/layouts';
-
-const tabs: ProfileTab[] = [
-  {
-    value: 'billing',
-    label: 'Billing',
-    content: <BillingSection />,
-  },
-];
-
-const slots: ProfileSlots = {
-  headerBadge:     <Badge>Pro</Badge>,           // next to user name
-  headerMenuItems: <DropdownMenuItem>…</DropdownMenuItem>, // in ⋯ menu
-  headerAfter:     <OnboardingBanner />,          // below avatar, above tabs
-  footer:          <LinkedAccounts />,            // below all tab content
-};
-
-<ProfileLayout
-  enable2FA
-  enableDeleteAccount
-  tabs={tabs}
-  slots={slots}
-/>
+<ProfileLayout enable2FA enableDeleteAccount tabs={tabs} slots={slots} />
 ```
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `enable2FA` | `boolean` | Show Security tab with 2FA management |
-| `enableDeleteAccount` | `boolean` | Show Delete account in `⋯` menu |
-| `tabs` | `ProfileTab[]` | Extra tabs appended after built-in ones |
-| `slots.headerBadge` | `ReactNode` | Rendered next to the user name (plan, role…) |
-| `slots.headerMenuItems` | `ReactNode` | Extra `DropdownMenuItem`s in the `⋯` menu |
-| `slots.headerAfter` | `ReactNode` | Below avatar row, above tabs |
-| `slots.footer` | `ReactNode` | Below all tab content |
+| Prop | Type | Role |
+|---|---|---|
+| `enable2FA` | `boolean` | Show Security tab with 2FA management. |
+| `enableDeleteAccount` | `boolean` | Show Delete account in `⋯` menu. |
+| `tabs` | `ProfileTab[]` | Extra tabs appended after built-in ones. |
+| `slots.headerBadge` | `ReactNode` | Next to user name (plan, role…). |
+| `slots.headerMenuItems` | `ReactNode` | Extra `DropdownMenuItem`s in `⋯` menu. |
+| `slots.headerAfter` | `ReactNode` | Below avatar row, above tabs. |
+| `slots.footer` | `ReactNode` | Below all tab content. |
 
 ---
 
-## i18n on AppLayout
+## i18n
 
 ```tsx
 import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
@@ -252,32 +124,32 @@ const { locale, locales, changeLocale } = useLocaleSwitcher();
 
 ## Monitor & debug
 
-`project` on **BaseApp** enables **`window.monitor`**. **Debug:** `Cmd+D` or `?debug=1`.
+`project` on `BaseApp` enables `window.monitor`. Debug panel: `Cmd+D` or `?debug=1`.
 
 ---
 
 ## Utilities
 
 | API | Role |
-|-----|------|
-| **useErrorEmitter**, **emitRuntimeError** | Error tracking hooks |
-| **ErrorLayout** (`/components/errors`) | 404 / error pages |
-| **RedirectPage** | Auth redirect helper |
-| **PrivacyPage**, **TermsPage**, … (`/pages/legal`) | Legal templates |
+|---|---|
+| `useErrorEmitter`, `emitRuntimeError` | Error tracking hooks. |
+| `ErrorLayout` (`/components/errors`) | 404 / error pages. |
+| `RedirectPage` | Auth redirect helper. |
+| `PrivacyPage`, `TermsPage`, … (`/pages/legal`) | Legal templates. |
 
 ---
 
 ## Package exports
 
 | Path | Contents |
-|------|----------|
-| `@djangocfg/layouts` | Barrel |
-| `@djangocfg/layouts/layouts` | Layout components |
-| `@djangocfg/layouts/components` | Misc |
-| `@djangocfg/layouts/pages/legal` | Legal pages |
-| `@djangocfg/layouts/styles` | Base CSS |
-
-## Extension packages
+|---|---|
+| `@djangocfg/layouts` | Barrel. |
+| `@djangocfg/layouts/layouts` | Layout components. |
+| `@djangocfg/layouts/components` | Misc. |
+| `@djangocfg/layouts/pages/legal` | Legal pages. |
+| `@djangocfg/layouts/styles` | Base CSS. |
+
+## Extensions
 
 `@djangocfg/ext-newsletter`, `ext-knowbase`, `ext-leads`, `ext-payments`, `ext-support`, …
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.275",
+  "version": "2.1.277",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -74,14 +74,14 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.275",
-    "@djangocfg/centrifugo": "^2.1.275",
-    "@djangocfg/debuger": "^2.1.275",
-    "@djangocfg/i18n": "^2.1.275",
-    "@djangocfg/monitor": "^2.1.275",
-    "@djangocfg/ui-core": "^2.1.275",
-    "@djangocfg/ui-nextjs": "^2.1.275",
-    "@djangocfg/ui-tools": "^2.1.275",
+    "@djangocfg/api": "^2.1.277",
+    "@djangocfg/centrifugo": "^2.1.277",
+    "@djangocfg/debuger": "^2.1.277",
+    "@djangocfg/i18n": "^2.1.277",
+    "@djangocfg/monitor": "^2.1.277",
+    "@djangocfg/ui-core": "^2.1.277",
+    "@djangocfg/ui-nextjs": "^2.1.277",
+    "@djangocfg/ui-tools": "^2.1.277",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -110,15 +110,15 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.275",
-    "@djangocfg/centrifugo": "^2.1.275",
-    "@djangocfg/debuger": "^2.1.275",
-    "@djangocfg/i18n": "^2.1.275",
-    "@djangocfg/monitor": "^2.1.275",
-    "@djangocfg/typescript-config": "^2.1.275",
-    "@djangocfg/ui-core": "^2.1.275",
-    "@djangocfg/ui-nextjs": "^2.1.275",
-    "@djangocfg/ui-tools": "^2.1.275",
+    "@djangocfg/api": "^2.1.277",
+    "@djangocfg/centrifugo": "^2.1.277",
+    "@djangocfg/debuger": "^2.1.277",
+    "@djangocfg/i18n": "^2.1.277",
+    "@djangocfg/monitor": "^2.1.277",
+    "@djangocfg/typescript-config": "^2.1.277",
+    "@djangocfg/ui-core": "^2.1.277",
+    "@djangocfg/ui-nextjs": "^2.1.277",
+    "@djangocfg/ui-tools": "^2.1.277",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/layouts/AppLayout/AppLayout.tsx

@@ -52,8 +52,8 @@ import type {
 import type { AuthConfig } from '@djangocfg/api/auth';
 import type { MonitorConfig } from '@djangocfg/monitor';
 
-import type { PublicNavbarConfig } from '../PublicLayout/components/PublicNavbar';
-import type { PublicFooterConfig } from '../PublicLayout/components/PublicFooter/types';
+import type { FloatingNavbarConfig } from '../PublicLayout/navbars/FloatingNavbar';
+import type { DefaultFooterConfig } from '../PublicLayout/footers/DefaultFooter/types';
 
 export type LayoutMode = 'public' | 'private' | 'admin';
 
@@ -63,10 +63,10 @@ export type PublicMainTopSpacing = 'auto' | 'none';
 /** Bottom padding of `<main>` above the footer. `compact` = less than `auto`; `none` = no extra gap. */
 export type PublicMainBottomSpacing = 'auto' | 'none' | 'compact';
 
-/** Shared marketing chrome defaults for `PublicNavbar` / `PublicFooter`, merged into your public layout. */
+/** Shared marketing chrome defaults for `FloatingNavbar` / `DefaultFooter`, merged into your public layout. */
 export interface AppLayoutPublicChrome {
-  navbar?: Partial<PublicNavbarConfig>;
-  footer?: Partial<PublicFooterConfig>;
+  navbar?: Partial<FloatingNavbarConfig>;
+  footer?: Partial<DefaultFooterConfig>;
   /**
    * Passed through to `PublicLayout` as `contentTopSpacing` / `contentBottomSpacing`.
    * Use `bottomSpacing: 'none'` when the page (or footer) should sit flush with no default gap.
@@ -86,11 +86,11 @@ export interface AppLayoutPublicChrome {
 }
 
 function mergePartialNavbar(
-  base?: Partial<PublicNavbarConfig>,
-  overlay?: Partial<PublicNavbarConfig>
-): Partial<PublicNavbarConfig> | undefined {
+  base?: Partial<FloatingNavbarConfig>,
+  overlay?: Partial<FloatingNavbarConfig>
+): Partial<FloatingNavbarConfig> | undefined {
   if (!base && !overlay) return undefined;
-  const merged: Partial<PublicNavbarConfig> = { ...base, ...overlay };
+  const merged: Partial<FloatingNavbarConfig> = { ...base, ...overlay };
   if (base?.shell || overlay?.shell) {
     merged.shell = { ...base?.shell, ...overlay?.shell };
   }
@@ -98,11 +98,11 @@ function mergePartialNavbar(
 }
 
 function mergePartialFooter(
-  base?: Partial<PublicFooterConfig>,
-  overlay?: Partial<PublicFooterConfig>
-): Partial<PublicFooterConfig> | undefined {
+  base?: Partial<DefaultFooterConfig>,
+  overlay?: Partial<DefaultFooterConfig>
+): Partial<DefaultFooterConfig> | undefined {
   if (!base && !overlay) return undefined;
-  const merged: Partial<PublicFooterConfig> = { ...base, ...overlay };
+  const merged: Partial<DefaultFooterConfig> = { ...base, ...overlay };
   if (base?.shell || overlay?.shell) merged.shell = { ...base?.shell, ...overlay?.shell };
   if (base?.brand || overlay?.brand) merged.brand = { ...base?.brand, ...overlay?.brand };
   if (base?.menus || overlay?.menus) merged.menus = { ...base?.menus, ...overlay?.menus };
@@ -164,7 +164,7 @@ export interface I18nLayoutConfig {
 
 /**
  * Props passed to every layout component (`public` / `private` / `admin`).
- * Use `publicChrome` to pass defaults for `PublicNavbar` / `PublicFooter` from `AppLayout`.
+ * Use `publicChrome` to pass defaults for `FloatingNavbar` / `DefaultFooter` from `AppLayout`.
  */
 export interface AppLayoutLayoutComponentProps {
   children: ReactNode;

package/src/layouts/PublicLayout/README.md

@@ -0,0 +1,144 @@
+# PublicLayout
+
+Slots-only shell for marketing / docs pages. You bring the navbar + footer; it provides the frame, mobile-drawer context, and main-content top/bottom spacing.
+
+```tsx
+import { PublicLayout, FloatingNavbar, DefaultFooter } from '@djangocfg/layouts';
+
+<PublicLayout
+  navbar={<FloatingNavbar config={{ brand, navigation, userMenu, actions }} />}
+  footer={<DefaultFooter config={{ variant: 'full', menus: { sections }, i18n }} />}
+>
+  {children}
+</PublicLayout>
+```
+
+## `PublicLayout`
+
+| Prop | Type | Default | Role |
+|---|---|---|---|
+| `navbar` | `ReactNode` | — | Pick a variant (below) or drop in your own. |
+| `footer` | `ReactNode` | — | Usually `DefaultFooter`. |
+| `backgroundSlot` | `ReactNode` | — | Full-viewport layer behind navbar + content. Use `fixed inset-0 -z-10 pointer-events-none`. |
+| `contentTopSpacing` | `'auto' \| 'none'` | `'auto'` | Auto pads `<main>` based on the navbar variant. |
+| `contentBottomSpacing` | `'auto' \| 'none' \| 'compact'` | `'auto'` | Bottom breathing room before footer. |
+
+## Navbar variants
+
+Three variants. All share the same core props (below); only the chrome differs.
+
+| Variant | Chrome |
+|---|---|
+| `FloatingNavbar` | Rounded, inset, soft shadow. `sticky top-3`. Default. |
+| `FlushNavbar` | Edge-to-edge, bottom border, no rounding. |
+| `MinimalNavbar` | Borderless, transparent-by-default (eesel-style), full-bleed. |
+
+### Shared config (all variants)
+
+| Prop | Type | Default | Role |
+|---|---|---|---|
+| `brand` | `ReactNode` | — | Logo slot. |
+| `brandHref` | `string` | `'/'` | Link target for brand. |
+| `navigation` | `NavigationItem[]` | `[]` | Primary items. Overflow collapses into a responsive "More" dropdown automatically. |
+| `userMenu` | `UserMenuConfig` | — | Groups + `authPath` + optional `i18n`. |
+| `actions` | `NavAction[]` | — | CTA pills on the right (before UserMenu). See `NavAction` below. |
+| `actionsLeadingSlot` | `ReactNode` | — | Arbitrary node between actions and UserMenu. |
+| `actionsTrailingSlot` | `ReactNode` | — | Arbitrary node after the mobile toggle. |
+| `navbarPosition` | `'sticky' \| 'fixed' \| 'static'` | `'sticky'` | |
+| `navbarHeight` | `'sm' \| 'md' \| 'lg'` | `'md'` | `py-2` / `py-3.5` / `py-5`. |
+| `navLayout` | `'default' \| 'brand-left' \| 'centered' \| 'split'` | `'default'` | Desktop arrangement. |
+| `hideNavOnScroll` | `boolean` | `false` | Slide up on scroll-down, back on scroll-up. |
+| `transparent` | `boolean` | `false` (Minimal: `true`) | Transparent at top, opaque after `transparentThreshold`. |
+| `transparentThreshold` | `number` | `40` | Px past which the nav becomes opaque. |
+| `desktopMaxPrimaryItems` | `number` | auto | Hard cap for primary items before overflow. |
+| `renderDesktopDropdown` | `(ctx) => ReactNode` | — | Replace default popover per-item. |
+
+### Variant-only
+
+| Variant | Extra props |
+|---|---|
+| `FloatingNavbar` | `shell?: { rounding?: string; className?: string }` |
+| `FlushNavbar` | `shell?: { rounding?: string; className?: string }` |
+| `MinimalNavbar` | `containerClassName?: string` (default `mx-auto max-w-[1400px] px-4 sm:px-6 lg:px-10`) |
+
+### `navLayout` variants
+
+- `default` — brand left | nav centered (flex-1) | actions right.
+- `brand-left` — brand + nav flow left-to-right, actions pushed right.
+- `centered` — all three groups centered in one row.
+- `split` — brand left, actions right, **no desktop nav** (drawer only).
+
+## `NavAction`
+
+Typed pill used by every navbar's `actions`.
+
+| Field | Type | Role |
+|---|---|---|
+| `label` | `string` | |
+| `href` | `string` | |
+| `external` | `boolean` | Opens in new tab. |
+| `variant` | `'link' \| 'ghost' \| 'outline' \| 'primary'` | Visual style. Default `ghost`. |
+| `hideOnSmall` | `boolean` | Hide below `lg`. |
+| `icon` | `ReactNode` | Optional leading icon. |
+| `onClick` | `(e) => void` | Extra handler; navigation still follows `href`. |
+
+```tsx
+actions={[
+  { label: 'Book a demo', href: '/demo', variant: 'ghost', hideOnSmall: true },
+  { label: 'Get started', href: '/signup', variant: 'primary' },
+]}
+```
+
+## `DefaultFooter`
+
+Three variants: `full` (default) with brand column + menus + controls; `compact` (one row + bottom); `simple` (copyright only).
+
+```tsx
+<DefaultFooter config={{ variant: 'full', menus: { sections }, i18n, slots }} />
+```
+
+| Prop (`config.*`) | Type | Default | Role |
+|---|---|---|---|
+| `variant` | `'full' \| 'compact' \| 'simple'` | `'full'` | |
+| `shell.className` | `string` | — | Outer container (e.g. `mx-auto max-w-7xl`). |
+| `brand.slot` | `ReactNode` | — | Replace the brand column. |
+| `brand.description` | `string` | — | Subtitle under brand. |
+| `brand.badge` | `{ icon: LucideIcon; text: string }` | — | Optional badge next to brand. |
+| `brand.showColumn` | `boolean` | `true` | Hide brand column entirely. |
+| `menus.sections` | `FooterMenuSection[]` | `[]` | Link columns. |
+| `menus.columnMinWidth` | `number` | `180` | Auto-fit grid min width. |
+| `menus.maxColumns` | `number` | `5` | |
+| `links` | `FooterLink[]` | `[]` | Bottom-row inline links (privacy / terms / …). |
+| `social` | `FooterSocialLinks` | — | Social icon row under brand. |
+| `meta.copyright` | `string` | `© ${year}. All rights reserved.` | |
+| `meta.credits` | `{ text: string; url?: string }` | — | |
+| `i18n` | `{ locale, locales, onLocaleChange }` | — | Required for the locale switcher. |
+| `controls.showThemeSwitcher` | `boolean` | `true` | Full variant only. |
+| `controls.showLocaleSwitcher` | `boolean` | `true` (if `i18n`) | Full variant only. |
+| `slots.aboveMenus` | `ReactNode` | — | Above the brand/menus grid (full variant). |
+| `slots.belowMenus` | `ReactNode` | — | Between menus and bottom row. |
+| `slots.bottomStart` | `ReactNode` | — | Next to copyright. |
+| `slots.bottomEnd` | `ReactNode` | — | Next to theme/locale controls. |
+
+## Hooks (custom navbars)
+
+| Hook | Role |
+|---|---|
+| `useNavbarScroll({ hideNavOnScroll, transparent, transparentThreshold })` | `{ hidden, scrolled }` |
+| `useDropdownMenu()` | Hover-open/close timers for desktop dropdowns. |
+| `useNavbarViewportVars(ref, deps)` | Sets `--public-navbar-mobile-drawer-top / max-height` CSS vars. |
+| `useResponsiveOverflow({ total, moreWidth, gap, minVisible })` | Dynamic "fit-or-overflow" for nav items (SSR-safe). |
+
+## Primitives
+
+`NavBrand`, `NavActions`, `NavActionItem`, `NavDesktopItems`, `ThemeBrandMark`, `ThemeBrandMarkImg`, `PublicLayoutProvider`, `usePublicLayout`.
+
+## Context
+
+`PublicLayoutProvider` is mounted by `PublicLayout`. Access via `usePublicLayout()`:
+
+| Field | Role |
+|---|---|
+| `mobileMenuOpen` / `toggleMobileMenu` / `closeMobileMenu` | Mobile drawer state. |
+| `navbarSurface` | `{ variant, position }` reported by the mounted navbar. |
+| `setNavbarSurface` | Called by navbars on mount/unmount — don't call yourself. |