@mui/internal-core-docs 0.0.1 → 9.0.0-canary.0

package/CodeCopy/CodeCopy.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+/**
+ * How to use: spread the handlers to the .MuiCode-root
+ *
+ * The html structure should be:
+ * <div className="MuiCode-root">
+ *  <pre>...</pre>
+ *  <button className="MuiCode-copy">...</button>
+ * </div>
+ */
+export declare function useCodeCopy(): React.HTMLAttributes<HTMLDivElement>;
+interface CodeCopyProviderProps {
+  children: React.ReactNode;
+}
+/**
+ * Place <CodeCopyProvider> at the page level. It will check the keydown event and try to initiate copy click if rootNode exist.
+ * Any code block inside the tree can set the rootNode when mouse enter to leverage keyboard copy.
+ */
+export declare function CodeCopyProvider({
+  children
+}: CodeCopyProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/CodeCopy/CodeCopy.js

@@ -0,0 +1,172 @@
+var _InitCodeCopy;
+import * as React from 'react';
+import { useRouter } from 'next/router';
+import clipboardCopy from 'clipboard-copy';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const CodeBlockContext = /*#__PURE__*/React.createContext({
+  current: null
+});
+
+/**
+ * How to use: spread the handlers to the .MuiCode-root
+ *
+ * The html structure should be:
+ * <div className="MuiCode-root">
+ *  <pre>...</pre>
+ *  <button className="MuiCode-copy">...</button>
+ * </div>
+ */
+export function useCodeCopy() {
+  const rootNode = React.useContext(CodeBlockContext);
+  return {
+    onMouseEnter: event => {
+      rootNode.current = event.currentTarget;
+    },
+    onMouseLeave: event => {
+      if (rootNode.current === event.currentTarget) {
+        rootNode.current.querySelector('.MuiCode-copy')?.blur();
+        rootNode.current = null;
+      }
+    },
+    onFocus: event => {
+      rootNode.current = event.currentTarget;
+    },
+    onBlur: event => {
+      if (rootNode.current === event.currentTarget) {
+        rootNode.current = null;
+      }
+    }
+  };
+}
+function InitCodeCopy() {
+  const rootNode = React.useContext(CodeBlockContext);
+  const router = useRouter();
+  React.useEffect(() => {
+    let key = 'Ctrl + ';
+    if (typeof window !== 'undefined') {
+      const macOS = window.navigator.platform.toUpperCase().includes('MAC');
+      if (macOS) {
+        key = '⌘';
+      }
+    }
+    const codeRoots = document.getElementsByClassName('MuiCode-root');
+    if (codeRoots !== null) {
+      const listeners = [];
+      Array.from(codeRoots).forEach(elm => {
+        const handleMouseEnter = () => {
+          rootNode.current = elm;
+        };
+        elm.addEventListener('mouseenter', handleMouseEnter);
+        listeners.push(() => elm.removeEventListener('mouseenter', handleMouseEnter));
+        const handleMouseLeave = () => {
+          if (rootNode.current === elm) {
+            rootNode.current.querySelector('.MuiCode-copy')?.blur();
+            rootNode.current = null;
+          }
+        };
+        elm.addEventListener('mouseleave', handleMouseLeave);
+        listeners.push(() => elm.removeEventListener('mouseleave', handleMouseLeave));
+        const handleFocusin = () => {
+          // use `focusin` because it bubbles from the copy button
+          rootNode.current = elm;
+        };
+        elm.addEventListener('focusin', handleFocusin);
+        listeners.push(() => elm.removeEventListener('focusin', handleFocusin));
+        const handleFocusout = () => {
+          // use `focusout` because it bubbles from the copy button
+          if (rootNode.current === elm) {
+            rootNode.current = null;
+          }
+        };
+        elm.addEventListener('focusout', handleFocusout);
+        listeners.push(() => elm.removeEventListener('focusout', handleFocusout));
+        async function handleClick(event) {
+          const trigger = event.currentTarget;
+          const pre = event.currentTarget?.previousElementSibling;
+          const textNode = trigger.childNodes[0];
+          textNode.nodeValue = textNode.textContent?.replace('Copy', 'Copied') || null;
+          trigger.dataset.copied = 'true';
+          setTimeout(() => {
+            if (trigger) {
+              textNode.nodeValue = textNode.textContent?.replace('Copied', 'Copy') || null;
+              delete trigger.dataset.copied;
+            }
+          }, 2000);
+          try {
+            if (pre.textContent) {
+              await clipboardCopy(pre.textContent);
+            }
+            // eslint-disable-next-line no-empty
+          } catch (error) {}
+        }
+        const btn = elm.querySelector('.MuiCode-copy');
+        if (btn) {
+          const keyNode = btn.querySelector('.MuiCode-copyKeypress')?.childNodes[1];
+          if (!keyNode) {
+            // skip the logic if the btn is not generated from the markdown.
+            return;
+          }
+          keyNode.textContent = keyNode?.textContent?.replace('$key', key) || null;
+          btn.addEventListener('click', handleClick);
+          listeners.push(() => btn.removeEventListener('click', handleClick));
+        }
+      });
+      return () => {
+        listeners.forEach(removeEventListener => {
+          removeEventListener();
+        });
+      };
+    }
+    return undefined;
+  }, [rootNode, router.pathname]);
+  return null;
+}
+function hasNativeSelection(element) {
+  if (window.getSelection()?.toString()) {
+    return true;
+  }
+
+  // window.getSelection() returns an empty string in Firefox for selections inside a form element.
+  // See: https://bugzilla.mozilla.org/show_bug.cgi?id=85686.
+  // Instead, we can use element.selectionStart that is only defined on form elements.
+  if (element && (element.selectionEnd || 0) - (element.selectionStart || 0) > 0) {
+    return true;
+  }
+  return false;
+}
+/**
+ * Place <CodeCopyProvider> at the page level. It will check the keydown event and try to initiate copy click if rootNode exist.
+ * Any code block inside the tree can set the rootNode when mouse enter to leverage keyboard copy.
+ */
+export function CodeCopyProvider({
+  children
+}) {
+  const rootNode = React.useRef(null);
+  React.useEffect(() => {
+    document.addEventListener('keydown', event => {
+      if (!rootNode.current) {
+        return;
+      }
+
+      // Skip if user is highlighting a text.
+      if (hasNativeSelection(event.target)) {
+        return;
+      }
+
+      // Skip if it's not a copy keyboard event
+      if (!((event.ctrlKey || event.metaKey) && String.fromCharCode(event.keyCode) === 'C' && !event.shiftKey && !event.altKey)) {
+        return;
+      }
+      const copyBtn = rootNode.current.querySelector('.MuiCode-copy');
+      const initialEventAction = copyBtn.getAttribute('data-ga-event-action');
+      // update the 'data-ga-event-action' on the button to track keyboard interaction
+      copyBtn.dataset.gaEventAction = initialEventAction?.replace('click', 'keyboard') || 'copy-keyboard';
+      copyBtn.click(); // let the GA setup in GoogleAnalytics.js do the job
+      copyBtn.dataset.gaEventAction = initialEventAction; // reset the 'data-ga-event-action' back to initial
+    });
+  }, []);
+  return /*#__PURE__*/_jsxs(CodeBlockContext.Provider, {
+    value: rootNode,
+    children: [_InitCodeCopy || (_InitCodeCopy = /*#__PURE__*/_jsx(InitCodeCopy, {})), children]
+  });
+}

package/CodeCopy/CodeCopyButton.d.ts

@@ -0,0 +1,4 @@
+export interface CodeCopyButtonProps {
+  code: string;
+}
+export declare function CodeCopyButton(props: CodeCopyButtonProps): import("react/jsx-runtime").JSX.Element;

package/CodeCopy/CodeCopyButton.js

@@ -0,0 +1,40 @@
+var _span, _span2;
+import useClipboardCopy from "./useClipboardCopy.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function CodeCopyButton(props) {
+  const {
+    code,
+    ...other
+  } = props;
+  const {
+    copy,
+    isCopied
+  } = useClipboardCopy();
+  // This component is designed to be wrapped in NoSsr
+  const macOS = window.navigator.platform.toUpperCase().includes('MAC');
+  const key = macOS ? '⌘' : 'Ctrl + ';
+  return /*#__PURE__*/_jsx("div", {
+    className: "MuiCode-copy-container",
+    children: /*#__PURE__*/_jsxs("button", {
+      ...other,
+      "aria-label": "Copy the code",
+      type: "button",
+      className: "MuiCode-copy",
+      onClick: async () => {
+        // event.stopPropagation();
+        await copy(code);
+      },
+      children: [isCopied ? 'Copied' : 'Copy', /*#__PURE__*/_jsxs("span", {
+        className: "MuiCode-copyKeypress",
+        style: {
+          opacity: isCopied ? 0 : 1
+        },
+        children: [_span || (_span = /*#__PURE__*/_jsx("span", {
+          children: "(or"
+        })), " ", key, "C", _span2 || (_span2 = /*#__PURE__*/_jsx("span", {
+          children: ")"
+        }))]
+      })]
+    })
+  });
+}

