@openpkg-ts/fumadocs-adapter 0.5.2 → 0.6.0

package/README.md

@@ -43,13 +43,91 @@ Styled components use a two-column layout at the `lg:` breakpoint (1024px). For
 - Consider using `full` layout for API pages or hiding the TOC to maximize content width
 - On narrower viewports, the layout automatically stacks vertically
 
-## Usage with doc-generator
+## Navigation Modes
+
+Two navigation patterns are supported:
+
+### Mode A: Single Page (Stripe-style)
+
+All exports on one scrollable page with filters and optional TOC:
+
+```tsx
+// app/docs/(api)/api/page.tsx
+import { FullAPIReferencePage, type OpenPkg } from '@openpkg-ts/fumadocs-adapter';
+import spec from '@/lib/openpkg.json';
+
+export default function APIPage() {
+  return (
+    <FullAPIReferencePage
+      spec={spec as OpenPkg}
+      title="API Reference"
+      showTOC           // sticky sidebar navigation
+      showFilters       // kind filter buttons (functions, types, etc.)
+    />
+  );
+}
+```
+
+Props:
+- `showTOC` - Enable sticky sidebar with anchor links
+- `showFilters` - Show kind filter buttons (functions, classes, etc.)
+- `kinds` - Limit to specific export kinds: `['function', 'type']`
+
+### Mode B: Index + Individual Pages
+
+Grid of cards linking to individual pages:
+
+```tsx
+// app/docs/(api)/api/page.tsx (index)
+import { ExportIndexPage, type OpenPkg } from '@openpkg-ts/fumadocs-adapter';
+import spec from '@/lib/openpkg.json';
+
+export default function APIIndexPage() {
+  return (
+    <ExportIndexPage
+      spec={spec as OpenPkg}
+      baseHref="/docs/api"
+      showSearch        // search input
+      showFilters       // category filter buttons
+    />
+  );
+}
+
+// app/docs/(api)/api/[kind]/[slug]/page.tsx (detail)
+import { FunctionPage, type OpenPkg, type SpecExport } from '@openpkg-ts/fumadocs-adapter';
+import spec from '@/lib/openpkg.json';
+
+export default function ExportDetailPage({ params }) {
+  const exp = (spec as OpenPkg).exports.find(e => e.id === params.slug);
+  return <FunctionPage export={exp as SpecExport} spec={spec as OpenPkg} />;
+}
+```
+
+## Using openpkgSource for Fumadocs Integration
+
+Generate a page tree for Fumadocs sidebar:
+
+```tsx
+// lib/api-source.ts
+import { loader } from 'fumadocs-core/source';
+import { openpkgSource, type OpenPkg } from '@openpkg-ts/fumadocs-adapter';
+import spec from './openpkg.json';
+
+export const apiSource = loader({
+  baseUrl: '/docs/api',
+  source: openpkgSource({ spec: spec as OpenPkg, baseDir: '' }),
+});
+```
+
+Then use in your layout:
 
 ```tsx
-import { FunctionPage } from '@openpkg-ts/doc-generator/react/styled'
+// app/docs/(api)/layout.tsx
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { apiSource } from '@/lib/api-source';
 
-export default function APIDocsPage({ fn }) {
-  return <FunctionPage export={fn} />
+export default function APILayout({ children }) {
+  return <DocsLayout tree={apiSource.pageTree}>{children}</DocsLayout>;
 }
 ```
 

package/dist/index.d.ts

