dumi 2.4.29 → 2.4.30

package/dist/loaders/markdown/transformer/remarkEmbed.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+import type { Transformer } from 'unified';
+import type { IMdTransformerOptions } from '.';
+export default function remarkEmbed(opts: Pick<IMdTransformerOptions, 'fileAbsPath' | 'alias'>): Transformer<Root>;

package/dist/loaders/markdown/transformer/remarkMeta.d.ts

@@ -0,0 +1,8 @@
+import type { Root } from 'mdast';
+import type { Transformer } from 'unified';
+import type { IMdTransformerOptions } from '.';
+type IRemarkMetaOpts = Pick<IMdTransformerOptions, 'cwd' | 'fileAbsPath' | 'resolve'> & {
+    fileLocaleLessPath: string;
+};
+export default function remarkMeta(opts: IRemarkMetaOpts): Transformer<Root>;
+export {};

package/dist/loaders/null/index.d.ts

@@ -0,0 +1,2 @@
+export default function loader(): string;
+export declare function pitch(): string;

package/dist/loaders/page/index.d.ts

@@ -0,0 +1 @@
+export default function pageMetaLoader(this: any, raw: string): string;

package/dist/loaders/post-raw/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * loader for mako dumi-raw watch-parent
+ */
+export default function postRawLoader(this: any, raw: string): string;

package/dist/loaders/pre-raw/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * loader for discard frontmatter from code file content
+ */
+export default function preRawLoader(this: any, raw: string): string;

package/dist/preset.d.ts

@@ -0,0 +1,5 @@
+import type { IApi } from "./types";
+declare const _default: (api: IApi) => {
+    plugins: string[];
+};
+export default _default;

package/dist/registerMethods.d.ts

@@ -0,0 +1,3 @@
+import type { IApi } from './types';
+declare const _default: (api: IApi) => void;
+export default _default;

package/dist/service/cli.d.ts

@@ -0,0 +1,5 @@
+interface IOpts {
+    presets?: string[];
+}
+export declare function run(opts?: IOpts): Promise<void>;
+export {};

package/dist/service/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const MIN_NODE_VERSION = 14;
+export declare const DEV_COMMAND = "dev";
+export declare const DEFAULT_CONFIG_FILES: string[];
+export declare const FRAMEWORK_NAME = "dumi";

package/dist/service/dev.d.ts

@@ -0,0 +1 @@
+export declare function dev(): void;

package/dist/service/forkedDev.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/service/printHelp.d.ts

@@ -0,0 +1 @@
+export declare function printHelp(): void;

package/dist/service/service.d.ts

@@ -0,0 +1,13 @@
+import { Service } from 'umi';
+export declare class DumiService extends Service {
+    constructor();
+    getPaths(): Promise<{
+        cwd: string;
+        absSrcPath: string;
+        absPagesPath: string;
+        absApiRoutesPath: string;
+        absTmpPath: string;
+        absNodeModulesPath: string;
+        absOutputPath: string;
+    }>;
+}

package/dist/techStacks/react.d.ts

@@ -0,0 +1,7 @@
+import type { IDumiTechStack } from "../types";
+export default class ReactTechStack implements IDumiTechStack {
+    name: string;
+    runtimeOpts?: IDumiTechStack['runtimeOpts'];
+    isSupported(...[, lang]: Parameters<IDumiTechStack['isSupported']>): boolean;
+    transformCode(...[raw, opts]: Parameters<IDumiTechStack['transformCode']>): string;
+}

package/dist/techStacks/utils.d.ts

@@ -0,0 +1,40 @@
+import type { ParserConfig } from '@swc/core';
+import { IDumiTechStack } from '../types';
+export { IDumiTechStack, IDumiTechStackOnBlockLoadArgs, IDumiTechStackOnBlockLoadResult, IDumiTechStackRuntimeOpts, } from '../types';
+/**
+ * for frameworks like vue , we need to extract the JS fragments in their scripts
+ * @param htmlLike HTML, vue and other html-like files are available
+ * @returns js/ts code
+ */
+export declare function extractScript(htmlLike: string): string;
+export interface IWrapDemoWithFnOptions {
+    filename: string;
+    parserConfig: ParserConfig;
+}
+/**
+ * Use swc to convert es module into async function.
+ * More transform process detail, refer to:
+ * https://github.com/umijs/dumi/blob/master/crates/swc_plugin_react_demo/src/lib.rs#L126
+ */
+export declare function wrapDemoWithFn(code: string, opts: IWrapDemoWithFnOptions): string;
+export type IDefineTechStackOptions = IDumiTechStack;
+/**
+ * Define a tech stack
+ * @param options techstack options
+ * @returns function that returns {@link IDumiTechStack}, can be used to register a techstack
+ *
+ * @example
+ * const ReactTechStack = defineTechStack({
+ *   name: 'jsx',
+ *   isSupported(_, lang) {
+ *     return ['jsx', 'tsx'].includes(lang);
+ *   },
+ *   transformCode() {
+ *     // ...
+ *     return '';
+ *   },
+ * });
+ *
+ * api.registerTechStack(() => ReactTechStack);
+ */
+export declare function defineTechStack(options: IDefineTechStackOptions): IDumiTechStack;

