@openpkg-ts/fumadocs-adapter 0.6.0 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # @openpkg-ts/fumadocs-adapter
 
-Fumadocs integration for OpenPkg API documentation. Provides CSS variables and theming for `@openpkg-ts/doc-generator` styled components.
+Fumadocs integration for OpenPkg API documentation. Provides virtual source generation, styled components, and theming.
 
 ## Installation
 
@@ -33,24 +33,30 @@ Tailwind v4 excludes `node_modules` by default. Add this directive to include st
 @source "../node_modules/@openpkg-ts/doc-generator/dist/**/*.js";
 ```
 
-Without this, utility classes like `lg:grid-cols-[1fr,minmax(0,420px)]` won't be included in your production build.
-
-## Layout Requirements
-
-Styled components use a two-column layout at the `lg:` breakpoint (1024px). For best results:
-
-- Content area should be >= 1024px wide
-- Consider using `full` layout for API pages or hiding the TOC to maximize content width
-- On narrower viewports, the layout automatically stacks vertically
-
 ## Navigation Modes
 
-Two navigation patterns are supported:
+Two navigation patterns are supported via `openpkgSource`:
 
-### Mode A: Single Page (Stripe-style)
+### Single-Page Mode
 
 All exports on one scrollable page with filters and optional TOC:
 
+```ts
+// 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: 'api',
+    mode: 'single',
+  }),
+});
+```
+
 ```tsx
 // app/docs/(api)/api/page.tsx
 import { FullAPIReferencePage, type OpenPkg } from '@openpkg-ts/fumadocs-adapter';
@@ -61,76 +67,118 @@ export default function APIPage() {
     <FullAPIReferencePage
       spec={spec as OpenPkg}
       title="API Reference"
-      showTOC           // sticky sidebar navigation
-      showFilters       // kind filter buttons (functions, types, etc.)
+      showTOC        // sticky sidebar navigation
+      showFilters    // kind filter buttons
     />
   );
 }
 ```
 
-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';
+// app/docs/(api)/api/layout.tsx
+import { apiSource } from '@/lib/api-source';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
-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} />;
+export default function APILayout({ children }) {
+  return <DocsLayout tree={apiSource.pageTree}>{children}</DocsLayout>;
 }
 ```
 
-## Using openpkgSource for Fumadocs Integration
+### Multi-Page Mode
 
-Generate a page tree for Fumadocs sidebar:
+Index page with cards + individual pages per export:
 
-```tsx
+```ts
 // lib/api-source.ts
 import { loader } from 'fumadocs-core/source';
-import { openpkgSource, type OpenPkg } from '@openpkg-ts/fumadocs-adapter';
+import { openpkgSource, openpkgPlugin, 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: '' }),
+  baseUrl: '/docs/reference',
+  source: openpkgSource({
+    spec: spec as OpenPkg,
+    baseDir: 'reference',
+    mode: 'pages',      // individual pages per export
+    indexPage: true,    // generate index page with cards
+  }),
+  plugins: [openpkgPlugin()],  // adds kind badges to sidebar
 });
 ```
 
-Then use in your layout:
+```tsx
+// app/docs/(reference)/reference/[[...slug]]/page.tsx
+import { apiSource } from '@/lib/api-source';
+import { notFound } from 'next/navigation';
+import {
+  APIPage,
+  ExportIndexPage,
+  type OpenPkgIndexPageData,
+  type OpenPkgPageData,
+} from '@openpkg-ts/fumadocs-adapter';
+
+export default async function ReferencePage({ params }) {
+  const { slug } = await params;
+  const page = apiSource.getPage(slug);
+  if (!page) notFound();
+
+  const data = page.data;
+
+  // Index page
+  if ('isIndex' in data && data.isIndex) {
+    return (
+      <ExportIndexPage
+        spec={data.spec}
+        baseHref="/docs/reference"
+      />
+    );
+  }
+
+  // Individual export page
+  return (
+    <APIPage
+      spec={data.spec}
+      id={data.export.id}
+      baseHref="/docs/reference"
+    />
+  );
+}
+
+export function generateStaticParams() {
+  return apiSource.generateParams();
+}
+```
 
 ```tsx
