@djangocfg/layouts 2.1.426 → 2.1.428

package/src/layouts/AppLayout/index.ts

@@ -1,25 +1,18 @@
 /**
- * AppLayout exports
+ * Provider stack exports.
+ *
+ * `BaseApp` is the canonical, framework-agnostic provider wrapper (theme, auth,
+ * i18n, monitor, error tracking…). Mount it ONCE at the app root. In Next.js
+ * apps, per-route shells are chosen by native route-group `layout.tsx` files
+ * (each imports `PrivateLayout` / `PublicLayout` and passes its own config) —
+ * there is no runtime layout-router component here anymore.
  */
 
-export { AppLayout } from './AppLayout';
-export type {
-  AppLayoutProps,
-  AppLayoutLayoutsConfig,
-  AppLayoutBaseAppConfig,
-  AppLayoutLayoutComponentProps,
-  AppLayoutPublicChrome,
-  LayoutMode,
-  I18nLayoutConfig,
-  PublicMainTopSpacing,
-  PublicMainBottomSpacing,
-} from './AppLayout';
-
-export { mergeAppLayoutPublicChrome } from './AppLayout';
-
 export { BaseApp } from './BaseApp';
 export type { BaseAppProps } from './BaseApp';
 
+export type { I18nLayoutConfig } from '../types';
+
 export {
   LayoutI18nProvider,
   useLayoutI18n,
@@ -27,8 +20,9 @@ export {
 } from './LayoutI18nProvider';
 export type { LayoutI18nProviderProps } from './LayoutI18nProvider';
 
-// Re-export theme-override primitives so consumers can import both the
-// AppLayout config surface and the rule/theme types from one place.
+// Re-export theme-override primitives so consumers can force a theme on a
+// subtree (e.g. an always-dark marketing route) without depending on ui-core
+// internals directly.
 export {
   ThemeOverride,
   resolveForcedTheme,
@@ -40,4 +34,3 @@ export type {
   ThemeOverrideProps,
   ForcedTheme,
 } from '@djangocfg/ui-core/theme';
-

package/src/layouts/AuthLayout/components/steps/SetupStep/SetupLoading.tsx

@@ -3,12 +3,16 @@
 import React, { memo, useMemo } from 'react';
 
 import { useAppT } from '@djangocfg/i18n';
+import { Preloader } from '@djangocfg/ui-core/components';
 
-import { AuthButton, AuthContainer, AuthHeader } from '../../shared';
+import { AuthContainer, AuthHeader } from '../../shared';
 
 /**
  * SetupLoading - Loading state for 2FA setup.
  *
+ * Uses the ui-core Preloader (text-primary spinner) so the "Setting up…"
+ * indicator stays clearly visible instead of the near-invisible chip spinner.
+ *
  * Memoised: no props; pure translation-driven component. Prevents
  * re-renders when parent orchestrators re-render for unrelated reasons.
  */
@@ -23,9 +27,7 @@ function SetupLoadingRaw() {
     <AuthContainer step="2fa-setup">
       <AuthHeader title={content.title} />
       <div className="auth-form-group">
-        <AuthButton loading disabled>
-          {content.button}
-        </AuthButton>
+        <Preloader variant="inline" text={content.button} className="py-4" />
       </div>
     </AuthContainer>
   );

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -13,7 +13,6 @@ import React, { ReactNode } from 'react';
 import { Preloader } from '@djangocfg/ui-core/components';
 import { SidebarInset, SidebarProvider } from '@djangocfg/ui-core/components';
 
-import type { AppLayoutPublicChrome } from '../AppLayout/AppLayout';
 import type { LayoutVisualConfig } from '../types';
 import { PrivateContent, PrivateSidebar } from './components';
 import { useAuthGuard } from './hooks';
@@ -42,8 +41,8 @@ export { SidebarBrandSwitcher } from './components';
 
 export { PrivateLayoutProps };
 
-const ProfileDialog = React.lazy(() =>
-  import('../ProfileLayout/ProfileDialog/ProfileDialog').then((m) => ({ default: m.ProfileDialog }))
+const SettingsDialog = React.lazy(() =>
+  import('../SettingsLayout/SettingsDialog').then((m) => ({ default: m.SettingsDialog }))
 );
 
 export function PrivateLayout({
@@ -55,6 +54,7 @@ export function PrivateLayout({
   contentScroll = 'auto',
   visual,
   requireAuth = true,
+  settings,
 }: PrivateLayoutProps) {
   const { isLoading, loadingText } = useAuthGuard({
     requireAuth,
@@ -104,7 +104,10 @@ export function PrivateLayout({
         </PrivateContent>
       </SidebarInset>
 
-      <ProfileDialog />
+      {/* Settings is the primary account dialog — always mounted so the
+          account-menu "Settings" item works out of the box. `settings` is
+          optional config (extra app sections / flags), not an on/off switch. */}
+      <SettingsDialog {...(settings ?? {})} />
     </SidebarProvider>
   );
 }

package/src/layouts/PrivateLayout/README.md

@@ -17,6 +17,36 @@ The auth guard redirects to `header.authPath` when there's no session. Pass `req
 
 ---
 
+## Wiring (canonical)
+
+Mount it in the **route-group `layout.tsx`** that owns the authenticated section
+— a thin config wrapper. Providers (`BaseApp`) live once at the app root; this
+file just chooses the private shell and feeds it sidebar/header config:
+
+```tsx
+// app/[locale]/(pages)/private/layout.tsx
+'use client';
+import { PrivateLayout } from '@djangocfg/layouts';
+import { usePathname } from '@djangocfg/nextjs/i18n/navigation';
+
+export default function PrivateRouteLayout({ children }) {
+  const pathname = usePathname();
+  return (
+    <PrivateLayout sidebar={sidebar} header={header} pathname={pathname}>
+      {children}
+    </PrivateLayout>
+  );
+}
+```
+
+**Admin** is the same component with a different `sidebar` — there is no separate
+`AdminLayout`. Put it in `app/.../admin/layout.tsx` with an admin menu config.
+
+See the demo app (`apps/demo/app/_layouts/PrivateLayout.tsx`) for a complete
+thin-wrapper reference, and the **BaseApp README** for the provider root.
+
+---
+
 ## Visual variants
 
 `boxed` (default) — `<SidebarInset>` becomes a rounded card; the wrapper paints `bg-sidebar` so the brand colour bleeds to the viewport edges. Mobile (<md) degrades to full-bleed automatically.

package/src/layouts/PrivateLayout/components/PrivateContent.tsx

@@ -1,6 +1,6 @@
 /**
  * Private layout main column — on narrow viewports a fixed menu FAB (`SidebarTrigger`) + scrollable area.
- * On viewports below `md`, the desktop sidebar is off-canvas; the trigger opens the `Drawer` from ui-nextjs sidebar.
+ * On viewports below `md`, the desktop sidebar is off-canvas; the trigger opens the `Drawer` from the ui-core sidebar.
  */
 
 'use client';
@@ -64,7 +64,11 @@ export function PrivateContent({
       : undefined;
 
   const scrollAreaClass = cn(
-    'min-h-0 flex-1 bg-card',
+    // The boxed content is the MAIN surface (Claude bg-100), not a raised card.
+    // `bg-background` keeps it the warm page tone; the slightly darker
+    // sidebar-canvas behind the inset gives the floating look. (`bg-card`, now
+    // lifted to 18.4%, made this big panel read too light.)
+    'min-h-0 flex-1 bg-background',
     scroll === 'auto' ? 'overflow-y-auto' : 'flex flex-col overflow-hidden',
     padding === 'default' && scroll === 'auto' && [
       'px-4 sm:px-6 lg:px-8',

package/src/layouts/PrivateLayout/components/PrivateSidebarAccount.tsx

@@ -11,9 +11,9 @@
 
 'use client';
 
-import { ChevronsUpDown, LogOut } from 'lucide-react';
+import { ChevronsUpDown, Languages, LogOut, Settings as SettingsIcon } from 'lucide-react';
 import { Link } from '@djangocfg/ui-core/components';
-import React, { memo, useMemo } from 'react';
+import React, { memo } from 'react';
 
 import { useAuth } from '@djangocfg/api/auth';
 import { useAppT } from '@djangocfg/i18n';
@@ -22,21 +22,19 @@ import {
   AvatarFallback,
   AvatarImage,
   Button,
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger,
+  LanguageFlag,
+  MenuBuilder,
 } from '@djangocfg/ui-core/components';
+import type { MenuItem } from '@djangocfg/ui-core/components';
 import { cn, isDev } from '@djangocfg/ui-core/lib';
 import { useSidebar } from '@djangocfg/ui-core/components';
 
 import { useLogout } from '../../../hooks';
 import { useLayoutI18nOptional } from '../../AppLayout/LayoutI18nProvider';
 import { LucideIcon as LucideIconRender } from '../../../components';
+import { getLocaleMeta } from '../../_components/locale-switcher/localeMeta';
 import { useShellVisualState } from '../hooks';
-import { useProfileDialogStore } from '../../ProfileLayout/ProfileDialog/store';
+import { useSettingsDialogStore } from '../../SettingsLayout/store';
 
 import type { HeaderConfig } from '../types';
 
@@ -101,11 +99,6 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
     setSidebarOpen(true);
   }, [setSidebarOpen]);
 
-  const onLogoutSelect = React.useCallback((e: Event) => {
-    e.preventDefault();
-    handleLogout();
-  }, [handleLogout]);
-
   // Hide entirely in production when there's no user (auth still loading or
   // /me failed and the parent guard hasn't redirected yet). In dev keep a
   // placeholder so the footer + Log out are reachable for debugging.
@@ -116,8 +109,10 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
   const secondary = header?.footerSecondaryAction;
 
   const triggerClassName = cn(
-    'group h-auto w-full gap-3 rounded-lg px-3 py-3 text-left',
+    'group h-auto w-full gap-3 rounded-lg px-3 py-3 text-left select-none',
     'hover:bg-sidebar-accent/70 hover:text-sidebar-accent-foreground',
+    // No focus ring on the menu trigger — the open menu is the affordance.
+    'focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0',
     content.isAccountCompact ? 'justify-center px-0 py-2' : 'min-h-[52px]',
   );
 
@@ -129,39 +124,16 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
     'p-1.5',
     content.isAccountCompact ? 'min-w-60' : 'w-[var(--radix-dropdown-menu-trigger-width)] min-w-60',
   );
-  const dropdownSide: 'top' | 'right' = content.isAccountCompact ? 'right' : 'top';
+  // Always open UPWARD over the avatar (Claude pattern). The footer sits at the
+  // bottom of the rail in both expanded and collapsed states, so `top` reads
+  // correctly either way (vs. `right`, which floated off to the side).
+  const dropdownSide: 'top' = 'top';
   const avatarClass = cn(
     'h-9 w-9 shrink-0 border border-transparent transition-colors',
     'group-hover:border-sidebar-border/70',
   );
 
   const headerLabelText = account.email ?? (account.source === 'dev-fallback' ? 'No active session' : null);
-  const headerLabel = headerLabelText ? (
-    <DropdownMenuLabel className="truncate px-2 py-1.5 text-xs font-normal text-muted-foreground">
-      {headerLabelText}
-    </DropdownMenuLabel>
-  ) : null;
-
-  const accountLinksItems = accountLinks.map((item) => {
-    const Icon = item.icon;
-    return (
-      <DropdownMenuItem key={item.href} asChild>
-        <Link
-          href={item.href!}
-          className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm"
-        >
-          {Icon ? <Icon className="h-4 w-4 shrink-0 text-muted-foreground" /> : null}
-          <span className="truncate">{item.label}</span>
-        </Link>
-      </DropdownMenuItem>
-    );
-  });
-  const accountLinksBlock = accountLinks.length > 0 ? (
-    <>
-      {headerLabel ? <DropdownMenuSeparator /> : null}
-      {accountLinksItems}
-    </>
-  ) : null;
 
   const expandedMeta = content.isAccountCompact ? null : (
     <>
@@ -184,17 +156,96 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
     </>
   );
 
-  const openProfileDialog = React.useCallback(() => {
-    useProfileDialogStore.getState().open();
+  // `accountAction: 'dialog'` opens the global SettingsDialog (mounted in
+  // PrivateLayout). Requires `settings` to be passed to PrivateLayout.
+  const openSettingsDialog = React.useCallback(() => {
+    useSettingsDialogStore.getState().open();
   }, []);
 
+  // ── Declarative account menu (Claude-style) — fed to MenuBuilder ──
+  const menuItems = React.useMemo<MenuItem[]>(() => {
+    const items: MenuItem[] = [];
+
+    // Email header.
+    if (headerLabelText) {
+      items.push({ kind: 'label', id: 'email', label: headerLabelText });
+    }
+
+    // Settings → opens the global SettingsDialog (⌘, like Claude).
+    items.push({
+      kind: 'item',
+      id: 'settings',
+      label: t('layouts.profile.settings') || 'Settings',
+      icon: SettingsIcon,
+      shortcut: '⇧⌘,',
+      onSelect: () => useSettingsDialogStore.getState().open(),
+    });
+
+    // Language → submenu with a radio group of locales (flag + native name,
+    // checkmark on the active one). Only when an i18n layout context is present.
+    if (layoutI18n && layoutI18n.locales.length > 1) {
+      items.push({
+        kind: 'submenu',
+        id: 'language',
+        label: t('layouts.profile.language') || 'Language',
+        icon: Languages,
+        items: [
+          {
+            kind: 'radio-group',
+            id: 'locale',
+            value: layoutI18n.locale,
+            onValueChange: layoutI18n.onLocaleChange,
+            options: layoutI18n.locales.map((code) => {
+              const meta = getLocaleMeta(code);
+              return {
+                id: code,
+                value: code,
+                label: meta.native,
+                icon: <LanguageFlag code={code} rounded className="h-3 w-4 shrink-0" />,
+              };
+            }),
+          },
+        ],
+      });
+    }
+
+    // App-provided account links (from header.groups).
+    if (accountLinks.length > 0) {
+      items.push({ kind: 'separator', id: 'sep-links' });
+      for (const link of accountLinks) {
+        items.push({
+          kind: 'item',
+          id: link.href!,
+          label: link.label,
+          icon: link.icon,
+          href: link.href,
+        });
+      }
+    }
+
+    // Log out (destructive). Let the menu close normally (no preventDefault) —
+    // the logout confirm dialog should appear over a CLOSED menu, not under a
+    // still-open one.
+    items.push({ kind: 'separator', id: 'sep-logout' });
+    items.push({
+      kind: 'item',
+      id: 'logout',
+      label: signOutLabel,
+      icon: LogOut,
+      variant: 'destructive',
+      onSelect: () => handleLogout(),
+    });
+
+    return items;
+  }, [headerLabelText, t, layoutI18n, accountLinks, signOutLabel, handleLogout]);
+
   const triggerButton = (
     <Button
       type="button"
       variant="ghost"
       aria-label={content.isAccountCompact ? account.displayName : undefined}
       className={triggerClassName}
-      onClick={header?.accountAction === 'dialog' ? openProfileDialog : onTriggerInteract}
+      onClick={header?.accountAction === 'dialog' ? openSettingsDialog : onTriggerInteract}
     >
       <Avatar className={avatarClass}>
         <AvatarImage src={account.avatarUrl} alt={account.displayName} />
@@ -209,7 +260,7 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
     content.isAccountCompact ? 'px-0 pb-0' : 'px-2 pb-2',
   );
 
-  // Dialog mode: simple button that opens the global ProfileDialog
+  // Dialog mode: simple button that opens the global SettingsDialog
   if (header?.accountAction === 'dialog') {
     return (
       <div className={wrapperClass}>
@@ -220,33 +271,17 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
 
   return (
     <div className={wrapperClass}>
-      <DropdownMenu
+      <MenuBuilder
+        items={menuItems}
         open={isAccountMenuOpen}
         onOpenChange={setIsAccountMenuOpen}
+        side={dropdownSide}
+        align="start"
+        sideOffset={8}
+        contentClassName={dropdownContentClass}
       >
-        <DropdownMenuTrigger asChild>
-          {triggerButton}
-        </DropdownMenuTrigger>
-
-        <DropdownMenuContent
-          side={dropdownSide}
-          align="start"
-          sideOffset={8}
-          className={dropdownContentClass}
-        >
-          {headerLabel}
-          {accountLinksBlock}
-
-          <DropdownMenuSeparator />
-          <DropdownMenuItem
-            onSelect={onLogoutSelect}
-            className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm text-destructive focus:bg-destructive/10 focus:text-destructive"
-          >
-            <LogOut className="h-4 w-4 shrink-0" />
-            <span className="truncate">{signOutLabel}</span>
-          </DropdownMenuItem>
-        </DropdownMenuContent>
-      </DropdownMenu>
+        {triggerButton}
+      </MenuBuilder>
     </div>
   );
 }

package/src/layouts/PrivateLayout/hooks/useAuthGuard.ts

@@ -33,17 +33,26 @@ export function useAuthGuard({
   const router = useRouter();
   const [isRedirecting, setIsRedirecting] = useState(false);
 
+  // Auth state lives in the browser (storage), so the server always renders
+  // unauthenticated → the preloader. Keep the first client render identical to
+  // the server (preloader) until mounted, then switch to the real auth result.
+  // Without this, the SSR preloader vs the hydrated shell is a hydration
+  // mismatch (logged as "Invalid HTML tag nesting" / regenerated tree).
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+
   useEffect(() => {
-    if (!requireAuth) return;
+    if (!mounted || !requireAuth) return;
     if (!authLoading && !isAuthenticated && !isRedirecting) {
       const currentUrl = window.location.pathname + window.location.search;
       saveRedirectUrl(currentUrl);
       setIsRedirecting(true);
       router.push(authPath);
     }
-  }, [requireAuth, isAuthenticated, authLoading, isRedirecting, router, saveRedirectUrl, authPath]);
+  }, [mounted, requireAuth, isAuthenticated, authLoading, isRedirecting, router, saveRedirectUrl, authPath]);
 
-  const isLoading = requireAuth && (authLoading || isRedirecting || !isAuthenticated);
+  const isLoading =
+    !mounted || (requireAuth && (authLoading || isRedirecting || !isAuthenticated));
   const loadingText = isRedirecting ? 'Redirecting to login...' : 'Authenticating...';
 
   return {

package/src/layouts/PrivateLayout/types.ts

@@ -7,7 +7,7 @@
 import type { ReactNode } from 'react';
 import type { LucideIcon } from 'lucide-react';
 
-import type { AppLayoutPublicChrome } from '../AppLayout/AppLayout';
+import type { SettingsDialogProps } from '../SettingsLayout/types';
 import type { LayoutVisualConfig } from '../types';
 import type { UserMenuConfig } from '../types';
 
@@ -223,6 +223,11 @@ export interface PrivateLayoutProps {
    * embeds where there's no real session. Default `true` (guard on).
    */
   requireAuth?: boolean;
-  /** Reserved for `AppLayout` passthrough (`publicChrome`); unused in this layout. */
-  publicChrome?: AppLayoutPublicChrome;
+  /**
+   * Mount the global SettingsDialog (Claude-style master/detail settings modal,
+   * hash-URL driven, openable via `useSettingsDialog()`). Pass a config object
+   * (even `{}`) to enable it with the built-in sections; omit to not mount it.
+   * Coexists with the legacy ProfileDialog — they are independent.
+   */
+  settings?: SettingsDialogProps;
 }