@docusaurus/theme-classic 3.7.0 → 3.8.0

package/src/theme/CodeBlock/{WordWrapButton → Buttons/WordWrapButton}/index.tsx

@@ -8,16 +8,21 @@
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
-import type {Props} from '@theme/CodeBlock/WordWrapButton';
+import {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import Button from '@theme/CodeBlock/Buttons/Button';
+import type {Props} from '@theme/CodeBlock/Buttons/WordWrapButton';
 import IconWordWrap from '@theme/Icon/WordWrap';
 
 import styles from './styles.module.css';
 
-export default function WordWrapButton({
-  className,
-  onClick,
-  isEnabled,
-}: Props): ReactNode {
+export default function WordWrapButton({className}: Props): ReactNode {
+  const {wordWrap} = useCodeBlockContext();
+
+  const canShowButton = wordWrap.isEnabled || wordWrap.isCodeScrollable;
+  if (!canShowButton) {
+    return false;
+  }
+
   const title = translate({
     id: 'theme.CodeBlock.wordWrapToggle',
     message: 'Toggle word wrap',
@@ -26,17 +31,15 @@ export default function WordWrapButton({
   });
 
   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/src/theme/CodeBlock/Buttons/index.tsx

@@ -0,0 +1,32 @@
+/**
+ * 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, {type ReactNode} 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 type {Props} from '@theme/CodeBlock/Buttons';
+
+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}: Props): ReactNode {
+  return (
+    <BrowserOnly>
+      {() => (
+        <div className={clsx(className, styles.buttonGroup)}>
+          <WordWrapButton />
+          <CopyButton />
+        </div>
+      )}
+    </BrowserOnly>
+  );
+}

package/src/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/src/theme/CodeBlock/Content/Element.tsx

@@ -12,8 +12,10 @@ import type {Props} from '@theme/CodeBlock/Content/Element';
 
 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}: Props): ReactNode {
   return (

package/src/theme/CodeBlock/Content/String.tsx

@@ -6,114 +6,37 @@
  */
 
 import React, {type ReactNode} from 'react';
-import clsx from 'clsx';
-import {useThemeConfig, usePrismTheme} from '@docusaurus/theme-common';
+import {useThemeConfig} from '@docusaurus/theme-common';
 import {
-  parseCodeBlockTitle,
-  parseLanguage,
-  parseLines,
-  containsLineNumbers,
+  CodeBlockContextProvider,
+  type CodeBlockMetadata,
+  createCodeBlockMetadata,
   useCodeWordWrap,
 } from '@docusaurus/theme-common/internal';
-import {Highlight, type Language} 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 type {Props} from '@theme/CodeBlock/Content/String';
-
-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: string | undefined): string | undefined {
-  return language?.toLowerCase();
+import CodeBlockLayout from '@theme/CodeBlock/Layout';
+
+function useCodeBlockMetadata(props: Props): CodeBlockMetadata {
+  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,
-}: Props): ReactNode {
-  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: Props): ReactNode {
+  const metadata = useCodeBlockMetadata(props);
   const wordWrap = useCodeWordWrap();
-
-  // 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 showLineNumbers =
-    showLineNumbersProp ?? containsLineNumbers(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') as Language}>
-          {({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,
-                  showLineNumbers && styles.codeBlockLinesWithNumbering,
-                )}>
-                {tokens.map((line, i) => (
-                  <Line
-                    key={i}
-                    line={line}
-                    getLineProps={getLineProps}
-                    getTokenProps={getTokenProps}
-                    classNames={lineClassNames[i]}
-                    showLineNumbers={showLineNumbers}
-                  />
-                ))}
-              </code>
-            </pre>
-          )}
-        </Highlight>
-        <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>
-      </div>
-    </Container>
+    <CodeBlockContextProvider metadata={metadata} wordWrap={wordWrap}>
+      <CodeBlockLayout />
+    </CodeBlockContextProvider>
   );
 }

package/src/theme/CodeBlock/Content/index.tsx

@@ -0,0 +1,84 @@
+/**
+ * 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, {type ComponentProps, type ReactNode} 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 type {Props} from '@theme/CodeBlock/Content';
+import Line from '@theme/CodeBlock/Line';
+
+import styles from './styles.module.css';
+
+// TODO Docusaurus v4: remove useless forwardRef
+const Pre = React.forwardRef<HTMLPreElement, ComponentProps<'pre'>>(
+  (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: ComponentProps<'code'>) {
+  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,
+}: Props): ReactNode {
+  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/src/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/src/theme/CodeBlock/Layout/index.tsx

@@ -0,0 +1,34 @@
+/**
+ * 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, {type ReactNode} 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 type {Props} from '@theme/CodeBlock/Layout';
+import Buttons from '@theme/CodeBlock/Buttons';
+
+import styles from './styles.module.css';
+
+export default function CodeBlockLayout({className}: Props): ReactNode {
+  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/src/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/src/theme/CodeBlock/Line/Token/index.tsx

@@ -0,0 +1,18 @@
+/**
+ * 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, {type ReactNode} from 'react';
+import type {Props} from '@theme/CodeBlock/Line/Token';
+
+// Pass-through components that users can swizzle and customize
+export default function CodeBlockLineToken({
+  line,
+  token,
+  ...props
+}: Props): ReactNode {
+  return <span {...props} />;
+}

package/src/theme/CodeBlock/Line/index.tsx

@@ -7,29 +7,48 @@
 
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import LineToken from '@theme/CodeBlock/Line/Token';
 import type {Props} from '@theme/CodeBlock/Line';
 
 import styles from './styles.module.css';
 
+type Token = Props['line'][number];
+
+// Replaces '\n' by ''
+// Historical code, not sure why we even need this :/
+function fixLineBreak(line: Token[]) {
+  const singleLineBreakToken =
+    line.length === 1 && line[0]!.content === '\n' ? line[0] : undefined;
+
+  if (singleLineBreakToken) {
+    return [{...singleLineBreakToken, content: ''}];
+  }
+
+  return line;
+}
+
 export default function CodeBlockLine({
-  line,
+  line: lineProp,
   classNames,
   showLineNumbers,
   getLineProps,
   getTokenProps,
 }: Props): ReactNode {
-  if (line.length === 1 && line[0]!.content === '\n') {
-    line[0]!.content = '';
-  }
+  const line = fixLineBreak(lineProp);
 
   const lineProps = getLineProps({
     line,
     className: clsx(classNames, showLineNumbers && styles.codeLine),
   });
 
-  const lineTokens = line.map((token, key) => (
-    <span key={key} {...getTokenProps({token})} />
-  ));
+  const lineTokens = line.map((token, key) => {
+    const tokenProps = getTokenProps({token});
+    return (
+      <LineToken key={key} {...tokenProps} line={line} token={token}>
+        {tokenProps.children}
+      </LineToken>
+    );
+  });
 
   return (
     <span {...lineProps}>

package/src/theme/CodeBlock/Title/index.tsx

@@ -0,0 +1,15 @@
+/**
+ * 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/Title';
+
+// Just a pass-through component that users can swizzle and customize
+export default function CodeBlockTitle({children}: Props): ReactNode {
+  return children;
+}