@usecross/docs 0.10.2 → 0.12.0

package/src/components/api/APIPage.tsx

@@ -0,0 +1,216 @@
+import type { APIPageProps, GriffeModule, GriffeClass, GriffeFunction, GriffeMember, GriffeAlias } from '../../types'
+import { APILayout } from './APILayout'
+import { ModuleDoc } from './ModuleDoc'
+import { ClassDoc } from './ClassDoc'
+import { FunctionDoc } from './FunctionDoc'
+import { TableOfContents, generateClassToc, type TocItem } from './TableOfContents'
+
+/**
+ * Resolve an alias to its target in the API data
+ */
+function resolveAlias(alias: GriffeAlias, apiData: GriffeModule): GriffeMember | null {
+  const targetPath = alias.target_path
+  if (!targetPath) return null
+
+  // Split the target path into parts
+  const parts = targetPath.split('.')
+  const packageName = apiData.name
+
+  let current: GriffeModule | GriffeClass = apiData
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]
+
+    // Skip the package name if it matches
+    if (i === 0 && part === packageName) continue
+
+    // Look in members
+    if (current.members) {
+      const member: GriffeMember | undefined = current.members[part]
+      if (member) {
+        // Only modules and classes have members to recurse into
+        if (member.kind === 'module' || member.kind === 'class') {
+          current = member as GriffeModule | GriffeClass
+        } else {
+          // Found a function, attribute, or alias - return it
+          return member
+        }
+      } else {
+        return null
+      }
+    } else {
+      return null
+    }
+  }
+
+  return current
+}
+
+/**
+ * Generate TOC items based on item type
+ */
+function generateTocItems(item: GriffeMember, apiData: GriffeModule): TocItem[] {
+  // Resolve aliases first
+  if (item.kind === 'alias') {
+    const resolved = resolveAlias(item as GriffeAlias, apiData)
+    if (resolved) {
+      return generateTocItems(resolved, apiData)
+    }
+    return []
+  }
+
+  if (item.kind === 'class') {
+    return generateClassToc(item as GriffeClass)
+  }
+  if (item.kind === 'function') {
+    const fn = item as GriffeFunction
+    const items: TocItem[] = [{ id: fn.name, title: fn.name, level: 1 }]
+    if (fn.parameters && fn.parameters.length > 0) {
+      items.push({ id: 'parameters', title: 'Parameters', level: 2 })
+    }
+    return items
+  }
+  if (item.kind === 'module') {
+    const mod = item as GriffeModule
+    const items: TocItem[] = [{ id: mod.name, title: mod.name, level: 1 }]
+    if (mod.members) {
+      const members = Object.values(mod.members)
+      const classes = members.filter(m => m.kind === 'class')
+      const functions = members.filter(m => m.kind === 'function')
+
+      if (classes.length > 0) {
+        items.push({ id: 'classes', title: 'Classes', level: 2 })
+      }
+      if (functions.length > 0) {
+        items.push({ id: 'functions', title: 'Functions', level: 2 })
+      }
+    }
+    return items
+  }
+  return []
+}
+
+/**
+ * Determine what kind of content to render based on the current item
+ */
+function APIContent({
+  item,
+  prefix,
+  currentPath,
+  apiData,
+  displayPath,
+  githubUrl,
+}: {
+  item: GriffeMember
+  prefix: string
+  currentPath: string
+  apiData: GriffeModule
+  /** Override the display path (used for aliases to show alias name instead of target) */
+  displayPath?: string
+  /** GitHub repository URL for "Open in GitHub" links */
+  githubUrl?: string
+}) {
+  // Handle aliases by resolving to target
+  if (item.kind === 'alias') {
+    const alias = item as GriffeAlias
+    const resolved = resolveAlias(alias, apiData)
+    if (resolved) {
+      // Pass the alias path as displayPath so title shows "strawberry.enum" not "strawberry.types.enum.enum"
+      const aliasDisplayPath = alias.path || `${apiData.name}.${alias.name}`
+      return <APIContent item={resolved} prefix={prefix} currentPath={currentPath} apiData={apiData} displayPath={aliasDisplayPath} githubUrl={githubUrl} />
+    }
+    // Could not resolve alias
+    return (
+      <div className="text-gray-600 dark:text-gray-300">
+        <p>Could not resolve alias: {alias.target_path}</p>
+      </div>
+    )
+  }
+
+  switch (item.kind) {
+    case 'module':
+      return <ModuleDoc module={item as GriffeModule} prefix={prefix} showFull displayPath={displayPath} githubUrl={githubUrl} />
+
+    case 'class':
+      return <ClassDoc cls={item as GriffeClass} prefix={prefix} currentPath={currentPath} displayPath={displayPath} githubUrl={githubUrl} />
+
+    case 'function':
+      return <FunctionDoc fn={item as GriffeFunction} displayPath={displayPath} githubUrl={githubUrl} />
+
+    default:
+      return (
+        <div className="text-gray-600 dark:text-gray-300">
+          <p>Unknown item type: {item.kind}</p>
+          <pre className="mt-4 text-xs bg-gray-100 dark:bg-gray-800 p-4 rounded overflow-auto">
+            {JSON.stringify(item, null, 2)}
+          </pre>
+        </div>
+      )
+  }
+}
+
+/**
+ * Main API documentation page component.
+ *
+ * Renders API documentation with a separate sidebar navigation.
+ * Automatically handles different item types (modules, classes, functions).
+ *
+ * @example
+ * // In your pages configuration:
+ * createDocsApp({
+ *   pages: {
+ *     'api/APIPage': APIPage,
+ *     // ...
+ *   }
+ * })
+ */
+export function APIPage({
+  apiData,
+  currentItem,
+  currentPath,
+  currentModule,
+  apiNav,
+  prefix,
+  logoUrl,
+  logoInvertedUrl,
+  footerLogoUrl,
+  footerLogoInvertedUrl,
+  githubUrl,
+  navLinks,
+  header,
+  headerHeight,
+  footer,
+}: APIPageProps) {
+  // Determine what to render
+  const itemToRender = currentItem || apiData
+
+  // Determine the title
+  let title = 'API Reference'
+  if (itemToRender) {
+    const name = itemToRender.name || currentModule
+    const kind = itemToRender.kind
+    title = `${name} (${kind}) - API Reference`
+  }
+
+  // Generate table of contents
+  const tocItems = itemToRender ? generateTocItems(itemToRender, apiData) : []
+
+  return (
+    <APILayout
+      title={title}
+      apiNav={apiNav}
+      currentPath={currentPath}
+      logoUrl={logoUrl}
+      logoInvertedUrl={logoInvertedUrl}
+      footerLogoUrl={footerLogoUrl}
+      footerLogoInvertedUrl={footerLogoInvertedUrl}
+      githubUrl={githubUrl}
+      navLinks={navLinks}
+      rightSidebar={tocItems.length > 0 ? <TableOfContents items={tocItems} /> : undefined}
+      header={header}
+      headerHeight={headerHeight}
+      footer={footer}
+    >
+      <APIContent item={itemToRender} prefix={prefix} currentPath={currentPath} apiData={apiData} githubUrl={githubUrl} />
+    </APILayout>
+  )
+}

