boltdocs 3.3.5 → 3.4.0

package/dist/index-RK7W_Fxy.d.cts

@@ -0,0 +1,343 @@
+
+import * as _$react from "react";
+import React$1, { ComponentType, ReactNode } from "react";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { AliasOptions, Plugin, UserConfig } from "vite";
+import { BadgeValue, BoltdocsCollectionsConfig, BoltdocsConfigContract, BoltdocsI18nConfig, BoltdocsIntegrationsConfig, BoltdocsVersionsConfig, CodeHighlightConfig, CodeTheme, JsonLdObject, PluginDefinition, RedirectConfig, RedirectStatus, StructuredData } from "@bdocs/contracts";
+
+//#region src/shared/types.d.ts
+/**
+ * Represents a single social link in the configuration.
+ */
+interface BoltdocsSocialLink {
+  icon: 'discord' | 'x' | 'github' | 'bluesky' | string;
+  link: string;
+}
+/**
+ * Theme-specific configuration options.
+ */
+interface BoltdocsThemeConfig {
+  title?: string | Record<string, string>;
+  description?: string | Record<string, string>;
+  logo?: string | {
+    dark: string;
+    light: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+  };
+  navbar?: Array<{
+    label: string | Record<string, string>;
+    href: BoltdocsRoutePathWithFallback;
+    items?: Array<{
+      label: string | Record<string, string>;
+      href: BoltdocsRoutePathWithFallback;
+    }>;
+  }>;
+  sidebar?: Record<string, Array<{
+    text: string;
+    link: BoltdocsRoutePathWithFallback;
+  }>>;
+  sidebarGroups?: Record<string, {
+    title?: string | Record<string, string>;
+    icon?: string;
+  }>;
+  socialLinks?: BoltdocsSocialLink[];
+  editLink?: string;
+  communityHelp?: string;
+  version?: string;
+  githubRepo?: string;
+  favicon?: string;
+  tabs?: Array<{
+    id: string;
+    text: string | Record<string, string>;
+    icon?: string;
+  }>;
+  /**
+   * Legacy alias for `codeHighlighting.theme`. Kept for backwards
+   * compatibility — prefer `codeHighlighting`.
+   * @deprecated Use `codeHighlighting` instead.
+   */
+  codeTheme?: CodeTheme;
+  /**
+   * Configures the markdown code highlighting engine. The engine is
+   * engine-agnostic: `engine` accepts a registry id (`'shiki'` by default),
+   * an adapter instance, or an adapter factory — so any highlighter can be
+   * plugged in without changes to the core.
+   *
+   * Shorthand: a plain string is a registry id, i.e. `'shiki'` is
+   * equivalent to `{ engine: 'shiki' }` (resolved by
+   * `normalizeCodeHighlightConfig()` at every read site).
+   */
+  codeHighlighting?: CodeHighlightConfig | string;
+}
+interface BoltdocsPlugin extends PluginDefinition<BoltdocsConfig, IncomingMessage, ServerResponse> {
+  vitePlugins?: Plugin[];
+}
+/**
+ * The root configuration object for Boltdocs.
+ */
+interface BoltdocsConfig extends BoltdocsConfigContract<BoltdocsPlugin> {
+  theme?: BoltdocsThemeConfig;
+  aliases?: AliasOptions;
+  vite?: UserConfig;
+}
+/**
+ * Global namespace for Boltdocs types that can be augmented by generated code.
+ * This allows for strictly typed locales and versions based on the project configuration.
+ */
+declare global {
+  namespace Boltdocs {
+    interface Types {}
+    /**
+     * Marker interface augmented by generated code to provide strict route path typing.
+     * When no types have been generated (e.g., before first dev server start),
+     * keyof is never, and BoltdocsRoutePath falls back to string.
+     */
+    interface RoutePaths {}
+  }
+}
+type BoltdocsTypes = Boltdocs.Types;
+type BoltdocsRoutePath = keyof Boltdocs.RoutePaths;
+type ExternalRouteReference = `/${string}` | `#${string}` | `?${string}` | `site:/${string}` | `site:${string}` | `http://${string}` | `https://${string}` | `//${string}`;
+type BoltdocsRoutePathWithFallback = BoltdocsRoutePath | ExternalRouteReference | string;
+type BoltdocsLocale = Boltdocs.Types extends {
+  Locale: infer L;
+} ? L : string;
+type BoltdocsVersion = Boltdocs.Types extends {
+  Version: infer V;
+} ? V : string;
+type UnpackMdxComponents<T> = T extends {
+  default: infer D;
+} ? D : T;
+type TransformMdxComponents<T> = { [K in keyof T as K extends `Frontmatter_${string}` ? never : K]: T[K] } & {
+  Frontmatter: { [K in keyof T as K extends `Frontmatter_${infer Name}` ? Name : never]: T[K] };
+};
+type BoltdocsMdxComponents = Boltdocs.Types extends {
+  MdxComponents: infer M;
+} ? TransformMdxComponents<UnpackMdxComponents<M>> : Omit<Record<string, ComponentType<unknown>>, 'Frontmatter'> & {
+  Frontmatter: Record<string, ComponentType<unknown>>;
+};
+//#endregion
+//#region src/client/router/types.d.ts
+interface LoaderFunctionArgs {
+  request: Request;
+  params: Record<string, string>;
+}
+type LoaderFunction<T = unknown> = (args: LoaderFunctionArgs) => Promise<T> | T;
+type PrefetchFunction$1 = (to: string) => Promise<void>;
+interface RouteMatch {
+  route: RouteRecord;
+  params: Record<string, string>;
+  pathname: string;
+  pathnameBase: string;
+  data?: Record<string, unknown>;
+}
+interface LazyRouteResult {
+  Component?: ComponentType<any>;
+  element?: ReactNode;
+  loader?: LoaderFunction;
+  ErrorBoundary?: ComponentType<any>;
+}
+/** Structurally compatible with react-router-dom's route objects */
+interface RouteRecord {
+  path?: string;
+  index?: boolean;
+  id?: string;
+  element?: ReactNode;
+  Component?: ComponentType<any>;
+  loader?: LoaderFunction;
+  action?: (...args: any[]) => any;
+  ErrorBoundary?: ComponentType<any>;
+  hasErrorBoundary?: boolean;
+  HydrateFallback?: ComponentType<any>;
+  children?: RouteRecord[];
+  lazy?: () => Promise<LazyRouteResult>;
+  caseSensitive?: boolean;
+  shouldRevalidate?: (...args: any[]) => boolean;
+  getStaticPaths?: () => string[] | Promise<string[]>;
+  entry?: string;
+  /** Locale this route belongs to (used by i18n fallbacks) */
+  locale?: string;
+}
+interface RouterOptions {
+  routes: RouteRecord[];
+  basename?: string;
+  future?: Record<string, boolean>;
+}
+interface RouteRendererProps {
+  routes: RouteRecord[];
+  pathname?: string;
+  loaderData?: Record<string, unknown> | null;
+  /** Whether loaderData was explicitly produced for the initial SSR route. */
+  hasLoaderData?: boolean;
+  /** Resolved branch supplied by SSR so lazy MDX routes render without effects. */
+  resolvedBranch?: RouteRecord[];
+  basename?: string;
+  /** Default locale is omitted from external URLs. */
+  defaultLocale?: string;
+  /** Optional route prefetcher used by Link hover/focus interactions. */
+  prefetch?: PrefetchFunction$1;
+  /** Enables native View Transitions for route updates. */
+  viewTransitions?: boolean | {
+    enabled?: boolean;
+    types?: string[];
+  };
+}
+interface CreateRoutesResult {
+  routes: RouteRecord[];
+  RouteRenderer: ComponentType<RouteRendererProps>;
+  matchRouteBranch: (routes: RouteRecord[], pathname: string) => RouteRecord[];
+  matchRouteBranchWithParams: (routes: RouteRecord[], pathname: string, basename?: string) => Array<{
+    route: RouteRecord;
+    params: Record<string, string>;
+  }>;
+  resolveRouteBranch: (branch: RouteRecord[]) => Promise<RouteRecord[]>;
+}
+//#endregion
+//#region src/client/router/context.d.ts
+interface LocationState {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+type PrefetchFunction = (to: string) => Promise<void>;
+type NavigateFunction = (to: string, options?: {
+  replace?: boolean;
+  state?: unknown; /** Disable the router transition when an outer transition owns the update. */
+  viewTransition?: boolean;
+}) => void;
+declare const defaultNavigate: NavigateFunction;
+declare const LocationContext: _$react.Context<LocationState>;
+declare const NavigateContext: _$react.Context<NavigateFunction>;
+declare const PrefetchContext: _$react.Context<PrefetchFunction>;
+declare const RouteDataContext: _$react.Context<Record<string, unknown> | null>;
+declare const MatchesContext: _$react.Context<RouteMatch[]>;
+interface LocationProviderProps {
+  pathname?: string;
+  children: React.ReactNode;
+  loaderData?: Record<string, unknown> | null;
+  matches?: RouteMatch[];
+  /** Base path of the application. Only links under this path are handled as SPA navigation. */
+  basename?: string;
+  /** Default locale is omitted from external URLs. */
+  defaultLocale?: string;
+  /** Optional route prefetcher used by Link hover/focus interactions. */
+  prefetch?: PrefetchFunction;
+  /** Enables the native View Transition API for route updates. */
+  viewTransitions?: boolean | {
+    enabled?: boolean;
+    types?: string[];
+  };
+}
+declare const LocationProvider: React.FC<LocationProviderProps>;
+//#endregion
+//#region src/client/router/hooks.d.ts
+declare function useLocation(): LocationState;
+declare function useNavigate(): NavigateFunction;
+declare function usePrefetch(): (to: string) => Promise<void>;
+declare function useRouteData<T = Record<string, unknown>>(): T;
+/** Alias for useRouteData — parity with react-router-dom's useLoaderData */
+declare function useLoaderData<T = Record<string, unknown>>(): T;
+declare function useMatches(): RouteMatch[];
+//#endregion
+//#region src/client/router/outlet.d.ts
+declare const OutletContext: _$react.Context<_$react.ReactNode>;
+declare const Outlet: React.FC;
+//#endregion
+//#region src/client/router/renderer.d.ts
+interface RouteBranchMatch {
+  route: RouteRecord;
+  params: Record<string, string>;
+}
+declare function matchRouteBranchWithParams(routes: RouteRecord[], pathname: string, basename?: string): RouteBranchMatch[];
+declare function matchRouteBranch(routes: RouteRecord[], pathname: string, basename?: string): RouteRecord[];
+declare function resolveRouteBranch(branch: RouteRecord[]): Promise<RouteRecord[]>;
+declare const RouteRenderer: React$1.FC<RouteRendererProps>;
+//#endregion
+//#region src/client/router/utils.d.ts
+declare function normalizeBasename(basename?: string): string;
+declare function hasBasename(path: string, basename: string): boolean;
+declare function stripBasename(path: string, basename: string): string;
+declare function addBasename(path: string, basename: string): string;
+//#endregion
+//#region src/client/router/url-contract.d.ts
+type UrlRouteKind = 'doc' | 'external' | 'collection';
+interface UrlContractConfig {
+  base?: string;
+  i18n?: Pick<BoltdocsI18nConfig, 'defaultLocale' | 'locales'>;
+  versions?: Pick<BoltdocsVersionsConfig, 'defaultVersion' | 'prefix' | 'versions'>;
+  collections?: readonly string[] | BoltdocsCollectionsConfig;
+}
+interface UrlRouteHint {
+  path: string;
+  kind?: UrlRouteKind;
+  collection?: string;
+}
+interface ParsedUrl {
+  /** The normalized pathname, without query string or hash. */
+  pathname: string;
+  /** The normalized route content after removing structural prefixes. */
+  routePath: string;
+  /** Query string including `?`, when present. */
+  search: string;
+  /** Hash including `#`, when present. */
+  hash: string;
+  kind: UrlRouteKind;
+  locale?: string;
+  version?: string;
+  collection?: string;
+  /** Whether the input used the explicit `site:` protocol. */
+  siteProtocol: boolean;
+  /** Whether the input pathname contained the configured documentation base. */
+  hadBase: boolean;
+}
+interface BuildUrlOptions {
+  kind: UrlRouteKind;
+  /** Route content, e.g. `/guides/start`, `/about`, or `/my-post`. */
+  path?: string;
+  locale?: string;
+  version?: string;
+  collection?: string;
+  search?: string;
+  hash?: string;
+  /** The input pathname already contained the configured base. */
+  hadBase?: boolean;
+}
+interface ResolveUrlOptions {
+  /** Explicitly choose the route family when the path is ambiguous. */
+  kind?: UrlRouteKind;
+  /** Known route metadata used to classify paths outside `base`. */
+  routes?: readonly UrlRouteHint[];
+  /** Locale/version to apply when building a canonical target. */
+  locale?: string;
+  version?: string;
+}
+declare function normalizeUrlBase(base?: string): string;
+declare function normalizeUrlPath(path: string): string;
+declare function hasUrlBase(pathname: string, base?: string): boolean;
+declare function stripUrlBase(pathname: string, base?: string): string;
+declare function addUrlBase(pathname: string, base?: string): string;
+declare function getConfiguredLocales(config: UrlContractConfig): string[];
+declare function getConfiguredVersions(config: UrlContractConfig): string[];
+declare function getVersionPrefixSegments(config: UrlContractConfig): string[];
+declare function getVersionSegments(version: string | undefined, config: UrlContractConfig): string[];
+declare function isConfiguredLocale(value: string | undefined, config: UrlContractConfig): value is string;
+declare function isConfiguredVersion(value: string | undefined, config: UrlContractConfig): value is string;
+declare function splitUrlReference(to: string): {
+  pathname: string;
+  search: string;
+  hash: string;
+};
+declare function stripSiteProtocol(to: string): {
+  value: string;
+  siteProtocol: boolean;
+};
+/** Returns true for URI schemes such as `mailto:`, `tel:`, or `data:`. */
+declare function hasUriScheme(value: string): boolean;
+declare function classifyUrlPath(pathname: string, config: UrlContractConfig, options?: Pick<ResolveUrlOptions, 'kind' | 'routes'>): UrlRouteKind;
+declare function parseUrlReference(to: string, config: UrlContractConfig, options?: Pick<ResolveUrlOptions, 'kind' | 'routes'>): ParsedUrl;
+declare function buildUrl(options: BuildUrlOptions, config: UrlContractConfig): string;
+declare function resolveUrlReference(to: string, config: UrlContractConfig, options?: ResolveUrlOptions): string;
+//#endregion
+export { LazyRouteResult as $, matchRouteBranch as A, useRouteData as B, stripSiteProtocol as C, normalizeBasename as D, hasBasename as E, useLoaderData as F, MatchesContext as G, LocationProvider as H, useLocation as I, PrefetchContext as J, NavigateContext as K, useMatches as L, resolveRouteBranch as M, Outlet as N, stripBasename as O, OutletContext as P, CreateRoutesResult as Q, useNavigate as R, splitUrlReference as S, addBasename as T, LocationProviderProps as U, LocationContext as V, LocationState as W, RouteDataContext as X, PrefetchFunction as Y, defaultNavigate as Z, isConfiguredVersion as _, RedirectConfig as _t, UrlRouteHint as a, RouterOptions as at, parseUrlReference as b, buildUrl as c, BoltdocsIntegrationsConfig as ct, getConfiguredVersions as d, BoltdocsRoutePath as dt, LoaderFunction as et, getVersionPrefixSegments as f, BoltdocsRoutePathWithFallback as ft, isConfiguredLocale as g, JsonLdObject as gt, hasUrlBase as h, BoltdocsVersion as ht, UrlContractConfig as i, RouteRendererProps as it, matchRouteBranchWithParams as j, RouteRenderer as k, classifyUrlPath as l, BoltdocsLocale as lt, hasUriScheme as m, BoltdocsTypes as mt, ParsedUrl as n, RouteMatch as nt, UrlRouteKind as o, BadgeValue as ot, getVersionSegments as p, BoltdocsSocialLink as pt, NavigateFunction as q, ResolveUrlOptions as r, RouteRecord as rt, addUrlBase as s, BoltdocsConfig as st, BuildUrlOptions as t, LoaderFunctionArgs as tt, getConfiguredLocales as u, BoltdocsMdxComponents as ut, normalizeUrlBase as v, RedirectStatus as vt, stripUrlBase as w, resolveUrlReference as x, normalizeUrlPath as y, StructuredData as yt, usePrefetch as z };