@usecross/docs 0.11.0 → 0.12.0

package/src/components/api/Signature.tsx

@@ -0,0 +1,317 @@
+import { useState } from 'react'
+import type { GriffeFunction, GriffeParameter, GriffeExpression } from '../../types'
+
+/**
+ * Render a type annotation expression 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
+  if (typeof expr === 'object') {
+    return JSON.stringify(expr)
+  }
+
+  return String(expr)
+}
+
+/**
+ * Render a parameter with its type annotation and default value
+ */
+function renderParameter(param: GriffeParameter): string {
+  let result = ''
+
+  // Handle special parameter kinds
+  if (param.kind === 'var-positional') {
+    result = `*${param.name}`
+  } else if (param.kind === 'var-keyword') {
+    result = `**${param.name}`
+  } else {
+    result = param.name
+  }
+
+  // Add type annotation
+  if (param.annotation) {
+    const annotation = renderExpression(param.annotation)
+    if (annotation) {
+      result += `: ${annotation}`
+    }
+  }
+
+  // Add default value
+  if (param.default) {
+    result += ` = ${renderExpression(param.default)}`
+  }
+
+  return result
+}
+
+/**
+ * Copy icon component
+ */
+function CopyIcon() {
+  return (
+    <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+    </svg>
+  )
+}
+
+/**
+ * Check icon component
+ */
+function CheckIcon() {
+  return (
+    <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+    </svg>
+  )
+}
+
+interface SignatureProps {
+  fn: GriffeFunction
+  /** Show full path or just function name */
+  showPath?: boolean
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Renders a Python function/method signature with syntax highlighting.
+ * Uses dark background style matching strawberry.rocks.
+ */
+export function Signature({ fn, showPath = false, className = '' }: SignatureProps) {
+  const [copied, setCopied] = useState(false)
+  const name = showPath && fn.path ? fn.path : fn.name
+  const isAsync = fn.is_async
+
+  // Filter out 'self' for cleaner display
+  const displayParams = fn.parameters?.filter(p => p.name !== 'self') ?? []
+
+  // Render return type
+  const returnType = renderExpression(fn.returns)
+
+  // Build parameter string with proper separators for positional-only and keyword-only
+  const buildParamString = (params: GriffeParameter[]): string => {
+    const parts: string[] = []
+    const hasVarPositional = params.some(p => p.kind === 'var-positional')
+    let addedBareAsterisk = false
+
+    for (let i = 0; i < params.length; i++) {
+      const param = params[i]
+      const nextParam = params[i + 1]
+
+      // Add the parameter itself
+      parts.push(renderParameter(param))
+
+      // Add / after last positional-only parameter
+      if (param.kind === 'positional-only' && nextParam && nextParam.kind !== 'positional-only') {
+        parts.push('/')
+      }
+
+      // Add bare * before first keyword-only parameter (if no *args)
+      if (!hasVarPositional && !addedBareAsterisk && nextParam?.kind === 'keyword-only' && param.kind !== 'keyword-only') {
+        parts.push('*')
+        addedBareAsterisk = true
+      }
+    }
+
+    return parts.join(', ')
+  }
+
+  // Build the plain text signature for copying
+  const plainSignature = (() => {
+    const params = buildParamString(displayParams)
+    const prefix = isAsync ? 'async def ' : 'def '
+    return returnType
+      ? `${prefix}${name}(${params}) -> ${returnType}`
+      : `${prefix}${name}(${params})`
+  })()
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(plainSignature)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  // Build list of parameter tokens (params + separators like / and *)
+  type ParamToken = { type: 'param'; param: GriffeParameter } | { type: 'separator'; value: '/' | '*' }
+  const buildParamTokens = (params: GriffeParameter[]): ParamToken[] => {
+    const tokens: ParamToken[] = []
+    const hasVarPositional = params.some(p => p.kind === 'var-positional')
+    let addedBareAsterisk = false
+
+    for (let i = 0; i < params.length; i++) {
+      const param = params[i]
+      const nextParam = params[i + 1]
+
+      tokens.push({ type: 'param', param })
+
+      // Add / after last positional-only parameter
+      if (param.kind === 'positional-only' && nextParam && nextParam.kind !== 'positional-only') {
+        tokens.push({ type: 'separator', value: '/' })
+      }
+
+      // Add bare * before first keyword-only parameter (if no *args)
+      if (!hasVarPositional && !addedBareAsterisk && nextParam?.kind === 'keyword-only' && param.kind !== 'keyword-only') {
+        tokens.push({ type: 'separator', value: '*' })
+        addedBareAsterisk = true
+      }
+    }
+
+    return tokens
+  }
+
+  const paramTokens = buildParamTokens(displayParams)
+
+  // Render a single parameter element
+  const renderParamElement = (param: GriffeParameter, multiline: boolean) => (
+    <>
+      {param.kind === 'var-positional' && <span className="text-gray-400">*</span>}
+      {param.kind === 'var-keyword' && <span className="text-gray-400">**</span>}
+      <span className="text-orange-300">{param.name}</span>
+      {param.annotation && (
+        <>
+          <span className="text-gray-400">: </span>
+          <span className="text-emerald-400">{renderExpression(param.annotation)}</span>
+        </>
+      )}
+      {param.default && (
+        <>
+          <span className="text-gray-400"> = </span>
+          <span className="text-blue-300">{renderExpression(param.default)}</span>
+        </>
+      )}
+      {multiline && <span className="text-gray-400">,</span>}
+    </>
+  )
+
+  // Determine if we need multi-line formatting
+  const needsMultiline = displayParams.length > 3
+
+  return (
+    <div className={`relative group ${className}`}>
+      {/* Dark code block like strawberry.rocks */}
+      <div className="font-mono text-sm bg-gray-900 dark:bg-gray-950 rounded-lg p-4 overflow-x-auto">
+        <code className="text-gray-100">
+          {isAsync && <span className="text-purple-400">async </span>}
+          <span className="text-blue-400">def</span>
+          {' '}
+          <span className="text-yellow-300">{name}</span>
+          <span className="text-gray-400">(</span>
+          {paramTokens.length > 0 && (
+            needsMultiline ? (
+              // Multi-line for many parameters
+              <>
+                {paramTokens.map((token, i) => (
+                  token.type === 'param' ? (
+                    <span key={token.param.name} className="block pl-4">
+                      {renderParamElement(token.param, true)}
+                    </span>
+                  ) : (
+                    <span key={`sep-${i}`} className="block pl-4">
+                      <span className="text-gray-400">{token.value},</span>
+                    </span>
+                  )
+                ))}
+              </>
+            ) : (
+              // Single line for few parameters
+              paramTokens.map((token, i) => (
+                token.type === 'param' ? (
+                  <span key={token.param.name}>
+                    {i > 0 && <span className="text-gray-400">, </span>}
+                    {renderParamElement(token.param, false)}
+                  </span>
+                ) : (
+                  <span key={`sep-${i}`}>
+                    <span className="text-gray-400">, {token.value}</span>
+                  </span>
+                )
+              ))
+            )
+          )}
+          <span className="text-gray-400">)</span>
+          {returnType && (
+            <>
+              <span className="text-gray-400"> -&gt; </span>
+              <span className="text-emerald-400">{returnType}</span>
+            </>
+          )}
+          <span className="text-gray-400">:</span>
+          <span className="block pl-2 text-gray-500">...</span>
+        </code>
+      </div>
+
+      {/* Copy button */}
+      <button
+        onClick={handleCopy}
+        className="absolute top-3 right-3 p-1.5 rounded bg-gray-700 hover:bg-gray-600 opacity-0 group-hover:opacity-100 transition-opacity text-gray-300 hover:text-white"
+        title="Copy to clipboard"
+      >
+        {copied ? <CheckIcon /> : <CopyIcon />}
+      </button>
+    </div>
+  )
+}

package/src/components/api/TableOfContents.tsx

@@ -0,0 +1,50 @@
+// Re-export the shared TableOfContents component
+export { TableOfContents } from '../TableOfContents'
+export type { TOCItem as TocItem } from '../../types'
+
+/**
+ * Generate TOC items from a class's members
+ * Filters out private members (except __init__) to match ClassDoc rendering
+ */
+export function generateClassToc(cls: {
+  name: string
+  members?: Record<string, { kind: string; name: string }>
+}): { id: string; title: string; level: number }[] {
+  const items: { id: string; title: string; level: number }[] = []
+
+  // Add class name as top item
+  items.push({ id: cls.name, title: cls.name, level: 1 })
+
+  if (!cls.members) return items
+
+  const members = Object.values(cls.members)
+
+  // Filter methods: __init__ is special, skip other private/dunder methods
+  const methods = members.filter(m => m.kind === 'function')
+  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))
+
+  // Filter attributes: skip private ones
+  const publicAttributes = members
+    .filter(m => m.kind === 'attribute' && !m.name.startsWith('_'))
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  // Add constructor section if exists
+  if (initMethod) {
+    items.push({ id: 'constructor', title: 'Constructor', level: 2 })
+  }
+
+  // Add methods section header if there are public methods
+  if (publicMethods.length > 0) {
+    items.push({ id: 'methods', title: 'Methods', level: 2 })
+  }
+
+  // Add attributes section header if there are public attributes
+  if (publicAttributes.length > 0) {
+    items.push({ id: 'attributes', title: 'Attributes', level: 2 })
+  }
+
+  return items
+}

