@djangocfg/layouts 2.1.606 → 2.1.608

package/src/layouts/PrivateLayout/components/SidebarBody.test.tsx

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { SidebarProvider } from '@djangocfg/ui-core/components';
+
+import { PrivateLayoutProvider } from '../context';
+import { SIDEBAR_SPACING } from '../geometry';
+import { SidebarBody } from './SidebarBody';
+
+vi.mock('@djangocfg/api/auth', async () => ({
+  AuthContext: (await import('react')).createContext(undefined),
+  useAuth: () => ({ user: { email: 'a@b.c', display_username: 'Mark' } }),
+}));
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let host: HTMLElement | null = null;
+let root: Root | null = null;
+
+beforeAll(() => {
+  window.matchMedia ??= ((query: string) => ({
+    matches: false, media: query, onchange: null,
+    addEventListener: () => {}, removeEventListener: () => {}, addListener: () => {}, removeListener: () => {}, dispatchEvent: () => false,
+  })) as typeof window.matchMedia;
+});
+afterEach(() => {
+  act(() => root?.unmount());
+  host?.remove();
+  host = root = null;
+});
+
+function render(isMobile: boolean) {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  act(() =>
+    root!.render(
+      <SidebarProvider>
+        <PrivateLayoutProvider sidebar={{ groups: [{ label: 'A', items: [{ label: 'Home', href: '/' }] }] }} header={undefined} pathname="/" isMobile={isMobile}>
+          <SidebarBody />
+        </PrivateLayoutProvider>
+      </SidebarProvider>,
+    ),
+  );
+  return host;
+}
+
+describe('SidebarBody zones', () => {
+  it.each([true, false])('header and footer are pinned (shrink-0), only the nav scrolls (mobile %s)', (isMobile) => {
+    const el = render(isMobile);
+    const header = el.querySelector<HTMLElement>('[data-sidebar="header"]')!;
+    const nav = el.querySelector<HTMLElement>('[data-sidebar="content"]')!;
+    const footer = nav.nextElementSibling as HTMLElement;
+    expect(header.className).toMatch(/\bshrink-0\b/);
+    expect(header.className).toContain('bg-sidebar');
+    expect(nav.className).toMatch(/\bmin-h-0\b/);
+    expect(nav.className).toMatch(/\bflex-1\b/);
+    expect(nav.className).toMatch(/\boverflow-y-auto\b/);
+    expect(nav.className).toMatch(/\boverscroll-contain\b/);
+    expect(footer.className).toMatch(/\bshrink-0\b/);
+    expect(footer.className).toMatch(/\bborder-t\b/);
+    expect(footer.className).toContain('bg-sidebar');
+    // Nothing else in the body scrolls.
+    expect(header.className).not.toMatch(/overflow-y-auto/);
+    expect(footer.className).not.toMatch(/overflow-y-auto/);
+  });
+
+  it('mobile footer respects the home indicator', () => {
+    expect(SIDEBAR_SPACING.mobile.footer).toContain('--safe-bottom');
+  });
+});

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

