@docusaurus/types 2.0.0-beta.20 → 2.0.0-beta.22

package/src/plugin.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {TranslationFile} from './i18n';
+import type {RuleSetRule, Configuration as WebpackConfiguration} from 'webpack';
+import type {CustomizeRuleString} from 'webpack-merge/dist/types';
+import type {CommanderStatic} from 'commander';
+import type Joi from 'joi';
+import type {HelmetServerState} from 'react-helmet-async';
+import type {ThemeConfig} from './config';
+import type {LoadContext, Props} from './context';
+import type {SwizzleConfig} from './swizzle';
+import type {RouteConfig} from './routing';
+
+export type PluginOptions = {id?: string} & {[key: string]: unknown};
+
+export type PluginConfig =
+  | string
+  | [string, PluginOptions]
+  | [PluginModule, PluginOptions]
+  | PluginModule
+  | false
+  | null;
+
+export type PresetConfig =
+  | string
+  | [string, {[key: string]: unknown}]
+  | false
+  | null;
+
+/**
+ * - `type: 'package'`, plugin is in a different package.
+ * - `type: 'project'`, plugin is in the same docusaurus project.
+ * - `type: 'local'`, none of the plugin's ancestor directories contains a
+ * package.json.
+ * - `type: 'synthetic'`, docusaurus generated internal plugin.
+ */
+export type PluginVersionInformation =
+  | {
+      readonly type: 'package';
+      readonly name?: string;
+      readonly version?: string;
+    }
+  | {readonly type: 'project'}
+  | {readonly type: 'local'}
+  | {readonly type: 'synthetic'};
+
+export type PluginContentLoadedActions = {
+  addRoute: (config: RouteConfig) => void;
+  createData: (name: string, data: string) => Promise<string>;
+  setGlobalData: (data: unknown) => void;
+};
+
+export type ConfigureWebpackUtils = {
+  getStyleLoaders: (
+    isServer: boolean,
+    cssOptions: {[key: string]: unknown},
+  ) => RuleSetRule[];
+  getJSLoader: (options: {
+    isServer: boolean;
+    babelOptions?: {[key: string]: unknown};
+  }) => RuleSetRule;
+};
+
+export type AllContent = {
+  [pluginName: string]: {
+    [pluginID: string]: unknown;
+  };
+};
+
+// TODO improve type (not exposed by postcss-loader)
+export type PostCssOptions = {plugins: unknown[]; [key: string]: unknown};
+
+export type ValidationSchema<T> = Joi.ObjectSchema<T>;
+
+export type Validate<In, Out> = (
+  validationSchema: ValidationSchema<Out>,
+  options: In,
+) => Out;
+
+export type OptionValidationContext<In, Out> = {
+  validate: Validate<In, Out>;
+  options: In;
+};
+
+export type ThemeConfigValidationContext<In, Out = In> = {
+  validate: Validate<In, Out>;
+  themeConfig: In;
+};
+
+export type HtmlTagObject = {
+  /**
+   * Attributes of the html tag.
+   * E.g. `{ disabled: true, value: "demo", rel: "preconnect" }`
+   */
+  attributes?: Partial<{[key: string]: string | boolean}>;
+  /** The tag name, e.g. `div`, `script`, `link`, `meta` */
+  tagName: string;
+  /** The inner HTML */
+  innerHTML?: string;
+};
+
+export type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
+
+export type Plugin<Content = unknown> = {
+  name: string;
+  loadContent?: () => Promise<Content> | Content;
+  contentLoaded?: (args: {
+    /** The content loaded by this plugin instance */
+    content: Content; //
+    /** Content loaded by ALL the plugins */
+    allContent: AllContent;
+    actions: PluginContentLoadedActions;
+  }) => Promise<void> | void;
+  postBuild?: (
+    props: Props & {
+      content: Content;
+      head: {[location: string]: HelmetServerState};
+    },
+  ) => Promise<void> | void;
+  // TODO refactor the configureWebpack API surface: use an object instead of
+  // multiple params (requires breaking change)
+  configureWebpack?: (
+    config: WebpackConfiguration,
+    isServer: boolean,
+    utils: ConfigureWebpackUtils,
+    content: Content,
+  ) => WebpackConfiguration & {
+    mergeStrategy?: {
+      [key: string]: CustomizeRuleString;
+    };
+  };
+  configurePostCss?: (options: PostCssOptions) => PostCssOptions;
+  getThemePath?: () => string;
+  getTypeScriptThemePath?: () => string;
+  getPathsToWatch?: () => string[];
+  getClientModules?: () => string[];
+  extendCli?: (cli: CommanderStatic) => void;
+  injectHtmlTags?: (args: {content: Content}) => {
+    headTags?: HtmlTags;
+    preBodyTags?: HtmlTags;
+    postBodyTags?: HtmlTags;
+  };
+  // TODO before/afterDevServer implementation
+
+  // translations
+  getTranslationFiles?: (args: {
+    content: Content;
+  }) => Promise<TranslationFile[]> | TranslationFile[];
+  getDefaultCodeTranslationMessages?: () =>
+    | Promise<{[id: string]: string}>
+    | {[id: string]: string};
+  translateContent?: (args: {
+    /** The content loaded by this plugin instance. */
+    content: Content;
+    translationFiles: TranslationFile[];
+  }) => Content;
+  translateThemeConfig?: (args: {
+    themeConfig: ThemeConfig;
+    translationFiles: TranslationFile[];
+  }) => ThemeConfig;
+};
+
+export type InitializedPlugin = Plugin & {
+  readonly options: Required<PluginOptions>;
+  readonly version: PluginVersionInformation;
+  /** The absolute path to the folder containing the entry point file. */
+  readonly path: string;
+};
+
+export type LoadedPlugin = InitializedPlugin & {
+  readonly content: unknown;
+};
+
+export type PluginModule = {
+  (context: LoadContext, options: unknown): Plugin | Promise<Plugin>;
+  validateOptions?: <T, U>(data: OptionValidationContext<T, U>) => U;
+  validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;
+
+  getSwizzleComponentList?: () => string[] | undefined; // TODO deprecate this one later
+  getSwizzleConfig?: () => SwizzleConfig | undefined;
+};
+
+export type Preset = {
+  plugins?: PluginConfig[];
+  themes?: PluginConfig[];
+};
+
+export type PresetModule = {
+  (context: LoadContext, presetOptions: unknown): Preset;
+};

