@docusaurus/theme-common 3.7.0 → 3.8.0-canary-6324

package/src/utils/{codeBlockUtils.ts → codeBlockUtils.tsx}

@@ -5,9 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {CSSProperties} from 'react';
+import type {CSSProperties, ReactNode} from 'react';
+import {createContext, useContext, useMemo} from 'react';
+import clsx from 'clsx';
 import rangeParser from 'parse-numeric-range';
+import {ReactContextError} from './reactUtils';
 import type {PrismTheme, PrismThemeEntry} from 'prism-react-renderer';
+import type {WordWrap} from '../hooks/useCodeWordWrap';
 
 const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
 const metastringLinesRangeRegex = /\{(?<range>[\d,-]+)\}/;
@@ -151,69 +155,81 @@ export function parseCodeBlockTitle(metastring?: string): string {
   return metastring?.match(codeBlockTitleRegex)?.groups!.title ?? '';
 }
 
+function getMetaLineNumbersStart(metastring?: string): number | undefined {
+  const showLineNumbersMeta = metastring
+    ?.split(' ')
+    .find((str) => str.startsWith('showLineNumbers'));
+
+  if (showLineNumbersMeta) {
+    if (showLineNumbersMeta.startsWith('showLineNumbers=')) {
+      const value = showLineNumbersMeta.replace('showLineNumbers=', '');
+      return parseInt(value, 10);
+    }
+    return 1;
+  }
+
+  return undefined;
+}
+
+export function getLineNumbersStart({
+  showLineNumbers,
+  metastring,
+}: {
+  showLineNumbers: boolean | number | undefined;
+  metastring: string | undefined;
+}): number | undefined {
+  const defaultStart = 1;
+  if (typeof showLineNumbers === 'boolean') {
+    return showLineNumbers ? defaultStart : undefined;
+  }
+  if (typeof showLineNumbers === 'number') {
+    return showLineNumbers;
+  }
+  return getMetaLineNumbersStart(metastring);
+}
+
+// TODO Docusaurus v4: remove, only kept for internal retro-compatibility
+//  See https://github.com/facebook/docusaurus/pull/11153
 export function containsLineNumbers(metastring?: string): boolean {
   return Boolean(metastring?.includes('showLineNumbers'));
 }
 
+type ParseCodeLinesParam = {
+  /**
+   * The full metastring, as received from MDX. Line ranges declared here
+   * start at 1.
+   */
+  metastring: string | undefined;
+  /**
+   * Language of the code block, used to determine which kinds of magic
+   * comment styles to enable.
+   */
+  language: string | undefined;
+  /**
+   * Magic comment types that we should try to parse. Each entry would
+   * correspond to one class name to apply to each line.
+   */
+  magicComments: MagicCommentConfig[];
+};
+
 /**
- * Gets the language name from the class name (set by MDX).
- * e.g. `"language-javascript"` => `"javascript"`.
- * Returns undefined if there is no language class name.
+ * The highlighted lines, 0-indexed. e.g. `{ 0: ["highlight", "sample"] }`
+ * means the 1st line should have `highlight` and `sample` as class names.
  */
-export function parseLanguage(className: string): string | undefined {
-  const languageClassName = className
-    .split(' ')
-    .find((str) => str.startsWith('language-'));
-  return languageClassName?.replace(/language-/, '');
-}
+type CodeLineClassNames = {[lineIndex: number]: string[]};
 
 /**
- * Parses the code content, strips away any magic comments, and returns the
- * clean content and the highlighted lines marked by the comments or metastring.
- *
- * If the metastring contains a range, the `content` will be returned as-is
- * without any parsing. The returned `lineClassNames` will be a map from that
- * number range to the first magic comment config entry (which _should_ be for
- * line highlight directives.)
- *
- * @param content The raw code with magic comments. Trailing newline will be
- * trimmed upfront.
- * @param options Options for parsing behavior.
+ * Code lines after applying magic comments or metastring highlight ranges
  */
