@usecross/docs 0.5.0 → 0.7.0

package/src/components/Sidebar.tsx

@@ -1,19 +1,28 @@
 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">
+          <h3 className="mb-3 text-xs font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400">
             {section.title}
           </h3>
-          <ul className="space-y-1 border-l-2 border-gray-200">
+          <ul className="space-y-1 border-l-2 border-gray-200 dark:border-gray-700">
             {section.items.map((item) => (
               <li key={item.href}>
                 <Link
@@ -21,8 +30,8 @@ export function Sidebar({ nav, currentPath, className }: SidebarProps) {
                   className={cn(
                     'block border-l-2 py-1.5 pl-4 text-sm transition-colors -ml-0.5',
                     currentPath === item.href
-                      ? 'border-primary-500 text-black font-bold'
-                      : 'border-transparent text-gray-600 hover:border-black hover:text-black'
+                      ? 'border-primary-500 text-gray-900 dark:text-white font-bold'
+                      : 'border-transparent text-gray-600 dark:text-gray-300 hover:border-gray-900 dark:hover:border-white hover:text-gray-900 dark:hover:text-white'
                   )}
                 >
                   {item.title}
@@ -32,6 +41,7 @@ export function Sidebar({ nav, currentPath, className }: SidebarProps) {
           </ul>
         </div>
       ))}
+      </div>
     </nav>
   )
 }

package/src/components/ThemeProvider.tsx

@@ -0,0 +1,125 @@
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react'
+
+export type Theme = 'light' | 'dark' | 'system'
+export type ResolvedTheme = 'light' | 'dark'
+
+interface ThemeContextValue {
+  theme: Theme
+  resolvedTheme: ResolvedTheme
+  setTheme: (theme: Theme) => void
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null)
+
+const STORAGE_KEY = 'cross-docs-theme'
+
+function getSystemTheme(): ResolvedTheme {
+  if (typeof window === 'undefined') return 'light'
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+function getStoredTheme(): Theme | null {
+  if (typeof window === 'undefined') return null
+  const stored = localStorage.getItem(STORAGE_KEY)
+  if (stored === 'light' || stored === 'dark' || stored === 'system') {
+    return stored
+  }
+  return null
+}
+
+interface ThemeProviderProps {
+  children: ReactNode
+  /** Default theme if no preference is stored. Defaults to 'system'. */
+  defaultTheme?: Theme
+  /** Force a specific theme, ignoring user preference */
+  forcedTheme?: ResolvedTheme
+}
+
+export function ThemeProvider({
+  children,
+  defaultTheme = 'system',
+  forcedTheme,
+}: ThemeProviderProps) {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    // During SSR, use defaultTheme
+    if (typeof window === 'undefined') return defaultTheme
+    return getStoredTheme() ?? defaultTheme
+  })
+
+  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(() => {
+    if (forcedTheme) return forcedTheme
+    if (typeof window === 'undefined') return 'light'
+    if (theme === 'system') return getSystemTheme()
+    return theme
+  })
+
+  // Update resolved theme when theme changes or system preference changes
+  useEffect(() => {
+    if (forcedTheme) {
+      setResolvedTheme(forcedTheme)
+      return
+    }
+
+    const updateResolvedTheme = () => {
+      if (theme === 'system') {
+        setResolvedTheme(getSystemTheme())
+      } else {
+        setResolvedTheme(theme)
+      }
+    }
+
+    updateResolvedTheme()
+
+    // Listen for system preference changes
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+    const handleChange = () => {
+      if (theme === 'system') {
+        setResolvedTheme(getSystemTheme())
+      }
+    }
+
+    mediaQuery.addEventListener('change', handleChange)
+    return () => mediaQuery.removeEventListener('change', handleChange)
+  }, [theme, forcedTheme])
+
+  // Apply theme class to document
+  useEffect(() => {
+    const root = document.documentElement
+    root.classList.remove('light', 'dark')
+    root.classList.add(resolvedTheme)
+  }, [resolvedTheme])
+
+  const setTheme = (newTheme: Theme) => {
+    setThemeState(newTheme)
+    localStorage.setItem(STORAGE_KEY, newTheme)
+  }
+
+  return (
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  )
+}
+
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext)
+  if (!context) {
+    throw new Error('useTheme must be used within a ThemeProvider')
+  }
+  return context
+}
+
+/**
+ * Script to prevent flash of unstyled content (FOUC) during page load.
+ * Include this in your HTML <head> before any stylesheets.
+ */
+export const themeInitScript = `
+(function() {
+  try {
+    var stored = localStorage.getItem('${STORAGE_KEY}');
+    var theme = stored === 'light' || stored === 'dark' ? stored :
+                (stored === 'system' || !stored) && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    document.documentElement.classList.add(theme);
+  } catch (e) {}
+})();
+`.trim()

