@djangocfg/layouts 2.1.264 → 2.1.267

package/README.md

@@ -104,7 +104,7 @@ import { AppLayout } from '@djangocfg/layouts';
     public: { component: PublicLayout, enabledPath: ['/', '/legal', '/contact'] },
     private: { component: PrivateLayout, enabledPath: ['/dashboard'] },
     admin: { component: AdminLayout, enabledPath: '/admin' },
-    noLayoutPaths: ['/embed'],
+    noLayoutPaths: ['/embed', '/ui'],  // fullscreen, no navbar/footer
   }}
   baseApp={{ project: 'my-app', theme: { defaultTheme: 'system' }, auth: { apiUrl: '…' } }}
   i18n={{ locale, locales, onLocaleChange }}
@@ -113,21 +113,130 @@ 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.
+
 ---
 
 ## Layouts (import from `@djangocfg/layouts`)
 
 | Component | Use |
 |-----------|-----|
-| **PublicLayout** | Marketing / docs — slots: **`navbar`**, **`footer`**, **`contentTopSpacing`**, **`contentBottomSpacing`** |
-| **PublicNavbar** / **PublicFooter** | **`PublicNavbarConfig`** / **`PublicFooterConfig`** — **`shell.rounding`**, **`navbarVariant`**, **`navbarPosition`**, etc. |
+| **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 + 2FA |
+| **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 |
+
+### ProfileLayout — slots & tabs
+
+```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}
+/>
+```
+
+| 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 |
+
 ---
 
 ## i18n on AppLayout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.264",
+  "version": "2.1.267",
   "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.264",
