@docusaurus/theme-common 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/lib/utils/useThemeConfig.d.ts

@@ -1,21 +1,32 @@
-import { PrismTheme } from 'prism-react-renderer';
-import { CSSProperties } from 'react';
+/**
+ * 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 { PrismTheme } from 'prism-react-renderer';
+import type { DeepPartial } from 'utility-types';
+import type { MagicCommentConfig } from './codeBlockUtils';
 export declare type DocsVersionPersistence = 'localStorage' | 'none';
 export declare type NavbarItem = {
     type?: string | undefined;
     items?: NavbarItem[];
     label?: string;
     position?: 'left' | 'right';
+} & {
+    [key: string]: unknown;
 };
 export declare type NavbarLogo = {
     src: string;
     srcDark?: string;
+    width?: string | number;
+    height?: string | number;
     href?: string;
     target?: string;
     alt?: string;
 };
 export declare type Navbar = {
-    style: 'dark' | 'primary';
+    style?: 'dark' | 'primary';
     hideOnScroll: boolean;
     title?: string;
     items: NavbarItem[];
@@ -25,12 +36,6 @@ export declare type ColorModeConfig = {
     defaultMode: 'light' | 'dark';
     disableSwitch: boolean;
     respectPrefersColorScheme: boolean;
-    switchConfig: {
-        darkIcon: string;
-        darkIconStyle: CSSProperties;
-        lightIcon: string;
-        lightIconStyle: CSSProperties;
-    };
 };
 export declare type AnnouncementBarConfig = {
     id: string;
@@ -40,10 +45,11 @@ export declare type AnnouncementBarConfig = {
     isCloseable: boolean;
 };
 export declare type PrismConfig = {
-    theme?: PrismTheme;
+    theme: PrismTheme;
     darkTheme?: PrismTheme;
     defaultLanguage?: string;
-    additionalLanguages?: string[];
+    additionalLanguages: string[];
+    magicComments: MagicCommentConfig[];
 };
 export declare type FooterLinkItem = {
     label?: string;
@@ -51,33 +57,58 @@ export declare type FooterLinkItem = {
     href?: string;
     html?: string;
     prependBaseUrlToHref?: string;
+} & {
+    [key: string]: unknown;
 };
-export declare type FooterLinks = {
-    title?: string;
-    items: FooterLinkItem[];
+export declare type FooterLogo = {
+    alt?: string;
+    src: string;
+    srcDark?: string;
+    width?: string | number;
+    height?: string | number;
+    href?: string;
 };
-export declare type Footer = {
+export declare type FooterBase = {
     style: 'light' | 'dark';
-    logo?: {
-        alt?: string;
-        src?: string;
-        srcDark?: string;
-        href?: string;
-    };
+    logo?: FooterLogo;
     copyright?: string;
-    links: FooterLinks[];
+};
+export declare type MultiColumnFooter = FooterBase & {
+    links: {
+        title: string | null;
+        items: FooterLinkItem[];
+    }[];
+};
+export declare type SimpleFooter = FooterBase & {
+    links: FooterLinkItem[];
+};
+export declare type Footer = MultiColumnFooter | SimpleFooter;
+export declare type TableOfContents = {
+    minHeadingLevel: number;
+    maxHeadingLevel: number;
 };
 export declare type ThemeConfig = {
     docs: {
         versionPersistence: DocsVersionPersistence;
+        sidebar: {
+            hideable: boolean;
+            autoCollapseCategories: boolean;
+        };
     };
     navbar: Navbar;
     colorMode: ColorModeConfig;
     announcementBar?: AnnouncementBarConfig;
     prism: PrismConfig;
     footer?: Footer;
-    hideableSidebar: boolean;
-    image: string;
-    metadatas: Array<Record<string, string>>;
+    image?: string;
+    metadata: {
+        [key: string]: string;
+    }[];
+    tableOfContents: TableOfContents;
 };
+export declare type UserThemeConfig = DeepPartial<ThemeConfig>;
+/**
+ * A convenient/more semantic way to get theme config from context.
+ */
 export declare function useThemeConfig(): ThemeConfig;
