@djangocfg/layouts 2.1.256 → 2.1.259

package/src/layouts/PublicLayout/components/PublicNavigation.tsx

@@ -1,14 +1,24 @@
 /**
  * Public Layout Navigation
  *
- * Navigation component for PublicLayout with mobile drawer support
+ * Navigation component for PublicLayout with mobile drawer support.
+ *
+ * Colors: use Tailwind semantic utilities backed by `@djangocfg/ui-core` theme
+ * (`packages/ui-core/src/styles/theme/light.css`, `dark.css`, `tokens.css`).
  */
 
 'use client';
 
 import { ChevronDown, Menu, X } from 'lucide-react';
 import Link from 'next/link';
-import React, { type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import React, {
+  type ReactNode,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
 import { useAuth } from '@djangocfg/api/auth';
 import { useAppT } from '@djangocfg/i18n';
@@ -16,17 +26,17 @@ import {
   Button,
 } from '@djangocfg/ui-core/components';
 import { useIsTabletOrBelow } from '@djangocfg/ui-core/hooks';
-// cn is reserved for future conditional styling
-import { cn as _cn } from '@djangocfg/ui-core/lib';
+import { cn } from '@djangocfg/ui-core/lib';
 import { usePathnameWithoutLocale } from '../../../hooks';
 
 import { UserMenu } from '../../_components/UserMenu';
 import { usePublicLayoutOptional } from '../context';
+import { publicFloatingChromeClassName } from '../publicShellShadow';
+import type { PublicNavbarPosition, PublicNavbarVariant } from '../navbarTypes';
 
 import type { NavigationItem, UserMenuConfig } from '../../types';
 
-export type PublicNavbarVariant = 'floating' | 'flush';
-export type PublicNavbarPosition = 'sticky' | 'fixed' | 'static';
+export type { PublicNavbarPosition, PublicNavbarVariant } from '../navbarTypes';
 
 export interface PublicDesktopDropdownRenderProps {
   item: NavigationItem;
@@ -40,12 +50,12 @@ export interface PublicDesktopDropdownRenderProps {
 export type PublicDesktopDropdownRenderer = (props: PublicDesktopDropdownRenderProps) => React.ReactNode;
 
 interface PublicNavigationProps {
-  /** Custom brand node (full control over logo/text/link) */
+  /**
+   * Brand area: any React node, or a plain string (wrapped in `<Link href={brandHref}>` as the title).
+   */
   brand?: ReactNode;
-  /** Brand link for default brand renderer */
+  /** Used when `brand` is a string; also for deduping a lone nav link that matches this href (desktop). @default '/' */
   brandHref?: string;
-  logo?: string;
-  siteName?: string;
   navigation?: NavigationItem[];
   userMenu?: UserMenuConfig;
   containerClassName?: string;
@@ -54,6 +64,11 @@ interface PublicNavigationProps {
   renderDesktopDropdown?: PublicDesktopDropdownRenderer;
   /** Max visible top-level desktop items before collapsing into "More" */
   desktopMaxPrimaryItems?: number;
+  /**
+   * Tailwind rounding for the floating navbar shell (e.g. `rounded-3xl`). Defaults to `rounded-2xl`.
+   * Prefer `PublicNavbar` `config.shell.rounding` (or `AppLayout` `publicChrome.navbar.shell.rounding`).
+   */
+  rounding?: string;
   mobileMenuOpen?: boolean;
   onMobileMenuToggle?: () => void;
 }
@@ -62,11 +77,10 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
   const context = usePublicLayoutOptional();
   const brand = props.brand;
   const brandHref = props.brandHref ?? '/';
-  const logo = props.logo;
-  const siteName = props.siteName ?? 'App';
   const navigation = props.navigation ?? [];
   const userMenu = props.userMenu;
   const containerClassName = props.containerClassName;
+  const rounding = props.rounding;
   const navbarVariant = props.navbarVariant ?? 'floating';
   const navbarPosition = props.navbarPosition ?? 'sticky';
   const renderDesktopDropdown = props.renderDesktopDropdown;
@@ -83,8 +97,31 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
   const navOuterRef = useRef<HTMLDivElement | null>(null);
 
   const toggleMobileLabel = useMemo(() => t('layouts.navigation.toggleMobile'), [t]);
-  const desktopNavItemClass =
-    'inline-flex h-8 items-center rounded-md px-2 text-sm font-medium text-foreground/90 transition-colors hover:text-foreground hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50';
+
+  /** Long i18n labels: ellipsis instead of stretching the bar (desktop top-level + “More”). */
+  const desktopNavLabelClass = 'min-w-0 max-w-[11rem] truncate sm:max-w-[13rem]';
+  /** Dropdown / overflow menu rows — a bit wider than top-level pills. */
+  /** Top-level desktop nav control — larger hit target, works in light/dark. */
+  const desktopNavItemClass = cn(
+    // No `border-transparent` (1px “ghost” stroke still paints); use `border-0` and only add stroke in dark when needed.
+    'inline-flex min-h-9 items-center justify-center gap-1 rounded-full border-0 px-4 py-1.5 text-sm font-medium',
+    'ring-0 focus-visible:ring-0',
+    'text-foreground/90 transition-colors',
+    'hover:bg-accent/55 hover:text-foreground',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/35',
+  );
+  /** Light: fill only. Dark: optional hairline + muted fill. */
+  const desktopNavItemActiveClass =
+    'border-0 bg-accent font-semibold text-foreground shadow-sm dark:border dark:border-border dark:bg-muted dark:shadow-none';
+
+  const subMenuLinkClass = (active: boolean) =>
+    cn(
+      'flex min-h-9 min-w-0 max-w-[min(17rem,calc(100vw-5rem))] items-center rounded-full border-0 px-4 py-2 text-sm font-medium transition-colors',
+      'hover:bg-accent/55',
+      active
+        ? 'border-0 bg-accent font-semibold text-foreground shadow-sm dark:border dark:border-border dark:bg-muted/90 dark:shadow-none'
+        : 'border-0 text-foreground/90',
+    );
 
   const clearOpenTimer = () => {
     if (openTimerRef.current) {
@@ -131,6 +168,16 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
     }
   }, [isTabletOrBelow]);
 
+  const setNavbarSurface = context?.setNavbarSurface;
+
+  useLayoutEffect(() => {
+    if (!setNavbarSurface) return;
+    setNavbarSurface({ variant: navbarVariant, position: navbarPosition });
+    return () => {
+      setNavbarSurface(null);
+    };
+  }, [setNavbarSurface, navbarVariant, navbarPosition]);
+
   useEffect(() => {
     const updateDrawerViewportVars = () => {
       const root = document.documentElement;
@@ -175,17 +222,15 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
     return `${positionClass} ${topClass} inset-x-0 z-50 ${insetPaddingClass}`.trim().replace(/\s+/g, ' ');
   })();
 
-  const navInnerClassName = (() => {
-    const base =
-      'mx-auto w-full border border-border/40 dark:border-border/70';
-
-    const visual =
-      navbarVariant === 'floating'
-        ? 'rounded-2xl shadow-[0_10px_28px_rgba(0,0,0,0.14)] dark:shadow-[0_10px_28px_rgba(0,0,0,0.22)]'
-        : 'rounded-none border-x-0 border-t-0 shadow-none';
-
-    return `${base} ${visual} ${containerClassName || ''}`.trim().replace(/\s+/g, ' ');
-  })();
+  const navInnerClassName = cn(
+    'mx-auto w-full',
+    navbarVariant === 'floating'
+      ? cn(rounding ?? 'rounded-2xl', publicFloatingChromeClassName)
+      : 'rounded-none border-x-0 border-t-0 border-b border-border/40 dark:border-border/70 shadow-none',
+    containerClassName,
+    // Last: guarantee shell has no stroke on light; `containerClassName` cannot reintroduce a border.
+    navbarVariant === 'floating' && '!border-0 dark:!border dark:!border-border/75',
+  );
 
   const isActivePath = (href: string) => {
     if (href === '/') return pathname === '/';
@@ -199,41 +244,50 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
   };
 
   const closeDropdown = () => setOpenDropdownKey(null);
-  const desktopPrimaryNavigation = navigation.slice(0, desktopMaxPrimaryItems);
-  const desktopOverflowNavigation = navigation.slice(desktopMaxPrimaryItems);
+
+  /** Desktop: omit a lone top-level link that duplicates the brand link — saves space; drawer keeps full list. */
+  const desktopNavItems = useMemo(() => {
+    return navigation.filter((item) => {
+      if (item.items && item.items.length > 0) return true;
+      return item.href !== brandHref;
+    });
+  }, [navigation, brandHref]);
+
+  const desktopPrimaryNavigation = desktopNavItems.slice(0, desktopMaxPrimaryItems);
+  const desktopOverflowNavigation = desktopNavItems.slice(desktopMaxPrimaryItems);
 
   const renderDesktopNavItem = (item: NavigationItem) => {
     if (item.items && item.items.length > 0) {
       const dropdownKey = `${item.label}-${item.href}`;
       const defaultItems = (
         <>
-          {item.items.map((subItem) => (
-            <div key={`${item.label}-${subItem.href}`} className="rounded-md">
-              {subItem.external ? (
-                <a
-                  href={subItem.href}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  className="block rounded-md px-2.5 py-2 text-sm font-medium hover:bg-accent/40"
-                >
-                  {subItem.label}
-                </a>
-              ) : (
-                <Link
-                  href={subItem.href}
-                  className="block rounded-md px-2.5 py-2 text-sm font-medium hover:bg-accent/40"
-                >
-                  {subItem.label}
-                </Link>
-              )}
-            </div>
-          ))}
+          {item.items.map((subItem) => {
+            const subActive = isActivePath(subItem.href);
+            return (
+              <div key={`${item.label}-${subItem.href}`} className="rounded-full">
+                {subItem.external ? (
+                  <a
+                    href={subItem.href}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className={subMenuLinkClass(subActive)}
+                  >
+                    <span className="min-w-0 truncate" title={subItem.label}>{subItem.label}</span>
+                  </a>
+                ) : (
+                  <Link href={subItem.href} className={subMenuLinkClass(subActive)}>
+                    <span className="min-w-0 truncate" title={subItem.label}>{subItem.label}</span>
+                  </Link>
+                )}
+              </div>
+            );
+          })}
         </>
       );
 
       const defaultPopover = (
         <div
-          className="absolute left-0 top-full mt-1 z-[1200] min-w-56 rounded-xl border border-border/70 bg-background/95 backdrop-blur-sm p-1 shadow-[0_10px_28px_rgba(0,0,0,0.22)]"
+          className="absolute left-0 top-full mt-1 z-[1200] min-w-[14.5rem] rounded-xl border border-border/70 bg-background/95 backdrop-blur-sm p-1.5 shadow-[0_1px_2px_rgba(0,0,0,0.05),0_6px_18px_rgba(0,0,0,0.035)] dark:shadow-[0_6px_20px_rgba(0,0,0,0.12)]"
           onMouseEnter={() => {
             clearOpenTimer();
             clearCloseTimer();
@@ -256,12 +310,23 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
           <Button
             variant="ghost"
             size="sm"
-            className={`group ${desktopNavItemClass} ${isOpen || isActive ? 'bg-accent/50 text-foreground' : ''}`}
+            className={cn(
+              // Override Button base [&_svg]:size-16px so hover/layout doesn’t fight icon size; fixed chevron box avoids neighbor jitter when rotating.
+              'group h-auto min-h-9 max-w-[15rem] gap-1 shadow-none [&_svg]:size-3.5 [&_svg]:shrink-0',
+              desktopNavItemClass,
+              (isOpen || isActive) && desktopNavItemActiveClass,
+              isOpen && 'border-0 dark:border dark:border-border',
+            )}
           >
-            <span>{item.label}</span>
-            <ChevronDown
-              className={`ml-1 h-3.5 w-3.5 text-muted-foreground transition-transform duration-200 ${isOpen ? 'rotate-180' : ''}`}
-            />
+            <span className={desktopNavLabelClass} title={item.label}>{item.label}</span>
+            <span
+              className="inline-flex size-3.5 shrink-0 items-center justify-center"
+              aria-hidden
+            >
+              <ChevronDown
+                className={`size-3.5 origin-center text-muted-foreground transition-transform duration-200 ease-out will-change-transform ${isOpen ? 'rotate-180' : ''}`}
+              />
+            </span>
           </Button>
 
           {isOpen && (
@@ -280,41 +345,54 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
       );
     }
 
+    const linkActive = isActivePath(item.href);
     return (
       <Link
         key={item.href}
         href={item.href}
-        className={`${desktopNavItemClass} ${isActivePath(item.href) ? 'bg-accent/50 text-foreground' : ''}`}
+        className={cn(desktopNavItemClass, linkActive && desktopNavItemActiveClass)}
       >
-        {item.label}
+        <span className={desktopNavLabelClass} title={item.label}>{item.label}</span>
       </Link>
     );
   };
 
+  const hasDesktopOverflowNav = desktopOverflowNavigation.length > 0;
+  const isMoreMenuOpen = openDropdownKey === '__overflow-more';
+  const moreMenuButtonActive =
+    isMoreMenuOpen || desktopOverflowNavigation.some((navItem) => isGroupActive(navItem));
+
   return (
     <div ref={navOuterRef} className={navOuterClassName}>
       <nav
-        className={navInnerClassName}
-        style={{ backgroundColor: 'hsl(var(--background) / 0.72)', backdropFilter: 'blur(10px)' }}
+        className={cn(
+          navInnerClassName,
+          // Light: glass over page bg. Dark: slightly lifted vs --background (see ui-core theme/dark.css --card).
+          'bg-background/72 backdrop-blur-[10px] dark:bg-card/80',
+        )}
       >
-      <div className="w-full px-3 sm:px-4 lg:px-6">
+      <div className="w-full pl-6 pr-3 sm:px-4 lg:px-6">
         <div className="flex items-center justify-between py-3.5">
-          {/* Logo */}
-          {brand ? (
-            brand
-          ) : (
-            <Link href={brandHref} className="flex items-center gap-1.5">
-              {logo && (
-                <img src={logo} alt={siteName} className="h-5.5 w-auto object-contain" />
-              )}
-              <span className="font-bold text-[15px]">{siteName}</span>
-            </Link>
-          )}
+          {/* Brand */}
+          <div className="min-w-0 shrink-0 flex items-center">
+            {brand != null && brand !== '' && brand !== false
+              ? typeof brand === 'string'
+                ? (
+                    <Link
+                      href={brandHref}
+                      className="font-bold text-[15px] text-foreground hover:opacity-90 transition-opacity"
+                    >
+                      {brand}
+                    </Link>
+                  )
+                : brand
+              : null}
+          </div>
 
           {/* Desktop Navigation */}
-          <div className="hidden lg:flex items-center gap-3">
+          <div className="hidden isolate lg:flex items-center gap-1">
             {desktopPrimaryNavigation.map(renderDesktopNavItem)}
-            {desktopOverflowNavigation.length > 0 && (
+            {hasDesktopOverflowNav && (
               <div
                 className="relative"
                 onMouseEnter={() => scheduleOpen('__overflow-more')}
@@ -323,41 +401,48 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
                 <Button
                   variant="ghost"
                   size="sm"
-                  className={`group ${desktopNavItemClass} ${
-                    openDropdownKey === '__overflow-more' || desktopOverflowNavigation.some((item) => isGroupActive(item))
-                      ? 'bg-accent/50 text-foreground'
-                      : ''
-                  }`}
+                  className={cn(
+                    'group h-auto min-h-9 max-w-[15rem] gap-1 shadow-none [&_svg]:size-3.5 [&_svg]:shrink-0',
+                    desktopNavItemClass,
+                    moreMenuButtonActive && desktopNavItemActiveClass,
+                    isMoreMenuOpen && 'border-0 dark:border dark:border-border',
+                  )}
                 >
-                  <span>More</span>
-                  <ChevronDown
-                    className={`ml-1 h-3.5 w-3.5 text-muted-foreground transition-transform duration-200 ${
-                      openDropdownKey === '__overflow-more' ? 'rotate-180' : ''
-                    }`}
-                  />
+                  <span className={desktopNavLabelClass}>More</span>
+                  <span
+                    className="inline-flex size-3.5 shrink-0 items-center justify-center"
+                    aria-hidden
+                  >
+                    <ChevronDown
+                      className={`size-3.5 origin-center text-muted-foreground transition-transform duration-200 ease-out will-change-transform ${
+                        isMoreMenuOpen ? 'rotate-180' : ''
+                      }`}
+                    />
+                  </span>
                 </Button>
 
-                {openDropdownKey === '__overflow-more' && (
+                {isMoreMenuOpen && (
                   <div
-                    className="absolute right-0 top-full mt-1 z-[1200] min-w-56 rounded-xl border border-border/70 bg-background/95 backdrop-blur-sm p-1 shadow-[0_10px_28px_rgba(0,0,0,0.22)]"
+                    className="absolute right-0 top-full mt-1 z-[1200] min-w-[14.5rem] rounded-xl border border-border/70 bg-background/95 backdrop-blur-sm p-1.5 shadow-[0_1px_2px_rgba(0,0,0,0.05),0_6px_18px_rgba(0,0,0,0.035)] dark:shadow-[0_6px_20px_rgba(0,0,0,0.12)]"
                     onMouseEnter={() => {
                       clearOpenTimer();
                       clearCloseTimer();
                     }}
                     onMouseLeave={() => scheduleClose('__overflow-more')}
                   >
-                    {desktopOverflowNavigation.map((item) => (
-                      <div key={`overflow-${item.href}`} className="rounded-md">
-                        <Link
-                          href={item.href}
-                          className={`block rounded-md px-2.5 py-2 text-sm font-medium hover:bg-accent/40 ${
-                            isGroupActive(item) ? 'bg-accent/45 text-foreground' : ''
-                          }`}
-                        >
-                          {item.label}
-                        </Link>
-                      </div>
-                    ))}
+                    {desktopOverflowNavigation.map((navItem) => {
+                      const overflowActive = isGroupActive(navItem);
+                      return (
+                        <div key={`overflow-${navItem.href}`} className="rounded-full">
+                          <Link
+                            href={navItem.href}
+                            className={subMenuLinkClass(overflowActive)}
+                          >
+                            <span className="min-w-0 truncate" title={navItem.label}>{navItem.label}</span>
+                          </Link>
+                        </div>
+                      );
+                    })}
                   </div>
                 )}
               </div>
@@ -373,6 +458,7 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
                   variant="desktop"
                   groups={userMenu?.groups}
                   authPath={userMenu?.authPath}
+                  i18n={userMenu?.i18n}
                 />
               </>
             </div>
@@ -383,7 +469,7 @@ export function PublicNavigation(props: PublicNavigationProps = {}) {
               size="icon"
               aria-label={toggleMobileLabel}
               data-mobile-menu-trigger="true"
-              className="lg:hidden"
+              className="lg:hidden rounded-full"
               onClick={toggleMobileMenu}
             >
               {mobileMenuOpen ? <X className="h-5 w-5" /> : <Menu className="h-5 w-5" />}

package/src/layouts/PublicLayout/components/ThemeBrandMark.tsx

@@ -0,0 +1,83 @@
+/**
+ * Theme-aware brand mark for public chrome (navbar, footer).
+ *
+ * Uses two layers and Tailwind `dark:` so the correct asset is chosen with **no JS theme hook**
+ * and **no hydration mismatch** — the same thing `next-themes` does for `html.dark` / class strategy.
+ *
+ * Prefer this over `useTheme().resolvedTheme` + one `<img>` unless you have a strong reason
+ * (single-DOM node only).
+ */
+
+'use client';
+
+import React, { type ReactNode } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface ThemeBrandMarkProps {
+  /**
+   * Mark when the app is in **light** appearance (`html` without `.dark`).
+   * Usually a dark-colored logo on a light bar.
+   */
+  light: ReactNode;
+  /**
+   * Mark when the app is in **dark** appearance (`html.dark`).
+   * Usually a light-colored logo on a dark bar.
+   */
+  dark: ReactNode;
+  /** Outer wrapper — keep sizing here (e.g. `h-5.5 w-auto`). */
+  className?: string;
+  /** `role="img"` label when children are decorative. */
+  'aria-label'?: string;
+}
+
+/**
+ * Renders two branches; only one is visible. Same idea as pairing
+ * `className="dark:hidden"` / `className="hidden dark:block"` on `<img>`, but works with
+ * any node (SVG component, picture, etc.).
+ */
+export function ThemeBrandMark({ light, dark, className, 'aria-label': ariaLabel }: ThemeBrandMarkProps) {
+  return (
+    <span
+      className={cn('inline-flex shrink-0 items-center justify-center', className)}
+      role={ariaLabel ? 'img' : undefined}
+      aria-label={ariaLabel}
+    >
+      <span className="flex items-center justify-center dark:hidden">{light}</span>
+      <span className="hidden items-center justify-center dark:flex">{dark}</span>
+    </span>
+  );
+}
+
+export interface ThemeBrandMarkImgProps {
+  /** Logo URL for light UI (no `html.dark`). */
+  srcLight: string;
+  /** Logo URL for dark UI (`html.dark`). */
+  srcDark: string;
+  alt?: string;
+  /** Applied to both images (e.g. `h-5.5 w-auto object-contain`). */
+  className?: string;
+  wrapperClassName?: string;
+  'aria-label'?: string;
+}
+
+/**
+ * Convenience wrapper around {@link ThemeBrandMark} for the common “two raster/SVG URLs” case.
+ */
+export function ThemeBrandMarkImg({
+  srcLight,
+  srcDark,
+  alt = '',
+  className,
+  wrapperClassName,
+  'aria-label': ariaLabel,
+}: ThemeBrandMarkImgProps) {
+  return (
+    <ThemeBrandMark
+      className={wrapperClassName}
+      aria-label={ariaLabel}
+      light={<img src={srcLight} alt={alt} className={className} />}
+      dark={<img src={srcDark} alt={alt} className={className} />}
+    />
+  );
+}

package/src/layouts/PublicLayout/components/index.ts

@@ -6,4 +6,6 @@ export { PublicNavigation } from './PublicNavigation';
 export { PublicMobileDrawer } from './PublicMobileDrawer';
 export { PublicNavbar } from './PublicNavbar';
 export { PublicFooter } from './PublicFooter';
+export { ThemeBrandMark, ThemeBrandMarkImg } from './ThemeBrandMark';
+export type { ThemeBrandMarkProps, ThemeBrandMarkImgProps } from './ThemeBrandMark';
 

package/src/layouts/PublicLayout/context.tsx

@@ -2,10 +2,15 @@
 
 import React, { createContext, useContext } from 'react';
 
+import type { PublicNavbarSurface } from './navbarTypes';
+
 export interface PublicLayoutContextValue {
   mobileMenuOpen: boolean;
   toggleMobileMenu: () => void;
   closeMobileMenu: () => void;
+  /** Filled by `<PublicNavigation />` — drives default `main` top spacing. */
+  navbarSurface: PublicNavbarSurface | null;
+  setNavbarSurface: (surface: PublicNavbarSurface | null) => void;
 }
 
 const PublicLayoutContext = createContext<PublicLayoutContextValue | null>(null);

package/src/layouts/PublicLayout/hooks/index.ts

@@ -1,2 +1,2 @@
-export { useFloatingPanel } from './useFloatingPanel';
+export { useMobileNavPanel } from './useMobileNavPanel';
 

package/src/layouts/PublicLayout/hooks/useMobileNavPanel.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/** Slightly above `transition-[transform,opacity] duration-[220ms]` in PublicMobileDrawer */
+const CLOSE_UNMOUNT_MS = 230;
+
+/**
+ * Keeps the mobile nav panel mounted briefly after `isOpen` becomes false so CSS can run the close transition,
+ * then unmounts — no reliance on `transitionend` (fragile with SPA navigation / Safari).
+ */
+export function useMobileNavPanel(options: { isOpen: boolean; onClose: () => void }) {
+  const { isOpen, onClose } = options;
+  const [mounted, setMounted] = useState(isOpen);
+  const [visible, setVisible] = useState(isOpen);
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      if (closeTimerRef.current) {
+        clearTimeout(closeTimerRef.current);
+        closeTimerRef.current = null;
+      }
+      setMounted(true);
+      const id = requestAnimationFrame(() => {
+        requestAnimationFrame(() => setVisible(true));
+      });
+      return () => cancelAnimationFrame(id);
+    }
+
+    setVisible(false);
+    closeTimerRef.current = setTimeout(() => {
+      setMounted((m) => (m ? false : m));
+      closeTimerRef.current = null;
+    }, CLOSE_UNMOUNT_MS);
+
+    return () => {
+      if (closeTimerRef.current) {
+        clearTimeout(closeTimerRef.current);
+        closeTimerRef.current = null;
+      }
+    };
+  }, [isOpen]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [isOpen, onClose]);
+
+  return { mounted, visible };
+}

package/src/layouts/PublicLayout/index.ts

@@ -6,8 +6,12 @@ export { PublicLayout } from './PublicLayout';
 export type { PublicLayoutProps } from './PublicLayout';
 export { PublicNavigation, PublicMobileDrawer, PublicNavbar } from './components';
 export type {
+  PublicNavbarSurface,
   PublicNavbarVariant,
   PublicNavbarPosition,
+  PublicNavbarShellConfig,
+} from './navbarTypes';
+export type {
   PublicDesktopDropdownRenderer,
   PublicDesktopDropdownRenderProps,
 } from './components/PublicNavigation';
@@ -20,8 +24,12 @@ export {
   FooterSocialLinksComponent,
   DjangoCFGLogo,
 } from './components/PublicFooter';
+export { ThemeBrandMark, ThemeBrandMarkImg } from './components/ThemeBrandMark';
+export type { ThemeBrandMarkProps, ThemeBrandMarkImgProps } from './components/ThemeBrandMark';
 export type {
   PublicFooterProps,
+  PublicFooterConfig,
+  FooterProjectInfoProps,
 } from './components/PublicFooter';
 export { PublicLayoutProvider, usePublicLayout } from './context';
 

package/src/layouts/PublicLayout/navbarTypes.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared navbar surface types — used by PublicNavigation (registration) and PublicLayout (main offset).
+ */
+
+export type PublicNavbarVariant = 'floating' | 'flush';
+
+export type PublicNavbarPosition = 'sticky' | 'fixed' | 'static';
+
+export interface PublicNavbarSurface {
+  variant: PublicNavbarVariant;
+  position: PublicNavbarPosition;
+}
+
+/** Floating bar + mobile drawer shell (rounding, width / centering). */
+export interface PublicNavbarShellConfig {
+  /** Tailwind rounding class (e.g. `rounded-3xl`). */
+  rounding?: string;
+  /** Strip + drawer wrapper (e.g. `mx-auto max-w-7xl`). */
+  className?: string;
+}