@doccov/fumadocs-adapter 0.0.1

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@doccov/fumadocs-adapter",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./components": "./src/components/index.ts",
+    "./css": "./src/styles/docskit.css"
+  },
+  "scripts": {
+    "build": "bunup",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@openpkg-ts/spec": "../spec"
+  },
+  "peerDependencies": {
+    "@doccov/ui": "../ui",
+    "codehike": "^1.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "bunup": "^0.11.5",
+    "codehike": "^1.0.7",
+    "typescript": "^5.0.0"
+  }
+}
+

package/src/components/api-page.tsx

@@ -0,0 +1,90 @@
+'use client';
+
+import type { OpenPkg, SpecExport } from '@openpkg-ts/spec';
+import type { OpenPkgInstance } from '../server';
+import { FunctionPage } from './function-page';
+import { ClassPage } from './class-page';
+import { InterfacePage } from './interface-page';
+import { EnumPage } from './enum-page';
+import { VariablePage } from './variable-page';
+
+export interface APIPageProps {
+  /** Direct spec object */
+  spec?: OpenPkg;
+  /** Or server instance from createOpenPkg() */
+  instance?: OpenPkgInstance;
+  /** Export ID to render */
+  id: string;
+}
+
+function NotFound({ id }: { id: string }) {
+  return (
+    <div className="rounded-lg border border-fd-border bg-fd-card p-6 text-center">
+      <p className="text-fd-muted-foreground">
+        Export <code className="font-mono text-fd-primary">{id}</code> not found in spec.
+      </p>
+    </div>
+  );
+}
+
+/**
+ * Main API page component that renders documentation for a single export.
+ *
+ * @example
+ * ```tsx
+ * import { APIPage } from '@doccov/fumadocs-adapter';
+ * import spec from './openpkg.json';
+ *
+ * <APIPage spec={spec} id="createClient" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With server instance
+ * import { APIPage } from '@doccov/fumadocs-adapter';
+ * import { openpkg } from '@/lib/openpkg';
+ *
+ * <APIPage instance={openpkg} id="createClient" />
+ * ```
+ */
+export function APIPage({ spec, instance, id }: APIPageProps) {
+  const resolvedSpec = spec ?? instance?.spec;
+
+  if (!resolvedSpec) {
+    return (
+      <div className="rounded-lg border border-red-500/20 bg-red-500/10 p-6 text-center">
+        <p className="text-red-600 dark:text-red-400">
+          No spec provided. Pass either <code>spec</code> or <code>instance</code> prop.
+        </p>
+      </div>
+    );
+  }
+
+  const exp = resolvedSpec.exports.find((e) => e.id === id);
+
+  if (!exp) {
+    return <NotFound id={id} />;
+  }
+
+  const pageProps = { export: exp, spec: resolvedSpec };
+
+  switch (exp.kind) {
+    case 'function':
+      return <FunctionPage {...pageProps} />;
+    case 'class':
+      return <ClassPage {...pageProps} />;
+    case 'interface':
+    case 'type':
+      return <InterfacePage {...pageProps} />;
+    case 'enum':
+      return <EnumPage {...pageProps} />;
+    case 'variable':
+    case 'namespace':
+    case 'module':
+    case 'reference':
+    case 'external':
+    default:
+      return <VariablePage {...pageProps} />;
+  }
+}
+

package/src/components/class-page.tsx

