@gentleduck/docs 0.0.13 → 0.0.16

package/src/components/docs/docs-sidebar.tsx

@@ -3,13 +3,29 @@
 import { type DocsConfig, useDocsConfig } from '@duck-docs/context'
 import type { SidebarNavItem } from '@duck-docs/types/nav'
 import { cn } from '@gentleduck/libs/cn'
+import { ChevronRight } from 'lucide-react'
 import Link from 'next/link'
 import { usePathname } from 'next/navigation'
+import * as React from 'react'
 
 export interface DocsSidebarNavProps {
   config?: DocsConfig
 }
 
+function isPathActive(pathname: string, href: string) {
+  return pathname === href || (href !== '/docs' && pathname.startsWith(`${href}/`))
+}
+
+function isPathCurrent(pathname: string, href: string) {
+  return pathname === href
+}
+
+function hasActivePath(item: SidebarNavItem, pathname: string | null): boolean {
+  if (!pathname) return false
+  if (item.href && isPathActive(pathname, item.href)) return true
+  return Boolean(item.items?.some((child) => hasActivePath(child, pathname)))
+}
+
 export function DocsSidebarNav({ config }: DocsSidebarNavProps) {
   const pathname = usePathname()
   const fallbackConfig = useDocsConfig()
@@ -31,7 +47,7 @@ export function DocsSidebarNav({ config }: DocsSidebarNavProps) {
 // Memoized category component to prevent unnecessary re-renders
 const CategoryItem = ({ item, pathname }: { item: SidebarNavItem; pathname: string | null }) => {
   return (
-    <div className="mb-2 flex flex-col gap-1">
+    <div className="mb-2 flex flex-col">
       <div className="flex h-[36px] w-full items-center justify-between text-start font-semibold text-sm [&>div]:w-full [&>div]:justify-between">
         {item.title}
         {item.label && (
@@ -41,7 +57,9 @@ const CategoryItem = ({ item, pathname }: { item: SidebarNavItem; pathname: stri
         )}
       </div>
       <div className="border-l">
-        {item?.items?.length && <DocsSidebarNavItems items={item.items} pathname={pathname} />}
+        {item?.items?.length && (
+          <DocsSidebarNavItems accordionDefault={Boolean(item.collapsible)} items={item.items} pathname={pathname} />
+        )}
       </div>
     </div>
   )
@@ -51,55 +69,202 @@ interface DocsSidebarNavItemsProps {
   items: SidebarNavItem[]
   pathname: string | null
   className?: string
+  depth?: number
+  accordionDefault?: boolean
 }
 
-export function DocsSidebarNavItems({ items, pathname }: DocsSidebarNavItemsProps) {
+export function DocsSidebarNavItems({
+  items,
+  pathname,
+  className,
+  depth = 0,
+  accordionDefault = false,
+}: DocsSidebarNavItemsProps) {
+  const activeAccordionIndex = React.useMemo(
+    () =>
+      items.findIndex((item) => {
+        const hasChildren = Boolean(item.items?.length)
+        const isAccordionItem = hasChildren && Boolean(item.collapsible ?? accordionDefault)
+        return isAccordionItem && hasActivePath(item, pathname)
+      }),
+    [items, pathname, accordionDefault],
+  )
+
   return (
     items?.length && (
-      <ul>
+      <ul className={cn(depth > 0 && 'ml-3 border-l', className)}>
         {items.map((item, index) => (
-          <DocsSidebarNavItem item={item} key={index} pathname={pathname} />
+          <DocsSidebarNavItem
+            accordionDefault={accordionDefault}
+            depth={depth}
+            forceClose={activeAccordionIndex !== -1 && activeAccordionIndex !== index}
+            forceOpen={activeAccordionIndex === index}
+            item={item}
+            key={index}
+            pathname={pathname}
+          />
         ))}
       </ul>
     )
   )
 }
 
-export function DocsSidebarNavItem({ item, pathname }: { item: SidebarNavItem; pathname: string | null }) {
+export function DocsSidebarNavItem({
+  item,
+  pathname,
+  depth = 0,
+  accordionDefault = false,
+  forceOpen = false,
+  forceClose = false,
+}: {
+  item: SidebarNavItem
+  pathname: string | null
+  depth?: number
+  accordionDefault?: boolean
+  forceOpen?: boolean
+  forceClose?: boolean
+}) {
+  const hasChildren = Boolean(item.items?.length)
+  const isAccordionItem = hasChildren && Boolean(item.collapsible ?? accordionDefault)
+  const isCurrent = Boolean(pathname && item.href && isPathCurrent(pathname, item.href))
+  const isActiveBranch = hasActivePath(item, pathname)
+  const isActive = isCurrent || (hasChildren && isActiveBranch)
+  const [isOpen, setIsOpen] = React.useState(() => {
+    if (!isAccordionItem) return true
+    return isActiveBranch || Boolean(item.defaultOpen)
+  })
+
+  React.useEffect(() => {
+    if (!isAccordionItem) return
+    if (forceOpen || isActiveBranch) {
+      setIsOpen(true)
+      return
+    }
+    if (forceClose) {
+      setIsOpen(false)
+    }
+  }, [isAccordionItem, forceOpen, forceClose, isActiveBranch])
+
   if (item.href && !item.disabled) {
     return (
-      <li className={cn(pathname === item.href && 'border-primary border-l')}>
-        <Link
-          className={cn(
-            'group flex w-full items-center border-primary px-4 py-1 font-medium text-sm focus-visible:border-l focus-visible:outline-none',
-            pathname === item.href ? 'font-medium text-foreground' : 'text-muted-foreground',
+      <li className={cn(isActive && 'border-primary border-l')}>
+        <div className="flex items-center">
+          <Link
+            aria-current={isCurrent ? 'page' : undefined}
+            className={cn(
+              'group flex w-full items-center border-primary px-4 py-1 font-medium text-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+              depth > 0 && 'px-3',
+              isActive ? 'font-medium text-foreground' : 'text-muted-foreground',
+            )}
+            href={item.href}
+            scroll
+            rel={item.external ? 'noreferrer' : ''}
+            target={item.external ? '_blank' : ''}>
+            {item.title}
+            {item.label && (
+              <span className="ml-2 rounded-md bg-primary px-1.5 py-0.5 font-medium text-accent text-xs leading-none no-underline group-hover:no-underline">
+                {item.label}
+              </span>
+            )}
+            {item.external && <span className="sr-only"> (opens in a new tab)</span>}
+          </Link>
+          {isAccordionItem && (
+            <button
+              aria-expanded={isOpen}
+              aria-label={`Toggle ${item.title}`}
+              className="relative mr-1 inline-flex size-6 items-center justify-center rounded-sm text-muted-foreground transition-colors after:absolute after:-inset-2 after:content-[''] hover:bg-accent hover:text-foreground"
+              onClick={(event) => {
+                event.preventDefault()
+                event.stopPropagation()
+                setIsOpen((open) => !open)
+              }}
+              type="button">
+              <ChevronRight aria-hidden="true" className={cn('size-3 transition-transform', isOpen && 'rotate-90')} />
+            </button>
           )}
-          href={item.href}
-          scroll
-          rel={item.external ? 'noreferrer' : ''}
-          target={item.external ? '_blank' : ''}>
+        </div>
+        {hasChildren &&
+          (isAccordionItem ? (
+            <AnimatedHeightCollapse open={isOpen}>
+              <DocsSidebarNavItems
+                accordionDefault={accordionDefault}
+                depth={depth + 1}
+                items={item.items ?? []}
+                pathname={pathname}
+              />
+            </AnimatedHeightCollapse>
+          ) : (
+            <DocsSidebarNavItems
+              accordionDefault={accordionDefault}
+              depth={depth + 1}
+              items={item.items ?? []}
+              pathname={pathname}
+            />
+          ))}
+      </li>
+    )
+  }
+
+  return (
+    <li>
+      <div className="flex items-center">
+        <span
+          className={cn(
+            'flex w-full cursor-not-allowed items-center rounded-md p-2 text-muted-foreground hover:underline',
+            depth > 0 && 'px-3',
+          )}>
           {item.title}
           {item.label && (
-            <span className="ml-2 rounded-md bg-primary px-1.5 py-0.5 font-medium text-accent text-xs leading-none no-underline group-hover:no-underline">
+            <span className="ml-2 rounded-md bg-muted px-1.5 py-0.5 text-muted-foreground text-sm leading-none no-underline group-hover:no-underline">
               {item.label}
             </span>
           )}
-        </Link>
-      </li>
-    )
-  }
+        </span>
+        {isAccordionItem && (
+          <button
+            aria-expanded={isOpen}
+            aria-label={`Toggle ${item.title}`}
+            className="relative mr-1 inline-flex size-6 items-center justify-center rounded-sm text-muted-foreground transition-colors after:absolute after:-inset-2 after:content-[''] hover:bg-accent hover:text-foreground"
+            onClick={() => {
+              setIsOpen((open) => !open)
+            }}
+            type="button">
+            <ChevronRight aria-hidden="true" className={cn('size-3 transition-transform', isOpen && 'rotate-90')} />
+          </button>
+        )}
+      </div>
+      {hasChildren &&
+        (isAccordionItem ? (
+          <AnimatedHeightCollapse open={isOpen}>
+            <DocsSidebarNavItems
+              accordionDefault={accordionDefault}
+              depth={depth + 1}
+              items={item.items ?? []}
+              pathname={pathname}
+            />
+          </AnimatedHeightCollapse>
+        ) : (
+          <DocsSidebarNavItems
+            accordionDefault={accordionDefault}
+            depth={depth + 1}
+            items={item.items ?? []}
+            pathname={pathname}
+          />
+        ))}
+    </li>
+  )
+}
 
+function AnimatedHeightCollapse({ open, children }: { open: boolean; children: React.ReactNode }) {
   return (
-    <span
+    <div
+      aria-hidden={!open}
       className={cn(
-        'flex w-full cursor-not-allowed items-center rounded-md p-2 text-muted-foreground hover:underline',
-      )}>
-      {item.title}
-      {item.label && (
-        <span className="ml-2 rounded-md bg-muted px-1.5 py-0.5 text-muted-foreground text-sm leading-none no-underline group-hover:no-underline">
-          {item.label}
-        </span>
+        'grid transition-[grid-template-rows] duration-300 ease-(--duck-motion-ease)',
+        open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]',
       )}
-    </span>
+      inert={!open || undefined}>
+      <div className={cn('overflow-hidden', !open && 'invisible')}>{children}</div>
+    </div>
   )
 }

package/src/components/docs/docs-toc.tsx

@@ -3,35 +3,44 @@
 import type { TocEntry } from '@duck-docs/context'
 import { useMounted } from '@duck-docs/hooks/use-mounted'
 import { cn } from '@gentleduck/libs/cn'
+import { BookOpenText } from 'lucide-react'
 import * as React from 'react'
 
+// -- Types -------------------------------------------------------------------
+
 interface TocProps {
   toc: TocEntry[]
 }
 
-export function DashboardTableOfContents({ toc }: TocProps) {
-  const itemIds = React.useMemo(
-    () =>
-      toc
-        ? toc
-            .flatMap((item) => [item.url, item?.items?.map((item) => item.url)])
-            .flat()
-            .filter(Boolean)
-            .map((id) => id?.split('#')[1])
-        : [],
-    [toc],
-  )
-  const activeHeading = useActiveItem(itemIds)
-  const mounted = useMounted()
+interface FlatTocItem {
+  url: string
+  title: string
+  depth: number
+}
 
-  return mounted ? (
-    <div className="space-y-2">
-      <p className="font-medium">On This Page</p>
-      <Tree activeItem={activeHeading} tree={toc} />
-    </div>
-  ) : null
+// -- Helpers -----------------------------------------------------------------
+
+function flattenToc(toc: TocEntry[], depth = 1): FlatTocItem[] {
+  const result: FlatTocItem[] = []
+  for (const entry of toc) {
+    result.push({ url: entry.url, title: entry.title, depth })
+    if (entry.items && depth < 2) {
+      result.push(...flattenToc(entry.items, depth + 1))
+    }
+  }
+  return result
 }
 
+function lineOffset(depth: number): number {
+  return depth >= 2 ? 12 : 0
+}
+
+function itemPadding(depth: number): number {
+  return depth >= 2 ? 28 : 16
+}
+
+// -- Hooks -------------------------------------------------------------------
+
 function useActiveItem(itemIds: (string | undefined)[]) {
   const [activeId, setActiveId] = React.useState<string>('')
 
@@ -44,30 +53,20 @@ function useActiveItem(itemIds: (string | undefined)[]) {
           }
         })
       },
-      { rootMargin: `0% 0% -80% 0%` },
+      { rootMargin: '0% 0% -80% 0%' },
     )
 
     itemIds?.forEach((id) => {
-      if (!id) {
-        return
-      }
-
+      if (!id) return
       const element = document.getElementById(id)
-      if (element) {
-        observer.observe(element)
-      }
+      if (element) observer.observe(element)
     })
 
     return () => {
       itemIds?.forEach((id) => {
-        if (!id) {
-          return
-        }
-
+        if (!id) return
         const element = document.getElementById(id)
-        if (element) {
-          observer.unobserve(element)
-        }
+        if (element) observer.unobserve(element)
       })
     }
   }, [itemIds])
@@ -75,30 +74,208 @@ function useActiveItem(itemIds: (string | undefined)[]) {
   return activeId
 }
 
-interface TreeProps {
-  tree: TocEntry[]
-  level?: number
-  activeItem?: string | null
+function useTocThumb(containerRef: React.RefObject<HTMLDivElement | null>, activeItem: string): [number, number] {
+  const [pos, setPos] = React.useState<[number, number]>([0, 0])
+
+  React.useEffect(() => {
+    const container = containerRef.current
+    if (!activeItem || !container || container.clientHeight === 0) {
+      setPos([0, 0])
+      return
+    }
+
+    const el = container.querySelector<HTMLElement>(`a[href="#${activeItem}"]`)
+    if (!el) {
+      setPos([0, 0])
+      return
+    }
+
+    const styles = getComputedStyle(el)
+    const top = el.offsetTop + parseFloat(styles.paddingTop)
+    const bottom = el.offsetTop + el.clientHeight - parseFloat(styles.paddingBottom)
+    setPos([top, bottom - top])
+  }, [activeItem, containerRef])
+
+  return pos
+}
+
+function useTocSvg(containerRef: React.RefObject<HTMLDivElement | null>, items: FlatTocItem[]) {
+  const [svg, setSvg] = React.useState<{ path: string; width: number; height: number } | null>(null)
+
+  React.useEffect(() => {
+    const container = containerRef.current
+    if (!container || container.clientHeight === 0) return
+
+    function compute() {
+      if (!container) return
+      let w = 0
+      let h = 0
+      const d: string[] = []
+      let previousOffset = 0
+      let previousBottom = 0
+      let hasStarted = false
+
+      for (const item of items) {
+        const el = container.querySelector<HTMLElement>(`a[href="${item.url}"]`)
+        if (!el) continue
+
+        const styles = getComputedStyle(el)
+        const offset = lineOffset(item.depth) + 1
+        const top = el.offsetTop + parseFloat(styles.paddingTop)
+        const bottom = el.offsetTop + el.clientHeight - parseFloat(styles.paddingBottom)
+
+        w = Math.max(offset, w)
+        h = Math.max(h, bottom)
+
+        if (!hasStarted) {
+          d.push(`M${offset} ${top}`)
+          d.push(`L${offset} ${bottom}`)
+          hasStarted = true
+        } else {
+          // Connect stacked items (including depth changes) with one continuous path.
+          if (top !== previousBottom || offset !== previousOffset) {
+            d.push(`L${offset} ${top}`)
+          }
+          d.push(`L${offset} ${bottom}`)
+        }
+
+        previousOffset = offset
+        previousBottom = bottom
+      }
+
+      setSvg(d.length > 0 ? { path: d.join(' '), width: w + 1, height: h } : null)
+    }
+
+    const observer = new ResizeObserver(compute)
+    compute()
+    observer.observe(container)
+    return () => observer.disconnect()
+  }, [items])
+
+  return svg
+}
+
+// -- Skeleton ----------------------------------------------------------------
+
+function TocSkeleton({ toc }: TocProps) {
+  const skeletonItems = React.useMemo(() => {
+    const items: { level: number; width: string }[] = []
+    for (const entry of toc) {
+      const chars = entry.title.length
+      items.push({ level: 1, width: `${Math.min(Math.max(chars * 8, 80), 200)}px` })
+      if (entry.items) {
+        for (const sub of entry.items) {
+          const subChars = sub.title.length
+          items.push({ level: 2, width: `${Math.min(Math.max(subChars * 7, 64), 160)}px` })
+        }
+      }
+    }
+    return items
+  }, [toc])
+
+  return (
+    <ul className="m-0 list-none">
+      {skeletonItems.map((item, i) => (
+        <li key={i} className={cn('mt-0 pt-2', { 'pl-4': item.level > 1 })}>
+          <div className="h-3.5 animate-pulse rounded-full bg-muted/70" style={{ width: item.width }} />
+        </li>
+      ))}
+    </ul>
+  )
 }
 
-function Tree({ tree, level = 1, activeItem }: TreeProps) {
-  return tree.length && level < 3 ? (
-    <ul className={cn('m-0 list-none', { 'pl-4': level !== 1 })}>
-      {tree.map((item, index) => {
+// -- TocTree -----------------------------------------------------------------
+
+function TocTree({ items, activeItem }: { items: FlatTocItem[]; activeItem: string }) {
+  const containerRef = React.useRef<HTMLDivElement>(null)
+  const thumb = useTocThumb(containerRef, activeItem)
+  const svg = useTocSvg(containerRef, items)
+
+  return (
+    <div ref={containerRef} className="relative">
+      {/* Shared SVG track for smoother joins and anti-aliased rendering */}
+      {svg ? (
+        <svg
+          aria-hidden="true"
+          className="pointer-events-none absolute start-0 top-0"
+          height={svg.height}
+          style={{ width: svg.width }}
+          viewBox={`0 0 ${svg.width} ${svg.height}`}
+          width={svg.width}>
+          <path
+            d={svg.path}
+            fill="none"
+            stroke="currentColor"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={1}
+            className="text-muted-foreground/20"
+          />
+        </svg>
+      ) : null}
+
+      {/* Link labels */}
+      {items.map((item, i) => {
         return (
-          <li className={cn('mt-0 pt-2')} key={index}>
-            <a
-              className={cn(
-                'inline-block no-underline',
-                item.url === `#${activeItem}` ? 'font-medium text-primary' : 'text-muted-foreground text-sm',
-              )}
-              href={item.url}>
-              {item.title}
-            </a>
-            {item.items?.length ? <Tree activeItem={activeItem} level={level + 1} tree={item.items} /> : null}
-          </li>
+          <a
+            key={i}
+            href={item.url}
+            className={cn(
+              'relative block py-1.5 no-underline transition-colors [overflow-wrap:anywhere]',
+              item.url === `#${activeItem}`
+                ? 'font-medium text-primary'
+                : 'text-muted-foreground text-sm hover:text-foreground',
+            )}
+            style={{ paddingInlineStart: `${itemPadding(item.depth)}px` }}>
+            {item.title}
+          </a>
         )
       })}
-    </ul>
-  ) : null
+
+      {/* Active highlight -- masked by the SVG path */}
+      {svg ? (
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute start-0 top-0"
+          style={{
+            width: svg.width,
+            height: svg.height,
+            maskImage: `url("data:image/svg+xml,${encodeURIComponent(
+              `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${svg.width} ${svg.height}"><path d="${svg.path}" stroke="black" stroke-width="2" fill="none" /></svg>`,
+            )}")`,
+          }}>
+          <div
+            className="bg-primary transition-all duration-300 ease-out"
+            style={{
+              marginTop: thumb[0],
+              height: thumb[1],
+            }}
+          />
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+// -- Main component ----------------------------------------------------------
+
+export function DashboardTableOfContents({ toc }: TocProps) {
+  const flatItems = React.useMemo(() => flattenToc(toc), [toc])
+  const itemIds = React.useMemo(() => flatItems.map((item) => item.url.split('#')[1]).filter(Boolean), [flatItems])
+  const activeHeading = useActiveItem(itemIds)
+  const mounted = useMounted()
+
+  if (!toc.length) return null
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col gap-2">
+      <div className="flex shrink-0 items-center gap-2">
+        <BookOpenText aria-hidden="true" className="size-4" />
+        <p className="font-medium">On This Page</p>
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        {mounted ? <TocTree activeItem={activeHeading} items={flatItems} /> : <TocSkeleton toc={toc} />}
+      </div>
+    </div>
+  )
 }