-export function parseLines(
-  content: string,
-  options: {
-    /**
-     * The full metastring, as received from MDX. Line ranges declared here
-     * start at 1.
-     */
-    metastring: string | undefined;
-    /**
-     * Language of the code block, used to determine which kinds of magic
-     * comment styles to enable.
-     */
-    language: string | undefined;
-    /**
-     * Magic comment types that we should try to parse. Each entry would
-     * correspond to one class name to apply to each line.
-     */
-    magicComments: MagicCommentConfig[];
-  },
-): {
-  /**
-   * The highlighted lines, 0-indexed. e.g. `{ 0: ["highlight", "sample"] }`
-   * means the 1st line should have `highlight` and `sample` as class names.
-   */
-  lineClassNames: {[lineIndex: number]: string[]};
-  /**
-   * If there's number range declared in the metastring, the code block is
-   * returned as-is (no parsing); otherwise, this is the clean code with all
-   * magic comments stripped away.
-   */
+type ParsedCodeLines = {
   code: string;
-} {
-  let code = content.replace(/\n$/, '');
-  const {language, magicComments, metastring} = options;
+  lineClassNames: CodeLineClassNames;
+};
+
+function parseCodeLinesFromMetastring(
+  code: string,
+  {metastring, magicComments}: ParseCodeLinesParam,
+): ParsedCodeLines | null {
   // Highlighted lines specified in props: don't parse the content
   if (metastring && metastringLinesRangeRegex.test(metastring)) {
     const linesRange = metastring.match(metastringLinesRangeRegex)!.groups!
@@ -229,6 +245,14 @@ export function parseLines(
       .map((n) => [n - 1, [metastringRangeClassName]] as [number, string[]]);
     return {lineClassNames: Object.fromEntries(lines), code};
   }
+  return null;
+}
+
+function parseCodeLinesFromContent(
+  code: string,
+  params: ParseCodeLinesParam,
+): ParsedCodeLines {
+  const {language, magicComments} = params;
   if (language === undefined) {
     return {lineClassNames: {}, code};
   }
@@ -237,7 +261,7 @@ export function parseLines(
     magicComments,
   );
   // Go through line by line
-  const lines = code.split('\n');
+  const lines = code.split(/\r?\n/);
   const blocks = Object.fromEntries(
     magicComments.map((d) => [d.className, {start: 0, range: ''}]),
   );
@@ -278,7 +302,7 @@ export function parseLines(
     }
     lines.splice(lineNumber, 1);
   }
-  code = lines.join('\n');
+
   const lineClassNames: {[lineIndex: number]: string[]} = {};
   Object.entries(blocks).forEach(([className, {range}]) => {
     rangeParser(range).forEach((l) => {
@@ -286,7 +310,145 @@ export function parseLines(
       lineClassNames[l]!.push(className);
     });
   });
-  return {lineClassNames, code};
+
+  return {code: lines.join('\n'), lineClassNames};
+}
+
+/**
+ * Parses the code content, strips away any magic comments, and returns the
+ * clean content and the highlighted lines marked by the comments or metastring.
+ *
+ * If the metastring contains a range, the `content` will be returned as-is
+ * without any parsing. The returned `lineClassNames` will be a map from that
+ * number range to the first magic comment config entry (which _should_ be for
+ * line highlight directives.)
+ */
+export function parseLines(
+  code: string,
+  params: ParseCodeLinesParam,
+): ParsedCodeLines {
+  // Historical behavior: we remove last line break
+  const newCode = code.replace(/\r?\n$/, '');
+  // Historical behavior: we try one strategy after the other
+  // we don't support mixing metastring ranges + magic comments
+  return (
+    parseCodeLinesFromMetastring(newCode, {...params}) ??
+    parseCodeLinesFromContent(newCode, {...params})
+  );
+}
+
+/**
+ * Gets the language name from the class name (set by MDX).
+ * e.g. `"language-javascript"` => `"javascript"`.
+ * Returns undefined if there is no language class name.
+ */
+export function parseClassNameLanguage(
+  className: string | undefined,
+): string | undefined {
+  if (!className) {
+    return undefined;
+  }
+  const languageClassName = className
+    .split(' ')
+    .find((str) => str.startsWith('language-'));
+  return languageClassName?.replace(/language-/, '');
+}
+
+// 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();
+}
+
+function getLanguage(params: {
+  language: string | undefined;
+  className: string | undefined;
+  defaultLanguage: string | undefined;
+}): string {
+  return (
+    normalizeLanguage(
+      params.language ??
+        parseClassNameLanguage(params.className) ??
+        params.defaultLanguage,
+    ) ?? 'text'
+  ); // There's always a language, required by Prism;
+}
+
+/**
+ * This ensures that we always have the code block language as className
+ * For MDX code blocks this is provided automatically by MDX
+ * For JSX code blocks, the language gets added by this function
+ * This ensures both cases lead to a consistent HTML output
+ */
+function ensureLanguageClassName({
+  className,
+  language,
+}: {
+  className: string | undefined;
+  language: string;
+}): string {
+  return clsx(
+    className,
+    language &&
+      !className?.includes(`language-${language}`) &&
+      `language-${language}`,
+  );
+}
+
+export interface CodeBlockMetadata {
+  codeInput: string; // Including magic comments
+  code: string; // Rendered code, excluding magic comments
+  className: string; // There's always a "language-<lang>" className
+  language: string;
+  title: ReactNode;
+  lineNumbersStart: number | undefined;
+  lineClassNames: CodeLineClassNames;
+}
+
+export function createCodeBlockMetadata(params: {
+  code: string;
+  className: string | undefined;
+  language: string | undefined;
+  defaultLanguage: string | undefined;
+  metastring: string | undefined;
+  magicComments: MagicCommentConfig[];
+  title: ReactNode;
+  showLineNumbers: boolean | number | undefined;
+}): CodeBlockMetadata {
+  const language = getLanguage({
+    language: params.language,
+    defaultLanguage: params.defaultLanguage,
+    className: params.className,
+  });
+
+  const {lineClassNames, code} = parseLines(params.code, {
+    metastring: params.metastring,
+    magicComments: params.magicComments,
+    language,
+  });
+
+  const className = ensureLanguageClassName({
+    className: params.className,
+    language,
+  });
+
+  const title = parseCodeBlockTitle(params.metastring) || params.title;
+
+  const lineNumbersStart = getLineNumbersStart({
+    showLineNumbers: params.showLineNumbers,
+    metastring: params.metastring,
+  });
+
+  return {
+    codeInput: params.code,
+    code,
+    className,
+    language,
+    title,
+    lineNumbersStart,
+    lineClassNames,
+  };
 }
 
 export function getPrismCssVariables(prismTheme: PrismTheme): CSSProperties {
@@ -304,3 +466,39 @@ export function getPrismCssVariables(prismTheme: PrismTheme): CSSProperties {
   });
   return properties;
 }