package/CodeCopy/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./CodeCopy.js";
+export * from "./CodeCopyButton.js";
+export { default as useClipboardCopy } from "./useClipboardCopy.js";

package/CodeCopy/index.js

@@ -0,0 +1,3 @@
+export * from "./CodeCopy.js";
+export * from "./CodeCopyButton.js";
+export { default as useClipboardCopy } from "./useClipboardCopy.js";

package/CodeCopy/useClipboardCopy.d.ts

@@ -0,0 +1,4 @@
+export default function useClipboardCopy(): {
+  copy: (text: string) => Promise<void>;
+  isCopied: boolean;
+};

package/CodeCopy/useClipboardCopy.js

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import clipboardCopy from 'clipboard-copy';
+export default function useClipboardCopy() {
+  const [isCopied, setIsCopied] = React.useState(false);
+  const timeout = React.useRef(undefined);
+  React.useEffect(() => () => {
+    clearTimeout(timeout.current);
+  }, []);
+  const copy = async text => {
+    await clipboardCopy(text);
+    setIsCopied(true);
+    clearTimeout(timeout.current);
+    timeout.current = setTimeout(() => {
+      setIsCopied(false);
+    }, 1200);
+  };
+  return {
+    copy,
+    isCopied
+  };
+}

package/ComponentLinkHeader/ComponentLinkHeader.d.ts

