@djangocfg/layouts 2.1.307 → 2.1.309

package/README.md

@@ -87,7 +87,7 @@ Wraps `BaseApp` and picks **admin → private → public** layout by path (`matc
 
 | Component | Use |
 |---|---|
-| **`PublicLayout`** | Marketing / docs. Slots for navbar + footer. All anchors render through `<Link>` from `@djangocfg/ui-core/components` — wrap with `LinkProvider` higher in the tree to inject a locale-aware Link (e.g. `next-intl`). All three navbars accept `controls` + `i18n` to show theme / locale switchers next to UserMenu (same shape as `DefaultFooter.controls`). **[See PublicLayout README](./src/layouts/PublicLayout/README.md)** for full props, navbar variants (`FloatingNavbar` / `FlushNavbar` / `MinimalNavbar`), `DefaultFooter`, `NavAction`, `NavControls`, and hooks. |
+| **`PublicLayout`** | Marketing / docs. Slots for navbar + footer. All anchors render through `<Link>` from `@djangocfg/ui-core/components` — wrap with `LinkProvider` higher in the tree to inject a locale-aware Link (e.g. `next-intl`). All three navbars accept a `controls` block to show theme / locale switchers next to `UserMenu`; locale data flows from `LayoutI18nProvider` (mounted by `AppLayout` / `BaseApp` when you pass `i18n`). The locale switcher renders SVG country flags and matches the `UserMenu` avatar size at `size="icon"`. **[See PublicLayout README](./src/layouts/PublicLayout/README.md)** for full props, navbar variants (`FloatingNavbar` / `FlushNavbar` / `MinimalNavbar`), `DefaultFooter`, `NavAction`, `NavControls`, and hooks. |
 | **`PrivateLayout`** | App shell — sidebar + header. Defaults to the `boxed` visual (inset rounded card on a sidebar-coloured canvas); pass `visual={{ variant: 'full-bleed' }}` for the legacy edge-to-edge layout. |
 | **`AuthLayout`** | Sign-in flows. |
 | **`AdminLayout`** | Admin console. |
@@ -139,11 +139,16 @@ Wraps `BaseApp` and picks **admin → private → public** layout by path (`matc
 
 ```tsx
 import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
+import { routing } from '@djangocfg/nextjs/i18n/routing';
 
 const { locale, locales, changeLocale } = useLocaleSwitcher();
-<AppLayout i18n={{ locale, locales, onLocaleChange: changeLocale }}>{children}</AppLayout>
+<AppLayout i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>
+  {children}
+</AppLayout>
 ```
 
+`i18n.routing` is the object returned by `defineRouting()` (`next-intl/routing`). When passed, `BaseApp` builds a locale-aware `Link` adapter from it and mounts a `LinkProvider`, so every `<Link>` rendered inside layouts (navbar, footer, drawer, …) keeps the active locale prefix on click. Drop it for default-locale-only apps — raw `next/link` works fine.
+
 ---
 
 ## Monitor & debug

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.307",
+  "version": "2.1.309",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -74,19 +74,20 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.307",
-    "@djangocfg/centrifugo": "^2.1.307",
-    "@djangocfg/debuger": "^2.1.307",
-    "@djangocfg/i18n": "^2.1.307",
-    "@djangocfg/monitor": "^2.1.307",
-    "@djangocfg/ui-core": "^2.1.307",
-    "@djangocfg/ui-nextjs": "^2.1.307",
-    "@djangocfg/ui-tools": "^2.1.307",
+    "@djangocfg/api": "^2.1.309",
+    "@djangocfg/centrifugo": "^2.1.309",
+    "@djangocfg/debuger": "^2.1.309",
+    "@djangocfg/i18n": "^2.1.309",
+    "@djangocfg/monitor": "^2.1.309",
+    "@djangocfg/ui-core": "^2.1.309",
+    "@djangocfg/ui-nextjs": "^2.1.309",
+    "@djangocfg/ui-tools": "^2.1.309",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
     "next": "^16.2.2",
+    "next-intl": "^4.9.1",
     "p-retry": "^7.0.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -110,19 +111,20 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.307",
-    "@djangocfg/centrifugo": "^2.1.307",
-    "@djangocfg/debuger": "^2.1.307",
-    "@djangocfg/i18n": "^2.1.307",
-    "@djangocfg/monitor": "^2.1.307",
-    "@djangocfg/typescript-config": "^2.1.307",
-    "@djangocfg/ui-core": "^2.1.307",
-    "@djangocfg/ui-nextjs": "^2.1.307",
-    "@djangocfg/ui-tools": "^2.1.307",
+    "@djangocfg/api": "^2.1.309",
+    "@djangocfg/centrifugo": "^2.1.309",
+    "@djangocfg/debuger": "^2.1.309",
+    "@djangocfg/i18n": "^2.1.309",
+    "@djangocfg/monitor": "^2.1.309",
+    "@djangocfg/typescript-config": "^2.1.309",
+    "@djangocfg/ui-core": "^2.1.309",
+    "@djangocfg/ui-nextjs": "^2.1.309",
+    "@djangocfg/ui-tools": "^2.1.309",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "eslint": "^9.37.0",
+    "next-intl": "^4.9.1",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/src/layouts/AppLayout/BaseApp.tsx

@@ -49,6 +49,7 @@ import { CentrifugoProvider } from '@djangocfg/centrifugo';
 import { Toaster, TooltipProvider } from '@djangocfg/ui-core/components';
 import { DialogProvider } from '@djangocfg/ui-core/lib/dialog-service';
 import { NextRouterAdapter, NextLinkProvider } from '@djangocfg/ui-core/adapters/nextjs';
+import { NextIntlLinkBridge } from './NextIntlLinkBridge';
 import { ThemeProvider } from '@djangocfg/ui-nextjs/theme';
 import { ThemeStyleBridge } from '../../theme/ThemeStyleBridge';
 import { ErrorBoundary } from '../../components/errors/ErrorBoundary';
@@ -158,7 +159,13 @@ export function BaseApp({
                     onMonitorCapture={(d) => FrontendMonitor.capture(errorDetailToMonitorEvent(d))}
                   >
                     <MonitorProvider {...monitorConfig} />
-                    <LayoutI18nProvider value={i18n}>{children}</LayoutI18nProvider>
+                    <LayoutI18nProvider value={i18n}>
+                      {i18n?.routing ? (
+                        <NextIntlLinkBridge routing={i18n.routing}>{children}</NextIntlLinkBridge>
+                      ) : (
+                        children
+                      )}
+                    </LayoutI18nProvider>
                     <NextTopLoader
                       color="hsl(var(--primary))"
                       height={3}

package/src/layouts/AppLayout/NextIntlLinkBridge.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+/**
+ * NextIntlLinkBridge
+ *
+ * Bridges next-intl's locale-aware `Link` (built from a `routing` object via
+ * `createNavigation()`) into our framework-agnostic `LinkProvider`. Mounted
+ * by `BaseApp` only when the consumer passes `i18n.routing`.
+ *
+ * Why this lives in @djangocfg/layouts (not @djangocfg/ui-core):
+ *   ui-core stays free of next-intl. Layouts already depend on next + nextjs
+ *   plumbing, so taking a peer on next-intl here is honest about scope and
+ *   keeps consumer apps from having to wire `createNavigation` themselves.
+ */
+
+import { forwardRef, useMemo, type ReactNode } from 'react';
+import { createNavigation } from 'next-intl/navigation';
+
+import {
+  LinkProvider,
+  type LinkComponent,
+  type LinkComponentProps,
+} from '@djangocfg/ui-core/components';
+
+import type { NextIntlRouting } from '../types/layout.types';
+
+export interface NextIntlLinkBridgeProps {
+  /** The `routing` object returned by `defineRouting()` from `next-intl/routing`. */
+  routing: NextIntlRouting;
+  children: ReactNode;
+}
+
+export function NextIntlLinkBridge({ routing, children }: NextIntlLinkBridgeProps) {
+  const adapter = useMemo<LinkComponent>(() => {
+    // The `createNavigation` overload signature splits between localized and
+    // shared routing variants and TS can't narrow either way through our
+    // opaque `NextIntlRouting` alias — cast to satisfy the localized branch
+    // and rely on next-intl to handle both at runtime.
+    const { Link: IntlLink } = createNavigation(
+      routing as unknown as Parameters<typeof createNavigation>[0],
+    );
+    return forwardRef<HTMLAnchorElement, LinkComponentProps>(
+      function NextIntlLinkAdapter(
+        { href, replace, scroll, prefetch, children: kids, ...rest },
+        ref,
+      ) {
+        // next-intl's Link accepts the same props we expose. The cast is safe
+        // because LinkComponentProps is a structural subset.
+        const Link = IntlLink as unknown as LinkComponent;
+        return (
+          <Link
+            href={href}
+            replace={replace}
+            scroll={scroll}
+            prefetch={prefetch}
+            ref={ref}
+            {...rest}
+          >
+            {kids}
+          </Link>
+        );
+      },
+    );
+  }, [routing]);
+
+  return <LinkProvider value={adapter}>{children}</LinkProvider>;
+}

package/src/layouts/PublicLayout/README.md

@@ -7,7 +7,7 @@ import { PublicLayout, FloatingNavbar, DefaultFooter } from '@djangocfg/layouts'
 
 <PublicLayout
   navbar={<FloatingNavbar config={{ brand, navigation, userMenu, actions }} />}
-  footer={<DefaultFooter config={{ variant: 'full', menus: { sections }, i18n }} />}
+  footer={<DefaultFooter config={{ variant: 'full', menus: { sections } }} />}
 >
   {children}
 </PublicLayout>
@@ -29,20 +29,11 @@ All internal anchors (navbar, footer, mobile drawer) use `<Link>` from
 `@djangocfg/ui-core/components`. In Next.js apps it renders through `next/link`
 automatically (via `NextLinkProvider`, which `BaseApp` mounts for you).
 
-For a locale-aware Link (e.g. `next-intl`'s `createNavigation().Link`), swap
-the underlying component by mounting your own `LinkProvider` from
-`@djangocfg/ui-core/components` higher in the tree:
-
-```tsx
-import { LinkProvider } from '@djangocfg/ui-core/components';
-import { Link as I18nLink } from '@/i18n/navigation';
-
-<LinkProvider value={I18nLink}>
-  <PublicLayout navbar={<FloatingNavbar config={…} />} footer={…}>
-    {children}
-  </PublicLayout>
-</LinkProvider>
-```
+For multi-locale apps (`next-intl` with `localePrefix: 'always' | 'as-needed'`)
+pass `i18n.routing` to `AppLayout` / `BaseApp`. The bridge inside `BaseApp`
+calls `createNavigation(routing)` and swaps the default `next/link` adapter
+for the locale-aware one — every navbar / footer / drawer link keeps the
+active locale prefix on click. See `@djangocfg/layouts` README → **i18n**.
 
 ## Navbar variants
 
@@ -74,8 +65,7 @@ Three variants. All share the same core props (below); only the chrome differs.
 | `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. |
-| `controls` | `{ showThemeSwitcher?; showLocaleSwitcher? }` | — | Compact theme + locale pills next to UserMenu. See below. |
-| `i18n` | `{ locale, locales, onLocaleChange }` | — | Required for the locale switcher (same shape as `DefaultFooter.i18n`). |
+| `controls` | `{ showThemeSwitcher?; showLocaleSwitcher? }` | — | Compact theme + locale pills next to UserMenu. Locale data flows from `LayoutI18nProvider` (mounted by `BaseApp`); the switcher hides itself when no provider is present. See below. |
 
 ### Variant-only
 
@@ -94,10 +84,9 @@ Three variants. All share the same core props (below); only the chrome differs.
 
 ## Theme + locale controls (navbar)
 
-All three navbars accept an optional `controls` block and `i18n` config that
-mirrors `DefaultFooter`. When enabled, a compact `NavControls` pill is rendered
-on desktop right before `UserMenu`, and an equivalent row appears in the mobile
-drawer footer.
+All three navbars accept an optional `controls` block. When enabled, a compact
+`NavControls` pill is rendered on desktop right before `UserMenu`, and an
+equivalent row appears in the mobile drawer footer.
 
 ```tsx
 <FloatingNavbar
@@ -106,7 +95,6 @@ drawer footer.
     navigation,
     userMenu: { authPath: '/auth' },
     controls: { showThemeSwitcher: true, showLocaleSwitcher: true },
-    i18n: { locale, locales, onLocaleChange: changeLocale },
   }}
 />
 ```
@@ -114,7 +102,12 @@ drawer footer.
 | Control | Required | Notes |
 |---|---|---|
 | `controls.showThemeSwitcher` | — | Light / system / dark pill (uses `useThemeContext`). |
-| `controls.showLocaleSwitcher` | `i18n` | Globe dropdown. Silently hidden when `i18n` is omitted. |
+| `controls.showLocaleSwitcher` | `LayoutI18nProvider` | Locale switcher (icon-size pill matching `UserMenu` avatar). Hidden when no provider is mounted. |
+
+Locale data (`locale`, `locales`, `onLocaleChange`) is read from
+`LayoutI18nProvider`, which `BaseApp` (and `AppLayout`) mounts automatically
+when you pass an `i18n` config. The switcher renders SVG country flags via
+`country-flag-icons` — no emoji.
 
 Same shape works for `FlushNavbar` and `MinimalNavbar`. If you build a custom
 navbar with `NavbarShell`, the controls node is pre-built and delivered to
@@ -129,7 +122,6 @@ import { NavControls } from '@djangocfg/layouts';
 <NavControls
   showThemeSwitcher
   showLocaleSwitcher
-  i18n={{ locale, locales, onLocaleChange }}
   size="compact" // 'compact' (navbar) | 'default' (footer)
 />
 ```
@@ -160,7 +152,7 @@ actions={[
 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 }} />
+<DefaultFooter config={{ variant: 'full', menus: { sections }, slots }} />
 ```
 
 | Prop (`config.*`) | Type | Default | Role |
@@ -178,9 +170,8 @@ Three variants: `full` (default) with brand column + menus + controls; `compact`
 | `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. |
+| `controls.showLocaleSwitcher` | `boolean` | `true` | Full variant only. Reads locale from `LayoutI18nProvider`; hidden when no provider is mounted. |
 | `slots.aboveMenus` | `ReactNode` | — | Above the brand/menus grid (full variant). |
 | `slots.belowMenus` | `ReactNode` | — | Between menus and bottom row. |
 | `slots.bottomStart` | `ReactNode` | — | Next to copyright. |

package/src/layouts/_components/locale-switcher/LocaleSwitcherDropdown.tsx

@@ -44,22 +44,38 @@ export function LocaleSwitcherDropdown({
 }: LocaleSwitcherDropdownProps) {
   const currentMeta = getLocaleMeta(locale, labels);
   const currentLabel = showCode ? locale.toUpperCase() : currentMeta.native;
+  const isIconOnly = size === 'icon';
 
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
-        <Button variant={variant} size={size} className={className}>
-          {showFlag ? (
-            <LanguageFlag
-              code={locale}
-              rounded
-              className={cn('h-3 w-4 shrink-0', showTriggerLabel && 'mr-1.5')}
-            />
-          ) : showIcon ? (
-            <Globe className={cn('h-4 w-4 shrink-0', showTriggerLabel && 'mr-1')} />
-          ) : null}
-          {showTriggerLabel && <span>{currentLabel}</span>}
-        </Button>
+        {isIconOnly ? (
+          <Button
+            variant={variant}
+            size={size}
+            aria-label={currentLabel}
+            className={cn('overflow-hidden rounded-full p-0', className)}
+          >
+            {showFlag ? (
+              <LanguageFlag code={locale} className="h-full w-full object-cover" />
+            ) : (
+              <Globe className="h-4 w-4" aria-hidden />
+            )}
+          </Button>
+        ) : (
+          <Button variant={variant} size={size} className={className}>
+            {showFlag ? (
+              <LanguageFlag
+                code={locale}
+                rounded
+                className={cn('h-3 w-4 shrink-0', showTriggerLabel && 'mr-1.5')}
+              />
+            ) : showIcon ? (
+              <Globe className={cn('h-4 w-4 shrink-0', showTriggerLabel && 'mr-1')} />
+            ) : null}
+            {showTriggerLabel && <span>{currentLabel}</span>}
+          </Button>
+        )}
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end">
         {locales.map((code) => {

package/src/layouts/_components/locale-switcher/LocaleSwitcherTrigger.tsx

@@ -48,6 +48,35 @@ export const LocaleSwitcherTrigger = React.forwardRef<
 ) {
   const meta = getLocaleMeta(locale, labels);
   const labelText = showCode ? locale.toUpperCase() : meta.native;
+  const isIconOnly = size === 'icon';
+
+  // Icon-only trigger: full-bleed flag inside a circular pill that lines up
+  // with neighbouring avatars / icon buttons. No padding, no inner gap.
+  if (isIconOnly) {
+    return (
+      <Button
+        ref={ref}
+        type="button"
+        variant={variant}
+        size={size}
+        onClick={onClick}
+        aria-label={ariaLabel ?? labelText}
+        className={cn(
+          'overflow-hidden rounded-full p-0',
+          className,
+        )}
+      >
+        {showFlag ? (
+          <LanguageFlag
+            code={locale}
+            className="h-full w-full object-cover"
+          />
+        ) : (
+          <Globe className="h-4 w-4" aria-hidden />
+        )}
+      </Button>
+    );
+  }
 
   return (
     <Button

package/src/layouts/types/layout.types.ts

@@ -13,6 +13,15 @@ import type { AnalyticsConfig } from '../../snippets/Analytics/types';
 import type { PwaInstallConfig } from '@djangocfg/ui-nextjs/pwa';
 import type { ErrorBoundaryConfig, ErrorTrackingConfig } from '../../components/errors/types';
 
+/**
+ * Opaque alias for the `routing` object returned by `defineRouting()` from
+ * `next-intl/routing`. Typed as `unknown` so consumer apps can pass shared
+ * (no `pathnames`) or localized routing without fighting next-intl's
+ * conditional generics. The bridge inside `BaseApp` casts it back when it
+ * calls `createNavigation(routing)`.
+ */
+export type NextIntlRouting = object & { __nextIntlRouting?: never };
+
 // Import local provider configs
 import type { ThemeConfig, SWRConfigOptions, CentrifugoConfig } from './providers.types';
 import type { MonitorConfig } from '@djangocfg/monitor';
@@ -117,6 +126,14 @@ export interface I18nLayoutConfig {
   brand?: I18nBrandConfig;
   /** Custom UI strings for the locale-switcher dialog. */
   dialogLabels?: I18nDialogLabels;
+  /**
+   * Optional `routing` object from `next-intl`'s `defineRouting()`. When
+   * passed, `BaseApp` builds a locale-aware Link adapter from it and mounts
+   * a `LinkProvider` so every `<Link>` rendered inside layouts keeps the
+   * active locale prefix on click. Without it, non-default-locale users get
+   * sent back to the default locale on every navbar / footer click.
+   */
+  routing?: NextIntlRouting;
 }
 
 // ============================================================================