[docs-infra] Add configurable jsdoc host variable (#42472)

Signed-off-by: Anthony Gravell <73857273+tonygravell@users.noreply.github.com> Co-authored-by: Tony Gravell <tonygravell@Tonys-Mac-mini.local> Co-authored-by: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> Co-authored-by: alexandre <alex.fauquette@gmail.com>
mui · Jun 7, 2024 · 8a741e4 · 8a741e4
1 parent cde3370
commit 8a741e4
Show file tree

Hide file tree

Showing 166 changed files with 444 additions and 428 deletions.
diff --git a/docs/src/modules/components/Head.tsx b/docs/src/modules/components/Head.tsx
@@ -5,7 +5,7 @@ import { LANGUAGES_SSR } from 'docs/config';
 import { useUserLanguage, useTranslate } from '@mui/docs/i18n';
 import { pathnameToLanguage } from 'docs/src/modules/utils/helpers';
 
-// #major-version-switch
+// #default-branch-switch
 const HOST = process.env.PULL_REQUEST_ID
   ? `https://deploy-preview-${process.env.PULL_REQUEST_ID}--${process.env.NETLIFY_SITE_NAME}.netlify.app`
   : 'https://mui.com';
@@ -44,21 +44,21 @@ export default function Head(props: HeadProps) {
       <meta name="twitter:card" content={largeCard ? 'summary_large_image' : 'summary'} />
       {/* https://x.com/MUI_hq */}
       <meta name="twitter:site" content="@MUI_hq" />
-      {/* #major-version-switch */}
+      {/* #default-branch-switch */}
       <meta name="twitter:title" content={title} />
       <meta name="twitter:description" content={description} />
       <meta name="twitter:image" content={preview} />
       {/* Facebook */}
       <meta property="og:type" content={type} />
       <meta property="og:title" content={title} />
-      {/* #major-version-switch */}
+      {/* #default-branch-switch */}
       <meta property="og:url" content={`${HOST}${router.asPath}`} />
       <meta property="og:description" content={description} />
       <meta property="og:image" content={preview} />
       <meta property="og:ttl" content="604800" />
       {/* Algolia */}
       <meta name="docsearch:language" content={userLanguage} />
-      {/* #major-version-switch */}
+      {/* #default-branch-switch */}
       <meta name="docsearch:version" content="master" />
       {disableAlternateLocale
         ? null

diff --git a/packages/api-docs-builder-core/baseUi/projectSettings.ts b/packages/api-docs-builder-core/baseUi/projectSettings.ts
@@ -43,4 +43,6 @@ export const projectSettings: ProjectSettings = {
   translationPagesDirectory: 'docs/translations/api-docs-base',
   generateClassName: generateUtilityClass,
   isGlobalClassName: isGlobalState,
+  // #default-branch-switch
+  baseApiUrl: 'https://next.mui.com',
 };
diff --git a/packages/api-docs-builder-core/materialUi/projectSettings.ts b/packages/api-docs-builder-core/materialUi/projectSettings.ts
@@ -33,4 +33,6 @@ export const projectSettings: ProjectSettings = {
   translationPagesDirectory: 'docs/translations/api-docs',
   generateClassName: generateUtilityClass,
   isGlobalClassName: isGlobalState,
+  // #default-branch-switch
+  baseApiUrl: 'https://next.mui.com',
 };
diff --git a/packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts b/packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts
@@ -150,8 +150,12 @@ export async function computeApiDescription(
  *  *
  *  * - [Icon API](https://mui.com/api/icon/)
  */
-async function annotateComponentDefinition(api: ReactApi, componentJsdoc: Annotation) {
-  const HOST = 'https://mui.com';
+async function annotateComponentDefinition(
+  api: ReactApi,
+  componentJsdoc: Annotation,
+  projectSettings: ProjectSettings,
+) {
+  const HOST = projectSettings.baseApiUrl ?? 'https://mui.com';
 
   const typesFilename = api.filename.replace(/\.js$/, '.d.ts');
   const fileName = path.parse(api.filename).name;
@@ -855,7 +859,7 @@ export default async function generateComponentApi(
         : !skipAnnotatingComponentDefinition
     ) {
       // Add comment about demo & api links (including inherited component) to the component file
-      await annotateComponentDefinition(reactApi, componentJsdoc);
+      await annotateComponentDefinition(reactApi, componentJsdoc, projectSettings);
     }
   }
 

diff --git a/packages/api-docs-builder/ApiBuilders/HookApiBuilder.ts b/packages/api-docs-builder/ApiBuilders/HookApiBuilder.ts
@@ -111,8 +111,12 @@ export interface ReactApi extends ReactDocgenApi {
  * *
  * * - [useButton API](https://mui.com/base-ui/api/use-button/)
  */
-async function annotateHookDefinition(api: ReactApi, hookJsdoc: Annotation) {
-  const HOST = 'https://mui.com';
+async function annotateHookDefinition(
+  api: ReactApi,
+  hookJsdoc: Annotation,
+  projectSettings: ProjectSettings,
+) {
+  const HOST = projectSettings.baseApiUrl ?? 'https://mui.com';
 
   const typesFilename = api.filename.replace(/\.js$/, '.d.ts');
   const fileName = path.parse(api.filename).name;
@@ -613,7 +617,7 @@ export default async function generateHookApi(
     await generateApiJson(apiPagesDirectory, reactApi);
 
     // Add comment about demo & api links to the component hook file
-    await annotateHookDefinition(reactApi, hookJsdoc);
+    await annotateHookDefinition(reactApi, hookJsdoc, projectSettings);
   }
 
   return reactApi;

diff --git a/packages/api-docs-builder/ProjectSettings.ts b/packages/api-docs-builder/ProjectSettings.ts
@@ -99,4 +99,8 @@ export interface ProjectSettings {
    * Determines if a given slot or state is a global state
    */
   isGlobalClassName: (slotOrState: string) => boolean;
+  /**
+   * Determines the base API URL for generated JSDocs
+   */
+  baseApiUrl?: string;
 }
diff --git a/packages/mui-base/src/FormControl/useFormControlContext.ts b/packages/mui-base/src/FormControl/useFormControlContext.ts
@@ -6,11 +6,11 @@ import { FormControlContext } from './FormControlContext';
  *
  * Demos:
  *
- * - [Form Control](https://mui.com/base-ui/react-form-control/#hook)
+ * - [Form Control](https://next.mui.com/base-ui/react-form-control/#hook)
  *
  * API:
  *
- * - [useFormControlContext API](https://mui.com/base-ui/react-form-control/hooks-api/#use-form-control-context)
+ * - [useFormControlContext API](https://next.mui.com/base-ui/react-form-control/hooks-api/#use-form-control-context)
  */
 export function useFormControlContext(): UseFormControlContextReturnValue | undefined {
   return React.useContext(FormControlContext);

diff --git a/packages/mui-base/src/unstable_useModal/useModal.ts b/packages/mui-base/src/unstable_useModal/useModal.ts
@@ -30,11 +30,11 @@ const defaultManager = new ModalManager();
  *
  * Demos:
  *
- * - [Modal](https://mui.com/base-ui/react-modal/#hook)
+ * - [Modal](https://next.mui.com/base-ui/react-modal/#hook)
  *
  * API:
  *
- * - [useModal API](https://mui.com/base-ui/react-modal/hooks-api/#use-modal)
+ * - [useModal API](https://next.mui.com/base-ui/react-modal/hooks-api/#use-modal)
  */
 export function useModal(parameters: UseModalParameters): UseModalReturnValue {
   const {

diff --git a/packages/mui-base/src/unstable_useNumberInput/useNumberInput.ts b/packages/mui-base/src/unstable_useNumberInput/useNumberInput.ts
@@ -36,11 +36,11 @@ export function getInputValueAsString(v: string): string {
  *
  * Demos:
  *
- * - [Number Input](https://mui.com/base-ui/react-number-input/#hook)
+ * - [Number Input](https://next.mui.com/base-ui/react-number-input/#hook)
  *
  * API:
  *
- * - [useNumberInput API](https://mui.com/base-ui/react-number-input/hooks-api/#use-number-input)
+ * - [useNumberInput API](https://next.mui.com/base-ui/react-number-input/hooks-api/#use-number-input)
  */
 export function useNumberInput(parameters: UseNumberInputParameters): UseNumberInputReturnValue {
   const {

diff --git a/packages/mui-base/src/useAutocomplete/useAutocomplete.d.ts b/packages/mui-base/src/useAutocomplete/useAutocomplete.d.ts
@@ -341,11 +341,11 @@ export type AutocompleteGetTagProps = ({ index }: { index: number }) => {
  *
  * Demos:
  *
- * - [Autocomplete](https://mui.com/base-ui/react-autocomplete/#hook)
+ * - [Autocomplete](https://next.mui.com/base-ui/react-autocomplete/#hook)
  *
  * API:
  *
- * - [useAutocomplete API](https://mui.com/base-ui/react-autocomplete/hooks-api/#use-autocomplete)
+ * - [useAutocomplete API](https://next.mui.com/base-ui/react-autocomplete/hooks-api/#use-autocomplete)
  */
 export function useAutocomplete<
   Value,

diff --git a/packages/mui-base/src/useBadge/useBadge.ts b/packages/mui-base/src/useBadge/useBadge.ts
@@ -7,11 +7,11 @@ import { UseBadgeParameters, UseBadgeReturnValue } from './useBadge.types';
  *
  * Demos:
  *
- * - [Badge](https://mui.com/base-ui/react-badge/#hook)
+ * - [Badge](https://next.mui.com/base-ui/react-badge/#hook)
  *
  * API:
  *
- * - [useBadge API](https://mui.com/base-ui/react-badge/hooks-api/#use-badge)
+ * - [useBadge API](https://next.mui.com/base-ui/react-badge/hooks-api/#use-badge)
  */
 export function useBadge(parameters: UseBadgeParameters): UseBadgeReturnValue {
   const {

diff --git a/packages/mui-base/src/useButton/useButton.ts b/packages/mui-base/src/useButton/useButton.ts
@@ -17,11 +17,11 @@ import { MuiCancellableEvent } from '../utils/MuiCancellableEvent';
  *
  * Demos:
  *
- * - [Button](https://mui.com/base-ui/react-button/#hook)
+ * - [Button](https://next.mui.com/base-ui/react-button/#hook)
  *
  * API:
  *
- * - [useButton API](https://mui.com/base-ui/react-button/hooks-api/#use-button)
+ * - [useButton API](https://next.mui.com/base-ui/react-button/hooks-api/#use-button)
  */
 export function useButton(parameters: UseButtonParameters = {}): UseButtonReturnValue {
   const {

diff --git a/packages/mui-base/src/useDropdown/useDropdown.ts b/packages/mui-base/src/useDropdown/useDropdown.ts
@@ -10,11 +10,11 @@ import { dropdownReducer } from './dropdownReducer';
  *
  * Demos:
  *
- * - [Menu](https://mui.com/base-ui/react-menu/#hooks)
+ * - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
  *
  * API:
  *
- * - [useDropdown API](https://mui.com/base-ui/react-menu/hooks-api/#use-dropdown)
+ * - [useDropdown API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-dropdown)
  */
 export function useDropdown(parameters: UseDropdownParameters = {}) {
   const { defaultOpen, onOpenChange, open: openProp, componentName = 'useDropdown' } = parameters;

diff --git a/packages/mui-base/src/useInput/useInput.ts b/packages/mui-base/src/useInput/useInput.ts
@@ -14,11 +14,11 @@ import {
  *
  * Demos:
  *
- * - [Input](https://mui.com/base-ui/react-input/#hook)
+ * - [Input](https://next.mui.com/base-ui/react-input/#hook)
  *
  * API:
  *
- * - [useInput API](https://mui.com/base-ui/react-input/hooks-api/#use-input)
+ * - [useInput API](https://next.mui.com/base-ui/react-input/hooks-api/#use-input)
  */
 export function useInput(parameters: UseInputParameters = {}): UseInputReturnValue {
   const {

diff --git a/packages/mui-base/src/useMenu/useMenu.ts b/packages/mui-base/src/useMenu/useMenu.ts
@@ -30,11 +30,11 @@ const FALLBACK_MENU_CONTEXT: DropdownContextValue = {
  *
  * Demos:
  *
- * - [Menu](https://mui.com/base-ui/react-menu/#hooks)
+ * - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
  *
  * API:
  *
- * - [useMenu API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu)
+ * - [useMenu API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu)
  */
 export function useMenu(parameters: UseMenuParameters = {}): UseMenuReturnValue {
   const {

diff --git a/packages/mui-base/src/useMenuButton/useMenuButton.ts b/packages/mui-base/src/useMenuButton/useMenuButton.ts
@@ -14,11 +14,11 @@ import { extractEventHandlers } from '../utils';
  *
  * Demos:
  *
- * - [Menu](https://mui.com/base-ui/react-menu/#hooks)
+ * - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
  *
  * API:
  *
- * - [useMenuButton API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu-button)
+ * - [useMenuButton API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu-button)
  */
 export function useMenuButton(parameters: UseMenuButtonParameters = {}): UseMenuButtonReturnValue {
   const { disabled = false, focusableWhenDisabled, rootRef: externalRef } = parameters;

diff --git a/packages/mui-base/src/useMenuItem/useMenuItem.ts b/packages/mui-base/src/useMenuItem/useMenuItem.ts
@@ -34,11 +34,11 @@ const FALLBACK_MENU_CONTEXT: DropdownContextValue = {
  *
  * Demos:
  *
- * - [Menu](https://mui.com/base-ui/react-menu/#hooks)
+ * - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
  *
  * API:
  *
- * - [useMenuItem API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu-item)
+ * - [useMenuItem API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu-item)
  */
 export function useMenuItem(params: UseMenuItemParameters): UseMenuItemReturnValue {
   const {

diff --git a/packages/mui-base/src/useMenuItem/useMenuItemContextStabilizer.ts b/packages/mui-base/src/useMenuItem/useMenuItemContextStabilizer.ts
@@ -8,11 +8,11 @@ import { ListContext, ListContextValue, ListItemState } from '../useList';
  *
  * Demos:
  *
- * - [Menu](https://mui.com/base-ui/react-menu/#hooks)
+ * - [Menu](https://next.mui.com/base-ui/react-menu/#hooks)
  *
  * API:
  *
- * - [useMenuItemContextStabilizer API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu-item-context-stabilizer)
+ * - [useMenuItemContextStabilizer API](https://next.mui.com/base-ui/react-menu/hooks-api/#use-menu-item-context-stabilizer)
  *
  * @param id - The id of the MenuItem. If undefined, it will be generated with useId.
  * @returns The stable ListContext value and the id of the MenuItem.

diff --git a/packages/mui-base/src/useOption/useOption.ts b/packages/mui-base/src/useOption/useOption.ts
@@ -14,11 +14,11 @@ import { EventHandlers } from '../utils/types';
  *
  * Demos:
  *
- * - [Select](https://mui.com/base-ui/react-select/#hooks)
+ * - [Select](https://next.mui.com/base-ui/react-select/#hooks)
  *
  * API:
  *
- * - [useOption API](https://mui.com/base-ui/react-select/hooks-api/#use-option)
+ * - [useOption API](https://next.mui.com/base-ui/react-select/hooks-api/#use-option)
  */
 export function useOption<Value>(params: UseOptionParameters<Value>): UseOptionReturnValue {
   const { value, label, disabled, rootRef: optionRefParam, id: idParam } = params;

diff --git a/packages/mui-base/src/useOption/useOptionContextStabilizer.ts b/packages/mui-base/src/useOption/useOptionContextStabilizer.ts
@@ -7,11 +7,11 @@ import { ListContext, ListContextValue } from '../useList';
  *
  * Demos:
  *
- * - [Select](https://mui.com/base-ui/react-select/#hooks)
+ * - [Select](https://next.mui.com/base-ui/react-select/#hooks)
  *
  * API:
  *
- * - [useOptionContextStabilizer API](https://mui.com/base-ui/react-select/hooks-api/#use-option-context-stabilizer)
+ * - [useOptionContextStabilizer API](https://next.mui.com/base-ui/react-select/hooks-api/#use-option-context-stabilizer)
  *
  * @param value - The value of the Option.
  * @returns The stable ListContext value.

diff --git a/packages/mui-base/src/useSelect/useSelect.ts b/packages/mui-base/src/useSelect/useSelect.ts
@@ -56,11 +56,11 @@ function defaultFormValueProvider<OptionValue>(
  *
  * Demos:
  *
- * - [Select](https://mui.com/base-ui/react-select/#hooks)
+ * - [Select](https://next.mui.com/base-ui/react-select/#hooks)
  *
  * API:
  *
- * - [useSelect API](https://mui.com/base-ui/react-select/hooks-api/#use-select)
+ * - [useSelect API](https://next.mui.com/base-ui/react-select/hooks-api/#use-select)
  */
 function useSelect<OptionValue, Multiple extends boolean = false>(
   props: UseSelectParameters<OptionValue, Multiple>,

diff --git a/packages/mui-base/src/useSlider/useSlider.ts b/packages/mui-base/src/useSlider/useSlider.ts
@@ -190,11 +190,11 @@ function doesSupportTouchActionNone() {
  *
  * Demos:
  *
- * - [Slider](https://mui.com/base-ui/react-slider/#hook)
+ * - [Slider](https://next.mui.com/base-ui/react-slider/#hook)
  *
  * API:
  *
- * - [useSlider API](https://mui.com/base-ui/react-slider/hooks-api/#use-slider)
+ * - [useSlider API](https://next.mui.com/base-ui/react-slider/hooks-api/#use-slider)
  */
 export function useSlider(parameters: UseSliderParameters): UseSliderReturnValue {
   const {

diff --git a/packages/mui-base/src/useSnackbar/useSnackbar.ts b/packages/mui-base/src/useSnackbar/useSnackbar.ts
@@ -17,11 +17,11 @@ import { EventHandlers } from '../utils/types';
  *
  * Demos:
  *
- * - [Snackbar](https://mui.com/base-ui/react-snackbar/#hook)
+ * - [Snackbar](https://next.mui.com/base-ui/react-snackbar/#hook)
  *
  * API:
  *
- * - [useSnackbar API](https://mui.com/base-ui/react-snackbar/hooks-api/#use-snackbar)
+ * - [useSnackbar API](https://next.mui.com/base-ui/react-snackbar/hooks-api/#use-snackbar)
  */
 export function useSnackbar(parameters: UseSnackbarParameters = {}): UseSnackbarReturnValue {
   const {

diff --git a/packages/mui-base/src/useSwitch/useSwitch.ts b/packages/mui-base/src/useSwitch/useSwitch.ts
@@ -12,11 +12,11 @@ import { UseSwitchParameters, UseSwitchReturnValue } from './useSwitch.types';
  *
  * Demos:
  *
- * - [Switch](https://mui.com/base-ui/react-switch/#hook)
+ * - [Switch](https://next.mui.com/base-ui/react-switch/#hook)
  *
  * API:
  *
- * - [useSwitch API](https://mui.com/base-ui/react-switch/hooks-api/#use-switch)
+ * - [useSwitch API](https://next.mui.com/base-ui/react-switch/hooks-api/#use-switch)
  */
 export function useSwitch(props: UseSwitchParameters): UseSwitchReturnValue {
   const {

diff --git a/packages/mui-base/src/useTab/useTab.ts b/packages/mui-base/src/useTab/useTab.ts
@@ -18,11 +18,11 @@ function tabValueGenerator(otherTabValues: Set<string | number>) {
  *
  * Demos:
  *
- * - [Tabs](https://mui.com/base-ui/react-tabs/#hooks)
+ * - [Tabs](https://next.mui.com/base-ui/react-tabs/#hooks)
  *
  * API:
  *
- * - [useTab API](https://mui.com/base-ui/react-tabs/hooks-api/#use-tab)
+ * - [useTab API](https://next.mui.com/base-ui/react-tabs/hooks-api/#use-tab)
  */
 function useTab(parameters: UseTabParameters): UseTabReturnValue {
   const { value: valueParam, rootRef: externalRef, disabled = false, id: idParam } = parameters;

diff --git a/packages/mui-base/src/useTabPanel/useTabPanel.ts b/packages/mui-base/src/useTabPanel/useTabPanel.ts
@@ -17,11 +17,11 @@ function tabPanelValueGenerator(otherTabPanelValues: Set<string | number>) {
  *
  * Demos:
  *
- * - [Tabs](https://mui.com/base-ui/react-tabs/#hooks)
+ * - [Tabs](https://next.mui.com/base-ui/react-tabs/#hooks)
  *
  * API:
  *
- * - [useTabPanel API](https://mui.com/base-ui/react-tabs/hooks-api/#use-tab-panel)
+ * - [useTabPanel API](https://next.mui.com/base-ui/react-tabs/hooks-api/#use-tab-panel)
  */
 function useTabPanel(parameters: UseTabPanelParameters): UseTabPanelReturnValue {
   const { value: valueParam, id: idParam, rootRef: externalRef } = parameters;

diff --git a/packages/mui-base/src/useTabs/useTabs.ts b/packages/mui-base/src/useTabs/useTabs.ts
@@ -17,11 +17,11 @@ type IdLookupFunction = (id: string | number) => string | undefined;
  *
  * Demos:
  *
- * - [Tabs](https://mui.com/base-ui/react-tabs/#hooks)
+ * - [Tabs](https://next.mui.com/base-ui/react-tabs/#hooks)
  *
  * API:
  *
- * - [useTabs API](https://mui.com/base-ui/react-tabs/hooks-api/#use-tabs)
+ * - [useTabs API](https://next.mui.com/base-ui/react-tabs/hooks-api/#use-tabs)
  */
 function useTabs(parameters: UseTabsParameters): UseTabsReturnValue {
   const {