@djangocfg/layouts 2.1.300 → 2.1.302

package/README.md

@@ -88,11 +88,35 @@ 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. |
-| **`PrivateLayout`** | App shell — sidebar + header. |
+| **`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. |
 | **`ProfileLayout`** | Profile page — avatar, editable fields, 2FA, tabs, slots (see below). |
 
+### `PrivateLayout` visual variants
+
+```tsx
+<PrivateLayout
+  sidebar={sidebar}
+  header={header}
+  visual={{ variant: 'boxed', inset: 12, radius: '2xl', border: true }}
+>
+  {children}
+</PrivateLayout>
+```
+
+`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.
+`full-bleed` — content stretches edge-to-edge next to the sidebar (legacy look). Opt in with `visual={{ variant: 'full-bleed' }}`.
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `variant` | `'full-bleed' \| 'boxed'` | `'boxed'` | Switch between the two shells. |
+| `inset` | `number \| { x?: number; y?: number }` | `12` | Gap (px) between the card and the viewport edges (md+). |
+| `radius` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'` | `'2xl'` | Card corner radius. |
+| `background` | `'sidebar' \| 'muted' \| 'card' \| 'background'` | `'sidebar'` | Canvas colour painted *behind* the boxed card. |
+| `border` | `boolean` | `true` | 1px border on the card. |
+| `maxWidth` | `'none' \| '7xl' \| 'screen-xl' \| 'screen-2xl'` | `'none'` | Optional inner content width cap. |
+
 ### `ProfileLayout`
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.300",
+  "version": "2.1.302",
   "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.300",
-    "@djangocfg/centrifugo": "^2.1.300",
-    "@djangocfg/debuger": "^2.1.300",
-    "@djangocfg/i18n": "^2.1.300",
-    "@djangocfg/monitor": "^2.1.300",
-    "@djangocfg/ui-core": "^2.1.300",
-    "@djangocfg/ui-nextjs": "^2.1.300",
-    "@djangocfg/ui-tools": "^2.1.300",
+    "@djangocfg/api": "^2.1.302",
+    "@djangocfg/centrifugo": "^2.1.302",
+    "@djangocfg/debuger": "^2.1.302",
+    "@djangocfg/i18n": "^2.1.302",
+    "@djangocfg/monitor": "^2.1.302",
+    "@djangocfg/ui-core": "^2.1.302",
+    "@djangocfg/ui-nextjs": "^2.1.302",
+    "@djangocfg/ui-tools": "^2.1.302",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -110,15 +110,15 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.300",
-    "@djangocfg/centrifugo": "^2.1.300",
-    "@djangocfg/debuger": "^2.1.300",
-    "@djangocfg/i18n": "^2.1.300",
-    "@djangocfg/monitor": "^2.1.300",
-    "@djangocfg/typescript-config": "^2.1.300",
-    "@djangocfg/ui-core": "^2.1.300",
-    "@djangocfg/ui-nextjs": "^2.1.300",
-    "@djangocfg/ui-tools": "^2.1.300",
+    "@djangocfg/api": "^2.1.302",
+    "@djangocfg/centrifugo": "^2.1.302",
+    "@djangocfg/debuger": "^2.1.302",
+    "@djangocfg/i18n": "^2.1.302",
+    "@djangocfg/monitor": "^2.1.302",
+    "@djangocfg/typescript-config": "^2.1.302",
+    "@djangocfg/ui-core": "^2.1.302",
+    "@djangocfg/ui-nextjs": "^2.1.302",
+    "@djangocfg/ui-tools": "^2.1.302",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -16,7 +16,7 @@ import { Preloader } from '@djangocfg/ui-core/components';
 import { SidebarInset, SidebarProvider } from '@djangocfg/ui-nextjs/components';
 
 import type { AppLayoutPublicChrome } from '../AppLayout/AppLayout';
-import type { I18nLayoutConfig } from '../types';
+import type { I18nLayoutConfig, LayoutVisualConfig } from '../types';
 import { UserMenuConfig } from '../types';
 import { PrivateContent, PrivateSidebar } from './components';
 