@@ -5,6 +5,14 @@ interface OpenPkgSourceOptions {
 	spec: OpenPkg | DocsInstance;
 	/** Base directory for pages (default: 'api') */
 	baseDir?: string;
+	/** Generate index page at baseDir/index.mdx (default: true) */
+	indexPage?: boolean;
+	/**
+	* Navigation mode:
+	* - 'pages': Individual pages per grouped by kind (default)
+	* - 'single': Single page with all exports and in-page navigation
+	*/
+	mode?: "pages" | "single";
 }
 interface OpenPkgPageData {
 	title: string;
@@ -14,6 +22,23 @@ interface OpenPkgPageData {
 	/** The full OpenPkg spec */
 	spec: OpenPkg;
 }
+interface OpenPkgIndexPageData {
+	title: string;
+	description?: string;
+	/** Index page marker */
+	isIndex: true;
+	/** The full OpenPkg spec */
+	spec: OpenPkg;
+}
+/** Page data for single-page mode */
+interface OpenPkgSinglePageData {
+	title: string;
+	description?: string;
+	/** Single page mode marker */
+	isSinglePage: true;
+	/** The full OpenPkg spec */
+	spec: OpenPkg;
+}
 interface OpenPkgMetaData {
 	title: string;
 	pages: string[];
@@ -27,7 +52,7 @@ interface OpenPkgMetaData {
 *
 * @example
 * ```ts
-* import { loader } from 'fumadocs-core/source';
+* // Multi-page mode (default) - individual pages per * import { loader } from 'fumadocs-core/source';
 * import { openpkgSource } from '@openpkg-ts/fumadocs-adapter';
 * import spec from './openpkg.json';
 *
@@ -36,9 +61,18 @@ interface OpenPkgMetaData {
 *   source: openpkgSource({ spec }),
 * });
 * ```
+*
+* @example
+* ```ts
+* // Single-page mode - all exports on one scrollable page
+* const source = loader({
+*   baseUrl: '/docs/api',
+*   source: openpkgSource({ spec, mode: 'single' }),
+* });
+* ```
 */
 declare function openpkgSource(options: OpenPkgSourceOptions): Source<{
-	pageData: OpenPkgPageData
+	pageData: OpenPkgPageData | OpenPkgIndexPageData | OpenPkgSinglePageData
 	metaData: OpenPkgMetaData
 }>;
 import { LoaderPlugin } from "fumadocs-core/source";
@@ -100,4 +134,4 @@ interface CoverageBadgeProps {
 	showDrift?: boolean;
 }
 declare function CoverageBadge({ docs, showMissing, showDrift }: CoverageBadgeProps): React.ReactNode;
-export { toSearchIndexJSON, toSearchIndex, toPagefindRecords, toNavigation, toMarkdown, toJSONString, toJSON, toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords, sortByName, resolveTypeRef, openpkgSource, openpkgPlugin, loadSpec, isProperty, isMethod, groupByVisibility, getProperties, getMethods, formatTypeParameters, formatSchema, formatReturnType, formatParameters, exportToMarkdown, createDocs2 as createOpenPkg, createDocs, buildSignatureString, VariableSectionProps, VariableSection, VariablePageProps, VariablePage, SpecTypeParameter, SpecTypeKind, SpecType, SpecTag, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExportKind2 as SpecExportKind, SpecExport2 as SpecExport, SpecExample, SearchRecord, SearchOptions, SearchIndex, ParameterItemProps, ParameterItem, PagefindRecord, OpenpkgPluginOptions, OpenPkgSourceOptions, OpenPkgPageData, LoadOptions as OpenPkgOptions, OpenPkgMetaData, DocsInstance2 as OpenPkgInstance, OpenPkg2 as OpenPkg, NestedPropertyItemProps, NavOptions, MarkdownOptions, LoadOptions2 as LoadOptions, KindBadgeProps, KindBadge, JSONOptions, InterfaceSectionProps, InterfaceSection, InterfacePageProps, InterfacePage, ImportSectionProps, ImportSection, HTMLOptions, FunctionSectionProps, FunctionSection, FunctionPageProps, FunctionPage, FullAPIReferencePageProps, FullAPIReferencePage, ExportSectionProps, ExportSection, ExportMarkdownOptions, ExportIndexPageProps, ExportIndexPage, ExportCardProps, ExportCard, EnumSectionProps, EnumSection, EnumPageProps, EnumPage, DocsMetadata, DocsInstance3 as DocsInstance, DocDrift, CoverageBadgeProps, CoverageBadge, CodeTabsProps, CodeTabs, CodeTab, ClassSectionProps, ClassSection, ClassPageProps, ClassPage, AlgoliaRecord, APIPageProps, APIPage };
+export { toSearchIndexJSON, toSearchIndex, toPagefindRecords, toNavigation, toMarkdown, toJSONString, toJSON, toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords, sortByName, resolveTypeRef, openpkgSource, openpkgPlugin, loadSpec, isProperty, isMethod, groupByVisibility, getProperties, getMethods, formatTypeParameters, formatSchema, formatReturnType, formatParameters, exportToMarkdown, createDocs2 as createOpenPkg, createDocs, buildSignatureString, VariableSectionProps, VariableSection, VariablePageProps, VariablePage, SpecTypeParameter, SpecTypeKind, SpecType, SpecTag, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExportKind2 as SpecExportKind, SpecExport2 as SpecExport, SpecExample, SearchRecord, SearchOptions, SearchIndex, ParameterItemProps, ParameterItem, PagefindRecord, OpenpkgPluginOptions, OpenPkgSourceOptions, OpenPkgSinglePageData, OpenPkgPageData, LoadOptions as OpenPkgOptions, OpenPkgMetaData, DocsInstance2 as OpenPkgInstance, OpenPkgIndexPageData, OpenPkg2 as OpenPkg, NestedPropertyItemProps, NavOptions, MarkdownOptions, LoadOptions2 as LoadOptions, KindBadgeProps, KindBadge, JSONOptions, InterfaceSectionProps, InterfaceSection, InterfacePageProps, InterfacePage, ImportSectionProps, ImportSection, HTMLOptions, FunctionSectionProps, FunctionSection, FunctionPageProps, FunctionPage, FullAPIReferencePageProps, FullAPIReferencePage, ExportSectionProps, ExportSection, ExportMarkdownOptions, ExportIndexPageProps, ExportIndexPage, ExportCardProps, ExportCard, EnumSectionProps, EnumSection, EnumPageProps, EnumPage, DocsMetadata, DocsInstance3 as DocsInstance, DocDrift, CoverageBadgeProps, CoverageBadge, CodeTabsProps, CodeTabs, CodeTab, ClassSectionProps, ClassSection, ClassPageProps, ClassPage, AlgoliaRecord, APIPageProps, APIPage };

package/dist/index.js

@@ -25,10 +25,34 @@ var KIND_LABELS = {
   external: "External"
 };
 function openpkgSource(options) {
-  const { baseDir = "api" } = options;
+  const { baseDir = "api", indexPage = true, mode = "pages" } = options;
   const docs = "getAllExports" in options.spec ? options.spec : createDocs(options.spec);
   const spec = docs.spec;
   const exports = docs.getAllExports();
+  const files = [];
+  if (mode === "single") {
+    files.push({
+      type: "meta",
+      path: `${baseDir}/meta.json`,
+      data: {
+        title: spec.meta.name || "API Reference",
+        pages: ["index"],
+        defaultOpen: true
+      }
+    });
+    files.push({
+      type: "page",
+      path: `${baseDir}/index.mdx`,
+      slugs: [],
+      data: {
+        title: spec.meta.name || "API Reference",
+        description: spec.meta.description,
+        isSinglePage: true,
+        spec
+      }
+    });
+    return { files };
+  }
   const groupedByKind = new Map;
   for (const exp of exports) {
     const kind = exp.kind;
@@ -37,8 +61,10 @@ function openpkgSource(options) {
     }
     groupedByKind.get(kind).push(exp);
   }
-  const files = [];
   const rootPages = [];
+  if (indexPage) {
+    rootPages.push("index");
+  }
   for (const kind of KIND_ORDER) {
     if (groupedByKind.has(kind)) {
       rootPages.push(`...${kind}s`);
@@ -53,6 +79,19 @@ function openpkgSource(options) {
       defaultOpen: true
     }
   });
+  if (indexPage) {
+    files.push({
+      type: "page",
+      path: `${baseDir}/index.mdx`,
+      slugs: [],
+      data: {
+        title: spec.meta.name || "API Reference",
+        description: spec.meta.description,
+        isIndex: true,
+        spec
+      }
+    });
+  }
   for (const kind of KIND_ORDER) {
     const kindExports = groupedByKind.get(kind);
     if (!kindExports || kindExports.length === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/fumadocs-adapter",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Fumadocs integration for OpenPkg API documentation",
   "type": "module",
   "sideEffects": false,
@@ -28,7 +28,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@openpkg-ts/doc-generator": "^0.5.1"
+    "@openpkg-ts/doc-generator": "^0.6.0"
   },
   "peerDependencies": {
     "fumadocs-core": "^16.0.0",