@djangocfg/layouts 2.1.607 → 2.1.609

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.5`,
-    '[&:not(:first-child)]:mt-1.5 [&:not(:first-child)]:border-t [&:not(:first-child)]:border-sidebar-border/60 [&:not(:first-child)]:pt-3',
+    // 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. */
@@ -49,7 +54,7 @@ function GroupDivider({ inset }: { inset: string }) {
 }
 
 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) {

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

@@ -1,27 +1,27 @@
 import { describe, expect, it } from 'vitest';
 
-import { NAV_GEOMETRY, SIDEBAR_SPACING } from './geometry';
+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-18px icon, not a large font`, () => {
+    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|\[18px\])/);
+      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(/\bpx-2\b/);
-      expect(SIDEBAR_SPACING[form].body).toMatch(/\bpy-3\b/);
+      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 keep a 44px touch target; desktop rows are 36px', () => {
-    expect(NAV_GEOMETRY.mobile.item).toMatch(/\bh-11\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/);
   });
 
@@ -29,4 +29,16 @@ describe('sidebar geometry', () => {
     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,6 +1,6 @@
 /**
- * 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 = {
@@ -14,12 +14,13 @@ export const NAV_GEOMETRY = {
     indent: 'pl-[34px]',
   },
   mobile: {
-    item: 'h-11 gap-2.5 px-2 text-sm [&>svg]:size-[18px]',
-    label: 'h-8 px-2 text-xs',
+    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',
-    /** 8 + 18 + 10px. */
-    indent: 'pl-9',
+    /** 10 + 20 + 10px. */
+    indent: 'pl-[40px]',
   },
 } as const;
 