+
+type CodeBlockContextValue = {
+  metadata: CodeBlockMetadata;
+  wordWrap: WordWrap;
+};
+
+const CodeBlockContext = createContext<CodeBlockContextValue | null>(null);
+
+export function CodeBlockContextProvider({
+  metadata,
+  wordWrap,
+  children,
+}: {
+  metadata: CodeBlockMetadata;
+  wordWrap: WordWrap;
+  children: ReactNode;
+}): ReactNode {
+  // Should we optimize this in 2 contexts?
+  // Unlike metadata, wordWrap is stateful and likely to trigger re-renders
+  const value: CodeBlockContextValue = useMemo(() => {
+    return {metadata, wordWrap};
+  }, [metadata, wordWrap]);
+  return (
+    <CodeBlockContext.Provider value={value}>
+      {children}
+    </CodeBlockContext.Provider>
+  );
+}
+
+export function useCodeBlockContext(): CodeBlockContextValue {
+  const value = useContext(CodeBlockContext);
+  if (value === null) {
+    throw new ReactContextError('CodeBlockContextProvider');
+  }
+  return value;
+}

package/src/utils/metadataUtils.tsx

@@ -10,7 +10,7 @@ import clsx from 'clsx';
 import Head from '@docusaurus/Head';
 import useRouteContext from '@docusaurus/useRouteContext';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