@@ -0,0 +1,8 @@
+import { MarkdownHeaders } from '@mui/internal-markdown';
+export interface ComponentLinkHeaderProps {
+  design?: boolean;
+  markdown: {
+    headers: MarkdownHeaders;
+  };
+}
+export declare function ComponentLinkHeader(props: ComponentLinkHeaderProps): import("react/jsx-runtime").JSX.Element;

package/ComponentLinkHeader/ComponentLinkHeader.js

@@ -0,0 +1,197 @@
+var _MarkdownIcon, _ChatRounded, _BundleSizeIcon, _GitHubIcon, _W3CIcon, _MaterialDesignIcon, _li, _li2;
+import * as React from 'react';
+import { useRouter } from 'next/router';
+import Chip from '@mui/material/Chip';
+import Tooltip from '@mui/material/Tooltip';
+import ChatRounded from '@mui/icons-material/ChatRounded';
+import GitHubIcon from '@mui/icons-material/GitHub';
+import { styled } from '@mui/material/styles';
+import MarkdownIcon from "../svgIcons/MarkdownIcon.js";
+import SketchIcon from "../svgIcons/SketchIcon.js";
+import FigmaIcon from "../svgIcons/FigmaIcon.js";
+import BundleSizeIcon from "../svgIcons/BundleSizeIcon.js";
+import W3CIcon from "../svgIcons/W3CIcon.js";
+import MaterialDesignIcon from "../svgIcons/MaterialDesignIcon.js";
+import { useTranslate } from "../i18n/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const Root = styled('ul')(({
+  theme
+}) => ({
+  margin: theme.spacing(2, 0),
+  padding: 0,
+  listStyle: 'none',
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 8,
+  '& .MuiChip-root': {
+    height: 26,
+    padding: '0 8px',
+    gap: 6,
+    '& .MuiChip-label': {
+      padding: 0
+    },
+    '& .MuiChip-iconSmall': {
+      margin: 0,
+      fontSize: 14
+    }
+  }
+}));
+const defaultPackageNames = {
+  'material-ui': '@mui/material',
+  'joy-ui': '@mui/joy',
+  'base-ui': '@mui/base',
+  system: '@mui/system'
+};
+export function ComponentLinkHeader(props) {
+  const {
+    markdown: {
+      headers
+    },
+    design
+  } = props;
+  const t = useTranslate();
+  const router = useRouter();
+  const packageName = headers.packageName ?? defaultPackageNames[headers.productId] ?? '@mui/material';
+  return /*#__PURE__*/_jsxs(Root, {
+    children: [packageName === '@mui/material' && /*#__PURE__*/_jsx("li", {
+      children: /*#__PURE__*/_jsx(Chip, {
+        clickable: true,
+        role: undefined,
+        component: "a",
+        size: "small",
+        variant: "outlined",
+        href: `${router.pathname}.md`,
+        icon: _MarkdownIcon || (_MarkdownIcon = /*#__PURE__*/_jsx(MarkdownIcon, {})),
+        "data-ga-event-category": "ComponentLinkHeader",
+        "data-ga-event-action": "click",
+        "data-ga-event-label": "Markdown",
+        "data-ga-event-split": "0.1",
+        label: "View as Markdown"
+      })
+    }), headers.githubLabel ? /*#__PURE__*/_jsx("li", {
+      children: /*#__PURE__*/_jsx(Chip, {
+        clickable: true,
+        role: undefined,
+        component: "a",
+        size: "small",
+        variant: "outlined",
+        rel: "nofollow",
+        href: `${process.env.SOURCE_CODE_REPO}/labels/${encodeURIComponent(headers.githubLabel)}`,
+        icon: _ChatRounded || (_ChatRounded = /*#__PURE__*/_jsx(ChatRounded, {
+          color: "primary"
+        })),
+        "data-ga-event-category": "ComponentLinkHeader",
+        "data-ga-event-action": "click",
+        "data-ga-event-label": t('githubLabel'),
+        "data-ga-event-split": "0.1",
+        label: t('githubLabel')
+      })
+    }) : null, /*#__PURE__*/_jsx("li", {
+      children: /*#__PURE__*/_jsx(Tooltip, {
+        title: t('bundleSizeTooltip'),
+        describeChild: true,
+        children: /*#__PURE__*/_jsx(Chip, {
+          clickable: true,
+          role: undefined,
+          component: "a",
+          size: "small",
+          variant: "outlined",
+          rel: "nofollow",
+          href: `https://bundlephobia.com/package/${packageName}@latest`,
+          icon: _BundleSizeIcon || (_BundleSizeIcon = /*#__PURE__*/_jsx(BundleSizeIcon, {
+            color: "primary"
+          })),
+          "data-ga-event-category": "ComponentLinkHeader",
+          "data-ga-event-action": "click",
+          "data-ga-event-label": t('bundleSize'),
+          "data-ga-event-split": "0.1",
+          label: t('bundleSize')
+        })
+      })
+    }), headers.githubSource ? /*#__PURE__*/_jsx("li", {
+      children: /*#__PURE__*/_jsx(Chip, {
+        clickable: true,
+        role: undefined,
+        component: "a",
+        size: "small",
+        variant: "outlined",
+        rel: "nofollow",
+        href: `${process.env.SOURCE_CODE_REPO}/tree/v${process.env.LIB_VERSION}/${headers.githubSource}`,
+        icon: _GitHubIcon || (_GitHubIcon = /*#__PURE__*/_jsx(GitHubIcon, {})),
+        "data-ga-event-category": "ComponentLinkHeader",
+        "data-ga-event-action": "click",
+        "data-ga-event-label": "Source",
+        "data-ga-event-split": "0.1",
+        label: "Source"
+      })
+    }) : null, headers.waiAria ? /*#__PURE__*/_jsx("li", {
+      children: /*#__PURE__*/_jsx(Chip, {
+        clickable: true,
+        role: undefined,
+        component: "a",
+        size: "small",
+        variant: "outlined",
+        rel: "nofollow",
+        href: headers.waiAria,
+        icon: _W3CIcon || (_W3CIcon = /*#__PURE__*/_jsx(W3CIcon, {
+          color: "primary"
+        })),
+        "data-ga-event-category": "ComponentLinkHeader",
+        "data-ga-event-action": "click",
+        "data-ga-event-label": "WAI-ARIA",
+        "data-ga-event-split": "0.1",
+        label: "WAI-ARIA"
+      })
+    }) : null, headers.materialDesign ? /*#__PURE__*/_jsx("li", {
+      children: /*#__PURE__*/_jsx(Chip, {
+        clickable: true,
+        role: undefined,
+        component: "a",
+        size: "small",
+        variant: "outlined",
+        rel: "nofollow",
+        href: headers.materialDesign,
+        icon: _MaterialDesignIcon || (_MaterialDesignIcon = /*#__PURE__*/_jsx(MaterialDesignIcon, {})),
+        "data-ga-event-category": "ComponentLinkHeader",
+        "data-ga-event-action": "click",
+        "data-ga-event-label": "Material Design",
+        "data-ga-event-split": "0.1",
+        label: "Material Design"
+      })
+    }) : null, design === false ? null : /*#__PURE__*/_jsxs(React.Fragment, {
+      children: [_li || (_li = /*#__PURE__*/_jsx("li", {
+        children: /*#__PURE__*/_jsx(Chip, {
+          clickable: true,
+          role: undefined,
+          component: "a",
+          size: "small",
+          variant: "outlined",
+          rel: "nofollow",
+          href: "https://mui.com/store/items/figma-react/?utm_source=docs&utm_medium=referral&utm_campaign=component-link-header",
+          icon: /*#__PURE__*/_jsx(FigmaIcon, {}),
+          "data-ga-event-category": "ComponentLinkHeader",
+          "data-ga-event-action": "click",
+          "data-ga-event-label": "Figma",
+          "data-ga-event-split": "0.1",
+          label: "Figma"
+        })
+      })), packageName === '@mui/joy' ? null : _li2 || (_li2 = /*#__PURE__*/_jsx("li", {
+        children: /*#__PURE__*/_jsx(Chip, {
+          clickable: true,
+          role: undefined,
+          component: "a",
+          size: "small",
+          variant: "outlined",
+          rel: "nofollow",
+          href: "https://mui.com/store/items/sketch-react/?utm_source=docs&utm_medium=referral&utm_campaign=component-link-header",
+          icon: /*#__PURE__*/_jsx(SketchIcon, {}),
+          "data-ga-event-category": "ComponentLinkHeader",
+          "data-ga-event-action": "click",
+          "data-ga-event-label": "Sketch",
+          "data-ga-event-split": "0.1",
+          label: "Sketch"
+        })
+      }))]
+    })]
+  });
+}