package/src/components/api/Breadcrumb.tsx

@@ -0,0 +1,98 @@
+import { Link } from '@inertiajs/react'
+
+interface BreadcrumbItem {
+  label: string
+  href?: string
+}
+
+interface BreadcrumbProps {
+  items: BreadcrumbItem[]
+  className?: string
+}
+
+/**
+ * Breadcrumb navigation for API documentation pages.
+ * Shows the path: API > Module > Class
+ */
+export function Breadcrumb({ items, className = '' }: BreadcrumbProps) {
+  if (items.length === 0) return null
+
+  return (
+    <nav className={`flex items-center gap-2 text-sm mb-4 ${className}`}>
+      {items.map((item, index) => (
+        <span key={index} className="flex items-center gap-2">
+          {index > 0 && (
+            <ChevronIcon className="text-gray-400 dark:text-gray-500" />
+          )}
+          {item.href ? (
+            <Link
+              href={item.href}
+              className="text-gray-500 dark:text-gray-400 hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
+            >
+              {item.label}
+            </Link>
+          ) : (
+            <span className="text-gray-900 dark:text-white font-medium">
+              {item.label}
+            </span>
+          )}
+        </span>
+      ))}
+    </nav>
+  )
+}
+
+function ChevronIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      className={`w-4 h-4 ${className}`}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+    </svg>
+  )
+}
+
+/**
+ * Generate breadcrumb items from a path like "/api/strawberry/schema/schema/Schema"
+ * Combines module path into dotted notation: API > strawberry.schema.schema > Schema
+ */
+export function generateBreadcrumb(currentPath: string, prefix: string = '/api'): BreadcrumbItem[] {
+  const items: BreadcrumbItem[] = [{ label: 'API', href: prefix }]
+
+  // Remove prefix from path
+  const relativePath = currentPath.startsWith(prefix)
+    ? currentPath.slice(prefix.length)
+    : currentPath
+
+  // Split path into parts
+  const parts = relativePath.split('/').filter(Boolean)
+
+  if (parts.length === 0) return items
+
+  // If we have parts, combine all but the last into a module path
+  if (parts.length === 1) {
+    // Just one part - show it as the current item
+    items.push({ label: parts[0] })
+  } else {
+    // Multiple parts: combine all but last into module path
+    const moduleParts = parts.slice(0, -1)
+    const finalItem = parts[parts.length - 1]
+
+    // Build href for module path (link to the parent)
+    const moduleHref = prefix + '/' + moduleParts.join('/')
+
+    // Add module path as dotted notation
+    items.push({
+      label: moduleParts.join('.'),
+      href: moduleHref,
+    })
+
+    // Add final item (class/function name)
+    items.push({ label: finalItem })
+  }
+
+  return items
+}

