@docusaurus/theme-classic 2.0.0-beta.16 → 2.0.0-beta.19

package/src/theme/CodeBlock/CopyButton/styles.module.css

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+
+:global(.theme-code-block:hover) .copyButtonCopied {
+  opacity: 1 !important;
+}
+
+.copyButtonIcons {
+  position: relative;
+  width: 1.125rem;
+  height: 1.125rem;
+}
+
+.copyButtonIcon,
+.copyButtonSuccessIcon {
+  position: absolute;
+  top: 0;
+  left: 0;
+  fill: currentColor;
+  opacity: inherit;
+  width: inherit;
+  height: inherit;
+  transition: all 0.15s ease;
+}
+
+.copyButtonSuccessIcon {
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%) scale(0.33);
+  opacity: 0;
+  color: #00d600;
+}
+
+.copyButtonCopied .copyButtonIcon {
+  transform: scale(0.33);
+  opacity: 0;
+}
+
+.copyButtonCopied .copyButtonSuccessIcon {
+  transform: translate(-50%, -50%) scale(1);
+  opacity: 1;
+  transition-delay: 0.075s;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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 type {Props} from '@theme/CodeBlock/Line';
+import styles from './styles.module.css';
+
+export default function CodeBlockLine({
+  line,
+  classNames,
+  showLineNumbers,
+  getLineProps,
+  getTokenProps,
+}: Props): JSX.Element {
+  if (line.length === 1 && line[0]!.content === '\n') {
+    line[0]!.content = '';
+  }
+
+  const lineProps = getLineProps({
+    line,
+    className: clsx(classNames, showLineNumbers && styles.codeLine),
+  });
+
+  const lineTokens = line.map((token, key) => (
+    <span key={key} {...getTokenProps({token, key})} />
+  ));
+
+  return (
+    <span {...lineProps}>
+      {showLineNumbers ? (
+        <>
+          <span className={styles.codeLineNumber} />
+          <span className={styles.codeLineContent}>{lineTokens}</span>
+        </>
+      ) : (
+        <>
+          {lineTokens}
+          <br />
+        </>
+      )}
+    </span>
+  );
+}

package/src/theme/CodeBlock/Line/styles.module.css

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+
+:global(.theme-code-block-highlighted-line) {
+  background-color: var(--docusaurus-highlighted-code-line-bg);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
+/* Intentionally has zero specificity, so that to be able to override
+the background in custom CSS file due bug https://github.com/facebook/docusaurus/issues/3678 */
+:where(:root) {
+  --docusaurus-highlighted-code-line-bg: rgb(72 77 91);
+}
+
+:where([data-theme='dark']) {
+  --docusaurus-highlighted-code-line-bg: rgb(100 100 100);
+}
+
+.codeLine {
+  display: table-row;
+  counter-increment: line-count;
+}
+
+.codeLineNumber {
+  display: table-cell;
+  text-align: right;
+  width: 1%;
+  position: sticky;
+  left: 0;
+  padding: 0 var(--ifm-pre-padding);
+  background: var(--ifm-pre-background);
+}
+
+.codeLineNumber::before {
+  content: counter(line-count);
+  opacity: 0.4;
+}
+
+.highlightedCodeLine .codeLineNumber::before {
+  opacity: 0.8;
+}
+
+.codeLineContent {
+  padding-right: var(--ifm-pre-padding);
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 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 {translate} from '@docusaurus/Translate';
+import type {Props} from '@theme/CodeBlock/WordWrapButton';
+
+import styles from './styles.module.css';
+
+export default function WordWrapButton({
+  className,
+  onClick,
+  isEnabled,
+}: Props): JSX.Element | null {
+  const title = translate({
+    id: 'theme.CodeBlock.wordWrapToggle',
+    message: 'Toggle word wrap',
+    description:
+      'The title attribute for toggle word wrapping button of code block lines',
+  });
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={clsx(
+        'clean-btn',
+        className,
+        isEnabled && styles.wordWrapButtonEnabled,
+      )}
+      aria-label={title}
+      title={title}>
+      <svg
+        className={styles.wordWrapButtonIcon}
+        viewBox="0 0 24 24"
+        aria-hidden="true">
+        <path
+          fill="currentColor"
+          d="M4 19h6v-2H4v2zM20 5H4v2h16V5zm-3 6H4v2h13.25c1.1 0 2 .9 2 2s-.9 2-2 2H15v-2l-3 3l3 3v-2h2c2.21 0 4-1.79 4-4s-1.79-4-4-4z"
+        />
+      </svg>
+    </button>
+  );
+}

package/src/theme/CodeBlock/WordWrapButton/styles.module.css

@@ -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.
+ */
+
+.wordWrapButtonIcon {
+  width: 1.2rem;
+  height: 1.2rem;
+}
+
+.wordWrapButtonEnabled .wordWrapButtonIcon {
+  color: var(--ifm-color-primary);
+}

package/src/theme/CodeBlock/index.tsx

@@ -5,177 +5,41 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {isValidElement, useEffect, useState} from 'react';
-import clsx from 'clsx';
-import Highlight, {defaultProps, type Language} from 'prism-react-renderer';
-import copy from 'copy-text-to-clipboard';
-import Translate, {translate} from '@docusaurus/Translate';
-import {
-  useThemeConfig,
-  parseCodeBlockTitle,
-  parseLanguage,
-  parseLines,
-  ThemeClassNames,
-  usePrismTheme,
-} from '@docusaurus/theme-common';
+import React, {isValidElement, type ReactNode} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import type {Props} from '@theme/CodeBlock';
+import ElementContent from '@theme/CodeBlock/Content/Element';
+import StringContent from '@theme/CodeBlock/Content/String';
 
-import styles from './styles.module.css';
-
-export default function CodeBlock({
-  children,
-  className: blockClassName = '',
-  metastring,
-  title,
-  language: languageProp,
-}: Props): JSX.Element {
-  const {prism} = useThemeConfig();
-
-  const [showCopied, setShowCopied] = useState(false);
-  const [mounted, setMounted] = useState(false);
-  // The Prism theme on SSR is always the default theme but the site theme
-  // can be in a different mode. React hydration doesn't update DOM styles
-  // that come from SSR. Hence force a re-render after mounting to apply the
-  // current relevant styles. There will be a flash seen of the original
-  // styles seen using this current approach but that's probably ok. Fixing
-  // the flash will require changing the theming approach and is not worth it
-  // at this point.
-  useEffect(() => {
-    setMounted(true);
-  }, []);
-
-  // 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 codeBlockTitle = parseCodeBlockTitle(metastring) || title;
-  const prismTheme = usePrismTheme();
-
-  // <pre> tags in markdown map to CodeBlocks and they may contain JSX children.
-  // When the children is not a simple string, we just return a styled block
-  // without actually highlighting.
+/**
+ * Best attempt to make the children a plain string so it is copyable. If there
+ * are react elements, we will not be able to copy the content, and it will
+ * return `children` as-is; otherwise, it concatenates the string children
+ * together.
+ */
+function maybeStringifyChildren(children: ReactNode): ReactNode {
   if (React.Children.toArray(children).some((el) => isValidElement(el))) {
-    return (
-      <Highlight
-        {...defaultProps}
-        key={String(mounted)}
-        theme={prismTheme}
-        code=""
-        language={'text' as Language}>
-        {({className, style}) => (
-          <pre
-            /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
-            tabIndex={0}
-            className={clsx(
-              className,
-              styles.codeBlockStandalone,
-              'thin-scrollbar',
-              styles.codeBlockContainer,
-              blockClassName,
-              ThemeClassNames.common.codeBlock,
-            )}
-            style={style}>
-            <code className={styles.codeBlockLines}>{children}</code>
-          </pre>
-        )}
-      </Highlight>
-    );
+    return children;
   }
-
   // The children is now guaranteed to be one/more plain strings
-  const content = Array.isArray(children)
-    ? children.join('')
-    : (children as string);
-
-  const language =
-    languageProp ?? parseLanguage(blockClassName) ?? prism.defaultLanguage;
-  const {highlightLines, code} = parseLines(content, metastring, language);
-
-  const handleCopyCode = () => {
-    copy(code);
-    setShowCopied(true);
-
-    setTimeout(() => setShowCopied(false), 2000);
-  };
+  return Array.isArray(children) ? children.join('') : (children as string);
+}
 
+export default function CodeBlock({
+  children: rawChildren,
+  ...props
+}: Props): JSX.Element {
+  // The Prism theme on SSR is always the default theme but the site theme can
+  // be in a different mode. React hydration doesn't update DOM styles that come
+  // from SSR. Hence force a re-render after mounting to apply the current
+  // relevant styles.
+  const isBrowser = useIsBrowser();
+  const children = maybeStringifyChildren(rawChildren);
+  const CodeBlockComp =
+    typeof children === 'string' ? StringContent : ElementContent;
   return (
-    <Highlight
-      {...defaultProps}
-      key={String(mounted)}
-      theme={prismTheme}
-      code={code}
-      language={(language ?? 'text') as Language}>
-      {({className, style, tokens, getLineProps, getTokenProps}) => (
-        <div
-          className={clsx(
-            styles.codeBlockContainer,
-            blockClassName,
-            {
-              [`language-${language}`]:
-                language && !blockClassName.includes(`language-${language}`),
-            },
-            ThemeClassNames.common.codeBlock,
-          )}>
-          {codeBlockTitle && (
-            <div style={style} className={styles.codeBlockTitle}>
-              {codeBlockTitle}
-            </div>
-          )}
-          <div className={clsx(styles.codeBlockContent, language)}>
-            <pre
-              /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
-              tabIndex={0}
-              className={clsx(className, styles.codeBlock, 'thin-scrollbar')}
-              style={style}>
-              <code className={styles.codeBlockLines}>
-                {tokens.map((line, i) => {
-                  if (line.length === 1 && line[0].content === '\n') {
-                    line[0].content = '';
-                  }
-
-                  const lineProps = getLineProps({line, key: i});
-
-                  if (highlightLines.includes(i)) {
-                    lineProps.className += ' docusaurus-highlight-code-line';
-                  }
-
-                  return (
-                    <span key={i} {...lineProps}>
-                      {line.map((token, key) => (
-                        <span key={key} {...getTokenProps({token, key})} />
-                      ))}
-                      <br />
-                    </span>
-                  );
-                })}
-              </code>
-            </pre>
-
-            <button
-              type="button"
-              aria-label={translate({
-                id: 'theme.CodeBlock.copyButtonAriaLabel',
-                message: 'Copy code to clipboard',
-                description: 'The ARIA label for copy code blocks button',
-              })}
-              className={clsx(styles.copyButton, 'clean-btn')}
-              onClick={handleCopyCode}>
-              {showCopied ? (
-                <Translate
-                  id="theme.CodeBlock.copied"
-                  description="The copied button label on code blocks">
-                  Copied
-                </Translate>
-              ) : (
-                <Translate
-                  id="theme.CodeBlock.copy"
-                  description="The copy button label on code blocks">
-                  Copy
-                </Translate>
-              )}
-            </button>
-          </div>
-        </div>
-      )}
-    </Highlight>
+    <CodeBlockComp key={String(isBrowser)} {...props}>
+      {children as string}
+    </CodeBlockComp>
   );
 }

package/src/theme/ColorModeToggle/index.tsx

@@ -0,0 +1,67 @@
+/**
+ * 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 type {Props} from '@theme/ColorModeToggle';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {translate} from '@docusaurus/Translate';
+import IconLightMode from '@theme/IconLightMode';
+import IconDarkMode from '@theme/IconDarkMode';
+
+import clsx from 'clsx';
+import styles from './styles.module.css';
+
+function ColorModeToggle({className, value, onChange}: Props): JSX.Element {
+  const isBrowser = useIsBrowser();
+
+  const title = translate(
+    {
+      message: 'Switch between dark and light mode (currently {mode})',
+      id: 'theme.colorToggle.ariaLabel',
+      description: 'The ARIA label for the navbar color mode toggle',
+    },
+    {
+      mode:
+        value === 'dark'
+          ? translate({
+              message: 'dark mode',
+              id: 'theme.colorToggle.ariaLabel.mode.dark',
+              description: 'The name for the dark color mode',
+            })
+          : translate({
+              message: 'light mode',
+              id: 'theme.colorToggle.ariaLabel.mode.light',
+              description: 'The name for the light color mode',
+            }),
+    },
+  );
+
+  return (
+    <div className={clsx(styles.toggle, className)}>
+      <button
+        className={clsx(
+          'clean-btn',
+          styles.toggleButton,
+          !isBrowser && styles.toggleButtonDisabled,
+        )}
+        type="button"
+        onClick={() => onChange(value === 'dark' ? 'light' : 'dark')}
+        disabled={!isBrowser}
+        title={title}
+        aria-label={title}>
+        <IconLightMode
+          className={clsx(styles.toggleIcon, styles.lightToggleIcon)}
+        />
+        <IconDarkMode
+          className={clsx(styles.toggleIcon, styles.darkToggleIcon)}
+        />
+      </button>
+    </div>
+  );
+}
+
+export default React.memo(ColorModeToggle);

package/src/theme/ColorModeToggle/styles.module.css

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+
+.toggle {
+  width: 2rem;
+  height: 2rem;
+}
+
+.toggleButton {
+  -webkit-tap-highlight-color: transparent;
+  align-items: center;
+  display: flex;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  transition: background var(--ifm-transition-fast);
+}
+
+.toggleButton:hover {
+  background: var(--ifm-color-emphasis-200);
+}
+
+[data-theme='light'] .darkToggleIcon,
+[data-theme='dark'] .lightToggleIcon {
+  display: none;
+}
+
+.toggleButtonDisabled {
+  cursor: not-allowed;
+}

package/src/theme/Details/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {Details as DetailsGeneric} from '@docusaurus/theme-common';
+import {Details as DetailsGeneric} from '@docusaurus/theme-common/Details';
 import type {Props} from '@theme/Details';
 import styles from './styles.module.css';
 

package/src/theme/DocBreadcrumbs/index.tsx

@@ -15,21 +15,37 @@ import styles from './styles.module.css';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
+import {translate} from '@docusaurus/Translate';
+import IconHome from '@theme/IconHome';
 
 // TODO move to design system folder
 function BreadcrumbsItemLink({
   children,
   href,
+  isLast,
 }: {
   children: ReactNode;
-  href?: string;
+  href: string | undefined;
+  isLast: boolean;
 }): JSX.Element {
-  const className = clsx('breadcrumbs__link', styles.breadcrumbsItemLink);
+  const className = 'breadcrumbs__link';
+  if (isLast) {
+    return (
+      <span className={className} itemProp="name">
+        {children}
+      </span>
+    );
+  }
   return href ? (
-    <Link className={className} href={href}>
-      {children}
+    <Link className={className} href={href} itemProp="item">
+      <span itemProp="name">{children}</span>
     </Link>
   ) : (
+    // TODO Google search console doesn't like breadcrumb items without href.
+    // The schema doesn't seem to require `id` for each `item`, although Google
+    // insist to infer one, even if it's invalid. Removing `itemProp="item
+    // name"` for now, since I don't know how to properly fix it.
+    // See https://github.com/facebook/docusaurus/issues/7241
     <span className={className}>{children}</span>
   );
 }
@@ -38,16 +54,26 @@ function BreadcrumbsItemLink({
 function BreadcrumbsItem({
   children,
   active,
+  index,
+  addMicrodata,
 }: {
   children: ReactNode;
   active?: boolean;
+  index: number;
+  addMicrodata: boolean;
 }): JSX.Element {
   return (
     <li
+      {...(addMicrodata && {
+        itemScope: true,
+        itemProp: 'itemListElement',
+        itemType: 'https://schema.org/ListItem',
+      })}
       className={clsx('breadcrumbs__item', {
         'breadcrumbs__item--active': active,
       })}>
       {children}
+      <meta itemProp="position" content={String(index + 1)} />
     </li>
   );
 }
@@ -55,9 +81,18 @@ function BreadcrumbsItem({
 function HomeBreadcrumbItem() {
   const homeHref = useBaseUrl('/');
   return (
-    <BreadcrumbsItem>
-      <BreadcrumbsItemLink href={homeHref}>🏠</BreadcrumbsItemLink>
-    </BreadcrumbsItem>
+    <li className="breadcrumbs__item">
+      <Link
+        aria-label={translate({
+          id: 'theme.docs.breadcrumbs.home',
+          message: 'Home page',
+          description: 'The ARIA label for the home page in the breadcrumbs',
+        })}
+        className={clsx('breadcrumbs__link', styles.breadcrumbsItemLink)}
+        href={homeHref}>
+        <IconHome className={styles.breadcrumbHomeIcon} />
+      </Link>
+    </li>
   );
 }
 
@@ -75,16 +110,30 @@ export default function DocBreadcrumbs(): JSX.Element | null {
         ThemeClassNames.docs.docBreadcrumbs,
         styles.breadcrumbsContainer,
       )}
-      aria-label="breadcrumbs">
-      <ul className="breadcrumbs">
+      aria-label={translate({
+        id: 'theme.docs.breadcrumbs.navAriaLabel',
+        message: 'Breadcrumbs',
+        description: 'The ARIA label for the breadcrumbs',
+      })}>
+      <ul
+        className="breadcrumbs"
+        itemScope
+        itemType="https://schema.org/BreadcrumbList">
         {homePageRoute && <HomeBreadcrumbItem />}
-        {breadcrumbs.map((item, idx) => (
-          <BreadcrumbsItem key={idx} active={idx === breadcrumbs.length - 1}>
-            <BreadcrumbsItemLink href={item.href}>
-              {item.label}
-            </BreadcrumbsItemLink>
-          </BreadcrumbsItem>
-        ))}
+        {breadcrumbs.map((item, idx) => {
+          const isLast = idx === breadcrumbs.length - 1;
+          return (
+            <BreadcrumbsItem
+              key={idx}
+              active={isLast}
+              index={idx}
+              addMicrodata={!!item.href}>
+              <BreadcrumbsItemLink href={item.href} isLast={isLast}>
+                {item.label}
+              </BreadcrumbsItemLink>
+            </BreadcrumbsItem>
+          );
+        })}
       </ul>
     </nav>
   );

package/src/theme/DocBreadcrumbs/styles.module.css

@@ -6,21 +6,14 @@
  */
 
 .breadcrumbsContainer {
-  margin-bottom: 0.4rem;
+  --ifm-breadcrumb-size-multiplier: 0.8;
+  margin-bottom: 0.8rem;
 }
 
-.breadcrumbsItemLink {
-  --ifm-breadcrumb-size-multiplier: 0.7 !important;
-  margin-bottom: 0.4rem;
-  background: var(--ifm-color-gray-100);
-}
-
-html[data-theme='dark'] .breadcrumbsItemLink {
-  background-color: var(--ifm-color-gray-900);
-}
-
-@media (min-width: 997px) {
-  .breadcrumbsItemLink {
-    --ifm-breadcrumb-size-multiplier: 0.8;
-  }
+.breadcrumbHomeIcon {
+  position: relative;
+  top: 1px;
+  vertical-align: top;
+  height: 1.1rem;
+  width: 1.1rem;
 }