@docusaurus/types 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@docusaurus/types",
-  "version": "2.0.0-beta.15d451942",
+  "version": "2.0.0-beta.16",
   "description": "Common types for Docusaurus packages.",
-  "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "publishConfig": {
     "access": "public"
@@ -13,12 +12,16 @@
     "directory": "packages/docusaurus-types"
   },
   "license": "MIT",
+  "scripts": {
+    "test": "tsc -p ."
+  },
   "dependencies": {
     "commander": "^5.1.0",
-    "joi": "^17.4.0",
-    "querystring": "0.2.0",
-    "webpack": "^5.37.0",
-    "webpack-merge": "^5.7.3"
+    "joi": "^17.6.0",
+    "querystring": "0.2.1",
+    "utility-types": "^3.10.0",
+    "webpack": "^5.69.1",
+    "webpack-merge": "^5.8.0"
   },
-  "gitHead": "dfceae8bd3e8b42ba8fc14f1449d861046c26143"
+  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
 }

package/src/index.d.ts

@@ -5,17 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// ESLint doesn't understand types dependencies in d.ts
-// eslint-disable-next-line import/no-extraneous-dependencies
 import type {RuleSetRule, Configuration} from 'webpack';
-import type {Command} from 'commander';
+import type {CustomizeRuleString} from 'webpack-merge/dist/types';
+import type {CommanderStatic} from 'commander';
 import type {ParsedUrlQueryInput} from 'querystring';
 import type Joi from 'joi';
-
-// Convert webpack-merge webpack-merge enum to union type
-// For type retro-compatible webpack-merge upgrade: we used string literals before)
-// see https://github.com/survivejs/webpack-merge/issues/179
-type MergeStrategy = 'match' | 'merge' | 'append' | 'prepend' | 'replace';
+import type {Overwrite, DeepPartial} from 'utility-types';
+import type {Location} from 'history';
 
 export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'error' | 'throw';
 
@@ -23,13 +19,17 @@ export type ThemeConfig = {
   [key: string]: unknown;
 };
 