package/src/components/api/ClassDoc.tsx

@@ -0,0 +1,257 @@
+import { useState } from 'react'
+import type { GriffeClass, GriffeFunction, GriffeAttribute, GriffeExpression } from '../../types'
+import { Docstring } from './Docstring'
+import { FunctionDoc } from './FunctionDoc'
+import { CodeSpan } from './CodeSpan'
+
+/**
+ * Render a type annotation expression or value to string
+ */
+function renderExpression(expr: GriffeExpression | string | undefined): string {
+  if (!expr) return ''
+  if (typeof expr === 'string') return expr
+  if (expr.str) return expr.str
+  if (expr.canonical) return expr.canonical
+
+  const exprAny = expr as any
+
+  // Handle ExprName with member reference
+  if (expr.name && typeof expr.name === 'string') return expr.name
+
+  // Handle ExprBoolOp (like `config or StrawberryConfig()`)
+  if (exprAny.cls === 'ExprBoolOp' && exprAny.operator && Array.isArray(exprAny.values)) {
+    return exprAny.values.map((v: any) => renderExpression(v)).join(` ${exprAny.operator} `)
+  }
+
+  // Handle ExprBinOp (like `type | None`)
+  if (exprAny.cls === 'ExprBinOp' && exprAny.left && exprAny.right) {
+    const left = renderExpression(exprAny.left)
+    const right = renderExpression(exprAny.right)
+    const op = exprAny.operator || '|'
+    return `${left} ${op} ${right}`
+  }
+
+  // Handle ExprCall (like `StrawberryConfig()`)
+  if (exprAny.cls === 'ExprCall' && exprAny.function) {
+    const funcName = renderExpression(exprAny.function)
+    const args = Array.isArray(exprAny.arguments)
+      ? exprAny.arguments.map((a: any) => renderExpression(a)).join(', ')
+      : ''
+    return `${funcName}(${args})`
+  }
+
+  // Handle ExprAttribute (like contextlib.asynccontextmanager)
+  if (exprAny.cls === 'ExprAttribute' && Array.isArray(exprAny.values)) {
+    return exprAny.values.map((v: any) => renderExpression(v)).join('.')
+  }
+
+  // Handle ExprList and ExprTuple
+  if ('elements' in exprAny && Array.isArray(exprAny.elements)) {
+    const inner = exprAny.elements.map((el: any) => renderExpression(el)).join(', ')
+    return exprAny.cls === 'ExprTuple' ? `(${inner})` : `[${inner}]`
+  }
+
+  // Handle ExprDict
+  if (exprAny.cls === 'ExprDict' && Array.isArray(exprAny.keys) && Array.isArray(exprAny.values)) {
+    const pairs = exprAny.keys.map((k: any, i: number) =>
+      `${renderExpression(k)}: ${renderExpression(exprAny.values[i])}`
+    ).join(', ')
+    return `{${pairs}}`
+  }
+
+  // Handle ExprSubscript (like Dict[str, int])
+  if (exprAny.left && exprAny.slice) {
+    const left = renderExpression(exprAny.left)
+    const slice = renderExpression(exprAny.slice)
+    return `${left}[${slice}]`
+  }
+
+  // Handle slice expressions
+  if ('slice' in exprAny && exprAny.slice && !exprAny.left) {
+    return renderExpression(exprAny.slice)
+  }
+
+  // Fallback for unknown expressions - try to avoid [object Object]
+  if (typeof expr === 'object') {
+    return JSON.stringify(expr)
+  }
+
+  return String(expr)
+}
+
+/**
+ * Collapsible method item with arrow indicator (strawberry.rocks style)
+ */
+function CollapsibleMethod({ method }: { method: GriffeFunction }) {
+  const [expanded, setExpanded] = useState(false)
+
+  return (
+    <div className="border-b border-gray-200 dark:border-gray-700 last:border-b-0">
+      <button
+        onClick={() => setExpanded(!expanded)}
+        className="w-full flex items-center gap-2 py-3 text-left hover:bg-gray-50 dark:hover:bg-gray-800/50 transition-colors"
+      >
+        <span className="font-mono text-base font-semibold text-gray-900 dark:text-white">
+          {method.name}
+        </span>
+        <span className="text-gray-400 text-sm">
+          {expanded ? '▲' : '▼'}
+        </span>
+      </button>
+      {expanded && (
+        <div className="pb-6">
+          <FunctionDoc fn={method} isMethod showName={false} />
+        </div>
+      )}
+    </div>
+  )
+}
+
+interface ClassDocProps {
+  cls: GriffeClass
+  /** URL prefix for links */
+  prefix?: string
+  /** Current path for breadcrumb */
+  currentPath?: string
+  /** GitHub repo URL for source links */
+  githubUrl?: string
+  /** Additional CSS class */
+  className?: string
+  /** Override display path (e.g., for aliases to show alias name instead of target path) */
+  displayPath?: string
+}
+
+/**
+ * Renders documentation for a class matching strawberry.rocks design.
+ * Includes: Title, Constructor, Methods (collapsible), Attributes, and footer.
+ */
+export function ClassDoc({ cls, prefix: _prefix = '/api', currentPath: _currentPath, githubUrl, className = '', displayPath }: ClassDocProps) {
+  const members = cls.members ?? {}
+
+  // Separate members by type
+  const methods: GriffeFunction[] = []
+  const attributes: GriffeAttribute[] = []
+
+  for (const member of Object.values(members)) {
+    // Skip private members
+    if (member.name.startsWith('_') && !member.name.startsWith('__')) continue
+
+    if (member.kind === 'function') {
+      methods.push(member as GriffeFunction)
+    } else if (member.kind === 'attribute') {
+      attributes.push(member as GriffeAttribute)
+    }
+  }
+
+  // Sort methods: __init__ first, then public methods alphabetically, skip other dunders
+  const initMethod = methods.find(m => m.name === '__init__')
+  const publicMethods = methods
+    .filter(m => m.name !== '__init__' && !m.name.startsWith('_'))
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  // Sort attributes alphabetically, skip private ones
+  const publicAttributes = attributes
+    .filter(a => !a.name.startsWith('_'))
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  // Get relative filepath for display (prefer package-relative path)
+  const relativeFilepath = cls.relative_package_filepath || cls.relative_filepath || cls.filepath
+
+  // Build GitHub URL for source link
+  const githubSourceUrl = githubUrl && relativeFilepath && cls.lineno
+    ? `${githubUrl}/blob/main/${relativeFilepath}#L${cls.lineno}-L${cls.endlineno || cls.lineno}`
+    : undefined
+
+  return (
+    <div className={className}>
+      {/* Title - monospace like strawberry.rocks */}
+      <h1 id={cls.name} className="font-mono text-2xl font-normal text-gray-900 dark:text-white mb-8">
+        {displayPath || cls.path || cls.name}
+      </h1>
+
+      {/* Constructor section */}
+      {initMethod && (
+        <section id="constructor" className="mb-8">
+          <h2 className="text-2xl font-bold text-gray-900 dark:text-white mb-4">
+            Constructor:
+          </h2>
+
+          {/* Docstring description */}
+          {initMethod.docstring && (
+            <div className="mb-6">
+              <Docstring docstring={initMethod.docstring} showOnlyText />
+            </div>
+          )}
+
+          <FunctionDoc fn={initMethod} isMethod showName={false} />
+        </section>
+      )}
+
+      {/* Class docstring if no __init__ */}
+      {!initMethod && cls.docstring && (
+        <section className="mb-8">
+          <Docstring docstring={cls.docstring} />
+        </section>
+      )}
+
+      {/* Methods section - collapsible */}
+      {publicMethods.length > 0 && (
+        <section id="methods" className="mb-8">
+          <h2 className="text-2xl font-bold text-gray-900 dark:text-white mb-4">
+            Methods:
+          </h2>
+          <div>
+            {publicMethods.map((method) => (
+              <CollapsibleMethod key={method.name} method={method} />
+            ))}
+          </div>
+        </section>
+      )}
+
+      {/* Attributes section */}
+      {publicAttributes.length > 0 && (
+        <section id="attributes" className="mb-8">
+          <h2 className="text-2xl font-bold text-gray-900 dark:text-white mb-4">
+            Attributes:
+          </h2>
+          <div className="space-y-2">
+            {publicAttributes.map((attr) => (
+              <div key={attr.name} className="flex items-baseline gap-2">
+                <CodeSpan>{attr.name}:</CodeSpan>
+                {attr.annotation && (
+                  <span className="text-sm text-gray-600 dark:text-gray-400 font-mono">
+                    {renderExpression(attr.annotation)}
+                  </span>
+                )}
+              </div>
+            ))}
+          </div>
+        </section>
+      )}
+
+      {/* Footer with file path and GitHub link */}
+      {relativeFilepath && (
+        <footer className="mt-8 pt-6 border-t border-gray-200 dark:border-gray-700 space-y-4">
+          <p className="flex items-center gap-2">
+            <span className="text-sm font-semibold text-gray-500 dark:text-gray-400 uppercase tracking-wide">
+              File path:
+            </span>
+            <CodeSpan allowCopy>{relativeFilepath}</CodeSpan>
+          </p>
+          {githubSourceUrl && (
+            <p>
+              <a
+                href={githubSourceUrl}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-sm font-semibold text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 uppercase tracking-wide"
+              >
+                Open in GitHub
+              </a>
+            </p>
+          )}
+        </footer>
+      )}
+    </div>
+  )
+}

