@djangocfg/layouts 2.1.604 → 2.1.606

package/src/layouts/AuthLayout/styles/oauth.css

@@ -0,0 +1,33 @@
+/**
+ * Provider sign-in (components/oauth). The buttons themselves are theme-token
+ * utilities in `OAuthProviderButton`; this file holds only what a utility
+ * cannot: the column, the room held while the provider list loads, and the
+ * developer hint. Sizes are tokens so the reserve and the buttons agree.
+ */
+
+:root {
+  /* A provider button is at least this tall (above the 44px touch minimum). */
+  --auth-oauth-height: 3rem;
+  --auth-oauth-gap: 0.75rem;
+}
+
+.auth-oauth {
+  display: flex;
+  flex-direction: column;
+  gap: var(--auth-oauth-gap);
+}
+
+/* Holds the room of two buttons, the gap and the divider while the server's
+   provider list loads, so the email field does not jump when it arrives. */
+.auth-oauth-reserve {
+  height: calc(2 * var(--auth-oauth-height) + var(--auth-oauth-gap) + var(--auth-gap) + 1rem);
+}
+
+/* The line for whoever deploys the site, under a notice about configuration. */
+.auth-oauth-hint {
+  margin-top: 0.5rem;
+  color: var(--auth-muted);
+  font-size: 0.75rem;
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+}

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 };
+}