-    "@djangocfg/centrifugo": "^2.1.264",
-    "@djangocfg/i18n": "^2.1.264",
-    "@djangocfg/monitor": "^2.1.264",
-    "@djangocfg/debuger": "^2.1.264",
-    "@djangocfg/ui-core": "^2.1.264",
-    "@djangocfg/ui-nextjs": "^2.1.264",
-    "@djangocfg/ui-tools": "^2.1.264",
+    "@djangocfg/api": "^2.1.267",
+    "@djangocfg/centrifugo": "^2.1.267",
+    "@djangocfg/debuger": "^2.1.267",
+    "@djangocfg/i18n": "^2.1.267",
+    "@djangocfg/monitor": "^2.1.267",
+    "@djangocfg/ui-core": "^2.1.267",
+    "@djangocfg/ui-nextjs": "^2.1.267",
+    "@djangocfg/ui-tools": "^2.1.267",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -103,21 +103,22 @@
     }
   },
   "dependencies": {
+    "libphonenumber-js": "^1.12.24",
     "nextjs-toploader": "^3.9.17",
     "qrcode.react": "^4.2.0",
     "react-ga4": "^2.1.0",
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.264",
-    "@djangocfg/i18n": "^2.1.264",
-    "@djangocfg/centrifugo": "^2.1.264",
-    "@djangocfg/monitor": "^2.1.264",
-    "@djangocfg/debuger": "^2.1.264",
-    "@djangocfg/typescript-config": "^2.1.264",
-    "@djangocfg/ui-core": "^2.1.264",
-    "@djangocfg/ui-nextjs": "^2.1.264",
-    "@djangocfg/ui-tools": "^2.1.264",
+    "@djangocfg/api": "^2.1.267",
+    "@djangocfg/centrifugo": "^2.1.267",
+    "@djangocfg/debuger": "^2.1.267",
+    "@djangocfg/i18n": "^2.1.267",
+    "@djangocfg/monitor": "^2.1.267",
+    "@djangocfg/typescript-config": "^2.1.267",
+    "@djangocfg/ui-core": "^2.1.267",
+    "@djangocfg/ui-nextjs": "^2.1.267",
+    "@djangocfg/ui-tools": "^2.1.267",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/hooks/index.ts

@@ -1,2 +1,2 @@
-export { usePathnameWithoutLocale, stripLocalePrefix } from './usePathnameWithoutLocale';
+export { usePathnameWithoutLocale } from './usePathnameWithoutLocale';
 export { useLogout } from './useLogout';

package/src/hooks/usePathnameWithoutLocale.ts

@@ -4,36 +4,52 @@ import { usePathname } from 'next/navigation';
 import { useMemo } from 'react';
 
 /**
- * Strip locale prefix from pathname
- * Handles: /xx/path, /xx-XX/path (e.g., /en, /ko, /pt-BR)
+ * Normalize pathname: remove trailing slash except for root "/".
+ * Works regardless of Next.js trailingSlash config.
  */
-function stripLocalePrefix(pathname: string): string {
-  // Match /xx or /xx-XX at the start
-  const match = pathname.match(/^\/[a-z]{2}(-[A-Z]{2})?(\/|$)/);
-
-  if (match) {
-    const rest = pathname.slice(match[0].length - 1) || '/';
-    return rest.startsWith('/') ? rest : '/' + rest;
-  }
+function normalize(p: string): string {
+  return p.length > 1 ? p.replace(/\/+$/, '') : p;
+}
 
+/**
+ * Strip locale prefix from pathname using known locale string.
+ */
+function stripLocale(pathname: string, locale: string): string {
+  const prefix = '/' + locale;
+  if (pathname === prefix || pathname === prefix + '/') return '/';
+  if (pathname.startsWith(prefix + '/')) return pathname.slice(prefix.length);
+  // Path already has no locale prefix (next-intl localePrefix:'as-needed' for default locale)
   return pathname;
 }
 
 /**
  * usePathnameWithoutLocale
  *
- * Returns pathname without locale prefix.
- * Useful for route matching when using next-intl or similar i18n routing.
+ * Returns the current pathname without locale prefix, normalized (no trailing slash).
+ *
+ * Pass `locale` (from i18n config / useLocaleSwitcher) for exact stripping.
+ * Without locale, falls back to regex — known to misfire on 2-letter path segments like /ui.
  *
  * @example
- * // URL: /ko/private/dashboard
- * const pathname = usePathnameWithoutLocale();
- * // pathname = '/private/dashboard'
+ * // URL: /en/ui/playground, locale="en"  →  "/ui/playground"
+ * // URL: /ui/playground/ (no prefix)     →  "/ui/playground"
  */
-export function usePathnameWithoutLocale(): string {
+export function usePathnameWithoutLocale(locale?: string): string {
   const pathname = usePathname();
 
-  return useMemo(() => stripLocalePrefix(pathname), [pathname]);
-}
+  return useMemo(() => {
+    if (locale) {
+      return normalize(stripLocale(pathname, locale));
+    }
 
-export { stripLocalePrefix };
+    // Fallback regex — only when locale is unknown
+    const match = pathname.match(/^\/[a-z]{2}(-[A-Z]{2})?(\/|$)/);
+    if (match) {
+      const rest = pathname.slice(match[0].length - 1) || '/';
+      const withSlash = rest.startsWith('/') ? rest : '/' + rest;
+      return normalize(withSlash);
+    }
+
+    return normalize(pathname);
+  }, [pathname, locale]);
+}

package/src/layouts/AppLayout/AppLayout.tsx

@@ -75,6 +75,14 @@ export interface AppLayoutPublicChrome {
     topSpacing?: PublicMainTopSpacing;
     bottomSpacing?: PublicMainBottomSpacing;
   };
+  /**
+   * Full-viewport background layer rendered behind the navbar and all page content.
+   * Pass a `fixed inset-0 -z-10 pointer-events-none` element — it covers the whole
+   * viewport (including the sticky navbar area) without affecting layout flow.
+   *
+   * Set per-page via `AppLayout publicChrome` or directly on `PublicSiteLayout`.
+   */
+  backgroundSlot?: ReactNode;
 }
 
 function mergePartialNavbar(
@@ -120,8 +128,10 @@ export function mergeAppLayoutPublicChrome(
     root?.main || fromLayouts?.main
       ? { ...root?.main, ...fromLayouts?.main }
       : undefined;
-  if (!navbar && !footer && !main) return undefined;
-  return { navbar, footer, ...(main ? { main } : {}) };
+  // backgroundSlot: layouts-level overrides root (more specific wins)
+  const backgroundSlot = fromLayouts?.backgroundSlot ?? root?.backgroundSlot;
+  if (!navbar && !footer && !main && !backgroundSlot) return undefined;
+  return { navbar, footer, ...(main ? { main } : {}), ...(backgroundSlot ? { backgroundSlot } : {}) };
 }
 
 /**
@@ -291,8 +301,9 @@ function AppLayoutContent({
   i18n,
   publicChrome,
 }: AppLayoutContentProps) {
-  // Use pathname without locale prefix for route matching
-  const pathname = usePathnameWithoutLocale();
+  // Use pathname without locale prefix for route matching.
+  // Pass locale from i18n so strip is exact — avoids regex misfiring on /ui, /ko, etc.
+  const pathname = usePathnameWithoutLocale(i18n?.locale);
 
   // Merge authPath into noLayoutPaths — auth pages are always fullscreen
   const effectiveNoLayoutPaths = useMemo(() => {

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

@@ -15,12 +15,8 @@ export interface SetupStepProps {
 }
 
 /**
- * SetupStep - Orchestrator for 2FA setup flow
- *
- * Delegates rendering to focused sub-components:
- * - SetupLoading: Initial loading state
- * - SetupQRCode: QR code scanning
- * - SetupComplete: Backup codes display
+ * SetupStep - Orchestrator for 2FA setup flow (requires AuthFormContext).
+ * For use outside AuthLayout use SetupStepStandalone.
  */
 export const SetupStep: React.FC<SetupStepProps> = ({ onComplete, onSkip }) => {
   const { setStep } = useAuthFormContext();
@@ -89,3 +85,51 @@ export const SetupStep: React.FC<SetupStepProps> = ({ onComplete, onSkip }) => {
   // Fallback to loading
   return <SetupLoading />;
 };
+
+/**
+ * SetupStepStandalone — same flow as SetupStep but without AuthFormContext.
+ * Use this inside ProfileLayout or any page outside AuthLayout.
+ */
+export const SetupStepStandalone: React.FC<SetupStepProps> = ({ onComplete, onSkip }) => {
+  const {
+    isLoading,
+    error,
+    setupData,
+    backupCodes,
+    backupCodesWarning,
+    setupStep,
+    startSetup,
+    confirmSetup,
+  } = useTwoFactorSetup({ onComplete, onError: () => {} });
+
+  React.useEffect(() => {
+    if (setupStep === 'idle') startSetup();
+  }, [setupStep, startSetup]);
+
+  if (isLoading && !setupData) return <SetupLoading />;
+
+  if (setupStep === 'complete' && backupCodes) {
+    return (
+      <SetupComplete
+        backupCodes={backupCodes}
+        backupCodesWarning={backupCodesWarning}
+        onDone={() => onComplete?.()}
+      />
+    );
+  }
+
+  if (setupData) {
+    return (
+      <SetupQRCode
+        provisioningUri={setupData.provisioningUri}
+        secret={setupData.secret}
+        isLoading={isLoading}
+        error={error}
+        onConfirm={confirmSetup}
+        onSkip={onSkip}
+      />
+    );
+  }
+
+  return <SetupLoading />;
+};