@@ -55,6 +55,14 @@ export interface SidebarConfig {
    * (above `footer` + account block).
    */
   menuEnd?: ReactNode;
+  /**
+   * Keep `menuStart` visible when the desktop sidebar is collapsed to the
+   * icon rail. Default `false` — most slot content is full-width and looks
+   * broken at ~56px. Set `true` only when the slot renders well in compact mode.
+   */
+  menuStartShowOnCollapsed?: boolean;
+  /** Same as `menuStartShowOnCollapsed`, but for `menuEnd`. Default `false`. */
+  menuEndShowOnCollapsed?: boolean;
   /** Custom footer component rendered at the bottom of the sidebar */
   footer?: ReactNode;
 }
@@ -95,6 +103,17 @@ export interface PrivateLayoutProps {
   contentPadding?: 'none' | 'default';
   /** i18n configuration for locale switching */
   i18n?: I18nLayoutConfig;
+  /**
+   * Visual style of the shell. Defaults to `'boxed'` (inset rounded card on a
+   * sidebar-coloured canvas). Pass `{ variant: 'full-bleed' }` for the legacy
+   * edge-to-edge layout.
+   */
+  visual?: LayoutVisualConfig;
+  /**
+   * Skip the built-in auth guard. Useful for static showcases / playground
+   * embeds where there's no real session. Default `true` (guard on).
+   */
+  requireAuth?: boolean;
   /** Reserved for `AppLayout` passthrough (`publicChrome`); unused in this layout. */
   publicChrome?: AppLayoutPublicChrome;
 }
@@ -106,21 +125,24 @@ export function PrivateLayout({
   pathname,
   contentPadding = 'default',
   i18n,
+  visual,
+  requireAuth = true,
 }: PrivateLayoutProps) {
   const { isAuthenticated, isLoading, saveRedirectUrl } = useAuth();
   const router = useRouter();
   const [isRedirecting, setIsRedirecting] = useState(false);
 
   useEffect(() => {
+    if (!requireAuth) return;
     if (!isLoading && !isAuthenticated && !isRedirecting) {
       const currentUrl = window.location.pathname + window.location.search;
       saveRedirectUrl(currentUrl);
       setIsRedirecting(true);
       router.push(header?.authPath || '/auth');
     }
-  }, [isAuthenticated, isLoading, isRedirecting, router, saveRedirectUrl, header?.authPath]);
+  }, [requireAuth, isAuthenticated, isLoading, isRedirecting, router, saveRedirectUrl, header?.authPath]);
 
