@djangocfg/layouts 2.1.603 → 2.1.605

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.603",
+  "version": "2.1.605",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -91,11 +91,11 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.603",
-    "@djangocfg/api": "^2.1.603",
-    "@djangocfg/devtools": "^2.1.603",
-    "@djangocfg/i18n": "^2.1.603",
-    "@djangocfg/ui-core": "^2.1.603",
+    "@djangocfg/analytics": "^2.1.605",
+    "@djangocfg/api": "^2.1.605",
+    "@djangocfg/devtools": "^2.1.605",
+    "@djangocfg/i18n": "^2.1.605",
+    "@djangocfg/ui-core": "^2.1.605",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -125,12 +125,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.603",
-    "@djangocfg/api": "^2.1.603",
-    "@djangocfg/devtools": "^2.1.603",
-    "@djangocfg/i18n": "^2.1.603",
-    "@djangocfg/typescript-config": "^2.1.603",
-    "@djangocfg/ui-core": "^2.1.603",
+    "@djangocfg/analytics": "^2.1.605",
+    "@djangocfg/api": "^2.1.605",
+    "@djangocfg/devtools": "^2.1.605",
+    "@djangocfg/i18n": "^2.1.605",
+    "@djangocfg/typescript-config": "^2.1.605",
+    "@djangocfg/ui-core": "^2.1.605",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

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

@@ -1,18 +1,19 @@
 /**
  * Private layout main column: the scroll surface, plus the sidebar trigger
  * whenever the sidebar is not docked (collapsed on desktop, always on mobile).
- * On desktop the trigger sits in a hover zone that peeks the sidebar open.
+ * On desktop (fine pointer) the trigger sits in a hover zone that peeks the sidebar open after a short intent delay.
  */
 
 'use client';
 
 import React, { ReactNode } from 'react';
 
-import { SidebarTrigger, useSidebar } from '@djangocfg/ui-core/components';
+import { useSidebar } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import type { LayoutVisualConfig } from '../../types';
 import { useSidebarPeek } from '../hooks';
