@mui/docs 6.0.0-dev.240424162023-9968b4889d → 6.0.0

package/Ad/Ad.d.ts

@@ -0,0 +1,6 @@
+import * as React from 'react';
+export declare const AD_MARGIN_TOP = 3;
+export declare const AD_MARGIN_BOTTOM = 3;
+export declare const AD_HEIGHT = 126;
+export declare const AD_HEIGHT_MOBILE: number;
+export declare function Ad(): React.JSX.Element;

package/Ad/Ad.js

@@ -0,0 +1,228 @@
+var _span, _PleaseDisableAdblock, _AdCarbon;
+import * as React from 'react';
+import Typography from '@mui/material/Typography';
+import Box from '@mui/material/Box';
+import Paper from '@mui/material/Paper';
+import { useTranslate } from "../i18n/index.js";
+import AdCarbon from "./AdCarbon.js";
+import AdInHouse from "./AdInHouse.js";
+import { AdContext, adShape } from "./AdManager.js";
+import { useAdConfig } from "./AdProvider.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function PleaseDisableAdblock() {
+  const t = useTranslate();
+  return /*#__PURE__*/_jsxs(Paper, {
+    component: "span",
+    elevation: 0,
+    sx: {
+      display: 'block',
+      p: 1.5,
+      border: '2px solid',
+      borderColor: 'primary.main'
+    },
+    children: [/*#__PURE__*/_jsx(Typography, {
+      variant: "body2",
+      component: "span",
+      gutterBottom: true,
+      sx: {
+        display: 'block'
+      },
+      children: t('likeMui')
+    }), /*#__PURE__*/_jsx(Typography, {
+      variant: "body2",
+      component: "span",
+      gutterBottom: true,
+      sx: {
+        display: 'block'
+      },
+      children: t('adblock')
+    }), /*#__PURE__*/_jsxs(Typography, {
+      variant: "body2",
+      component: "span",
+      sx: {
+        display: 'block'
+      },
+      children: [t('thanks'), ' ', /*#__PURE__*/_jsx("span", {
+        role: "img",
+        "aria-label": t('emojiLove'),
+        children: "\u2764\uFE0F"
+      })]
+    })]
+  });
+}
+const disableAd = process.env.NODE_ENV !== 'production' && process.env.ENABLE_AD_IN_DEV_MODE !== 'true';
+const inHouseAds = [{
+  name: 'scaffoldhub',
+  link: 'https://v2.scaffoldhub.io/scaffolds/react-material-ui?partner=1',
+  img: '/static/ads-in-house/scaffoldhub.png',
+  description: '<b>ScaffoldHub</b>. Automate building your full-stack Material UI web-app.'
+}, {
+  name: 'templates',
+  link: 'https://mui.com/store/?utm_source=docs&utm_medium=referral&utm_campaign=in-house-templates',
+  img: '/static/ads-in-house/themes-2.jpg',
+  description: '<b>Premium Templates</b>. Start your project with the best templates for admins, dashboards, and more.'
+}, {
+  name: 'themes',
+  link: 'https://mui.com/store/?utm_source=docs&utm_medium=referral&utm_campaign=in-house-themes',
+  img: '/static/ads-in-house/themes.png',
+  description: '<b>Premium Themes</b>. Kickstart your application development with a ready-made theme.'
+}, {
+  name: 'tidelift',
+  link: 'https://tidelift.com/subscription/pkg/npm-material-ui?utm_source=npm-material-ui&utm_medium=referral&utm_campaign=enterprise&utm_content=ad',
+  img: '/static/ads-in-house/tidelift.png',
+  description: '<b>MUI for enterprise</b>. Save time and reduce risk. Managed open source — backed by maintainers.'
+}, {
+  name: 'figma',
+  link: 'https://mui.com/store/items/figma-react/?utm_source=docs&utm_medium=referral&utm_campaign=in-house-figma',
+  img: '/static/ads-in-house/figma.png',
+  description: '<b>For Figma</b>. A large UI kit with over 600 handcrafted Material UI, MUI X, Joy UI components 🎨.'
+}];
+class AdErrorBoundary extends React.Component {
+  state = {
+    didError: false
+  };
+  static getDerivedStateFromError() {
+    return {
+      didError: true
+    };
+  }
+  componentDidCatch() {
+    // send explicit `'null'`
+    const eventLabel = String(this.props.eventLabel);
+    // TODO: Use proper error monitoring service (for example Sentry) instead
+
+    window.gtag('event', 'ad', {
+      eventAction: 'crash',
+      eventLabel
+    });
+  }
+  render() {
+    const {
+      didError
+    } = this.state;
+    const {
+      children
+    } = this.props;
+    if (didError) {
+      return null;
+    }
+    return children;
+  }
+}
+export const AD_MARGIN_TOP = 3;
+export const AD_MARGIN_BOTTOM = 3;
+export const AD_HEIGHT = 126;
+// Add more height on mobile as the text tends to wrap beyond the image height.
+export const AD_HEIGHT_MOBILE = 126 + 16;
+
+// https://stackoverflow.com/a/20084661
+function isBot() {
+  return /bot|googlebot|crawler|spider|robot|crawling/i.test(navigator.userAgent);
+}
+export function Ad() {
+  const [adblock, setAdblock] = React.useState(null);
+  const [carbonOut, setCarbonOut] = React.useState(null);
+  const {
+    current: randomAdblock
+  } = React.useRef(Math.random());
+  const {
+    current: randomInHouse
+  } = React.useRef(Math.random());
+  let children;
+  let label;
+  // Hide the content to google bot to avoid its indexation.
+  if (typeof window !== 'undefined' && isBot() || disableAd) {
+    children = _span || (_span = /*#__PURE__*/_jsx("span", {}));
+  } else if (adblock) {
+    if (randomAdblock < 0.2) {
+      children = _PleaseDisableAdblock || (_PleaseDisableAdblock = /*#__PURE__*/_jsx(PleaseDisableAdblock, {}));
+      label = 'in-house-adblock';
+    } else {
+      children = /*#__PURE__*/_jsx(AdInHouse, {
+        ad: inHouseAds[Math.floor(inHouseAds.length * randomInHouse)]
+      });
+      label = 'in-house';
+    }
+  } else if (carbonOut) {
+    children = /*#__PURE__*/_jsx(AdInHouse, {
+      ad: inHouseAds[Math.floor(inHouseAds.length * randomInHouse)]
+    });
+    label = 'in-house-carbon';
+  } else {
+    children = _AdCarbon || (_AdCarbon = /*#__PURE__*/_jsx(AdCarbon, {}));
+    label = 'carbon';
+  }
+  const ad = React.useContext(AdContext);
+  const eventLabel = label ? `${label}-${ad.placement}-${adShape}` : null;
+  const timerAdblock = React.useRef(undefined);
+  const checkAdblock = React.useCallback((attempt = 1) => {
+    if (document.querySelector('.ea-placement') || document.querySelector('#carbonads') || document.querySelector('.carbonads') || carbonOut) {
+      if (document.querySelector('#carbonads a') && document.querySelector('#carbonads a')?.getAttribute('href') === 'https://material-ui-next.com/discover-more/backers') {
+        setCarbonOut(true);
+      }
+      setAdblock(false);
+      return;
+    }
+    if (attempt < 30) {
+      timerAdblock.current = setTimeout(() => {
+        checkAdblock(attempt + 1);
+      }, 500);
+    }
+    if (attempt > 6) {
+      setAdblock(true);
+    }
+  }, [carbonOut]);
+  React.useEffect(() => {
+    if (disableAd) {
+      return undefined;
+    }
+    checkAdblock();
+    return () => {
+      clearTimeout(timerAdblock.current);
+    };
+  }, [checkAdblock]);
+  const {
+    GADisplayRatio
+  } = useAdConfig();
+  React.useEffect(() => {
+    // Avoid an exceed on the Google Analytics quotas.
+    if (Math.random() > (GADisplayRatio ?? 0.1) || !eventLabel) {
+      return undefined;
+    }
+    const delay = setTimeout(() => {
+      window.gtag('event', 'ad', {
+        eventAction: 'display',
+        eventLabel
+      });
+    }, 2500);
+    return () => {
+      clearTimeout(delay);
+    };
+  }, [GADisplayRatio, eventLabel]);
+  return /*#__PURE__*/_jsx(Box, {
+    component: "span",
+    sx: theme => ({
+      position: 'relative',
+      display: 'block',
+      mt: AD_MARGIN_TOP,
+      mb: AD_MARGIN_BOTTOM,
+      minHeight: AD_HEIGHT_MOBILE,
+      [theme.breakpoints.up('sm')]: {
+        minHeight: AD_HEIGHT
+      },
+      ...(adShape === 'image' && {}),
+      ...(adShape === 'inline' && {
+        display: 'flex',
+        alignItems: 'flex-end'
+      })
+    }),
+    "data-ga-event-category": "ad",
+    "data-ga-event-action": "click",
+    "data-ga-event-label": eventLabel,
+    className: "Ad-root",
+    children: /*#__PURE__*/_jsx(AdErrorBoundary, {
+      eventLabel: eventLabel,
+      children: children
+    })
+  });
+}