package/ComponentLinkHeader/index.d.ts

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

package/ComponentLinkHeader/index.js

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

package/DemoContext/DemoContext.d.ts

@@ -0,0 +1,86 @@
+import * as React from 'react';
+import type { MuiProductId } from "../getProductInfoFromUrl/index.js";
+export type CodeVariant = 'TS' | 'JS';
+type RelativeModule = {
+  module: string;
+  raw: string;
+};
+export interface DemoData {
+  title: string;
+  language: string;
+  raw: string;
+  codeVariant: CodeVariant;
+  githubLocation: string;
+  productId?: Exclude<MuiProductId, 'null'>;
+  relativeModules?: RelativeModule[];
+}
+export interface SandboxConfig {
+  /**
+   * Generates the root index.js/tsx content for CodeSandbox/StackBlitz.
+   * Receives codeVariant ('TS' | 'JS') for type assertion.
+   */
+  getRootIndex?: (codeVariant: CodeVariant) => string;
+  /**
+   * Primary npm package for this product, used in sandbox generation.
+   * e.g., "@mui/material", "@mui/joy", "@mui/x-data-grid"
+   */
+  primaryPackage: string;
+  /**
+   * Default dependency to add when generating sandbox (e.g., '@mui/material' for StyledEngineProvider)
+   * Used when the root index template requires a specific package.
+   */
+  fallbackDependency?: {
+    name: string;
+    version: string;
+  };
+  /**
+   * Hook to add extra peer dependencies to sandbox.
+   */
+  includePeerDependencies?: (deps: Record<string, string>, options: {
+    versions: Record<string, string>;
+  }) => Record<string, string>;
+  /**
+   * Hook to override default package versions.
+   */
+  getVersions?: (versions: Record<string, string>, options: {
+    muiCommitRef?: string;
+  }) => Record<string, string>;
+  /**
+   * Hook to resolve custom imports to dependencies.
+   */
+  postProcessImport?: (importName: string) => Record<string, string> | null;
+}
+export interface IframeWrapperProps {
+  /**
+   * The demo content (already cloned with `window` prop by FramedDemo).
+   * The wrapper should just render {children} - no cloning needed.
+   */
+  children: React.ReactElement;
+  /** The iframe's document, for setting attributes or observing color scheme */
+  document: Document;
+  /** If true, the demo is isolated and should not inject theme CSS variables */
+  isolated?: boolean;
+}
+export interface DemoContextValue {
+  /**
+   * Display name shown in demo titles, e.g., "Material UI", "Joy UI", "MUI X"
+   */
+  productDisplayName: string;
+  /**
+   * Optional wrapper component for iframe demo content.
+   * Responsible for:
+   * - Creating and injecting CSS theme variables (via GlobalStyles)
+   * - Any product-specific observers (e.g., JoyIframeObserver)
+   *
+   * If not provided, defaults to MaterialIframeWrapper (creates Material theme).
+   * Pass `null` explicitly to disable iframe wrapping entirely.
+   */
+  IframeWrapper?: React.ComponentType<IframeWrapperProps> | null;
+  /**
+   * Configuration for CodeSandbox/StackBlitz sandbox generation.
+   */
+  csb: SandboxConfig;
+}
+declare const DemoContext: React.Context<DemoContextValue | null>;
+export declare function useDemoContext(): DemoContextValue;
+export default DemoContext;

