@usecross/docs 0.4.2 → 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

@@ -1,22 +1,49 @@
 /**
- * Cross-Docs default styles
+ * Cross-Docs default styles (Tailwind CSS v4)
  *
- * Import this file in your app's CSS entry point:
+ * Import this file in your app's CSS entry point after importing Tailwind:
+ *
+ * @import "tailwindcss";
+ * @plugin "@tailwindcss/typography";
+ * @import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&display=swap');
  * @import '@usecross/docs/styles.css';
+ * @source "../node_modules/@usecross/docs";
+ *
+ * Note: The @source directive ensures Tailwind scans the package for utility classes.
+ * Note: The Google Fonts import must come before other imports to avoid CSS ordering warnings.
  */
 
-@reference "tailwindcss";
-
-@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&display=swap');
+/* Theme customizations for Tailwind v4 */
+@theme {
+  /* Max width */
+  --max-width-8xl: 88rem;
+
+  /* Font families */
+  --font-sans: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,
+    sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+  --font-heading: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  --font-mono: 'Fira Code', Consolas, Monaco, 'Andale Mono', monospace;
+
+  /* Default primary colors - sky blue (can be overridden via CSS variables) */
+  --color-primary-50: #f0f9ff;
+  --color-primary-100: #e0f2fe;
+  --color-primary-200: #bae6fd;
+  --color-primary-300: #7dd3fc;
+  --color-primary-400: #38bdf8;
+  --color-primary-500: #0ea5e9;
+  --color-primary-600: #0284c7;
+  --color-primary-700: #0369a1;
+  --color-primary-800: #075985;
+  --color-primary-900: #0c4a6e;
+  --color-primary-950: #082f49;
+
+  /* Dark colors for code blocks */
+  --color-dark-800: #1e293b;
+  --color-dark-900: #0f172a;
+}
 
 @layer base {
   :root {
-    /* Font stacks */
-    --font-sans: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,
-      sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
-    --font-heading: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
-    --font-mono: 'Fira Code', Consolas, Monaco, 'Andale Mono', monospace;
-
     /* Code highlighting - matches Starlight/Expressive Code dark theme */
     --shiki-color-text: #e2e8f0;
     --shiki-color-background: #24292f;
@@ -29,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 {
@@ -41,11 +93,17 @@
   }
 
   body {
-    @apply antialiased;
+    @apply antialiased bg-white text-gray-800;
     font-family: var(--font-sans);
     font-weight: 400;
-    background: #ffffff;
-    color: #1f2937;
+    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 */
@@ -63,10 +121,21 @@
 @layer components {
   /* Prose content styles */
   .prose {
+    max-width: none;
     font-size: 1rem;
     line-height: 1.75;
   }
 
+  /* Prose link styling */
+  .prose a {
+    @apply text-primary-600 hover:text-primary-700;
+  }
+
+  /* Dark mode prose link styling */
+  .prose-invert a {
+    @apply text-primary-400 hover:text-primary-300;
+  }
+
   /* Scroll margin for headings (so they don't hide under fixed header) */
   .prose h1,
   .prose h2,
@@ -93,12 +162,36 @@
   /* 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,
   .prose :not(pre) > code::after {
     content: none;
   }
+
+  /* Dark mode inline code */
+  .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 */
@@ -129,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) */

package/src/tailwind.preset.cjs

@@ -1,118 +0,0 @@
-/**
- * Cross-Docs Tailwind CSS preset
- *
- * @example
- * ```js
- * // tailwind.config.js
- * const docsPreset = require('@usecross/docs/tailwind.preset')
- *
- * module.exports = {
- *   presets: [docsPreset],
- *   content: [
- *     './frontend/**\/*.{ts,tsx}',
- *     './node_modules/@usecross/docs/**\/*.{js,tsx}',
- *   ],
- *   theme: {
- *     extend: {
- *       colors: {
- *         primary: { // Override with your brand colors },
- *       },
- *     },
- *   },
- * }
- * ```
- */
-module.exports = {
-  darkMode: 'class',
-  theme: {
-    extend: {
-      maxWidth: {
-        '8xl': '88rem',
-      },
-      fontFamily: {
-        sans: [
-          'system-ui',
-          '-apple-system',
-          'Segoe UI',
-          'Roboto',
-          'Helvetica',
-          'Arial',
-          'sans-serif',
-          'Apple Color Emoji',
-          'Segoe UI Emoji',
-          'Segoe UI Symbol',
-        ],
-        heading: [
-          'system-ui',
-          '-apple-system',
-          'Segoe UI',
-          'Roboto',
-          'sans-serif',
-        ],
-        mono: ['Fira Code', 'Consolas', 'Monaco', 'Andale Mono', 'monospace'],
-      },
-      colors: {
-        // Default primary colors - sky blue (can be overridden)
-        primary: {
-          50: '#f0f9ff',
-          100: '#e0f2fe',
-          200: '#bae6fd',
-          300: '#7dd3fc',
-          400: '#38bdf8',
-          500: '#0ea5e9',
-          600: '#0284c7',
-          700: '#0369a1',
-          800: '#075985',
-          900: '#0c4a6e',
-          950: '#082f49',
-        },
-        // Dark colors for code blocks
-        dark: {
-          800: '#1e293b',
-          900: '#0f172a',
-        },
-      },
-      typography: (theme) => ({
-        DEFAULT: {
-          css: {
-            maxWidth: 'none',
-            color: theme('colors.gray.700'),
-            a: {
-              color: theme('colors.primary.600'),
-              '&:hover': {
-                color: theme('colors.primary.700'),
-              },
-            },
-            'code::before': {
-              content: '""',
-            },
-            'code::after': {
-              content: '""',
-            },
-            code: {
-              backgroundColor: theme('colors.gray.100'),
-              padding: '0.25rem 0.375rem',
-              borderRadius: '0.25rem',
-              fontWeight: '500',
-            },
-          },
-        },
-        invert: {
-          css: {
-            color: theme('colors.gray.300'),
-            a: {
-              color: theme('colors.primary.400'),
-              '&:hover': {
-                color: theme('colors.primary.300'),
-              },
-            },
-            code: {
-              backgroundColor: theme('colors.gray.800'),
-            },
-          },
-        },
-      }),
-    },
-  },
-  plugins: [require('@tailwindcss/typography')],
-}