@usecross/docs 0.10.2 → 0.12.0

package/src/components/api/ParameterTable.tsx

@@ -0,0 +1,183 @@
+import type { GriffeParameter, GriffeDocstringSection, GriffeDocstringElement, GriffeExpression } from '../../types'
+import { CodeSpan } from './CodeSpan'
+
+/**
+ * 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)
+}
+
+/**
+ * Get parameter description from docstring sections
+ */
+function getParamDescription(
+  paramName: string,
+  docstringSections?: GriffeDocstringSection[]
+): string | undefined {
+  if (!docstringSections) return undefined
+
+  for (const section of docstringSections) {
+    if (section.kind === 'parameters' && Array.isArray(section.value)) {
+      const param = (section.value as GriffeDocstringElement[]).find(
+        (p) => p.name === paramName
+      )
+      if (param) return param.description
+    }
+  }
+  return undefined
+}
+
+interface ParameterTableProps {
+  parameters: GriffeParameter[]
+  /** Docstring sections for parameter descriptions */
+  docstringSections?: GriffeDocstringSection[]
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Renders a two-column parameter list matching strawberry.rocks design.
+ * Left column: parameter name badge
+ * Right column: description, type, and default value
+ */
+export function ParameterTable({ parameters, docstringSections, className = '' }: ParameterTableProps) {
+  if (!parameters || parameters.length === 0) return null
+
+  // Filter out 'self' parameter for cleaner display
+  const displayParams = parameters.filter(p => p.name !== 'self')
+
+  if (displayParams.length === 0) return null
+
+  return (
+    <ol className={`list-none p-0 ${className}`}>
+      {displayParams.map((param, index) => {
+        const description = getParamDescription(param.name, docstringSections)
+        const annotation = renderExpression(param.annotation)
+        const defaultValue = renderExpression(param.default)
+        const isLast = index === displayParams.length - 1
+
+        return (
+          <li
+            key={param.name}
+            className="contents"
+          >
+            <div className={`grid grid-cols-[max-content_1fr] items-baseline gap-x-8 gap-y-2 py-6 ${!isLast ? 'border-b border-gray-200 dark:border-gray-700' : ''}`}>
+              {/* Parameter name badge - left column */}
+              <div className="flex-shrink-0">
+                <CodeSpan>
+                  {param.kind === 'var-positional' && '*'}
+                  {param.kind === 'var-keyword' && '**'}
+                  {param.name}:
+                </CodeSpan>
+              </div>
+
+              {/* Description and metadata - right column */}
+              <div className="space-y-3">
+                {/* Description */}
+                {description && (
+                  <p className="text-gray-700 dark:text-gray-300 leading-relaxed">
+                    {description}
+                  </p>
+                )}
+
+                {/* Type and Default in definition list style */}
+                <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-2">
+                  {annotation && (
+                    <>
+                      <dt className="font-semibold text-gray-500 dark:text-gray-400">
+                        Type
+                      </dt>
+                      <dd className="m-0">
+                        <CodeSpan>{annotation}</CodeSpan>
+                      </dd>
+                    </>
+                  )}
+
+                  {defaultValue && (
+                    <>
+                      <dt className="font-semibold text-gray-500 dark:text-gray-400">
+                        Default
+                      </dt>
+                      <dd className="m-0">
+                        <CodeSpan>{defaultValue}</CodeSpan>
+                      </dd>
+                    </>
+                  )}
+                </dl>
+              </div>
+            </div>
+          </li>
+        )
+      })}
+    </ol>
+  )
+}

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

@@ -1,6 +1,6 @@
 export { CodeBlock, InlineCode } from './CodeBlock'
 export { DocSetSelector } from './DocSetSelector'
-export { DocsLayout } from './DocsLayout'
+export { DocsLayout, MobileMenuButton } from './DocsLayout'
 export { DocsPage } from './DocsPage'
 export { EmojiConfetti } from './EmojiConfetti'
 export { HomePage } from './HomePage'
@@ -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

@@ -8,12 +8,22 @@ export {
   HomePage,
   InlineCode,
   Markdown,
+  MobileMenuButton,
   Sidebar,
   TableOfContents,
   ThemeProvider,
   ThemeToggle,
   useTheme,
   themeInitScript,
+  // API Documentation Components
+  APIPage,
+  APILayout,
+  ModuleDoc,
+  ClassDoc,
+  FunctionDoc,
+  Signature,
+  Docstring,
+  ParameterTable,
 } from './components'
 
 // HomePage sub-components (for compound component pattern)
@@ -47,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'