@mui/docs 9.0.0-alpha.3 → 9.0.0-beta.0

package/ApiPage/sections/ClassesSection.js

@@ -0,0 +1,76 @@
+var _br;
+/* eslint-disable react/no-danger */
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import { SectionTitle } from "../../SectionTitle/index.js";
+import { useTranslate } from "../../i18n/index.js";
+import { ToggleDisplayOption, useApiPageOption } from "./ToggleDisplayOption.js";
+import { getClassApiDefinitions } from "../definitions/classes.js";
+import ClassesTable from "../table/ClassesTable.js";
+import ClassesList from "../list/ClassesList.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function ClassesSection(props) {
+  const {
+    classes,
+    componentClasses,
+    classDescriptions,
+    componentName,
+    spreadHint,
+    title = 'api-docs.classes',
+    titleHash = 'classes',
+    level = 'h2',
+    displayClassKeys,
+    styleOverridesLink,
+    defaultLayout,
+    layoutStorageKey
+  } = props;
+  const t = useTranslate();
+  const [displayOption, setDisplayOption] = useApiPageOption(layoutStorageKey, defaultLayout);
+  const formattedClasses = classes || getClassApiDefinitions({
+    componentClasses,
+    classDescriptions,
+    componentName
+  });
+  if (!formattedClasses || formattedClasses.length === 0) {
+    return null;
+  }
+  return /*#__PURE__*/_jsxs(React.Fragment, {
+    children: [/*#__PURE__*/_jsxs(Box, {
+      sx: {
+        display: 'flex',
+        alignItems: 'baseline',
+        mb: 1
+      },
+      children: [/*#__PURE__*/_jsx(SectionTitle, {
+        title: t(title),
+        hash: titleHash,
+        level: level
+      }), /*#__PURE__*/_jsx(ToggleDisplayOption, {
+        displayOption: displayOption,
+        setDisplayOption: setDisplayOption,
+        sectionType: "classes"
+      })]
+    }), spreadHint && /*#__PURE__*/_jsx("p", {
+      dangerouslySetInnerHTML: {
+        __html: spreadHint
+      }
+    }), displayOption === 'table' ? /*#__PURE__*/_jsx(ClassesTable, {
+      classes: formattedClasses,
+      displayClassKeys: displayClassKeys
+    }) : /*#__PURE__*/_jsx(ClassesList, {
+      classes: formattedClasses,
+      displayOption: displayOption,
+      displayClassKeys: displayClassKeys
+    }), styleOverridesLink && /*#__PURE__*/_jsxs(React.Fragment, {
+      children: [_br || (_br = /*#__PURE__*/_jsx("br", {})), /*#__PURE__*/_jsx("p", {
+        dangerouslySetInnerHTML: {
+          __html: t('api-docs.overrideStyles')
+        }
+      }), /*#__PURE__*/_jsx("span", {
+        dangerouslySetInnerHTML: {
+          __html: t('api-docs.overrideStylesStyledComponent').replace(/{{styleOverridesLink}}/, styleOverridesLink)
+        }
+      })]
+    })]
+  });
+}

package/ApiPage/sections/PropertiesSection.d.ts