package/Ad/AdCarbon.d.ts

@@ -0,0 +1,3 @@
+import * as React from 'react';
+export declare function AdCarbonInline(): React.JSX.Element;
+export default function AdCarbon(): React.JSX.Element;

package/Ad/AdCarbon.js

@@ -0,0 +1,120 @@
+var _AdCarbonImage;
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import loadScript from "../utils/loadScript.js";
+import AdDisplay from "./AdDisplay.js";
+import { adBodyImageStyles } from "./ad.styles.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const CarbonRoot = styled('span')(({
+  theme
+}) => {
+  const styles = adBodyImageStyles(theme);
+  return {
+    width: '100%',
+    '& > div': {
+      // The isolation logic of carbonads is broken.
+      // Once the script starts loading, it will asynchronous resolve, with no way to stop it.
+      // This leads to duplication of the ad.
+      //
+      // To solve the issue, we only display the #carbonads div
+      display: 'none'
+    },
+    '& #carbonads': {
+      ...styles.root,
+      '& .carbon-img': styles.imgWrapper,
+      '& img': styles.img,
+      '& a, & a:hover': styles.a,
+      '& .carbon-text': styles.description,
+      '& .carbon-poweredby': styles.poweredby
+    }
+  };
+});
+function AdCarbonImage() {
+  const ref = React.useRef(null);
+  React.useEffect(() => {
+    // The isolation logic of carbonads is broken.
+    // Once the script starts loading, it will asynchronous resolve, with no way to stop it.
+    // This leads to duplication of the ad.
+    //
+    // To solve the issue, for example StrictModel double effect execution, we debounce the load action.
+    const load = setTimeout(() => {
+      const script = loadScript('https://cdn.carbonads.com/carbon.js?serve=CKYIL27L&placement=material-uicom', ref.current);
+      script.id = '_carbonads_js';
+    });
+    return () => {
+      clearTimeout(load);
+    };
+  }, []);
+  return /*#__PURE__*/_jsx(CarbonRoot, {
+    ref: ref
+  });
+}
+export function AdCarbonInline() {
+  const [ad, setAd] = React.useState(null);
+  React.useEffect(() => {
+    let active = true;
+    let attempt = 0;
+    (async () => {
+      async function tryFetch() {
+        if (attempt >= 10 || !active) {
+          return null;
+        }
+        attempt += 1;
+        let response;
+        try {
+          response = await fetch('https://srv.buysellads.com/ads/CE7DC23W.json');
+        } catch (err) {
+          // Ad blocker crashes this request
+          return null;
+        }
+        const data = await response.json();
+        // Inspired by https://github.com/Semantic-Org/Semantic-UI-React/blob/2c7134128925dd831de85011e3eb0ec382ba7f73/docs/src/components/CarbonAd/CarbonAdNative.js#L9
+        const sanitizedAd = data.ads.filter(item => Object.keys(item).length > 0).filter(item => item.statlink).filter(Boolean)[0];
+        if (!sanitizedAd) {
+          return tryFetch();
+        }
+        return sanitizedAd;
+      }
+      const sanitizedAd = await tryFetch();
+      if (active) {
+        setAd(sanitizedAd);
+      }
+    })();
+    return () => {
+      active = false;
+    };
+  }, []);
+  return ad ? /*#__PURE__*/_jsxs(React.Fragment, {
+    children: [/*#__PURE__*/_jsx("img", {
+      src: ad.statimp,
+      alt: "",
+      style: {
+        display: 'none'
+      }
+    }), ad.pixel && ad.pixel.split('||').map((pixel, i) => /*#__PURE__*/_jsx("img", {
+      src: `${pixel.replace('[timestamp]', ad.timestamp)}`,
+      style: {
+        display: 'none'
+      },
+      alt: ""
+    }, i)), /*#__PURE__*/_jsx(AdDisplay, {
+      className: "carbonads",
+      shape: "inline",
+      ad: {
+        link: ad.statlink,
+        img: ad.image,
+        name: ad.company,
+        description: `<strong>${ad.company}</strong> - ${ad.description}`,
+        poweredby: 'Carbon',
+        label: 'carbon-demo-inline'
+      }
+    })]
+  }) : /*#__PURE__*/_jsx("div", {
+    style: {
+      minHeight: 52
+    }
+  });
+}
+export default function AdCarbon() {
+  return _AdCarbonImage || (_AdCarbonImage = /*#__PURE__*/_jsx(AdCarbonImage, {}));
+}