+//# sourceMappingURL=useThemeConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useThemeConfig.d.ts","sourceRoot":"","sources":["../../src/utils/useThemeConfig.ts"],"names":[],"mappings":"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"}

package/lib/utils/useThemeConfig.js

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+/**
+ * A convenient/more semantic way to get theme config from context.
+ */
 export function useThemeConfig() {
     return useDocusaurusContext().siteConfig.themeConfig;
 }
+//# sourceMappingURL=useThemeConfig.js.map

package/lib/utils/useThemeConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThemeConfig.js","sourceRoot":"","sources":["../../src/utils/useThemeConfig.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AA6HpE;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,oBAAoB,EAAE,CAAC,UAAU,CAAC,WAA0B,CAAC;AACtE,CAAC"}

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "2.0.0-beta.1ec2c95e3",
+  "version": "2.0.0-beta.21",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
+  "sideEffects": [
+    "lib/components/Details/*",
+    "*.css"
+  ],
+  "exports": {
+    ".": "./lib/index.js",
+    "./Details": "./lib/components/Details/index.js"
+  },
   "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch"
+    "build": "tsc && node ../../admin/scripts/copyUntypedFiles.js",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --watch",
+    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "publishConfig": {
     "access": "public"
@@ -18,23 +28,28 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.1ec2c95e3",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.1ec2c95e3",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.1ec2c95e3",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.1ec2c95e3",
-    "@docusaurus/types": "2.0.0-beta.1ec2c95e3",
-    "tslib": "^2.1.0"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.21",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.21",
+    "clsx": "^1.1.1",
+    "parse-numeric-range": "^1.3.0",
+    "prism-react-renderer": "^1.3.3",
+    "tslib": "^2.4.0",
+    "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.1ec2c95e3"
+    "@docusaurus/core": "2.0.0-beta.21",
+    "@docusaurus/types": "2.0.0-beta.21",
+    "fs-extra": "^10.1.0",
+    "lodash": "^4.17.21"
   },
   "peerDependencies": {
-    "prism-react-renderer": "^1.2.1",
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=16.14"
   },
-  "gitHead": "05c1ed75bb06738f274fe71baf71749a05b2db24"
+  "gitHead": "69ac49fc6909517f13615ee40290c4bd00c39df4"
 }

package/src/components/Collapsible/index.tsx

