@djangocfg/layouts 2.1.607 → 2.1.609

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -14,7 +14,13 @@
 
 import React from 'react';
 
+import { useAuth } from '@djangocfg/api/auth';
+import { useLandingRoute } from './hooks/useLandingRoute';
+import { useProjectName } from '../../shared/ProjectContext';
 import { Preloader } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { SHELL_CLASS } from './geometry';
 import { SidebarInset, SidebarProvider } from '@djangocfg/ui-core/components';
 
 import { ForbiddenState, PrivateContent, PrivateSidebar } from './components';
@@ -55,6 +61,7 @@ export function PrivateLayout({
   children,
   sidebar,
   header,
+  topBar,
   pathname,
   contentPadding = 'default',
   contentScroll = 'auto',
@@ -73,9 +80,26 @@ export function PrivateLayout({
   const { providerStyle, providerClassName, insetClassName, sidebarVariant } =
     useLayoutVisual(visual);
 
+  // The account avatar lives in the top bar for a signed-in user unless `topBar.account === false`.
+  const { user } = useAuth();
+  // Bar title: topBar.title > header.title > the BaseApp project name > nothing. Only the last two link home.
+  const projectName = useProjectName();
+  const landing = useLandingRoute();
+  const barTitle = topBar?.title ?? (header?.title?.trim() || projectName || undefined);
+  const barHref = header?.href || sidebar?.homeHref || landing || '/';
+  const accountInBar = Boolean(user) && topBar?.account !== false;
+
   const defaultOpen = useSidebarDefaultOpen();
   const sidebarWidth = useSidebarWidth(Boolean(sidebar) && sidebar?.resizable !== false);
 
+  // Marks <html> while a private shell is mounted: base.css locks html/body (no document scroll, no rubber band)
+  // in an installed app, for private pages only. Public pages never carry it and stay scrollable.
+  React.useEffect(() => {
+    const root = document.documentElement;
+    root.setAttribute('data-private-shell', '');
+    return () => root.removeAttribute('data-private-shell');
+  }, []);
+
   if (isLoading) {
     return (
       <Preloader
@@ -99,7 +123,7 @@ export function PrivateLayout({
     <SidebarProvider
       defaultOpen={defaultOpen}
       style={{ ...providerStyle, ...sidebarWidth.style }}
-      className={providerClassName}
+      className={cn(SHELL_CLASS, providerClassName)}
       data-sidebar-resizing={sidebarWidth.dragging || undefined}
     >
       <SidebarWidthContext.Provider value={sidebarWidth}>
@@ -110,6 +134,7 @@ export function PrivateLayout({
               header={header}
               pathname={pathname}
               variant={sidebarVariant}
+              accountInBar={accountInBar}
             />
           )}
 
@@ -118,6 +143,12 @@ export function PrivateLayout({
               padding={contentPadding}
               scroll={contentScroll}
               hasSidebar={Boolean(sidebar)}
+              pathname={pathname}
+              title={barTitle}
+              titleHref={topBar?.title == null && barTitle ? barHref : undefined}
+              actions={topBar?.actions}
+              showAccount={accountInBar}
+              header={header}
               visual={visual}
             >
               {children}

package/src/layouts/PrivateLayout/README.md

@@ -1,6 +1,6 @@
 # PrivateLayout
 
-Authenticated app shell — a docked, resizable sidebar + scrollable content area. Collapsed, a trigger remains and hovering it peeks the sidebar open over the page; on mobile it is a drawer.
+Authenticated app shell — a docked, resizable sidebar + scrollable content area. Collapsed, a top bar remains and resting at the left screen edge peeks the sidebar open over the page (the toggle itself only clicks); on mobile it is a drawer.
 
 ```tsx
 <PrivateLayout
@@ -137,7 +137,7 @@ For pages like Kanban boards where the shell must be exactly one viewport tall a
 | Field | Type | Notes |
 |---|---|---|
 | `groups` | `SidebarGroupConfig[]` | Nav items grouped under labels. Set `group.label = ''` to render flat (no header). |
-| `homeHref` | `string` | Brand link target. |
+| `homeHref` | `string` | Brand link target. Order: `header.href` > `sidebar.homeHref` > auth `routes.defaultCallback` (the private landing page set in `BaseApp` `auth.routes`) > `/`. |
 | `menuStart` / `menuEnd` | `ReactNode` | Free slots above / below `groups` in the scrollable column. |
 | `menuStartShowOnCollapsed` / `menuEndShowOnCollapsed` | `boolean` | Deprecated, no effect (no icon rail). |
 | `resizable` | `boolean` | Drag the sidebar edge (14–24rem, remembered under `cfg.layouts.sidebar-width`; double-click resets). Default `true`. |
@@ -163,7 +163,7 @@ For pages like Kanban boards where the shell must be exactly one viewport tall a
 
 | Field | Type | Notes |
 |---|---|---|
-| `label`, `href`, `icon`, `tooltip` | — | Standard nav item fields. |
+| `label`, `href`, `icon` | — | Standard nav item fields (`tooltip` is deprecated, no effect). |
 | `settingsSection` | section id | Instead of `href`: a row that opens the Settings dialog on that section. Rendered only while the mounted dialog lists the section (no dead door), active while the dialog shows it. Type it with `SidebarItem<AppSectionId>` (see [SettingsLayout](../SettingsLayout/README.md#typed-section-ids)). |
 | `badge` | `string \| number` | Trailing badge content. |
 | `badgeVariant` | `'count' \| 'pill'` | Visual style. `'pill'` is accent-tinted (e.g. "lite"/"new"); `'count'` is neutral (default). |
@@ -279,7 +279,23 @@ const header: HeaderConfig = {
 | State | Behaviour |
 |---|---|
 | Docked | Width from `--sidebar-width`; drag the right edge, arrow keys, double-click to reset. |
-| Collapsed (desktop) | Hidden. A trigger stays top-left in a 48px top bar (in flow, so content never sits under it); hovering the trigger (or the free area around it) floats the sidebar over the page. The panel stays while the pointer is on it or a menu opened from it is open; Esc, navigation and moving away close it. Clicking the trigger docks it. |
-| Mobile (< md) | Drawer up to 22rem: 44px rows, 14px text, 18px icons, 8px side padding, 12px vertical body padding, close button. The drawer header and footer respect the safe areas (at least 1rem). The trigger is a 40px ghost button in a 48px in-flow top bar (also for `contentPadding="none"` pages) that adds `env(safe-area-inset-top)`. |
+| Collapsed (desktop) | Hidden. The top bar (toggle top-left, title, actions, avatar) shows; resting the pointer at the left screen edge (not on the toggle) floats the sidebar over the page. The panel stays while the pointer is on it or a menu opened from it is open; Esc, navigation and moving away close it. Clicking the trigger docks it. |
+| Mobile (< md) | Drawer 88vw wide (max 22rem, the dimmed strip taps it closed) and full height (`fixed inset-y-0`: the real visible area in a browser tab and in an iOS standalone PWA): 40px rows (44px hit area), 14px text, 20px icons, 8px container gutter + 10px row padding (icon column and logo at 18px; dividers, highlighted rows and footer share the 8px gutter), header is the brand only (48px under safe-top, no toggle or close button; it closes by backdrop tap, swipe, Escape or navigating). Three zones: pinned header (gets a bottom hairline once the nav scrolls), the nav as the ONLY scroller (`overscroll-contain`), pinned footer with a full-width top border and its own background; the drawer panel itself is `overflow-hidden` (`DrawerContent bare`). Header and footer respect the safe areas on top, bottom and sides (at least 1rem vertically). On a phone (below md) the layout draws a plain top bar: `safe-top + 3rem` tall (`--layout-bar-height`, `0px` from md up and without a sidebar), `bg-background` with a 1px bottom border, holding the sidebar toggle (the same ghost button as in the sidebar header) and `header.title`. It overlays the content column and slides away (`transform`, 200ms) on scroll-down and back on scroll-up or at the top, using the same `useNavbarScroll` policy as `PublicLayout` driven by the content scroller; it stays while the drawer is open, a field has focus, or the page is not scrollable. Content starts below the bar for every page, so pages do nothing; apps may use `--layout-bar-height` to offset their own sticky elements. `PrivateLayout` takes `topBar={{ title, actions }}` (types: `PrivateTopBarConfig`): `title` replaces `header.title` in the bar, `actions` is a ReactNode on the right (vertically centred, never shrinks the toggle; the title takes the rest and truncates). The same bar shows on desktop while the sidebar is collapsed (static, no auto-hide) and carries the account avatar for a signed-in user (`topBar.account={false}` to opt out); on a phone the drawer then has no footer account. Recommended actions are compact ghost icon `Button`s (36px); several are fine, keep them few. The toggle stays left and is not configurable. It is rendered by the phone bar only; desktop shows nothing (the sidebar is the navigation). |
 
-Row metrics (`geometry.ts`): desktop rows 36px, mobile rows 44px (touch target), both `text-sm` with 16px (desktop) or 18px (mobile) icons and group labels in `text-xs`. Safe-area insets only exist when the host app sets `viewportFit: "cover"` in its Next.js `viewport` export; without it the offsets fall back to the fixed minimums.
+Row metrics (`geometry.ts`): desktop rows 36px, mobile rows 40px (with a 44px hit area from an invisible `::after`), both `text-sm` with 16px (desktop) or 20px (mobile) icons and group labels in `text-xs`. Safe-area insets only exist when the host app sets `viewportFit: "cover"` in its Next.js `viewport` export; without it the offsets fall back to the fixed minimums. For an installed iOS PWA also set `appleWebApp.statusBarStyle` (`black-translucent` draws the page under the status bar and relies on the insets; `default` keeps it below). The drawer height is pinned with `inset-y-0` rather than `100dvh`, which can disagree with the visible area in standalone mode.
+
+
+## Installed app (PWA) support
+
+- Detection: `useDisplayMode()` / `useIsPwa()` from `@djangocfg/ui-core/hooks` (the `display-mode` media query, iOS `navigator.standalone`, Android TWA referrer). The server and hydration render say `browser`; for first-paint styling use CSS: `UiProviders` sets `<html data-display-mode="browser|standalone|fullscreen|minimal-ui|window-controls-overlay">`.
+- Tokens (ui-core `base.css`): `--safe-top/right/bottom/left` (= `--app-safe-*` if set, else `env(safe-area-inset-*)`), `--app-height: 100dvh`. Tokens are for layout and spacing; the hook is for behaviour (hide an "install app" prompt, show a back button).
+- Host requirements for a good PWA: `viewport-fit=cover` (`viewport.viewportFit = 'cover'`), `appleWebApp: { capable: true, statusBarStyle }` (`black-translucent` draws the page under the status bar and needs the insets; `default` keeps it below), a manifest with `display: 'standalone'`, and `themeColor`. `createViewport({ themeColor, viewportFit: 'cover' })` and `createManifestMetadata({ ..., statusBarStyle })` from `@djangocfg/nextjs` set them.
+- Storybook: toolbar items "Display mode" and "Safe area" emulate an installed iPhone; see the PhonePwa* stories.
+
+## The shell never scrolls the document
+
+`PrivateLayout` is exactly one dynamic viewport tall (`h-[var(--app-height,100dvh)] overflow-hidden`, `SHELL_CLASS`): the (desktop) trigger bar is `shrink-0`, the content below it is `flex-1 min-h-0` and owns the scroll (per `contentScroll`). While mounted it sets `data-private-shell` on `<html>`; in an installed app base.css then locks `html`/`body` (`height: 100%; overflow: hidden; overscroll-behavior: none`), so pressing and dragging the top bar cannot move the page. Public pages never carry the attribute and stay scrollable. Consequences for pages: sticky elements and `window.scrollTo` now relate to the content region, not the window; the layout scrolls its content back to the top when `pathname` changes. Do not wrap the layout in `min-h-screen` / `h-screen`. On iOS < 16, `overscroll-behavior` is ignored, so a rubber band at the very edge can only be ruled out on a real device.
+
+## Brand title and link
+
+The product name is semibold (16px on desktop, 14px on a phone, theme type scale), one line, truncated. Title order: `header.title` > `BaseApp` `project` name > none (monogram only). The brand (sidebar header, phone drawer header) and the default top bar title link to `header.href` (default `sidebar.homeHref`, else `/`) through the router `Link` (target order: `header.href` > `sidebar.homeHref` > auth `defaultCallback` > `/`); the drawer closes on click. A custom `header.brand` node is not wrapped; `topBar.title` is shown as given.

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

@@ -0,0 +1,208 @@
+// @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 { AuthContext } from '@djangocfg/api/auth';
+import { LinkProvider, type LinkComponentProps } from '@djangocfg/ui-core/components';
+
+import { ProjectNameProvider } from '../../shared/ProjectContext';
+import { PrivateLayout } from './PrivateLayout';
+
+vi.mock('next/navigation', () => ({ usePathname: () => '/', useRouter: () => ({ push: () => {}, replace: () => {} }), useSearchParams: () => new URLSearchParams() }));
+vi.mock('../SettingsLayout/SettingsDialog', () => ({ SettingsDialog: () => null }));
+vi.mock('@djangocfg/api/auth', async () => ({
+  AuthContext: (await import('react')).createContext(undefined),
+  useAuth: () => ({ user: null }),
+}));
+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;
+const navigated: string[] = [];
+
+/** A router-style Link: records the navigation instead of loading a page. */
+function RouterLink({ href, children, onClick, ...rest }: LinkComponentProps) {
+  return (
+    <a
+      href={href}
+      {...(rest as object)}
+      onClick={(e) => {
+        onClick?.(e);
+        e.preventDefault();
+        navigated.push(href);
+      }}
+    >
+      {children}
+    </a>
+  );
+}
+
+beforeAll(() => {
+  window.matchMedia = ((query: string) => ({
+    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;
+  navigated.length = 0;
+  document.cookie = 'sidebar_state=; path=/; max-age=0';
+});
+
+async function mount(props: Partial<React.ComponentProps<typeof PrivateLayout>>, project?: string, landing?: string) {
+  host = document.createElement('div');
+  document.body.appendChild(host);
+  root = createRoot(host);
+  await act(async () =>
+    root!.render(
+      <AuthContext.Provider value={(landing ? { routes: { auth: '/auth', defaultCallback: landing, defaultAuthCallback: '/auth' } } : undefined) as never}>
+      <LinkProvider value={RouterLink}>
+        <ProjectNameProvider value={project}>
+          <PrivateLayout requireAuth={false} sidebar={{ groups: [{ label: 'A', items: [{ label: 'Docs', href: '/docs' }] }] }} {...props}>
+            <p>page</p>
+          </PrivateLayout>
+        </ProjectNameProvider>
+      </LinkProvider>
+      </AuthContext.Provider>,
+    ),
+  );
+}
+
+const bar = () => document.querySelector('[data-sidebar="topbar"]');
+const barLink = () => bar()?.querySelector('a') ?? null;
+
+async function openDrawer() {
+  await act(async () => {
+    (document.querySelector('[data-sidebar="trigger"]') as HTMLElement).click();
+  });
+}
+const drawerBrand = () =>
+  document.querySelector('[data-sidebar="header"] a') as HTMLAnchorElement | null;
+
+describe('brand link and title resolution', () => {
+  it('bar title links to "/" by default', async () => {
+    await mount({ header: { title: 'Acme' } });
+    expect(barLink()?.getAttribute('href')).toBe('/');
+    expect(barLink()?.textContent).toBe('Acme');
+    expect(barLink()?.getAttribute('aria-label')).toBe('Acme');
+  });
+
+  it('header.href sets the target; click goes through the router link', async () => {
+    await mount({ header: { title: 'Acme', href: '/app' } });
+    expect(barLink()?.getAttribute('href')).toBe('/app');
+    await act(async () => barLink()!.click());
+    expect(navigated).toEqual(['/app']);
+  });
+
+  it('topBar.title stays as given, not linkified', async () => {
+    await mount({ header: { title: 'Acme' }, topBar: { title: 'Calls' } });
+    expect(bar()?.textContent).toContain('Calls');
+    expect(barLink()).toBeNull();
+  });
+
+  it('drawer brand links home and closes the drawer on click', async () => {
+    await mount({ header: { title: 'Acme', href: '/app' } });
+    await openDrawer();
+    const link = drawerBrand()!;
+    expect(link.getAttribute('href')).toBe('/app');
+    expect(link.textContent).toContain('Acme');
+    expect(document.querySelector('[data-sidebar="sidebar"][data-mobile="true"], [role="dialog"]')).not.toBeNull();
+    await act(async () => link.click());
+    expect(navigated).toEqual(['/app']);
+    expect(document.querySelector('[role="dialog"][data-state="open"]')).toBeNull();
+  });
+
+  it('a custom brand node is rendered as given, not wrapped in a link', async () => {
+    await mount({ header: { title: 'Acme', brand: <b data-testid="mine">Mine</b> } }, undefined);
+    phone = false;
+    await act(async () => root?.unmount());
+    host?.remove();
+    document.cookie = 'sidebar_state=true; path=/';
+    await mount({ header: { title: 'Acme', brand: <b data-testid="mine">Mine</b> } });
+    const mine = document.querySelector('[data-testid="mine"]')!;
+    expect(mine.closest('a')).toBeNull();
+  });
+
+  it('no header.title: the project name from the provider is shown and linked', async () => {
+    await mount({}, 'Proj');
+    expect(barLink()?.textContent).toBe('Proj');
+    expect(barLink()?.getAttribute('href')).toBe('/');
+  });
+
+  it('explicit header.title wins over the project name', async () => {
+    await mount({ header: { title: 'Acme' } }, 'Proj');
+    expect(barLink()?.textContent).toBe('Acme');
+  });
+
+  it('no provider and no title: no text, no crash, no empty bar link', async () => {
+    await mount({});
+    expect(bar()).not.toBeNull();
+    expect(barLink()).toBeNull();
+    await openDrawer();
+    const link = drawerBrand();
+    expect(link?.getAttribute('aria-label')).toBe('Home');
+    expect(link?.textContent?.trim().length).toBeLessThanOrEqual(1);
+  });
+
+  describe('home href resolution: header.href > sidebar.homeHref > auth defaultCallback > "/"', () => {
+    it('auth provider defaultCallback is the target when nothing else is set', async () => {
+      await mount({ header: { title: 'Acme' } }, undefined, '/workspace');
+      expect(barLink()?.getAttribute('href')).toBe('/workspace');
+      await openDrawer();
+      expect(drawerBrand()?.getAttribute('href')).toBe('/workspace');
+    });
+
+    it('sidebar.homeHref beats defaultCallback; header.href beats both', async () => {
+      await mount({ header: { title: 'Acme' }, sidebar: { homeHref: '/home', groups: [] } }, undefined, '/workspace');
+      expect(barLink()?.getAttribute('href')).toBe('/home');
+      await act(async () => root?.unmount());
+      host?.remove();
+      await mount({ header: { title: 'Acme', href: '/x' }, sidebar: { homeHref: '/home', groups: [] } }, undefined, '/workspace');
+      expect(barLink()?.getAttribute('href')).toBe('/x');
+    });
+
+    it('outside the auth provider: "/", no crash', async () => {
+      await mount({ header: { title: 'Acme' } });
+      expect(barLink()?.getAttribute('href')).toBe('/');
+    });
+  });
+
+  describe('sidebar header toggle', () => {
+    it('phone drawer header is the brand only: no toggle button, the link stays, accessible name present', async () => {
+      await mount({ header: { title: 'Acme' } });
+      await openDrawer();
+      const header = document.querySelector('[data-sidebar="header"]')!;
+      expect(header.querySelector('button')).toBeNull();
+      expect(header.querySelector('[data-sidebar="trigger"]')).toBeNull();
+      expect(header.querySelector('a')?.textContent).toContain('Acme');
+      // The primitive keeps an sr-only title for screen readers.
+      expect(document.querySelector('[role="dialog"] .sr-only')?.textContent).toContain('Sidebar');
+    });
+
+    it('phone drawer closes on Escape', async () => {
+      await mount({ header: { title: 'Acme' } });
+      await openDrawer();
+      expect(document.querySelector('[role="dialog"][data-state="open"]')).not.toBeNull();
+      await act(async () => {
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+      });
+      expect(document.querySelector('[role="dialog"][data-state="open"]')).toBeNull();
+    });
+
+    it('desktop docked sidebar header keeps its toggle', async () => {
+      phone = false;
+      document.cookie = 'sidebar_state=true; path=/';
+      await mount({ header: { title: 'Acme' } });
+      expect(document.querySelector('[data-sidebar="header"] [data-sidebar="trigger"]')).not.toBeNull();
+    });
+  });
+});

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

@@ -36,7 +36,7 @@ export function ForbiddenState({
   return (
     <div
       role="alert"
-      className="flex min-h-svh flex-col items-center justify-center gap-4 p-6 text-center"
+      className="flex min-h-[var(--app-height,100svh)] flex-col items-center justify-center gap-4 p-6 text-center"
     >
       <div className="flex size-12 items-center justify-center rounded-full bg-destructive/10">
         <ShieldAlert className="size-6 text-destructive" />

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

@@ -1,20 +1,24 @@
 // @vitest-environment jsdom
 import React, { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
-import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
 
 import { SidebarProvider } from '@djangocfg/ui-core/components';
 
 import { PrivateContent } from './PrivateContent';
 
+vi.mock('@djangocfg/api/auth', () => ({ useAuth: () => ({ user: { email: 'a@b.c', display_username: 'Mark', avatar: null } }) }));
+vi.mock('next/navigation', () => ({ usePathname: () => '/', useRouter: () => ({ push: () => {}, replace: () => {} }), useSearchParams: () => new URLSearchParams() }));
+
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+let phone = false;
 let host: HTMLElement | null = null;
 let root: Root | null = null;
 
 beforeAll(() => {
   window.matchMedia ??= ((query: string) => ({
-    matches: false,
+    matches: phone,
     media: query,
     onchange: null,
     addEventListener: () => {},
@@ -29,17 +33,19 @@ afterEach(() => {
   act(() => root?.unmount());
   host?.remove();
   host = root = null;
+  phone = false;
 });
 
-function render(defaultOpen: boolean, padding: 'none' | 'default') {
+function render(defaultOpen: boolean, padding: 'none' | 'default', title?: React.ReactNode, actions?: React.ReactNode, showAccount = false) {
   host = document.createElement('div');
   document.body.appendChild(host);
   root = createRoot(host);
   act(() =>
     root!.render(
       <SidebarProvider defaultOpen={defaultOpen}>
-        <PrivateContent padding={padding} scroll={padding === 'none' ? 'hidden' : 'auto'}>
+        <PrivateContent title={title} actions={actions} showAccount={showAccount} padding={padding} scroll={padding === 'none' ? 'hidden' : 'auto'}>
           <p>page</p>
+          <input aria-label="field" />
         </PrivateContent>
       </SidebarProvider>,
     ),
@@ -48,18 +54,177 @@ function render(defaultOpen: boolean, padding: 'none' | 'default') {
 }
 
 describe('PrivateContent top bar', () => {
-  it.each(['none', 'default'] as const)('reserves an in-flow, safe-area aware bar for the trigger (padding %s)', (padding) => {
+  it.each(['none', 'default'] as const)('desktop, sidebar collapsed: the same overlay bar, content offset by its real height (padding %s)', (padding) => {
     const el = render(false, padding);
     const bar = el.querySelector('[data-sidebar="topbar"]')!;
+    const col = bar.parentElement as HTMLElement;
     expect(bar).not.toBeNull();
-    expect(bar.className).toContain('env(safe-area-inset-top');
-    expect(bar.className).not.toMatch(/\babsolute\b/);
+    expect(col.style.getPropertyValue('--layout-bar-height')).toContain('3rem');
+    expect(bar.className).toContain('h-[var(--layout-bar-height)]');
+    expect(bar.className).toContain('pt-[var(--safe-top');
+    expect(bar.className).toMatch(/\babsolute\b/);
     expect(bar.querySelector('[data-sidebar="trigger"]')).not.toBeNull();
-    // The page is a sibling after the bar, never underneath it.
-    expect(bar.nextElementSibling?.textContent).toBe('page');
+    expect((bar.nextElementSibling as HTMLElement).className).toContain('layout-bar-height');
+  });
+
+  it('draws no bar while the sidebar is docked, and the bar height is 0', () => {
+    const el = render(true, 'default');
+    expect(el.querySelector('[data-sidebar="topbar"]')).toBeNull();
+    expect(el.querySelector<HTMLElement>('[style*="--layout-bar-height"]')!.style.getPropertyValue('--layout-bar-height')).toBe('0px');
+  });
+
+  it.each(['none', 'default'] as const)('phone + padding %s: one fixed-height in-flow bar, the same for every page', (padding) => {
+    phone = true;
+    const el = render(false, padding, 'Acme');
+    const bar = el.querySelector('[data-sidebar="topbar"]')!;
+    const col = bar.parentElement as HTMLElement;
+    expect(col.style.getPropertyValue('--layout-bar-height')).toBe('calc(var(--safe-top, env(safe-area-inset-top, 0px)) + 3rem)');
+    expect(bar.className).toContain('h-[var(--layout-bar-height)]');
+    expect(bar.className).toMatch(/\bborder-b\b/);
+    expect(bar.className).toContain('bg-background');
+    expect(bar.className).toContain('pt-[var(--safe-top');
+    expect(bar.className).toContain('pl-[calc(var(--safe-left');
+    expect(bar.className).toContain('pr-[calc(var(--safe-right');
+    // Overlays the column (transform-hidden), so hiding never reflows; the content pads by the bar height.
+    expect(bar.className).toMatch(/\babsolute\b/);
+    expect(bar.className).toContain('transition-transform');
+    expect((bar.nextElementSibling as HTMLElement).className).toContain('layout-bar-height');
+    expect(bar.querySelector('[data-sidebar="trigger"]')!.className).not.toMatch(/\b(rounded-full|border|shadow)/);
+    expect(bar.textContent).toBe('Acme');
+    expect(bar.getAttribute('data-hidden')).toBe('false');
+    // Content is the next sibling: it starts under the bar and carries no trigger offsets.
+    const scroller = bar.nextElementSibling as HTMLElement;
+    expect(scroller.className).not.toContain('layout-trigger');
+  });
+
+  it('phone without a title shows the toggle only; desktop sets the bar height to 0', () => {
+    phone = true;
+    expect(render(false, 'default').querySelector('[data-sidebar="topbar"]')!.textContent).toBe('');
+  });
+
+  it('top bar is shrink-0 and the content below it is flex-1 min-h-0 (document cannot grow)', () => {
+    const el = render(false, 'default');
+    const bar = el.querySelector('[data-sidebar="topbar"]')!;
+    const col = bar.parentElement!;
+    const scroller = bar.nextElementSibling as HTMLElement;
+    expect(bar.className).toMatch(/\bshrink-0\b/);
+    expect(col.className).toMatch(/\bmin-h-0\b/);
+    expect(scroller.className).toMatch(/\bmin-h-0\b/);
+    expect(scroller.className).toMatch(/\bflex-1\b/);
+    expect(scroller.className).toMatch(/\boverflow-y-auto\b/);
   });
 
-  it('draws no bar while the sidebar is docked', () => {
-    expect(render(true, 'default').querySelector('[data-sidebar="topbar"]')).toBeNull();
+  describe('phone auto-hide', () => {
+    function mountPhone(isPhone = true) {
+      phone = isPhone;
+      // Deferred like a real frame: useScroll's store expects the id to be assigned before the callback runs.
+      let id = 0;
+      vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+        void Promise.resolve().then(() => cb(0));
+        return ++id;
+      });
+      const el = render(false, 'default', 'Acme');
+      const bar = el.querySelector('[data-sidebar="topbar"]') as HTMLElement;
+      const scroller = bar.nextElementSibling as HTMLElement;
+      Object.defineProperty(scroller, 'scrollHeight', { configurable: true, value: 3000 });
+      Object.defineProperty(scroller, 'clientHeight', { configurable: true, value: 800 });
+      const scrollTo = (top: number) =>
+        act(async () => {
+          scroller.scrollTop = top;
+          scroller.dispatchEvent(new Event('scroll'));
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+      return { el, bar, scroller, scrollTo };
+    }
+    afterEach(() => vi.unstubAllGlobals());
+
+    it('hides on scroll down, shows on scroll up and at the top', async () => {
+      const { bar, scrollTo } = mountPhone();
+      expect(bar.getAttribute('data-hidden')).toBe('false');
+      await scrollTo(120);
+      await scrollTo(200);
+      expect(bar.getAttribute('data-hidden')).toBe('true');
+      await scrollTo(180);
+      await scrollTo(150);
+      expect(bar.getAttribute('data-hidden')).toBe('false');
+      await scrollTo(300);
+      await scrollTo(400);
+      expect(bar.getAttribute('data-hidden')).toBe('true');
+      await scrollTo(0);
+      expect(bar.getAttribute('data-hidden')).toBe('false');
+    });
+
+    it('desktop (sidebar collapsed): the bar is static and never hides', async () => {
+      const { bar, scrollTo } = mountPhone(false);
+      await scrollTo(120);
+      await scrollTo(400);
+      expect(bar.getAttribute('data-hidden')).toBe('false');
+    });
+
+    it('stays visible while the drawer is open', async () => {
+      const { bar, scrollTo } = mountPhone();
+      act(() => (bar.querySelector('[data-sidebar="trigger"]') as HTMLElement).click());
+      await scrollTo(120);
+      await scrollTo(400);
+      expect(bar.getAttribute('data-hidden')).toBe('false');
+    });
+
+    it('stays visible while a field has focus', async () => {
+      const { el, bar, scrollTo } = mountPhone();
+      act(() => (el.querySelector('input') as HTMLInputElement).focus());
+      await scrollTo(120);
+      await scrollTo(400);
+      expect(bar.getAttribute('data-hidden')).toBe('false');
+    });
+
+    it('never hides when the content is not scrollable', async () => {
+      const { bar, scroller, scrollTo } = mountPhone();
+      Object.defineProperty(scroller, 'scrollHeight', { configurable: true, value: 800 });
+      await scrollTo(120);
+      await scrollTo(400);
+      expect(bar.getAttribute('data-hidden')).toBe('false');
+    });
+  });
+
+  describe('topBar content', () => {
+    it('renders title and right-hand actions; the toggle stays first and does not shrink', () => {
+      phone = true;
+      const bar = render(false, 'default', 'Calls', <button>New</button>).querySelector('[data-sidebar="topbar"]')!;
+      const children = [...bar.children];
+      expect(children[0].getAttribute('data-sidebar')).toBe('trigger');
+      expect(children[0].className).toMatch(/\bshrink-0\b/);
+      const title = children[1] as HTMLElement;
+      expect(title.textContent).toBe('Calls');
+      expect(title.className).toContain('truncate');
+      expect(title.className).toContain('flex-1');
+      const actions = children[2] as HTMLElement;
+      expect(actions.className).toMatch(/\bshrink-0\b/);
+      expect(actions.className).toContain('items-center');
+      expect(actions.textContent).toBe('New');
+    });
+
+    it('desktop, sidebar collapsed: same markup, title and actions', () => {
+      const bar = render(false, 'default', 'Calls', <button>New</button>).querySelector('[data-sidebar="topbar"]')!;
+      expect(bar.children[0].getAttribute('data-sidebar')).toBe('trigger');
+      expect(bar.children[1].textContent).toBe('Calls');
+      expect(bar.children[2].textContent).toBe('New');
+    });
+
+    it('account avatar: after the actions, in the actions container, only with showAccount', () => {
+      phone = true;
+      const bar = render(false, 'default', 'Calls', <button>New</button>, true).querySelector('[data-sidebar="topbar"]')!;
+      const actions = bar.querySelector('[data-sidebar="topbar-actions"]')!;
+      expect(actions.children[0].textContent).toBe('New');
+      expect(actions.children[1].getAttribute('data-sidebar')).toBe('topbar-account');
+      expect(actions.children[1].getAttribute('aria-label')).toBe('User menu');
+    });
+
+    it('no avatar without showAccount', () => {
+      phone = true;
+      const bar = render(false, 'default', 'Calls').querySelector('[data-sidebar="topbar"]')!;
+      expect(bar.querySelector('[data-sidebar="topbar-account"]')).toBeNull();
+      expect(bar.querySelector('[data-sidebar="topbar-actions"]')).toBeNull();
+    });
   });
 });