@docusaurus/theme-classic 3.7.0-canary-6274 → 3.7.0-canary-6276

package/lib/getSwizzleConfig.js

@@ -148,7 +148,7 @@ function getSwizzleConfig() {
             'CodeBlock/Content': {
                 actions: {
                     eject: 'unsafe',
-                    wrap: 'forbidden',
+                    wrap: 'unsafe',
                 },
                 description: 'The folder containing components responsible for rendering different types of CodeBlock content.',
             },

package/lib/theme/CodeBlock/{WordWrapButton → Buttons/Button}/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { type ReactNode } from 'react';
-import type { Props } from '@theme/CodeBlock/WordWrapButton';
-export default function WordWrapButton({ className, onClick, isEnabled, }: Props): ReactNode;
+import type { Props } from '@theme/CodeBlock/Buttons/Button';
+export default function CodeBlockButton({ className, ...props }: Props): ReactNode;

package/lib/theme/CodeBlock/Buttons/Button/index.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+export default function CodeBlockButton({className, ...props}) {
+  return (
+    <button type="button" {...props} className={clsx('clean-btn', className)} />
+  );
+}

package/lib/theme/CodeBlock/Buttons/CopyButton/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Buttons/CopyButton';
+export default function CopyButton({ className }: Props): ReactNode;

package/lib/theme/CodeBlock/{CopyButton → Buttons/CopyButton}/index.js

@@ -8,13 +8,38 @@ import React, {useCallback, useState, useRef, useEffect} from 'react';
 import clsx from 'clsx';
 import copy from 'copy-text-to-clipboard';
 import {translate} from '@docusaurus/Translate';
+import {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import Button from '@theme/CodeBlock/Buttons/Button';
 import IconCopy from '@theme/Icon/Copy';
 import IconSuccess from '@theme/Icon/Success';
 import styles from './styles.module.css';
-export default function CopyButton({code, className}) {
+function title() {
+  return translate({
+    id: 'theme.CodeBlock.copy',
+    message: 'Copy',
+    description: 'The copy button label on code blocks',
+  });
+}
+function ariaLabel(isCopied) {
+  return isCopied
+    ? translate({
+        id: 'theme.CodeBlock.copied',
+        message: 'Copied',
+        description: 'The copied button label on code blocks',
+      })
+    : translate({
+        id: 'theme.CodeBlock.copyButtonAriaLabel',
+        message: 'Copy code to clipboard',
+        description: 'The ARIA label for copy code blocks button',
+      });
+}
+function useCopyButton() {
+  const {
+    metadata: {code},
+  } = useCodeBlockContext();
   const [isCopied, setIsCopied] = useState(false);
   const copyTimeout = useRef(undefined);
-  const handleCopyCode = useCallback(() => {
+  const copyCode = useCallback(() => {
     copy(code);
     setIsCopied(true);
     copyTimeout.current = window.setTimeout(() => {
@@ -22,38 +47,24 @@ export default function CopyButton({code, className}) {
     }, 1000);
   }, [code]);
   useEffect(() => () => window.clearTimeout(copyTimeout.current), []);
+  return {copyCode, isCopied};
+}
+export default function CopyButton({className}) {
+  const {copyCode, isCopied} = useCopyButton();
   return (
-    <button
-      type="button"
-      aria-label={
-        isCopied
-          ? translate({
-              id: 'theme.CodeBlock.copied',
-              message: 'Copied',
-              description: 'The copied button label on code blocks',
-            })
-          : translate({
-              id: 'theme.CodeBlock.copyButtonAriaLabel',
-              message: 'Copy code to clipboard',
-              description: 'The ARIA label for copy code blocks button',
-            })
-      }
-      title={translate({
-        id: 'theme.CodeBlock.copy',
-        message: 'Copy',
-        description: 'The copy button label on code blocks',
-      })}
+    <Button
+      aria-label={ariaLabel(isCopied)}
+      title={title()}
       className={clsx(
-        'clean-btn',
         className,
         styles.copyButton,
         isCopied && styles.copyButtonCopied,
       )}
-      onClick={handleCopyCode}>
+      onClick={copyCode}>
       <span className={styles.copyButtonIcons} aria-hidden="true">
         <IconCopy className={styles.copyButtonIcon} />
         <IconSuccess className={styles.copyButtonSuccessIcon} />
       </span>
-    </button>
+    </Button>
   );
 }

package/lib/theme/CodeBlock/Buttons/WordWrapButton/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Buttons/WordWrapButton';
+export default function WordWrapButton({ className }: Props): ReactNode;

package/lib/theme/CodeBlock/{WordWrapButton → Buttons/WordWrapButton}/index.js

@@ -7,9 +7,16 @@
 import React from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
+import {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import Button from '@theme/CodeBlock/Buttons/Button';
 import IconWordWrap from '@theme/Icon/WordWrap';
 import styles from './styles.module.css';
-export default function WordWrapButton({className, onClick, isEnabled}) {
+export default function WordWrapButton({className}) {
+  const {wordWrap} = useCodeBlockContext();
+  const canShowButton = wordWrap.isEnabled || wordWrap.isCodeScrollable;
+  if (!canShowButton) {
+    return false;
+  }
   const title = translate({
     id: 'theme.CodeBlock.wordWrapToggle',
     message: 'Toggle word wrap',
@@ -17,17 +24,15 @@ export default function WordWrapButton({className, onClick, isEnabled}) {
       'The title attribute for toggle word wrapping button of code block lines',
   });
   return (
-    <button
-      type="button"
-      onClick={onClick}
+    <Button
+      onClick={() => wordWrap.toggle()}
       className={clsx(
-        'clean-btn',
         className,
-        isEnabled && styles.wordWrapButtonEnabled,
+        wordWrap.isEnabled && styles.wordWrapButtonEnabled,
       )}
       aria-label={title}
       title={title}>
       <IconWordWrap className={styles.wordWrapButtonIcon} aria-hidden="true" />
-    </button>
+    </Button>
   );
 }

package/lib/theme/CodeBlock/{CopyButton → Buttons}/index.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { type ReactNode } from 'react';
-import type { Props } from '@theme/CodeBlock/CopyButton';
-export default function CopyButton({ code, className }: Props): ReactNode;
+import type { Props } from '@theme/CodeBlock/Buttons';
+export default function CodeBlockButtons({ className }: Props): ReactNode;

package/lib/theme/CodeBlock/Buttons/index.js

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import CopyButton from '@theme/CodeBlock/Buttons/CopyButton';
+import WordWrapButton from '@theme/CodeBlock/Buttons/WordWrapButton';
+import styles from './styles.module.css';
+// Code block buttons are not server-rendered on purpose
+// Adding them to the initial HTML is useless and expensive (due to JSX SVG)
+// They are hidden by default and require React  to become interactive
+export default function CodeBlockButtons({className}) {
+  return (
+    <BrowserOnly>
+      {() => (
+        <div className={clsx(className, styles.buttonGroup)}>
+          <WordWrapButton />
+          <CopyButton />
+        </div>
+      )}
+    </BrowserOnly>
+  );
+}

package/lib/theme/CodeBlock/Buttons/styles.module.css

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.buttonGroup {
+  display: flex;
+  column-gap: 0.2rem;
+  position: absolute;
+  /* rtl:ignore */
+  right: calc(var(--ifm-pre-padding) / 2);
+  top: calc(var(--ifm-pre-padding) / 2);
+}
+
+.buttonGroup button {
+  display: flex;
+  align-items: center;
+  background: var(--prism-background-color);
+  color: var(--prism-color);
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  padding: 0.4rem;
+  line-height: 0;
+  transition: opacity var(--ifm-transition-fast) ease-in-out;
+  opacity: 0;
+}
+
+.buttonGroup button:focus-visible,
+.buttonGroup button:hover {
+  opacity: 1 !important;
+}
+
+:global(.theme-code-block:hover) .buttonGroup button {
+  opacity: 0.4;
+}

package/lib/theme/CodeBlock/Content/Element.js

@@ -8,8 +8,10 @@ import React from 'react';
 import clsx from 'clsx';
 import Container from '@theme/CodeBlock/Container';
 import styles from './styles.module.css';
-// <pre> tags in markdown map to CodeBlocks. They may contain JSX children. When
-// the children is not a simple string, we just return a styled block without
+// TODO Docusaurus v4: move this component at the root?
+// This component only handles a rare edge-case: <pre><MyComp/></pre> in MDX
+// <pre> tags in markdown map to CodeBlocks. They may contain JSX children.
+// When children is not a simple string, we just return a styled block without
 // actually highlighting.
 export default function CodeBlockJSX({children, className}) {
   return (

package/lib/theme/CodeBlock/Content/String.d.ts

@@ -6,4 +6,4 @@
  */
 import { type ReactNode } from 'react';
 import type { Props } from '@theme/CodeBlock/Content/String';
-export default function CodeBlockString({ children, className: blockClassName, metastring, title: titleProp, showLineNumbers: showLineNumbersProp, language: languageProp, }: Props): ReactNode;
+export default function CodeBlockString(props: Props): ReactNode;

package/lib/theme/CodeBlock/Content/String.js

@@ -5,115 +5,33 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import clsx from 'clsx';
-import {useThemeConfig, usePrismTheme} from '@docusaurus/theme-common';
+import {useThemeConfig} from '@docusaurus/theme-common';
 import {
-  parseCodeBlockTitle,
-  parseLanguage,
-  parseLines,
-  getLineNumbersStart,
+  CodeBlockContextProvider,
+  createCodeBlockMetadata,
   useCodeWordWrap,
 } from '@docusaurus/theme-common/internal';
-import useIsBrowser from '@docusaurus/useIsBrowser';
-import {Highlight} from 'prism-react-renderer';
-import Line from '@theme/CodeBlock/Line';
-import CopyButton from '@theme/CodeBlock/CopyButton';
-import WordWrapButton from '@theme/CodeBlock/WordWrapButton';
-import Container from '@theme/CodeBlock/Container';
-import styles from './styles.module.css';
-// Prism languages are always lowercase
-// We want to fail-safe and allow both "php" and "PHP"
-// See https://github.com/facebook/docusaurus/issues/9012
-function normalizeLanguage(language) {
-  return language?.toLowerCase();
+import CodeBlockLayout from '@theme/CodeBlock/Layout';
+function useCodeBlockMetadata(props) {
+  const {prism} = useThemeConfig();
+  return createCodeBlockMetadata({
+    code: props.children,
+    className: props.className,
+    metastring: props.metastring,
+    magicComments: prism.magicComments,
+    defaultLanguage: prism.defaultLanguage,
+    language: props.language,
+    title: props.title,
+    showLineNumbers: props.showLineNumbers,
+  });
 }
-export default function CodeBlockString({
-  children,
-  className: blockClassName = '',
-  metastring,
-  title: titleProp,
-  showLineNumbers: showLineNumbersProp,
-  language: languageProp,
-}) {
-  const {
-    prism: {defaultLanguage, magicComments},
-  } = useThemeConfig();
-  const language = normalizeLanguage(
-    languageProp ?? parseLanguage(blockClassName) ?? defaultLanguage,
-  );
-  const prismTheme = usePrismTheme();
+// TODO Docusaurus v4: move this component at the root?
+export default function CodeBlockString(props) {
+  const metadata = useCodeBlockMetadata(props);
   const wordWrap = useCodeWordWrap();
-  const isBrowser = useIsBrowser();
-  // We still parse the metastring in case we want to support more syntax in the
-  // future. Note that MDX doesn't strip quotes when parsing metastring:
-  // "title=\"xyz\"" => title: "\"xyz\""
-  const title = parseCodeBlockTitle(metastring) || titleProp;
-  const {lineClassNames, code} = parseLines(children, {
-    metastring,
-    language,
-    magicComments,
-  });
-  const lineNumbersStart = getLineNumbersStart({
-    showLineNumbers: showLineNumbersProp,
-    metastring,
-  });
   return (
-    <Container
-      as="div"
-      className={clsx(
-        blockClassName,
-        language &&
-          !blockClassName.includes(`language-${language}`) &&
-          `language-${language}`,
-      )}>
-      {title && <div className={styles.codeBlockTitle}>{title}</div>}
-      <div className={styles.codeBlockContent}>
-        <Highlight theme={prismTheme} code={code} language={language ?? 'text'}>
-          {({className, style, tokens, getLineProps, getTokenProps}) => (
-            <pre
-              /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
-              tabIndex={0}
-              ref={wordWrap.codeBlockRef}
-              className={clsx(className, styles.codeBlock, 'thin-scrollbar')}
-              style={style}>
-              <code
-                className={clsx(
-                  styles.codeBlockLines,
-                  lineNumbersStart !== undefined &&
-                    styles.codeBlockLinesWithNumbering,
-                )}
-                style={
-                  lineNumbersStart === undefined
-                    ? undefined
-                    : {counterReset: `line-count ${lineNumbersStart - 1}`}
-                }>
-                {tokens.map((line, i) => (
-                  <Line
-                    key={i}
-                    line={line}
-                    getLineProps={getLineProps}
-                    getTokenProps={getTokenProps}
-                    classNames={lineClassNames[i]}
-                    showLineNumbers={lineNumbersStart !== undefined}
-                  />
-                ))}
-              </code>
-            </pre>
-          )}
-        </Highlight>
-        {isBrowser ? (
-          <div className={styles.buttonGroup}>
-            {(wordWrap.isEnabled || wordWrap.isCodeScrollable) && (
-              <WordWrapButton
-                className={styles.codeButton}
-                onClick={() => wordWrap.toggle()}
-                isEnabled={wordWrap.isEnabled}
-              />
-            )}
-            <CopyButton className={styles.codeButton} code={code} />
-          </div>
-        ) : null}
-      </div>
-    </Container>
+    <CodeBlockContextProvider metadata={metadata} wordWrap={wordWrap}>
+      <CodeBlockLayout />
+    </CodeBlockContextProvider>
   );
 }

package/lib/theme/CodeBlock/Content/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Content';
+export default function CodeBlockContent({ className: classNameProp, }: Props): ReactNode;

package/lib/theme/CodeBlock/Content/index.js

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import {usePrismTheme} from '@docusaurus/theme-common';
+import {Highlight} from 'prism-react-renderer';
+import Line from '@theme/CodeBlock/Line';
+import styles from './styles.module.css';
+// TODO Docusaurus v4: remove useless forwardRef
+const Pre = React.forwardRef((props, ref) => {
+  return (
+    <pre
+      ref={ref}
+      /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
+      tabIndex={0}
+      {...props}
+      className={clsx(props.className, styles.codeBlock, 'thin-scrollbar')}
+    />
+  );
+});
+function Code(props) {
+  const {metadata} = useCodeBlockContext();
+  return (
+    <code
+      {...props}
+      className={clsx(
+        props.className,
+        styles.codeBlockLines,
+        metadata.lineNumbersStart !== undefined &&
+          styles.codeBlockLinesWithNumbering,
+      )}
+      style={{
+        ...props.style,
+        counterReset:
+          metadata.lineNumbersStart === undefined
+            ? undefined
+            : `line-count ${metadata.lineNumbersStart - 1}`,
+      }}
+    />
+  );
+}
+export default function CodeBlockContent({className: classNameProp}) {
+  const {metadata, wordWrap} = useCodeBlockContext();
+  const prismTheme = usePrismTheme();
+  const {code, language, lineNumbersStart, lineClassNames} = metadata;
+  return (
+    <Highlight theme={prismTheme} code={code} language={language}>
+      {({className, style, tokens: lines, getLineProps, getTokenProps}) => (
+        <Pre
+          ref={wordWrap.codeBlockRef}
+          className={clsx(classNameProp, className)}
+          style={style}>
+          <Code>
+            {lines.map((line, i) => (
+              <Line
+                key={i}
+                line={line}
+                getLineProps={getLineProps}
+                getTokenProps={getTokenProps}
+                classNames={lineClassNames[i]}
+                showLineNumbers={lineNumbersStart !== undefined}
+              />
+            ))}
+          </Code>
+        </Pre>
+      )}
+    </Highlight>
+  );
+}

package/lib/theme/CodeBlock/Content/styles.module.css

@@ -5,33 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.codeBlockContent {
-  position: relative;
-  /* rtl:ignore */
-  direction: ltr;
-  border-radius: inherit;
-}
-
-.codeBlockTitle {
-  border-bottom: 1px solid var(--ifm-color-emphasis-300);
-  font-size: var(--ifm-code-font-size);
-  font-weight: 500;
-  padding: 0.75rem var(--ifm-pre-padding);
-  border-top-left-radius: inherit;
-  border-top-right-radius: inherit;
-}
-
 .codeBlock {
   --ifm-pre-background: var(--prism-background-color);
   margin: 0;
   padding: 0;
 }
 
-.codeBlockTitle + .codeBlockContent .codeBlock {
-  border-top-left-radius: 0;
-  border-top-right-radius: 0;
-}
-
 .codeBlockStandalone {
   padding: 0;
 }
@@ -54,34 +33,3 @@
     white-space: pre-wrap;
   }
 }
-
-.buttonGroup {
-  display: flex;
-  column-gap: 0.2rem;
-  position: absolute;
-  /* rtl:ignore */
-  right: calc(var(--ifm-pre-padding) / 2);
-  top: calc(var(--ifm-pre-padding) / 2);
-}
-
-.buttonGroup button {
-  display: flex;
-  align-items: center;
-  background: var(--prism-background-color);
-  color: var(--prism-color);
-  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: var(--ifm-global-radius);
-  padding: 0.4rem;
-  line-height: 0;
-  transition: opacity var(--ifm-transition-fast) ease-in-out;
-  opacity: 0;
-}
-
-.buttonGroup button:focus-visible,
-.buttonGroup button:hover {
-  opacity: 1 !important;
-}
-
-:global(.theme-code-block:hover) .buttonGroup button {
-  opacity: 0.4;
-}

package/lib/theme/CodeBlock/Layout/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Layout';
+export default function CodeBlockLayout({ className }: Props): ReactNode;

package/lib/theme/CodeBlock/Layout/index.js

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import Container from '@theme/CodeBlock/Container';
+import Title from '@theme/CodeBlock/Title';
+import Content from '@theme/CodeBlock/Content';
+import Buttons from '@theme/CodeBlock/Buttons';
+import styles from './styles.module.css';
+export default function CodeBlockLayout({className}) {
+  const {metadata} = useCodeBlockContext();
+  return (
+    <Container as="div" className={clsx(className, metadata.className)}>
+      {metadata.title && (
+        <div className={styles.codeBlockTitle}>
+          <Title>{metadata.title}</Title>
+        </div>
+      )}
+      <div className={styles.codeBlockContent}>
+        <Content />
+        <Buttons />
+      </div>
+    </Container>
+  );
+}

package/lib/theme/CodeBlock/Layout/styles.module.css

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.codeBlockContent {
+  position: relative;
+  /* rtl:ignore */
+  direction: ltr;
+  border-radius: inherit;
+}
+
+.codeBlockTitle {
+  border-bottom: 1px solid var(--ifm-color-emphasis-300);
+  font-size: var(--ifm-code-font-size);
+  font-weight: 500;
+  padding: 0.75rem var(--ifm-pre-padding);
+  border-top-left-radius: inherit;
+  border-top-right-radius: inherit;
+}
+
+.codeBlockTitle + .codeBlockContent .codeBlock {
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}

package/lib/theme/CodeBlock/Line/Token/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type ReactNode } from 'react';
+import type { Props } from '@theme/CodeBlock/Line/Token';
+export default function CodeBlockLineToken({ line, token, ...props }: Props): ReactNode;

package/lib/theme/CodeBlock/Line/Token/index.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+// Pass-through components that users can swizzle and customize
+export default function CodeBlockLineToken({line, token, ...props}) {
+  return <span {...props} />;
+}