@@ -0,0 +1,263 @@
+/**
+ * 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, {
+  useState,
+  useEffect,
+  useRef,
+  useCallback,
+  useLayoutEffect,
+  type RefObject,
+  type Dispatch,
+  type SetStateAction,
+  type ReactNode,
+} from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+const DefaultAnimationEasing = 'ease-in-out';
+
+/**
+ * This hook is a very thin wrapper around a `useState`.
+ */
+export function useCollapsible({
+  initialState,
+}: {
+  /** The initial state. Will be non-collapsed by default. */
+  initialState?: boolean | (() => boolean);
+}): {
+  collapsed: boolean;
+  setCollapsed: Dispatch<SetStateAction<boolean>>;
+  toggleCollapsed: () => void;
+} {
+  const [collapsed, setCollapsed] = useState(initialState ?? false);
+
+  const toggleCollapsed = useCallback(() => {
+    setCollapsed((expanded) => !expanded);
+  }, []);
+
+  return {
+    collapsed,
+    setCollapsed,
+    toggleCollapsed,
+  };
+}
+
+const CollapsedStyles = {
+  display: 'none',
+  overflow: 'hidden',
+  height: '0px',
+} as const;
+
+const ExpandedStyles = {
+  display: 'block',
+  overflow: 'visible',
+  height: 'auto',
+} as const;
+
+function applyCollapsedStyle(el: HTMLElement, collapsed: boolean) {
+  const collapsedStyles = collapsed ? CollapsedStyles : ExpandedStyles;
+  el.style.display = collapsedStyles.display;
+  el.style.overflow = collapsedStyles.overflow;
+  el.style.height = collapsedStyles.height;
+}
+
+/*
+Lex111: Dynamic transition duration is used in Material design, this technique
+is good for a large number of items.
+https://material.io/archive/guidelines/motion/duration-easing.html#duration-easing-dynamic-durations
+https://github.com/mui-org/material-ui/blob/e724d98eba018e55e1a684236a2037e24bcf050c/packages/material-ui/src/styles/createTransitions.js#L40-L43
+ */
+function getAutoHeightDuration(height: number) {
+  const constant = height / 36;
+  return Math.round((4 + 15 * constant ** 0.25 + constant / 5) * 10);
+}
+
+type CollapsibleAnimationConfig = {
+  duration?: number;
+  easing?: string;
+};
+
+function useCollapseAnimation({
+  collapsibleRef,
+  collapsed,
+  animation,
+}: {
+  collapsibleRef: RefObject<HTMLElement>;
+  collapsed: boolean;
+  animation?: CollapsibleAnimationConfig;
+}) {
+  const mounted = useRef(false);
+
+  useEffect(() => {
+    const el = collapsibleRef.current!;
+
+    function getTransitionStyles() {
+      const height = el.scrollHeight;
+      const duration = animation?.duration ?? getAutoHeightDuration(height);
+      const easing = animation?.easing ?? DefaultAnimationEasing;
+      return {
+        transition: `height ${duration}ms ${easing}`,
+        height: `${height}px`,
+      };
+    }
+
+    function applyTransitionStyles() {
+      const transitionStyles = getTransitionStyles();
+      el.style.transition = transitionStyles.transition;
+      el.style.height = transitionStyles.height;
+    }
+
+    // On mount, we just apply styles, no animated transition
+    if (!mounted.current) {
+      applyCollapsedStyle(el, collapsed);
+      mounted.current = true;
+      return undefined;
+    }
+
+    el.style.willChange = 'height';
+
+    function startAnimation() {
+      const animationFrame = requestAnimationFrame(() => {
+        // When collapsing
+        if (collapsed) {
+          applyTransitionStyles();
+
+          requestAnimationFrame(() => {
+            el.style.height = CollapsedStyles.height;
+            el.style.overflow = CollapsedStyles.overflow;
+          });
+        }
+        // When expanding
+        else {
+          el.style.display = 'block';
+          requestAnimationFrame(() => {
+            applyTransitionStyles();
+          });
+        }
+      });
+
+      return () => cancelAnimationFrame(animationFrame);
+    }
+
+    return startAnimation();
+  }, [collapsibleRef, collapsed, animation]);
+}
+
+type CollapsibleElementType = React.ElementType<
+  Pick<React.HTMLAttributes<unknown>, 'className' | 'onTransitionEnd' | 'style'>
+>;
+
+/**
+ * Prevent hydration layout shift before animations are handled imperatively
+ * with JS
+ */
+function getSSRStyle(collapsed: boolean) {
+  if (ExecutionEnvironment.canUseDOM) {
+    return undefined;
+  }
+  return collapsed ? CollapsedStyles : ExpandedStyles;
+}
+
+type CollapsibleBaseProps = {
+  /** The actual DOM element to be used in the markup. */
+  as?: CollapsibleElementType;
+  /** Initial collapsed state. */
+  collapsed: boolean;
+  children: ReactNode;
+  /** Configuration of animation, like `duration` and `easing` */
+  animation?: CollapsibleAnimationConfig;
+  /**
+   * A callback fired when the collapse transition animation ends. Receives
+   * the **new** collapsed state: e.g. when
+   * expanding, `collapsed` will be `false`. You can use this for some "cleanup"
+   * like applying new styles when the container is fully expanded.
+   */
+  onCollapseTransitionEnd?: (collapsed: boolean) => void;
+  /** Class name for the underlying DOM element. */
+  className?: string;
+  /**
+   * This is mostly useful for details/summary component where ssrStyle is not
+   * needed (as details are hidden natively) and can mess up with the browser's
+   * native behavior when JS fails to load or is disabled
+   */
+  disableSSRStyle?: boolean;
+};
+
+function CollapsibleBase({
+  as: As = 'div',
+  collapsed,
+  children,
+  animation,
+  onCollapseTransitionEnd,
+  className,
+  disableSSRStyle,
+}: CollapsibleBaseProps) {
+  const collapsibleRef = useRef<HTMLElement>(null);
+
+  useCollapseAnimation({collapsibleRef, collapsed, animation});
+
+  return (
+    <As
+      // @ts-expect-error: the "too complicated type" is produced from
+      // "CollapsibleElementType" being a huge union
+      ref={collapsibleRef as RefObject<never>} // Refs are contravariant, which is not expressible in TS
+      style={disableSSRStyle ? undefined : getSSRStyle(collapsed)}
+      onTransitionEnd={(e: React.TransitionEvent) => {
+        if (e.propertyName !== 'height') {
+          return;
+        }
+
+        applyCollapsedStyle(collapsibleRef.current!, collapsed);
+        onCollapseTransitionEnd?.(collapsed);
+      }}
+      className={className}>
+      {children}
+    </As>
+  );
+}
+
+function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
+  const [mounted, setMounted] = useState(!collapsed);
+  // Updated in effect so that first expansion transition can work
+  const [lazyCollapsed, setLazyCollapsed] = useState(collapsed);
+
+  useLayoutEffect(() => {
+    if (!collapsed) {
+      setMounted(true);
+    }
+  }, [collapsed]);
+
+  useLayoutEffect(() => {
+    if (mounted) {
+      setLazyCollapsed(collapsed);
+    }
+  }, [mounted, collapsed]);
+
+  return mounted ? (
+    <CollapsibleBase {...props} collapsed={lazyCollapsed} />
+  ) : null;
+}
+
+type CollapsibleProps = CollapsibleBaseProps & {
+  /**
+   * Delay rendering of the content till first expansion. Marked as required to
+   * force us to think if content should be server-rendered or not. This has
+   * perf impact since it reduces html file sizes, but could undermine SEO.
+   * @see https://github.com/facebook/docusaurus/issues/4753
+   */
+  lazy: boolean;
+};
+
+/**
+ * A headless component providing smooth and uniform collapsing behavior. The
+ * component will be invisible (zero height) when collapsed. Doesn't provide
+ * interactivity by itself: collapse state is toggled through props.
+ */
+export function Collapsible({lazy, ...props}: CollapsibleProps): JSX.Element {
+  const Comp = lazy ? CollapsibleLazy : CollapsibleBase;
+  return <Comp {...props} />;
+}