package/dist/types.d.ts

@@ -0,0 +1,159 @@
+import type { BaseAtomAssetsParser as IAtomAssetsParser } from "./assetParsers/BaseParser";
+import type { IParsedBlockAsset } from "./assetParsers/block";
+import type { IDumiDemoProps } from "./client/theme-api/DumiDemo";
+import type { ILocalesConfig, IThemeConfig } from "./client/theme-api/types";
+import type { IContentTab } from "./features/tabs";
+import type { IThemeLoadResult } from "./features/theme/loader";
+import { OnLoadArgs, OnLoadResult } from '@umijs/bundler-utils/compiled/esbuild';
+import type { IModify } from '@umijs/core';
+import type { AssetsPackage, ExampleBlockAsset } from 'dumi-assets-types';
+import type { Element } from 'hast';
+import type { IApi as IUmiApi, defineConfig as defineUmiConfig } from 'umi';
+type Subset<K> = {
+    [attr in keyof K]?: K[attr] extends Array<any> ? K[attr] : K[attr] extends Function | undefined ? K[attr] : K[attr] extends object ? Subset<K[attr]> : K[attr] extends object | null ? Subset<K[attr]> | null : K[attr] extends object | null | undefined ? Subset<K[attr]> | null | undefined : K[attr];
+};
+type NoStringIndex<T> = {
+    [K in keyof T as string extends K ? never : K]: T[K];
+};
+type IUmiConfig = Omit<NoStringIndex<Parameters<typeof defineUmiConfig>[0]>, 'resolve' | 'extraRemarkPlugins' | 'extraRehypePlugins' | 'themeConfig'>;
+interface IDumiExtendsConfig {
+    resolve: {
+        docDirs: (string | {
+            type?: string;
+            dir: string;
+        })[];
+        atomDirs: {
+            type: string;
+            subType?: string;
+            dir: string;
+        }[];
+        codeBlockMode: 'active' | 'passive';
+        entryFile?: string;
+        forceKebabCaseRouting: boolean;
+    };
+    locales: ILocalesConfig;
+    themeConfig: IThemeConfig;
+    autoAlias?: boolean;
+    /**
+     * extra unified plugins
+     */
+    extraRemarkPlugins?: (string | Function | [string | Function, object])[];
+    extraRehypePlugins?: (string | Function | [string | Function, object])[];
+}
+export type IDumiConfig = Omit<IUmiConfig, 'locales'> & IDumiExtendsConfig;
+export type IDumiUserConfig = Subset<Omit<IDumiConfig, 'locales'>> & {
+    locales?: Exclude<IDumiConfig['locales'][0], {
+        base: string;
+    }>[] | Omit<Exclude<IDumiConfig['locales'][0], {
+        suffix: string;
+    }>, 'base'>[];
+    [key: string]: any;
+};
+export interface IDumiTechStackOnBlockLoadResult {
+    content: string;
+    type: Required<OnLoadResult>['loader'];
+}
+export type IDumiTechStackOnBlockLoadArgs = OnLoadArgs & {
+    entryPointCode: string;
+    filename: string;
+};
+export interface IDumiTechStackRuntimeOpts {
+    /**
+     * Component detection function path,
+     * used to detect errors that occur from application creation to component mounting.
+     */
+    preflightPath?: string;
+    /**
+     * path of the cancelable{@link IDemoCancelableFn} function
+     * that manipulate(mount/unmount) third-party framework component
+     */
+    rendererPath?: string;
+    /**
+     * path to runtime compile function module
+     */
+    compilePath?: string;
+    /**
+     * path to runtime plugin for this tech stack
+     */
+    pluginPath?: string;
+}
+export declare abstract class IDumiTechStack {
+    /**
+     * tech stack name, such as 'react'
+     */
+    abstract name: string;
+    /**
+     * runtime options
+     */
+    abstract runtimeOpts?: IDumiTechStackRuntimeOpts;
+    /**
+     * Is the lang supported by the current tech stack?
+     * @param lang
+     * @param node hast Element https://github.com/syntax-tree/hast?tab=readme-ov-file#element
+     */
+    abstract isSupported(node: Element, lang: string): boolean;
+    /**
+     * transform for parse demo source to expression/function/class
+     */
+    abstract transformCode(raw: string, opts: {
+        type: 'external' | 'code-block';
+        fileAbsPath: string;
+    }): string;
+    /**
+     * generator for return asset metadata
+     */
+    abstract generateMetadata?(asset: ExampleBlockAsset, opts: {
+        type: Parameters<IDumiTechStack['transformCode']>[1]['type'];
+        mdAbsPath: string;
+        fileAbsPath?: string;
+        entryPointCode?: string;
+    }): Promise<ExampleBlockAsset> | ExampleBlockAsset;
+    /**
+     * generator for return previewer props
+     */
+    abstract generatePreviewerProps?(props: IDumiDemoProps['previewerProps'], opts: Parameters<NonNullable<IDumiTechStack['generateMetadata']>>[1]): Promise<IDumiDemoProps['previewerProps']> | IDumiDemoProps['previewerProps'];
+    /**
+     * generator for return file path of demo source
+     */
+    abstract generateSources?(source: IParsedBlockAsset['resolveMap'], opts: Parameters<NonNullable<IDumiTechStack['generateMetadata']>>[1]): Promise<IParsedBlockAsset['resolveMap']> | IParsedBlockAsset['resolveMap'];
+    /**
+     * Use current function as onLoad CallBack(https://esbuild.github.io/plugins/#on-load)
+     * @description
+     * Why use this method?
+     * By default, dumi can only support the parsing of js/ts related code blocks,
+     * but many front-end frameworks have custom extensions,
+     * so this method is provided to facilitate developers to convert codes.
+     */
+    abstract onBlockLoad?(args: IDumiTechStackOnBlockLoadArgs): IDumiTechStackOnBlockLoadResult | null;
+}
+export type IApi = IUmiApi & {
+    config: IDumiConfig & {
+        [key: string]: any;
+    };
+    userConfig: IDumiUserConfig;
+    service: IUmiApi['service'] & {
+        themeData: IThemeLoadResult;
+        atomParser: IAtomAssetsParser;
+    };
+    /**
+     * register a new tech stack
+     */
+    registerTechStack: (fn: () => IDumiTechStack) => void;
+    /**
+     * modify original theme data
+     */
+    modifyTheme: IModify<IThemeLoadResult, null>;
+    /**
+     * add content tab
+     */
+    addContentTab: (fn: () => IContentTab) => void;
+    /**
+     * modify assets metadata
+     */
+    modifyAssetsMetadata: IModify<AssetsPackage, null>;
+    /**
+     * get assets metadata
+     */
+    getAssetsMetadata?: () => Promise<AssetsPackage>;
+};
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,67 @@
+/// <reference types="node" />
+import type { Range, RangeOptions } from '@umijs/utils/compiled/semver';
+import Cache from 'file-system-cache';
+import type { RunLoaderOption as InternalRunLoaderOption, RunLoaderResult } from '../compiled/loader-runner';
+export type * from '../compiled/loader-runner';
+export { getContext } from '../compiled/loader-runner';
+/**
+ * get route path from file-system path
+ */
+export declare function getFileIdFromFsPath(fsPath: string): string;
+/**
+ * get range lines of markdown file
+ */
+export declare const getFileRangeLines: (content: string, range: string) => string;
+/**
+ * get file content by regular expression
+ * @param content   source file content
+ * @param regexp    regular expression string
+ * @param filePath  source file path
+ */
+export declare const getFileContentByRegExp: (content: string, regexp: string, filePath: string) => string;
+/**
+ * parse frontmatter from code string,
+ * also supports html/xml comments
+ */
+export declare function parseCodeFrontmatter(raw: string): {
+    code: string;
+    frontmatter: Record<string, any> | null;
+};
+declare const caches: Record<string, ReturnType<typeof Cache>>;
+export declare function _setFSCacheDir(dir: string): void;
+export declare function getCache(ns: string): (typeof caches)['0'];
+/**
+ * try to get father config
+ */
+export declare function tryFatherBuildConfigs(cwd: string): Promise<any[]>;
+/**
+ * get root dir for monorepo project
+ */
+export declare function getProjectRoot(cwd: string): string;
+/**
+ *
+ * transform component into webpack chunkName
+ * @export
+ * @param {string} component component path
+ * @param {string} [cwdPath] current root path
+ * @return {*}  {string}
+ */
+export declare function componentToChunkName(component: string, cwdPath?: string): string;
+export declare function generateMetaChunkName(path: string, cwd: string, locales?: string[]): string;
+/**
+ * generate hash for string
+ */
+export declare function getContentHash(content: string, length?: number): string;
+export type RunLoaderOption = Partial<InternalRunLoaderOption>;
+export declare function runLoaders(options: RunLoaderOption): Promise<RunLoaderResult>;
+export declare function runLoaders(options: RunLoaderOption, callback: undefined): Promise<RunLoaderResult>;
+export declare function runLoaders(options: RunLoaderOption, callback: (err: NodeJS.ErrnoException | null, result: RunLoaderResult) => any): void;
+/**
+ * check if version is in range
+ */
+export declare function isVersionInRange(version: string, range: string | Range, options?: RangeOptions): boolean;
+/**
+ * normalize module specifier for generated import/export statements
+ * keep package/bare specifiers unchanged and normalize path separators
+ */
+export declare function toImportSpecifier(source: string): string;