+import { PrivateSidebarTrigger } from './PrivateSidebarTrigger';
 
 interface PrivateContentProps {
   children: ReactNode;
@@ -73,15 +74,10 @@ export function PrivateContent({
       {showTrigger ? (
         <div
           data-sidebar="trigger-zone"
-          {...(isMobile ? undefined : peek?.zoneProps)}
+          {...(isMobile || !peek?.hoverEnabled ? undefined : peek.zoneProps)}
           className="absolute left-0 top-[env(safe-area-inset-top,0px)] z-20 flex size-14 items-center justify-center"
         >
-          <SidebarTrigger
-            className={cn(
-              'text-muted-foreground hover:text-foreground',
-              isMobile ? 'size-11 [&_svg]:!size-5' : 'size-8',
-            )}
-          />
+          <PrivateSidebarTrigger className="text-muted-foreground hover:text-foreground" />
         </div>
       ) : null}
       <div className={scrollAreaClass}>

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

@@ -30,6 +30,7 @@ import { useSidebar } from '@djangocfg/ui-core/components';
 import { LucideIcon as LucideIconRender } from '../../../components';
 import { usePeekPin } from '../hooks';
 import { usePrivateLayoutContext } from '../context';
+import { SIDEBAR_SPACING } from '../geometry';
 import { useAccountMenuItems } from '../../SettingsLayout/hooks';
 
 import type { HeaderConfig } from '../types';
@@ -170,8 +171,10 @@ function PrivateSidebarAccountRaw({ header }: PrivateSidebarAccountProps) {
     </Button>
   );
 
-  const wrapperClass =
-    'flex w-full min-w-0 shrink-0 items-center justify-between gap-1 border-t border-sidebar-border/60 p-2 pb-[max(0.5rem,env(safe-area-inset-bottom,0px))]';
+  const wrapperClass = cn(
+    'flex w-full min-w-0 shrink-0 items-center justify-between gap-1 border-t border-sidebar-border/60',
+    SIDEBAR_SPACING[isMobile ? 'mobile' : 'desktop'].footer,
+  );
 
   return (
     <div className={wrapperClass}>

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

@@ -0,0 +1,45 @@
+/**
+ * The one sidebar button: same box, icon and position rules on mobile and desktop.
+ * Floating over the content it opens the sidebar; inside the sidebar header it closes or
+ * collapses it. Both are `toggleSidebar`.
+ */
+
+'use client';
+
+import React from 'react';
+import { PanelLeft } from 'lucide-react';
+
+import { Button, useSidebar } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { TRIGGER_CLASS } from '../geometry';
+
+export const PrivateSidebarTrigger = React.forwardRef<
+  React.ElementRef<typeof Button>,
+  React.ComponentProps<typeof Button>
+>(({ className, onClick, ...props }, ref) => {
+  const { toggleSidebar, isMobile, openMobile, open } = useSidebar();
+  const isOpen = isMobile ? openMobile : open;
+  const label = isOpen ? 'Close sidebar' : 'Open sidebar';
+
+  return (
+    <Button
+      ref={ref}
+      type="button"
+      data-sidebar="trigger"
+      variant="ghost"
+      size="icon"
+      title={label}
+      aria-label={label}
+      className={cn(TRIGGER_CLASS, className)}
+      onClick={(event) => {
+        onClick?.(event);
+        toggleSidebar();
+      }}
+      {...props}
+    >
+      <PanelLeft aria-hidden />
+    </Button>
+  );
+});
+PrivateSidebarTrigger.displayName = 'PrivateSidebarTrigger';

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

@@ -8,6 +8,8 @@
 import React, { useMemo } from 'react';
 
 import { usePrivateLayoutContext } from '../context';
+import { SIDEBAR_SPACING } from '../geometry';
+import { cn } from '@djangocfg/ui-core/lib';
 import { sidebarItemKey } from '../sidebarItems';
 import { PrivateSidebarAccount } from './PrivateSidebarAccount';
 import { SidebarBrand } from './SidebarBrand';
@@ -15,7 +17,7 @@ import { SidebarNavGroup } from './SidebarNavGroup';
 import { SidebarSlots } from './SidebarSlots';
 
 export function SidebarBody() {
-  const { sidebar, header } = usePrivateLayoutContext();
+  const { sidebar, header, isMobile } = usePrivateLayoutContext();
 
   const groups = useMemo(
     () =>
@@ -36,7 +38,10 @@ export function SidebarBody() {
       <SidebarBrand />
       <div
         data-sidebar="content"
-        className="flex min-h-0 flex-1 flex-col gap-1 overflow-y-auto overflow-x-hidden py-2"
+        className={cn(
+          'flex min-h-0 flex-1 flex-col gap-1 overflow-y-auto overflow-x-hidden',
+          SIDEBAR_SPACING[isMobile ? 'mobile' : 'desktop'].body,
+        )}
       >
         <SidebarSlots />
         {groups}

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

@@ -6,13 +6,14 @@
 'use client';
 
 import React, { memo } from 'react';
-import { X } from 'lucide-react';
 
-import { Button, Link, SidebarTrigger, useSidebar } from '@djangocfg/ui-core/components';
+import { Link } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { LucideIcon } from '../../../components';
 import { usePrivateLayoutContext } from '../context';
+import { SIDEBAR_SPACING } from '../geometry';
+import { PrivateSidebarTrigger } from './PrivateSidebarTrigger';
 import { SidebarBrandSwitcher } from './SidebarBrandSwitcher';
 
 const BRAND_LINK =
@@ -20,7 +21,6 @@ const BRAND_LINK =
 
 function SidebarBrandRaw() {
   const { header, homeHref, brandTitle, brandMonogram, isMobile } = usePrivateLayoutContext();
-  const { setOpenMobile } = useSidebar();
 
   const customBrand = header?.brand;
 
@@ -55,33 +55,17 @@ function SidebarBrandRaw() {
       </Link>
     );
 
-  const trailing = isMobile ? (
-    <Button
-      type="button"
-      variant="ghost"
-      size="icon"
-      className="size-11 shrink-0 text-sidebar-foreground/70"
-      aria-label="Close menu"
-      onClick={() => setOpenMobile(false)}
-    >
-      <X className="size-5" />
-    </Button>
-  ) : header?.switcher ? null : (
-    <SidebarTrigger className="shrink-0 text-sidebar-foreground/60 hover:text-sidebar-foreground" />
+  const trailing = header?.switcher ? null : (
+    <PrivateSidebarTrigger className="text-sidebar-foreground/60 hover:text-sidebar-foreground" />
   );
 
   return (
     <div
       data-sidebar="header"
-      className={cn(
-        'flex shrink-0 items-center gap-2',
-        isMobile
-          ? 'px-4 pb-2 pt-[max(0.5rem,env(safe-area-inset-top,0px))]'
-          : 'px-3 pb-1 pt-3',
-      )}
+      className={cn('flex shrink-0 items-center gap-2', SIDEBAR_SPACING[isMobile ? 'mobile' : 'desktop'].header)}
     >
       <div className="min-w-0 flex-1">
-        {header?.switcher ? <SidebarBrandSwitcher config={header.switcher} showCollapseTrigger={!isMobile} /> : brand}
+        {header?.switcher ? <SidebarBrandSwitcher config={header.switcher} showCollapseTrigger /> : brand}
       </div>
       {trailing}
     </div>

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

@@ -20,12 +20,12 @@ import {
   DropdownMenuItem,
   DropdownMenuSeparator,
   DropdownMenuTrigger,
-  SidebarTrigger,
 } from '@djangocfg/ui-core/components';
 import { Link } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { usePeekPin } from '../hooks';
+import { PrivateSidebarTrigger } from './PrivateSidebarTrigger';
 import type { SidebarBrandSwitcherConfig, SidebarBrandSwitcherItem } from '../types';
 
 interface SidebarBrandSwitcherProps {
@@ -125,7 +125,7 @@ function SidebarBrandSwitcherRaw({ config, showCollapseTrigger }: SidebarBrandSw
       </DropdownMenu>
 
       {showCollapseTrigger ? (
-        <SidebarTrigger className="shrink-0" aria-label="Collapse sidebar" data-no-expand />
+        <PrivateSidebarTrigger data-no-expand />
       ) : null}
     </div>
   );

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

@@ -27,22 +27,23 @@ import { isSettingsItem, isSidebarGroupVisible, sidebarItemKey, visibleSidebarIt
 import type { SidebarGroupConfig } from '../types';
 import { SidebarNavItem } from './SidebarNavItem';
 
-const GROUP_CLASS = cn(
-  'gap-0 px-2 py-1',
-  '[&:not(:first-child)]:mt-1 [&:not(:first-child)]:border-t [&:not(:first-child)]:border-sidebar-border/60 [&:not(:first-child)]:pt-2',
-);
+const groupClassFor = (inset: string) =>
+  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',
+  );
 
 /** A `separated` group draws its own, stronger divider (below), so it drops the hairline and takes more air. */
-const SEPARATED_GROUP_CLASS = 'gap-0 px-2 pb-1 pt-0';
+const separatedGroupClassFor = (inset: string) => `gap-0 ${inset} pb-1 pt-0`;
 
 /** Full-width rule with room above and below; decorative, so the rail and the drawer read the same. */
-function GroupDivider() {
+function GroupDivider({ inset }: { inset: string }) {
   return (
     <div
       role="separator"
       aria-orientation="horizontal"
       data-sidebar="group-divider"
-      className="mx-2 mb-2 mt-3 h-px shrink-0 bg-sidebar-border"
+      className={cn(inset, 'mb-2 mt-3 h-px shrink-0 bg-sidebar-border')}
     />
   );
 }
@@ -83,8 +84,8 @@ function SidebarNavGroupRaw({ group }: { group: SidebarGroupConfig }) {
   ));
   if (!visible) return null;
 
-  const groupClass = group.separated ? SEPARATED_GROUP_CLASS : GROUP_CLASS;
-  const divider = group.separated ? <GroupDivider /> : null;
+  const groupClass = group.separated ? separatedGroupClassFor(geometry.inset) : groupClassFor(geometry.inset);
+  const divider = group.separated ? <GroupDivider inset={geometry.dividerInset} /> : null;
 
   if (isCollapsible) {
     return (

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

@@ -1,6 +1,7 @@
 /**
  * Peek panel: the full sidebar floated over the page while it is collapsed.
- * Opened and held by `SidebarPeekProvider`.
+ * Opened by hover intent on the left edge (or the trigger zone), held by `SidebarPeekProvider`,
+ * slides in and out (it stays mounted while the exit animation runs).
  */
 
 'use client';
@@ -13,22 +14,36 @@ import { SidebarResizeHandle } from './SidebarResizeHandle';
 
 export function SidebarPeek() {
   const peek = useSidebarPeek();
-  if (!peek?.open) return null;
+  if (!peek) return null;
 
   return (
-    <div
-      data-sidebar="peek"
-      role="complementary"
-      aria-label="Navigation"
-      {...peek.panelProps}
-      className={[
-        'fixed bottom-2 left-2 top-2 z-50 flex w-(--sidebar-width) flex-col overflow-hidden',
-        'rounded-xl border border-sidebar-border bg-sidebar text-sidebar-foreground shadow-2xl',
-        'animate-in fade-in-0 slide-in-from-left-4 duration-150',
-      ].join(' ')}
-    >
-      <SidebarBody />
-      <SidebarResizeHandle />
-    </div>
+    <>
+      {peek.hoverEnabled ? (
+        // Thin hot strip on the left edge: resting the pointer here opens the panel.
+        <div
+          data-sidebar="peek-edge"
+          aria-hidden
+          className="fixed inset-y-0 left-0 z-40 w-1.5"
+          {...peek.zoneProps}
+        />
+      ) : null}
+      {peek.mounted ? (
+        <div
+          data-sidebar="peek"
+          data-state={peek.state}
+          role="complementary"
+          aria-label="Navigation"
+          inert={peek.state === 'closed'}
+          {...peek.panelProps}
+          className={[
+            'private-sidebar-peek fixed bottom-2 left-2 top-2 z-50 flex w-(--sidebar-width) flex-col overflow-hidden',
+            'rounded-xl border border-sidebar-border bg-sidebar text-sidebar-foreground shadow-2xl',
+          ].join(' ')}
+        >
+          <SidebarBody />
+          <SidebarResizeHandle />
+        </div>
+      ) : null}
+    </>
   );
 }

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

@@ -9,11 +9,10 @@ import React, { memo } from 'react';
 import { usePrivateLayoutContext } from '../context';
 import { SidebarFeatured } from './SidebarFeatured';
 
-const SLOT = 'w-full min-w-0 shrink-0 px-2';
-
 function SidebarSlotsRaw() {
-  const { sidebar } = usePrivateLayoutContext();
+  const { sidebar, geometry } = usePrivateLayoutContext();
   if (!sidebar) return null;
+  const SLOT = `w-full min-w-0 shrink-0 ${geometry.inset}`;
 
   return (
     <>

package/src/layouts/PrivateLayout/geometry.ts

@@ -1,17 +1,50 @@
 /**
- * Sidebar row geometry. Two sizes only: a pointer-sized desktop row and a
- * 44px touch row for the mobile drawer.
+ * 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.
  */
 
 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',
+    /** Horizontal inset of groups, slots and the divider; equals the header and footer inset. */
+    inset: 'px-2',
+    dividerInset: 'mx-2',
   },
   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',
   },
 } as const;
 
 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.
+ */
+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))]',
+  },
+  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))]',
+  },
+} as const;
+
+/** The one trigger button: same box and icon size on mobile and desktop. */
+export const TRIGGER_CLASS = 'size-10 shrink-0 [&_svg]:!size-5';
+
+/** Slide duration of the peek panel; keep equal to `--private-sidebar-motion` in dashboard.css. */
+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;

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

@@ -8,3 +8,7 @@ export { useSidebarKeyboard } from './useSidebarKeyboard';
 export { useSidebarDefaultOpen } from './useSidebarDefaultOpen';
 export { SidebarPeekProvider, usePeekPin, useSidebarPeek } from './useSidebarPeek';
 export { SidebarWidthContext, useSidebarWidth, useSidebarWidthContext } from './useSidebarWidth';
+export { useHoverIntent } from './useHoverIntent';
+export type { HoverIntent, HoverIntentOptions } from './useHoverIntent';
+export { usePresence } from './usePresence';
+export type { Presence } from './usePresence';

package/src/layouts/PrivateLayout/hooks/useHoverIntent.test.tsx

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useHoverIntent, type HoverIntent, type HoverIntentOptions } from './useHoverIntent';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let host: HTMLElement;
+let root: Root;
+let intent: HoverIntent;
+
+function Probe(props: HoverIntentOptions) {
+  intent = useHoverIntent(props);
+  return null;
+}
+
+function mount(props: HoverIntentOptions = { openDelay: 400, closeDelay: 250 }) {
+  act(() => root.render(<Probe {...props} />));
+}
+
+const mouse = { pointerType: 'mouse' };
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  host = document.createElement('div');
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  vi.useRealTimers();
+});
+
+describe('useHoverIntent', () => {
+  it('opens only after the open delay', () => {
+    mount();
+    act(() => intent.zoneProps.onPointerEnter(mouse));
+    act(() => void vi.advanceTimersByTime(399));
+    expect(intent.open).toBe(false);
+    act(() => void vi.advanceTimersByTime(1));
+    expect(intent.open).toBe(true);
+  });
+
+  it('a pass-by shorter than the open delay never opens', () => {
+    mount();
+    act(() => intent.zoneProps.onPointerEnter(mouse));
+    act(() => void vi.advanceTimersByTime(200));
+    act(() => intent.zoneProps.onPointerLeave(mouse));
+    act(() => void vi.advanceTimersByTime(1000));
+    expect(intent.open).toBe(false);
+  });
+
+  it('closes after the grace delay, and returning in time keeps it open', () => {
+    mount();
+    act(() => intent.zoneProps.onPointerEnter(mouse));
+    act(() => void vi.advanceTimersByTime(400));
+    expect(intent.open).toBe(true);
+
+    act(() => intent.panelProps.onPointerLeave(mouse));
+    act(() => void vi.advanceTimersByTime(200));
+    act(() => intent.panelProps.onPointerEnter(mouse));
+    act(() => void vi.advanceTimersByTime(1000));
+    expect(intent.open).toBe(true);
+
+    act(() => intent.panelProps.onPointerLeave(mouse));
+    act(() => void vi.advanceTimersByTime(249));
+    expect(intent.open).toBe(true);
+    act(() => void vi.advanceTimersByTime(1));
+    expect(intent.open).toBe(false);
+  });
+
+  it('ignores touch pointers', () => {
+    mount();
+    act(() => intent.zoneProps.onPointerEnter({ pointerType: 'touch' }));
+    act(() => void vi.advanceTimersByTime(1000));
+    expect(intent.open).toBe(false);
+  });
+
+  it('never opens when disabled', () => {
+    mount({ enabled: false });
+    act(() => intent.zoneProps.onPointerEnter(mouse));
+    act(() => void vi.advanceTimersByTime(1000));
+    expect(intent.open).toBe(false);
+  });
+
+  it('stays open while pinned and closes after the grace once released', () => {
+    mount();
+    act(() => intent.zoneProps.onPointerEnter(mouse));
+    act(() => void vi.advanceTimersByTime(400));
+    act(() => intent.pin(true));
+    act(() => intent.panelProps.onPointerLeave(mouse));
+    act(() => void vi.advanceTimersByTime(2000));
+    expect(intent.open).toBe(true);
+    act(() => intent.pin(false));
+    act(() => void vi.advanceTimersByTime(250));
+    expect(intent.open).toBe(false);
+  });
+});

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