@@ -34,15 +35,26 @@ export const SIDEBAR_SPACING = {
   desktop: {
     header: 'pl-4 pr-2 pb-2 pt-3',
     body: 'gap-1 py-3',
-    footer: 'px-2 pt-2 pb-[max(0.5rem,env(safe-area-inset-bottom,0px))]',
+    footer: 'px-2 pt-2 pb-[max(0.5rem,var(--safe-bottom,env(safe-area-inset-bottom,0px)))]',
   },
   mobile: {
-    header: 'pl-4 pr-2 pb-3 pt-[max(1rem,env(safe-area-inset-top,0px))]',
-    body: 'gap-1 py-3',
-    footer: 'px-2 pt-3 pb-[max(1rem,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';
 
@@ -52,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;
 }
@@ -71,10 +71,10 @@ const BOXED_BG_CLASS: Record<NonNullable<LayoutVisualConfig['background']>, stri
 export function resolveProviderClassName(
   visual: LayoutVisualConfig | undefined,
 ): string | undefined {
-  // h-svh + overflow-hidden: lock the shell to exactly one viewport height so
+  // h-[var(--app-height)] + overflow-hidden: lock the shell to exactly one viewport height so
   // the inner scroll-area (PrivateContent) is the only scroll surface. Without
   // this, SidebarProvider grows via min-h-svh and the whole page scrolls.
-  const base = 'h-svh overflow-hidden';
+  const base = 'h-[var(--app-height,100svh)] overflow-hidden';
   if ((visual?.variant ?? 'full-bleed') !== 'boxed') return base;
   // `max-md:!bg-background` neutralises shadcn-sidebar's built-in
   // `has-[[data-variant=inset]]:bg-sidebar` below md so the mobile Drawer shell

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';

package/src/layouts/PrivateLayout/topBar.test.tsx

@@ -0,0 +1,213 @@
+// @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 { PrivateLayout } from './PrivateLayout';
+
+vi.mock('next/navigation', () => ({ usePathname: () => '/', useRouter: () => ({ push: () => {}, replace: () => {} }), useSearchParams: () => new URLSearchParams() }));
+
+// PrivateLayout lazy-loads the settings dialog without its own Suspense; keep the test to the shell.
+vi.mock('../SettingsLayout/SettingsDialog', () => ({ SettingsDialog: () => null }));
+let currentUser: { email: string; display_username: string; avatar: null } | null = { email: 'a@b.c', display_username: 'Mark', avatar: null };
+vi.mock('@djangocfg/api/auth', async () => ({
+  AuthContext: (await import('react')).createContext(undefined),
+  useAuth: () => ({ user: currentUser }),
+}));
+vi.mock('./hooks/useAuthGuard', () => ({ useAuthGuard: () => ({ isLoading: false, isForbidden: false, loadingText: '' }) }));
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let phone = true;
+let host: HTMLElement | null = null;
+let root: Root | null = null;
+
+beforeAll(() => {
+  window.matchMedia = ((query: string) => ({
+    // A phone has no precise hover pointer; a desktop does.
+    matches: query.includes('hover: hover') ? !phone : phone,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })) as typeof window.matchMedia;
+});
+
+afterEach(() => {
+  act(() => root?.unmount());
+  host?.remove();
+  host = root = null;
+  phone = true;
+  currentUser = { email: 'a@b.c', display_username: 'Mark', avatar: null };
+  document.cookie = 'sidebar_state=; path=/; max-age=0';
+});
+
+async function mount(props: Partial<React.ComponentProps<typeof PrivateLayout>>) {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  await act(async () =>
+    root!.render(
+      <PrivateLayout
+        requireAuth={false}
+        sidebar={{ groups: [{ label: 'A', items: [{ label: 'Home', href: '/' }] }] }}
+        header={{ title: 'Acme' }}
+        {...props}
+      >
+        <p>page</p>
+      </PrivateLayout>,
+    ),
+  );
+  return document.querySelector('[data-sidebar="topbar"]');
+}
+
+describe('PrivateLayout topBar', () => {
+  it('title falls back to header.title', async () => {
+    expect((await mount({ topBar: { account: false } }))?.textContent).toBe('Acme');
+  });
+
+  it('topBar.title overrides it and topBar.actions render on the right', async () => {
+    const bar = (await mount({ topBar: { title: 'Calls', actions: <button>New</button> } }))!;
+    expect(bar.textContent).toBe('CallsNewM');
+    expect(bar.querySelector('[data-sidebar="topbar-actions"]')!.firstElementChild?.textContent).toBe('New');
+  });
+
+  it('desktop, sidebar pinned open: no bar, the account stays in the sidebar footer', async () => {
+    phone = false;
+    document.cookie = 'sidebar_state=true; path=/';
+    await mount({ topBar: { title: 'Calls', actions: <button>New</button> } });
+    expect(document.querySelector('[data-sidebar="topbar"]')).toBeNull();
+    expect(document.querySelector('[data-sidebar="topbar-account"]')).toBeNull();
+    expect(document.body.textContent).toContain('Mark');
+  });
+
+  it('desktop, sidebar collapsed: the same bar with title, actions and avatar', async () => {
+    phone = false;
+    document.cookie = 'sidebar_state=false; path=/';
+    const bar = (await mount({ topBar: { title: 'Calls', actions: <button>New</button> } }))!;
+    expect(bar.children[1].textContent).toBe('Calls');
+    expect(bar.querySelector('[data-sidebar="topbar-actions"]')!.children[1].getAttribute('data-sidebar')).toBe('topbar-account');
+  });
+
+  describe('account', () => {
+    it('avatar present when signed in', async () => {
+      const bar = (await mount({}))!;
+      expect(bar.querySelector('[data-sidebar="topbar-account"]')).not.toBeNull();
+    });
+
+    it('no avatar without a session', async () => {
+      currentUser = null;
+      const bar = (await mount({}))!;
+      expect(bar.querySelector('[data-sidebar="topbar-account"]')).toBeNull();
+    });
+
+    it('no avatar with topBar.account === false', async () => {
+      const bar = (await mount({ topBar: { account: false } }))!;
+      expect(bar.querySelector('[data-sidebar="topbar-account"]')).toBeNull();
+    });
+
+    it('bar avatar and sidebar footer open the same menu items', async () => {
+      const labels = async (el: Element) => {
+        await act(async () => {
+          el.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true, button: 0 }));
+          el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, button: 0 }));
+          (el as HTMLElement).click();
+        });
+        const items = [...document.querySelectorAll('[role="menuitem"]')].map((i) => i.textContent);
+        await act(async () => {
+          document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+        });
+        return items;
+      };
+      const bar = (await mount({}))!;
+      const fromBar = await labels(bar.querySelector('[data-sidebar="topbar-account"]')!);
+      expect(fromBar.length).toBeGreaterThan(0);
+      await act(async () => root?.unmount());
+      host?.remove();
+      phone = false;
+      document.cookie = 'sidebar_state=true; path=/';
+      await mount({});
+      const footer = [...document.querySelectorAll('button')].find((b) => b.textContent?.includes('Mark'))!;
+      expect(await labels(footer)).toEqual(fromBar);
+    });
+
+    async function openDrawer() {
+      await act(async () => {
+        (document.querySelector('[data-sidebar="trigger"]') as HTMLElement).click();
+      });
+      return document.querySelector('[data-sidebar="sidebar"][data-mobile="true"]') ?? document.body;
+    }
+
+    it('phone drawer has no footer account while the bar carries the avatar', async () => {
+      await mount({});
+      const drawer = await openDrawer();
+      expect(drawer.textContent).toContain('Home');
+      expect(document.body.textContent).not.toContain('Mark');
+    });
+
+    it('phone drawer shows the footer account again with topBar.account === false', async () => {
+      await mount({ topBar: { account: false } });
+      await openDrawer();
+      expect(document.body.textContent).toContain('Mark');
+    });
+  });
+
+  describe('toggle', () => {
+    it('no tooltip and no native title on desktop or phone; aria-label stays', async () => {
+      for (const isPhone of [false, true]) {
+        phone = isPhone;
+        document.cookie = 'sidebar_state=false; path=/';
+        const bar = (await mount({}))!;
+        const trigger = bar.querySelector<HTMLElement>('[data-sidebar="trigger"]')!;
+        expect(trigger.hasAttribute('data-state')).toBe(false);
+        expect(trigger.hasAttribute('title')).toBe(false);
+        expect(trigger.getAttribute('aria-label')).toBe('Open sidebar');
+        await act(async () => {
+          trigger.focus();
+          trigger.dispatchEvent(new FocusEvent('focus'));
+        });
+        expect(document.querySelector('[role="tooltip"]')).toBeNull();
+        await act(async () => root?.unmount());
+        host?.remove();
+        host = root = null;
+      }
+    });
+  });
+
+  describe('hover-open', () => {
+    const enter = (el: Element) =>
+      act(async () => {
+        const ev = new Event('pointerenter', { bubbles: false }) as Event & { pointerType?: string };
+        ev.pointerType = 'mouse';
+        el.dispatchEvent(ev);
+        // React's onPointerEnter listens to pointerover.
+        const over = new Event('pointerover', { bubbles: true }) as Event & { pointerType?: string };
+        over.pointerType = 'mouse';
+        el.dispatchEvent(over);
+      });
+
+    it('the bar toggle does not open the hover overlay; the left edge zone does', async () => {
+      vi.useFakeTimers();
+      try {
+        phone = false;
+        document.cookie = 'sidebar_state=false; path=/';
+        const bar = (await mount({}))!;
+        const trigger = bar.querySelector('[data-sidebar="trigger"]')!;
+        await enter(trigger);
+        await act(async () => { vi.advanceTimersByTime(1000); });
+        expect(document.querySelector('[data-sidebar="peek"]')).toBeNull();
+
+        const edge = document.querySelector('[data-sidebar="peek-edge"]')!;
+        expect(edge).not.toBeNull();
+        await enter(edge);
+        await act(async () => { vi.advanceTimersByTime(1000); });
+        expect(document.querySelector('[data-sidebar="peek"]')).not.toBeNull();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
+});

package/src/layouts/PrivateLayout/types.ts

@@ -21,7 +21,7 @@ interface SidebarItemBase {
   badge?: string | number;
   /** Visual style of `badge`: `'count'` (default, neutral pill) or `'pill'` (accent-tinted, e.g. "lite"/"new"). */
   badgeVariant?: 'count' | 'pill';
-  /** Collapsed rail: shown in tooltip; defaults to `label`. */
+  /** @deprecated No effect: a collapsed sidebar is hidden, not an icon rail, and rows show no tooltip. */
   tooltip?: string;
 }
 
@@ -128,7 +128,7 @@ export interface SidebarConfig<Id extends string = string> {
   groupLabelStyle?: SidebarGroupLabelStyle;
   /** Featured CTA tile rendered below all groups, above `menuEnd`. */
   featured?: SidebarFeaturedConfig;
-  /** @deprecated No effect: rows are one desktop size and one 44px touch size. */
+  /** @deprecated No effect: rows are one desktop size (36px) and one phone size (40px with a 44px hit area). */
   density?: 'comfortable' | 'default' | 'compact';
 }
 
@@ -172,6 +172,13 @@ export interface HeaderConfig {
    * Takes priority over `brand`, `title`, `brandIcon`, `brandLetter`.
    */
   switcher?: SidebarBrandSwitcherConfig;
+  /**
+   * Where the product name (sidebar header brand, phone drawer header, and the default top bar title) links to,
+   * through the router. Resolution: `header.href` > `sidebar.homeHref` > the auth route `routes.defaultCallback` configured on
+   * `BaseApp` (`auth.routes`, default `/private`) > `/` (outside the auth provider). A custom `brand` node is rendered as given (never
+   * wrapped in a second link); a string `brand` is linkified.
+   */
+  href?: string;
   /** Custom header brand node (same idea as PublicNavbar `brand`). */
   brand?: ReactNode;
   /** Shown next to the logo when the sidebar is expanded */
@@ -209,12 +216,30 @@ export interface HeaderConfig {
 // PrivateLayout Props
 // ============================================================================
 
+/**
+ * Top bar content. One bar at every width, shown whenever the sidebar is not visible (always on a phone; on desktop
+ * while the sidebar is collapsed; never while it is docked). The sidebar toggle is always on the left and not configurable.
+ */
+export interface PrivateTopBarConfig {
+  /** Truncated next to the toggle. Defaults to `header.title` (the product name). */
+  title?: ReactNode;
+  /** Right end of the bar, vertically centred. Keep it to a couple of compact controls. */
+  actions?: ReactNode;
+  /**
+   * Account avatar at the right end of the bar for a signed-in user (the same menu as the sidebar footer). Default
+   * `true`. `false` removes the avatar from the bar and keeps the account in the phone drawer's footer.
+   */
+  account?: boolean;
+}
+
 export interface PrivateLayoutProps {
   children: ReactNode;
   /** Sidebar configuration */
   sidebar?: SidebarConfig;
   /** Title + account links (no top navbar — title is used in the sidebar chrome) */
   header?: HeaderConfig;
+  /** Top bar content (title override, right-hand actions, account avatar). The bar shows only while the sidebar is not visible. */
+  topBar?: PrivateTopBarConfig;
   /**
    * Path for active nav highlighting. With `@djangocfg/nextjs` i18n routing, pass `usePathname()` from
    * `@djangocfg/nextjs/i18n/navigation` (no `/[locale]` segment). If omitted, uses `next/navigation` (includes locale).