package/src/components/api/index.ts

@@ -0,0 +1,17 @@
+/**
+ * API Documentation Components
+ *
+ * Components for rendering Python API documentation generated by Griffe.
+ */
+
+export { APIPage } from './APIPage'
+export { APILayout } from './APILayout'
+export { ModuleDoc } from './ModuleDoc'
+export { ClassDoc } from './ClassDoc'
+export { FunctionDoc } from './FunctionDoc'
+export { Signature } from './Signature'
+export { Docstring } from './Docstring'
+export { ParameterTable } from './ParameterTable'
+export { CodeSpan } from './CodeSpan'
+export { TableOfContents, generateClassToc, type TocItem } from './TableOfContents'
+export { Breadcrumb, generateBreadcrumb } from './Breadcrumb'

package/src/components/index.ts

@@ -9,3 +9,15 @@ export { Sidebar } from './Sidebar'
 export { TableOfContents } from './TableOfContents'
 export { ThemeProvider, useTheme, themeInitScript } from './ThemeProvider'
 export { ThemeToggle } from './ThemeToggle'
+
+// API Documentation Components
+export {
+  APIPage,
+  APILayout,
+  ModuleDoc,
+  ClassDoc,
+  FunctionDoc,
+  Signature,
+  Docstring,
+  ParameterTable,
+} from './api'