package/src/components/ThemeToggle.tsx

@@ -0,0 +1,188 @@
+import { useState, useRef, useEffect } from 'react'
+import { useTheme, type Theme } from './ThemeProvider'
+import { cn } from '../lib/utils'
+
+interface ThemeToggleProps {
+  /** Additional CSS classes */
+  className?: string
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg'
+}
+
+// Refined sun icon with balanced proportions
+const SunIcon = ({ className }: { className?: string }) => (
+  <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="12" cy="12" r="4" stroke="currentColor" strokeWidth="1.5" />
+    <path d="M12 5V3M12 21v-2M5 12H3m18 0h-2M7.05 7.05 5.636 5.636m12.728 12.728L16.95 16.95M7.05 16.95l-1.414 1.414M18.364 5.636 16.95 7.05" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+  </svg>
+)
+
+// Refined moon icon - elegant crescent
+const MoonIcon = ({ className }: { className?: string }) => (
+  <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path d="M21.752 15.002A9.718 9.718 0 0 1 18 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 0 0 3 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 0 0 9.002-5.998Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+)
+
+// Refined monitor icon - clean display shape
+const MonitorIcon = ({ className }: { className?: string }) => (
+  <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <rect x="2" y="3" width="20" height="14" rx="2" stroke="currentColor" strokeWidth="1.5" />
+    <path d="M8 21h8m-4-4v4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+  </svg>
+)
+
+const themeOptions: { value: Theme; label: string; icon: typeof SunIcon }[] = [
+  { value: 'light', label: 'Light', icon: SunIcon },
+  { value: 'dark', label: 'Dark', icon: MoonIcon },
+  { value: 'system', label: 'System', icon: MonitorIcon },
+]
+
+/**
+ * Theme toggle dropdown with Light, Dark, and System options.
+ * Refined design with smooth animations and premium feel.
+ */
+export function ThemeToggle({ className, size = 'md' }: ThemeToggleProps) {
+  const { theme, resolvedTheme, setTheme } = useTheme()
+  const [isOpen, setIsOpen] = useState(false)
+  const dropdownRef = useRef<HTMLDivElement>(null)
+
+  // 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 iconSizes = {
+    sm: 'w-[18px] h-[18px]',
+    md: 'w-5 h-5',
+    lg: 'w-[22px] h-[22px]',
+  }
+
+  return (
+    <div className="relative" ref={dropdownRef}>
+      {/* Toggle Button */}
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className={cn(
+          'relative inline-flex items-center justify-center',
+          'rounded-full p-4',
+          'text-gray-500 hover:text-gray-900 dark:text-gray-400 dark:hover:text-white',
+          'hover:bg-gray-100 dark:hover:bg-white/10',
+          'transition-all duration-200 ease-out',
+          'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50 focus-visible:ring-offset-2 dark:focus-visible:ring-offset-[#0f0f0f]',
+          iconSizes[size],
+          className
+        )}
+        aria-label="Toggle theme"
+        aria-expanded={isOpen}
+        aria-haspopup="listbox"
+      >
+        {/* Sun icon - visible in light mode */}
+        <SunIcon
+          className={cn(
+            iconSizes[size],
+            'absolute inset-0 m-auto transition-all duration-300 ease-out',
+            resolvedTheme === 'light'
+              ? 'rotate-0 scale-100 opacity-100'
+              : 'rotate-90 scale-75 opacity-0'
+          )}
+        />
+
+        {/* Moon icon - visible in dark mode */}
+        <MoonIcon
+          className={cn(
+            iconSizes[size],
+            'absolute inset-0 m-auto transition-all duration-300 ease-out',
+            resolvedTheme === 'dark'
+              ? 'rotate-0 scale-100 opacity-100'
+              : '-rotate-90 scale-75 opacity-0'
+          )}
+        />
+      </button>
+
+      {/* Dropdown Menu */}
+      <div
+        className={cn(
+          'absolute right-0 mt-2 min-w-[140px]',
+          'p-1',
+          'bg-white dark:bg-[#171717]',
+          'border border-gray-200 dark:border-[#262626]',
+          'rounded-xl',
+          'shadow-lg shadow-black/5 dark:shadow-black/40',
+          'z-50',
+          'transition-all duration-200 ease-out origin-top-right',
+          isOpen
+            ? 'opacity-100 scale-100 translate-y-0'
+            : 'opacity-0 scale-95 -translate-y-1 pointer-events-none'
+        )}
+        role="listbox"
+        aria-label="Select theme"
+      >
+        {themeOptions.map((option, index) => {
+          const Icon = option.icon
+          const isSelected = theme === option.value
+
+          return (
+            <button
+              key={option.value}
+              onClick={() => {
+                setTheme(option.value)
+                setIsOpen(false)
+              }}
+              className={cn(
+                'w-full flex items-center gap-2.5 px-3 py-2',
+                'rounded-lg',
+                'text-[13px] font-medium',
+                'transition-all duration-150 ease-out',
+                'focus:outline-none',
+                isSelected
+                  ? 'text-gray-900 dark:text-white bg-gray-100 dark:bg-[#262626]'
+                  : 'text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white hover:bg-gray-50 dark:hover:bg-[#1f1f1f]'
+              )}
+              role="option"
+              aria-selected={isSelected}
+              style={{
+                animationDelay: isOpen ? `${index * 25}ms` : '0ms'
+              }}
+            >
+              <Icon className={cn(
+                'w-4 h-4 flex-shrink-0',
+                'transition-transform duration-150',
+                isSelected ? 'scale-110' : 'scale-100'
+              )} />
+              <span className="flex-1 text-left">{option.label}</span>
+              <div className={cn(
+                'w-1.5 h-1.5 rounded-full',
+                'transition-all duration-200',
+                isSelected
+                  ? 'bg-primary-500 scale-100 opacity-100'
+                  : 'bg-transparent scale-0 opacity-0'
+              )} />
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/src/components/index.ts

@@ -1,7 +1,10 @@
 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 { 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,10 @@ export {
   InlineCode,
   Markdown,
   Sidebar,
+  ThemeProvider,
+  ThemeToggle,
+  useTheme,
+  themeInitScript,
 } from './components'
 
 // HomePage sub-components (for compound component pattern)
@@ -33,6 +38,7 @@ export type {
   DocContent,
   DocsAppConfig,
   DocsLayoutProps,
+  DocSetMeta,
   MarkdownProps,
   NavItem,
   NavSection,
@@ -40,6 +46,8 @@ export type {
   SidebarProps,
 } from './types'
 
+export type { Theme, ResolvedTheme } from './components/ThemeProvider'
+
 export type {
   HomePageProps,
   HomePageContextValue,

package/src/ssr.tsx

@@ -2,6 +2,7 @@ import { createInertiaApp } from '@inertiajs/react'
 import createServer from '@inertiajs/react/server'
 import ReactDOMServer from 'react-dom/server'
 import type { DocsAppConfig } from './types'
+import { ThemeProvider } from './components/ThemeProvider'
 
 /**
  * Create an SSR server for documentation.
@@ -33,7 +34,11 @@ export function createDocsServer(config: DocsAppConfig): void {
         }
         return pageComponent
       },
-      setup: ({ App, props }) => <App {...props} />,
+      setup: ({ App, props }) => (
+        <ThemeProvider>
+          <App {...props} />
+        </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 */
@@ -56,6 +59,31 @@
     --shiki-token-string-expression: #86efac;
     --shiki-token-punctuation: #94a3b8;
     --shiki-token-link: #38bdf8;
+
+    /* Surface colors for light mode */
+    --surface-primary: #ffffff;
+    --surface-secondary: #f9fafb;
+    --surface-tertiary: #f3f4f6;
+    --border-primary: #e5e7eb;
+    --border-secondary: #d1d5db;
+    --text-primary: #111827;
+    --text-secondary: #4b5563;
+    --text-tertiary: #6b7280;
+  }
+
+  .dark {
+    /* Surface colors for dark mode */
+    --surface-primary: #0f0f0f;
+    --surface-secondary: #171717;
+    --surface-tertiary: #262626;
+    --border-primary: #262626;
+    --border-secondary: #404040;
+    --text-primary: #fafafa;
+    --text-secondary: #a3a3a3;
+    --text-tertiary: #737373;
+
+    /* Slightly lighter code blocks in dark mode for contrast */
+    --shiki-color-background: #1a1a1a;
   }
 
   html {
@@ -71,6 +99,14 @@
     @apply antialiased bg-white text-gray-800;
     font-family: var(--font-sans);
     font-weight: 400;
+    transition: background-color 0.2s ease, color 0.2s ease;
+  }
+
+  /* Dark mode body - using direct selector for cross-package compatibility */
+  .dark body,
+  :root.dark body {
+    background-color: #0f0f0f;
+    color: #f3f4f6;
   }
 
   /* Headings use heading font */
@@ -129,6 +165,7 @@
   /* Inline code styling */
   .prose :not(pre) > code {
     @apply bg-gray-100 px-1.5 py-0.5 rounded text-sm font-medium text-gray-800;
+    @apply dark:bg-gray-800 dark:text-gray-200;
   }
 
   .prose :not(pre) > code::before,
@@ -140,6 +177,24 @@
   .prose-invert :not(pre) > code {
     @apply bg-gray-800;
   }
+
+  /* Dark mode prose text colors */
+  .dark .prose {
+    --tw-prose-body: theme(colors.gray.300);
+    --tw-prose-headings: theme(colors.white);
+    --tw-prose-lead: theme(colors.gray.400);
+    --tw-prose-bold: theme(colors.white);
+    --tw-prose-counters: theme(colors.gray.400);
+    --tw-prose-bullets: theme(colors.gray.600);
+    --tw-prose-hr: theme(colors.gray.700);
+    --tw-prose-quotes: theme(colors.gray.100);
+    --tw-prose-quote-borders: theme(colors.gray.700);
+    --tw-prose-captions: theme(colors.gray.400);
+    --tw-prose-kbd: theme(colors.white);
+    --tw-prose-kbd-shadows: 0 0 0 theme(colors.gray.100);
+    --tw-prose-th-borders: theme(colors.gray.600);
+    --tw-prose-td-borders: theme(colors.gray.700);
+  }
 }
 
 /* Syntax highlighting - rounded corners like Starlight */
@@ -170,6 +225,15 @@
   @apply bg-gray-400;
 }
 
+/* Dark mode scrollbars */
+.dark ::-webkit-scrollbar-thumb {
+  @apply bg-gray-700;
+}
+
+.dark ::-webkit-scrollbar-thumb:hover {
+  @apply bg-gray-600;
+}
+
 /* Emoji confetti animation */
 @keyframes emojiConfettiBurst {
   0% {

package/src/types.ts

@@ -16,6 +16,18 @@ export interface NavSection {
   items: NavItem[]
 }
 
+/** Documentation set metadata (for multi-docs mode) */
+export interface DocSetMeta {
+  name: string
+  slug: string
+  description: string
+  /** Emoji or short text icon (e.g., "🍓") */
+  icon?: string
+  /** URL to icon image */
+  iconUrl?: string
+  prefix: string
+}
+
 /** Shared props passed to all pages via Inertia */
 export interface SharedProps {
   nav: NavSection[]
@@ -26,10 +38,16 @@ export interface SharedProps {
   logoInvertedUrl?: string
   /** Footer logo image URL (from Python backend) */
   footerLogoUrl?: string
+  /** Footer logo image URL for dark mode (from Python backend) */
+  footerLogoInvertedUrl?: string
   /** GitHub repository URL (from Python backend) */
   githubUrl?: string
   /** Additional navigation links (from Python backend) */
   navLinks?: Array<{ label: string; href: string }>
+  /** Available documentation sets (multi-docs mode) */
+  docSets?: DocSetMeta[]
+  /** Current documentation set slug (multi-docs mode) */
+  currentDocSet?: string
 }
 
 /** Document content structure */
@@ -65,6 +83,10 @@ export interface SidebarProps {
   nav: NavSection[]
   currentPath: string
   className?: string
+  /** Available documentation sets (multi-docs mode) */
+  docSets?: DocSetMeta[]
+  /** Current documentation set slug (multi-docs mode) */
+  currentDocSet?: string
 }
 
 /** Props for Markdown component */