@usecross/docs 0.5.0 → 0.6.0

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

@@ -5,3 +5,5 @@ 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

@@ -8,6 +8,10 @@ export {
   InlineCode,
   Markdown,
   Sidebar,
+  ThemeProvider,
+  ThemeToggle,
+  useTheme,
+  themeInitScript,
 } from './components'
 
 // HomePage sub-components (for compound component pattern)
@@ -40,6 +44,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

@@ -56,6 +56,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 +96,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 +162,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 +174,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 +222,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

@@ -26,6 +26,8 @@ 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) */