-// app/docs/(api)/layout.tsx
-import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+// app/docs/(reference)/reference/layout.tsx
 import { apiSource } from '@/lib/api-source';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
-export default function APILayout({ children }) {
+export default function ReferenceLayout({ children }) {
   return <DocsLayout tree={apiSource.pageTree}>{children}</DocsLayout>;
 }
 ```
 
+## openpkgSource Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `spec` | `OpenPkg` | required | The OpenPkg spec object |
+| `baseDir` | `string` | `'api'` | Base directory for generated pages |
+| `mode` | `'pages' \| 'single'` | `'pages'` | Navigation mode |
+| `indexPage` | `boolean` | `true` | Generate index page (pages mode only) |
+
+## FullAPIReferencePage Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `spec` | `OpenPkg` | required | The OpenPkg spec |
+| `title` | `string` | spec.meta.name | Page title |
+| `description` | `ReactNode` | - | Description below title |
+| `showTOC` | `boolean` | `false` | Show sticky sidebar TOC |
+| `showFilters` | `boolean` | `true` | Show kind filter buttons |
+| `kinds` | `SpecExportKind[]` | all | Filter to specific kinds |
+
 ## CSS Variables Reference
 
 ### DocsKit Variables (`--dk-*`)
@@ -144,10 +192,6 @@ export default function APILayout({ children }) {
 | `--dk-tab-active-foreground` | Active tab text |
 | `--dk-selection` | Text selection color |
 
-### CodeHike Variables (`--ch-*`)
-
-GitHub syntax theme colors (`--ch-0` through `--ch-26`). Automatically adapts to light/dark mode.
-
 ### API Reference Variables (`--api-*`)
 
 | Variable | Purpose |

package/dist/index.js

@@ -24,6 +24,21 @@ var KIND_LABELS = {
   reference: "References",
   external: "External"
 };
+var KIND_SLUGS = {
+  function: "functions",
+  class: "classes",
+  interface: "interfaces",
+  type: "types",
+  enum: "enums",
+  variable: "variables",
+  namespace: "namespaces",
+  module: "modules",
+  reference: "references",
+  external: "externals"
+};
+function pluralizeKind(kind) {
+  return KIND_SLUGS[kind] || `${kind}s`;
+}
 function openpkgSource(options) {
   const { baseDir = "api", indexPage = true, mode = "pages" } = options;
   const docs = "getAllExports" in options.spec ? options.spec : createDocs(options.spec);
@@ -67,7 +82,7 @@ function openpkgSource(options) {
   }
   for (const kind of KIND_ORDER) {
     if (groupedByKind.has(kind)) {
-      rootPages.push(`...${kind}s`);
+      rootPages.push(`...${pluralizeKind(kind)}`);
     }
   }
   files.push({
@@ -96,8 +111,9 @@ function openpkgSource(options) {
     const kindExports = groupedByKind.get(kind);
     if (!kindExports || kindExports.length === 0)
       continue;
-    const kindDir = `${baseDir}/${kind}s`;
-    const label = KIND_LABELS[kind] || `${kind}s`;
+    const kindSlug = pluralizeKind(kind);
+    const kindDir = `${baseDir}/${kindSlug}`;
+    const label = KIND_LABELS[kind] || kindSlug;
     const sortedExports = [...kindExports].sort((a, b) => a.name.localeCompare(b.name));
     files.push({
       type: "meta",
@@ -112,7 +128,7 @@ function openpkgSource(options) {
       files.push({
         type: "page",
         path: `${kindDir}/${exp.id}.mdx`,
-        slugs: [kind + "s", exp.id],
+        slugs: [kindSlug, exp.id],
         data: {
           title: exp.name,
           description: exp.description,

package/package.json

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