@@ -0,0 +1,165 @@
+'use client';
+
+import type { OpenPkg, SpecExport, SpecMember } from '@openpkg-ts/spec';
+import { CodeExample } from './code-example';
+import { CoverageBadge } from './coverage-badge';
+import { ExpandableProperty } from './expandable-property';
+import { CollapsibleMethod } from './collapsible-method';
+
+export interface ClassPageProps {
+  export: SpecExport;
+  spec: OpenPkg;
+}
+
+function formatSchema(schema: unknown): string {
+  if (!schema) return 'unknown';
+  if (typeof schema === 'string') return schema;
+  if (typeof schema === 'object' && schema !== null) {
+    const s = schema as Record<string, unknown>;
+    if (s.$ref && typeof s.$ref === 'string') {
+      return s.$ref.replace('#/types/', '');
+    }
+    if (s.tsType) return String(s.tsType);
+    if (s.type) return String(s.type);
+  }
+  return 'unknown';
+}
+
+/**
+ * Compact property display for class properties (not method params)
+ */
+function PropertyItem({ member }: { member: SpecMember }) {
+  const visibility = member.visibility ?? 'public';
+  const flags = member.flags as Record<string, boolean> | undefined;
+  const isStatic = flags?.static;
+  const isReadonly = flags?.readonly;
+  const type = formatSchema(member.schema);
+
+  return (
+    <div className="py-3 border-b border-fd-border last:border-0">
+      <div className="flex items-baseline gap-2 flex-wrap">
+        <span className="font-semibold text-fd-foreground">{member.name}:</span>
+        <span className="text-fd-muted-foreground font-mono text-sm">{type}</span>
+        {visibility !== 'public' && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-fd-muted text-fd-muted-foreground">
+            {visibility}
+          </span>
+        )}
+        {isStatic && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-blue-500/10 text-blue-600 dark:text-blue-400">
+            static
+          </span>
+        )}
+        {isReadonly && (
+          <span className="text-xs px-1.5 py-0.5 rounded bg-purple-500/10 text-purple-600 dark:text-purple-400">
+            readonly
+          </span>
+        )}
+      </div>
+      {member.description && (
+        <p className="text-sm text-fd-muted-foreground mt-1">{member.description}</p>
+      )}
+    </div>
+  );
+}
+
+export function ClassPage({ export: exp, spec }: ClassPageProps) {
+  const hasExamples = exp.examples && exp.examples.length > 0;
+
+  // Group members
+  const constructors = exp.members?.filter((m) => m.kind === 'constructor') ?? [];
+  const properties = exp.members?.filter((m) => m.kind === 'property' || m.kind === 'field') ?? [];
+  const methods = exp.members?.filter((m) => m.kind === 'method') ?? [];
+
+  // Get constructor parameters
+  const constructorSig = constructors[0]?.signatures?.[0];
+  const constructorParams = constructorSig?.parameters ?? [];
+
+  return (
+    <div className="space-y-8">
+      {/* Description */}
+      {exp.description && (
+        <p className="text-fd-muted-foreground text-lg leading-relaxed">
+          {exp.description}
+        </p>
+      )}
+
+      {/* Declaration */}
+      <div className="rounded-lg border border-fd-border bg-fd-muted/30 p-4 overflow-x-auto">
+        <code className="font-mono text-sm text-fd-foreground whitespace-pre">
+          class {exp.name}
+          {exp.extends ? ` extends ${exp.extends}` : ''}
+          {exp.implements?.length ? ` implements ${exp.implements.join(', ')}` : ''}
+        </code>
+      </div>
+
+      {/* Two-column layout for content + example */}
+      <div className={`grid gap-8 ${hasExamples ? 'lg:grid-cols-2' : 'grid-cols-1'}`}>
+        {/* Left column: Constructor, Methods, Properties */}
+        <div className="space-y-8">
+          {/* Constructor */}
+          {constructorParams.length > 0 && (
+            <section>
+              <h3 className="text-sm font-semibold uppercase tracking-wide text-fd-muted-foreground mb-4">
+                Constructor
+              </h3>
+              <div className="ml-2 border-l-2 border-fd-border pl-4">
+                {constructorParams.map((param, index) => (
+                  <ExpandableProperty key={param.name ?? index} param={param} />
+                ))}
+              </div>
+            </section>
+          )}
+
+          {/* Methods - collapsible sections */}
+          {methods.length > 0 && (
+            <section>
+              <h3 className="text-sm font-semibold uppercase tracking-wide text-fd-muted-foreground mb-4">
+                Methods
+              </h3>
+              <div className="rounded-lg border border-fd-border overflow-hidden">
+                {methods.map((member, index) => (
+                  <CollapsibleMethod
+                    key={member.name ?? index}
+                    member={member}
+                    defaultExpanded={index === 0}
+                  />
+                ))}
+              </div>
+            </section>
+          )}
+
+          {/* Properties - compact list */}
+          {properties.length > 0 && (
+            <section>
+              <h3 className="text-sm font-semibold uppercase tracking-wide text-fd-muted-foreground mb-4">
+                Properties
+              </h3>
+              <div className="rounded-lg border border-fd-border bg-fd-card px-4">
+                {properties.map((member, index) => (
+                  <PropertyItem key={member.name ?? index} member={member} />
+                ))}
+              </div>
+            </section>
+          )}
+        </div>
+
+        {/* Right column: Examples */}
+        {hasExamples && (
+          <div className="lg:sticky lg:top-20 lg:self-start">
+            <h3 className="text-sm font-semibold uppercase tracking-wide text-fd-muted-foreground mb-4">
+              Example
+            </h3>
+            <CodeExample
+              code={exp.examples![0]}
+              filename={`${exp.name.toLowerCase()}.ts`}
+            />
+          </div>
+        )}
+      </div>
+
+      {/* Coverage */}
+      {exp.docs && <CoverageBadge docs={exp.docs} />}
+    </div>
+  );
+}

