boltdocs 3.1.0 → 3.2.2

package/dist/{sidebar-DknLUI1R.d.ts → sidebar-COTaMHR-.d.ts}

@@ -2,6 +2,7 @@
 import * as React$2 from "react";
 import { ComponentType, ReactNode } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import * as _$http from "http";
 import { Plugin } from "vite";
 
 //#region src/shared/types.d.ts
@@ -109,15 +110,15 @@ interface BoltdocsThemeConfig {
   };
   navbar?: Array<{
     label: string | Record<string, string>;
-    href: BoltdocsRoutePathWithFallback$1;
+    href: BoltdocsRoutePathWithFallback;
     items?: Array<{
       label: string | Record<string, string>;
-      href: BoltdocsRoutePathWithFallback$1;
+      href: BoltdocsRoutePathWithFallback;
     }>;
   }>;
   sidebar?: Record<string, Array<{
     text: string;
-    link: BoltdocsRoutePathWithFallback$1;
+    link: BoltdocsRoutePathWithFallback;
   }>>;
   sidebarGroups?: Record<string, {
     title?: string | Record<string, string>;
@@ -178,6 +179,43 @@ interface BoltdocsVersionConfig {
   label: string;
   path: string;
 }
+/**
+ * Configuration for content collections (e.g. blog posts, changelog)
+ * declared in `boltdocs.config.ts`. Each entry maps a directory name
+ * (e.g. `[blog]`) to its display + ordering settings.
+ */
+interface BoltdocsCollectionsConfig {
+  /**
+   * Map of collection id (matches the bracketed directory name) to
+   * its display label. Falls back to the id when a label is missing.
+   */
+  labels?: Record<string, string | Record<string, string>>;
+  /**
+   * Map of collection id to a numeric position used for sidebar ordering.
+   * Collections with no explicit position are sorted last.
+   */
+  positions?: Record<string, number>;
+  /**
+   * Items-per-page for paginated collection routes (e.g. blog indexes).
+   * Falls back to the framework default (10) when omitted.
+   */
+  postsPerPage?: number;
+  /**
+   * Default collection ID used by collection routing when no collection
+   * is explicitly referenced. Defaults to `'blog'`.
+   */
+  defaultCollection?: string;
+  /**
+   * Date format string for rendering post dates in listing pages.
+   * Defaults to `'MMMM dd, yyyy'`.
+   */
+  dateFormat?: string;
+  /**
+   * Field used to sort posts within a collection.
+   * Defaults to `'date'`.
+   */
+  sortBy?: 'date' | 'title' | 'sidebarPosition';
+}
 /**
  * Configuration for documentation versioning.
  */
@@ -197,7 +235,7 @@ type BadgeValue = string | {
  * Context provided to plugin lifecycle hooks.
  */
 interface PluginContext {
-  readonly config: BoltdocsConfig$1;
+  readonly config: BoltdocsConfig;
   readonly logger: PluginLogger;
   readonly store: PluginStore;
   readonly meta: PluginMeta;
@@ -205,6 +243,129 @@ interface PluginContext {
   readonly rootDir: string;
   readonly outDir: string;
   readonly routes: RouteMeta[];
+  /** Namespaced cache helpers bound to the core's cache machinery. */
+  readonly caches: PluginCachesAPI;
+  /** Structured diagnostics channel; reports can be drained via `list()`. */
+  readonly diagnostics: PluginDiagnosticsAPI;
+  /** Helpers for resolving paths inside the workspace safely. */
+  readonly paths: PluginPathsAPI;
+  /** Declare virtual modules the core should expose to Vite. */
+  readonly virtualModules: PluginVirtualModulesAPI;
+  /** Register and query transform middleware at runtime. */
+  readonly middleware: PluginMiddlewareAPI;
+  /**
+   * Hook into dev-server file watching and send custom HMR events
+   * to connected clients.
+   */
+  readonly hmr: PluginHmrAPI;
+  /**
+   * Register HTTP middleware and server lifecycle hooks without
+   * writing a Vite plugin.
+   */
+  readonly server: PluginServerAPI;
+}
+/**
+ * Functional cache helpers exposed through `PluginContext.caches`.
+ *
+ * Plugin authors do not get a reference to the raw `TransformCache` /
+ * `FileCache` instances — those stay encapsulated in core. The methods
+ * returned here are bound to namespaced keys so two plugins cannot
+ * collide.
+ */
+interface PluginCachesAPI {
+  /** Sharded, hash-keyed cache. One namespace per plugin recommended. */
+  transform(namespace: string): PluginTransformCacheAPI;
+  /** Routes cache wrapper around the parsed-doc cache. */
+  routes: PluginRoutesCacheAPI;
+  /** In-memory LRU cache keyed by namespace + plugin-supplied key. */
+  memory<V = unknown>(namespace: string, opts?: {
+    max?: number;
+    ttl?: number;
+  }): PluginMemoryCacheAPI<V>;
+}
+interface PluginTransformCacheAPI {
+  /** Async read — first call may warm from disk if the entry was evicted. */
+  get(key: string): Promise<string | null>;
+  /** Synchronous write that batches a background disk flush. */
+  set(key: string, value: string): void;
+  /** Force-flush background writes. Call before measuring disk state. */
+  flush(): Promise<void>;
+}
+interface PluginRoutesCacheAPI {
+  /** Read a parsed `RouteMeta` (and its private `_content` blob) by abs file path. */
+  get(filePath: string): RouteMeta | null;
+  /** Write a parsed route entry. Caller assumptions match `docCache.set`. */
+  set(filePath: string, route: RouteMeta): void;
+  /** Invalidate one route. Use when content changes. */
+  invalidate(filePath: string): void;
+  /** Clear every cached route. Use when the directory layout changes. */
+  invalidateAll(): void;
+}
+interface PluginMemoryCacheAPI<V> {
+  get(key: string): V | undefined;
+  set(key: string, value: V): void;
+  has(key: string): boolean;
+}
+/**
+ * Plugin diagnostics API.
+ *
+ * Plugins push structured records instead of spamming the logger; downstream
+ * tools (dev-server overlay, CI reporters, IDE plugins) drain the queue via
+ * `list()`.
+ */
+interface DiagnosticRecord {
+  readonly id: number;
+  readonly severity: 'info' | 'warn' | 'error';
+  readonly code: string;
+  readonly message: string;
+  readonly pluginName: string;
+  readonly filePath?: string;
+  readonly routePath?: string;
+  readonly time: Date;
+}
+interface PluginDiagnosticsAPI {
+  report(severity: DiagnosticRecord['severity'], code: string, message: string, where?: {
+    filePath?: string;
+    routePath?: string;
+  }): void;
+  list(): readonly DiagnosticRecord[];
+  clear(): void;
+}
+/**
+ * Path-resolution helpers exposed through `PluginContext.paths`.
+ *
+ * Both `resolveDocs` and `resolveAsset` validate the resulting path against
+ * the workspace boundary and reject any segment that resolves outside the
+ * docs / project root directories.
+ */
+interface PluginPathsAPI {
+  resolveDocs(...parts: string[]): string;
+  resolveAsset(...parts: string[]): string;
+  /**
+   * Build a `file://` URL for an absolute path inside the workspace.
+   * Useful for `new URL(import.meta.url)` replacements and image srcsets.
+   */
+  safeFileURL(absFilePath: string): string;
+}
+/**
+ * Plugin virtual-modules registration.
+ *
+ * Plugins call `add(id, loader)` to expose a `virtual:<plugin>/<id>` module
+ * to Vite without having to author a full Vite plugin. The loader returns
+ * the module source code as a string; the core wraps it in the right
+ * `resolveId`/`load` plumbing at Vite build time.
+ */
+interface RegisteredVirtualModule {
+  readonly id: string;
+  readonly eager: boolean;
+  readonly loader: () => string | Promise<string>;
+}
+interface PluginVirtualModulesAPI {
+  add(id: string, loader: () => string | Promise<string>, opts?: {
+    eager?: boolean;
+  }): void;
+  has(id: string): boolean;
+  list(): readonly RegisteredVirtualModule[];
 }
 /**
  * Logger interface for plugin logging.
@@ -231,6 +392,152 @@ interface PluginMeta {
   version?: string;
   boltdocsVersion?: string;
 }
+/**
+ * Chain control signal returned by transform hooks. Use with `__signal` in
+ * the return value to influence the middleware chain:
+ *
+ * - `'skip'`: stop processing this hook for the current file (remaining
+ *   plugins in the chain still run).
+ * - `'break'`: stop the entire chain immediately — no further plugin's
+ *   transform hooks run for this file.
+ *
+ * @example
+ * ```ts
+ * transformMdx: async (_ctx, { code }) => ({
+ *   code: code.replace(/foo/g, 'bar'),
+ *   __signal: 'skip',   // skip remaining plugins
+ * })
+ * ```
+ */
+type ChainSignal = 'skip' | 'break';
+/**
+ * Returned by a transform hook that wants to signal the chain. The `__signal`
+ * field is optional — most hooks will just return `{ code: string }` and the
+ * chain continues normally. When `__signal` is present, `runChain` reacts:
+ *
+ * - `'skip'` continues with the next plugin, but passes the **original params**
+ *   (the output of this hook is discarded).
+ * - `'break'` stops the chain immediately.
+ *
+ * @template T The params shape (e.g. `{ code: string; filePath: string }`).
+ */
+type TransformResult<T> = T & {
+  __signal?: ChainSignal;
+};
+/**
+ * Enriched params passed to `transformSource` and `transformMdx`. The `code`
+ * and `filePath` fields are always present. The optional `frontmatter` and
+ * `route` fields are populated when available (they are `undefined` in the
+ * early pipeline where frontmatter hasn't been parsed yet).
+ */
+interface TransformSourceParams {
+  /** The raw or compiled code (source before MDX / JS after MDX). */
+  code: string;
+  /** Absolute file path of the source document. */
+  filePath: string;
+  /** Parsed frontmatter, if available. `undefined` in very early pipeline. */
+  frontmatter?: Record<string, unknown>;
+}
+/**
+ * Enriched params passed to `transformHtml`. The `html` and `path` fields
+ * are always present. The optional `route` carries the generated `RouteMeta`
+ * for richer context (locale, version, collection, etc.).
+ */
+interface TransformHtmlParams {
+  /** The rendered HTML string for this page. */
+  html: string;
+  /** The route path (e.g. `/docs/guides/start`). */
+  path: string;
+  /** The route metadata for the page, if available. */
+  route?: RouteMeta;
+}
+/**
+ * Plugin transform middleware. Each middleware runs in the transform
+ * pipeline alongside lifecycle hooks. The `name` field is optional —
+ * when omitted, the owning plugin's name is used as context.
+ * Middleware runs in `enforce` order (pre → normal → post) and supports
+ * `__signal: 'skip'` / `__signal: 'break'` for chain control.
+ */
+interface PluginTransformMiddleware {
+  /** Optional name. Defaults to the owning plugin's name for diagnostics. */
+  name?: string;
+  enforce?: 'pre' | 'post';
+  transformSource?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
+    code: string;
+  }> | Promise<TransformResult<{
+    code: string;
+  }>>;
+  transformMdx?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
+    code: string;
+  }> | Promise<TransformResult<{
+    code: string;
+  }>>;
+  transformHtml?: (ctx: PluginContext, params: TransformHtmlParams) => TransformResult<{
+    html: string;
+  }> | Promise<TransformResult<{
+    html: string;
+  }>>;
+}
+/**
+ * Plugin middleware registry API exposed through `PluginContext.middleware`.
+ * Plugins can register named middleware entries from lifecycle hooks.
+ */
+interface PluginMiddlewareAPI {
+  add(middleware: PluginTransformMiddleware): void;
+  remove(name: string): void;
+  has(name: string): boolean;
+  list(): readonly PluginTransformMiddleware[];
+}
+/**
+ * HMR event types plugins can listen to.
+ */
+type PluginHmrEvent = 'add' | 'change' | 'unlink';
+/**
+ * Plugin HMR API — hook into file-watching events and send custom
+ * HMR messages to connected clients.
+ */
+interface PluginHmrAPI {
+  /**
+   * Register a callback for file events scoped to the docs directory.
+   * The callback receives the normalized file path and event type.
+   */
+  onFileEvent(eventType: PluginHmrEvent, handler: (filePath: string) => void | Promise<void>): void;
+  /** Shorthand for `onFileEvent('add', handler)`. */
+  onFileAdd(handler: (filePath: string) => void | Promise<void>): void;
+  /** Shorthand for `onFileEvent('change', handler)`. */
+  onFileChange(handler: (filePath: string) => void | Promise<void>): void;
+  /** Shorthand for `onFileEvent('unlink', handler)`. */
+  onFileUnlink(handler: (filePath: string) => void | Promise<void>): void;
+  /**
+   * Send a custom HMR event to all connected clients.
+   * The client can listen with `import.meta.hot.on('boltdocs:plugin:<name>', ...)`.
+   */
+  send(event: string, data?: unknown): void;
+}
+/**
+ * Plugin Server API — register HTTP middleware and lifecycle hooks
+ * for the dev server and preview server, without writing a Vite plugin.
+ */
+interface PluginServerAPI {
+  /**
+   * Register a Connect-style middleware function.
+   * Runs on both dev and preview servers.
+   */
+  use(middleware: PluginServerMiddleware): void;
+  /**
+   * Register a middleware scoped to a specific path prefix.
+   * Only requests starting with `path` trigger the handler.
+   */
+  useAt(path: string, handler: PluginServerMiddleware): void;
+  /** Called when the dev/preview server starts (once per process). */
+  onStart(callback: () => void | Promise<void>): void;
+  /** Called when the server shuts down (cleanup). */
+  onEnd(callback: () => void | Promise<void>): void;
+}
+/**
+ * Connect-style middleware signature.
+ */
+type PluginServerMiddleware = (req: _$http.IncomingMessage, res: _$http.ServerResponse, next: (err?: unknown) => void) => void | Promise<void>;
 /**
  * Plugin lifecycle hooks with full type safety.
  */
@@ -240,30 +547,21 @@ interface PluginLifecycleHooks {
   beforeDev?: (ctx: PluginContext) => Promise<void> | void;
   afterDev?: (ctx: PluginContext) => Promise<void> | void;
   buildEnd?: (ctx: PluginContext) => Promise<void> | void;
-  transformSource?: (ctx: PluginContext, params: {
+  transformSource?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
     code: string;
-    filePath: string;
-  }) => Promise<{
+  }> | Promise<TransformResult<{
     code: string;
-  }> | {
-    code: string;
-  };
-  transformMdx?: (ctx: PluginContext, params: {
-    code: string;
-    filePath: string;
-  }) => Promise<{
+  }>>;
+  transformMdx?: (ctx: PluginContext, params: TransformSourceParams) => TransformResult<{
     code: string;
-  }> | {
+  }> | Promise<TransformResult<{
     code: string;
-  };
-  transformHtml?: (ctx: PluginContext, params: {
-    html: string;
-    path: string;
-  }) => Promise<{
+  }>>;
+  transformHtml?: (ctx: PluginContext, params: TransformHtmlParams) => TransformResult<{
     html: string;
-  }> | {
+  }> | Promise<TransformResult<{
     html: string;
-  };
+  }>>;
 }
 /**
  * MDX processor configuration.
@@ -287,22 +585,19 @@ interface BoltdocsPlugin {
   rehypePlugins?: unknown[];
   vitePlugins?: Plugin[];
   components?: Record<string, string>;
+  /** Optional runtime metadata exposed to client via useConfig().plugins[].metadata */
+  metadata?: Record<string, unknown>;
+  /** Declarative transform middleware entries. */
+  middleware?: PluginTransformMiddleware[];
   /** Lifecycle hooks with full type safety */
   hooks?: PluginLifecycleHooks;
 }
 /**
- * Configuration for the collections (blog) feature.
  */