package/src/index.ts

@@ -15,6 +15,15 @@ export {
   ThemeToggle,
   useTheme,
   themeInitScript,
+  // API Documentation Components
+  APIPage,
+  APILayout,
+  ModuleDoc,
+  ClassDoc,
+  FunctionDoc,
+  Signature,
+  Docstring,
+  ParameterTable,
 } from './components'
 
 // HomePage sub-components (for compound component pattern)
@@ -48,6 +57,28 @@ export type {
   SidebarProps,
   TableOfContentsProps,
   TOCItem,
+  // API Documentation Types
+  GriffeKind,
+  GriffeDocstringSectionKind,
+  GriffeExpression,
+  GriffeParameter,
+  GriffeDocstringElement,
+  GriffeDocstringSection,
+  GriffeDocstring,
+  GriffeDecorator,
+  GriffeObjectBase,
+  GriffeFunction,
+  GriffeAttribute,
+  GriffeClass,
+  GriffeModule,
+  GriffeMember,
+  APIPageProps,
+  ModuleDocProps,
+  ClassDocProps,
+  FunctionDocProps,
+  SignatureProps,
+  DocstringProps,
+  ParameterTableProps,
 } from './types'
 
 export type { Theme, ResolvedTheme } from './components/ThemeProvider'

package/src/types.ts

