[docs-infra] Move ApiPage to TS (#43149)

mui · Aug 2, 2024 · 85a3b55 · 85a3b55
1 parent 6833fb2
commit 85a3b55
Show file tree

Hide file tree

Showing 19 changed files with 424 additions and 287 deletions.
diff --git a/docs/package.json b/docs/package.json
@@ -117,6 +117,7 @@
     "@mui/internal-docs-utils": "workspace:^",
     "@mui/internal-scripts": "workspace:^",
     "@mui/internal-test-utils": "workspace:^",
+    "@mui-internal/api-docs-builder": "workspace:^",
     "@types/autosuggest-highlight": "^3.2.3",
     "@types/chai": "^4.3.16",
     "@types/css-mediaquery": "^0.1.4",

diff --git a/docs/src/modules/components/ApiPage.js → docs/src/modules/components/ApiPage.tsx b/docs/src/modules/components/ApiPage.js → docs/src/modules/components/ApiPage.tsx
@@ -1,16 +1,16 @@
 /* eslint-disable react/no-danger */
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { exactProp } from '@mui/utils';
+import { ComponentApiContent, PropsTranslations } from '@mui-internal/api-docs-builder';
 import Typography from '@mui/material/Typography';
 import Alert from '@mui/material/Alert';
 import { Ad, AdGuest } from '@mui/docs/Ad';
 import VerifiedRoundedIcon from '@mui/icons-material/VerifiedRounded';
 import WarningRoundedIcon from '@mui/icons-material/WarningRounded';
-import { useTranslate, useUserLanguage } from '@mui/docs/i18n';
+import { Translate, useTranslate, useUserLanguage } from '@mui/docs/i18n';
 import { HighlightedCode } from '@mui/docs/HighlightedCode';
 import { BrandingProvider } from '@mui/docs/branding';
-import { SectionTitle } from '@mui/docs/SectionTitle';
+import { SectionTitle, SectionTitleProps } from '@mui/docs/SectionTitle';
 import { MarkdownElement } from '@mui/docs/MarkdownElement';
 import AppLayoutDocs from 'docs/src/modules/components/AppLayoutDocs';
 import PropertiesSection, {
@@ -20,9 +20,23 @@ import ClassesSection, {
   getClassesToC,
 } from 'docs/src/modules/components/ApiPage/sections/ClassesSection';
 import SlotsSection from 'docs/src/modules/components/ApiPage/sections/SlotsSection';
-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 { TableOfContentsEntry } from '@mui/internal-markdown';
 
-export function getTranslatedHeader(t, header) {
+type ApiHeaderKeys =
+  | 'demos'
+  | 'import'
+  | 'props'
+  | 'theme-default-props'
+  | 'inheritance'
+  | 'slots'
+  | 'classes'
+  | 'css';
+
+export function getTranslatedHeader(t: Translate, header: ApiHeaderKeys) {
   const translations = {
     demos: t('api-docs.demos'),
     import: t('api-docs.import'),
@@ -46,7 +60,7 @@ export function getTranslatedHeader(t, header) {
   return translations[header] || header;
 }
 
-function Heading(props) {
+function Heading(props: Pick<SectionTitleProps<ApiHeaderKeys>, 'hash' | 'level'>) {
   const { hash, level = 'h2' } = props;
   const t = useTranslate();
   return <SectionTitle title={getTranslatedHeader(t, hash)} hash={hash} level={level} />;
@@ -57,7 +71,30 @@ Heading.propTypes = {
   level: PropTypes.string,
 };
 
-export default function ApiPage(props) {
+export interface LayoutStorageKeys {
+  slots: string;
+  props: string;
+  classes: string;
+}
+
+interface ApiPageProps {
+  descriptions: {
+    [lang: string]: PropsTranslations & {
+      // Table of Content added by the mapApiPageTranslations function
+      componentDescriptionToc: TableOfContentsEntry[];
+    };
+  };
+  disableAd?: boolean;
+  pageContent: ComponentApiContent;
+  defaultLayout?: ApiDisplayOptions;
+  /**
+   * The localStorage key used to save the user layout for each section.
+   * It's useful to dave different preferences on different pages.
+   * For example, the data grid has a different key that the core.
+   */
+  layoutStorageKey?: LayoutStorageKeys;
+}
+export default function ApiPage(props: ApiPageProps) {
   const {
     descriptions,
     disableAd = false,
@@ -77,7 +114,7 @@ export default function ApiPage(props) {
     inheritance,
     props: componentProps,
     spread,
-    slots: componentSlots,
+    slots: componentSlots = [],
     classes,
   } = pageContent;
 
@@ -106,14 +143,14 @@ export default function ApiPage(props) {
     classDescriptions,
     deprecationInfo,
     propDescriptions,
-    slotDescriptions,
+    slotDescriptions = {},
   } = descriptions[userLanguage];
   const description = t('api-docs.pageDescription').replace(/{{name}}/, pageContent.name);
 
   // Prefer linking the .tsx or .d.ts for the "Edit this page" link.
   const apiSourceLocation = filename.replace('.js', '.d.ts');
 
-  function createTocEntry(sectionName) {
+  function createTocEntry(sectionName: ApiHeaderKeys) {
     return {
       text: getTranslatedHeader(t, sectionName),
       hash: sectionName,
@@ -288,6 +325,7 @@ export default function ApiPage(props) {
             />
           </React.Fragment>
         )}
+        (
         <SlotsSection
           componentSlots={componentSlots}
           slotDescriptions={slotDescriptions}
@@ -299,6 +337,7 @@ export default function ApiPage(props) {
           defaultLayout={defaultLayout}
           layoutStorageKey={layoutStorageKey.slots}
         />
+        )
         <ClassesSection
           componentClasses={componentClasses}
           componentName={pageContent.name}
@@ -318,19 +357,3 @@ export default function ApiPage(props) {
     </AppLayoutDocs>
   );
 }
-
-ApiPage.propTypes = {
-  defaultLayout: PropTypes.oneOf(['collapsed', 'expanded', 'table']),
-  descriptions: PropTypes.object.isRequired,
-  disableAd: PropTypes.bool,
-  layoutStorageKey: PropTypes.shape({
-    classes: PropTypes.string,
-    props: PropTypes.string,
-    slots: PropTypes.string,
-  }),
-  pageContent: PropTypes.object.isRequired,
-};
-
-if (process.env.NODE_ENV !== 'production') {
-  ApiPage.propTypes = exactProp(ApiPage.propTypes);
-}
diff --git a/docs/src/modules/components/ApiPage/list/PropertiesList.tsx b/docs/src/modules/components/ApiPage/list/PropertiesList.tsx
@@ -145,7 +145,7 @@ export interface Properties {
   isPremiumPlan?: boolean;
   propDefault?: string;
   propName: string;
-  requiresRef?: string;
+  requiresRef?: boolean;
   seeMoreDescription?: string;
   signature?: string;
   signatureArgs?: { argName: string; argDescription?: string }[];
@@ -233,7 +233,7 @@ export default function PropertiesList(props: PropertiesListProps) {
                 className="prop-list-additional-description  MuiApi-collapsible"
                 key={key}
                 dangerouslySetInnerHTML={{
-                  __html: t(`api-docs.additional-info.${key}`),
+                  __html: t(`api-docs.additional-info.${key}`)!,
                 }}
               />
             ))}

diff --git a/docs/src/modules/components/ApiPage/list/SlotsList.tsx b/docs/src/modules/components/ApiPage/list/SlotsList.tsx
@@ -43,22 +43,22 @@ const StyledApiItem = styled(ExpandableApiItem)(
   }),
 );
 
-type HashParams = { componentName: string; className: string };
+type HashParams = { componentName: string; className: string | null; name: string };
 
-export function getHash({ componentName, className }: HashParams) {
-  return `${componentName}-css-${className}`;
+export function getHash({ componentName, className, name }: HashParams) {
+  return `${componentName}-css-${className ?? name}`;
 }
 
-export type SlotsFormatedParams = {
-  className: string;
+export type SlotsFormattedParams = {
+  className: string | null;
   componentName: string;
   description?: string;
   name: string;
   defaultValue?: string;
 };
 
 interface SlotsListProps {
-  slots: SlotsFormatedParams[];
+  slots: SlotsFormattedParams[];
   displayOption: 'collapsed' | 'expanded';
 }
 
@@ -75,8 +75,8 @@ export default function SlotsList(props: SlotsListProps) {
 
         return (
           <StyledApiItem
-            id={getHash({ componentName, className })}
-            key={className}
+            id={getHash({ componentName, className, name })}
+            key={name}
             title={name}
             note=""
             type="slots"

diff --git a/docs/src/modules/components/ApiPage/sections/ClassesSection.tsx b/docs/src/modules/components/ApiPage/sections/ClassesSection.tsx
@@ -1,6 +1,6 @@
 /* eslint-disable react/no-danger */
 import * as React from 'react';
-import { useTranslate } from '@mui/docs/i18n';
+import { Translate, useTranslate } from '@mui/docs/i18n';
 import { SectionTitle } from '@mui/docs/SectionTitle';
 import { ComponentClassDefinition } from '@mui/internal-docs-utils';
 import Box from '@mui/material/Box';
@@ -14,7 +14,7 @@ import ClassesTable from 'docs/src/modules/components/ApiPage/table/ClassesTable
 export type GetCssToCParams = {
   componentName: string;
   componentClasses: ComponentClassDefinition[];
-  t: (key: any, options?: {}) => any;
+  t: Translate;
   hash?: string;
 };
 
@@ -47,8 +47,18 @@ export type ClassesSectionProps = {
   classDescriptions: ClassDescription;
   componentName: string;
   spreadHint?: string;
-  title: string;
-  titleHash: string;
+  /**
+   * The translation key of the section title.
+   * @default 'api-docs.classes'
+   */
+  title?: string;
+  /**
+   * @default 'classes'
+   */
+  titleHash?: string;
+  /**
+   * @default 'h2'
+   */
   level?: 'h2' | 'h3' | 'h4';
   defaultLayout: ApiDisplayOptions;
   layoutStorageKey: string;