@djangocfg/layouts 2.1.257 → 2.1.259

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

@@ -1,7 +1,10 @@
 /**
  * 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';
@@ -23,12 +26,12 @@ 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';
@@ -47,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;
@@ -61,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;
 }
@@ -69,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;
@@ -90,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) {
@@ -192,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 === '/';
@@ -216,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();
@@ -273,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 && (
@@ -297,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 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')}
@@ -340,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>
@@ -401,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/index.ts

@@ -9,6 +9,7 @@ export type {
   PublicNavbarSurface,
   PublicNavbarVariant,
   PublicNavbarPosition,
+  PublicNavbarShellConfig,
 } from './navbarTypes';
 export type {
   PublicDesktopDropdownRenderer,
@@ -23,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

@@ -10,3 +10,11 @@ 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;
+}

package/src/layouts/PublicLayout/publicShellShadow.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared “floating glass” chrome for navbar + mobile drawer.
+ *
+ * Light: barely-there lift. Dark: one soft outer shadow (border already defines the edge).
+ */
+export const publicFloatingChromeClassName =
+  [
+    '!border-0 ring-0 outline-none',
+    'shadow-[0_1px_6px_rgba(0,0,0,0.028)]',
+    'dark:!border dark:!border-border/75',
+    'dark:shadow-[0_3px_14px_rgba(0,0,0,0.07)]',
+  ].join(' ');

package/src/layouts/_components/UserMenu.tsx

@@ -138,7 +138,7 @@ export function UserMenu({
         <div className="pt-4 border-t border-border/50">
           <Link
             href={authPath}
-            className="group flex items-center justify-between rounded-lg px-2 py-2.5 text-sm font-medium text-muted-foreground transition-colors hover:text-foreground hover:bg-accent/40"
+            className="group flex items-center justify-between rounded-full px-4 py-2.5 text-sm font-medium text-muted-foreground transition-colors hover:text-foreground hover:bg-accent/40"
           >
             <span>{labels.signIn}</span>
             <ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-0.5" />
@@ -148,7 +148,7 @@ export function UserMenu({
     }
     return (
       <Link href={authPath}>
-        <Button variant="default" size="sm">
+        <Button variant="default" size="sm" className="rounded-full px-5">
           {labels.signIn}
         </Button>
       </Link>

package/src/layouts/types/index.ts

@@ -10,7 +10,15 @@
 // ============================================================================
 
 // Local provider configs
-export type { ThemeConfig, SWRConfigOptions, CentrifugoConfig } from './providers.types';
+export type {
+  ThemeConfig,
+  ThemeStyleConfig,
+  ThemeCssVarKey,
+  ThemeCssVarMap,
+  ThemeStylePresetId,
+  SWRConfigOptions,
+  CentrifugoConfig,
+} from './providers.types';
 
 // External provider configs (re-export for convenience)
 export type { AnalyticsConfig } from '../../snippets/Analytics/types';

package/src/layouts/types/providers.types.ts

@@ -5,6 +5,11 @@
  * Note: Analytics, PWA, Push, and Error types are defined in their respective modules
  */
 
+import type { ThemeStyleConfig } from '../../theme/themeStyle.types';
+
+// Re-export for consumers that only import from `layouts/types`
+export type { ThemeStyleConfig, ThemeCssVarKey, ThemeCssVarMap, ThemeStylePresetId } from '../../theme/themeStyle.types';
+
 // ============================================================================
 // Theme Configuration
 // ============================================================================
@@ -12,6 +17,11 @@
 export interface ThemeConfig {
   defaultTheme?: 'light' | 'dark' | 'system';
   storageKey?: string;
+  /**
+   * Typed CSS variable presets and per-mode overrides (see `ThemeStyleBridge` in BaseApp).
+   * For heavy visual editing, use the playground Theme Configurator and export CSS instead.
+   */
+  style?: ThemeStyleConfig;
 }
 
 // ============================================================================

package/src/theme/ThemeStyleBridge.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import { useEffect, useMemo } from 'react';
+
+import { buildThemeStyleSheet } from './buildThemeStyleSheet';
+
+import type { ThemeStyleConfig } from './themeStyle.types';
+
+const STYLE_ELEMENT_ID = 'djangocfg-baseapp-theme-style';
+
+export interface ThemeStyleBridgeProps {
+  style?: ThemeStyleConfig;
+}
+
+/**
+ * Injects merged theme CSS variables after globals (preset + typed overrides).
+ * Renders nothing; safe to mount once under ThemeProvider.
+ */
+export function ThemeStyleBridge({ style }: ThemeStyleBridgeProps) {
+  const css = useMemo(() => buildThemeStyleSheet(style), [style]);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    let el = document.getElementById(STYLE_ELEMENT_ID) as HTMLStyleElement | null;
+    if (!css) {
+      el?.remove();
+      return;
+    }
+
+    if (!el) {
+      el = document.createElement('style');
+      el.id = STYLE_ELEMENT_ID;
+      document.head.appendChild(el);
+    }
+
+    el.textContent = css;
+  }, [css]);
+
+  return null;
+}