@spree/dashboard-core 0.13.0 → 1.0.0-beta.1

package/src/components/nav-main.tsx

@@ -1,7 +1,9 @@
 import {
+  cn,
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
   SidebarGroup,
   SidebarMenu,
@@ -14,8 +16,9 @@ import {
 } from '@spree/dashboard-ui'
 import { Link, useRouterState } from '@tanstack/react-router'
 import type { LucideIcon } from 'lucide-react'
-import { type ComponentType, useState } from 'react'
-import type { SubjectName } from '../lib/permissions'
+import { type ComponentType, useCallback, useEffect, useRef, useState } from 'react'
+import { isPathWithin } from '../lib/nav-registry'
+import type { ActionName, SubjectName } from '../lib/permissions'
 
 export type NavItem = {
   title: string
@@ -23,9 +26,18 @@ export type NavItem = {
   icon: LucideIcon
   /** CanCanCan subject required to see this item. If omitted, item is always visible. */
   subject?: SubjectName
+  /** Action checked against `subject`. Defaults to `'read'`. */
+  action?: ActionName
   /** Component rendered after the label (e.g. a count badge). May return null. */
   badge?: ComponentType
-  items?: { title: string; url: string; subject?: SubjectName }[]
+  items?: {
+    title: string
+    url: string
+    subject?: SubjectName
+    action?: ActionName
+    /** Component rendered after the label, same contract as the parent's. */
+    badge?: ComponentType
+  }[]
 }
 
 export function NavIcon({ icon: Icon, isActive }: { icon: NavItem['icon']; isActive?: boolean }) {
@@ -41,28 +53,133 @@ export function NavIcon({ icon: Icon, isActive }: { icon: NavItem['icon']; isAct
   )
 }
 
-function CollapsedDropdown({ item, children }: { item: NavItem; children: React.ReactNode }) {
-  const [open, setOpen] = useState(false)
+/** Grace period between leaving the trigger/menu and the menu closing. */
+const HOVER_CLOSE_DELAY_MS = 150
+
+/**
+ * Which collapsed-nav menu is open, shared across the whole rail.
+ *
+ * One value rather than per-item state, so the menus are mutually exclusive by
+ * construction: hovering a neighbour replaces the open key instantly instead of
+ * leaving the previous menu on screen for the close delay, which read as two
+ * panels flickering over each other.
+ */
+interface HoverMenuController {
+  openKey: string | null
+  /** Opens `key` immediately, replacing whatever was open. */
+  open: (key: string) => void
+  /** Schedules a close, but only if `key` is still the open one. */
+  closeSoon: (key: string) => void
+  /** Closes right away — for explicit dismissals (Escape, selecting an item). */
+  closeNow: () => void
+  /** Cancels a pending close (pointer came back). */
+  cancelClose: () => void
+}
+
+function useHoverMenuController(): HoverMenuController {
+  const [openKey, setOpenKey] = useState<string | null>(null)
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const cancelClose = useCallback(() => {
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current)
+      closeTimer.current = null
+    }
+  }, [])
+
+  const open = useCallback(
+    (key: string) => {
+      cancelClose()
+      setOpenKey(key)
+    },
+    [cancelClose],
+  )
+
+  const closeSoon = useCallback(
+    (key: string) => {
+      cancelClose()
+      closeTimer.current = setTimeout(() => {
+        // Guarded so a late timer from the menu the pointer just left can't
+        // close the one it has since moved to.
+        setOpenKey((current) => (current === key ? null : current))
+      }, HOVER_CLOSE_DELAY_MS)
+    },
+    [cancelClose],
+  )
+
+  const closeNow = useCallback(() => {
+    cancelClose()
+    setOpenKey(null)
+  }, [cancelClose])
+
+  useEffect(
+    () => () => {
+      if (closeTimer.current) clearTimeout(closeTimer.current)
+    },
+    [],
+  )
+
+  return { openKey, open, closeSoon, closeNow, cancelClose }
+}
+
+function CollapsedDropdown({
+  item,
+  controller,
+  children,
+}: {
+  item: NavItem
+  controller: HoverMenuController
+  children: React.ReactNode
+}) {
+  const key = item.title
+  const open = controller.openKey === key
+  const openNow = () => controller.open(key)
+  const closeSoon = () => controller.closeSoon(key)
 
   return (
-    <DropdownMenu open={open} onOpenChange={setOpen}>
+    <DropdownMenu
+      open={open}
+      // Base UI's own open/close signals (Escape, outside click, selecting an
+      // item) are explicit dismissals, so they close immediately — the grace
+      // period exists only for the pointer leaving on its way somewhere.
+      onOpenChange={(next) => {
+        if (next) controller.open(key)
+        else controller.closeNow()
+      }}
+    >
       {/* `nativeButton={false}` because the trigger renders a `<div>` wrapping
           a `SidebarMenuButton` (whose inner element is a `<Link>` → `<a>`),
           not a `<button>`. The wrapper exists to attach `onMouseLeave` for
           the hover-out close, so we can't drop it; instead we tell Base UI
           we're rendering a non-button trigger and let it apply menu role +
           keyboard semantics. */}
-      <DropdownMenuTrigger asChild nativeButton={false} onMouseEnter={() => setOpen(true)}>
+      <DropdownMenuTrigger asChild nativeButton={false} onMouseEnter={openNow}>
         {/* biome-ignore lint/a11y/noStaticElementInteractions: hover trigger for collapsed nav */}
-        <div onMouseLeave={() => setOpen(false)}>{children}</div>
+        <div onMouseLeave={closeSoon}>{children}</div>
       </DropdownMenuTrigger>
+      {/* `sideOffset={0}` plus inline-start *padding* closes the dead zone the
+          pointer used to cross: an offset (or a margin) puts those pixels
+          outside both elements, so travelling to the menu reads as leaving
+          both. Padding keeps the gap inside the panel's own hover area, so the
+          visual inset costs nothing in reachability. */}
       <DropdownMenuContent
         side="right"
         align="start"
-        sideOffset={4}
-        onMouseLeave={() => setOpen(false)}
-        onMouseEnter={() => setOpen(true)}
+        sideOffset={0}
+        className="ps-1"
+        onMouseLeave={closeSoon}
+        onMouseEnter={openNow}
       >
+        {/* The section itself leads the list. Collapsed, the icon is the only
+            route to it, and hovering opens this panel instead — so without an
+            entry here "Products" is reachable by a click most people won't
+            guess at, and not at all by keyboard. */}
+        <DropdownMenuItem asChild>
+          <Link to={item.url} className="no-underline font-medium">
+            {item.title}
+          </Link>
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
         {item.items!.map((subItem) => (
           <DropdownMenuItem key={subItem.title} asChild>
             <Link to={subItem.url} className="no-underline">
@@ -79,19 +196,24 @@ function NavItemContent({
   item,
   currentPath,
   isCollapsed,
+  isMobile,
+  hoverMenu,
 }: {
   item: NavItem
   currentPath: string
   isCollapsed: boolean
+  isMobile: boolean
+  hoverMenu: HoverMenuController
 }) {
   const isExactActive = currentPath === item.url || currentPath === `${item.url}/`
   // Only prefix-match for items with a sub-path after the storeId segment (e.g. /store_abc/orders)
   const hasSubPath = item.url.split('/').filter(Boolean).length > 1
-  const isActive = isExactActive || (hasSubPath && currentPath.startsWith(item.url))
-  const hasActiveChild = item.items?.some(
-    (sub) => currentPath === sub.url || currentPath.startsWith(sub.url),
-  )
-  const showSubmenu = isActive || hasActiveChild
+  const isActive = isExactActive || (hasSubPath && isPathWithin(currentPath, item.url))
+  const hasActiveChild = item.items?.some((sub) => isPathWithin(currentPath, sub.url))
+  // Desktop reveals children on hover or when the section is active. Touch has
+  // no hover, and the drawer closes on navigation, so a collapsed child would
+  // take three taps to reach — show every child up front instead.
+  const showSubmenu = isMobile || isActive || hasActiveChild
   const itemIsActive = isActive || !!hasActiveChild
 
   const button = (
@@ -100,14 +222,19 @@ function NavItemContent({
       asChild
       isActive={itemIsActive}
     >
-      <Link to={item.url}>
+      {/* `aria-label` because the visible label is hidden in collapsed icon
+          mode, which would otherwise leave the link with no accessible name —
+          an icon-only link is unusable to a screen reader. */}
+      <Link to={item.url} aria-label={isCollapsed ? item.title : undefined}>
         <NavIcon icon={item.icon} isActive={itemIsActive} />
         {/* Explicitly hide in collapsed icon mode: a trailing badge span would
             otherwise steal the `span:last-child` position the base button style
             relies on to hide the label, leaving the title visible. */}
         <span className="group-data-[collapsible=icon]:hidden">{item.title}</span>
+        {/* `shrink-0` so the badge keeps its shape while the sidebar width
+            animates — a squeezed badge deforms before the label clips. */}
         {item.badge && (
-          <span className="ml-auto group-data-[collapsible=icon]:hidden">
+          <span className="ml-auto shrink-0 group-data-[collapsible=icon]:hidden">
             <item.badge />
           </span>
         )}
@@ -116,21 +243,31 @@ function NavItemContent({
   )
 
   return (
-    <SidebarMenuItem>
+    // Hovering an item with no submenu dismisses whatever menu is open: the
+    // pointer has clearly moved on, and leaving a neighbour's panel hanging
+    // over the rail reads as a stuck popup.
+    <SidebarMenuItem onMouseEnter={isCollapsed && !item.items ? hoverMenu.closeNow : undefined}>
       {isCollapsed && item.items ? (
-        <CollapsedDropdown item={item}>{button}</CollapsedDropdown>
+        <CollapsedDropdown item={item} controller={hoverMenu}>
+          {button}
+        </CollapsedDropdown>
       ) : (
         button
       )}
       {item.items && showSubmenu && (
         <SidebarMenuSub>
           {item.items.map((subItem) => {
-            const subActive = currentPath === subItem.url || currentPath.startsWith(subItem.url)
+            const subActive = isPathWithin(currentPath, subItem.url)
             return (
               <SidebarMenuSubItem key={subItem.title}>
                 <SidebarMenuSubButton asChild isActive={subActive}>
                   <Link to={subItem.url}>
                     <span>{subItem.title}</span>
+                    {subItem.badge && (
+                      <span className="ml-auto">
+                        <subItem.badge />
+                      </span>
+                    )}
                   </Link>
                 </SidebarMenuSubButton>
               </SidebarMenuSubItem>
@@ -145,11 +282,35 @@ function NavItemContent({
 export function NavMain({ items, bottomItems }: { items: NavItem[]; bottomItems?: NavItem[] }) {
   const routerState = useRouterState()
   const currentPath = routerState.location.pathname
-  const { state } = useSidebar()
+  const { state, isMobile, setOpenMobile } = useSidebar()
   const isCollapsed = state === 'collapsed'
+  // Close the drawer as the link is tapped. Done here rather than in an effect
+  // watching the path: this tree renders *inside* the Sheet, so it remounts on
+  // every open and an effect could not tell "just opened" from "just navigated".
+  const handleLinkTap = useCallback(
+    (event: React.MouseEvent) => {
+      if (isMobile && (event.target as HTMLElement).closest('a')) setOpenMobile(false)
+    },
+    [isMobile, setOpenMobile],
+  )
+  // One controller for the whole rail so only a single hover menu is ever open.
+  const hoverMenu = useHoverMenuController()
+
+  // Expanding the rail unmounts the dropdowns but leaves `openKey` set, so
+  // collapsing again would restore a menu the user never opened.
+  const { closeNow } = hoverMenu
+  useEffect(() => {
+    if (!isCollapsed) closeNow()
+  }, [isCollapsed, closeNow])
 
   return (
-    <>
+    // The close handler sits on the list rather than each `<Link>`: those links
+    // are rendered through nested `asChild` Slots (Tooltip → SidebarMenuButton),
+    // which clone their own `onClick` over anything the child declares. A
+    // bubble-phase listener here sees the tap regardless.
+    // biome-ignore lint/a11y/noStaticElementInteractions: delegated link taps only
+    // biome-ignore lint/a11y/useKeyWithClickEvents: links keep their own keyboard behaviour
+    <div onClick={handleLinkTap} className="contents">
       <SidebarGroup>
         <SidebarMenu>
           {items.map((item) => (
@@ -158,22 +319,31 @@ export function NavMain({ items, bottomItems }: { items: NavItem[]; bottomItems?
               item={item}
               currentPath={currentPath}
               isCollapsed={isCollapsed}
+              isMobile={isMobile}
+              hoverMenu={hoverMenu}
             />
           ))}
         </SidebarMenu>
       </SidebarGroup>
 
       {bottomItems && bottomItems.length > 0 && (
-        <SidebarGroup className="mt-auto mb-2">
+        // `mt-auto` pins Settings to the foot of the desktop rail. In a
+        // full-height drawer that strands it alone below a screen of empty
+        // space, so on mobile it simply follows the list.
+        <SidebarGroup className={cn('mb-2', !isMobile && 'mt-auto')}>
           <SidebarMenu>
             {bottomItems.map((item) => {
               const isActive =
-                currentPath === item.url || (item.url !== '/' && currentPath.startsWith(item.url))
+                currentPath === item.url ||
+                (item.url !== '/' && isPathWithin(currentPath, item.url))
 
               return (
                 <SidebarMenuItem key={item.title}>
                   <SidebarMenuButton tooltip={item.title} asChild isActive={isActive}>
-                    <Link to={item.url}>
+                    {/* `aria-label` for the same reason as the main nav above:
+                        collapsed mode hides the label, and Settings lives here
+                        — the one place the rail is collapsed by default. */}
+                    <Link to={item.url} aria-label={isCollapsed ? item.title : undefined}>
                       <NavIcon icon={item.icon} isActive={isActive} />
                       <span>{item.title}</span>
                     </Link>
@@ -184,6 +354,6 @@ export function NavMain({ items, bottomItems }: { items: NavItem[]; bottomItems?
           </SidebarMenu>
         </SidebarGroup>
       )}
-    </>
+    </div>
   )
 }