@@ -53,7 +53,10 @@ export interface SharedProps {
 /** Table of contents item */
 export interface TOCItem {
   id: string
-  text: string
+  /** Display text (use either text or title) */
+  text?: string
+  /** Display title (use either text or title) */
+  title?: string
   level: number
 }
 
@@ -96,7 +99,7 @@ export interface DocsLayoutProps {
 export interface TableOfContentsProps {
   items: TOCItem[]
   className?: string
-  style: any
+  style?: React.CSSProperties
 }
 
 /** Props for Sidebar component */
@@ -134,3 +137,216 @@ export interface DocsAppConfig {
   /** Custom components to use in markdown (e.g., Alert, Card, etc.) */
   components?: Record<string, React.ComponentType<any>>
 }
+
+// =============================================================================
+// Griffe API Documentation Types
+// =============================================================================
+
+/** Griffe object kinds */
+export type GriffeKind = 'module' | 'class' | 'function' | 'attribute'
+
+/** Griffe docstring section kinds */
+export type GriffeDocstringSectionKind =
+  | 'text'
+  | 'parameters'
+  | 'returns'
+  | 'yields'
+  | 'receives'
+  | 'raises'
+  | 'warns'
+  | 'examples'
+  | 'attributes'
+  | 'other'
+  | 'deprecated'
+  | 'admonition'
+
+/** Griffe expression (type annotation) */
+export interface GriffeExpression {
+  /** String representation of the expression */
+  str?: string
+  /** Canonical string representation */
+  canonical?: string
+  /** For name expressions */
+  name?: string
+  /** For subscript expressions (e.g., List[int]) */
+  slice?: GriffeExpression
+  /** For compound expressions */
+  left?: GriffeExpression
+  right?: GriffeExpression
+}
+
+/** Griffe parameter */
+export interface GriffeParameter {
+  name: string
+  kind: 'positional-only' | 'positional-or-keyword' | 'var-positional' | 'keyword-only' | 'var-keyword'
+  annotation?: GriffeExpression | string
+  default?: string
+}
+
+/** Griffe docstring section element (for parameters, returns, etc.) */
+export interface GriffeDocstringElement {
+  name?: string
+  annotation?: GriffeExpression | string
+  description?: string
+  value?: string
+}
+
+/** Griffe docstring section */
+export interface GriffeDocstringSection {
+  kind: GriffeDocstringSectionKind
+  value?: string | GriffeDocstringElement[]
+  title?: string
+}
+
+/** Griffe parsed docstring */
+export interface GriffeDocstring {
+  value: string
+  parsed?: GriffeDocstringSection[]
+}
+
+/** Griffe decorator */
+export interface GriffeDecorator {
+  value: string
+  lineno?: number
+}
+
+/** Base Griffe object with common properties */
+export interface GriffeObjectBase {
+  kind: GriffeKind
+  name: string
+  path?: string
+  filepath?: string
+  /** Relative file path (set by cross-docs) */
+  relative_filepath?: string
+  /** Relative file path within the package (set by Griffe) */
+  relative_package_filepath?: string
+  lineno?: number
+  endlineno?: number
+  docstring?: GriffeDocstring
+  labels?: string[]
+}
+
+/** Griffe function/method */
+export interface GriffeFunction extends GriffeObjectBase {
+  kind: 'function'
+  parameters?: GriffeParameter[]
+  returns?: GriffeExpression | string
+  decorators?: GriffeDecorator[]
+  /** Whether this is an async function */
+  is_async?: boolean
+}
+
+/** Griffe attribute */
+export interface GriffeAttribute extends GriffeObjectBase {
+  kind: 'attribute'
+  annotation?: GriffeExpression | string
+  value?: string
+}
+
+/** Griffe class */
+export interface GriffeClass extends GriffeObjectBase {
+  kind: 'class'
+  bases?: Array<GriffeExpression | string>
+  decorators?: GriffeDecorator[]
+  members?: Record<string, GriffeMember>
+}
+
+/** Griffe module */
+export interface GriffeModule extends GriffeObjectBase {
+  kind: 'module'
+  members?: Record<string, GriffeMember>
+  /** Generator metadata added by cross-docs */
+  _generator?: string
+  _plugin?: string
+  _version?: string
+}
+
+/** Griffe alias (re-export) */
+export interface GriffeAlias {
+  kind: 'alias'
+  name: string
+  path?: string
+  /** The target path this alias points to */
+  target_path: string
+  lineno?: number
+  endlineno?: number
+}
+
+/** Union of all Griffe member types */
+export type GriffeMember = GriffeModule | GriffeClass | GriffeFunction | GriffeAttribute | GriffeAlias
+
+/** Props for API documentation pages */
+export interface APIPageProps {
+  /** Full API data (the entire module tree) */
+  apiData: GriffeModule
+  /** Current item being viewed (module, class, or function) */
+  currentItem?: GriffeMember
+  /** Current URL path */
+  currentPath: string
+  /** Current module name */
+  currentModule: string
+  /** Navigation structure for API sidebar */
+  apiNav: NavSection[]
+  /** URL prefix for API links (e.g., /docs/api-reference) */
+  prefix: string
+  /** Logo URL */
+  logoUrl?: string
+  /** Logo URL for dark mode */
+  logoInvertedUrl?: string
+  /** Footer logo URL */
+  footerLogoUrl?: string
+  /** Footer logo URL for dark mode */
+  footerLogoInvertedUrl?: string
+  /** GitHub URL */
+  githubUrl?: string
+  /** Navigation links */
+  navLinks?: Array<{ label: string; href: string }>
+  /** 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
+}
+
+/** Props for ModuleDoc component */
+export interface ModuleDocProps {
+  module: GriffeModule
+  /** URL prefix for links */
+  prefix?: string
+}
+
+/** Props for ClassDoc component */
+export interface ClassDocProps {
+  cls: GriffeClass
+  /** URL prefix for links */
+  prefix?: string
+}
+
+/** Props for FunctionDoc component */
+export interface FunctionDocProps {
+  fn: GriffeFunction
+  /** Whether this is a method (inside a class) */
+  isMethod?: boolean
+}
+
+/** Props for Signature component */
+export interface SignatureProps {
+  fn: GriffeFunction
+  /** Show full path or just name */
+  showPath?: boolean
+}
+
+/** Props for Docstring component */
+export interface DocstringProps {
+  docstring: GriffeDocstring
+  /** Show raw text instead of parsed sections */
+  raw?: boolean
+}
+
+/** Props for ParameterTable component */
+export interface ParameterTableProps {
+  parameters: GriffeParameter[]
+  /** Docstring sections for parameter descriptions */
+  docstringSections?: GriffeDocstringSection[]
+}