-  if (isLoading || isRedirecting || !isAuthenticated) {
+  if (requireAuth && (isLoading || isRedirecting || !isAuthenticated)) {
     return (
       <Preloader
         variant="fullscreen"
@@ -132,17 +154,105 @@ export function PrivateLayout({
     );
   }
 
+  const variant: LayoutVisualConfig['variant'] = visual?.variant ?? 'boxed';
+  const sidebarVariant = variant === 'boxed' ? 'inset' : 'sidebar';
+
   return (
-    <SidebarProvider defaultOpen={true}>
+    <SidebarProvider
+      defaultOpen={true}
+      style={resolveProviderStyle(visual)}
+      className={resolveProviderClassName(visual)}
+    >
       {sidebar && (
-        <PrivateSidebar sidebar={sidebar} header={header} i18n={i18n} pathname={pathname} />
+        <PrivateSidebar
+          sidebar={sidebar}
+          header={header}
+          i18n={i18n}
+          pathname={pathname}
+          variant={sidebarVariant}
+        />
       )}
 
-      <SidebarInset className="flex flex-col">
-        <PrivateContent padding={contentPadding} hasSidebar={Boolean(sidebar)}>
+      <SidebarInset className={resolveInsetClassName(visual)}>
+        <PrivateContent
+          padding={contentPadding}
+          hasSidebar={Boolean(sidebar)}
+          visual={visual}
+        >
           {children}
         </PrivateContent>
       </SidebarInset>
     </SidebarProvider>
   );
 }
+
+/** CSS variables consumed by the boxed `SidebarInset` (margin + radius). */
+function resolveProviderStyle(visual: LayoutVisualConfig | undefined): React.CSSProperties | undefined {
+  if ((visual?.variant ?? 'boxed') !== 'boxed') return undefined;
+  const inset = normaliseInset(visual?.inset);
+  return {
+    ['--app-shell-inset-x' as string]: `${inset.x}px`,
+    ['--app-shell-inset-y' as string]: `${inset.y}px`,
+    ['--app-shell-radius' as string]: BOXED_RADIUS_REM[visual?.radius ?? '2xl'],
+  };
+}
+
+/**
+ * Statically-known Tailwind classes for the boxed inset. Margin and radius are
+ * driven by the CSS variables set in `resolveProviderStyle`, so JIT can fully
+ * extract these classes at build time.
+ */
+const BOXED_INSET_CLASS = [
+  'flex flex-col',
+  'md:peer-data-[variant=inset]:my-[var(--app-shell-inset-y)]',
+  'md:peer-data-[variant=inset]:mr-[var(--app-shell-inset-x)]',
+  'md:peer-data-[variant=inset]:rounded-[var(--app-shell-radius)]',
+  'md:peer-data-[variant=inset]:overflow-hidden',
+].join(' ');
+
+const BOXED_INSET_BORDER_CLASS =
+  'md:peer-data-[variant=inset]:border md:peer-data-[variant=inset]:border-border/60';
+
+const BOXED_RADIUS_REM: Record<NonNullable<LayoutVisualConfig['radius']>, string> = {
+  sm: '0.375rem',
+  md: '0.5rem',
+  lg: '0.75rem',
+  xl: '1rem',
+  '2xl': '1.25rem',
+  '3xl': '1.75rem',
+};
+
+function resolveInsetClassName(visual: LayoutVisualConfig | undefined): string {
+  if ((visual?.variant ?? 'boxed') !== 'boxed') return 'flex flex-col';
+  const border = visual?.border ?? true;
+  return border ? `${BOXED_INSET_CLASS} ${BOXED_INSET_BORDER_CLASS}` : BOXED_INSET_CLASS;
+}
+
+/**
+ * Background painted *behind* the boxed container on md+. On mobile the
+ * canvas tint is dropped because the sidebar is a Drawer — leaking the
+ * canvas colour to the whole viewport just makes the page look dim.
+ *
+ * `bg-sidebar` (the default) overrides shadcn-sidebar's built-in
+ * `has-[&_[data-variant=inset]]:bg-sidebar` only at the breakpoint where
+ * the inset shape actually exists.
+ */
+const BOXED_BG_CLASS: Record<NonNullable<LayoutVisualConfig['background']>, string> = {
+  sidebar: 'md:!bg-sidebar',
+  muted: 'md:!bg-muted',
+  card: 'md:!bg-card',
+  background: 'md:!bg-background',
+};
+
+function resolveProviderClassName(visual: LayoutVisualConfig | undefined): string | undefined {
+  if ((visual?.variant ?? 'boxed') !== 'boxed') return undefined;
+  // `max-md:!bg-background` neutralises shadcn-sidebar's built-in
+  // `has-[[data-variant=inset]]:bg-sidebar` below md so the mobile Drawer shell
+  // doesn't paint the whole viewport with the canvas tint.
+  return `max-md:!bg-background ${BOXED_BG_CLASS[visual?.background ?? 'sidebar']}`;
+}
+
+function normaliseInset(inset: LayoutVisualConfig['inset']): { x: number; y: number } {
+  if (typeof inset === 'number') return { x: inset, y: inset };
+  return { x: inset?.x ?? 12, y: inset?.y ?? 12 };
+}

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

@@ -10,17 +10,29 @@ import React, { ReactNode } from 'react';
 import { SidebarTrigger, useSidebar } from '@djangocfg/ui-nextjs/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
+import type { LayoutVisualConfig } from '../../types';
+
 interface PrivateContentProps {
   children: ReactNode;
   padding?: 'none' | 'default';
   /** When false, no mobile hamburger (e.g. layout without a sidebar). Default true. */
   hasSidebar?: boolean;
+  /** Visual config from PrivateLayout — controls maxWidth in boxed mode. */
+  visual?: LayoutVisualConfig;
 }
 
+const MAX_WIDTH_CLASS: Record<NonNullable<LayoutVisualConfig['maxWidth']>, string> = {
+  none: '',
+  '7xl': 'mx-auto w-full max-w-7xl',
+  'screen-xl': 'mx-auto w-full max-w-screen-xl',
+  'screen-2xl': 'mx-auto w-full max-w-screen-2xl',
+};
+
 export function PrivateContent({
   children,
   padding = 'default',
   hasSidebar = true,
+  visual,
 }: PrivateContentProps) {
   const { isMobile, openMobile } = useSidebar();
 
@@ -66,10 +78,14 @@ export function PrivateContent({
     />
   ) : null;
 
+  const innerWidthClass = MAX_WIDTH_CLASS[visual?.maxWidth ?? 'none'];
+
   return (
     <div className="flex min-h-0 min-w-0 flex-1 flex-col">
       {mobileMenuFab}
-      <div className={scrollAreaClass}>{children}</div>
+      <div className={scrollAreaClass}>
+        {innerWidthClass ? <div className={innerWidthClass}>{children}</div> : children}
+      </div>
     </div>
   );
 }

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

@@ -101,12 +101,18 @@ interface PrivateSidebarProps {
   header?: HeaderConfig;
   i18n?: I18nLayoutConfig;
   pathname?: string;
+  /**
+   * shadcn-sidebar `variant`. Used to trigger the inset/boxed visual:
+   * `'inset'` makes the sidebar wrapper paint `bg-sidebar` and lets `SidebarInset`
+   * float as a rounded card. Default `'sidebar'` (full-bleed).
+   */
+  variant?: 'sidebar' | 'inset';
 }
 
-export function PrivateSidebar({ sidebar, header, i18n, pathname: pathnameProp }: PrivateSidebarProps) {
+export function PrivateSidebar({ sidebar, header, i18n, pathname: pathnameProp, variant = 'sidebar' }: PrivateSidebarProps) {
   const pathnameFromNext = useNextPathname();
   const pathname = pathnameProp ?? pathnameFromNext;
-  const { state, isMobile, setOpenMobile } = useSidebar();
+  const { state, isMobile, setOpen, setOpenMobile } = useSidebar();
   const homeHref = sidebar.homeHref || '/';
 
   React.useEffect(() => {
@@ -151,8 +157,15 @@ export function PrivateSidebar({ sidebar, header, i18n, pathname: pathnameProp }
     </span>
   );
 
-  const showMenuStart = sidebar.menuStart != null && sidebar.menuStart !== false;
-  const showMenuEnd = sidebar.menuEnd != null && sidebar.menuEnd !== false;
+  const hasMenuStart = sidebar.menuStart != null && sidebar.menuStart !== false;
+  const hasMenuEnd = sidebar.menuEnd != null && sidebar.menuEnd !== false;
+  // Hide slots on the desktop icon rail unless the consumer opted in. Mobile
+  // drawer always shows them — there's no rail in the drawer to begin with.
+  const collapsedRail = !isMobile && state === 'collapsed';
+  const showMenuStart =
+    hasMenuStart && (!collapsedRail || sidebar.menuStartShowOnCollapsed === true);
+  const showMenuEnd =
+    hasMenuEnd && (!collapsedRail || sidebar.menuEndShowOnCollapsed === true);
   const menuStartSlot = showMenuStart ? (
     <div className="w-full min-w-0 shrink-0 px-2">{sidebar.menuStart}</div>
   ) : null;
@@ -274,8 +287,33 @@ export function PrivateSidebar({ sidebar, header, i18n, pathname: pathnameProp }
       : 'px-2 pt-3.5',
   );
 
+  /**
+   * Click on the collapsed icon-rail expands the sidebar — but only on empty
+   * areas. Native interactive elements (nav links, the trigger, account menu,
+   * tooltips) keep their original behaviour: we bail out as soon as the click
+   * target sits inside a `button`, `a`, or anything explicitly marked
+   * non-expandable via `data-no-expand`.
+   */
+  const expandOnRailClick = !isMobile && state === 'collapsed'
+    ? (event: React.MouseEvent<HTMLDivElement>) => {
+        const interactive = (event.target as Element | null)?.closest(
+          'a, button, [role="menuitem"], [data-no-expand]',
+        );
+        if (interactive) return;
+        setOpen(true);
+      }
+    : undefined;
+
+  const railExpandHintClass =
+    !isMobile && state === 'collapsed' ? 'cursor-pointer' : undefined;
+
   return (
-    <Sidebar collapsible="icon">
+    <Sidebar
+      collapsible="icon"
+      variant={variant}
+      className={railExpandHintClass}
+      onClick={expandOnRailClick}
+    >
       <SidebarHeader className={sidebarHeaderClass}>{sidebarHeaderContent}</SidebarHeader>
 
       <SidebarContent className={sidebarContentClass}>

package/src/layouts/types/index.ts

@@ -52,4 +52,12 @@ export type {
 // Layout Types
 // ============================================================================
 
-export type { BaseLayoutProps, DebugConfig, I18nLayoutConfig } from './layout.types';
+export type {
+  BaseLayoutProps,
+  DebugConfig,
+  I18nLayoutConfig,
+  LayoutVisualVariant,
+  LayoutVisualConfig,
+  LayoutBoxedRadius,
+  LayoutBoxedBackground,
+} from './layout.types';

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

@@ -83,3 +83,49 @@ export interface I18nLayoutConfig {
   onLocaleChange: (locale: string) => void;
 }
 
+// ============================================================================
+// Layout Visual Variant
+// ============================================================================
+
+/**
+ * Visual style of the private/app shell.
+ * - `boxed` (default) — content lives in a fixed, rounded card inset from the
+ *   viewport edges while the sidebar-coloured background bleeds to the screen
+ *   border. Internal scroll inside the card; mobile (<md) falls back to
+ *   `full-bleed` automatically.
+ * - `full-bleed` — content stretches edge-to-edge next to the sidebar (legacy look).
+ */
+export type LayoutVisualVariant = 'full-bleed' | 'boxed';
+
+/** Border radius preset for the boxed container. */
+export type LayoutBoxedRadius = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+/** Background token used for the area *behind* the boxed container. */
+export type LayoutBoxedBackground = 'sidebar' | 'muted' | 'card' | 'background';
+
+/**
+ * Visual config for the private layout shell.
+ * All `boxed`-only options are ignored when `variant === 'full-bleed'`.
+ */
+export interface LayoutVisualConfig {
+  /** Visual variant. Default: `'boxed'`. */
+  variant?: LayoutVisualVariant;
+  /**
+   * Inset (px) between the boxed container and the viewport edges on desktop.
+   * Either a single value (applied to all sides next to the sidebar) or per-axis.
+   * Default: `12`.
+   */
+  inset?: number | { x?: number; y?: number };
+  /** Border radius preset of the boxed container. Default: `'2xl'`. */
+  radius?: LayoutBoxedRadius;
+  /** Background colour token shown *behind* the boxed container. Default: `'sidebar'`. */
+  background?: LayoutBoxedBackground;
+  /** Whether to render a 1px border on the boxed container. Default: `true`. */
+  border?: boolean;
+  /**
+   * Optional max width for the inner scrollable area (Tailwind size token).
+   * Default: `'none'` (fills available width minus inset).
+   */
+  maxWidth?: 'none' | 'screen-xl' | 'screen-2xl' | '7xl';
+}
+