package/src/components/Details/index.tsx

@@ -0,0 +1,109 @@
+/**
+ * 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, {
+  useRef,
+  useState,
+  type ComponentProps,
+  type ReactElement,
+} from 'react';
+import clsx from 'clsx';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {useCollapsible, Collapsible} from '../Collapsible';
+import styles from './styles.module.css';
+
+function isInSummary(node: HTMLElement | null): boolean {
+  if (!node) {
+    return false;
+  }
+  return node.tagName === 'SUMMARY' || isInSummary(node.parentElement);
+}
+
+function hasParent(node: HTMLElement | null, parent: HTMLElement): boolean {
+  if (!node) {
+    return false;
+  }
+  return node === parent || hasParent(node.parentElement, parent);
+}
+
+export type DetailsProps = {
+  /** Summary is provided as props, including the wrapping `<summary>` tag */
+  summary?: ReactElement;
+} & ComponentProps<'details'>;
+
+/**
+ * A mostly un-styled `<details>` element with smooth collapsing. Provides some
+ * very lightweight styles, but you should bring your UI.
+ */
+export function Details({
+  summary,
+  children,
+  ...props
+}: DetailsProps): JSX.Element {
+  const isBrowser = useIsBrowser();
+  const detailsRef = useRef<HTMLDetailsElement>(null);
+
+  const {collapsed, setCollapsed} = useCollapsible({
+    initialState: !props.open,
+  });
+  // Use a separate state for the actual details prop, because it must be set
+  // only after animation completes, otherwise close animations won't work
+  const [open, setOpen] = useState(props.open);
+
+  return (
+    // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-noninteractive-element-interactions
+    <details
+      {...props}
+      ref={detailsRef}
+      open={open}
+      data-collapsed={collapsed}
+      className={clsx(
+        styles.details,
+        isBrowser && styles.isBrowser,
+        props.className,
+      )}
+      onMouseDown={(e) => {
+        const target = e.target as HTMLElement;
+        // Prevent a double-click to highlight summary text
+        if (isInSummary(target) && e.detail > 1) {
+          e.preventDefault();
+        }
+      }}
+      onClick={(e) => {
+        e.stopPropagation(); // For isolation of multiple nested details/summary
+        const target = e.target as HTMLElement;
+        const shouldToggle =
+          isInSummary(target) && hasParent(target, detailsRef.current!);
+        if (!shouldToggle) {
+          return;
+        }
+        e.preventDefault();
+        if (collapsed) {
+          setCollapsed(false);
+          setOpen(true);
+        } else {
+          setCollapsed(true);
+          // Don't do this, it breaks close animation!
+          // setOpen(false);
+        }
+      }}>
+      {/* eslint-disable-next-line @docusaurus/no-untranslated-text */}
+      {summary ?? <summary>Details</summary>}
+
+      <Collapsible
+        lazy={false} // Content might matter for SEO in this case
+        collapsed={collapsed}
+        disableSSRStyle // Allows component to work fine even with JS disabled!
+        onCollapseTransitionEnd={(newCollapsed) => {
+          setCollapsed(newCollapsed);
+          setOpen(!newCollapsed);
+        }}>
+        <div className={styles.collapsibleContent}>{children}</div>
+      </Collapsible>
+    </details>
+  );
+}

