feat: details/summary theme / MDX component (#5216)

* Details component

* polish arrow animation

* fix text selection bug

* fix some edge cases + polish

* example of overriding baseClassName

* Move Details component to theme-common

* make component work even when JS is disabled or failed to load

* update arrow transform

* Details component: better handling of no-JS fallback mode: avoid delaying arrow navigation when JS (see review)

* prefix css vars with --docusaurus

* improve css arrow styling

* slightly change details/summary design

* better md doc + include quotes and details in doc

packages/docusaurus-theme-common/src/components/Collapsible/index.tsx

@@ -164,7 +164,12 @@ type CollapsibleBaseProps = {
   collapsed: boolean;
   children: ReactNode;
   animation?: CollapsibleAnimationConfig;
+  onCollapseTransitionEnd?: (collapsed: boolean) => void;
   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
+  disableSSRStyle?: boolean;
 };
 
 function CollapsibleBase({
@@ -172,7 +177,9 @@ function CollapsibleBase({
   collapsed,
   children,
   animation,
+  onCollapseTransitionEnd,
   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);
@@ -183,7 +190,7 @@ function CollapsibleBase({
     <As
       // @ts-expect-error: see https://twitter.com/sebastienlorber/status/1412784677795110914
       ref={collapsibleRef}
-      style={getSSRStyle(collapsed)}
+      style={disableSSRStyle ? undefined : getSSRStyle(collapsed)}
       onTransitionEnd={(e) => {
         if (e.propertyName !== 'height') {
           return;
@@ -197,10 +204,12 @@ function CollapsibleBase({
           parseInt(currentCollapsibleElementHeight, 10) === el.scrollHeight
         ) {
           applyCollapsedStyle(el, false);
+          onCollapseTransitionEnd?.(false);
         }
 
         if (currentCollapsibleElementHeight === CollapsedStyles.height) {
           applyCollapsedStyle(el, true);
+          onCollapseTransitionEnd?.(true);
         }
       }}
       className={className}>
@@ -239,7 +248,7 @@ type CollapsibleProps = CollapsibleBaseProps & {
   lazy: boolean;
 };
 
-export function Collapsible({lazy, ...props}: CollapsibleProps) {
+export function Collapsible({lazy, ...props}: CollapsibleProps): JSX.Element {
   const Comp = lazy ? CollapsibleLazy : CollapsibleBase;
   return <Comp {...props} />;
 }

packages/docusaurus-theme-common/src/components/Details/index.tsx

@@ -0,0 +1,94 @@
+/**
+ * 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, {ComponentProps, ReactElement, useRef, useState} from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import clsx from 'clsx';
+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?: ReactElement;
+} & ComponentProps<'details'>;
+
+const Details = ({summary, children, ...props}: DetailsProps): JSX.Element => {
+  const {isClient} = useDocusaurusContext();
+  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
+  const [open, setOpen] = useState(props.open);
+
+  return (
+    <details
+      {...props}
+      ref={detailsRef}
+      open={open}
+      data-collapsed={collapsed}
+      className={clsx(
+        styles.details,
+        {[styles.isClient]: isClient},
+        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);
+          // setOpen(false); // Don't do this, it breaks close animation!
+        }
+      }}>
+      {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>
+  );
+};
+
+export default Details;

packages/docusaurus-theme-common/src/components/Details/styles.module.css

@@ -0,0 +1,59 @@
+/**
+ * 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 overriden 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;
+  margin-left: 1.8rem;
+}
+
+.details > summary::-webkit-details-marker {
+  display: none;
+}
+
+.details > summary:before {
+  position: absolute;
+  top: 0.45rem;
+  left: -1.2rem;
+
+  /* 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
+    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(.isClient) > summary:before,
+/* When JS works: we use the data-attribute for arrow animation */
+.details[data-collapsed='false'].isClient > summary:before {
+  transform: rotate(90deg);
+}
+
+.collapsibleContent {
+  margin-top: 1rem;
+  border-top: 1px solid var(--docusaurus-details-decoration-color);
+  padding-top: 1rem;
+}

packages/docusaurus-theme-common/src/index.ts

@@ -37,11 +37,14 @@ export {useLocationChange} from './utils/useLocationChange';
 
 export {usePrevious} from './utils/usePrevious';
 
-export {useCollapsible, Collapsible} from './utils/useCollapsible';
+export {useCollapsible, Collapsible} from './components/Collapsible';
 export type {
   UseCollapsibleConfig,
   UseCollapsibleReturns,
-} from './utils/useCollapsible';
+} from './components/Collapsible';
+
+export {default as Details} from './components/Details';
+export type {DetailsProps} from './components/Details';
 
 export {
   MobileSecondaryMenuProvider,