@docusaurus/theme-common 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/components/Collapsible/index.tsx

@@ -5,35 +5,34 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import React, {
   useState,
   useEffect,
   useRef,
   useCallback,
-  RefObject,
-  Dispatch,
-  SetStateAction,
-  ReactNode,
   useLayoutEffect,
+  type RefObject,
+  type Dispatch,
+  type SetStateAction,
+  type ReactNode,
 } from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 
 const DefaultAnimationEasing = 'ease-in-out';
 
-export type UseCollapsibleConfig = {
-  initialState: boolean | (() => boolean);
-};
-
-export type UseCollapsibleReturns = {
+/**
+ * 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;
-};
-
-// This hook just define the state
-export function useCollapsible({
-  initialState,
-}: UseCollapsibleConfig): UseCollapsibleReturns {
+} {
   const [collapsed, setCollapsed] = useState(initialState ?? false);
 
   const toggleCollapsed = useCallback(() => {
@@ -67,7 +66,8 @@ function applyCollapsedStyle(el: HTMLElement, collapsed: boolean) {
 }
 
 /*
-Lex111: Dynamic transition duration is used in Material design, this technique is good for a large number of items.
+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
  */
@@ -120,7 +120,7 @@ function useCollapseAnimation({
 
     el.style.willChange = 'height';
 
-    function startAnimation(): () => void {
+    function startAnimation() {
       const animationFrame = requestAnimationFrame(() => {
         // When collapsing
         if (collapsed) {
@@ -151,7 +151,10 @@ type CollapsibleElementType = React.ElementType<
   Pick<React.HTMLAttributes<unknown>, 'className' | 'onTransitionEnd' | 'style'>
 >;
 
-// Prevent hydration layout shift before anims are handled imperatively with JS
+/**
+ * Prevent hydration layout shift before animations are handled imperatively
+ * with JS
+ */
 function getSSRStyle(collapsed: boolean) {
   if (ExecutionEnvironment.canUseDOM) {
     return undefined;
@@ -160,15 +163,27 @@ function getSSRStyle(collapsed: boolean) {
 }
 
 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 default native behavior of the browser when JS fails to load or is disabled
+  /**
+   * 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;
 };
 
@@ -181,36 +196,23 @@ function CollapsibleBase({
   className,
   disableSSRStyle,
 }: CollapsibleBaseProps) {
-  // any because TS is a pain for HTML element refs, see https://twitter.com/sebastienlorber/status/1412784677795110914
-  const collapsibleRef = useRef<any>(null);
+  const collapsibleRef = useRef<HTMLElement>(null);
 
   useCollapseAnimation({collapsibleRef, collapsed, animation});
 
   return (
     <As
-      // @ts-expect-error: see https://twitter.com/sebastienlorber/status/1412784677795110914
-      ref={collapsibleRef}
+      // @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) => {
+      onTransitionEnd={(e: React.TransitionEvent) => {
         if (e.propertyName !== 'height') {
           return;
         }
 
-        const el = collapsibleRef.current!;
-        const currentCollapsibleElementHeight = el.style.height;
-
-        if (
-          !collapsed &&
-          parseInt(currentCollapsibleElementHeight, 10) === el.scrollHeight
-        ) {
-          applyCollapsedStyle(el, false);
-          onCollapseTransitionEnd?.(false);
-        }
-
-        if (currentCollapsibleElementHeight === CollapsedStyles.height) {
-          applyCollapsedStyle(el, true);
-          onCollapseTransitionEnd?.(true);
-        }
+        applyCollapsedStyle(collapsibleRef.current!, collapsed);
+        onCollapseTransitionEnd?.(collapsed);
       }}
       className={className}>
       {children}
@@ -220,6 +222,8 @@ function CollapsibleBase({
 
 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) {
@@ -227,8 +231,6 @@ function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
     }
   }, [collapsed]);
 
-  // lazyCollapsed updated in effect so that the first expansion transition can work
-  const [lazyCollapsed, setLazyCollapsed] = useState(collapsed);
   useLayoutEffect(() => {
     if (mounted) {
       setLazyCollapsed(collapsed);
@@ -241,13 +243,20 @@ function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
 }
 
 type CollapsibleProps = CollapsibleBaseProps & {
-  // Lazy allows to delay the rendering when collapsed => it will render children only after hydration, on first expansion
-  // Required prop: it forces to think if content should be server-rendered or not!
-  // This has perf impact on the SSR output and html file sizes
-  // See https://github.com/facebook/docusaurus/issues/4753
+  /**
+   * 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

@@ -5,9 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ComponentProps, ReactElement, useRef, useState} from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+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';
 
@@ -26,21 +31,31 @@ function hasParent(node: HTMLElement | null, parent: HTMLElement): boolean {
 }
 
 export type DetailsProps = {
+  /** Summary is provided as props, including the wrapping `<summary>` tag */
   summary?: ReactElement;
 } & ComponentProps<'details'>;
 
-const Details = ({summary, children, ...props}: DetailsProps): JSX.Element => {
-  const {isClient} = useDocusaurusContext();
+/**
+ * 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,
   });
-  // We use a separate prop because it must be set only after animation completes
-  // Otherwise close anim won't work
+  // 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}
@@ -48,7 +63,7 @@ const Details = ({summary, children, ...props}: DetailsProps): JSX.Element => {
       data-collapsed={collapsed}
       className={clsx(
         styles.details,
-        {[styles.isClient]: isClient},
+        isBrowser && styles.isBrowser,
         props.className,
       )}
       onMouseDown={(e) => {
@@ -72,10 +87,12 @@ const Details = ({summary, children, ...props}: DetailsProps): JSX.Element => {
           setOpen(true);
         } else {
           setCollapsed(true);
-          // setOpen(false); // Don't do this, it breaks close animation!
+          // Don't do this, it breaks close animation!
+          // setOpen(false);
         }
       }}>
-      {summary}
+      {/* eslint-disable-next-line @docusaurus/no-untranslated-text */}
+      {summary ?? <summary>Details</summary>}
 
       <Collapsible
         lazy={false} // Content might matter for SEO in this case
@@ -89,6 +106,4 @@ const Details = ({summary, children, ...props}: DetailsProps): JSX.Element => {
       </Collapsible>
     </details>
   );
-};
-
-export default Details;
+}

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

@@ -6,7 +6,7 @@
  */
 
 /*
-CSS variables, meant to be overriden by final theme
+CSS variables, meant to be overridden by final theme
  */
 .details {
   --docusaurus-details-summary-arrow-size: 0.38rem;
@@ -18,25 +18,24 @@ CSS variables, meant to be overriden by final theme
   position: relative;
   cursor: pointer;
   list-style: none;
-  margin-left: 1.8rem;
+  padding-left: 1rem;
 }
 
+/* TODO: deprecation, need to remove this after Safari will support `::marker` */
 .details > summary::-webkit-details-marker {
   display: none;
 }
 
-.details > summary:before {
+.details > summary::before {
   position: absolute;
   top: 0.45rem;
-  left: -1.2rem;
+  left: 0;
 
   /* CSS-only Arrow */
   content: '';
-  width: 0;
-  height: 0;
-  border-top: var(--docusaurus-details-summary-arrow-size) solid transparent;
-  border-bottom: var(--docusaurus-details-summary-arrow-size) solid transparent;
-  border-left: var(--docusaurus-details-summary-arrow-size) solid
+  border-width: var(--docusaurus-details-summary-arrow-size);
+  border-style: solid;
+  border-color: transparent transparent transparent
     var(--docusaurus-details-decoration-color);
 
   /* Arrow rotation anim */
@@ -46,9 +45,9 @@ CSS variables, meant to be overriden by final theme
 }
 
 /* When JS disabled/failed to load: we use the open property for arrow animation: */
-.details[open]:not(.isClient) > summary:before,
+.details[open]:not(.isBrowser) > summary::before,
 /* When JS works: we use the data-attribute for arrow animation */
-.details[data-collapsed='false'].isClient > summary:before {
+.details[data-collapsed='false'].isBrowser > summary::before {
   transform: rotate(90deg);
 }
 
@@ -57,3 +56,7 @@ CSS variables, meant to be overriden by final theme
   border-top: 1px solid var(--docusaurus-details-decoration-color);
   padding-top: 1rem;
 }
+
+.collapsibleContent > *:last-child {
+  margin-bottom: 0;
+}

package/src/{utils/announcementBarUtils.tsx → contexts/announcementBar.tsx}

@@ -10,13 +10,13 @@ import React, {
   useEffect,
   useCallback,
   useMemo,
-  ReactNode,
   useContext,
-  createContext,
+  type ReactNode,
 } from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {createStorageSlot} from './storageUtils';
-import {useThemeConfig} from './useThemeConfig';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {createStorageSlot} from '../utils/storageUtils';
+import {ReactContextError} from '../utils/reactUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
 
 export const AnnouncementBarDismissStorageKey =
   'docusaurus.announcement.dismiss';
@@ -32,22 +32,28 @@ const isDismissedInStorage = () =>
 const setDismissedInStorage = (bool: boolean) =>
   AnnouncementBarDismissStorage.set(String(bool));
 
-type AnnouncementBarAPI = {
-  readonly isClosed: boolean;
+type ContextValue = {
+  /** Whether the announcement bar should be displayed. */
+  readonly isActive: boolean;
+  /**
+   * Callback fired when the user closes the announcement. Will be saved.
+   */
   readonly close: () => void;
 };
 
-const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
+const Context = React.createContext<ContextValue | null>(null);
+
+function useContextValue(): ContextValue {
   const {announcementBar} = useThemeConfig();
-  const {isClient} = useDocusaurusContext();
+  const isBrowser = useIsBrowser();
 
-  const [isClosed, setClosed] = useState(() => {
-    return isClient
-      ? // On client navigation: init with localstorage value
+  const [isClosed, setClosed] = useState(() =>
+    isBrowser
+      ? // On client navigation: init with local storage value
         isDismissedInStorage()
       : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
-        false;
-  });
+        false,
+  );
   // Update state after hydration
   useEffect(() => {
     setClosed(isDismissedInStorage());
@@ -66,8 +72,9 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
 
     let viewedId = IdStorage.get();
 
-    // retrocompatibility due to spelling mistake of default id
+    // Retrocompatibility due to spelling mistake of default id
     // see https://github.com/facebook/docusaurus/issues/3338
+    // cSpell:ignore annoucement
     if (viewedId === 'annoucement-bar') {
       viewedId = 'announcement-bar';
     }
@@ -83,33 +90,30 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
     if (isNewAnnouncement || !isDismissedInStorage()) {
       setClosed(false);
     }
-  }, []);
+  }, [announcementBar]);
 
-  return useMemo(() => {
-    return {
-      isClosed,
+  return useMemo(
+    () => ({
+      isActive: !!announcementBar && !isClosed,
       close: handleClose,
-    };
-  }, [isClosed]);
-};
-
-const AnnouncementBarContext = createContext<AnnouncementBarAPI | null>(null);
-
-export const AnnouncementBarProvider = ({children}: {children: ReactNode}) => {
-  const value = useAnnouncementBarContextValue();
-  return (
-    <AnnouncementBarContext.Provider value={value}>
-      {children}
-    </AnnouncementBarContext.Provider>
+    }),
+    [announcementBar, isClosed, handleClose],
   );
-};
-
-export const useAnnouncementBar = (): AnnouncementBarAPI => {
-  const api = useContext(AnnouncementBarContext);
+}
+
+export function AnnouncementBarProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const value = useContextValue();
+  return <Context.Provider value={value}>{children}</Context.Provider>;
+}
+
+export function useAnnouncementBar(): ContextValue {
+  const api = useContext(Context);
   if (!api) {
-    throw new Error(
-      'useAnnouncementBar(): AnnouncementBar not found in React context: make sure to use the AnnouncementBarProvider on top of the tree',
-    );
+    throw new ReactContextError('AnnouncementBarProvider');
   }
   return api;
-};
+}

package/src/contexts/blogPost.tsx

@@ -0,0 +1,80 @@
+/**
+ * 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, {useMemo, type ReactNode, useContext} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+
+import type {PropBlogPostContent} from '@docusaurus/plugin-content-blog';
+
+/**
+ * The React context value returned by the `useBlogPost()` hook.
+ * It contains useful data related to the currently browsed blog post.
+ */
+export type BlogPostContextValue = Pick<
+  PropBlogPostContent,
+  'metadata' | 'frontMatter' | 'assets' | 'toc'
+> & {
+  readonly isBlogPostPage: boolean;
+};
+
+const Context = React.createContext<BlogPostContextValue | null>(null);
+
+/**
+ * Note: we don't use `PropBlogPostContent` as context value on purpose. Metadata is
+ * currently stored inside the MDX component, but we may want to change that in
+ * the future.
+ */
+function useContextValue({
+  content,
+  isBlogPostPage,
+}: {
+  content: PropBlogPostContent;
+  isBlogPostPage: boolean;
+}): BlogPostContextValue {
+  return useMemo(
+    () => ({
+      metadata: content.metadata,
+      frontMatter: content.frontMatter,
+      assets: content.assets,
+      toc: content.toc,
+      isBlogPostPage,
+    }),
+    [content, isBlogPostPage],
+  );
+}
+
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the blog post to the children tree.
+ */
+export function BlogPostProvider({
+  children,
+  content,
+  isBlogPostPage = false,
+}: {
+  children: ReactNode;
+  content: PropBlogPostContent;
+  isBlogPostPage?: boolean;
+}): JSX.Element {
+  const contextValue = useContextValue({content, isBlogPostPage});
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Returns the data of the currently browsed blog post. Gives access to
+ * front matter, metadata, TOC, etc.
+ * When swizzling a low-level component (e.g. the "Edit this page" link)
+ * and you need some extra metadata, you don't have to drill the props
+ * all the way through the component tree: simply use this hook instead.
+ */
+export function useBlogPost(): BlogPostContextValue {
+  const blogPost = useContext(Context);
+  if (blogPost === null) {
+    throw new ReactContextError('BlogPostProvider');
+  }
+  return blogPost;
+}