-import {useTitleFormatter} from './generalUtils';
+import {useTitleFormatter} from './titleFormatterUtils';
 
 type PageMetadataProps = {
   readonly title?: string;
@@ -20,6 +20,55 @@ type PageMetadataProps = {
   readonly children?: ReactNode;
 };
 
+function TitleMetadata({title}: {title: string}) {
+  const titleFormatter = useTitleFormatter();
+  const formattedTitle = titleFormatter.format(title);
+  return (
+    <Head>
+      <title>{formattedTitle}</title>
+      <meta property="og:title" content={formattedTitle} />
+    </Head>
+  );
+}
+
+function DescriptionMetadata({description}: {description: string}) {
+  return (
+    <Head>
+      <meta name="description" content={description} />
+      <meta property="og:description" content={description} />
+    </Head>
+  );
+}
+
+function ImageMetadata({image}: {image: string}) {
+  const {withBaseUrl} = useBaseUrlUtils();
+  const pageImage = withBaseUrl(image, {absolute: true});
+  return (
+    <Head>
+      <meta property="og:image" content={pageImage} />
+      <meta name="twitter:image" content={pageImage} />
+    </Head>
+  );
+}
+
+function KeywordsMetadata({
+  keywords,
+}: {
+  keywords: PageMetadataProps['keywords'];
+}) {
+  return (
+    <Head>
+      <meta
+        name="keywords"
+        content={
+          // https://github.com/microsoft/TypeScript/issues/17002
+          (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
+        }
+      />
+    </Head>
+  );
+}
+
 /**
  * Helper component to manipulate page metadata and override site defaults.
  * Works in the same way as Helmet.
@@ -31,33 +80,14 @@ export function PageMetadata({
   image,
   children,
 }: PageMetadataProps): ReactNode {
-  const pageTitle = useTitleFormatter(title);
-  const {withBaseUrl} = useBaseUrlUtils();
-  const pageImage = image ? withBaseUrl(image, {absolute: true}) : undefined;
-
   return (
-    <Head>
-      {title && <title>{pageTitle}</title>}
-      {title && <meta property="og:title" content={pageTitle} />}
-
-      {description && <meta name="description" content={description} />}
-      {description && <meta property="og:description" content={description} />}
-
-      {keywords && (
-        <meta
-          name="keywords"
-          content={
-            // https://github.com/microsoft/TypeScript/issues/17002
-            (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
-          }
-        />
-      )}
-
-      {pageImage && <meta property="og:image" content={pageImage} />}
-      {pageImage && <meta name="twitter:image" content={pageImage} />}
-
-      {children}
-    </Head>
+    <>
+      {title && <TitleMetadata title={title} />}
+      {description && <DescriptionMetadata description={description} />}
+      {keywords && <KeywordsMetadata keywords={keywords} />}
+      {image && <ImageMetadata image={image} />}
+      {children && <Head>{children}</Head>}
+    </>
   );
 }
 

package/src/utils/reactUtils.tsx

@@ -50,6 +50,9 @@ export function usePrevious<T>(value: T): T | undefined {
     ref.current = value;
   });
 
+  // TODO need to fix this React Compiler lint error
+  //  probably requires changing the API though
+  // eslint-disable-next-line react-compiler/react-compiler
   return ref.current;
 }
 
@@ -81,7 +84,7 @@ export function useShallowMemoObject<O extends object>(obj: O): O {
   const deps = Object.entries(obj);
   // Sort by keys to make it order-insensitive
   deps.sort((a, b) => a[0].localeCompare(b[0]));
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+  // eslint-disable-next-line react-compiler/react-compiler,react-hooks/exhaustive-deps
   return useMemo(() => obj, deps.flat());
 }
 

package/src/utils/scrollUtils.tsx

@@ -124,6 +124,7 @@ export function useScrollPosition(
     window.addEventListener('scroll', handleScroll, opts);
 
     return () => window.removeEventListener('scroll', handleScroll, opts);
+    // eslint-disable-next-line react-compiler/react-compiler
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [dynamicEffect, scrollEventsEnabledRef, ...deps]);
 }

package/src/utils/storageUtils.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useCallback, useRef, useSyncExternalStore} from 'react';
+import {useCallback, useState, useSyncExternalStore} from 'react';
 import SiteStorage from '@generated/site-storage';
 
 export type StorageType = (typeof SiteStorage)['type'] | 'none';
@@ -208,12 +208,12 @@ export function useStorageSlot(
   options?: {persistence?: StorageType},
 ): [string | null, StorageSlot] {
   // Not ideal but good enough: assumes storage slot config is constant
-  const storageSlot = useRef(() => {
+  const [storageSlot] = useState(() => {
     if (key === null) {
       return NoopStorageSlot;
     }
     return createStorageSlot(key, options);
-  }).current();
+  });
 
   const listen: StorageSlot['listen'] = useCallback(
     (onChange) => {

package/src/utils/titleFormatterUtils.tsx

@@ -0,0 +1,122 @@
+/**
+ * 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 {createContext, useContext} from 'react';
+import type {ReactNode} from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useRouteContext from '@docusaurus/useRouteContext';
+import {ReactContextError} from './reactUtils';
+
+type TitleFormatterParams = {
+  /**
+   * The page title to format
+   * Usually provided with these APIs:
+   * - <PageMetadata title={title}>
+   * - useTitleFormatter().format(title)
+   */
+  title: string;
+
+  /**
+   * The siteConfig.title value
+   */
+  siteTitle: string;
+
+  /**
+   * The siteConfig.titleDelimiter value
+   */
+  titleDelimiter: string;
+
+  /**
+   * The plugin that created the page you are on
+   */
+  plugin: {
+    id: string;
+    name: string;
+  };
+};
+
+/**
+ * This is the full formatting function, including all useful params
+ * Can be customized through React context with the provider
+ */
+export type TitleFormatterFn = (params: TitleFormatterParams) => string;
+
+/**
+ * The default formatter is provided in params for convenience
+ */
+export type TitleFormatterFnWithDefault = (
+  params: TitleFormatterParams & {
+    defaultFormatter: (params: TitleFormatterParams) => string;
+  },
+) => string;
+
+export const TitleFormatterFnDefault: TitleFormatterFn = ({
+  title,
+  siteTitle,
+  titleDelimiter,
+}): string => {
+  const trimmedTitle = title?.trim();
+  if (!trimmedTitle || trimmedTitle === siteTitle) {
+    return siteTitle;
+  }
+  return `${trimmedTitle} ${titleDelimiter} ${siteTitle}`;
+};
+
+/**
+ * This is the simpler API exposed to theme/users
+ */
+type TitleFormatter = {format: (title: string) => string};
+
+const TitleFormatterContext = createContext<TitleFormatterFnWithDefault | null>(
+  null,
+);
+
+export function TitleFormatterProvider({
+  formatter,
+  children,
+}: {
+  children: ReactNode;
+  formatter: TitleFormatterFnWithDefault;
+}): ReactNode {
+  return (
+    <TitleFormatterContext.Provider value={formatter}>
+      {children}
+    </TitleFormatterContext.Provider>
+  );
+}
+
+function useTitleFormatterContext() {
+  const value = useContext(TitleFormatterContext);
+  if (value === null) {
+    throw new ReactContextError('TitleFormatterProvider');
+  }
+  return value;
+}
+
+/**
+ * Returns a function to format the page title
+ */
+export function useTitleFormatter(): TitleFormatter {
+  const formatter = useTitleFormatterContext();
+  const {siteConfig} = useDocusaurusContext();
+  const {title: siteTitle, titleDelimiter} = siteConfig;
+
+  // Unfortunately we can only call this hook here, not in the provider
+  // Route context can't be accessed in any provider applied above the router
+  const {plugin} = useRouteContext();
+
+  return {
+    format: (title: string) =>
+      formatter({
+        title,
+        siteTitle,
+        titleDelimiter,
+        plugin,
+        defaultFormatter: TitleFormatterFnDefault,
+      }),
+  };
+}

package/src/utils/useThemeConfig.ts

@@ -9,12 +9,13 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import type {PrismTheme} from 'prism-react-renderer';
 import type {DeepPartial} from 'utility-types';
 import type {MagicCommentConfig} from './codeBlockUtils';
+import type {ColorMode} from '../contexts/colorMode';
 
 export type DocsVersionPersistence = 'localStorage' | 'none';
 
 // TODO improve types, use unions
 export type NavbarItem = {
-  type?: string | undefined;
+  type?: string;
   items?: NavbarItem[];
   label?: string;
   position?: 'left' | 'right';
@@ -44,7 +45,7 @@ export type Navbar = {
 };
 
 export type ColorModeConfig = {
-  defaultMode: 'light' | 'dark';
+  defaultMode: ColorMode;
   disableSwitch: boolean;
   respectPrefersColorScheme: boolean;
 };
@@ -103,6 +104,7 @@ export type TableOfContents = {
   maxHeadingLevel: number;
 };
 
+// TODO Docusaurus v4: use interface + declaration merging to enhance
 // Theme config after validation/normalization
 export type ThemeConfig = {
   docs: {

package/lib/utils/generalUtils.d.ts

@@ -1,11 +0,0 @@
-/**
- * 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.
- */
-/**
- * Formats the page's title based on relevant site config and other contexts.
- */
-export declare function useTitleFormatter(title?: string | undefined): string;
-//# sourceMappingURL=generalUtils.d.ts.map

package/lib/utils/generalUtils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generalUtils.d.ts","sourceRoot":"","sources":["../../src/utils/generalUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMpE"}