[docs-infra] Move API pages to TS (mui#43199)

DiegoAndai · Aug 13, 2024 · f88194a · f88194a
1 parent 224756b
commit f88194a
Show file tree

Hide file tree

Showing 11 changed files with 122 additions and 72 deletions.
diff --git a/docs/src/modules/components/ApiPage.tsx b/docs/src/modules/components/ApiPage.tsx
@@ -30,7 +30,7 @@ import {
   getClassApiDefinitions,
   getClassesToC,
 } from 'docs/src/modules/components/ApiPage/definitions/classes';
-import { getSlotsApiDefinitions } from './ApiPage/definitions/slots';
+import { getSlotsApiDefinitions } from 'docs/src/modules/components/ApiPage/definitions/slots';
 
 // TODO Move this type definition to the AppLayoutDocs file when moved to TS
 export interface TableOfContentsParams {

diff --git a/docs/src/modules/components/ApiPage/definitions/properties.ts b/docs/src/modules/components/ApiPage/definitions/properties.ts
@@ -1,10 +1,11 @@
-import { PropsTableItem, PropsTranslations } from '@mui-internal/api-docs-builder';
-import { Translate } from '@mui/docs/i18n';
-import kebabCase from 'lodash/kebabCase';
 import {
+  PropsTableItem,
+  PropsTranslations,
   HookApiContent,
   HooksTranslations,
-} from 'packages/api-docs-builder/types/ApiBuilder.types';
+} from '@mui-internal/api-docs-builder';
+import { Translate } from '@mui/docs/i18n';
+import kebabCase from 'lodash/kebabCase';
 import type { TableOfContentsParams } from 'docs/src/modules/components/ApiPage';
 
 export interface PropertyDefinition {

diff --git a/docs/src/modules/components/ApiPage/sections/ClassesSection.tsx b/docs/src/modules/components/ApiPage/sections/ClassesSection.tsx
@@ -13,8 +13,7 @@ import {
   ClassDefinition,
   getClassApiDefinitions,
 } from 'docs/src/modules/components/ApiPage/definitions/classes';
-import { ComponentClassDefinition } from '@mui/internal-docs-utils';
-import { PropsTranslations } from '@mui-internal/api-docs-builder';
+import { PropsTranslations, ComponentClassDefinition } from '@mui-internal/api-docs-builder';
 import kebabCase from 'lodash/kebabCase';
 
 export type GetCssToCParams = {
@@ -25,7 +24,7 @@ export type GetCssToCParams = {
 };
 
 /**
- * @deprecated Use the function from ApiPage/processors
+ * @deprecated Use the function from ApiPage/definitions
  */
 export const getClassesToC = ({ componentName, componentClasses, t, hash }: GetCssToCParams) =>
   !componentClasses || componentClasses.length === 0
@@ -74,8 +73,8 @@ export type ClassesSectionProps = (
   level?: 'h2' | 'h3' | 'h4';
   defaultLayout: ApiDisplayOptions;
   layoutStorageKey: string;
-  displayClassKeys: boolean;
-  styleOverridesLink: string;
+  displayClassKeys?: boolean;
+  styleOverridesLink?: string;
 };
 
 export default function ClassesSection(props: ClassesSectionProps) {

diff --git a/docs/src/modules/components/ApiPage/sections/PropertiesSection.tsx b/docs/src/modules/components/ApiPage/sections/PropertiesSection.tsx
@@ -14,7 +14,11 @@ import {
   getPropsApiDefinitions,
 } from 'docs/src/modules/components/ApiPage/definitions/properties';
 import { LayoutStorageKeys } from 'docs/src/modules/components/ApiPage';
-import { ComponentApiContent, PropsTableItem, PropsTranslations } from 'packages/api-docs-builder';
+import {
+  ComponentApiContent,
+  PropsTableItem,
+  PropsTranslations,
+} from '@mui-internal/api-docs-builder';
 import kebabCase from 'lodash/kebabCase';
 
 interface GetPropsToCParams extends Pick<ComponentApiContent, 'inheritance' | 'themeDefaultProps'> {
@@ -28,7 +32,7 @@ interface GetPropsToCParams extends Pick<ComponentApiContent, 'inheritance' | 't
 }
 
 /**
- * @deprecated Use the one from ApiPage/processors
+ * @deprecated Use the one from ApiPage/definitions
  */
 export function getPropsToC({
   componentName,

diff --git a/...odules/components/ComponentsApiContent.js → ...dules/components/ComponentsApiContent.tsx b/...odules/components/ComponentsApiContent.js → ...dules/components/ComponentsApiContent.tsx
@@ -3,20 +3,26 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import kebabCase from 'lodash/kebabCase';
 import { useRouter } from 'next/router';
-import { exactProp } from '@mui/utils';
-import { useTranslate, useUserLanguage } from '@mui/docs/i18n';
-import { SectionTitle } from '@mui/docs/SectionTitle';
+import exactProp from '@mui/utils/exactProp';
+import { Translate, useTranslate, useUserLanguage } from '@mui/docs/i18n';
+import { SectionTitle, SectionTitleProps } from '@mui/docs/SectionTitle';
 import { HighlightedCode } from '@mui/docs/HighlightedCode';
 import { MarkdownElement } from '@mui/docs/MarkdownElement';
+import { ComponentApiContent, PropsTranslations } from '@mui-internal/api-docs-builder';
 import PropertiesSection from 'docs/src/modules/components/ApiPage/sections/PropertiesSection';
 import ClassesSection from 'docs/src/modules/components/ApiPage/sections/ClassesSection';
 import SlotsSection from 'docs/src/modules/components/ApiPage/sections/SlotsSection';
 import { getPropsApiDefinitions } from 'docs/src/modules/components/ApiPage/definitions/properties';
 import { getClassApiDefinitions } from 'docs/src/modules/components/ApiPage/definitions/classes';
-import { DEFAULT_API_LAYOUT_STORAGE_KEYS } from 'docs/src/modules/components/ApiPage/sections/ToggleDisplayOption';
+import {
+  ApiDisplayOptions,
+  DEFAULT_API_LAYOUT_STORAGE_KEYS,
+} from 'docs/src/modules/components/ApiPage/sections/ToggleDisplayOption';
+import { getSlotsApiDefinitions } from 'docs/src/modules/components/ApiPage/definitions/slots';
+import { LayoutStorageKeys } from 'docs/src/modules/components/ApiPage';
 
-function getTranslatedHeader(t, header, text) {
-  const translations = {
+function getTranslatedHeader(t: Translate, header: string, title?: string) {
+  const translations: Record<string, string> = {
     demos: t('api-docs.demos'),
     import: t('api-docs.import'),
     props: t('api-docs.props'),
@@ -27,23 +33,34 @@ function getTranslatedHeader(t, header, text) {
     css: t('api-docs.css'),
   };
 
-  return translations[header] || translations[text] || text || header;
+  return translations[header] || (title && translations[title]) || title || header;
 }
 
-function Heading(props) {
-  const { hash, text, level = 'h2' } = props;
+function Heading(props: SectionTitleProps) {
+  const { hash, title, level = 'h2' } = props;
   const t = useTranslate();
 
-  return <SectionTitle title={getTranslatedHeader(t, hash, text)} hash={hash} level={level} />;
+  return <SectionTitle title={getTranslatedHeader(t, hash, title)} hash={hash} level={level} />;
 }
 
 Heading.propTypes = {
   hash: PropTypes.string.isRequired,
   level: PropTypes.string,
-  text: PropTypes.string,
+  title: PropTypes.string,
 };
 
-export default function ComponentsApiContent(props) {
+type ComponentsApiContentProps = {
+  descriptions: {
+    [component: string]: {
+      [lang: string]: PropsTranslations;
+    };
+  };
+  pageContents: { [component: string]: ComponentApiContent };
+  defaultLayout?: ApiDisplayOptions;
+  layoutStorageKey?: LayoutStorageKeys;
+};
+
+export default function ComponentsApiContent(props: ComponentsApiContentProps) {
   const {
     descriptions,
     pageContents,
@@ -63,7 +80,7 @@ export default function ComponentsApiContent(props) {
         {
           hash: `${anchor.replace('-unstyled', '')}`,
         },
-        null,
+        undefined,
         {
           shallow: true,
         },
@@ -139,8 +156,8 @@ export default function ComponentsApiContent(props) {
     return (
       <React.Fragment key={`component-api-${key}`}>
         <MarkdownElement>
-          <Heading hash={componentNameKebabCase} text={`${componentName} API`} />
-          <Heading text="import" hash={`${componentNameKebabCase}-import`} level="h3" />
+          <Heading hash={componentNameKebabCase} title={`${componentName} API`} />
+          <Heading title="import" hash={`${componentNameKebabCase}-import`} level="h3" />
           <HighlightedCode code={importInstructions} language="jsx" />
           {imports.length > 1 && (
             <p dangerouslySetInnerHTML={{ __html: t('api-docs.importDifference') }} />
@@ -181,7 +198,7 @@ export default function ComponentsApiContent(props) {
           {inheritance && (
             <React.Fragment>
               <Heading
-                text="inheritance"
+                title="inheritance"
                 hash={`${componentNameKebabCase}-inheritance`}
                 level="h3"
               />
@@ -199,7 +216,7 @@ export default function ComponentsApiContent(props) {
           {pageContent.themeDefaultProps && (
             <React.Fragment>
               <Heading
-                text="theme-default-props"
+                title="theme-default-props"
                 hash={`${componentName}-theme-default-props`}
                 level="h4"
               />
@@ -213,9 +230,11 @@ export default function ComponentsApiContent(props) {
             </React.Fragment>
           )}
           <SlotsSection
-            componentSlots={componentSlots}
-            slotDescriptions={slotDescriptions}
-            componentName={componentName}
+            slots={getSlotsApiDefinitions({
+              componentSlots,
+              slotDescriptions,
+              componentName,
+            })}
             titleHash={`${componentNameKebabCase}-slots`}
             level="h3"
             spreadHint={
@@ -248,17 +267,15 @@ export default function ComponentsApiContent(props) {
   });
 }
 
-ComponentsApiContent.propTypes = {
-  defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']),
-  descriptions: PropTypes.object.isRequired,
-  layoutStorageKey: PropTypes.shape({
-    classes: PropTypes.string,
-    props: PropTypes.string,
-    slots: PropTypes.string,
-  }),
-  pageContents: PropTypes.object.isRequired,
-};
-
 if (process.env.NODE_ENV !== 'production') {
-  ComponentsApiContent.propTypes = exactProp(ComponentsApiContent.propTypes);
+  ComponentsApiContent.propTypes = exactProp({
+    defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']),
+    descriptions: PropTypes.object.isRequired,
+    layoutStorageKey: PropTypes.shape({
+      classes: PropTypes.string,
+      props: PropTypes.string,
+      slots: PropTypes.string,
+    }),
+    pageContents: PropTypes.object.isRequired,
+  });
 }
diff --git a/...src/modules/components/HooksApiContent.js → ...rc/modules/components/HooksApiContent.tsx b/...src/modules/components/HooksApiContent.js → ...rc/modules/components/HooksApiContent.tsx
@@ -2,41 +2,57 @@
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import kebabCase from 'lodash/kebabCase';
-import { exactProp } from '@mui/utils';
-import { useTranslate, useUserLanguage } from '@mui/docs/i18n';
-import { SectionTitle } from '@mui/docs/SectionTitle';
+import exactProp from '@mui/utils/exactProp';
+import { Translate, useTranslate, useUserLanguage } from '@mui/docs/i18n';
+import { SectionTitle, SectionTitleProps } from '@mui/docs/SectionTitle';
+import { HookApiContent, HooksTranslations } from '@mui-internal/api-docs-builder';
 import PropertiesSection from 'docs/src/modules/components/ApiPage/sections/PropertiesSection';
 import { getHookApiDefinitions } from 'docs/src/modules/components/ApiPage/definitions/properties';
 import { HighlightedCode } from '@mui/docs/HighlightedCode';
 import { MarkdownElement } from '@mui/docs/MarkdownElement';
-import { DEFAULT_API_LAYOUT_STORAGE_KEYS } from 'docs/src/modules/components/ApiPage/sections/ToggleDisplayOption';
+import {
+  ApiDisplayOptions,
+  DEFAULT_API_LAYOUT_STORAGE_KEYS,
+} from 'docs/src/modules/components/ApiPage/sections/ToggleDisplayOption';
+import { LayoutStorageKeys } from 'docs/src/modules/components//ApiPage';
 
-function getTranslatedHeader(t, header, text) {
-  const translations = {
+function getTranslatedHeader(t: Translate, header: string, title?: string) {
+  const translations: Record<string, string> = {
     demos: t('api-docs.demos'),
     import: t('api-docs.import'),
     'hook-name': t('api-docs.hookName'),
     parameters: t('api-docs.parameters'),
     'return-value': t('api-docs.returnValue'),
   };
 
-  return translations[header] || translations[text] || text || header;
+  return translations[header] || (title && translations[title]) || title || header;
 }
 
-function Heading(props) {
-  const { hash, text, level = 'h2' } = props;
+function Heading(props: SectionTitleProps) {
+  const { hash, title, level = 'h2' } = props;
   const t = useTranslate();
 
-  return <SectionTitle hash={hash} title={getTranslatedHeader(t, hash, text)} level={level} />;
+  return <SectionTitle title={getTranslatedHeader(t, hash, title)} hash={hash} level={level} />;
 }
 
 Heading.propTypes = {
   hash: PropTypes.string.isRequired,
   level: PropTypes.string,
-  text: PropTypes.string,
+  title: PropTypes.string,
 };
 
-export default function HooksApiContent(props) {
+type HooksApiContentProps = {
+  descriptions: {
+    [hookName: string]: {
+      [lang: string]: HooksTranslations;
+    };
+  };
+  pagesContents: { [component: string]: HookApiContent };
+  defaultLayout?: ApiDisplayOptions;
+  layoutStorageKey?: LayoutStorageKeys;
+};
+
+export default function HooksApiContent(props: HooksApiContentProps) {
   const {
     descriptions,
     pagesContents,
@@ -62,8 +78,8 @@ export default function HooksApiContent(props) {
     return (
       <React.Fragment key={`hook-api-${key}`}>
         <MarkdownElement>
-          <Heading hash={hookNameKebabCase} text={`${hookName} API`} />
-          <Heading text="import" hash={`${hookNameKebabCase}-import`} level="h3" />
+          <Heading hash={hookNameKebabCase} title={`${hookName} API`} />
+          <Heading title="import" hash={`${hookNameKebabCase}-import`} level="h3" />
           <HighlightedCode code={importInstructions} language="jsx" />
           {imports.length > 1 && (
             <p dangerouslySetInnerHTML={{ __html: t('api-docs.importDifference') }} />
@@ -80,7 +96,7 @@ export default function HooksApiContent(props) {
               title="api-docs.parameters"
               titleHash={`${hookNameKebabCase}-parameters`}
               defaultLayout={defaultLayout}
-              layoutStorageKey={layoutStorageKey}
+              layoutStorageKey={layoutStorageKey.props}
             />
           ) : (
             <span>{t('api-docs.hooksNoParameters')}</span>
@@ -97,7 +113,7 @@ export default function HooksApiContent(props) {
             title="api-docs.returnValue"
             titleHash={`${hookNameKebabCase}-return-value`}
             defaultLayout={defaultLayout}
-            layoutStorageKey={layoutStorageKey}
+            layoutStorageKey={layoutStorageKey.props}
           />
           <br />
         </MarkdownElement>
@@ -111,13 +127,11 @@ export default function HooksApiContent(props) {
   });
 }
 
-HooksApiContent.propTypes = {
-  defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']),
-  descriptions: PropTypes.object.isRequired,
-  layoutStorageKey: PropTypes.string,
-  pagesContents: PropTypes.object.isRequired,
-};
-
 if (process.env.NODE_ENV !== 'production') {
-  HooksApiContent.propTypes = exactProp(HooksApiContent.propTypes);
+  HooksApiContent.propTypes = exactProp({
+    defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']),
+    descriptions: PropTypes.object.isRequired,
+    layoutStorageKey: PropTypes.string,
+    pagesContents: PropTypes.object.isRequired,
+  });
 }
diff --git a/packages-internal/docs-utils/src/ComponentClassDefinition.ts b/packages-internal/docs-utils/src/ComponentClassDefinition.ts
@@ -1,3 +1,6 @@
+/**
+ * @deprecated Import if from '@mui-internal/api-docs-builder'
+ */
 export interface ComponentClassDefinition {
   key: string;
   className: string;

diff --git a/packages/api-docs-builder/ProjectSettings.ts b/packages/api-docs-builder/ProjectSettings.ts
@@ -1,7 +1,10 @@
-import { ComponentClassDefinition } from '@mui/internal-docs-utils';
 import { CreateTypeScriptProjectOptions } from './utils/createTypeScriptProject';
 import { CreateDescribeablePropSettings } from './utils/createDescribeableProp';
-import { ComponentReactApi, HookReactApi } from './types/ApiBuilder.types';
+import {
+  ComponentClassDefinition,
+  ComponentReactApi,
+  HookReactApi,
+} from './types/ApiBuilder.types';
 import { Slot, ComponentInfo, HookInfo } from './types/utils.types';
 
 export type SortingStrategiesType = {

diff --git a/packages/api-docs-builder/index.ts b/packages/api-docs-builder/index.ts
@@ -8,5 +8,6 @@ export type {
   PropsTranslations,
   HooksTranslations,
   HookApiContent,
+  ComponentClassDefinition,
 } from './types/ApiBuilder.types';
 export type { Slot } from './types/utils.types';