package/Ad/AdDisplay.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+export interface AdParameters {
+    name: string;
+    link: string;
+    img?: string;
+    description: string;
+    poweredby: string;
+    label: string;
+}
+interface AdDisplayProps {
+    ad: AdParameters;
+    className?: string;
+    shape?: 'auto' | 'inline' | 'image';
+}
+export default function AdDisplay(props: AdDisplayProps): React.JSX.Element;
+export {};

package/Ad/AdDisplay.js

@@ -0,0 +1,89 @@
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import { useTranslate } from "../i18n/index.js";
+import { adShape } from "./AdManager.js";
+import { adBodyImageStyles, adBodyInlineStyles } from "./ad.styles.js";
+import { useAdConfig } from "./AdProvider.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const InlineShape = styled('span')(({
+  theme
+}) => {
+  const styles = adBodyInlineStyles(theme);
+  return {
+    ...styles.root,
+    '& img': styles.img,
+    '& a, & a:hover': styles.a,
+    '& .AdDisplay-imageWrapper': styles.imgWrapper,
+    '& .AdDisplay-description': styles.description,
+    '& .AdDisplay-poweredby': styles.poweredby
+  };
+});
+const ImageShape = styled('span')(({
+  theme
+}) => {
+  const styles = adBodyImageStyles(theme);
+  return {
+    ...styles.root,
+    '& img': styles.img,
+    '& a, & a:hover': styles.a,
+    '& .AdDisplay-imageWrapper': styles.imgWrapper,
+    '& .AdDisplay-description': styles.description,
+    '& .AdDisplay-poweredby': styles.poweredby
+  };
+});
+export default function AdDisplay(props) {
+  const {
+    ad,
+    className,
+    shape: shapeProp = 'auto'
+  } = props;
+  const t = useTranslate();
+  const {
+    GADisplayRatio
+  } = useAdConfig();
+  React.useEffect(() => {
+    // Avoid an exceed on the Google Analytics quotas.
+    if (Math.random() > (GADisplayRatio ?? 0.1) || !ad.label) {
+      return;
+    }
+    window.gtag('event', 'ad', {
+      eventAction: 'display',
+      eventLabel: ad.label
+    });
+  }, [GADisplayRatio, ad.label]);
+  const shape = shapeProp === 'auto' ? adShape : shapeProp;
+  const Root = shape === 'image' ? ImageShape : InlineShape;
+
+  /* eslint-disable react/no-danger */
+  return /*#__PURE__*/_jsxs(Root, {
+    className: className,
+    children: [/*#__PURE__*/_jsxs("a", {
+      href: ad.link,
+      target: "_blank",
+      rel: "noopener sponsored",
+      ...(ad.label ? {
+        'data-ga-event-category': 'ad',
+        'data-ga-event-action': 'click',
+        'data-ga-event-label': ad.label
+      } : {}),
+      children: [/*#__PURE__*/_jsx("span", {
+        className: "AdDisplay-imageWrapper",
+        children: /*#__PURE__*/_jsx("img", {
+          height: "100",
+          width: "130",
+          src: ad.img,
+          alt: ad.name
+        })
+      }), /*#__PURE__*/_jsx("span", {
+        className: "AdDisplay-description",
+        dangerouslySetInnerHTML: {
+          __html: ad.description
+        }
+      })]
+    }), /*#__PURE__*/_jsx("span", {
+      className: "AdDisplay-poweredby",
+      children: t('adPublisher').replace('{{publisher}}', ad.poweredby)
+    })]
+  });
+  /* eslint-enable react/no-danger */
+}