@@ -0,0 +1,45 @@
+import { PropsTableItem, PropsTranslations } from '@mui-internal/api-docs-builder';
+import { type ApiDisplayLayout } from "./ToggleDisplayOption.js";
+import { type SectionTitleProps } from "../../SectionTitle/index.js";
+import { LayoutStorageKeys } from "../types.js";
+import { PropertyDefinition } from "../definitions/index.js";
+type PropertiesSectionProps = ({
+  properties: {
+    [name: string]: PropsTableItem & {
+      isProPlan?: true;
+      isPremiumPlan?: true;
+    };
+  };
+  propertiesDescriptions: PropsTranslations['propDescriptions'];
+  componentName: string;
+  /**
+   * Add indicators that the properties is optional instead of showing it is required.
+   */
+  showOptionalAbbr?: boolean;
+} | {
+  showOptionalAbbr?: undefined;
+  properties: PropertyDefinition[];
+  propertiesDescriptions?: undefined;
+  componentName?: undefined;
+}) & {
+  spreadHint?: string;
+  defaultLayout: ApiDisplayLayout;
+  layoutStorageKey: LayoutStorageKeys['props'];
+  /**
+   * The translation key of the section title.
+   * @default 'api-docs.props'
+   */
+  title?: string;
+  /**
+   * The hash linking to the section title.
+   * @default 'props'
+   */
+  titleHash?: SectionTitleProps['hash'];
+  /**
+   * The title level of the section.
+   * @default 'h2'
+   */
+  level?: SectionTitleProps['level'];
+};
+export declare function PropertiesSection(props: PropertiesSectionProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/ApiPage/sections/PropertiesSection.js

@@ -0,0 +1,59 @@
+/* eslint-disable react/no-danger */
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import { useTranslate } from "../../i18n/index.js";
+import { ToggleDisplayOption, useApiPageOption } from "./ToggleDisplayOption.js";
+import { SectionTitle } from "../../SectionTitle/index.js";
+import PropertiesTable from "../table/PropertiesTable.js";
+import PropertiesList from "../list/PropertiesList.js";
+import { getPropsApiDefinitions } from "../definitions/properties.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function PropertiesSection(props) {
+  const {
+    properties,
+    propertiesDescriptions,
+    componentName,
+    title = 'api-docs.props',
+    titleHash = 'props',
+    level = 'h2',
+    spreadHint,
+    defaultLayout,
+    layoutStorageKey,
+    showOptionalAbbr
+  } = props;
+  const t = useTranslate();
+  const [displayOption, setDisplayOption] = useApiPageOption(layoutStorageKey, defaultLayout);
+  const formattedProperties = Array.isArray(properties) ? properties : getPropsApiDefinitions({
+    properties,
+    propertiesDescriptions: propertiesDescriptions,
+    componentName: componentName,
+    showOptionalAbbr
+  });
+  return /*#__PURE__*/_jsxs(React.Fragment, {
+    children: [/*#__PURE__*/_jsxs(Box, {
+      sx: {
+        display: 'flex',
+        alignItems: 'baseline',
+        mb: 1
+      },
+      children: [/*#__PURE__*/_jsx(SectionTitle, {
+        title: t(title),
+        hash: titleHash,
+        level: level
+      }), /*#__PURE__*/_jsx(ToggleDisplayOption, {
+        displayOption: displayOption,
+        setDisplayOption: setDisplayOption,
+        sectionType: "props"
+      })]
+    }), spreadHint && /*#__PURE__*/_jsx("p", {
+      dangerouslySetInnerHTML: {
+        __html: spreadHint
+      }
+    }), displayOption === 'table' ? /*#__PURE__*/_jsx(PropertiesTable, {
+      properties: formattedProperties
+    }) : /*#__PURE__*/_jsx(PropertiesList, {
+      properties: formattedProperties,
+      displayOption: displayOption
+    })]
+  });
+}

package/ApiPage/sections/SlotsSection.d.ts

@@ -0,0 +1,24 @@
+import { ComponentApiContent } from '@mui-internal/api-docs-builder';
+import { SlotDefinition } from "../definitions/types.js";
+import { type ApiDisplayLayout } from "./ToggleDisplayOption.js";
+export type SlotsSectionProps = ({
+  slots: SlotDefinition[];
+  componentSlots?: undefined;
+  slotDescriptions?: undefined;
+  componentName?: undefined;
+} | {
+  slots: undefined;
+  componentSlots: ComponentApiContent['slots'];
+  slotDescriptions: {
+    [key: string]: string;
+  };
+  componentName: string;
+}) & {
+  title?: string;
+  titleHash?: string;
+  level?: 'h2' | 'h3' | 'h4';
+  defaultLayout: ApiDisplayLayout;
+  layoutStorageKey: string;
+  spreadHint?: string;
+};
+export declare function SlotsSection(props: SlotsSectionProps): import("react/jsx-runtime").JSX.Element | null;

package/ApiPage/sections/SlotsSection.js

@@ -0,0 +1,61 @@
+/* eslint-disable react/no-danger */
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import { useTranslate } from "../../i18n/index.js";
+import { SectionTitle } from "../../SectionTitle/index.js";
+import SlotsList from "../list/SlotsList.js";
+import SlotsTable from "../table/SlotsTable.js";
+import { ToggleDisplayOption, useApiPageOption } from "./ToggleDisplayOption.js";
+import { getSlotsApiDefinitions } from "../definitions/slots.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function SlotsSection(props) {
+  const {
+    slots,
+    componentSlots,
+    slotDescriptions,
+    componentName,
+    title = 'api-docs.slots',
+    titleHash = 'slots',
+    level = 'h2',
+    spreadHint,
+    defaultLayout,
+    layoutStorageKey
+  } = props;
+  const t = useTranslate();
+  const [displayOption, setDisplayOption] = useApiPageOption(layoutStorageKey, defaultLayout);
+  const formattedSlots = slots ?? getSlotsApiDefinitions({
+    componentSlots,
+    slotDescriptions,
+    componentName
+  });
+  if (!formattedSlots || formattedSlots.length === 0) {
+    return null;
+  }
+  return /*#__PURE__*/_jsxs(React.Fragment, {
+    children: [/*#__PURE__*/_jsxs(Box, {
+      sx: {
+        display: 'flex',
+        alignItems: 'baseline',
+        mb: 1
+      },
+      children: [/*#__PURE__*/_jsx(SectionTitle, {
+        title: t(title),
+        hash: titleHash,
+        level: level
+      }), /*#__PURE__*/_jsx(ToggleDisplayOption, {
+        displayOption: displayOption,
+        setDisplayOption: setDisplayOption,
+        sectionType: "slots"
+      })]
+    }), spreadHint && /*#__PURE__*/_jsx("p", {
+      dangerouslySetInnerHTML: {
+        __html: spreadHint
+      }
+    }), displayOption === 'table' ? /*#__PURE__*/_jsx(SlotsTable, {
+      slots: formattedSlots
+    }) : /*#__PURE__*/_jsx(SlotsList, {
+      slots: formattedSlots,
+      displayOption: displayOption
+    })]
+  });
+}