package/DemoContext/DemoContext.js

@@ -0,0 +1,13 @@
+import * as React from 'react';
+const DemoContext = /*#__PURE__*/React.createContext(null);
+if (process.env.NODE_ENV !== 'production') {
+  DemoContext.displayName = 'DemoContext';
+}
+export function useDemoContext() {
+  const context = React.useContext(DemoContext);
+  if (!context) {
+    throw new Error('useDemoContext must be used within a DemoContext.Provider');
+  }
+  return context;
+}
+export default DemoContext;

package/DemoContext/index.d.ts

@@ -0,0 +1,2 @@
+export { default, useDemoContext } from "./DemoContext.js";
+export type { CodeVariant, DemoData, SandboxConfig, IframeWrapperProps, DemoContextValue } from "./DemoContext.js";

package/DemoContext/index.js

@@ -0,0 +1 @@
+export { default, useDemoContext } from "./DemoContext.js";

package/DocsApp/AnalyticsProvider.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+type ConsentStatus = 'analytics' | 'essential' | null;
+interface AnalyticsContextValue {
+  consentStatus: ConsentStatus;
+  hasAnalyticsConsent: boolean;
+  needsConsent: boolean;
+  setAnalyticsConsent: () => void;
+  setEssentialOnly: () => void;
+}
+export declare function useAnalyticsConsent(): AnalyticsContextValue;
+export declare function CookieConsentDialog(): import("react/jsx-runtime").JSX.Element;
+export declare function AnalyticsProvider({
+  children
+}: {
+  children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export {};