package/src/components/api/CodeSpan.tsx

@@ -0,0 +1,53 @@
+import { cn } from '../../lib/utils'
+
+interface CodeSpanProps {
+  children: React.ReactNode
+  /** Visual variant */
+  variant?: 'default' | 'simple'
+  /** Allow copy on click */
+  allowCopy?: boolean
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Styled code span component matching strawberry.rocks design.
+ * Uses coral/pink color for code badges.
+ */
+export function CodeSpan({ children, variant = 'default', allowCopy = false, className }: CodeSpanProps) {
+  const handleCopy = () => {
+    if (allowCopy && typeof children === 'string') {
+      navigator.clipboard.writeText(children)
+    }
+  }
+
+  if (variant === 'simple') {
+    return (
+      <code
+        onClick={allowCopy ? handleCopy : undefined}
+        className={cn(
+          'font-mono text-[0.9em] font-semibold text-gray-900 dark:text-white',
+          allowCopy && 'cursor-pointer hover:text-primary-600 dark:hover:text-primary-400',
+          className
+        )}
+      >
+        {children}
+      </code>
+    )
+  }
+
+  return (
+    <code
+      onClick={allowCopy ? handleCopy : undefined}
+      className={cn(
+        'inline-flex items-center px-2 py-0.5 rounded font-mono text-sm',
+        'bg-red-50 text-red-600 border border-red-200',
+        'dark:bg-red-900/20 dark:text-red-400 dark:border-red-800/50',
+        allowCopy && 'cursor-pointer hover:bg-red-100 dark:hover:bg-red-900/30',
+        className
+      )}
+    >
+      {children}
+    </code>
+  )
+}