@@ -0,0 +1,112 @@
+/**
+ * Hover intent: open only after the pointer has rested for `openDelay`, close only after it has
+ * been away for `closeDelay`. A pass-by shorter than `openDelay` never opens; a quick trip out
+ * and back within `closeDelay` never closes. Touch pointers are ignored.
+ */
+
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { HOVER_CLOSE_DELAY_MS, HOVER_OPEN_DELAY_MS } from '../geometry';
+
+export interface HoverIntentOptions {
+  openDelay?: number;
+  closeDelay?: number;
+  /** False (touch device, docked sidebar): never opens, and closes an open panel at once. */
+  enabled?: boolean;
+}
+
+interface PointerHandlers {
+  onPointerEnter: (e: { pointerType?: string }) => void;
+  onPointerLeave: (e: { pointerType?: string }) => void;
+}
+
+export interface HoverIntent {
+  open: boolean;
+  /** For the hot zone: enter starts the open timer, leave schedules the close. */
+  zoneProps: PointerHandlers;
+  /** For the opened panel: enter opens/keeps at once, leave schedules the close. */
+  panelProps: PointerHandlers;
+  /** Close at once. */
+  close: () => void;
+  /** Hold open (a menu launched from the panel is open); releasing schedules the close. */
+  pin: (pinned: boolean) => void;
+}
+
+export function useHoverIntent({
+  openDelay = HOVER_OPEN_DELAY_MS,
+  closeDelay = HOVER_CLOSE_DELAY_MS,
+  enabled = true,
+}: HoverIntentOptions = {}): HoverIntent {
+  const [open, setOpen] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pinned = useRef(false);
+  const openRef = useRef(false);
+
+  const set = useCallback((value: boolean) => {
+    openRef.current = value;
+    setOpen(value);
+  }, []);
+
+  const cancel = useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+  }, []);
+
+  const scheduleClose = useCallback(() => {
+    cancel();
+    if (!openRef.current || pinned.current) return;
+    timer.current = setTimeout(() => set(false), closeDelay);
+  }, [cancel, closeDelay, set]);
+
+  const close = useCallback(() => {
+    cancel();
+    set(false);
+  }, [cancel, set]);
+
+  const pin = useCallback(
+    (value: boolean) => {
+      pinned.current = value;
+      if (value) cancel();
+      else scheduleClose();
+    },
+    [cancel, scheduleClose],
+  );
+
+  const zoneProps = useMemo<PointerHandlers>(
+    () => ({
+      onPointerEnter: (e) => {
+        if (!enabled || e.pointerType === 'touch') return;
+        cancel();
+        if (openRef.current) return;
+        timer.current = setTimeout(() => set(true), openDelay);
+      },
+      onPointerLeave: (e) => {
+        if (e.pointerType === 'touch') return;
+        scheduleClose();
+        // Not open yet: leaving cancels the pending open (cancel ran in scheduleClose).
+      },
+    }),
+    [enabled, cancel, scheduleClose, set, openDelay],
+  );
+
+  const panelProps = useMemo<PointerHandlers>(
+    () => ({
+      onPointerEnter: () => {
+        cancel();
+        if (enabled) set(true);
+      },
+      onPointerLeave: () => scheduleClose(),
+    }),
+    [enabled, cancel, scheduleClose, set],
+  );
+
+  useEffect(() => {
+    if (!enabled) close();
+  }, [enabled, close]);
+
+  useEffect(() => cancel, [cancel]);
+
+  return { open: enabled && open, zoneProps, panelProps, close, pin };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Presence: keeps an element mounted for `exitMs` after `open` turns false, so its exit
+ * animation can run. With `prefers-reduced-motion` the exit is skipped (unmount at once).
+ */
+
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { useMediaQuery } from '@djangocfg/ui-core/hooks';
+
+import { SIDEBAR_MOTION_MS } from '../geometry';
+
+export interface Presence {
+  /** Render the element. */
+  mounted: boolean;
+  /** Drives `data-state`: `open` while entering/shown, `closed` while exiting. */
+  state: 'open' | 'closed';
+}
+
+export function usePresence(open: boolean, exitMs: number = SIDEBAR_MOTION_MS): Presence {
+  const reduced = useMediaQuery('(prefers-reduced-motion: reduce)');
+  const [lingering, setLingering] = useState(false);
+
+  useEffect(() => {
+    if (open) {
+      setLingering(true);
+      return;
+    }
+    if (reduced || exitMs <= 0) {
+      setLingering(false);
+      return;
+    }
+    const t = setTimeout(() => setLingering(false), exitMs);
+    return () => clearTimeout(t);
+  }, [open, reduced, exitMs]);
+
+  return { mounted: open || lingering, state: open ? 'open' : 'closed' };
+}

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