package/src/components/code-example.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import { ClientDocsKitCode } from '@doccov/ui/docskit';
+import type { RawCode } from 'codehike/code';
+
+export interface CodeExampleProps {
+  code: string;
+  filename?: string;
+  language?: string;
+}
+
+/**
+ * Cleans up code by removing markdown code fence markers if present.
+ */
+function cleanCode(code: string): string {
+  let cleaned = code.trim();
+  if (cleaned.startsWith('```')) {
+    const lines = cleaned.split('\n');
+    lines.shift(); // Remove opening ```ts or ```typescript
+    if (lines[lines.length - 1] === '```') {
+      lines.pop(); // Remove closing ```
+    }
+    cleaned = lines.join('\n');
+  }
+  return cleaned;
+}
+
+export function CodeExample({ code, filename = 'example.ts', language = 'typescript' }: CodeExampleProps) {
+  const cleaned = cleanCode(code);
+  
+  // Build RawCode object for ClientDocsKitCode
+  // The meta field uses flags: 'c' for copyButton, 'n' for lineNumbers
+  const codeblock: RawCode = {
+    value: cleaned,
+    lang: language,
+    meta: `${filename} -cn`, // title + copyButton + lineNumbers flags (must prefix with -)
+  };
+
+  return <ClientDocsKitCode codeblock={codeblock} className="not-fumadocs-codeblock" />;
+}

package/src/components/collapsible-method.tsx

