@docusaurus/types 2.0.0-beta.17 → 2.0.0-beta.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/types",
-  "version": "2.0.0-beta.17",
+  "version": "2.0.0-beta.18",
   "description": "Common types for Docusaurus packages.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -18,10 +18,9 @@
   "dependencies": {
     "commander": "^5.1.0",
     "joi": "^17.6.0",
-    "querystring": "0.2.1",
     "utility-types": "^3.10.0",
-    "webpack": "^5.69.1",
+    "webpack": "^5.70.0",
     "webpack-merge": "^5.8.0"
   },
-  "gitHead": "0032c0b0480083227af2e1b4da2d3ee6ce992403"
+  "gitHead": "1a945d06993d53376e61bed2c942799fe07dc336"
 }

package/src/index.d.ts

@@ -5,13 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {RuleSetRule, Configuration} from 'webpack';
+import type {RuleSetRule, Configuration as WebpackConfiguration} from 'webpack';
 import type {CustomizeRuleString} from 'webpack-merge/dist/types';
 import type {CommanderStatic} from 'commander';
 import type {ParsedUrlQueryInput} from 'querystring';
 import type Joi from 'joi';
 import type {Overwrite, DeepPartial} from 'utility-types';
 import type {Location} from 'history';
+import type Loadable from 'react-loadable';
 
 export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'error' | 'throw';
 