package/src/components/Details/styles.module.css

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+
+/*
+CSS variables, meant to be overridden by final theme
+ */
+.details {
+  --docusaurus-details-summary-arrow-size: 0.38rem;
+  --docusaurus-details-transition: transform 200ms ease;
+  --docusaurus-details-decoration-color: grey;
+}
+
+.details > summary {
+  position: relative;
+  cursor: pointer;
+  list-style: none;
+  padding-left: 1rem;
+}
+
+/* TODO: deprecation, need to remove this after Safari will support `::marker` */
+.details > summary::-webkit-details-marker {
+  display: none;
+}
+
+.details > summary::before {
+  position: absolute;
+  top: 0.45rem;
+  left: 0;
+
+  /* CSS-only Arrow */
+  content: '';
+  border-width: var(--docusaurus-details-summary-arrow-size);
+  border-style: solid;
+  border-color: transparent transparent transparent
+    var(--docusaurus-details-decoration-color);
+
+  /* Arrow rotation anim */
+  transform: rotate(0deg);
+  transition: var(--docusaurus-details-transition);
+  transform-origin: calc(var(--docusaurus-details-summary-arrow-size) / 2) 50%;
+}
+
+/* When JS disabled/failed to load: we use the open property for arrow animation: */
+.details[open]:not(.isBrowser) > summary::before,
+/* When JS works: we use the data-attribute for arrow animation */
+.details[data-collapsed='false'].isBrowser > summary::before {
+  transform: rotate(90deg);
+}
+
+.collapsibleContent {
+  margin-top: 1rem;
+  border-top: 1px solid var(--docusaurus-details-decoration-color);
+  padding-top: 1rem;
+}
+
+.collapsibleContent > *:last-child {
+  margin-bottom: 0;
+}