@usecross/docs 0.6.0 → 0.8.0

package/src/components/DocSetSelector.tsx

@@ -0,0 +1,239 @@
+import { useState, useRef, useEffect } from 'react'
+import { router } from '@inertiajs/react'
+import { cn } from '../lib/utils'
+import type { DocSetMeta } from '../types'
+
+interface DocSetSelectorProps {
+  docSets: DocSetMeta[]
+  currentDocSet: string
+  className?: string
+}
+
+// Chevron icon with up/down indicators like Fumadocs
+const ChevronUpDownIcon = ({ className }: { className?: string }) => (
+  <svg
+    className={className}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M5 6l3-3 3 3M5 10l3 3 3-3"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+)
+
+// Checkmark for selected state
+const CheckIcon = ({ className }: { className?: string }) => (
+  <svg
+    className={className}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M3.5 8.5l3 3 6-6.5"
+      stroke="currentColor"
+      strokeWidth="1.75"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+)
+
+// Default package/docs icon when no iconUrl is provided
+const PackageIcon = ({ className }: { className?: string }) => (
+  <svg
+    className={className}
+    viewBox="0 0 20 20"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path
+      d="M10 2L17 6v8l-7 4-7-4V6l7-4z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M10 10v8M10 10l7-4M10 10L3 6"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+)
+
+/**
+ * Dropdown selector for switching between documentation sets.
+ * Inspired by Fumadocs design - clean and minimal.
+ */
+export function DocSetSelector({ docSets, currentDocSet, className }: DocSetSelectorProps) {
+  const [isOpen, setIsOpen] = useState(false)
+  const dropdownRef = useRef<HTMLDivElement>(null)
+
+  const current = docSets.find((ds) => ds.slug === currentDocSet) || docSets[0]
+
+  // Close dropdown when clicking outside
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false)
+      }
+    }
+
+    if (isOpen) {
+      document.addEventListener('mousedown', handleClickOutside)
+      return () => document.removeEventListener('mousedown', handleClickOutside)
+    }
+  }, [isOpen])
+
+  // Close on escape key
+  useEffect(() => {
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setIsOpen(false)
+    }
+
+    if (isOpen) {
+      document.addEventListener('keydown', handleEscape)
+      return () => document.removeEventListener('keydown', handleEscape)
+    }
+  }, [isOpen])
+
+  const handleSelect = (docSet: DocSetMeta) => {
+    setIsOpen(false)
+    if (docSet.slug !== currentDocSet) {
+      router.visit(`${docSet.prefix}/`)
+    }
+  }
+
+  return (
+    <div className={cn('relative', className)} ref={dropdownRef}>
+      {/* Trigger Button - Clean, flat design like Fumadocs */}
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className={cn(
+          'w-full flex items-center gap-2.5 px-3 py-2',
+          'bg-gray-100/80 dark:bg-white/5',
+          'border border-gray-200 dark:border-white/10',
+          'rounded-lg',
+          'hover:bg-gray-200/80 dark:hover:bg-white/10',
+          'transition-colors duration-150',
+          'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50'
+        )}
+        aria-label="Select documentation"
+        aria-expanded={isOpen}
+        aria-haspopup="listbox"
+      >
+        {/* Icon */}
+        <div className="flex-shrink-0 w-5 h-5 flex items-center justify-center text-gray-600 dark:text-gray-400">
+          {current.icon ? (
+            <span className="text-base leading-none">{current.icon}</span>
+          ) : current.iconUrl ? (
+            <img src={current.iconUrl} alt="" className="w-5 h-5" />
+          ) : (
+            <PackageIcon className="w-5 h-5" />
+          )}
+        </div>
+
+        {/* Text */}
+        <span className="flex-1 text-left text-sm font-medium text-gray-900 dark:text-white truncate">
+          {current.name}
+        </span>
+
+        {/* Chevron */}
+        <ChevronUpDownIcon className="flex-shrink-0 w-4 h-4 text-gray-400 dark:text-gray-500" />
+      </button>
+
+      {/* Dropdown Menu */}
+      <div
+        className={cn(
+          'absolute left-0 right-0 mt-1.5',
+          'py-1',
+          'bg-white dark:bg-[#1a1a1a]',
+          'border border-gray-200 dark:border-white/10',
+          'rounded-lg',
+          'shadow-lg shadow-black/5 dark:shadow-black/30',
+          'z-50',
+          'transition-all duration-150 ease-out origin-top',
+          isOpen
+            ? 'opacity-100 scale-100'
+            : 'opacity-0 scale-95 pointer-events-none'
+        )}
+        role="listbox"
+        aria-label="Select documentation set"
+      >
+        {docSets.map((docSet) => {
+          const isSelected = docSet.slug === currentDocSet
+
+          return (
+            <button
+              key={docSet.slug || '_root'}
+              onClick={() => handleSelect(docSet)}
+              className={cn(
+                'w-full flex items-center gap-2.5 px-3 py-2',
+                'transition-colors duration-100',
+                'focus:outline-none',
+                isSelected
+                  ? 'bg-primary-50 dark:bg-primary-500/10'
+                  : 'hover:bg-gray-50 dark:hover:bg-white/5'
+              )}
+              role="option"
+              aria-selected={isSelected}
+            >
+              {/* Icon */}
+              <div className={cn(
+                'flex-shrink-0 w-5 h-5 flex items-center justify-center',
+                isSelected
+                  ? 'text-primary-600 dark:text-primary-400'
+                  : 'text-gray-500 dark:text-gray-400'
+              )}>
+                {docSet.icon ? (
+                  <span className="text-base leading-none">{docSet.icon}</span>
+                ) : docSet.iconUrl ? (
+                  <img src={docSet.iconUrl} alt="" className="w-5 h-5" />
+                ) : (
+                  <PackageIcon className="w-5 h-5" />
+                )}
+              </div>
+
+              {/* Text Content */}
+              <div className="flex-1 text-left min-w-0">
+                <div
+                  className={cn(
+                    'text-sm font-medium truncate',
+                    isSelected
+                      ? 'text-primary-700 dark:text-primary-300'
+                      : 'text-gray-900 dark:text-white'
+                  )}
+                >
+                  {docSet.name}
+                </div>
+                {docSet.description && (
+                  <div className={cn(
+                    'text-xs truncate',
+                    isSelected
+                      ? 'text-primary-600/70 dark:text-primary-400/70'
+                      : 'text-gray-500 dark:text-gray-400'
+                  )}>
+                    {docSet.description}
+                  </div>
+                )}
+              </div>
+
+              {/* Checkmark indicator */}
+              {isSelected && (
+                <CheckIcon className="flex-shrink-0 w-4 h-4 text-primary-600 dark:text-primary-400" />
+              )}
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/src/components/DocsLayout.tsx

@@ -1,6 +1,7 @@
 import { Head, Link, usePage } from '@inertiajs/react'
 import { useState } from 'react'
 import { Sidebar } from './Sidebar'
+import { TableOfContents } from './TableOfContents'
 import { ThemeToggle } from './ThemeToggle'
 import { useTheme } from './ThemeProvider'
 import type { DocsLayoutProps, SharedProps } from '../types'
@@ -52,9 +53,10 @@ export function DocsLayout({
   githubUrl: propGithubUrl,
   navLinks: propNavLinks,
   footer,
+  toc,
 }: DocsLayoutProps) {
   const sharedProps = usePage<{ props: SharedProps }>().props as unknown as SharedProps
-  const { nav, currentPath } = sharedProps
+  const { nav, currentPath, docSets, currentDocSet } = sharedProps
   const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
   const { resolvedTheme } = useTheme()
 
@@ -132,28 +134,37 @@ export function DocsLayout({
       {mobileMenuOpen && (
         <div className="fixed inset-0 z-40 lg:hidden">
           <div className="fixed inset-0 bg-black/50 dark:bg-black/70" onClick={() => setMobileMenuOpen(false)} />
-          <div className="fixed inset-y-0 left-0 w-72 overflow-y-auto bg-white dark:bg-[#0f0f0f] px-4 lg:px-10 py-6 pt-20 border-r border-gray-200 dark:border-gray-800 transition-colors">
-            <Sidebar nav={nav} currentPath={currentPath} />
+          <div className="fixed inset-y-0 left-0 w-64 overflow-y-auto bg-white dark:bg-[#0f0f0f] px-4 py-6 pt-20 border-r border-gray-200 dark:border-gray-800 transition-colors">
+            <Sidebar nav={nav} currentPath={currentPath} docSets={docSets} currentDocSet={currentDocSet} />
           </div>
         </div>
       )}
 
       {/* Main content area */}
       <div className="bg-white dark:bg-[#0f0f0f] pt-16 w-full flex-1 transition-colors">
-        <div className="grid grid-cols-12">
-          {/* Desktop sidebar */}
-          <aside className="hidden lg:block lg:col-span-3 xl:col-span-2 border-r border-gray-200 dark:border-gray-800 min-h-[calc(100vh-4rem)] transition-colors">
-            <nav className="sticky top-16 px-4 lg:px-10 py-6 max-h-[calc(100vh-4rem)] overflow-y-auto">
-              <Sidebar nav={nav} currentPath={currentPath} />
+        <div className="flex">
+          {/* Desktop sidebar - fixed width */}
+          <aside className="hidden lg:block w-72 flex-shrink-0 border-r border-gray-200 dark:border-gray-800 min-h-[calc(100vh-4rem)] transition-colors">
+            <nav className="sticky top-16 px-4 py-6 max-h-[calc(100vh-4rem)] overflow-y-auto">
+              <Sidebar nav={nav} currentPath={currentPath} docSets={docSets} currentDocSet={currentDocSet} />
             </nav>
           </aside>
 
           {/* Main content */}
-          <main className="col-span-12 lg:col-span-9 xl:col-span-10 p-4 lg:px-10 lg:py-6">
+          <main className="flex-1 min-w-0 p-4 lg:px-10 lg:py-6">
             <article className="prose prose-lg max-w-3xl prose-headings:font-bold prose-headings:tracking-tight prose-h1:text-3xl prose-h1:mb-4 prose-h2:text-2xl prose-h2:mt-10 first:prose-h2:mt-0 prose-h3:text-xl prose-a:text-primary-600 dark:prose-a:text-primary-400 prose-a:no-underline hover:prose-a:underline prose-code:bg-gray-100 dark:prose-code:bg-gray-800 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded prose-code:before:content-none prose-code:after:content-none dark:prose-headings:text-white dark:prose-strong:text-white dark:text-gray-300">
               {children}
             </article>
           </main>
+
+          {/* Table of Contents - desktop only */}
+          {toc && toc.length > 0 && (
+            <aside className="hidden xl:block w-64 flex-shrink-0 min-h-[calc(100vh-4rem)] transition-colors">
+              <div className="sticky top-16 px-4 py-6 max-h-[calc(100vh-4rem)] overflow-y-auto">
+                <TableOfContents items={toc} />
+              </div>
+            </aside>
+          )}
         </div>
       </div>
 

package/src/components/DocsPage.tsx

@@ -15,7 +15,12 @@ export function DocsPage({ content, ...layoutProps }: DocsPageProps) {
   const { components } = useComponents()
 
   return (
-    <DocsLayout title={content?.title ?? ''} description={content?.description} {...layoutProps}>
+    <DocsLayout
+      title={content?.title ?? ''}
+      description={content?.description}
+      toc={content?.toc}
+      {...layoutProps}
+    >
       <Markdown content={content?.body ?? ''} components={components} />
     </DocsLayout>
   )

package/src/components/Markdown.tsx

@@ -4,6 +4,32 @@ import rehypeRaw from 'rehype-raw'
 import { CodeBlock } from './CodeBlock'
 import type { MarkdownProps } from '../types'
 
+/**
+ * Convert heading text to URL-safe slug.
+ * Must match the Python slugify function in markdown.py.
+ */
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+/**
+ * Extract text content from React children.
+ */
+function getTextContent(children: React.ReactNode): string {
+  if (typeof children === 'string') return children
+  if (typeof children === 'number') return String(children)
+  if (Array.isArray(children)) return children.map(getTextContent).join('')
+  if (children && typeof children === 'object' && 'props' in children) {
+    return getTextContent((children as React.ReactElement).props.children)
+  }
+  return ''
+}
+
 /**
  * Markdown renderer with syntax highlighting and GFM support.
  */
@@ -96,6 +122,25 @@ export function Markdown({ content, components }: MarkdownProps) {
             </td>
           )
         },
+        // Headings with anchor IDs for TOC
+        h2({ children }) {
+          const text = getTextContent(children)
+          const id = slugify(text)
+          return (
+            <h2 id={id}>
+              {children}
+            </h2>
+          )
+        },
+        h3({ children }) {
+          const text = getTextContent(children)
+          const id = slugify(text)
+          return (
+            <h3 id={id}>
+              {children}
+            </h3>
+          )
+        },
       }}
     >
       {content}

package/src/components/Sidebar.tsx

@@ -1,13 +1,22 @@
 import { Link } from '@inertiajs/react'
 import { cn } from '../lib/utils'
+import { DocSetSelector } from './DocSetSelector'
 import type { SidebarProps } from '../types'
 
 /**
  * Documentation sidebar with section-based navigation.
+ * In multi-docs mode, includes a dropdown selector at the top.
  */
-export function Sidebar({ nav, currentPath, className }: SidebarProps) {
+export function Sidebar({ nav, currentPath, className, docSets, currentDocSet }: SidebarProps) {
   return (
-    <nav className={cn('space-y-8', className)}>
+    <nav className={cn('space-y-6', className)}>
+      {/* Doc Set Selector - only shown in multi-docs mode */}
+      {docSets && docSets.length > 1 && (
+        <DocSetSelector docSets={docSets} currentDocSet={currentDocSet ?? ''} className="mb-6" />
+      )}
+
+      {/* Navigation Sections */}
+      <div className="space-y-8">
       {nav.map((section) => (
         <div key={section.title}>
           <h3 className="mb-3 text-xs font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400">
@@ -32,6 +41,7 @@ export function Sidebar({ nav, currentPath, className }: SidebarProps) {
           </ul>
         </div>
       ))}
+      </div>
     </nav>
   )
 }

package/src/components/TableOfContents.tsx

@@ -0,0 +1,180 @@
+import { useEffect, useState, useRef } from 'react'
+import type { TableOfContentsProps } from '../types'
+
+/**
+ * Table of contents component with scroll spy functionality.
+ * Displays "ON THIS PAGE" sidebar with heading links.
+ */
+export function TableOfContents({ items, className = '' }: TableOfContentsProps) {
+  const [activeId, setActiveId] = useState<string>(() => {
+    // Initialize with hash from URL if present
+    if (typeof window !== 'undefined' && window.location.hash) {
+      return window.location.hash.slice(1)
+    }
+    return ''
+  })
+
+  // Track if we're currently scrolling from a click
+  const isClickScrolling = useRef(false)
+
+  useEffect(() => {
+    if (items.length === 0) return
+
+    // Listen for hash changes
+    const handleHashChange = () => {
+      const hash = window.location.hash.slice(1)
+      if (hash) {
+        setActiveId(hash)
+      }
+    }
+    window.addEventListener('hashchange', handleHashChange)
+
+    // Scroll-based detection - find the heading closest to top of viewport
+    const handleScroll = () => {
+      // Skip if we're in the middle of a click-initiated scroll
+      if (isClickScrolling.current) return
+
+      const headerOffset = 100
+      let currentId = ''
+
+      // Check if we're at the bottom of the page
+      const scrollTop = window.scrollY
+      const scrollHeight = document.documentElement.scrollHeight
+      const clientHeight = document.documentElement.clientHeight
+      const isAtBottom = scrollTop + clientHeight >= scrollHeight - 50
+
+      if (isAtBottom) {
+        // At bottom of page - find the last heading that's visible in viewport
+        for (let i = items.length - 1; i >= 0; i--) {
+          const element = document.getElementById(items[i].id)
+          if (element) {
+            const rect = element.getBoundingClientRect()
+            // If this heading is visible in the viewport
+            if (rect.top < clientHeight && rect.bottom > 0) {
+              currentId = items[i].id
+              break
+            }
+          }
+        }
+      } else {
+        // Normal scroll detection
+        for (const item of items) {
+          const element = document.getElementById(item.id)
+          if (element) {
+            const rect = element.getBoundingClientRect()
+            // If the heading is at or above the threshold, it's the current section
+            if (rect.top <= headerOffset) {
+              currentId = item.id
+            } else {
+              // Once we find a heading below the threshold, stop
+              break
+            }
+          }
+        }
+      }
+
+      // If no heading is above threshold, use the first one
+      if (!currentId && items.length > 0) {
+        currentId = items[0].id
+      }
+
+      if (currentId) {
+        setActiveId(currentId)
+      }
+    }
+
+    // Throttle scroll handler
+    let ticking = false
+    const scrollListener = () => {
+      if (!ticking) {
+        requestAnimationFrame(() => {
+          handleScroll()
+          ticking = false
+        })
+        ticking = true
+      }
+    }
+
+    window.addEventListener('scroll', scrollListener, { passive: true })
+
+    // Initial check (only if no hash in URL)
+    if (!window.location.hash) {
+      handleScroll()
+    }
+
+    return () => {
+      window.removeEventListener('scroll', scrollListener)
+      window.removeEventListener('hashchange', handleHashChange)
+    }
+  }, [items])
+
+  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>, id: string) => {
+    e.preventDefault()
+    const element = document.getElementById(id)
+    if (element) {
+      // Mark that we're click-scrolling to prevent scroll handler from overriding
+      isClickScrolling.current = true
+      setActiveId(id)
+
+      const top = element.getBoundingClientRect().top + window.scrollY - 80
+      window.scrollTo({ top, behavior: 'smooth' })
+
+      // Update URL hash without jumping
+      window.history.pushState(null, '', `#${id}`)
+
+      // Re-enable scroll detection after scroll settles
+      // Use requestAnimationFrame loop to wait for scroll to stabilize
+      let lastScrollY = window.scrollY
+      let stableCount = 0
+      const checkScrollEnd = () => {
+        if (window.scrollY === lastScrollY) {
+          stableCount++
+          if (stableCount >= 5) {
+            // Scroll has been stable for ~5 frames, animation is done
+            isClickScrolling.current = false
+            return
+          }
+        } else {
+          stableCount = 0
+          lastScrollY = window.scrollY
+        }
+        requestAnimationFrame(checkScrollEnd)
+      }
+      requestAnimationFrame(checkScrollEnd)
+    }
+  }
+
+  if (items.length === 0) {
+    return null
+  }
+
+  return (
+    <nav className={className}>
+      <h5 className="mb-4 text-sm font-semibold tracking-wide text-gray-500 dark:text-gray-400 uppercase">
+        On this page
+      </h5>
+      <ul className="space-y-2.5 text-sm border-l border-gray-200 dark:border-gray-700">
+        {items.map((item) => {
+          const isActive = activeId === item.id
+          const indent = item.level === 3 ? 'pl-6' : 'pl-4'
+
+          return (
+            <li key={item.id}>
+              <a
+                href={`#${item.id}`}
+                onClick={(e) => handleClick(e, item.id)}
+                className={`block ${indent} -ml-px border-l transition-colors ${
+                  isActive
+                    ? 'border-primary-500 text-primary-600 dark:text-primary-400'
+                    : 'border-transparent text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200 hover:border-gray-300 dark:hover:border-gray-600'
+                }`}
+              >
+                {item.text}
+              </a>
+            </li>
+          )
+        })}
+      </ul>
+    </nav>
+  )
+}

package/src/components/index.ts

@@ -1,9 +1,11 @@
 export { CodeBlock, InlineCode } from './CodeBlock'
+export { DocSetSelector } from './DocSetSelector'
 export { DocsLayout } from './DocsLayout'
 export { DocsPage } from './DocsPage'
 export { EmojiConfetti } from './EmojiConfetti'
 export { HomePage } from './HomePage'
 export { Markdown } from './Markdown'
 export { Sidebar } from './Sidebar'
+export { TableOfContents } from './TableOfContents'
 export { ThemeProvider, useTheme, themeInitScript } from './ThemeProvider'
 export { ThemeToggle } from './ThemeToggle'

package/src/index.ts

@@ -1,6 +1,7 @@
 // Components
 export {
   CodeBlock,
+  DocSetSelector,
   DocsLayout,
   DocsPage,
   EmojiConfetti,
@@ -8,6 +9,7 @@ export {
   InlineCode,
   Markdown,
   Sidebar,
+  TableOfContents,
   ThemeProvider,
   ThemeToggle,
   useTheme,
@@ -37,11 +39,14 @@ export type {
   DocContent,
   DocsAppConfig,
   DocsLayoutProps,
+  DocSetMeta,
   MarkdownProps,
   NavItem,
   NavSection,
   SharedProps,
   SidebarProps,
+  TableOfContentsProps,
+  TOCItem,
 } from './types'
 
 export type { Theme, ResolvedTheme } from './components/ThemeProvider'

package/src/styles.css

@@ -13,6 +13,9 @@
  * Note: The Google Fonts import must come before other imports to avoid CSS ordering warnings.
  */
 
+/* Enable class-based dark mode (using .dark class on root element) */
+@custom-variant dark (&:where(.dark, .dark *));
+
 /* Theme customizations for Tailwind v4 */
 @theme {
   /* Max width */