package/Ad/AdGuest.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+export interface AdGuestProps {
+    /**
+     * The querySelector use to target the element which will include the ad.
+     */
+    classSelector?: string;
+    children?: React.ReactNode | undefined;
+}
+declare function AdGuest(props: AdGuestProps): React.JSX.Element | null;
+export { AdGuest };

package/Ad/AdGuest.js

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import Portal from '@mui/material/Portal';
+import { AdContext } from "./AdManager.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+function AdGuest(props) {
+  const {
+    classSelector = '.description',
+    children
+  } = props;
+  const ad = React.useContext(AdContext);
+  if (!ad.element) {
+    return null;
+  }
+  return /*#__PURE__*/_jsx(Portal, {
+    container: () => {
+      const element = document.querySelector(classSelector);
+      if (element) {
+        if (ad.element === element) {
+          element.classList.add('ad');
+        } else {
+          element.classList.remove('ad');
+        }
+      }
+      return ad.element;
+    },
+    children: children
+  });
+}
+export { AdGuest };

package/Ad/AdInHouse.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+import { AdParameters } from './AdDisplay';
+export default function AdInHouse(props: {
+    ad: Omit<AdParameters, 'poweredby' | 'label'>;
+}): React.JSX.Element;

package/Ad/AdInHouse.js

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import AdDisplay from "./AdDisplay.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export default function AdInHouse(props) {
+  const {
+    ad
+  } = props;
+  return /*#__PURE__*/_jsx(AdDisplay, {
+    ad: {
+      poweredby: 'MUI',
+      label: `in-house-${ad.name}`,
+      ...ad
+    }
+  });
+}

