@usecross/docs 0.6.0 → 0.7.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

@@ -54,7 +54,7 @@ export function DocsLayout({
   footer,
 }: 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,24 +132,24 @@ 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>

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/index.ts

@@ -1,4 +1,5 @@
 export { CodeBlock, InlineCode } from './CodeBlock'
+export { DocSetSelector } from './DocSetSelector'
 export { DocsLayout } from './DocsLayout'
 export { DocsPage } from './DocsPage'
 export { EmojiConfetti } from './EmojiConfetti'

package/src/index.ts

@@ -1,6 +1,7 @@
 // Components
 export {
   CodeBlock,
+  DocSetSelector,
   DocsLayout,
   DocsPage,
   EmojiConfetti,
@@ -37,6 +38,7 @@ export type {
   DocContent,
   DocsAppConfig,
   DocsLayoutProps,
+  DocSetMeta,
   MarkdownProps,
   NavItem,
   NavSection,

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 */

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[]
@@ -32,6 +44,10 @@ export interface SharedProps {
   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 */
@@ -67,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 */