package/src/routing.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ParsedUrlQueryInput} from 'querystring';
+
+/**
+ * A "module" represents a unit of serialized data emitted from the plugin. It
+ * will be imported on client-side and passed as props, context, etc.
+ *
+ * If it's a string, it's a file path that Webpack can `require`; if it's
+ * an object, it can also contain `query` or other metadata.
+ */
+export type Module =
+  | {
+      /**
+       * A marker that tells the route generator this is an import and not a
+       * nested object to recurse.
+       */
+      __import?: boolean;
+      path: string;
+      query?: ParsedUrlQueryInput;
+    }
+  | string;
+
+/**
+ * Represents the data attached to each route. Since the routes.js is a
+ * monolithic data file, any data (like props) should be serialized separately
+ * and registered here as file paths (a {@link Module}), so that we could
+ * code-split.
+ */
+export type RouteModules = {
+  [propName: string]: Module | RouteModules | RouteModules[];
+};
+
+/**
+ * Represents a "slice" of the final route structure returned from the plugin
+ * `addRoute` action.
+ */
+export type RouteConfig = {
+  /** With leading slash. Trailing slash will be normalized by config. */
+  path: string;
+  /** Component used to render this route, a path that Webpack can `require`. */
+  component: string;
+  /**
+   * Props. Each entry should be `[propName]: pathToPropModule` (created with
+   * `createData`)
+   */
+  modules?: RouteModules;
+  /**
+   * The route context will wrap the `component`. Use `useRouteContext` to
+   * retrieve what's declared here. Note that all custom route context declared
+   * here will be namespaced under {@link RouteContext.data}.
+   */
+  context?: RouteModules;
+  /** Nested routes config. */
+  routes?: RouteConfig[];
+  /** React router config option: `exact` routes would not match subroutes. */
+  exact?: boolean;
+  /** Used to sort routes. Higher-priority routes will be placed first. */
+  priority?: number;
+  /** Extra props; will be copied to routes.js. */
+  [propName: string]: unknown;
+};
+
+export type RouteContext = {
+  /**
+   * Plugin-specific context data.
+   */
+  data?: object | undefined;
+};
+
+/**
+ * Top-level plugin routes automatically add some context data to the route.
+ * This permits us to know which plugin is handling the current route.
+ */
+export type PluginRouteContext = RouteContext & {
+  plugin: {
+    id: string;
+    name: string;
+  };
+};
+
+/**
+ * The shape would be isomorphic to {@link RouteModules}:
+ * {@link Module} -> `string`, `RouteModules[]` -> `ChunkNames[]`.
+ *
+ * Each `string` chunk name will correlate with one key in the {@link Registry}.
+ */
+export type ChunkNames = {
+  [propName: string]: string | ChunkNames | ChunkNames[];
+};
+
+/**
+ * A map from route paths (with a hash) to the chunk names of each module, which
+ * the bundler will collect.
+ *
+ * Chunk keys are routes with a hash, because 2 routes can conflict with each
+ * other if they have the same path, e.g.: parent=/docs, child=/docs
+ *
+ * @see https://github.com/facebook/docusaurus/issues/2917
+ */
+export type RouteChunkNames = {
+  [routePathHashed: string]: ChunkNames;
+};
+
+/**
+ * Each key is the chunk name, which you can get from `routeChunkNames` (see
+ * {@link RouteChunkNames}). The values are the opts data that react-loadable
+ * needs. For example:
+ *
+ * ```js
+ * const options = {
+ *   optsLoader: {
+ *     component: () => import('./Pages.js'),
+ *     content.foo: () => import('./doc1.md'),
+ *   },
+ *   optsModules: ['./Pages.js', './doc1.md'],
+ *   optsWebpack: [
+ *     require.resolveWeak('./Pages.js'),
+ *     require.resolveWeak('./doc1.md'),
+ *   ],
+ * }
+ * ```
+ *
+ * @see https://github.com/jamiebuilds/react-loadable#declaring-which-modules-are-being-loaded
+ */
+export type Registry = {
+  readonly [chunkName: string]: [
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Loader: () => Promise<any>,
+    ModuleName: string,
+    ResolvedModuleName: string,
+  ];
+};