+// Docusaurus config, after validation/normalization
 export interface DocusaurusConfig {
   baseUrl: string;
   baseUrlIssueBanner: boolean;
-  favicon: string;
-  tagline?: string;
+  favicon?: string;
+  tagline: string;
   title: string;
   url: string;
+  // trailingSlash undefined = legacy retrocompatible behavior
+  // /file => /file/index.html
+  trailingSlash: boolean | undefined;
   i18n: I18nConfig;
   onBrokenLinks: ReportingSeverity;
   onBrokenMarkdownLinks: ReportingSeverity;
@@ -37,6 +37,7 @@ export interface DocusaurusConfig {
   noIndex: boolean;
   organizationName?: string;
   projectName?: string;
+  deploymentBranch?: string;
   githubHost?: string;
   githubPort?: string;
   plugins?: PluginConfig[];
@@ -55,6 +56,7 @@ export interface DocusaurusConfig {
   )[];
   clientModules?: string[];
   ssrTemplate?: string;
+  staticDirectories: string[];
   stylesheets?: (
     | string
     | {
@@ -68,10 +70,24 @@ export interface DocusaurusConfig {
   };
 }
 
+// Docusaurus config, as provided by the user (partial/unnormalized)
+// This type is used to provide type-safety / IDE auto-complete on the config
+// file. See https://docusaurus.io/docs/typescript-support
+export type Config = Overwrite<
+  Partial<DocusaurusConfig>,
+  {
+    title: Required<DocusaurusConfig['title']>;
+    url: Required<DocusaurusConfig['url']>;
+    baseUrl: Required<DocusaurusConfig['baseUrl']>;
+    i18n?: DeepPartial<DocusaurusConfig['i18n']>;
+  }
+>;
+
 /**
  * - `type: 'package'`, plugin is in a different package.
  * - `type: 'project'`, plugin is in the same docusaurus project.
- * - `type: 'local'`, none of plugin's ancestor directory contains any package.json.
+ * - `type: 'local'`, none of the plugin's ancestor directories contains a
+ * package.json.
  * - `type: 'synthetic'`, docusaurus generated internal plugin.
  */
 export type DocusaurusPluginVersionInformation =
@@ -103,6 +119,7 @@ export type TranslationFiles = TranslationFile[];
 
 export type I18nLocaleConfig = {
   label: string;
+  htmlLang: string;
   direction: string;
 };
 
@@ -125,7 +142,10 @@ export interface DocusaurusContext {
   globalData: Record<string, unknown>;
   i18n: I18n;
   codeTranslations: Record<string, string>;
-  isClient: boolean;
+
+  // Don't put mutable values here, to avoid triggering re-renders
+  // We could reconsider that choice if context selectors are implemented
+  // isBrowser: boolean; // Not here on purpose!
 }
 
 export interface Preset {
@@ -133,6 +153,14 @@ export interface Preset {
   themes?: PluginConfig[];
 }
 
+export type PresetModule = {
+  <T>(context: LoadContext, presetOptions: T): Preset;
+};
+
+export type ImportedPresetModule = PresetModule & {
+  default?: PresetModule;
+};
+
 export type PresetConfig =
   | [string, Record<string, unknown>]
   | [string]
@@ -178,9 +206,9 @@ export interface LoadContext {
   siteConfig: DocusaurusConfig;
   siteConfigPath: string;
   outDir: string;
-  baseUrl: string;
+  baseUrl: string; // TODO to remove: useless, there's already siteConfig.baseUrl!
   i18n: I18n;
-  ssrTemplate?: string;
+  ssrTemplate: string;
   codeTranslations: Record<string, string>;
 }
 
@@ -193,17 +221,17 @@ export interface InjectedHtmlTags {
 export type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
 
 export interface Props extends LoadContext, InjectedHtmlTags {
-  siteMetadata: DocusaurusSiteMetadata;
-  routes: RouteConfig[];
-  routesPaths: string[];
-  plugins: Plugin<unknown>[];
+  readonly siteMetadata: DocusaurusSiteMetadata;
+  readonly routes: RouteConfig[];
+  readonly routesPaths: string[];
+  readonly plugins: LoadedPlugin[];
 }
 
 export interface PluginContentLoadedActions {
-  addRoute(config: RouteConfig): void;
+  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: any) => Promise<string>;
+  setGlobalData: <T = unknown>(data: T) => void;
 }
 
 export type AllContent = Record<
@@ -217,32 +245,34 @@ export type AllContent = Record<
 // TODO improve type (not exposed by postcss-loader)
 export type PostCssOptions = Record<string, unknown> & {plugins: unknown[]};
 
-export interface Plugin<Content> {
+export interface Plugin<Content = unknown> {
   name: string;
-  loadContent?(): Promise<Content>;
-  contentLoaded?({
+  loadContent?: () => Promise<Content>;
+  contentLoaded?: ({
     content,
     actions,
   }: {
     content: Content; // the content loaded by this plugin instance
     allContent: AllContent; // content loaded by ALL the plugins
     actions: PluginContentLoadedActions;
-  }): void;
-  routesLoaded?(routes: RouteConfig[]): void; // TODO remove soon, deprecated (alpha-60)
-  postBuild?(props: Props): void;
-  postStart?(props: Props): void;
-  configureWebpack?(
+  }) => Promise<void>;
+  routesLoaded?: (routes: RouteConfig[]) => void; // TODO remove soon, deprecated (alpha-60)
+  postBuild?: (props: Props & {content: Content}) => Promise<void>;
+  // TODO refactor the configureWebpack API surface: use an object instead of
+  // multiple params (requires breaking change)
+  configureWebpack?: (
     config: Configuration,
     isServer: boolean,
     utils: ConfigureWebpackUtils,
-  ): Configuration & {mergeStrategy?: ConfigureWebpackFnMergeStrategy};
-  configurePostCss?(options: PostCssOptions): PostCssOptions;
-  getThemePath?(): string;
-  getTypeScriptThemePath?(): string;
-  getPathsToWatch?(): string[];
-  getClientModules?(): string[];
-  extendCli?(cli: Command): void;
-  injectHtmlTags?(): {
+    content: Content,
+  ) => Configuration & {mergeStrategy?: ConfigureWebpackFnMergeStrategy};
+  configurePostCss?: (options: PostCssOptions) => PostCssOptions;
+  getThemePath?: () => string;
+  getTypeScriptThemePath?: () => string;
+  getPathsToWatch?: () => string[];
+  getClientModules?: () => string[];
+  extendCli?: (cli: CommanderStatic) => void;
+  injectHtmlTags?: ({content}: {content: Content}) => {
     headTags?: HtmlTags;
     preBodyTags?: HtmlTags;
     postBodyTags?: HtmlTags;
@@ -250,38 +280,66 @@ export interface Plugin<Content> {
   // TODO before/afterDevServer implementation
 
   // translations
-  getTranslationFiles?({
+  getTranslationFiles?: ({
     content,
   }: {
     content: Content;
-  }): Promise<TranslationFiles>;
-  getDefaultCodeTranslationMessages?(): Promise<
+  }) => Promise<TranslationFiles>;
+  getDefaultCodeTranslationMessages?: () => Promise<
     Record<
       string, // id
       string // message
     >
   >;
-  translateContent?({
+  translateContent?: ({
     content,
     translationFiles,
   }: {
     content: Content; // the content loaded by this plugin instance
     translationFiles: TranslationFiles;
-  }): Content;
-  translateThemeConfig?({
+  }) => Content;
+  translateThemeConfig?: ({
     themeConfig,
     translationFiles,
   }: {
     themeConfig: ThemeConfig;
     translationFiles: TranslationFiles;
-  }): ThemeConfig;
+  }) => ThemeConfig;
 }
 
+export type InitializedPlugin<Content = unknown> = Plugin<Content> & {
+  readonly options: PluginOptions;
+  readonly version: DocusaurusPluginVersionInformation;
+};
+
+export type LoadedPlugin<Content = unknown> = InitializedPlugin<Content> & {
+  readonly content: Content;
+};
+
+export type SwizzleAction = 'eject' | 'wrap';
+export type SwizzleActionStatus = 'safe' | 'unsafe' | 'forbidden';
+
+export type SwizzleComponentConfig = {
+  actions: Record<SwizzleAction, SwizzleActionStatus>;
+  description?: string;
+};
+
+export type SwizzleConfig = {
+  components: Record<string, SwizzleComponentConfig>;
+  // Other settings could be added here,
+  // For example: the ability to declare the config as exhaustive
+  // so that we can emit errors
+};
+
 export type PluginModule = {
-  <T, X>(context: LoadContext, options: T): Plugin<X>;
-  validateOptions?<T>(data: OptionValidationContext<T>): T;
-  validateThemeConfig?<T>(data: ThemeConfigValidationContext<T>): T;
-  getSwizzleComponentList?(): string[];
+  <Options, Content>(context: LoadContext, options: Options):
+    | Plugin<Content>
+    | Promise<Plugin<Content>>;
+  validateOptions?: <T>(data: OptionValidationContext<T>) => T;
+  validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;
+
+  getSwizzleComponentList?: () => string[] | undefined; // TODO deprecate this one later
+  getSwizzleConfig?: () => SwizzleConfig | undefined;
 };
 
 export type ImportedPluginModule = PluginModule & {
@@ -289,7 +347,10 @@ export type ImportedPluginModule = PluginModule & {
 };
 
 export type ConfigureWebpackFn = Plugin<unknown>['configureWebpack'];
-export type ConfigureWebpackFnMergeStrategy = Record<string, MergeStrategy>;
+export type ConfigureWebpackFnMergeStrategy = Record<
+  string,
+  CustomizeRuleString
+>;
 export type ConfigurePostCssFn = Plugin<unknown>['configurePostCss'];
 
 export type PluginOptions = {id?: string} & Record<string, unknown>;
@@ -329,9 +390,11 @@ export interface RouteConfig {
   routes?: RouteConfig[];
   exact?: boolean;
   priority?: number;
+  [propName: string]: unknown;
 }
 
-export interface ThemeAlias {
+// Aliases used for Webpack resolution (when using docusaurus swizzle)
+export interface ThemeAliases {
   [alias: string]: string;
 }
 
@@ -346,18 +409,6 @@ export interface ConfigureWebpackUtils {
     isServer: boolean;
     babelOptions?: Record<string, unknown>;
   }) => RuleSetRule;
-
-  // TODO deprecated: remove before end of 2021?
-  getCacheLoader: (
-    isServer: boolean,
-    cacheOptions?: Record<string, unknown>,
-  ) => RuleSetRule | null;
-
-  // TODO deprecated: remove before end of 2021?
-  getBabelLoader: (
-    isServer: boolean,
-    options?: Record<string, unknown>,
-  ) => RuleSetRule;
 }
 
 interface HtmlTagObject {
@@ -365,9 +416,7 @@ interface HtmlTagObject {
    * Attributes of the html tag
    * E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
    */
-  attributes?: {
-    [attributeName: string]: string | boolean;
-  };
+  attributes?: Partial<Record<string, string | boolean>>;
   /**
    * The tag name e.g. `div`, `script`, `link`, `meta`
    */
@@ -397,8 +446,18 @@ export interface ThemeConfigValidationContext<T> {
   themeConfig: Partial<T>;
 }
 
-export interface TOCItem {
+export type TOCItem = {
   readonly value: string;
   readonly id: string;
-  readonly children: TOCItem[];
-}
+  readonly level: number;
+};
+
+export type RouteChunksTree = {[x: string | number]: string | RouteChunksTree};
+
+export type ClientModule = {
+  onRouteUpdate?: (args: {
+    previousLocation: Location | null;
+    location: Location;
+  }) => void;
+  onRouteUpdateDelayed?: (args: {location: Location}) => void;
+};

package/src/index.js

@@ -1,10 +0,0 @@
-/**
- * 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.
- */
-
-/* eslint-disable */
-'use strict';
-Object.defineProperty(exports, '__esModule', {value: true});