-interface BoltdocsCollectionsConfig {
-  /** Number of posts per page in collection listing pages. Defaults to 10. */
-  postsPerPage?: number;
-  /** The name of the default collection used by BlogList when none is specified. */
-  defaultCollection?: string;
-  /** Date format string for rendering post dates (e.g., 'MMMM dd, yyyy'). */
-  dateFormat?: string;
-  /** Field to sort posts by. Defaults to 'date'. */
-  sortBy?: 'date' | 'title' | 'sidebarPosition';
-}
+/**
+ */
+/**
+ */
 interface BoltdocsSecurityConfig {
   headers?: Record<string, string>;
   enableCSP?: boolean;
@@ -425,7 +720,7 @@ interface BoltdocsDraftsConfig {
 /**
  * The root configuration object for Boltdocs.
  */
-interface BoltdocsConfig$1 {
+interface BoltdocsConfig {
   siteUrl?: string;
   docsDir?: string;
   base?: string;
@@ -461,7 +756,7 @@ declare global {
 }
 type BoltdocsTypes = Boltdocs.Types;
 type BoltdocsRoutePath = keyof Boltdocs.RoutePaths;
-type BoltdocsRoutePathWithFallback$1 = BoltdocsRoutePath extends never ? string : BoltdocsRoutePath;
+type BoltdocsRoutePathWithFallback = BoltdocsRoutePath extends never ? string : BoltdocsRoutePath;
 type BoltdocsLocale = Boltdocs.Types extends {
   Locale: infer L;
 } ? L : string;
@@ -476,8 +771,7 @@ type TransformMdxComponents<T> = { [K in keyof T as K extends `Frontmatter_${str
 };
 type BoltdocsMdxComponents = Boltdocs.Types extends {
   MdxComponents: infer M;
-} ? TransformMdxComponents<UnpackMdxComponents<M>> : {
-  [key: string]: ComponentType<any>;
+} ? TransformMdxComponents<UnpackMdxComponents<M>> : Omit<Record<string, ComponentType<any>>, 'Frontmatter'> & {
   Frontmatter: Record<string, ComponentType<any>>;
 };
 //#endregion
@@ -556,12 +850,26 @@ interface ComponentRoute {
   excerpt?: string;
   /** Cover image for blog posts */
   coverImage?: string;
+  /** Optional explicit order (alternative to sidebarPosition) */
+  order?: number;
+  /** Optional explicit label for the sidebar */
+  sidebarLabel?: string;
+  /** Optional category for the page */
+  category?: string;
+  /** Whether the page is hidden from the sidebar */
+  sidebarHidden?: boolean;
+  /**
+   * Optional nested child routes for sidebar hierarchies that mirror the
+   * server-side `RouteMeta.subRoutes` shape. `sidebar.tsx` walks this
+   * field to render the group → subRoutes → items tree.
+   */
+  routes?: ComponentRoute[];
   /** Raw extensible frontmatter data for custom components and formatters */
-  frontmatter?: Record<string, any>;
+  frontmatter?: Record<string, unknown>;
   /** Clean URL segments stripped of locale/version prefixes */
   slugParts?: string[];
   /** SEO metadata for page headers */
-  seo?: Record<string, any>;
+  seo?: Record<string, unknown>;
   /** Flag to indicate if this is a fallback redirect route */
   fallback?: boolean;
 }
@@ -719,7 +1027,7 @@ declare function SidebarGroup({
  */
 interface SidebarLinkProps extends ComponentBase {
   label: string;
-  href: BoltdocsRoutePathWithFallback$1;
+  href: BoltdocsRoutePathWithFallback;
   active?: boolean;
   icon?: React.ElementType;
   badge?: ComponentRoute['badge'];
@@ -789,4 +1097,4 @@ declare const Sidebar: typeof SidebarRoot & {
   Items: typeof SidebarItems;
 };
 //#endregion
-export { BoltdocsRoutePathWithFallback$1 as A, SiteConfig as C, BoltdocsLocale as D, BoltdocsIntegrationsConfig as E, BoltdocsTypes as M, BoltdocsVersion as N, BoltdocsMdxComponents as O, SidebarProps as S, BoltdocsConfig$1 as T, CollectionPostLoaderData as _, SidebarItem as a, NavbarLink as b, SidebarItemsProps as c, SidebarMobile as d, SidebarRoot as f, CollectionListLoaderData as g, BoltdocsTab as h, SidebarHeader as i, BoltdocsSocialLink as j, BoltdocsRoutePath as k, SidebarLink as l, ComponentBase as m, SidebarContent as n, SidebarItemProps as o, SidebarSubGroup as p, SidebarGroup as r, SidebarItems as s, Sidebar as t, SidebarLinkProps as u, ComponentRoute as v, TabsProps as w, OnThisPageProps as x, LayoutProps as y };
+export { BoltdocsRoutePathWithFallback as A, SiteConfig as C, BoltdocsLocale as D, BoltdocsIntegrationsConfig as E, BoltdocsTypes as M, BoltdocsVersion as N, BoltdocsMdxComponents as O, SidebarProps as S, BoltdocsConfig as T, CollectionPostLoaderData as _, SidebarItem as a, NavbarLink as b, SidebarItemsProps as c, SidebarMobile as d, SidebarRoot as f, CollectionListLoaderData as g, BoltdocsTab as h, SidebarHeader as i, BoltdocsSocialLink as j, BoltdocsRoutePath as k, SidebarLink as l, ComponentBase as m, SidebarContent as n, SidebarItemProps as o, SidebarSubGroup as p, SidebarGroup as r, SidebarItems as s, Sidebar as t, SidebarLinkProps as u, ComponentRoute as v, TabsProps as w, OnThisPageProps as x, LayoutProps as y };