@@ -17,7 +17,7 @@ import { SidebarNavGroup } from './SidebarNavGroup';
 import { SidebarSlots } from './SidebarSlots';
 
 export function SidebarBody() {
-  const { sidebar, header, isMobile } = usePrivateLayoutContext();
+  const { sidebar, header, isMobile, accountInBar } = usePrivateLayoutContext();
 
   const groups = useMemo(
     () =>
@@ -33,20 +33,29 @@ export function SidebarBody() {
     [sidebar?.groups],
   );
 
+  // Three zones: pinned header, the ONLY scroller (nav), pinned footer. The header gets a border once the nav scrolls.
+  const [scrolled, setScrolled] = React.useState(false);
+  const onScroll = React.useCallback((e: React.UIEvent<HTMLDivElement>) => {
+    const next = e.currentTarget.scrollTop > 0;
+    setScrolled((prev) => (prev === next ? prev : next));
+  }, []);
+
   return (
     <>
-      <SidebarBrand />
+      <SidebarBrand bordered={scrolled} />
       <div
         data-sidebar="content"
+        onScroll={onScroll}
         className={cn(
-          'flex min-h-0 flex-1 flex-col gap-1 overflow-y-auto overflow-x-hidden',
+          'flex min-h-0 flex-1 flex-col overflow-y-auto overflow-x-hidden overscroll-contain',
           SIDEBAR_SPACING[isMobile ? 'mobile' : 'desktop'].body,
         )}
       >
         <SidebarSlots />
         {groups}
       </div>
-      <PrivateSidebarAccount header={header} />
+      {/* On a phone the account lives in the top bar when it shows the avatar; no second entry point here. */}
+      {isMobile && accountInBar ? null : <PrivateSidebarAccount header={header} />}
     </>
   );
 }

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

@@ -7,7 +7,7 @@
 
 import React, { memo } from 'react';
 
-import { Link } from '@djangocfg/ui-core/components';
+import { Link, useSidebar } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { LucideIcon } from '../../../components';
@@ -17,41 +17,48 @@ import { PrivateSidebarTrigger } from './PrivateSidebarTrigger';
 import { SidebarBrandSwitcher } from './SidebarBrandSwitcher';
 
 const BRAND_LINK =
-  'flex min-w-0 items-center gap-2.5 rounded-lg py-1 outline-none ring-sidebar-ring focus-visible:ring-2';
+  'flex min-w-0 items-center gap-2.5 rounded-lg py-1 text-sidebar-foreground no-underline outline-none ring-sidebar-ring transition-opacity hover:no-underline hover:opacity-80 focus-visible:ring-2';
 
-function SidebarBrandRaw() {
+/** Brand name: semibold, one step larger on desktop (18px), 16px on a phone; one line, truncated. */
+const BRAND_NAME = 'truncate text-base font-semibold tracking-tight md:text-lg';
+
+function SidebarBrandRaw({ bordered = false }: { bordered?: boolean }) {
   const { header, homeHref, brandTitle, brandMonogram, isMobile } = usePrivateLayoutContext();
 
+  const { isMobile: drawer, setOpenMobile } = useSidebar();
+  // On a phone the drawer closes on click, also when the target is the current page (no pathname change).
+  const closeDrawer = React.useCallback(() => {
+    if (drawer) setOpenMobile(false);
+  }, [drawer, setOpenMobile]);
+
   const customBrand = header?.brand;
 
   const brand =
     customBrand != null && customBrand !== false ? (
       typeof customBrand === 'string' ? (
-        <Link href={homeHref} className={BRAND_LINK}>
-          <span className="truncate text-base font-medium tracking-tight">{customBrand}</span>
+        <Link href={homeHref} className={BRAND_LINK} aria-label={customBrand} onClick={closeDrawer}>
+          <span className={BRAND_NAME}>{customBrand}</span>
         </Link>
       ) : (
         customBrand
       )
     ) : (
-      <Link href={homeHref} className={BRAND_LINK}>
+      <Link href={homeHref} className={BRAND_LINK} aria-label={brandTitle || 'Home'} onClick={closeDrawer}>
         <span
           className={cn(
             'flex shrink-0 items-center justify-center rounded-lg bg-sidebar-primary',
-            isMobile ? 'size-9' : 'size-7',
+            isMobile ? 'size-7' : 'size-8',
           )}
         >
           {header?.brandIcon ? (
-            <LucideIcon icon={header.brandIcon} className="size-4 text-sidebar-primary-foreground" />
+            <LucideIcon icon={header.brandIcon} className="size-4 text-sidebar-primary-foreground md:size-[18px]" />
           ) : (
-            <span className="text-[11px] font-bold leading-none text-sidebar-primary-foreground">
+            <span className="text-xs font-bold leading-none text-sidebar-primary-foreground">
               {brandMonogram}
             </span>
           )}
         </span>
-        <span className={cn('truncate font-medium tracking-tight', isMobile ? 'text-lg' : 'text-base')}>
-          {brandTitle}
-        </span>
+        {brandTitle ? <span className={BRAND_NAME}>{brandTitle}</span> : null}
       </Link>
     );
 
@@ -62,12 +69,16 @@ function SidebarBrandRaw() {
   return (
     <div
       data-sidebar="header"
-      className={cn('flex shrink-0 items-center gap-2', SIDEBAR_SPACING[isMobile ? 'mobile' : 'desktop'].header)}
+      className={cn(
+        'flex shrink-0 items-center gap-2 bg-sidebar shadow-[0_1px_0_0_transparent] transition-shadow',
+        bordered && 'shadow-[0_1px_0_0_color-mix(in_oklab,var(--sidebar-border)_60%,transparent)]',
+        SIDEBAR_SPACING[isMobile ? 'mobile' : 'desktop'].header)}
     >
       <div className="min-w-0 flex-1">
         {header?.switcher ? <SidebarBrandSwitcher config={header.switcher} showCollapseTrigger /> : brand}
       </div>
-      {trailing}
+      {/* The desktop toggle collapses the pinned sidebar. The phone drawer has none: it closes by backdrop, swipe, Escape, or navigating. */}
+      {isMobile ? null : trailing}
     </div>
   );
 }

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

@@ -27,10 +27,15 @@ import { isSettingsItem, isSidebarGroupVisible, sidebarItemKey, visibleSidebarIt
 import type { SidebarGroupConfig } from '../types';
 import { SidebarNavItem } from './SidebarNavItem';
 
-const groupClassFor = (inset: string) =>
+const groupClassFor = (inset: string, insetRule: boolean) =>
   cn(
-    `gap-0 ${inset} py-1`,
-    '[&:not(:first-child)]:mt-1 [&:not(:first-child)]:border-t [&:not(:first-child)]:border-sidebar-border/60 [&:not(:first-child)]:pt-2',
+    // Phone drawer (insetRule): half the air between groups.
+    `gap-0 ${inset} ${insetRule ? 'py-1' : 'py-1.5'}`,
+    insetRule ? '[&:not(:first-child)]:mt-0.5 [&:not(:first-child)]:pt-1.5' : '[&:not(:first-child)]:mt-1.5 [&:not(:first-child)]:pt-3',
+    // Phone drawer: the hairline is inset to the row gutter (8px). Desktop keeps its full-width border.
+    insetRule
+      ? '[&:not(:first-child)]:before:absolute [&:not(:first-child)]:before:inset-x-2 [&:not(:first-child)]:before:top-0 [&:not(:first-child)]:before:h-px [&:not(:first-child)]:before:bg-sidebar-border/60'
+      : '[&:not(:first-child)]:border-t [&:not(:first-child)]:border-sidebar-border/60',
   );
 
 /** A `separated` group draws its own, stronger divider (below), so it drops the hairline and takes more air. */
@@ -43,13 +48,13 @@ function GroupDivider({ inset }: { inset: string }) {
       role="separator"
       aria-orientation="horizontal"
       data-sidebar="group-divider"
-      className={cn(inset, 'mb-2 mt-3 h-px shrink-0 bg-sidebar-border')}
+      className={cn(inset, 'mb-3 mt-3 h-px shrink-0 bg-sidebar-border')}
     />
   );
 }
 
 function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
-  const { isActive, geometry } = usePrivateLayoutContext();
+  const { isActive, geometry, isMobile } = usePrivateLayoutContext();
 
   const hasLabel = group.label.trim().length > 0;
   const isCollapsible = Boolean(group.collapsible) && hasLabel;
@@ -84,7 +89,7 @@ function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
   ));
   if (!visible) return null;
 
-  const groupClass = group.separated ? separatedGroupClassFor(geometry.inset) : groupClassFor(geometry.inset);
+  const groupClass = group.separated ? separatedGroupClassFor(geometry.inset) : groupClassFor(geometry.inset, isMobile);
   const divider = group.separated ? <GroupDivider inset={geometry.dividerInset} /> : null;
 
   if (isCollapsible) {
@@ -98,7 +103,7 @@ function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
                 type="button"
                 aria-expanded={open}
                 className={cn(
-                  'flex w-full items-center gap-2.5 rounded-lg font-normal text-sidebar-foreground',
+                  'flex w-full items-center rounded-lg font-normal text-sidebar-foreground',
                   'transition-colors duration-150 hover:bg-sidebar-accent/60',
                   'outline-none ring-sidebar-ring focus-visible:ring-2',
                   geometry.item,
@@ -117,7 +122,7 @@ function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
             </CollapsibleTrigger>
             <CollapsibleContent className="overflow-hidden data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down">
               <SidebarGroupContent>
-                <SidebarMenu className="mt-0.5 gap-0.5">{rows}</SidebarMenu>
+                <SidebarMenu className="mt-1 gap-0.5">{rows}</SidebarMenu>
               </SidebarGroupContent>
             </CollapsibleContent>
           </Collapsible>

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

@@ -66,7 +66,7 @@ function SidebarSettingsNavItem({ item, hideItemIcons }: { item: SidebarSettings
         onClick={open}
         aria-haspopup="dialog"
         aria-current={active ? 'true' : undefined}
-        className={cn(ITEM_CLASS, geometry.item, hideItemIcons && 'pl-8')}
+        className={cn(ITEM_CLASS, geometry.item, hideItemIcons && geometry.indent)}
       >
         <ItemContent item={item} hideItemIcons={hideItemIcons} />
       </SidebarMenuButton>
@@ -83,7 +83,7 @@ function SidebarLinkNavItem({ item, hideItemIcons }: { item: SidebarLinkItem; hi
       <SidebarMenuButton
         asChild
         isActive={active}
-        className={cn(ITEM_CLASS, geometry.item, hideItemIcons && 'pl-8')}
+        className={cn(ITEM_CLASS, geometry.item, hideItemIcons && geometry.indent)}
       >
         <Link href={item.href} aria-current={active ? 'page' : undefined}>
           <ItemContent item={item} hideItemIcons={hideItemIcons} />

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

@@ -1,6 +1,6 @@
 /**
  * Peek panel: the full sidebar floated over the page while it is collapsed.
- * Opened by hover intent on the left edge (or the trigger zone), held by `SidebarPeekProvider`,
+ * Opened by hover intent on the left screen edge strip (the toggle button itself does not open it), held by `SidebarPeekProvider`,
  * slides in and out (it stays mounted while the exit animation runs).
  */
 

package/src/layouts/PrivateLayout/context.tsx

@@ -7,6 +7,8 @@
 
 'use client';
 
+import { useLandingRoute } from './hooks/useLandingRoute';
+import { useProjectName } from '../../shared/ProjectContext';
 import React, { createContext, useContext, useMemo } from 'react';
 
 import { NAV_GEOMETRY } from './geometry';
@@ -19,6 +21,8 @@ export interface PrivateLayoutContextValue {
   header: HeaderConfig | undefined;
   pathname: string;
   isMobile: boolean;
+  /** The top bar carries the account avatar, so the phone drawer drops its footer account (one entry point). */
+  accountInBar: boolean;
   geometry: NavGeometry;
   /** The route rows; Settings launchers have no route and take no part in the active-route check. */
   allItems: SidebarLinkItem[];
@@ -44,6 +48,7 @@ interface PrivateLayoutProviderProps {
   header: HeaderConfig | undefined;
   pathname: string;
   isMobile: boolean;
+  accountInBar?: boolean;
 }
 
 export function PrivateLayoutProvider({
@@ -52,9 +57,15 @@ export function PrivateLayoutProvider({
   header,
   pathname,
   isMobile,
+  accountInBar = false,
 }: PrivateLayoutProviderProps) {
-  const homeHref = sidebar?.homeHref || '/';
-  const brandTitle = header?.title?.trim() || 'Dashboard';
+  // header.href > sidebar.homeHref > the private landing route AppLayout/BaseApp configures (`auth.routes.defaultCallback`,
+  // resolved by the auth provider; `undefined` outside it) > '/'.
+  const landing = useLandingRoute();
+  const homeHref = header?.href || sidebar?.homeHref || landing || '/';
+  // header.title > the project name from BaseApp > nothing (monogram only).
+  const projectName = useProjectName();
+  const brandTitle = header?.title?.trim() || projectName || '';
   const brandMonogram = (
     header?.brandLetter?.trim().charAt(0) ||
     brandTitle.charAt(0) ||
@@ -87,6 +98,7 @@ export function PrivateLayoutProvider({
       header,
       pathname,
       isMobile,
+      accountInBar,
       geometry: isMobile ? NAV_GEOMETRY.mobile : NAV_GEOMETRY.desktop,
       allItems,
       isActive,
@@ -94,7 +106,7 @@ export function PrivateLayoutProvider({
       brandTitle,
       brandMonogram,
     }),
-    [sidebar, header, pathname, isMobile, allItems, isActive, homeHref, brandTitle, brandMonogram],
+    [sidebar, header, pathname, isMobile, accountInBar, allItems, isActive, homeHref, brandTitle, brandMonogram],
   );
 
   return <PrivateLayoutContext.Provider value={value}>{children}</PrivateLayoutContext.Provider>;

package/src/layouts/PrivateLayout/geometry.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+
+import { NAV_GEOMETRY, SHELL_CLASS, SIDEBAR_SPACING } from './geometry';
+
+const SIZES = /\btext-(base|lg|xl|2xl)\b/;
+
+describe('sidebar geometry', () => {
+  for (const form of ['desktop', 'mobile'] as const) {
+    it(`${form}: rows use 14px text and a 16-20px icon, not a large font`, () => {
+      expect(NAV_GEOMETRY[form].item).toMatch(/\btext-sm\b/);
+      expect(NAV_GEOMETRY[form].item).not.toMatch(SIZES);
+      expect(NAV_GEOMETRY[form].item).toMatch(/\[&>svg\]:size-(4|5)/);
+      expect(NAV_GEOMETRY[form].label).toMatch(/\btext-xs\b/);
+    });
+
+    it(`${form}: horizontal inset is tight (8px), vertical body padding is roomier`, () => {
+      expect(NAV_GEOMETRY[form].inset).toBe('px-2');
+      expect(NAV_GEOMETRY[form].item).toMatch(form === 'mobile' ? /\bpx-2\.5\b/ : /\bpx-2\b/);
+      expect(SIDEBAR_SPACING[form].body).toMatch(form === 'mobile' ? /\bpy-2\b/ : /\bpy-3\b/);
+    });
+  }
+
+  it('mobile rows are 40px with a 44px hit area (see touch-safe.css); desktop rows are 36px', () => {
+    expect(NAV_GEOMETRY.mobile.item).toMatch(/\bh-10\b/);
+    expect(NAV_GEOMETRY.desktop.item).toMatch(/\bh-9\b/);
+  });
+
+  it('mobile header and footer never go under the status bar or home indicator', () => {
+    expect(SIDEBAR_SPACING.mobile.header).toContain('env(safe-area-inset-top');
+    expect(SIDEBAR_SPACING.mobile.footer).toContain('env(safe-area-inset-bottom');
+  });
+
+  it('the shell is one dynamic viewport tall and clips, so the document never scrolls', () => {
+    expect(SHELL_CLASS).toContain('h-[var(--app-height,100dvh)]');
+    expect(SHELL_CLASS).toContain('overflow-hidden');
+    expect(SHELL_CLASS).toContain('min-h-0');
+    expect(SHELL_CLASS).not.toMatch(/min-h-(screen|svh)/);
+  });
+
+  it('mobile header and footer also respect the side safe areas (landscape notch)', () => {
+    expect(SIDEBAR_SPACING.mobile.header).toContain('env(safe-area-inset-left');
+    expect(SIDEBAR_SPACING.mobile.footer).toContain('env(safe-area-inset-right');
+  });
+});

package/src/layouts/PrivateLayout/geometry.ts

@@ -1,21 +1,26 @@
 /**
- * Sidebar geometry. Row sizes (a pointer-sized desktop row, a 44px touch row for the mobile
- * drawer), one horizontal inset shared by every block, one trigger size, and the motion timing.
+ * Sidebar geometry. Row sizes (a pointer-sized 36px desktop row, a 40px row for the mobile
+ * drawer, whose 44px hit area comes from an invisible ::after in ui-core touch-safe.css), one horizontal inset shared by every block, one trigger size, and the motion timing.
  */
 
 export const NAV_GEOMETRY = {
   desktop: {
-    item: 'h-8 gap-2.5 px-2.5 text-base [&>svg]:size-4',
-    label: 'h-7 px-2.5 text-xs',
+    item: 'h-9 gap-2.5 px-2 text-sm [&>svg]:size-4',
+    label: 'h-7 px-2 text-xs',
     /** Horizontal inset of groups, slots and the divider; equals the header and footer inset. */
     inset: 'px-2',
     dividerInset: 'mx-2',
+    /** Left padding of a row without an icon, so its text lines up with the text of rows that have one (8 + 16 + 10px). */
+    indent: 'pl-[34px]',
   },
   mobile: {
-    item: 'h-11 gap-3 px-3 text-lg [&>svg]:size-5',
-    label: 'h-8 px-3 text-sm',
-    inset: 'px-3',
-    dividerInset: 'mx-3',
+    item: 'h-10 gap-2.5 px-2.5 text-sm [&>svg]:size-5',
+    label: 'h-7 px-2.5 text-xs',
+    /** One 8px gutter for rows, dividers, header and footer; rows add 10px, so the icon column (and the logo) sit at 18px. */
+    inset: 'px-2',
+    dividerInset: 'mx-2',
+    /** 10 + 20 + 10px. */
+    indent: 'pl-[40px]',
   },
 } as const;
 
@@ -23,22 +28,33 @@ export type NavGeometry = (typeof NAV_GEOMETRY)[keyof typeof NAV_GEOMETRY];
 
 /**
  * One spacing scale for the three blocks of the sidebar (header, list, footer). On mobile every
- * block uses the same 0.75rem unit on the sides and the safe-area aware edge; the list gives
- * 0.5rem between blocks.
+ * block keeps tight sides (0.5rem rows, 0.75rem header) and roomier verticals, with the top and
+ * bottom edges safe-area aware (never less than 1rem).
  */
 export const SIDEBAR_SPACING = {
   desktop: {
-    header: 'px-3 pb-1 pt-3',
-    body: 'py-2',
-    footer: 'p-2 pb-[max(0.5rem,env(safe-area-inset-bottom,0px))]',
+    header: 'pl-4 pr-2 pb-2 pt-3',
+    body: 'gap-1 py-3',
+    footer: 'px-2 pt-2 pb-[max(0.5rem,var(--safe-bottom,env(safe-area-inset-bottom,0px)))]',
   },
   mobile: {
-    header: 'px-3 pb-2 pt-[max(0.75rem,env(safe-area-inset-top,0px))]',
-    body: 'py-2',
-    footer: 'p-3 pb-[max(0.75rem,env(safe-area-inset-bottom,0px))]',
+    // The same row height as the top bar: 48px under the safe-top inset, the brand vertically centred, its left edge on the
+    // nav icon column (18px). No toggle: the drawer closes by backdrop, swipe, Escape or navigation.
+    header:
+      'box-border h-[calc(var(--safe-top,env(safe-area-inset-top,0px))+3rem)] pt-[var(--safe-top,env(safe-area-inset-top,0px))] pl-[calc(var(--safe-left,env(safe-area-inset-left,0px))+1.125rem)] pr-[calc(var(--safe-right,env(safe-area-inset-right,0px))+0.75rem)]',
+    body: 'gap-1 py-2',
+    footer:
+      'pt-2 pb-[max(0.5rem,var(--safe-bottom,env(safe-area-inset-bottom,0px)))] pl-[max(0.5rem,var(--safe-left,env(safe-area-inset-left,0px)))] pr-[max(0.5rem,var(--safe-right,env(safe-area-inset-right,0px)))]',
   },
 } as const;
 
+/**
+ * The private app shell is exactly one dynamic viewport tall and clips, so the DOCUMENT never scrolls: the top bar
+ * is `shrink-0`, the content below it is `flex-1 min-h-0` and owns the scroll (see `PrivateContent`).
+ * (`SidebarProvider` defaults to `min-h-svh`, which let content grow the page past the viewport.)
+ */
+export const SHELL_CLASS = 'h-[var(--app-height,100dvh)] max-h-[var(--app-height,100dvh)] min-h-0 overflow-hidden';
+
 /** The one trigger button: same box and icon size on mobile and desktop. */
 export const TRIGGER_CLASS = 'size-10 shrink-0 [&_svg]:!size-5';
 
@@ -48,3 +64,11 @@ export const SIDEBAR_MOTION_MS = 180;
 /** Desktop hover-open timing: intent delay before opening, grace before closing. */
 export const HOVER_OPEN_DELAY_MS = 400;
 export const HOVER_CLOSE_DELAY_MS = 250;
+
+/**
+ * Fixed-height top bar: safe-top + 3rem. `--layout-bar-height` is set on the layout's main column to this value whenever
+ * the bar is shown (always on a phone; on desktop while the sidebar is collapsed) and to `0px` when it is not (desktop
+ * with the sidebar docked, or no sidebar); content starts right under the bar, pages need to know nothing about it.
+ * Apps may use it to offset their own sticky elements.
+ */
+export const LAYOUT_BAR_HEIGHT = 'calc(var(--safe-top, env(safe-area-inset-top, 0px)) + 3rem)';

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

@@ -0,0 +1,16 @@
+/**
+ * The private landing route AppLayout/BaseApp configures: `auth.routes.defaultCallback`, resolved by the auth
+ * provider (default `/private`). Returns `undefined` outside the provider, so stories and tests fall back to `/`.
+ * Reads the context directly: `useAuth()` returns default state outside the provider, which would leak the
+ * framework default.
+ */
+
+'use client';
+
+import { useContext } from 'react';
+
+import { AuthContext } from '@djangocfg/api/auth';
+
+export function useLandingRoute(): string | undefined {
+  return useContext(AuthContext)?.routes?.defaultCallback || undefined;
+}

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

@@ -27,7 +27,7 @@ export function resolveProviderStyle(
  * extract these classes at build time.
  */
 const BOXED_INSET_CLASS = [
-  'flex flex-col',
+  'flex min-h-0 min-w-0 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)]',
@@ -47,7 +47,7 @@ const BOXED_RADIUS_REM: Record<NonNullable<LayoutVisualConfig['radius']>, string
 };
 
 export function resolveInsetClassName(visual: LayoutVisualConfig | undefined): string {
-  if ((visual?.variant ?? 'full-bleed') !== 'boxed') return 'flex flex-col';
+  if ((visual?.variant ?? 'full-bleed') !== 'boxed') return 'flex min-h-0 min-w-0 flex-col';
   const border = visual?.border ?? true;
   return border ? `${BOXED_INSET_CLASS} ${BOXED_INSET_BORDER_CLASS}` : BOXED_INSET_CLASS;
 }

package/src/layouts/PrivateLayout/hooks/useSidebarPeek.tsx

@@ -18,7 +18,7 @@ import { usePresence } from './usePresence';
 type PointerHandlers = ReturnType<typeof useHoverIntent>['zoneProps'];
 
 export interface SidebarPeek extends Presence {
-  /** True while the sidebar is collapsed on desktop: the trigger zone shows. */
+  /** True while the sidebar is collapsed on desktop: the left-edge hot zone is mounted. */
   enabled: boolean;
   /** Hover-open is live: collapsed, desktop, and a fine (mouse/pen) pointer. */
   hoverEnabled: boolean;

package/src/layouts/PrivateLayout/index.ts

@@ -4,6 +4,7 @@
 
 export { PrivateLayout } from './PrivateLayout';
 export { PrivateLayoutProvider, usePrivateLayoutContext } from './context';
+export { LAYOUT_BAR_HEIGHT } from './geometry';
 export { mcpSidebarItem, mcpSidebarGroup } from './mcpSidebar';
 export type { McpSidebarItemOptions, McpSidebarGroupOptions } from './mcpSidebar';
 export { SidebarBrandSwitcher, ForbiddenState } from './components';
@@ -21,4 +22,5 @@ export type {
   SidebarFeaturedConfig,
   SidebarBrandSwitcherConfig,
   SidebarBrandSwitcherItem,
+  PrivateTopBarConfig,
 } from './types';