@vendure-io/docs-provider 0.1.0 → 0.2.0

package/README.md

@@ -8,6 +8,7 @@ Contract types and utilities for Vendure documentation packages. This package de
 - [Creating a Docs Package](./docs/creating-a-docs-package.md) - Step-by-step guide to building a documentation package
 - [Manifest Reference](./docs/manifest-reference.md) - Complete API documentation for manifest types and utilities
 - [Frontmatter Reference](./docs/frontmatter-reference.md) - All available MDX frontmatter options
+- [MDX Components Reference](./docs/mdx-components-reference.md) - Available MDX components for reference documentation
 - [Publishing](./docs/publishing.md) - How to publish and integrate with vendure.io
 
 ## Installation
@@ -22,10 +23,18 @@ bun add @vendure-io/docs-provider
 
 ### Defining a Documentation Package Manifest
 
-Documentation packages export a manifest that describes their structure:
+Documentation packages export a manifest that describes their structure. **Important**: File paths must be absolute paths. Use a helper pattern to resolve paths relative to your package root:
 
 ```typescript
 import type { DocsPackageManifest } from '@vendure-io/docs-provider'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+// Resolve the package root directory at module load time
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+
+// Helper to resolve file paths to absolute paths
+const file = (relativePath: string) => join(packageRoot, relativePath)
 
 export const manifest: DocsPackageManifest = {
   id: 'core',
@@ -40,12 +49,12 @@ export const manifest: DocsPackageManifest = {
         {
           title: 'Installation',
           slug: 'installation',
-          file: 'docs/getting-started/installation.mdx',
+          file: file('docs/getting-started/installation.mdx'),
         },
         {
           title: 'Configuration',
           slug: 'configuration',
-          file: 'docs/getting-started/configuration.mdx',
+          file: file('docs/getting-started/configuration.mdx'),
         },
       ],
     },
@@ -54,22 +63,24 @@ export const manifest: DocsPackageManifest = {
     indexFields: ['title', 'description', 'content', 'keywords'],
     boosts: { title: 2, keywords: 1.5 },
   },
+  github: {
+    repository: 'your-org/your-repo',
+    branch: 'main',
+    docsPath: 'libs/your-docs-package',
+  },
 }
 ```
 