@@ -0,0 +1,185 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import type { SpecMember, SpecSchema } from '@openpkg-ts/spec';
+import { ExpandableProperty } from './expandable-property';
+
+export interface CollapsibleMethodProps {
+  member: SpecMember;
+  defaultExpanded?: boolean;
+}
+
+// Chevron icon component
+function ChevronIcon({ expanded }: { expanded: boolean }) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      className={`transition-transform duration-200 ${expanded ? 'rotate-90' : ''}`}
+    >
+      <path
+        d="M6 4L10 8L6 12"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+function formatSchema(schema: unknown): string {
+  if (!schema) return 'unknown';
+  if (typeof schema === 'string') return schema;
+  if (typeof schema === 'object' && schema !== null) {
+    const s = schema as Record<string, unknown>;
+    if (s.$ref && typeof s.$ref === 'string') {
+      return s.$ref.replace('#/types/', '');
+    }
+    if (s.tsType) {
+      const tsType = String(s.tsType);
+      if (tsType.length > 40) return tsType.slice(0, 37) + '...';
+      return tsType;
+    }
+    if (s.type) return String(s.type);
+  }
+  return 'unknown';
+}
+
+function formatReturnType(returns: { schema?: SpecSchema; tsType?: string } | undefined): string {
+  if (!returns) return 'void';
+  if (returns.tsType) {
+    const t = returns.tsType;
+    if (t.length > 40) return t.slice(0, 37) + '...';
+    return t;
+  }
+  return formatSchema(returns.schema);
+}
+
+function formatParamPreview(params: { name?: string }[] | undefined): string {
+  if (!params || params.length === 0) return '';
+  if (params.length === 1) return params[0].name || 'arg';
+  return `${params[0].name || 'arg'}, ...`;
+}
+
+/**
+ * Collapsible method section with expand/collapse behavior
+ * Shows compact signature when collapsed, full details when expanded
+ */
+export function CollapsibleMethod({ member, defaultExpanded = false }: CollapsibleMethodProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+
+  const sig = member.signatures?.[0];
+  const hasParams = sig?.parameters && sig.parameters.length > 0;
+  const visibility = member.visibility ?? 'public';
+  const flags = member.flags as Record<string, boolean> | undefined;
+  const isStatic = flags?.static;
+  const isAsync = flags?.async;
+
+  const returnType = formatReturnType(sig?.returns);
+  const returnDescription = sig?.returns?.description;
+  const paramPreview = formatParamPreview(sig?.parameters);
+
+  // Auto-expand if URL hash matches this method
+  useEffect(() => {
+    if (typeof window !== 'undefined' && window.location.hash === `#${member.name}`) {
+      setExpanded(true);
+    }
+  }, [member.name]);
+
+  return (
+    <div
+      id={member.name}
+      className="scroll-mt-20 border-b border-fd-border last:border-0"
+    >
+      {/* Clickable header */}
+      <button
+        onClick={() => setExpanded(!expanded)}
+        className="w-full flex items-center gap-3 py-4 px-1 text-left hover:bg-fd-muted/30 transition-colors cursor-pointer group"
+      >
+        {/* Chevron */}
+        <span className="text-fd-muted-foreground group-hover:text-fd-foreground transition-colors">
+          <ChevronIcon expanded={expanded} />
+        </span>
+
+        {/* Method signature preview */}
+        <div className="flex-1 min-w-0 flex items-baseline gap-2 flex-wrap">
+          <span className="font-mono text-sm font-semibold text-fd-foreground">
+            {member.name}
+            <span className="text-fd-muted-foreground font-normal">({paramPreview})</span>
+          </span>
+          <span className="text-fd-muted-foreground">→</span>
+          <span className="font-mono text-sm text-fd-muted-foreground truncate">
+            {returnType}
+          </span>
+        </div>
+
+        {/* Badges */}
+        <div className="flex gap-1.5 shrink-0">
+          {visibility !== 'public' && (
+            <span className="text-xs px-1.5 py-0.5 rounded bg-fd-muted text-fd-muted-foreground">
+              {visibility}
+            </span>
+          )}
+          {isStatic && (
+            <span className="text-xs px-1.5 py-0.5 rounded bg-blue-500/10 text-blue-600 dark:text-blue-400">
+              static
+            </span>
+          )}
+          {isAsync && (
+            <span className="text-xs px-1.5 py-0.5 rounded bg-purple-500/10 text-purple-600 dark:text-purple-400">
+              async
+            </span>
+          )}
+        </div>
+      </button>
+
+      {/* Expanded content */}
+      {expanded && (
+        <div className="pb-6 pl-8 pr-4">
+          {/* Description */}
+          {member.description && (
+            <p className="text-fd-muted-foreground mb-4 leading-relaxed">
+              {member.description}
+            </p>
+          )}
+
+          {/* Parameters */}
+          {hasParams && (
+            <div className="mb-4">
+              <span className="text-xs uppercase tracking-wide text-fd-muted-foreground font-medium block mb-2">
+                Parameters
+              </span>
+              <div className="border-l-2 border-fd-border pl-4">
+                {sig.parameters!.map((param, index) => (
+                  <ExpandableProperty key={param.name ?? index} param={param} />
+                ))}
+              </div>
+            </div>
+          )}
+
+          {/* Returns */}
+          {sig?.returns && returnType !== 'void' && (
+            <div>
+              <span className="text-xs uppercase tracking-wide text-fd-muted-foreground font-medium block mb-2">
+                Returns
+              </span>
+              <div className="border-l-2 border-fd-border pl-4 py-2">
+                <span className="font-mono text-sm text-fd-muted-foreground">
+                  {sig.returns.tsType || formatSchema(sig.returns.schema)}
+                </span>
+                {returnDescription && (
+                  <p className="text-sm text-fd-muted-foreground mt-1 leading-relaxed">
+                    {returnDescription}
+                  </p>
+                )}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/coverage-badge.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import type { SpecDocsMetadata } from '@openpkg-ts/spec';
+
+export interface CoverageBadgeProps {
+  docs: SpecDocsMetadata;
+  showMissing?: boolean;
+  showDrift?: boolean;
+}
+
+function getScoreColor(score: number): string {
+  if (score >= 80) return 'text-green-600 dark:text-green-400 bg-green-500/10 border-green-500/20';
+  if (score >= 60) return 'text-yellow-600 dark:text-yellow-400 bg-yellow-500/10 border-yellow-500/20';
+  return 'text-red-600 dark:text-red-400 bg-red-500/10 border-red-500/20';
+}
+
+function formatSignal(signal: string): string {
+  return signal.charAt(0).toUpperCase() + signal.slice(1);
+}
+
+export function CoverageBadge({ docs, showMissing = true, showDrift = true }: CoverageBadgeProps) {
+  const score = docs.coverageScore;
+  const hasMissing = showMissing && docs.missing && docs.missing.length > 0;
+  const hasDrift = showDrift && docs.drift && docs.drift.length > 0;
+
+  if (score == null && !hasMissing && !hasDrift) return null;
+
+  return (
+    <div className="my-6 space-y-3">
+      {score != null && (
+        <div
+          className={`inline-flex items-center gap-2 px-3 py-1.5 rounded-md border text-sm font-medium ${getScoreColor(score)}`}
+        >
+          <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"
+            />
+          </svg>
+          Coverage: {score}%
+        </div>
+      )}
+
+      {hasMissing && (
+        <div className="rounded-md bg-yellow-500/10 border border-yellow-500/20 px-3 py-2">
+          <p className="text-sm font-medium text-yellow-600 dark:text-yellow-400 mb-1">
+            Missing Documentation
+          </p>
+          <ul className="text-sm text-yellow-600/80 dark:text-yellow-400/80 list-disc list-inside">
+            {docs.missing!.map((signal) => (
+              <li key={signal}>{formatSignal(signal)}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {hasDrift && (
+        <div className="rounded-md bg-red-500/10 border border-red-500/20 px-3 py-2">
+          <p className="text-sm font-medium text-red-600 dark:text-red-400 mb-1">Documentation Drift</p>
+          <ul className="text-sm text-red-600/80 dark:text-red-400/80 space-y-1">
+            {docs.drift!.map((drift, index) => (
+              <li key={index} className="flex flex-col">
+                <span className="font-medium">{drift.type}</span>
+                <span className="text-xs opacity-80">{drift.issue}</span>
+                {drift.suggestion && (
+                  <span className="text-xs text-fd-muted-foreground mt-0.5">
+                    Suggestion: {drift.suggestion}
+                  </span>
+                )}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+}
+

package/src/components/enum-page.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import type { OpenPkg, SpecExport } from '@openpkg-ts/spec';
+import { Signature } from './signature';
+import { ExamplesSection } from './examples';
+import { CoverageBadge } from './coverage-badge';
+
+export interface EnumPageProps {
+  export: SpecExport;
+  spec: OpenPkg;
+}
+
+export function EnumPage({ export: exp, spec }: EnumPageProps) {
+  const members = exp.members ?? [];
+
+  return (
+    <div className="space-y-6">
+      {/* Description */}
+      {exp.description && (
+        <p className="text-fd-muted-foreground text-base leading-relaxed">{exp.description}</p>
+      )}
+
+      {/* Signature */}
+      <section>
+        <h2 className="text-xl font-semibold mb-2">Declaration</h2>
+        <Signature export={exp} />
+      </section>
+
+      {/* Enum Members */}
+      {members.length > 0 && (
+        <section>
+          <h2 className="text-xl font-semibold mb-2">Members</h2>
+          <div className="overflow-x-auto">
+            <table className="w-full text-sm border-collapse">
+              <thead>
+                <tr className="border-b border-fd-border">
+                  <th className="text-left py-2 px-3 font-medium text-fd-muted-foreground">Name</th>
+                  <th className="text-left py-2 px-3 font-medium text-fd-muted-foreground">Value</th>
+                  <th className="text-left py-2 px-3 font-medium text-fd-muted-foreground">
+                    Description
+                  </th>
+                </tr>
+              </thead>
+              <tbody>
+                {members.map((member, index) => {
+                  // For enum members, the value might be in schema or flags
+                  const value =
+                    member.schema !== undefined
+                      ? typeof member.schema === 'object' && member.schema !== null
+                        ? (member.schema as any).const ?? (member.schema as any).default ?? '-'
+                        : member.schema
+                      : '-';
+
+                  return (
+                    <tr key={member.name ?? index} className="border-b border-fd-border last:border-0">
+                      <td className="py-2 px-3 align-top">
+                        <code className="text-fd-primary font-mono text-xs bg-fd-secondary px-1.5 py-0.5 rounded">
+                          {member.name}
+                        </code>
+                      </td>
+                      <td className="py-2 px-3 align-top">
+                        <code className="font-mono text-xs text-fd-muted-foreground">
+                          {String(value)}
+                        </code>
+                      </td>
+                      <td className="py-2 px-3 align-top text-fd-muted-foreground">
+                        {member.description ?? ''}
+                      </td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+        </section>
+      )}
+
+      {/* Examples */}
+      {exp.examples && exp.examples.length > 0 && <ExamplesSection examples={exp.examples} />}
+
+      {/* Coverage */}
+      {exp.docs && <CoverageBadge docs={exp.docs} />}
+    </div>
+  );
+}
+