package/ApiPage/sections/ToggleDisplayOption.d.ts

@@ -0,0 +1,17 @@
+export type ApiDisplayLayout = 'collapsed' | 'expanded' | 'table';
+export declare const DEFAULT_API_LAYOUT_STORAGE_KEYS: {
+  readonly slots: "apiPage_slots";
+  readonly props: "apiPage_props";
+  readonly classes: "apiPage_classes";
+};
+export declare function useApiPageOption(storageKey: string, defaultValue: ApiDisplayLayout): [ApiDisplayLayout, (newOption: ApiDisplayLayout) => void];
+interface ToggleDisplayOptionProps {
+  displayOption: ApiDisplayLayout;
+  setDisplayOption: (newValue: ApiDisplayLayout) => void;
+  /**
+   * The type of section. This value is used to send correct event to Google Analytics.
+   */
+  sectionType: 'classes' | 'props' | 'slots';
+}
+export declare function ToggleDisplayOption(props: ToggleDisplayOptionProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/ApiPage/sections/ToggleDisplayOption.js

@@ -0,0 +1,158 @@
+var _ArrowDropDownRounded;
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Menu from '@mui/material/Menu';
+import MenuItem from '@mui/material/MenuItem';
+import CheckIcon from '@mui/icons-material/Check';
+import ArrowDropDownRoundedIcon from '@mui/icons-material/ArrowDropDownRounded';
+import useEnhancedEffect from '@mui/utils/useEnhancedEffect';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const options = ['collapsed', 'expanded', 'table'];
+export const DEFAULT_API_LAYOUT_STORAGE_KEYS = {
+  slots: 'apiPage_slots',
+  props: 'apiPage_props',
+  classes: 'apiPage_classes'
+};
+let neverHydrated = true;
+function getOption(storageKey, defaultValue) {
+  if (neverHydrated) {
+    return defaultValue;
+  }
+  try {
+    const savedOption = localStorage.getItem(storageKey);
+    if (savedOption !== null && options.includes(savedOption)) {
+      return savedOption;
+    }
+  } catch (error) {
+    return defaultValue;
+  }
+  return defaultValue;
+}
+export function useApiPageOption(storageKey, defaultValue) {
+  const [option, setOption] = React.useState(getOption(storageKey, defaultValue));
+  useEnhancedEffect(() => {
+    // TODO: uncomment once we enable eslint-plugin-react-compiler // eslint-disable-next-line react-compiler/react-compiler -- useEnhancedEffect uses useEffect under the hood
+    neverHydrated = false;
+    const newOption = getOption(storageKey, defaultValue);
+    setOption(newOption);
+  }, [storageKey, defaultValue]);
+  React.useEffect(() => {
+    if (option !== defaultValue) {
+      const id = document.location.hash.slice(1);
+      const element = document.getElementById(id);
+      element?.scrollIntoView();
+    }
+    return undefined;
+  }, [option, defaultValue]);
+  const updateOption = React.useCallback(newOption => {
+    try {
+      localStorage.setItem(storageKey, newOption);
+    } catch (error) {
+      // Do nothing
+    }
+    setOption(newOption);
+  }, [storageKey]);
+  return [option, updateOption];
+}
+export function ToggleDisplayOption(props) {
+  const {
+    displayOption,
+    setDisplayOption,
+    sectionType
+  } = props;
+  const [anchorEl, setAnchorEl] = React.useState(null);
+  const [open, setOpen] = React.useState(false);
+  const handleMenuClick = event => {
+    setAnchorEl(event.currentTarget);
+    setOpen(true);
+  };
+  const handleClose = () => {
+    setAnchorEl(null);
+    setOpen(false);
+  };
+  const handleMenuItemClick = newDisplayOption => {
+    setDisplayOption(newDisplayOption);
+    handleClose();
+  };
+  return /*#__PURE__*/_jsxs(React.Fragment, {
+    children: [/*#__PURE__*/_jsxs(Button, {
+      size: "small",
+      variant: "outlined",
+      color: "secondary",
+      id: "view-switching-button",
+      "aria-controls": open ? 'view-switching-button' : undefined,
+      "aria-haspopup": "true",
+      "aria-expanded": open ? 'true' : undefined,
+      onClick: handleMenuClick,
+      endIcon: _ArrowDropDownRounded || (_ArrowDropDownRounded = /*#__PURE__*/_jsx(ArrowDropDownRoundedIcon, {})),
+      sx: {
+        height: '1.875rem',
+        p: '6px 4px 6px 8px',
+        textTransform: 'capitalize'
+      },
+      children: [/*#__PURE__*/_jsx(Box, {
+        component: "span",
+        sx: {
+          fontWeight: 'medium',
+          mr: 0.5
+        },
+        children: 'View:'
+      }), displayOption]
+    }), /*#__PURE__*/_jsxs(Menu, {
+      id: "view-options-menu",
+      anchorEl: anchorEl,
+      open: open,
+      onClose: handleClose,
+      sx: {
+        mt: 1,
+        '.MuiMenuItem-root': {
+          pl: 1
+        }
+      },
+      children: [/*#__PURE__*/_jsxs(MenuItem, {
+        value: "table",
+        onClick: () => handleMenuItemClick('table'),
+        selected: displayOption === 'table',
+        "data-ga-event-category": "layout",
+        "data-ga-event-action": sectionType,
+        "data-ga-event-label": "table",
+        children: ['Table', /*#__PURE__*/_jsx(CheckIcon, {
+          sx: {
+            fontSize: '0.85rem',
+            ml: 'auto',
+            opacity: displayOption === 'table' ? 1 : 0
+          }
+        })]
+      }), /*#__PURE__*/_jsxs(MenuItem, {
+        value: "expanded",
+        onClick: () => handleMenuItemClick('expanded'),
+        selected: displayOption === 'expanded',
+        "data-ga-event-category": "layout",
+        "data-ga-event-action": sectionType,
+        "data-ga-event-label": "expanded",
+        children: ['Expanded list', /*#__PURE__*/_jsx(CheckIcon, {
+          sx: {
+            fontSize: '0.85rem',
+            ml: 'auto',
+            opacity: displayOption === 'expanded' ? 1 : 0
+          }
+        })]
+      }), /*#__PURE__*/_jsxs(MenuItem, {
+        value: "collapsed",
+        onClick: () => handleMenuItemClick('collapsed'),
+        selected: displayOption === 'collapsed',
+        "data-ga-event-category": "layout",
+        "data-ga-event-action": sectionType,
+        "data-ga-event-label": "collapsed",
+        children: ['Collapsed list', /*#__PURE__*/_jsx(CheckIcon, {
+          sx: {
+            fontSize: '0.85rem',
+            ml: 'auto',
+            opacity: displayOption === 'collapsed' ? 1 : 0
+          }
+        })]
+      })]
+    })]
+  });
+}

package/ApiPage/sections/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./ToggleDisplayOption.js";
+export * from "./PropertiesSection.js";
+export * from "./ClassesSection.js";
+export * from "./SlotsSection.js";

package/ApiPage/sections/index.js

@@ -0,0 +1,4 @@
+export * from "./ToggleDisplayOption.js";
+export * from "./PropertiesSection.js";
+export * from "./ClassesSection.js";
+export * from "./SlotsSection.js";

package/ApiPage/table/ClassesTable.d.ts

@@ -0,0 +1,7 @@
+import { ClassDefinition } from "../definitions/types.js";
+interface ClassesTableProps {
+  classes: ClassDefinition[];
+  displayClassKeys?: boolean;
+}
+export default function ClassesTable(props: ClassesTableProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/ApiPage/table/ClassesTable.js

@@ -0,0 +1,116 @@
+var _th, _th2, _th3;
+/* eslint-disable react/no-danger */
+import * as React from 'react';
+import { styled, alpha } from '@mui/material/styles';
+import { brandingDarkTheme as darkTheme, brandingLightTheme as lightTheme } from "../../branding/index.js";
+import { useTranslate } from "../../i18n/index.js";
+import { StyledTableContainer } from "./StyledTableContainer.js";
+import { ApiWarningAlert } from "../ApiWarningAlert.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const StyledTable = styled('table')(({
+  theme
+}) => ({
+  textAlign: 'left',
+  // Override docs/src/modules/components/MarkdownElement styles
+  '&&': {
+    display: 'table',
+    width: '100%'
+  },
+  '& .class-name': {
+    flexShrink: 0,
+    fontWeight: theme.typography.fontWeightSemiBold,
+    fontFamily: theme.typography.fontFamilyCode,
+    fontSize: theme.typography.pxToRem(13),
+    color: `var(--muidocs-palette-primary-600, ${lightTheme.palette.primary[600]})`
+  },
+  '& .class-key': {
+    ...theme.typography.caption,
+    fontFamily: theme.typography.fontFamilyCode,
+    fontWeight: theme.typography.fontWeightRegular,
+    color: `var(--muidocs-palette-text-primary, ${lightTheme.palette.text.primary})`,
+    padding: '1px 4px',
+    borderRadius: 6,
+    border: '1px solid',
+    borderColor: alpha(darkTheme.palette.primary[100], 0.8),
+    backgroundColor: `var(--muidocs-palette-primary-50, ${lightTheme.palette.primary[50]})`
+  }
+}), ({
+  theme
+}) => ({
+  [`:where(${theme.vars ? '[data-mui-color-scheme="dark"]' : '.mode-dark'}) &`]: {
+    '& .class-name': {
+      color: `var(--muidocs-palette-primary-200, ${darkTheme.palette.primary[200]})`
+    },
+    '& .class-key': {
+      color: `var(--muidocs-palette-text-primary, ${darkTheme.palette.text.primary})`,
+      borderColor: alpha(darkTheme.palette.primary[400], 0.1),
+      backgroundColor: alpha(darkTheme.palette.primary[900], 0.4)
+    }
+  }
+}));
+export default function ClassesTable(props) {
+  const {
+    classes,
+    displayClassKeys
+  } = props;
+  const t = useTranslate();
+  return /*#__PURE__*/_jsx(StyledTableContainer, {
+    children: /*#__PURE__*/_jsxs(StyledTable, {
+      children: [/*#__PURE__*/_jsx("thead", {
+        children: /*#__PURE__*/_jsxs("tr", {
+          children: [_th || (_th = /*#__PURE__*/_jsx("th", {
+            children: 'Class name'
+          })), displayClassKeys && (_th2 || (_th2 = /*#__PURE__*/_jsx("th", {
+            children: 'Rule name'
+          }))), _th3 || (_th3 = /*#__PURE__*/_jsx("th", {
+            children: 'Description'
+          }))]
+        })
+      }), /*#__PURE__*/_jsx("tbody", {
+        children: classes.map(params => {
+          const {
+            className,
+            hash,
+            key,
+            description,
+            isGlobal,
+            isDeprecated,
+            deprecationInfo
+          } = params;
+          return /*#__PURE__*/_jsxs("tr", {
+            id: hash,
+            children: [/*#__PURE__*/_jsx("td", {
+              className: "algolia-lvl3",
+              children: /*#__PURE__*/_jsxs("span", {
+                className: "class-name",
+                children: [".", className]
+              })
+            }), displayClassKeys && /*#__PURE__*/_jsx("td", {
+              children: !isGlobal && /*#__PURE__*/_jsx("span", {
+                className: "class-key",
+                children: key
+              })
+            }), /*#__PURE__*/_jsxs("td", {
+              className: "algolia-content",
+              children: [/*#__PURE__*/_jsx("span", {
+                dangerouslySetInnerHTML: {
+                  __html: description || ''
+                }
+              }), isDeprecated && /*#__PURE__*/_jsxs(ApiWarningAlert, {
+                children: [/*#__PURE__*/_jsx("b", {
+                  children: t('api-docs.deprecated')
+                }), deprecationInfo && /*#__PURE__*/_jsxs(React.Fragment, {
+                  children: ['－', /*#__PURE__*/_jsx("span", {
+                    dangerouslySetInnerHTML: {
+                      __html: deprecationInfo
+                    }
+                  })]
+                })]
+              })]
+            })]
+          }, className);
+        })
+      })]
+    })
+  });
+}

package/ApiPage/table/PropertiesTable.d.ts

@@ -0,0 +1,6 @@
+import type { PropertyDefinition } from "../definitions/types.js";
+interface PropertiesTableProps {
+  properties: PropertyDefinition[];
+}
+export default function PropertiesTable(props: PropertiesTableProps): import("react/jsx-runtime").JSX.Element;
+export {};