package/src/swizzle.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {JSXElementConstructor} from 'react';
+
+export type SwizzleAction = 'eject' | 'wrap';
+export type SwizzleActionStatus = 'safe' | 'unsafe' | 'forbidden';
+
+export type SwizzleComponentConfig = {
+  actions: {[action in SwizzleAction]: SwizzleActionStatus};
+  description?: string;
+};
+
+export type SwizzleConfig = {
+  components: {[componentName: string]: SwizzleComponentConfig};
+  // Other settings could be added here, like the ability to declare the config
+  // as exhaustive so that we can emit errors
+};
+
+/**
+ * This type is almost the same as `React.ComponentProps`, but with one minor
+ * fix: when the component is a function with no parameters, it produces `{}`
+ * instead of `unknown`, allowing us to spread the props derived from another
+ * component. This is useful for wrap swizzling.
+ *
+ * @see https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/60766
+ */
+export type WrapperProps<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends keyof JSX.IntrinsicElements | JSXElementConstructor<any>,
+> = T extends JSXElementConstructor<infer P>
+  ? unknown extends P
+    ? // eslint-disable-next-line @typescript-eslint/ban-types
+      {}
+    : P
+  : T extends keyof JSX.IntrinsicElements
+  ? JSX.IntrinsicElements[T]
+  : // eslint-disable-next-line @typescript-eslint/ban-types
+    {};

package/src/utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export type UseDataOptions = {
+  /**
+   * Throw an error, or simply return undefined if the data cannot be found. Use
+   * `true` if you are sure the data must exist.
+   */
+  failfast?: boolean;
+};