@usecross/docs 0.10.2 → 0.12.0

package/src/components/Sidebar.tsx

@@ -1,13 +1,151 @@
+import { useState } from 'react'
 import { Link } from '@inertiajs/react'
 import { cn } from '../lib/utils'
 import { DocSetSelector } from './DocSetSelector'
-import type { SidebarProps } from '../types'
+import type { SidebarProps, NavSection } from '../types'
+
+/**
+ * Chevron icon for collapsible sections
+ */
+function ChevronIcon({ expanded, className }: { expanded: boolean; className?: string }) {
+  return (
+    <svg
+      className={cn('w-4 h-4 transition-transform duration-200', expanded && 'rotate-90', className)}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+    </svg>
+  )
+}
+
+/**
+ * Collapsible navigation section
+ */
+function CollapsibleSection({
+  section,
+  currentPath,
+  defaultExpanded = true,
+  compact = false,
+}: {
+  section: NavSection
+  currentPath: string
+  defaultExpanded?: boolean
+  compact?: boolean
+}) {
+  // Check if current path is in this section
+  const isActive = section.items.some(
+    (item) => currentPath === item.href || currentPath + '/' === item.href
+  )
+  const [expanded, setExpanded] = useState(defaultExpanded || isActive)
+
+  return (
+    <div>
+      <button
+        onClick={() => setExpanded(!expanded)}
+        className="w-full flex items-center justify-between mb-2 group"
+      >
+        <h3 className={cn(
+          'text-sm font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400',
+          'group-hover:text-gray-700 dark:group-hover:text-gray-300 transition-colors'
+        )}>
+          {section.title}
+        </h3>
+        <ChevronIcon expanded={expanded} className="text-gray-400 dark:text-gray-500" />
+      </button>
+      {expanded && (
+        <ul className={cn(
+          'border-l-2 border-gray-200 dark:border-gray-700',
+          compact ? 'space-y-0.5' : 'space-y-1.5'
+        )}>
+          {section.items.map((item) => (
+            <li key={item.href}>
+              <Link
+                href={item.href}
+                className={cn(
+                  'block border-l-2 py-1 pl-4 leading-snug transition-colors -ml-0.5',
+                  compact ? 'text-sm' : 'text-[15px]',
+                  currentPath === item.href || currentPath + '/' === item.href
+                    ? 'border-primary-500 text-gray-900 dark:text-white font-semibold'
+                    : 'border-transparent text-gray-600 dark:text-gray-400 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
+                )}
+              >
+                {item.title}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Static navigation section (non-collapsible)
+ */
+function StaticSection({
+  section,
+  currentPath,
+  compact = false,
+}: {
+  section: NavSection
+  currentPath: string
+  compact?: boolean
+}) {
+  return (
+    <div>
+      <h3 className="mb-3 text-sm font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400">
+        {section.title}
+      </h3>
+      <ul className={cn(
+        'border-l-2 border-gray-200 dark:border-gray-700',
+        compact ? 'space-y-0.5' : 'space-y-1.5'
+      )}>
+        {section.items.map((item) => (
+          <li key={item.href}>
+            <Link
+              href={item.href}
+              className={cn(
+                'block border-l-2 py-1 pl-4 leading-snug transition-colors -ml-0.5',
+                compact ? 'text-sm' : 'text-[15px]',
+                currentPath === item.href || currentPath + '/' === item.href
+                  ? 'border-primary-500 text-gray-900 dark:text-white font-semibold'
+                  : 'border-transparent text-gray-600 dark:text-gray-400 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
+              )}
+            >
+              {item.title}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+export interface ExtendedSidebarProps extends SidebarProps {
+  /** Use compact styling (smaller text) */
+  compact?: boolean
+  /** Make sections collapsible */
+  collapsible?: boolean
+  /** Collapse sections with more than N items by default */
+  collapseThreshold?: number
+}
 
 /**
  * Documentation sidebar with section-based navigation.
- * In multi-docs mode, includes a dropdown selector at the top.
+ * Supports both docs and API navigation styles.
  */
-export function Sidebar({ nav, currentPath, className, docSets, currentDocSet }: SidebarProps) {
+export function Sidebar({
+  nav,
+  currentPath,
+  className,
+  docSets,
+  currentDocSet,
+  compact = false,
+  collapsible = false,
+  collapseThreshold = 10,
+}: ExtendedSidebarProps) {
   return (
     <nav className={cn('space-y-6', className)}>
       {/* Doc Set Selector - only shown in multi-docs mode */}
@@ -16,31 +154,36 @@ export function Sidebar({ nav, currentPath, className, docSets, currentDocSet }:
       )}
 
       {/* 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">
-            {section.title}
-          </h3>
-          <ul className="space-y-1 border-l-2 border-gray-200 dark:border-gray-700">
-            {section.items.map((item) => (
-              <li key={item.href}>
-                <Link
-                  href={item.href}
-                  className={cn(
-                    'block border-l-2 py-1.5 pl-4 text-base transition-colors -ml-0.5',
-                    currentPath === item.href
-                      ? 'border-primary-500 text-gray-900 dark:text-white font-bold'
-                      : 'border-transparent text-gray-600 dark:text-gray-300 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
-                  )}
-                >
-                  {item.title}
-                </Link>
-              </li>
-            ))}
-          </ul>
-        </div>
-      ))}
+      <div className={compact ? 'space-y-4' : 'space-y-6'}>
+        {nav.map((section) => {
+          // Determine if this section should be collapsible
+          const shouldCollapse = collapsible && section.items.length > collapseThreshold
+          // Check if current path is in this section
+          const isActive = section.items.some(
+            (item) => currentPath === item.href || currentPath + '/' === item.href
+          )
+
+          if (shouldCollapse) {
+            return (
+              <CollapsibleSection
+                key={section.title}
+                section={section}
+                currentPath={currentPath}
+                defaultExpanded={isActive}
+                compact={compact}
+              />
+            )
+          }
+
+          return (
+            <StaticSection
+              key={section.title}
+              section={section}
+              currentPath={currentPath}
+              compact={compact}
+            />
+          )
+        })}
       </div>
     </nav>
   )

package/src/components/TableOfContents.tsx

@@ -5,7 +5,7 @@ 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) {
+export function TableOfContents({ items, className = '', ...props }: TableOfContentsProps) {
   const [activeId, setActiveId] = useState<string>(() => {
     // Initialize with hash from URL if present
     if (typeof window !== 'undefined' && window.location.hash) {
@@ -149,11 +149,11 @@ export function TableOfContents({ items, className = '' }: TableOfContentsProps)
   }
 
   return (
-    <nav className={className}>
-      <h3 className="mb-3 text-xs font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400">
+    <nav className={className} {...props}>
+      <h3 className="mb-3 text-sm font-mono uppercase tracking-widest text-gray-500 dark:text-gray-400">
         On this page
       </h3>
-      <ul className="space-y-1 border-l-2 border-gray-200 dark:border-gray-700">
+      <ul className="space-y-1.5 border-l-2 border-gray-200 dark:border-gray-700">
         {items.map((item) => {
           const isActive = activeId === item.id
           const indent = item.level === 3 ? 'pl-6' : 'pl-4'
@@ -163,13 +163,13 @@ export function TableOfContents({ items, className = '' }: TableOfContentsProps)
               <a
                 href={`#${item.id}`}
                 onClick={(e) => handleClick(e, item.id)}
-                className={`block border-l-2 py-1.5 ${indent} -ml-0.5 text-sm transition-colors ${
+                className={`block border-l-2 py-1 ${indent} -ml-0.5 text-base leading-snug transition-colors ${
                   isActive
                     ? 'border-primary-500 text-gray-900 dark:text-white font-bold'
                     : 'border-transparent text-gray-600 dark:text-gray-300 hover:border-primary-300 dark:hover:border-primary-400 hover:text-gray-900 dark:hover:text-white'
                 }`}
               >
-                {item.text}
+                {item.text || item.title}
               </a>
             </li>
           )

package/src/components/api/APILayout.tsx

@@ -0,0 +1,231 @@
+import { Head, Link, usePage } from '@inertiajs/react'
+import { useState } from 'react'
+import { ThemeToggle } from '../ThemeToggle'
+import { useTheme } from '../ThemeProvider'
+import { MobileMenuButton } from '../DocsLayout'
+import { Sidebar } from '../Sidebar'
+import type { NavSection, SharedProps } from '../../types'
+
+interface APILayoutProps {
+  children: React.ReactNode
+  title: string
+  apiNav: NavSection[]
+  currentPath: string
+  logoUrl?: string
+  logoInvertedUrl?: string
+  footerLogoUrl?: string
+  footerLogoInvertedUrl?: string
+  githubUrl?: string
+  navLinks?: Array<{ label: string; href: string }>
+  /** Right sidebar content (e.g., table of contents) */
+  rightSidebar?: React.ReactNode
+  /** Custom header component (replaces entire header). Can be a ReactNode or a function that receives mobile menu props. */
+  header?: React.ReactNode | ((props: { mobileMenuOpen: boolean; toggleMobileMenu: () => void }) => React.ReactNode)
+  /** Header height in pixels. Used to calculate content offset. Defaults to 64 (h-16). */
+  headerHeight?: number
+  /** Custom footer component */
+  footer?: React.ReactNode
+}
+
+/** Shared props type for API pages */
+interface APISharedProps extends SharedProps {
+  apiNav?: NavSection[]
+}
+
+function GitHubIcon() {
+  return (
+    <svg className="w-6 h-6" fill="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+      <path
+        fillRule="evenodd"
+        d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"
+        clipRule="evenodd"
+      />
+    </svg>
+  )
+}
+
+/**
+ * Layout component for API documentation pages.
+ * Uses the shared Sidebar component with compact styling and collapsible sections.
+ */
+export function APILayout({
+  children,
+  title,
+  apiNav,
+  currentPath,
+  logoUrl: propLogoUrl,
+  logoInvertedUrl: propLogoInvertedUrl,
+  footerLogoUrl: propFooterLogoUrl,
+  footerLogoInvertedUrl: propFooterLogoInvertedUrl,
+  githubUrl: propGithubUrl,
+  navLinks: propNavLinks,
+  rightSidebar,
+  header,
+  headerHeight: propHeaderHeight = 64,
+  footer,
+}: APILayoutProps) {
+  const sharedProps = usePage<{ props: APISharedProps }>().props as unknown as APISharedProps
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
+  const { resolvedTheme } = useTheme()
+  const headerHeight = propHeaderHeight
+
+  // Merge props - component props take precedence over shared props from Python
+  const logoUrl = propLogoUrl ?? sharedProps.logoUrl
+  const logoInvertedUrl = propLogoInvertedUrl ?? sharedProps.logoInvertedUrl
+  const githubUrl = propGithubUrl ?? sharedProps.githubUrl
+  const navLinks = propNavLinks ?? sharedProps.navLinks ?? []
+
+  const headerLogo = logoInvertedUrl ? (
+    <img src={logoInvertedUrl} alt="Logo" className="h-8" />
+  ) : logoUrl ? (
+    <img src={logoUrl} alt="Logo" className="h-8" />
+  ) : null
+
+  const footerLogoUrl = propFooterLogoUrl || sharedProps.footerLogoUrl || logoUrl
+  const footerLogoInvertedUrl = propFooterLogoInvertedUrl || sharedProps.footerLogoInvertedUrl || logoInvertedUrl
+  const currentFooterLogoUrl = resolvedTheme === 'dark' ? (footerLogoInvertedUrl || footerLogoUrl) : footerLogoUrl
+  const footerLogo = currentFooterLogoUrl ? (
+    <img src={currentFooterLogoUrl} alt="Logo" className="h-6" />
+  ) : null
+
+  return (
+    <div className="min-h-screen bg-white dark:bg-[#0f0f0f] flex flex-col transition-colors duration-200">
+      <Head title={title} />
+
+      {/* Fixed navigation */}
+      {(typeof header === 'function'
+        ? header({ mobileMenuOpen, toggleMobileMenu: () => setMobileMenuOpen(!mobileMenuOpen) })
+        : header) || (
+        <nav className="fixed w-full z-50 bg-white/95 dark:bg-[#0f0f0f]/95 backdrop-blur-sm border-b border-gray-200 dark:border-gray-800 transition-colors">
+          <div className="px-4 lg:px-10">
+            <div className="flex justify-between h-16 items-center">
+              <div className="flex items-center gap-2">
+                <MobileMenuButton onClick={() => setMobileMenuOpen(!mobileMenuOpen)} isOpen={mobileMenuOpen} />
+                {headerLogo ? (
+                  <Link href="/" className="flex items-center">
+                    {headerLogo}
+                  </Link>
+                ) : (
+                  <Link href="/" className="font-bold text-lg text-gray-900 dark:text-white">
+                    Docs
+                  </Link>
+                )}
+              </div>
+              <div className="flex items-center gap-6">
+                <div className="-mr-2">
+                  <ThemeToggle size="sm" />
+                </div>
+                {navLinks.map((link) => (
+                  <Link
+                    key={link.href}
+                    href={link.href}
+                    className="hidden sm:block text-gray-700 dark:text-gray-300 font-medium hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
+                  >
+                    {link.label}
+                  </Link>
+                ))}
+                {githubUrl && (
+                  <a
+                    href={githubUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="text-gray-700 dark:text-gray-300 hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
+                  >
+                    <GitHubIcon />
+                  </a>
+                )}
+              </div>
+            </div>
+          </div>
+        </nav>
+      )}
+
+      {/* Mobile sidebar */}
+      {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 py-6 border-r border-gray-200 dark:border-gray-800 transition-colors"
+            style={{ paddingTop: headerHeight + 16 }}
+          >
+            <Sidebar
+              nav={apiNav}
+              currentPath={currentPath}
+            />
+          </div>
+        </div>
+      )}
+
+      {/* Main content area */}
+      <div className="bg-white dark:bg-[#0f0f0f] w-full flex-1 transition-colors" style={{ paddingTop: headerHeight }}>
+        <div className="flex">
+          {/* Desktop sidebar */}
+          <aside
+            className="hidden lg:block w-64 shrink-0 border-r border-gray-200 dark:border-gray-800 transition-colors"
+            style={{ minHeight: `calc(100vh - ${headerHeight}px)` }}
+          >
+            <div
+              className="sticky px-6 py-6 overflow-y-auto"
+              style={{ top: headerHeight, maxHeight: `calc(100vh - ${headerHeight}px)` }}
+            >
+              <Sidebar
+                nav={apiNav}
+                currentPath={currentPath}
+              />
+            </div>
+          </aside>
+
+          {/* Right section: content + TOC + footer */}
+          <div className="flex-1 min-w-0 flex flex-col">
+            <div className="flex-1 p-4 lg:px-10 lg:py-6">
+              <div className="flex gap-5">
+                {/* Main content */}
+                <main className="min-w-0 w-full max-w-4xl">
+                  {children}
+                </main>
+
+                {/* Table of Contents - desktop only */}
+                {rightSidebar && (
+                  <aside className="hidden xl:block w-56 shrink-0 transition-colors">
+                    <div
+                      className="sticky overflow-y-auto"
+                      style={{ top: headerHeight + 24, maxHeight: `calc(100vh - ${headerHeight + 24}px)` }}
+                    >
+                      {rightSidebar}
+                    </div>
+                  </aside>
+                )}
+              </div>
+            </div>
+
+            {/* Footer */}
+            {footer || (
+              <footer className="border-t border-gray-200 dark:border-gray-800 py-8 px-4 lg:px-10 transition-colors">
+                <div className="flex flex-col md:flex-row justify-between items-center gap-6">
+                  {footerLogo && <Link href="/">{footerLogo}</Link>}
+                  <div className="flex gap-8 text-sm text-gray-600 dark:text-gray-400">
+                    {navLinks.map((link) => (
+                      <Link key={link.href} href={link.href} className="hover:text-black dark:hover:text-white transition-colors">
+                        {link.label}
+                      </Link>
+                    ))}
+                    {githubUrl && (
+                      <a
+                        href={githubUrl}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="hover:text-black dark:hover:text-white transition-colors"
+                      >
+                        GitHub
+                      </a>
+                    )}
+                  </div>
+                </div>
+              </footer>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}