package/Ad/AdManager.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+type AdPortal = {
+    placement: 'body-top';
+    element: Element | null;
+};
+interface AdManagerProps {
+    /**
+     * The querySelector use to target the element which will include the ad.
+     */
+    classSelector?: string;
+    children?: React.ReactNode | undefined;
+}
+export declare const AdContext: React.Context<AdPortal>;
+export declare const adShape: string;
+export declare function AdManager({ classSelector, children }: AdManagerProps): React.JSX.Element;
+export {};

package/Ad/AdManager.js

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { unstable_useEnhancedEffect as useEnhancedEffect } from '@mui/material/utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+export const AdContext = /*#__PURE__*/React.createContext({
+  placement: 'body-top',
+  element: null
+});
+
+// Persisted for the whole session.
+// The state is used to use different ad placements.
+const randomSession = Math.random();
+
+// Distribution profile:
+// 20% body-inline
+// 80% body-image
+export const adShape = randomSession < 0.2 ? 'inline' : 'image';
+export function AdManager({
+  classSelector = '.description',
+  children
+}) {
+  const [portal, setPortal] = React.useState({
+    placement: 'body-top',
+    element: null
+  });
+  useEnhancedEffect(() => {
+    const container = document.querySelector(classSelector);
+    setPortal({
+      placement: 'body-top',
+      element: container
+    });
+  }, [classSelector]);
+  return /*#__PURE__*/_jsx(AdContext.Provider, {
+    value: portal,
+    children: children
+  });
+}

package/Ad/AdProvider.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+export interface AdConfig {
+    /**
+     * The ratio of "ad display" event sent to Google Analytics.
+     * Used to avoid an exceed on the Google Analytics quotas.
+     * @default 0.1
+     */
+    GADisplayRatio: number;
+}
+export interface AdProviderProps {
+    children: React.ReactNode;
+    config?: Partial<AdConfig>;
+}
+export declare function AdProvider(props: AdProviderProps): React.JSX.Element;
+export declare function useAdConfig(): AdConfig;

package/Ad/AdProvider.js

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { jsx as _jsx } from "react/jsx-runtime";
+const AdConfigContext = /*#__PURE__*/React.createContext(null);
+export function AdProvider(props) {
+  const {
+    children,
+    config
+  } = props;
+  const value = React.useMemo(() => ({
+    GADisplayRatio: 0.1,
+    ...config
+  }), [config]);
+  return /*#__PURE__*/_jsx(AdConfigContext.Provider, {
+    value: value,
+    children: children
+  });
+}
+export function useAdConfig() {
+  const config = React.useContext(AdConfigContext);
+  if (!config) {
+    throw new Error('Could not find docs ad config context value; please ensure the component is wrapped in a <AdProvider>');
+  }
+  return config;
+}