@usecross/docs 0.11.0 → 0.12.0

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>
+  )
+}

package/src/components/api/Docstring.tsx

@@ -0,0 +1,269 @@
+import type { GriffeDocstring, GriffeDocstringSection, GriffeDocstringElement, GriffeExpression } from '../../types'
+import { Markdown } from '../Markdown'
+
+/**
+ * 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)
+}
+
+interface DocstringSectionProps {
+  section: GriffeDocstringSection
+}
+
+function DocstringSection({ section }: DocstringSectionProps) {
+  switch (section.kind) {
+    case 'text':
+      return (
+        <div className="prose prose-sm dark:prose-invert max-w-none">
+          <Markdown content={section.value as string} />
+        </div>
+      )
+
+    case 'parameters':
+      return (
+        <div className="mt-4">
+          <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">Parameters</h4>
+          <dl className="space-y-2">
+            {(section.value as GriffeDocstringElement[])?.map((param) => (
+              <div key={param.name} className="grid grid-cols-[auto_1fr] gap-x-3">
+                <dt className="font-mono text-sm">
+                  <span className="text-orange-600 dark:text-orange-400">{param.name}</span>
+                  {param.annotation && (
+                    <span className="text-gray-500 dark:text-gray-400">
+                      {' '}({renderExpression(param.annotation)})
+                    </span>
+                  )}
+                </dt>
+                <dd className="text-sm text-gray-600 dark:text-gray-300">
+                  {param.description}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        </div>
+      )
+
+    case 'returns':
+      return (
+        <div className="mt-4">
+          <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">Returns</h4>
+          <div className="text-sm text-gray-600 dark:text-gray-300">
+            {Array.isArray(section.value) ? (
+              (section.value as GriffeDocstringElement[]).map((ret, i) => (
+                <div key={i}>
+                  {ret.annotation && (
+                    <span className="font-mono text-green-600 dark:text-green-400">
+                      {renderExpression(ret.annotation)}
+                    </span>
+                  )}
+                  {ret.description && <span> - {ret.description}</span>}
+                </div>
+              ))
+            ) : (
+              section.value
+            )}
+          </div>
+        </div>
+      )
+
+    case 'raises':
+      return (
+        <div className="mt-4">
+          <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">Raises</h4>
+          <dl className="space-y-2">
+            {(section.value as GriffeDocstringElement[])?.map((exc, i) => (
+              <div key={i} className="grid grid-cols-[auto_1fr] gap-x-3">
+                <dt className="font-mono text-sm text-red-600 dark:text-red-400">
+                  {exc.annotation ? renderExpression(exc.annotation) : exc.name}
+                </dt>
+                <dd className="text-sm text-gray-600 dark:text-gray-300">
+                  {exc.description}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        </div>
+      )
+
+    case 'examples':
+      return (
+        <div className="mt-4">
+          <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">Examples</h4>
+          <pre className="bg-gray-100 dark:bg-gray-800 rounded-lg p-4 overflow-x-auto text-sm">
+            <code>{section.value as string}</code>
+          </pre>
+        </div>
+      )
+
+    case 'attributes':
+      return (
+        <div className="mt-4">
+          <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">Attributes</h4>
+          <dl className="space-y-2">
+            {(section.value as GriffeDocstringElement[])?.map((attr) => (
+              <div key={attr.name} className="grid grid-cols-[auto_1fr] gap-x-3">
+                <dt className="font-mono text-sm">
+                  <span className="text-orange-600 dark:text-orange-400">{attr.name}</span>
+                  {attr.annotation && (
+                    <span className="text-gray-500 dark:text-gray-400">
+                      {' '}({renderExpression(attr.annotation)})
+                    </span>
+                  )}
+                </dt>
+                <dd className="text-sm text-gray-600 dark:text-gray-300">
+                  {attr.description}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        </div>
+      )
+
+    case 'deprecated':
+      return (
+        <div className="mt-4 p-3 bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 rounded-lg">
+          <h4 className="text-sm font-semibold text-yellow-800 dark:text-yellow-200 mb-1">Deprecated</h4>
+          <p className="text-sm text-yellow-700 dark:text-yellow-300">{section.value as string}</p>
+        </div>
+      )
+
+    case 'admonition':
+      return (
+        <div className="mt-4 p-3 bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg">
+          {section.title && (
+            <h4 className="text-sm font-semibold text-blue-800 dark:text-blue-200 mb-1">{section.title}</h4>
+          )}
+          <p className="text-sm text-blue-700 dark:text-blue-300">{section.value as string}</p>
+        </div>
+      )
+
+    default:
+      if (section.title) {
+        return (
+          <div className="mt-4">
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">{section.title}</h4>
+            <div className="text-sm text-gray-600 dark:text-gray-300">
+              {typeof section.value === 'string' ? section.value : JSON.stringify(section.value)}
+            </div>
+          </div>
+        )
+      }
+      return null
+  }
+}
+
+interface DocstringProps {
+  docstring: GriffeDocstring | undefined
+  /** Show raw text instead of parsed sections */
+  raw?: boolean
+  /** Only show the text/description part, skip parameters/returns/etc */
+  showOnlyText?: boolean
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Renders a parsed docstring with sections for parameters, returns, raises, etc.
+ */
+export function Docstring({ docstring, raw = false, showOnlyText = false, className = '' }: DocstringProps) {
+  if (!docstring) return null
+
+  // If raw mode or no parsed sections, show raw value
+  if (raw || !docstring.parsed || docstring.parsed.length === 0) {
+    return (
+      <div className={`prose prose-sm dark:prose-invert max-w-none ${className}`}>
+        <p className="whitespace-pre-wrap text-gray-600 dark:text-gray-300">{docstring.value}</p>
+      </div>
+    )
+  }
+
+  // If showOnlyText, only render the first text section (the description)
+  if (showOnlyText) {
+    const firstTextSection = docstring.parsed.find(s => s.kind === 'text')
+    if (!firstTextSection) return null
+
+    return (
+      <div className={`prose prose-sm dark:prose-invert max-w-none ${className}`}>
+        <Markdown content={firstTextSection.value as string} />
+      </div>
+    )
+  }
+
+  return (
+    <div className={className}>
+      {docstring.parsed.map((section, i) => (
+        <DocstringSection key={`${section.kind}-${i}`} section={section} />
+      ))}
+    </div>
+  )
+}