-### Loading Documentation Packages
-
-```typescript
-import { loadDocsPackage, loadDocPageBySlug } from '@vendure-io/docs-provider'
+Your package should export the manifest from a dedicated entry point. Add the following to your `package.json`:
 
-// Load a docs package
-const { manifest, basePath } = await loadDocsPackage('@vendure/docs-core')
-
-// Load a specific page by slug
-const page = await loadDocPageBySlug(loadedPackage, 'getting-started/installation')
-if (page) {
-  console.log(page.meta.title) // "Installation"
-  console.log(page.content) // MDX content
+```json
+{
+  "exports": {
+    "./manifest": {
+      "import": "./dist/manifest.js",
+      "types": "./dist/manifest.d.ts"
+    }
+  }
 }
 ```
 
@@ -153,6 +164,7 @@ if (hasFrontmatter(mdxContent)) {
 | `NavigationNode`      | A node in the navigation tree                         |
 | `DocPage`             | A loaded documentation page with metadata and content |
 | `DocPageMeta`         | Frontmatter metadata for a page                       |
+| `ParsedFrontmatter`   | Result of parsing frontmatter (meta + content)        |
 | `SearchConfig`        | Search indexing configuration                         |
 | `VendureVersion`      | Supported Vendure versions (`'v1' \| 'v2' \| 'v3'`)   |
 | `FlatNavigationNode`  | Flattened navigation node with path info              |
@@ -160,6 +172,17 @@ if (hasFrontmatter(mdxContent)) {
 | `LoadedDocsPackage`   | Result of loading a docs package                      |
 | `GitHubConfig`        | GitHub repository configuration for edit links        |
 
+### MDX Component Props
+
+| Type                       | Description                             |
+| -------------------------- | --------------------------------------- |
+| `GenerationInfoProps`      | Props for GenerationInfo component      |
+| `MemberInfoProps`          | Props for MemberInfo component          |
+| `MemberDescriptionProps`   | Props for MemberDescription component   |
+| `CustomFieldPropertyProps` | Props for CustomFieldProperty component |
+| `StackblitzProps`          | Props for Stackblitz component          |
+| `MdxComponentProps`        | Union type of all MDX component props   |
+
 ### Schemas (Zod)
 
 All types have corresponding Zod schemas for runtime validation:
@@ -190,16 +213,11 @@ All types have corresponding Zod schemas for runtime validation:
 | `isNodeActive(node, currentPath)`        | Check if node matches path                |
 | `getNodesAtDepth(manifest, depth)`       | Get nodes at specific depth               |
 
-#### Loader Utilities
+#### Navigation Utilities
 
-| Function                               | Description                      |
-| -------------------------------------- | -------------------------------- |
-| `loadDocsPackage(packageName)`         | Load and validate a docs package |
-| `loadDocPage(package, filePath)`       | Load a page by file path         |
-| `loadDocPageBySlug(package, slugPath)` | Load a page by slug path         |
-| `resolveFilePath(package, node)`       | Resolve full file path           |
-| `isDocsPackageInstalled(packageName)`  | Check if package is installed    |
-| `getAllFilePaths(manifest)`            | Get all file paths from manifest |
+| Function                    | Description                      |
+| --------------------------- | -------------------------------- |
+| `getAllFilePaths(manifest)` | Get all file paths from manifest |
 
 #### Frontmatter Utilities
 
@@ -216,7 +234,6 @@ All types have corresponding Zod schemas for runtime validation:
 | ------------------------- | ------------------------------------- |
 | `ManifestValidationError` | Thrown when manifest validation fails |
 | `FrontmatterParseError`   | Thrown when frontmatter parsing fails |
-| `DocsPackageLoadError`    | Thrown when package loading fails     |
 
 ## Development
 

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { FrontmatterParseError, extractFrontmatterData, hasFrontmatter, parseFro
 export type { ParsedFrontmatter } from './frontmatter';
 export { ManifestValidationError, buildBreadcrumbs, findNavigationNode, flattenNavigation, getLeafNodes, getNodesAtDepth, getPrevNextNodes, isNodeActive, validateManifest, } from './manifest';
 export { getAllFilePaths } from './navigation-utils';
+export type { CustomFieldPropertyProps, GenerationInfoProps, MdxComponentProps, MemberDescriptionProps, MemberInfoProps, StackblitzProps, } from './mdx-components';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,cAAc,EACd,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAA;AAGhB,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,UAAU,CAAA;AAGjB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGtD,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,cAAc,EACd,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAA;AAGhB,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,UAAU,CAAA;AAGjB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGtD,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGpD,YAAY,EACV,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,eAAe,GAChB,MAAM,kBAAkB,CAAA"}

package/dist/mdx-components.d.ts

@@ -0,0 +1,120 @@
+/**
+ * MDX Component Contract Types
+ *
+ * This file defines TypeScript interfaces for MDX components used in Vendure documentation.
+ * These contracts are framework-agnostic (no React dependency) and define the expected
+ * props for each component.
+ *
+ * The actual React implementations live in `apps/docs/src/components/mdx/`.
+ */
+/**
+ * GenerationInfo Component
+ *
+ * Displays package metadata with NPM and GitHub source links.
+ * Typically shown at the top of reference documentation pages.
+ *
+ * @example
+ * ```mdx
+ * <GenerationInfo
+ *   packageName="@vendure/core"
+ *   sourceFile="src/entity/product.entity.ts"
+ *   sourceLine={42}
+ *   since="1.0.0"
+ * />
+ * ```
+ */
+export interface GenerationInfoProps {
+    /** NPM package name (e.g., "@vendure/core") */
+    packageName: string;
+    /** Path to source file relative to package root */
+    sourceFile: string;
+    /** Line number in source file */
+    sourceLine: number;
+    /** Version when this API was introduced */
+    since?: string;
+    /** Mark as experimental API */
+    experimental?: boolean;
+}
+/**
+ * MemberInfo Component
+ *
+ * Displays type information for class/interface members.
+ * Used in TypeScript API reference documentation.
+ *
+ * @example
+ * ```mdx
+ * <MemberInfo
+ *   kind="method"
+ *   type={<>(<a href="/reference/ctx">RequestContext</a>) =&gt; Promise&lt;Product&gt;</>}
+ *   since="2.0.0"
+ * />
+ * ```
+ */
+export interface MemberInfoProps {
+    /** Member kind: method, property, getter, setter, constructor */
+    kind: 'method' | 'property' | 'getter' | 'setter' | 'constructor';
+    /** TypeScript type signature (accepts JSX with links) */
+    type: unknown;
+    /** Version when this member was introduced */
+    since?: string;
+    /** Mark as experimental API */
+    experimental?: boolean;
+    /** Default value (accepts JSX) */
+    default?: unknown;
+}
+/**
+ * MemberDescription Component
+ *
+ * Simple wrapper for member descriptions in API reference documentation.
+ * Provides consistent styling for description content.
+ *
+ * @example
+ * ```mdx
+ * <MemberDescription>
+ *   The `Product` entity represents items in your catalog.
+ *   It includes pricing, variants, and inventory information.
+ * </MemberDescription>
+ * ```
+ */
+export interface MemberDescriptionProps {
+    /** Description content (MDX/JSX) */
+    children: unknown;
+}
+/**
+ * CustomFieldProperty Component
+ *
+ * Shows required/optional status and type information for custom fields.
+ * Used in custom field configuration documentation.
+ *
+ * @example
+ * ```mdx
+ * <CustomFieldProperty required={true} type="string" typeLink="/reference/types/string" />
+ * ```
+ */
+export interface CustomFieldPropertyProps {
+    /** Whether the field is required */
+    required: boolean;
+    /** Type name to display */
+    type: string;
+    /** Optional link for the type */
+    typeLink?: string;
+}
+/**
+ * Stackblitz Component
+ *
+ * Embeds a Stackblitz editor for interactive code examples.
+ *
+ * @example
+ * ```mdx
+ * <Stackblitz id="vendure-getting-started" />
+ * ```
+ */
+export interface StackblitzProps {
+    /** Stackblitz project ID */
+    id: string;
+}
+/**
+ * Union type of all MDX component props for type checking
+ */
+export type MdxComponentProps = GenerationInfoProps | MemberInfoProps | MemberDescriptionProps | CustomFieldPropertyProps | StackblitzProps;
+//# sourceMappingURL=mdx-components.d.ts.map

package/dist/mdx-components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdx-components.d.ts","sourceRoot":"","sources":["../src/mdx-components.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAA;IACjE,yDAAyD;IACzD,IAAI,EAAE,OAAO,CAAA;IACb,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAA;IACjB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,eAAe,GACf,sBAAsB,GACtB,wBAAwB,GACxB,eAAe,CAAA"}

package/docs/mdx-components-reference.md

@@ -0,0 +1,281 @@
+# MDX Components Reference
+
+This document describes the MDX components available for use in Vendure documentation. These components are particularly useful for TypeScript and GraphQL API reference documentation.
+
+## General Components
+
+### Callout
+
+Displays an informational callout box with different variants.
+
+#### Props
+
+| Prop       | Type                                                              | Default  | Description                    |
+| ---------- | ----------------------------------------------------------------- | -------- | ------------------------------ |
+| `type`     | `'info' \| 'warning' \| 'danger' \| 'tip' \| 'caution' \| 'note'` | `'info'` | The callout variant            |
+| `title`    | `string`                                                          | -        | Optional title for the callout |
+| `children` | `ReactNode`                                                       | -        | Content of the callout         |
+
+#### Example
+
+```mdx
+<Callout
+  type="warning"
+  title="Deprecation Notice"
+>
+  This API will be removed in version 4.0. Please migrate to the new API.
+</Callout>
+
+<Callout type="tip">Use the `RequestContext` to access the current user and channel.</Callout>
+```
+
+### Stackblitz
+
+Embeds a Stackblitz editor for interactive code examples.
+
+#### Props
+
+| Prop | Type     | Required | Description               |
+| ---- | -------- | -------- | ------------------------- |
+| `id` | `string` | Yes      | The Stackblitz project ID |
+
+#### Example
+
+```mdx
+<Stackblitz id="vendure-getting-started" />
+```
+
+---
+
+## Reference Documentation Components
+
+These components are designed for TypeScript/GraphQL API reference documentation.
+
+### GenerationInfo
+
+Displays package metadata with NPM and GitHub source links. Typically shown at the top of reference documentation pages.
+
+#### Props
+
+| Prop           | Type      | Required | Description                                  |
+| -------------- | --------- | -------- | -------------------------------------------- |
+| `packageName`  | `string`  | Yes      | NPM package name (e.g., `@vendure/core`)     |
+| `sourceFile`   | `string`  | Yes      | Path to source file relative to package root |
+| `sourceLine`   | `number`  | Yes      | Line number in source file                   |
+| `since`        | `string`  | No       | Version when this API was introduced         |
+| `experimental` | `boolean` | No       | Mark as experimental API                     |
+
+#### Example
+
+```mdx
+<GenerationInfo
+  packageName="@vendure/core"
+  sourceFile="src/entity/product.entity.ts"
+  sourceLine={42}
+  since="1.0.0"
+/>
+
+<GenerationInfo
+  packageName="@vendure/core"
+  sourceFile="src/service/services/product.service.ts"
+  sourceLine={156}
+  experimental={true}
+/>
+```
+
+### MemberInfo
+
+Displays type information for class/interface members. Used in TypeScript API reference documentation.
+
+#### Props
+
+| Prop           | Type                                                              | Required | Description                                        |
+| -------------- | ----------------------------------------------------------------- | -------- | -------------------------------------------------- |
+| `kind`         | `'method' \| 'property' \| 'getter' \| 'setter' \| 'constructor'` | Yes      | The kind of member                                 |
+| `type`         | `ReactNode`                                                       | Yes      | TypeScript type signature (accepts JSX with links) |
+| `since`        | `string`                                                          | No       | Version when this member was introduced            |
+| `experimental` | `boolean`                                                         | No       | Mark as experimental API                           |
+| `default`      | `ReactNode`                                                       | No       | Default value (accepts JSX)                        |
+
+#### Example
+
+```mdx
+{/* Simple property */}
+
+<MemberInfo
+  kind="property"
+  type={<>string</>}
+  default={<>'default-value'</>}
+/>
+
+{/* Method with type links */}
+
+<MemberInfo
+  kind="method"
+  type={
+    <>
+      (<a href="/reference/ctx">RequestContext</a>, productId: <a href="/reference/id">ID</a>) =&gt;
+      Promise&lt;<a href="/reference/product">Product</a>&gt;
+    </>
+  }
+  since="2.0.0"
+/>
+
+{/* Experimental getter */}
+
+<MemberInfo
+  kind="getter"
+  type={<>boolean</>}
+  experimental={true}
+/>
+```
+
+### MemberDescription
+
+Simple wrapper for member descriptions in API reference documentation. Provides consistent styling for description content.
+
+#### Props
+
+| Prop       | Type        | Required | Description                   |
+| ---------- | ----------- | -------- | ----------------------------- |
+| `children` | `ReactNode` | Yes      | Description content (MDX/JSX) |
+
+#### Example
+
+```mdx
+<MemberDescription>
+  The `Product` entity represents items in your catalog.
+  It includes pricing, variants, and inventory information.
+
+See the [Product Guide](/guides/products) for more details.
+
+</MemberDescription>
+```
+
+### CustomFieldProperty
+
+Shows required/optional status and type information for custom fields. Used in custom field configuration documentation.
+
+#### Props
+
+| Prop       | Type      | Required | Description                   |
+| ---------- | --------- | -------- | ----------------------------- |
+| `required` | `boolean` | Yes      | Whether the field is required |
+| `type`     | `string`  | Yes      | Type name to display          |
+| `typeLink` | `string`  | No       | Optional link for the type    |
+
+#### Example
+
+```mdx
+<CustomFieldProperty
+  required={true}
+  type="string"
+/>
+
+<CustomFieldProperty
+  required={false}
+  type="LocalizedString"
+  typeLink="/reference/types/localized-string"
+/>
+```
+
+---
+
+## Complete Reference Page Example
+
+Here's an example of how these components can be used together for a complete reference page:
+
+```mdx
+---
+title: Product
+description: The Product entity represents items in your catalog.
+---
+
+# Product
+
+<GenerationInfo
+  packageName="@vendure/core"
+  sourceFile="src/entity/product/product.entity.ts"
+  sourceLine={25}
+  since="1.0.0"
+/>
+
+The `Product` entity represents items in your catalog.
+
+## Properties
+
+### name
+
+<MemberInfo
+  kind="property"
+  type={<>string</>}
+/>
+
+<MemberDescription>The name of the product as displayed to customers.</MemberDescription>
+
+### slug
+
+<MemberInfo
+  kind="property"
+  type={<>string</>}
+/>
+
+<MemberDescription>The URL-friendly identifier for this product.</MemberDescription>
+
+## Methods
+
+### getVariants
+
+<MemberInfo
+  kind="method"
+  type={
+    <>
+      (<a href="/reference/ctx">RequestContext</a>) =&gt; Promise&lt;
+      <a href="/reference/product-variant">ProductVariant</a>[]&gt;
+    </>
+  }
+  since="1.1.0"
+/>
+
+<MemberDescription>Returns all variants associated with this product.</MemberDescription>
+
+## Custom Fields
+
+Products support the following custom field types:
+
+<CustomFieldProperty
+  required={false}
+  type="string"
+/>
+<CustomFieldProperty
+  required={false}
+  type="int"
+/>
+<CustomFieldProperty
+  required={false}
+  type="boolean"
+/>
+<CustomFieldProperty
+  required={false}
+  type="relation"
+  typeLink="/reference/custom-fields#relation"
+/>
+```
+
+---
+
+## TypeScript Contracts
+
+All component props have TypeScript interfaces defined in `@vendure-io/docs-provider`:
+
+```typescript
+import type {
+  GenerationInfoProps,
+  MemberInfoProps,
+  MemberDescriptionProps,
+  CustomFieldPropertyProps,
+  StackblitzProps,
+} from '@vendure-io/docs-provider'
+```
+
+These interfaces are framework-agnostic and can be used for type checking without importing React.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vendure-io/docs-provider",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Contract types and utilities for Vendure documentation packages",
   "private": false,
   "publishConfig": {