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

package/ApiPage/ApiWarningAlert.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+interface ApiWarningAlertProps {
+  children?: React.ReactNode;
+  className?: string;
+}
+export declare function ApiWarningAlert({
+  children,
+  className
+}: ApiWarningAlertProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/ApiPage/ApiWarningAlert.js

@@ -0,0 +1,22 @@
+var _WarningRoundedIcon;
+import * as React from 'react';
+import Alert from '@mui/material/Alert';
+import WarningRoundedIcon from '@mui/icons-material/WarningRounded';
+import { jsx as _jsx } from "react/jsx-runtime";
+export function ApiWarningAlert({
+  children,
+  className
+}) {
+  return /*#__PURE__*/_jsx(Alert, {
+    severity: "warning",
+    className: className,
+    icon: _WarningRoundedIcon || (_WarningRoundedIcon = /*#__PURE__*/_jsx(WarningRoundedIcon, {
+      fontSize: "small"
+    })),
+    sx: {
+      fontSize: '0.875rem',
+      mt: '12px'
+    },
+    children: children
+  });
+}

package/ApiPage/definitions/classes.d.ts

@@ -0,0 +1,18 @@
+import type { PropsTranslations, ComponentApiContent } from '@mui-internal/api-docs-builder';
+import type { ClassDefinition, BaseCssTOCParams } from "./types.js";
+import type { TableOfContentsParams } from "../types.js";
+export declare const getClassesToc: ({
+  classes,
+  t,
+  hash,
+  componentName
+}: BaseCssTOCParams & {
+  classes: ClassDefinition[];
+  componentName?: string;
+}) => TableOfContentsParams[];
+export interface GetClassApiDefinitionsParams {
+  componentClasses: ComponentApiContent['classes'];
+  classDescriptions: PropsTranslations['classDescriptions'];
+  componentName: string;
+}
+export declare function getClassApiDefinitions(params: GetClassApiDefinitionsParams): ClassDefinition[];

package/ApiPage/definitions/classes.js

@@ -0,0 +1,54 @@
+import { kebabCase } from 'es-toolkit/string';
+export const getClassesToc = ({
+  classes,
+  t,
+  hash,
+  componentName
+}) => !classes || classes.length === 0 ? [] : [{
+  text: t('api-docs.classes'),
+  hash: hash ?? 'classes',
+  children: [...classes.map(({
+    key,
+    hash: classHash
+  }) => ({
+    text: key,
+    hash: componentName ? `${kebabCase(componentName)}-classes-${key}` : classHash,
+    children: []
+  }))]
+}];
+const errorMessage = (componentName, className, slotName) => `${className} description from component ${componentName} should include ${slotName} since its definition includes "{{${slotName}}}"`;
+export function getClassApiDefinitions(params) {
+  const {
+    componentClasses,
+    classDescriptions,
+    componentName
+  } = params;
+  return componentClasses.map(classDefinition => {
+    const {
+      conditions,
+      nodeName,
+      deprecationInfo,
+      description: translatedDescription
+    } = classDescriptions[classDefinition.key] ?? {}; // Not all classes have a description.
+
+    let description = translatedDescription ?? classDefinition.description;
+    if (description.includes('{{conditions}}')) {
+      if (!conditions) {
+        throw new Error(errorMessage(componentName, classDefinition.className, 'conditions'));
+      }
+      description = description.replace(/{{conditions}}/, conditions);
+    }
+    if (description.includes('{{nodeName}}')) {
+      if (!nodeName) {
+        throw new Error(errorMessage(componentName, classDefinition.className, 'nodeName'));
+      }
+      description = description.replace(/{{nodeName}}/, nodeName);
+    }
+    return {
+      ...classDefinition,
+      description,
+      deprecationInfo,
+      hash: `${kebabCase(componentName)}-classes-${classDefinition.className}`
+    };
+  });
+}

package/ApiPage/definitions/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./classes.js";
+export * from "./properties.js";
+export * from "./slots.js";
+export * from "./types.js";

package/ApiPage/definitions/index.js

@@ -0,0 +1,4 @@
+export * from "./classes.js";
+export * from "./properties.js";
+export * from "./slots.js";
+export * from "./types.js";

package/ApiPage/definitions/properties.d.ts

@@ -0,0 +1,58 @@
+import type { PropsTableItem, PropsTranslations, HookApiContent, HooksTranslations } from '@mui-internal/api-docs-builder';
+import type { BaseCssTOCParams, PropertyDefinition } from "./types.js";
+import type { TableOfContentsParams } from "../types.js";
+type GetPropertiesTocParams = BaseCssTOCParams & ({
+  properties: Array<Pick<PropertyDefinition, 'propName' | 'hash'>>;
+  componentProps?: never;
+  componentName?: never;
+} | {
+  componentProps: Record<string, unknown>;
+  componentName: string;
+  properties?: never;
+});
+export declare const getPropertiesToc: ({
+  properties,
+  componentProps,
+  componentName,
+  inheritance,
+  themeDefaultProps,
+  t,
+  hash
+}: GetPropertiesTocParams) => TableOfContentsParams;
+interface GetPropsApiDefinitionsParams {
+  componentName: string;
+  properties: {
+    [name: string]: PropsTableItem & {
+      /**
+       * Only to be compatible the time of the migration for X
+       */
+      isProPlan?: boolean;
+      /**
+       * Only to be compatible the time of the migration for X
+       */
+      isPremiumPlan?: boolean;
+    };
+  };
+  propertiesDescriptions: PropsTranslations['propDescriptions'];
+  /**
+   * Add indicators that the properties is optional instead of showing it is required.
+   */
+  showOptionalAbbr?: boolean;
+}
+export declare function getPropsApiDefinitions(params: GetPropsApiDefinitionsParams): PropertyDefinition[];
+interface HookCommonApiParams {
+  hookName: string;
+  showOptionalAbbr?: boolean;
+}
+interface GetHookReturnApiDefinitionsParams extends HookCommonApiParams {
+  kind: 'return';
+  properties: HookApiContent['returnValue'];
+  translations: HooksTranslations['returnValueDescriptions'];
+}
+interface GetHookParametersApiDefinitions extends HookCommonApiParams {
+  kind: 'parameters';
+  properties: HookApiContent['parameters'];
+  translations: HooksTranslations['parametersDescriptions'];
+}
+export declare function getHookApiDefinitions(params: GetHookReturnApiDefinitionsParams | GetHookParametersApiDefinitions): PropertyDefinition[];
+export {};

package/ApiPage/definitions/properties.js

@@ -0,0 +1,110 @@
+import { kebabCase } from 'es-toolkit/string';
+export const getPropertiesToc = ({
+  properties,
+  componentProps,
+  componentName,
+  inheritance,
+  themeDefaultProps,
+  t,
+  hash
+}) => {
+  const resolvedProperties = properties ?? Object.keys(componentProps).map(propName => ({
+    propName,
+    hash: `${kebabCase(componentName)}-prop-${propName}`
+  }));
+  return {
+    text: t('api-docs.props'),
+    hash: hash ?? '',
+    children: [...resolvedProperties.map(({
+      propName,
+      hash: propertyHash
+    }) => ({
+      text: propName,
+      hash: propertyHash,
+      children: []
+    })), ...(inheritance ? [{
+      text: t('api-docs.inheritance'),
+      hash: 'inheritance',
+      children: []
+    }] : []), ...(themeDefaultProps ? [{
+      text: t('api-docs.themeDefaultProps'),
+      hash: 'theme-default-props',
+      children: []
+    }] : [])]
+  };
+};
+export function getPropsApiDefinitions(params) {
+  const {
+    properties,
+    propertiesDescriptions,
+    componentName,
+    showOptionalAbbr = false
+  } = params;
+  return Object.entries(properties).map(([propName, propData]) => {
+    const isRequired = propData.required && !showOptionalAbbr;
+    const isOptional = !propData.required && showOptionalAbbr;
+    const isDeprecated = propData.deprecated;
+    const deprecationInfo = propData.deprecationInfo;
+    const typeName = propData.type?.description || propData.type.name;
+    const propDefault = propData.default;
+    const propDescription = propertiesDescriptions[propName];
+    const additionalInfo = ['cssApi', 'sx', 'slotsApi', 'joy-size', 'joy-color', 'joy-variant'].filter(key => propData.additionalInfo?.[key]);
+    const seeMoreDescription = propDescription?.seeMoreText && propData.seeMoreLink && propDescription.seeMoreText.replace('{{link}}', `<a href="${propData.seeMoreLink.url}">${propData.seeMoreLink.text}</a>`);
+    const signature = propData.signature?.type;
+    const signatureArgs = propData.signature?.describedArgs?.map(argName => ({
+      argName,
+      argDescription: propertiesDescriptions[propName].typeDescriptions?.[argName].description,
+      argType: propertiesDescriptions[propName].typeDescriptions?.[argName]?.argType,
+      argTypeDescription: propertiesDescriptions[propName].typeDescriptions?.[argName]?.argTypeDescription
+    }));
+    const signatureReturnDescription = propData.signature?.returned && propertiesDescriptions[propName].typeDescriptions?.[propData.signature.returned].argTypeDescription;
+    return {
+      hash: `${kebabCase(componentName)}-prop-${propName}`,
+      propName,
+      seeMoreDescription,
+      description: propDescription?.description,
+      requiresRef: propDescription?.requiresRef,
+      isOptional,
+      isRequired,
+      isDeprecated,
+      deprecationInfo,
+      typeName,
+      propDefault,
+      additionalInfo,
+      signature,
+      signatureArgs,
+      signatureReturnDescription,
+      isProPlan: propData.isProPlan,
+      isPremiumPlan: propData.isPremiumPlan
+    };
+  });
+}
+export function getHookApiDefinitions(params) {
+  const {
+    properties,
+    translations,
+    hookName,
+    kind,
+    showOptionalAbbr
+  } = params;
+  return Object.entries(properties).map(([propName, propData]) => {
+    const isRequired = propData.required && !showOptionalAbbr;
+    const isOptional = !propData.required && showOptionalAbbr;
+    const isDeprecated = propData.deprecated;
+    const deprecationInfo = propData.deprecationInfo;
+    const typeName = propData.type?.description || propData.type.name;
+    const propDefault = propData.default;
+    const propDescription = translations[propName];
+    return {
+      hash: `${kebabCase(hookName)}-${kind === 'parameters' ? 'parameters' : 'return-value'}-${propName}`,
+      propName,
+      description: propDescription?.description,
+      isRequired,
+      isOptional,
+      isDeprecated,
+      deprecationInfo,
+      typeName,
+      propDefault
+    };
+  });
+}

package/ApiPage/definitions/slots.d.ts

@@ -0,0 +1,16 @@
+import type { PropsTranslations, ComponentApiContent } from '@mui-internal/api-docs-builder';
+import type { BaseCssTOCParams, SlotDefinition } from "./types.js";
+import type { TableOfContentsParams } from "../types.js";
+export interface GetSlotsApiDefinitionsParams {
+  componentSlots: ComponentApiContent['slots'];
+  slotDescriptions: PropsTranslations['slotDescriptions'];
+  componentName: string;
+}
+export declare function getSlotsApiDefinitions(params: GetSlotsApiDefinitionsParams): SlotDefinition[];
+export declare const getSlotsToc: ({
+  slots,
+  t,
+  hash
+}: BaseCssTOCParams & {
+  slots: SlotDefinition[];
+}) => TableOfContentsParams[];

package/ApiPage/definitions/slots.js

@@ -0,0 +1,39 @@
+export function getSlotsApiDefinitions(params) {
+  const {
+    componentSlots,
+    slotDescriptions,
+    componentName
+  } = params;
+  if (!componentSlots) {
+    return [];
+  }
+  return componentSlots.map(({
+    class: className,
+    name,
+    default: defaultValue
+  }) => {
+    return {
+      description: slotDescriptions?.[name],
+      className,
+      name,
+      defaultValue,
+      hash: `${componentName}-css-${className ?? name}`
+    };
+  });
+}
+export const getSlotsToc = ({
+  slots,
+  t,
+  hash
+}) => !slots || slots.length === 0 ? [] : [{
+  text: t('api-docs.slots'),
+  hash: hash ?? 'slots',
+  children: [...slots.map(({
+    name,
+    hash: slotHash
+  }) => ({
+    text: name,
+    hash: slotHash,
+    children: []
+  }))]
+}];

package/ApiPage/definitions/types.d.ts

@@ -0,0 +1,53 @@
+import type { Translate } from "../../i18n/index.js";
+export type ClassDefinition = {
+  className: string;
+  key: string;
+  hash: string;
+  description?: string;
+  isGlobal?: boolean;
+  isDeprecated?: boolean;
+  deprecationInfo?: string;
+};
+export type PropertyDefinition = {
+  additionalInfo?: string[];
+  hash: string;
+  deprecationInfo?: string;
+  description?: string;
+  isDeprecated?: boolean;
+  isOptional?: boolean;
+  isRequired?: boolean;
+  propDefault?: string;
+  propName: string;
+  requiresRef?: boolean;
+  seeMoreDescription?: string;
+  signature?: string;
+  signatureArgs?: {
+    argName: string;
+    argDescription?: string;
+    argType?: string;
+    argTypeDescription?: string;
+  }[];
+  signatureReturnDescription?: string;
+  typeName: string;
+  /**
+   * Used by MUI X interface documentation
+   */
+  isProPlan?: boolean;
+  /**
+   * Used by MUI X interface documentation
+   */
+  isPremiumPlan?: boolean;
+};
+export type SlotDefinition = {
+  className: string | null;
+  hash: string;
+  description?: string;
+  name: string;
+  defaultValue?: string;
+};
+export type BaseCssTOCParams = {
+  inheritance?: boolean;
+  themeDefaultProps?: boolean;
+  t: Translate;
+  hash?: string;
+};

package/ApiPage/definitions/types.js

@@ -0,0 +1 @@
+export {};

package/ApiPage/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ApiWarningAlert.js";
+export type { LayoutStorageKeys, TableOfContentsParams } from "./types.js";

package/ApiPage/index.js

@@ -0,0 +1,2 @@
+export * from "./ApiWarningAlert.js";
+export {};

package/ApiPage/list/ClassesList.d.ts

@@ -0,0 +1,11 @@
+import { ClassDefinition } from "../definitions/types.js";
+type ClassesListProps = {
+  classes: ClassDefinition[];
+  displayOption: 'collapsed' | 'expanded';
+  /**
+   * If `true` the the associated key in the classes object is visible.
+   */
+  displayClassKeys?: boolean;
+};
+export default function ClassesList(props: ClassesListProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/ApiPage/list/ClassesList.js

@@ -0,0 +1,103 @@
+var _span;
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import { useTranslate } from "../../i18n/index.js";
+import { brandingDarkTheme as darkTheme, brandingLightTheme as lightTheme } from "../../branding/index.js";
+import { ApiItemContainer, ExpandableApiItem } from "./ExpandableApiItem.js";
+import { ApiWarningAlert } from "../ApiWarningAlert.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const StyledApiItem = styled(ExpandableApiItem)(({
+  theme
+}) => ({
+  '& p': {
+    margin: 0
+  },
+  '& .prop-list-title': {
+    ...theme.typography.body2,
+    fontWeight: theme.typography.fontWeightSemiBold,
+    color: theme.palette.text.primary,
+    paddingRight: 5,
+    whiteSpace: 'nowrap',
+    margin: 0
+  },
+  '& .prop-list-class': {
+    margin: 0
+  },
+  '&.classes-list-deprecated-item': {
+    '& .MuiApi-item-note': {
+      color: `var(--muidocs-palette-warning-700, ${lightTheme.palette.warning[700]})`
+    }
+  }
+}), ({
+  theme
+}) => ({
+  [`:where(${theme.vars ? '[data-mui-color-scheme="dark"]' : '.mode-dark'}) &`]: {
+    '& .prop-list-title': {
+      color: `var(--muidocs-palette-grey-50, ${darkTheme.palette.grey[50]})`
+    },
+    '&.classes-list-deprecated-item': {
+      '& .MuiApi-item-note': {
+        color: `var(--muidocs-palette-warning-400, ${darkTheme.palette.warning[400]})`
+      }
+    }
+  }
+}));
+export default function ClassesList(props) {
+  const {
+    classes,
+    displayOption,
+    displayClassKeys
+  } = props;
+  const t = useTranslate();
+  return /*#__PURE__*/_jsx(ApiItemContainer, {
+    children: classes.map(classDefinition => {
+      const {
+        hash,
+        className,
+        key,
+        description,
+        isGlobal,
+        isDeprecated,
+        deprecationInfo
+      } = classDefinition;
+      let note = isGlobal ? t('api-docs.state') : '';
+      if (isDeprecated) {
+        note = [note, t('api-docs.deprecated')].filter(Boolean).join(' - ');
+      }
+      return /*#__PURE__*/_jsxs(StyledApiItem, {
+        id: hash,
+        note: note,
+        title: `.${className}`,
+        type: "classes",
+        displayOption: displayOption,
+        isExtendable: !!description,
+        className: isDeprecated ? 'classes-list-deprecated-item' : '',
+        children: [description && /*#__PURE__*/_jsx("p", {
+          dangerouslySetInnerHTML: {
+            __html: description
+          }
+        }), displayClassKeys && !isGlobal && /*#__PURE__*/_jsxs("p", {
+          className: "prop-list-class",
+          children: [_span || (_span = /*#__PURE__*/_jsxs("span", {
+            className: "prop-list-title",
+            children: ['Rule name', ":"]
+          })), /*#__PURE__*/_jsx("code", {
+            className: "Api-code",
+            children: key
+          })]
+        }), isDeprecated && /*#__PURE__*/_jsxs(ApiWarningAlert, {
+          children: [/*#__PURE__*/_jsx("b", {
+            children: t('api-docs.deprecated')
+          }), deprecationInfo && /*#__PURE__*/_jsxs(React.Fragment, {
+            children: ['－', /*#__PURE__*/_jsx("span", {
+              /* eslint-disable-next-line react/no-danger */
+              dangerouslySetInnerHTML: {
+                __html: deprecationInfo
+              }
+            })]
+          })]
+        })]
+      }, key);
+    })
+  });
+}

package/ApiPage/list/ExpandableApiItem.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { SxProps } from '@mui/material/styles';
+type DescriptionType = 'props' | 'classes' | 'CSS' | 'slots';
+type ExpandableApiItemProps = {
+  children?: React.ReactNode;
+  className?: string;
+  description?: string;
+  displayOption?: 'collapsed' | 'expanded';
+  id: string;
+  isExtendable?: boolean;
+  note?: string;
+  sx?: SxProps;
+  title: string | React.ReactNode;
+  type?: DescriptionType;
+};
+export declare function ExpandableApiItem(props: ExpandableApiItemProps): import("react/jsx-runtime").JSX.Element;
+export declare const ApiItemContainer: import("@emotion/styled").StyledComponent<import("@mui/system").MUIStyledCommonProps<import("@mui/material/styles").Theme>, React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export {};