package/dumi-types.d.ts

@@ -0,0 +1,115 @@
+import type {
+  OnLoadArgs,
+  OnLoadResult,
+} from '@umijs/bundler-utils/compiled/esbuild';
+import type { IModify } from '@umijs/core';
+import type { AssetsPackage, ExampleBlockAsset } from 'dumi-assets-types';
+import type { Element } from 'hast';
+import type { IApi as IUmiApi, defineConfig as defineUmiConfig } from 'umi';
+import type { IDumiDemoProps, ILocalesConfig, IThemeConfig } from './theme-api';
+
+type Subset<K> = {
+  [attr in keyof K]?: K[attr] extends Array<any>
+    ? K[attr]
+    : K[attr] extends (...args: any[]) => any | undefined
+    ? K[attr]
+    : K[attr] extends object
+    ? Subset<K[attr]>
+    : K[attr] extends object | null
+    ? Subset<K[attr]> | null
+    : K[attr] extends object | null | undefined
+    ? Subset<K[attr]> | null | undefined
+    : K[attr];
+};
+type NoStringIndex<T> = {
+  [K in keyof T as string extends K ? never : K]: T[K];
+};
+type IUmiConfig = Omit<
+  NoStringIndex<Parameters<typeof defineUmiConfig>[0]>,
+  'resolve' | 'extraRemarkPlugins' | 'extraRehypePlugins' | 'themeConfig'
+>;
+type UnifiedPluginConfig =
+  | string
+  | ((...args: any[]) => any)
+  | [string | ((...args: any[]) => any), object];
+
+export interface IDumiExtendsConfig {
+  resolve: {
+    docDirs: (string | { type?: string; dir: string })[];
+    atomDirs: { type: string; subType?: string; dir: string }[];
+    codeBlockMode: 'active' | 'passive';
+    entryFile?: string;
+    forceKebabCaseRouting: boolean;
+  };
+  locales: ILocalesConfig;
+  themeConfig: IThemeConfig;
+  autoAlias?: boolean;
+  extraRemarkPlugins?: UnifiedPluginConfig[];
+  extraRehypePlugins?: UnifiedPluginConfig[];
+}
+
+export type IDumiConfig = Omit<IUmiConfig, 'locales'> & IDumiExtendsConfig;
+export type IDumiUserConfig = Subset<Omit<IDumiConfig, 'locales'>> & {
+  locales?:
+    | Exclude<IDumiConfig['locales'][0], { base: string }>[]
+    | Omit<Exclude<IDumiConfig['locales'][0], { suffix: string }>, 'base'>[];
+  [key: string]: any;
+};
+export interface IDumiTechStackOnBlockLoadResult {
+  content: string;
+  type: Required<OnLoadResult>['loader'];
+}
+export type IDumiTechStackOnBlockLoadArgs = OnLoadArgs & {
+  entryPointCode: string;
+  filename: string;
+};
+export interface IDumiTechStackRuntimeOpts {
+  preflightPath?: string;
+  rendererPath?: string;
+  compilePath?: string;
+  pluginPath?: string;
+}
+export abstract class IDumiTechStack {
+  abstract name: string;
+  abstract runtimeOpts?: IDumiTechStackRuntimeOpts;
+  abstract isSupported(node: Element, lang: string): boolean;
+  abstract transformCode(
+    raw: string,
+    opts: { type: 'external' | 'code-block'; fileAbsPath: string },
+  ): string;
+  abstract generateMetadata?(
+    asset: ExampleBlockAsset,
+    opts: {
+      type: Parameters<IDumiTechStack['transformCode']>[1]['type'];
+      mdAbsPath: string;
+      fileAbsPath?: string;
+      entryPointCode?: string;
+    },
+  ): Promise<ExampleBlockAsset> | ExampleBlockAsset;
+  abstract generatePreviewerProps?(
+    props: IDumiDemoProps['previewerProps'],
+    opts: Parameters<NonNullable<IDumiTechStack['generateMetadata']>>[1],
+  ):
+    | Promise<IDumiDemoProps['previewerProps']>
+    | IDumiDemoProps['previewerProps'];
+  abstract generateSources?(
+    source: Record<string, string>,
+    opts: Parameters<NonNullable<IDumiTechStack['generateMetadata']>>[1],
+  ): Promise<Record<string, string>> | Record<string, string>;
+  abstract onBlockLoad?(
+    args: IDumiTechStackOnBlockLoadArgs,
+  ): IDumiTechStackOnBlockLoadResult | null;
+}
+export type IApi = IUmiApi & {
+  config: IDumiConfig & { [key: string]: any };
+  userConfig: IDumiUserConfig;
+  service: IUmiApi['service'] & {
+    themeData: any;
+    atomParser: any;
+  };
+  registerTechStack: (fn: () => IDumiTechStack) => void;
+  modifyTheme: IModify<any, null>;
+  addContentTab: (fn: () => any) => void;
+  modifyAssetsMetadata: IModify<AssetsPackage, null>;
+  getAssetsMetadata?: () => Promise<AssetsPackage>;
+};