@@ -1,36 +1,27 @@
 /**
- * Peek: while the sidebar is collapsed, hovering its trigger zone floats the
- * full sidebar over the page. The panel keeps itself open while the pointer is
+ * Peek: while the sidebar is collapsed, resting the pointer on the left edge or the trigger
+ * zone (hover intent) floats the full sidebar over the page. The panel keeps itself open while the pointer is
  * on it, or while a menu opened from it (account, workspace switcher) is open.
  */
 
 'use client';
 
-import React, {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import React, { createContext, useContext, useEffect, useMemo } from 'react';
 
 import { useSidebar } from '@djangocfg/ui-core/components';
+import { useMediaQuery } from '@djangocfg/ui-core/hooks';
 
-// Opens on entry with no delay, then stays at least MIN_OPEN_MS even if the
-// pointer only grazed the zone, so a user who didn't notice it still sees it.
-const MIN_OPEN_MS = 900;
-const CLOSE_DELAY_MS = 300;
+import { useHoverIntent } from './useHoverIntent';
+import type { Presence } from './usePresence';
+import { usePresence } from './usePresence';
 
-interface PointerHandlers {
-  onPointerEnter: (e: React.PointerEvent) => void;
-  onPointerLeave: (e: React.PointerEvent) => void;
-}
+type PointerHandlers = ReturnType<typeof useHoverIntent>['zoneProps'];
 
-export interface SidebarPeek {
+export interface SidebarPeek extends Presence {
   /** True while the sidebar is collapsed on desktop: the trigger zone shows. */
   enabled: boolean;
+  /** Hover-open is live: collapsed, desktop, and a fine (mouse/pen) pointer. */
+  hoverEnabled: boolean;
   open: boolean;
   zoneProps: PointerHandlers;
   panelProps: PointerHandlers;
@@ -64,68 +55,14 @@ interface SidebarPeekProviderProps {
 export function SidebarPeekProvider({ pathname, children }: SidebarPeekProviderProps) {
   const { state, isMobile } = useSidebar();
   const enabled = !isMobile && state === 'collapsed';
+  // Hover is a mouse affordance: only where the primary pointer can hover precisely.
+  const finePointer = useMediaQuery('(hover: hover) and (pointer: fine)');
+  const hoverEnabled = enabled && finePointer;
 
-  const [open, setOpen] = useState(false);
-  const pinned = useRef(false);
-  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const openedAt = useRef(0);
-
-  const cancel = useCallback(() => {
-    if (timer.current) clearTimeout(timer.current);
-    timer.current = null;
-  }, []);
-
-  const scheduleClose = useCallback(() => {
-    cancel();
-    if (pinned.current) return;
-    const grace = openedAt.current + MIN_OPEN_MS - Date.now();
-    timer.current = setTimeout(() => setOpen(false), Math.max(CLOSE_DELAY_MS, grace));
-  }, [cancel]);
-
-  const show = useCallback(() => {
-    cancel();
-    setOpen((was) => {
-      if (!was) openedAt.current = Date.now();
-      return true;
-    });
-  }, [cancel]);
-
-  const close = useCallback(() => {
-    cancel();
-    setOpen(false);
-  }, [cancel]);
-
-  const pin = useCallback(
-    (value: boolean) => {
-      pinned.current = value;
-      if (!value) scheduleClose();
-    },
-    [scheduleClose],
-  );
-
-  // Hover is a mouse affordance; touch taps the trigger to dock instead.
-  const zoneProps = useMemo<PointerHandlers>(
-    () => ({
-      onPointerEnter: (e) => {
-        if (e.pointerType !== 'mouse') return;
-        show();
-      },
-      onPointerLeave: scheduleClose,
-    }),
-    [show, scheduleClose],
-  );
-
-  const panelProps = useMemo<PointerHandlers>(
-    () => ({
-      onPointerEnter: show,
-      onPointerLeave: scheduleClose,
-    }),
-    [show, scheduleClose],
-  );
-
-  useEffect(() => {
-    if (!enabled) close();
-  }, [enabled, close]);
+  const intent = useHoverIntent({ enabled: hoverEnabled });
+  const { close } = intent;
+  const open = enabled && intent.open;
+  const presence = usePresence(open);
 
   useEffect(() => {
     close();
@@ -140,11 +77,19 @@ export function SidebarPeekProvider({ pathname, children }: SidebarPeekProviderP
     return () => window.removeEventListener('keydown', onKey);
   }, [open, close]);
 
-  useEffect(() => cancel, [cancel]);
-
   const value = useMemo<SidebarPeek>(
-    () => ({ enabled, open: enabled && open, zoneProps, panelProps, close, pin }),
-    [enabled, open, zoneProps, panelProps, close, pin],
+    () => ({
+      enabled,
+      hoverEnabled,
+      open,
+      mounted: enabled && presence.mounted,
+      state: presence.state,
+      zoneProps: intent.zoneProps,
+      panelProps: intent.panelProps,
+      close,
+      pin: intent.pin,
+    }),
+    [enabled, hoverEnabled, open, presence.mounted, presence.state, intent.zoneProps, intent.panelProps, close, intent.pin],
   );
 
   return <PeekContext.Provider value={value}>{children}</PeekContext.Provider>;

package/src/styles/dashboard.css

@@ -49,3 +49,30 @@
 [data-sidebar-resizing] [data-variant][data-state] * {
   transition: none !important;
 }
+
+
+/**
+ * Private layout: peek panel slide in and out. Shipped here so consumers need no animation
+ * plugin. Duration mirrors SIDEBAR_MOTION_MS in PrivateLayout/geometry.ts.
+ */
+@keyframes private-sidebar-in {
+  from { opacity: 0; transform: translateX(-1rem); }
+  to { opacity: 1; transform: translateX(0); }
+}
+@keyframes private-sidebar-out {
+  from { opacity: 1; transform: translateX(0); }
+  to { opacity: 0; transform: translateX(-1rem); }
+}
+.private-sidebar-peek[data-state="open"] {
+  animation: private-sidebar-in 180ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+.private-sidebar-peek[data-state="closed"] {
+  animation: private-sidebar-out 180ms ease-in both;
+  pointer-events: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .private-sidebar-peek[data-state="open"],
+  .private-sidebar-peek[data-state="closed"] {
+    animation: none;
+  }
+}