@@ -40,24 +41,24 @@ export interface DocusaurusConfig {
   deploymentBranch?: string;
   githubHost?: string;
   githubPort?: string;
-  plugins?: PluginConfig[];
-  themes?: PluginConfig[];
-  presets?: PresetConfig[];
+  plugins: PluginConfig[];
+  themes: PluginConfig[];
+  presets: PresetConfig[];
   themeConfig: ThemeConfig;
   customFields?: {
     [key: string]: unknown;
   };
-  scripts?: (
+  scripts: (
     | string
     | {
         src: string;
         [key: string]: unknown;
       }
   )[];
-  clientModules?: string[];
+  clientModules: string[];
   ssrTemplate?: string;
   staticDirectories: string[];
-  stylesheets?: (
+  stylesheets: (
     | string
     | {
         href: string;
@@ -90,7 +91,7 @@ export type Config = Overwrite<
  * package.json.
  * - `type: 'synthetic'`, docusaurus generated internal plugin.
  */
-export type DocusaurusPluginVersionInformation =
+export type PluginVersionInformation =
   | {
       readonly type: 'package';
       readonly name?: string;
@@ -103,7 +104,7 @@ export type DocusaurusPluginVersionInformation =
 export interface DocusaurusSiteMetadata {
   readonly docusaurusVersion: string;
   readonly siteVersion?: string;
-  readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;
+  readonly pluginVersions: {[pluginName: string]: PluginVersionInformation};
 }
 
 // Inspired by Chrome JSON, because it's a widely supported i18n format
@@ -113,7 +114,7 @@ export interface DocusaurusSiteMetadata {
 // https://docs.transifex.com/formats/chrome-json
 // https://help.phrase.com/help/chrome-json-messages
 export type TranslationMessage = {message: string; description?: string};
-export type TranslationFileContent = Record<string, TranslationMessage>;
+export type TranslationFileContent = {[key: string]: TranslationMessage};
 export type TranslationFile = {path: string; content: TranslationFileContent};
 export type TranslationFiles = TranslationFile[];
 
@@ -126,22 +127,24 @@ export type I18nLocaleConfig = {
 export type I18nConfig = {
   defaultLocale: string;
   locales: [string, ...string[]];
-  localeConfigs: Record<string, Partial<I18nLocaleConfig>>;
+  localeConfigs: {[locale: string]: Partial<I18nLocaleConfig>};
 };
 
 export type I18n = {
   defaultLocale: string;
   locales: [string, ...string[]];
   currentLocale: string;
-  localeConfigs: Record<string, I18nLocaleConfig>;
+  localeConfigs: {[locale: string]: I18nLocaleConfig};
 };
 
+export type GlobalData = {[pluginName: string]: {[pluginId: string]: unknown}};
+
 export interface DocusaurusContext {
   siteConfig: DocusaurusConfig;
   siteMetadata: DocusaurusSiteMetadata;
-  globalData: Record<string, unknown>;
+  globalData: GlobalData;
   i18n: I18n;
-  codeTranslations: Record<string, string>;
+  codeTranslations: {[msgId: string]: string};
 
   // Don't put mutable values here, to avoid triggering re-renders
   // We could reconsider that choice if context selectors are implemented
@@ -161,10 +164,7 @@ export type ImportedPresetModule = PresetModule & {
   default?: PresetModule;
 };
 
-export type PresetConfig =
-  | [string, Record<string, unknown>]
-  | [string]
-  | string;
+export type PresetConfig = string | [string, {[key: string]: unknown}];
 
 export type HostPortCLIOptions = {
   host?: string;
@@ -209,7 +209,7 @@ export interface LoadContext {
   baseUrl: string; // TODO to remove: useless, there's already siteConfig.baseUrl!
   i18n: I18n;
   ssrTemplate: string;
-  codeTranslations: Record<string, string>;
+  codeTranslations: {[msgId: string]: string};
 }
 
 export interface InjectedHtmlTags {
@@ -229,31 +229,27 @@ export interface Props extends LoadContext, InjectedHtmlTags {
 
 export interface PluginContentLoadedActions {
   addRoute: (config: RouteConfig) => void;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  createData: (name: string, data: any) => Promise<string>;
-  setGlobalData: <T = unknown>(data: T) => void;
+  createData: (name: string, data: string) => Promise<string>;
+  setGlobalData: (data: unknown) => void;
 }
 
-export type AllContent = Record<
-  string, // plugin name
-  Record<
-    string, // plugin id
-    unknown // plugin data
-  >
->;
+export type AllContent = {
+  [pluginName: string]: {
+    [pluginID: string]: unknown;
+  };
+};
 
 // TODO improve type (not exposed by postcss-loader)
-export type PostCssOptions = Record<string, unknown> & {plugins: unknown[]};
+export type PostCssOptions = {[key: string]: unknown} & {plugins: unknown[]};
 
 export interface Plugin<Content = unknown> {
   name: string;
   loadContent?: () => Promise<Content>;
-  contentLoaded?: ({
-    content,
-    actions,
-  }: {
-    content: Content; // the content loaded by this plugin instance
-    allContent: AllContent; // content loaded by ALL the plugins
+  contentLoaded?: (args: {
+    /** the content loaded by this plugin instance */
+    content: Content; //
+    /** content loaded by ALL the plugins */
+    allContent: AllContent;
     actions: PluginContentLoadedActions;
   }) => Promise<void>;
   routesLoaded?: (routes: RouteConfig[]) => void; // TODO remove soon, deprecated (alpha-60)
@@ -261,18 +257,20 @@ export interface Plugin<Content = unknown> {
   // TODO refactor the configureWebpack API surface: use an object instead of
   // multiple params (requires breaking change)
   configureWebpack?: (
-    config: Configuration,
+    config: WebpackConfiguration,
     isServer: boolean,
     utils: ConfigureWebpackUtils,
     content: Content,
-  ) => Configuration & {mergeStrategy?: ConfigureWebpackFnMergeStrategy};
+  ) => WebpackConfiguration & {
+    mergeStrategy?: ConfigureWebpackFnMergeStrategy;
+  };
   configurePostCss?: (options: PostCssOptions) => PostCssOptions;
   getThemePath?: () => string;
   getTypeScriptThemePath?: () => string;
   getPathsToWatch?: () => string[];
   getClientModules?: () => string[];
   extendCli?: (cli: CommanderStatic) => void;
-  injectHtmlTags?: ({content}: {content: Content}) => {
+  injectHtmlTags?: (args: {content: Content}) => {
     headTags?: HtmlTags;
     preBodyTags?: HtmlTags;
     postBodyTags?: HtmlTags;
@@ -280,36 +278,25 @@ export interface Plugin<Content = unknown> {
   // TODO before/afterDevServer implementation
 
   // translations
-  getTranslationFiles?: ({
-    content,
-  }: {
-    content: Content;
-  }) => Promise<TranslationFiles>;
-  getDefaultCodeTranslationMessages?: () => Promise<
-    Record<
-      string, // id
-      string // message
-    >
-  >;
-  translateContent?: ({
-    content,
-    translationFiles,
-  }: {
+  getTranslationFiles?: (args: {content: Content}) => Promise<TranslationFiles>;
+  getDefaultCodeTranslationMessages?: () => Promise<{[id: string]: string}>;
+  translateContent?: (args: {
     content: Content; // the content loaded by this plugin instance
     translationFiles: TranslationFiles;
   }) => Content;
-  translateThemeConfig?: ({
-    themeConfig,
-    translationFiles,
-  }: {
+  translateThemeConfig?: (args: {
     themeConfig: ThemeConfig;
     translationFiles: TranslationFiles;
   }) => ThemeConfig;
 }
 
 export type InitializedPlugin<Content = unknown> = Plugin<Content> & {
-  readonly options: PluginOptions;
-  readonly version: DocusaurusPluginVersionInformation;
+  readonly options: Required<PluginOptions>;
+  readonly version: PluginVersionInformation;
+  /**
+   * The absolute path to the folder containing the entry point file.
+   */
+  readonly path: string;
 };
 
 export type LoadedPlugin<Content = unknown> = InitializedPlugin<Content> & {
@@ -320,12 +307,12 @@ export type SwizzleAction = 'eject' | 'wrap';
 export type SwizzleActionStatus = 'safe' | 'unsafe' | 'forbidden';
 
 export type SwizzleComponentConfig = {
-  actions: Record<SwizzleAction, SwizzleActionStatus>;
+  actions: {[action in SwizzleAction]: SwizzleActionStatus};
   description?: string;
 };
 
 export type SwizzleConfig = {
-  components: Record<string, SwizzleComponentConfig>;
+  components: {[componentName: string]: SwizzleComponentConfig};
   // Other settings could be added here,
   // For example: the ability to declare the config as exhaustive
   // so that we can emit errors
@@ -335,7 +322,7 @@ export type PluginModule = {
   <Options, Content>(context: LoadContext, options: Options):
     | Plugin<Content>
     | Promise<Plugin<Content>>;
-  validateOptions?: <T>(data: OptionValidationContext<T>) => T;
+  validateOptions?: <T, U>(data: OptionValidationContext<T, U>) => U;
   validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;
 
   getSwizzleComponentList?: () => string[] | undefined; // TODO deprecate this one later
@@ -347,18 +334,16 @@ export type ImportedPluginModule = PluginModule & {
 };
 
 export type ConfigureWebpackFn = Plugin<unknown>['configureWebpack'];
-export type ConfigureWebpackFnMergeStrategy = Record<
-  string,
-  CustomizeRuleString
->;
+export type ConfigureWebpackFnMergeStrategy = {
+  [key: string]: CustomizeRuleString;
+};
 export type ConfigurePostCssFn = Plugin<unknown>['configurePostCss'];
 
-export type PluginOptions = {id?: string} & Record<string, unknown>;
+export type PluginOptions = {id?: string} & {[key: string]: unknown};
 
 export type PluginConfig =
-  | [string, PluginOptions]
-  | [string]
   | string
+  | [string, PluginOptions]
   | [PluginModule, PluginOptions]
   | PluginModule;
 
@@ -393,6 +378,31 @@ export interface RouteConfig {
   [propName: string]: unknown;
 }
 
+export interface 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 interface PluginRouteContext extends RouteContext {
+  plugin: {
+    id: string;
+    name: string;
+  };
+}
+
+export type Route = {
+  readonly path: string;
+  readonly component: ReturnType<typeof Loadable>;
+  readonly exact?: boolean;
+  readonly routes?: Route[];
+};
+
 // Aliases used for Webpack resolution (when using docusaurus swizzle)
 export interface ThemeAliases {
   [alias: string]: string;
@@ -407,7 +417,7 @@ export interface ConfigureWebpackUtils {
   ) => RuleSetRule[];
   getJSLoader: (options: {
     isServer: boolean;
-    babelOptions?: Record<string, unknown>;
+    babelOptions?: {[key: string]: unknown};
   }) => RuleSetRule;
 }
 
@@ -416,7 +426,7 @@ interface HtmlTagObject {
    * Attributes of the html tag
    * E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
    */
-  attributes?: Partial<Record<string, string | boolean>>;
+  attributes?: Partial<{[key: string]: string | boolean}>;
   /**
    * The tag name e.g. `div`, `script`, `link`, `meta`
    */
@@ -427,22 +437,20 @@ interface HtmlTagObject {
   innerHTML?: string;
 }
 
-export type ValidationResult<T> = T;
-
 export type ValidationSchema<T> = Joi.ObjectSchema<T>;
 
-export type Validate<T> = (
-  validationSchema: ValidationSchema<T>,
-  options: Partial<T>,
-) => ValidationResult<T>;
+export type Validate<T, U> = (
+  validationSchema: ValidationSchema<U>,
+  options: T,
+) => U;
 
-export interface OptionValidationContext<T> {
-  validate: Validate<T>;
-  options: Partial<T>;
-}
+export type OptionValidationContext<T, U> = {
+  validate: Validate<T, U>;
+  options: T;
+};
 
 export interface ThemeConfigValidationContext<T> {
-  validate: Validate<T>;
+  validate: Validate<T, T>;
   themeConfig: Partial<T>;
 }