package/index.d.ts

@@ -1,11 +1,70 @@
-export * from '@@/dumi/exports';
+import type { IRouteMeta, IRoutesById } from './theme-api';
+
 export { Root as HastRoot } from 'hast';
 export * from 'umi';
 export {
   Plugin as UnifiedPlugin,
   Transformer as UnifiedTransformer,
 } from 'unified';
-export * from './dist';
-// override umi exported defineConfig
-export { defineConfig } from './dist';
-export { IApi } from './dist/types';
+export type {
+  IApi,
+  IDumiConfig,
+  IDumiTechStack,
+  IDumiTechStackOnBlockLoadArgs,
+  IDumiTechStackOnBlockLoadResult,
+  IDumiTechStackRuntimeOpts,
+  IDumiUserConfig,
+} from './dumi-types';
+export * from './theme-api';
+
+export declare enum ApplyPluginsType {
+  add = 'add',
+  modify = 'modify',
+  event = 'event',
+  compose = 'compose',
+}
+export declare class PluginManager {
+  static create(opts: Record<string, any>): PluginManager;
+  applyPlugins(opts: Record<string, any>): any;
+  [key: string]: any;
+}
+
+export declare const getSketchJSON: (
+  element: Element,
+  opts: Record<string, any>,
+) => Promise<Record<string, any>>;
+export declare const history: {
+  location: Location;
+  push(to: string | Record<string, any>): void;
+  replace(to: string | Record<string, any>): void;
+  listen(listener: (...args: any[]) => void): () => void;
+  [key: string]: any;
+};
+export declare const Helmet: any;
+export declare const Link: any;
+export declare const NavLink: any;
+export declare const matchRoutes: (...args: any[]) => any;
+export declare const useAppData: () => {
+  clientRoutes: any[];
+  routes: IRoutesById;
+  [key: string]: any;
+};
+export declare const useLocation: () => Location & Record<string, any>;
+export declare const useOutlet: () => any;
+export declare const useParams: () => Record<string, string | undefined>;
+export declare const useRouteData: () => {
+  route: { path?: string; meta?: IRouteMeta; [key: string]: any };
+  [key: string]: any;
+};
+export declare const useSearchParams: () => [
+  URLSearchParams,
+  (...args: any[]) => void,
+];
+
+export declare let unistUtilVisit: typeof import('unist-util-visit');
+export declare const getProjectRoot: (cwd: string) => string;
+export declare const defineConfig: <
+  T extends import('./dumi-types').IDumiUserConfig,
+>(
+  config: T,
+) => T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dumi",
-  "version": "2.4.29",
+  "version": "2.4.30",
   "description": "📖 Documentation Generator of React Component",
   "keywords": [
     "generator",
@@ -30,7 +30,10 @@
     "dist",
     "compiled",
     "theme-default",
+    "dumi-types.d.ts",
     "index.d.ts",
+    "theme-api.d.ts",
+    "theme-modules.d.ts",
     "plugin-utils.js",
     "plugin-utils.d.ts",
     "tech-stack-utils.js",