@elastic/eui-docusaurus-theme 2.0.0

package/src/theme/DocRoot/Layout/Sidebar/index.tsx

@@ -0,0 +1,124 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React, { type ReactNode, useState, useCallback, JSX } from 'react';
+import clsx from 'clsx';
+import { css } from '@emotion/react';
+import {
+  prefersReducedMotion,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
+import { useDocsSidebar } from '@docusaurus/plugin-content-docs/client';
+import { useLocation } from '@docusaurus/router';
+import DocSidebar from '@theme-original/DocSidebar';
+import type { Props } from '@theme-original/DocRoot/Layout/Sidebar';
+import ExpandButton from '@theme-original/DocRoot/Layout/Sidebar/ExpandButton';
+
+// converted from css modules to Emotion
+const styles = {
+  docSidebarContainer: css`
+    display: none;
+
+    @media (min-width: 997px) {
+      // ensure scrolling still works
+      display: flex;
+      width: var(--doc-sidebar-width);
+      margin-top: calc(-1 * var(--ifm-navbar-height));
+      border-right: 1px solid var(--ifm-toc-border-color);
+      will-change: width;
+      transition: width var(--ifm-transition-fast) ease;
+      clip-path: inset(0);
+    }
+
+    .theme-doc-sidebar-menu.menu__list {
+      padding-inline-end: var(--eui-size-s);
+    }
+  `,
+  docSidebarContainerHidden: css`
+    width: var(--doc-sidebar-hidden-width);
+    cursor: pointer;
+  `,
+  sidebarViewport: css`
+    top: 0;
+    position: sticky;
+    height: 100%;
+    max-height: 100vh;
+  `,
+};
+
+// Reset sidebar state when sidebar changes
+// Use React key to unmount/remount the children
+// See https://github.com/facebook/docusaurus/issues/3414
+function ResetOnSidebarChange({ children }: { children: ReactNode }) {
+  const sidebar = useDocsSidebar();
+  return (
+    <React.Fragment key={sidebar?.name ?? 'noSidebar'}>
+      {children}
+    </React.Fragment>
+  );
+}
+
+export default function DocRootLayoutSidebar({
+  sidebar,
+  hiddenSidebarContainer,
+  setHiddenSidebarContainer,
+}: Props): JSX.Element {
+  const { pathname } = useLocation();
+
+  const [hiddenSidebar, setHiddenSidebar] = useState(false);
+  const toggleSidebar = useCallback(() => {
+    if (hiddenSidebar) {
+      setHiddenSidebar(false);
+    }
+    // onTransitionEnd won't fire when sidebar animation is disabled
+    // fixes https://github.com/facebook/docusaurus/issues/8918
+    if (!hiddenSidebar && prefersReducedMotion()) {
+      setHiddenSidebar(true);
+    }
+    setHiddenSidebarContainer((value) => !value);
+  }, [setHiddenSidebarContainer, hiddenSidebar]);
+
+  return (
+    <aside
+      className={clsx(
+        ThemeClassNames.docs.docSidebarContainer,
+        styles.docSidebarContainer.name // adding the name here to preserve the functionality of the class check further down
+      )}
+      css={[
+        styles.docSidebarContainer,
+        hiddenSidebarContainer && styles.docSidebarContainerHidden,
+      ]}
+      onTransitionEnd={(e) => {
+        if (
+          !e.currentTarget.classList.contains(styles.docSidebarContainer.name!)
+        ) {
+          return;
+        }
+
+        if (hiddenSidebarContainer) {
+          setHiddenSidebar(true);
+        }
+      }}
+    >
+      <ResetOnSidebarChange>
+        <div
+          className={clsx(hiddenSidebar && 'sidebarViewportHidden')}
+          css={styles.sidebarViewport}
+        >
+          <DocSidebar
+            sidebar={sidebar}
+            path={pathname}
+            onCollapse={toggleSidebar}
+            isHidden={hiddenSidebar}
+          />
+          {hiddenSidebar && <ExpandButton toggleSidebar={toggleSidebar} />}
+        </div>
+      </ResetOnSidebarChange>
+    </aside>
+  );
+}

package/src/theme/DocRoot/Layout/index.tsx

@@ -0,0 +1,72 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { useEffect, useState, JSX } from 'react';
+import { css } from '@emotion/react';
+import { useDocsSidebar } from '@docusaurus/plugin-content-docs/client';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import BackToTopButton from '@theme-original/BackToTopButton';
+import type { Props } from '@theme-original/DocRoot/Layout';
+import DocRootLayoutSidebar from '@theme-original/DocRoot/Layout/Sidebar';
+
+import DocRootLayoutMain from './Main';
+
+// converted from css modules to Emotion
+const styles = {
+  docRoot: css`
+    display: flex;
+    width: 100%;
+  `,
+  docsWrapper: css`
+    display: flex;
+    flex: 1 0 auto;
+  `,
+};
+
+export default function DocRootLayout({ children }: Props): JSX.Element {
+  const isBrowser = useIsBrowser();
+  const sidebar = useDocsSidebar();
+  const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
+
+  // Replicate browser hash scroll behavior to trigger it after the MDX content
+  // is rendered. Timeout = 0 should do the job here just fine as the effect
+  // will get executed at next render cycle when all elements are (hopefully)
+  // already in the DOM.
+  useEffect(() => {
+    if (!isBrowser) {
+      return;
+    }
+
+    if (window.location.hash) {
+      setTimeout(() => {
+        const element = document.getElementById(
+          window.location.hash.substring(1)
+        );
+        element?.scrollIntoView(true);
+      }, 100);
+    }
+  }, [isBrowser]);
+
+  return (
+    <div css={styles.docsWrapper}>
+      <BackToTopButton />
+      <div css={styles.docRoot}>
+        {sidebar && (
+          <DocRootLayoutSidebar
+            sidebar={sidebar.items}
+            hiddenSidebarContainer={hiddenSidebarContainer}
+            setHiddenSidebarContainer={setHiddenSidebarContainer}
+          />
+        )}
+        <DocRootLayoutMain hiddenSidebarContainer={hiddenSidebarContainer}>
+          {children}
+        </DocRootLayoutMain>
+      </div>
+    </div>
+  );
+}

package/src/theme/DocSidebarItem/Category/index.tsx

@@ -0,0 +1,266 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { type ComponentProps, useEffect, useMemo, JSX } from 'react';
+import clsx from 'clsx';
+import { css, Interpolation, Theme } from '@emotion/react';
+import {
+  ThemeClassNames,
+  useThemeConfig,
+  usePrevious,
+  Collapsible,
+  useCollapsible,
+} from '@docusaurus/theme-common';
+import { isSamePath } from '@docusaurus/theme-common/internal';
+import {
+  isActiveSidebarItem,
+  findFirstSidebarItemLink,
+  useDocSidebarItemsExpandedState,
+} from '@docusaurus/plugin-content-docs/client';
+import Link from '@docusaurus/Link';
+import { translate } from '@docusaurus/Translate';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import type { Props } from '@theme-original/DocSidebarItem/Category';
+import { EuiIcon, useEuiMemoizedStyles, UseEuiTheme } from '@elastic/eui';
+
+import DocSidebarItems from '../../DocSidebarItems';
+
+const getStyles = ({ euiTheme }: UseEuiTheme) => ({
+  listItem: css`
+    --ifm-menu-color-background-hover: var(--eui-background-color-primary);
+    --ifm-menu-color-background-active: var(--eui-background-color-primary);
+
+    --ifm-menu-link-padding-horizontal: ${euiTheme.size.s};
+    --ifm-menu-link-padding-vertical: calc(${euiTheme.size.xs} + 2px);
+
+    .menu__link--sublist {
+      color: ${euiTheme.colors.text};
+      font-size: var(--eui-font-size-s);
+      line-height: var(--eui-line-height-s);
+      font-weight: ${euiTheme.font.weight.bold};
+    }
+
+    .menu__link--active {
+      border-radius: ${euiTheme.border.radius.small};
+      color: ${euiTheme.colors.primary};
+    }
+  `,
+  button: css`
+    padding: ${euiTheme.size.s};
+  `,
+});
+
+// If we navigate to a category and it becomes active, it should automatically
+// expand itself
+function useAutoExpandActiveCategory({
+  isActive,
+  collapsed,
+  updateCollapsed,
+}: {
+  isActive: boolean;
+  collapsed: boolean;
+  updateCollapsed: (b: boolean) => void;
+}) {
+  const wasActive = usePrevious(isActive);
+  useEffect(() => {
+    const justBecameActive = isActive && !wasActive;
+    if (justBecameActive && collapsed) {
+      updateCollapsed(false);
+    }
+  }, [isActive, wasActive, collapsed, updateCollapsed]);
+}
+
+/**
+ * When a collapsible category has no link, we still link it to its first child
+ * during SSR as a temporary fallback. This allows to be able to navigate inside
+ * the category even when JS fails to load, is delayed or simply disabled
+ * React hydration becomes an optional progressive enhancement
+ * see https://github.com/facebookincubator/infima/issues/36#issuecomment-772543188
+ * see https://github.com/facebook/docusaurus/issues/3030
+ */
+function useCategoryHrefWithSSRFallback(
+  item: Props['item']
+): string | undefined {
+  const isBrowser = useIsBrowser();
+  return useMemo(() => {
+    if (item.href && !item.linkUnlisted) {
+      return item.href;
+    }
+    // In these cases, it's not necessary to render a fallback
+    // We skip the "findFirstCategoryLink" computation
+    if (isBrowser || !item.collapsible) {
+      return undefined;
+    }
+    return findFirstSidebarItemLink(item);
+  }, [item, isBrowser]);
+}
+
+function CollapseButton({
+  collapsed,
+  categoryLabel,
+  onClick,
+  ...rest
+}: {
+  collapsed: boolean;
+  categoryLabel: string;
+  onClick: ComponentProps<'button'>['onClick'];
+  css?: Interpolation<Theme>;
+}) {
+  return (
+    <button
+      aria-label={
+        collapsed
+          ? translate(
+              {
+                id: 'theme.DocSidebarItem.expandCategoryAriaLabel',
+                message: "Expand sidebar category '{label}'",
+                description: 'The ARIA label to expand the sidebar category',
+              },
+              { label: categoryLabel }
+            )
+          : translate(
+              {
+                id: 'theme.DocSidebarItem.collapseCategoryAriaLabel',
+                message: "Collapse sidebar category '{label}'",
+                description: 'The ARIA label to collapse the sidebar category',
+              },
+              { label: categoryLabel }
+            )
+      }
+      aria-expanded={!collapsed}
+      type="button"
+      className="clean-btn"
+      onClick={onClick}
+      {...rest}
+    >
+      <EuiIcon size="s" type={collapsed ? 'arrowRight' : 'arrowDown'} />
+    </button>
+  );
+}
+
+export default function DocSidebarItemCategory({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): JSX.Element {
+  const { items, label, collapsible, className, href } = item;
+  const {
+    docs: {
+      sidebar: { autoCollapseCategories },
+    },
+  } = useThemeConfig();
+  const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
+
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isCurrentPage = isSamePath(href, activePath);
+
+  const styles = useEuiMemoizedStyles(getStyles);
+
+  const { collapsed, setCollapsed } = useCollapsible({
+    // Active categories are always initialized as expanded. The default
+    // (`item.collapsed`) is only used for non-active categories.
+    initialState: () => {
+      if (!collapsible) {
+        return false;
+      }
+      return isActive ? false : item.collapsed;
+    },
+  });
+
+  const { expandedItem, setExpandedItem } = useDocSidebarItemsExpandedState();
+  // Use this instead of `setCollapsed`, because it is also reactive
+  const updateCollapsed = (toCollapsed: boolean = !collapsed) => {
+    setExpandedItem(toCollapsed ? null : index);
+    setCollapsed(toCollapsed);
+  };
+  useAutoExpandActiveCategory({ isActive, collapsed, updateCollapsed });
+  useEffect(() => {
+    if (
+      collapsible &&
+      expandedItem != null &&
+      expandedItem !== index &&
+      autoCollapseCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        className
+      )}
+      css={styles.listItem}
+    >
+      <div
+        className={clsx('menu__list-item-collapsible', {
+          'menu__list-item-collapsible--active': isCurrentPage && !collapsed,
+        })}
+      >
+        <Link
+          className={clsx('menu__link', {
+            'menu__link--sublist': collapsible,
+            'menu__link--active': isCurrentPage && !collapsed && isActive,
+          })}
+          onClick={
+            collapsible
+              ? (e) => {
+                  onItemClick?.(item);
+                  if (href) {
+                    updateCollapsed(false);
+                  } else {
+                    e.preventDefault();
+                    updateCollapsed();
+                  }
+                }
+              : () => {
+                  onItemClick?.(item);
+                }
+          }
+          aria-current={isCurrentPage ? 'page' : undefined}
+          role={collapsible && !href ? 'button' : undefined}
+          aria-expanded={collapsible && !href ? !collapsed : undefined}
+          href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
+          {...props}
+        >
+          {label}
+        </Link>
+        {collapsible && (
+          <CollapseButton
+            collapsed={collapsed}
+            categoryLabel={label}
+            onClick={(e) => {
+              e.preventDefault();
+              updateCollapsed();
+            }}
+            css={styles.button}
+          />
+        )}
+      </div>
+
+      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
+        <DocSidebarItems
+          items={items}
+          tabIndex={collapsed ? -1 : 0}
+          onItemClick={onItemClick}
+          activePath={activePath}
+          level={level + 1}
+        />
+      </Collapsible>
+    </li>
+  );
+}

package/src/theme/DocSidebarItem/Link/index.tsx

@@ -0,0 +1,86 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { JSX } from 'react';
+import clsx from 'clsx';
+import { css } from '@emotion/react';
+import { ThemeClassNames } from '@docusaurus/theme-common';
+import { isActiveSidebarItem } from '@docusaurus/plugin-content-docs/client';
+import Link from '@docusaurus/Link';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import IconExternalLink from '@theme-original/Icon/ExternalLink';
+import type { Props } from '@theme-original/DocSidebarItem/Link';
+import { useEuiMemoizedStyles, UseEuiTheme } from '@elastic/eui';
+
+// converted from css modules to Emotion
+const getStyles = ({ euiTheme }: UseEuiTheme) => ({
+  menuListItem: css`
+    .menu__link {
+      color: ${euiTheme.colors.text};
+      font-size: var(--eui-font-size-s);
+      line-height: var(--eui-line-height-s);
+    }
+
+    .menu__link--active {
+      border-radius: ${euiTheme.border.radius.small};
+      color: ${euiTheme.colors.primary};
+      font-weight: ${euiTheme.font.weight.bold};
+    }
+  `,
+  menuExternalLink: css`
+    align-items: center;
+  `,
+});
+
+export default function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}: Props): JSX.Element {
+  const { href, label, className, autoAddBaseUrl } = item;
+  const isActive = isActiveSidebarItem(item, activePath);
+  const isInternalLink = isInternalUrl(href);
+
+  const styles = useEuiMemoizedStyles(getStyles);
+
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        'menu__list-item',
+        className
+      )}
+      key={label}
+      css={styles.menuListItem}
+    >
+      <Link
+        className={clsx(
+          'menu__link',
+          !isInternalLink && styles.menuExternalLink,
+          {
+            'menu__link--active': isActive,
+          }
+        )}
+        autoAddBaseUrl={autoAddBaseUrl}
+        aria-current={isActive ? 'page' : undefined}
+        to={href}
+        {...(isInternalLink && {
+          onClick: onItemClick ? () => onItemClick(item) : undefined,
+        })}
+        {...props}
+      >
+        {label}
+        {!isInternalLink && <IconExternalLink />}
+      </Link>
+    </li>
+  );
+}

package/src/theme/DocSidebarItem/index.tsx

@@ -0,0 +1,29 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { JSX } from 'react';
+import type { Props } from '@theme-original/DocSidebarItem';
+import DocSidebarItemHtml from '@theme-original/DocSidebarItem/Html';
+
+import DocSidebarItemCategory from './Category';
+import DocSidebarItemLink from './Link';
+
+export default function DocSidebarItem({
+  item,
+  ...props
+}: Props): JSX.Element | null {
+  switch (item.type) {
+    case 'category':
+      return <DocSidebarItemCategory item={item} {...props} />;
+    case 'html':
+      return <DocSidebarItemHtml item={item} {...props} />;
+    case 'link':
+    default:
+      return <DocSidebarItemLink item={item} {...props} />;
+  }
+}

package/src/theme/DocSidebarItems/index.tsx

@@ -0,0 +1,30 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { memo, JSX } from 'react';
+import {
+  DocSidebarItemsExpandedStateProvider,
+  useVisibleSidebarItems,
+} from '@docusaurus/plugin-content-docs/client';
+import type { Props } from '@theme-original/DocSidebarItems';
+
+import DocSidebarItem from '../DocSidebarItem';
+
+function DocSidebarItems({ items, ...props }: Props): JSX.Element {
+  const visibleItems = useVisibleSidebarItems(items, props.activePath);
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {visibleItems.map((item, index) => (
+        <DocSidebarItem key={index} item={item} index={index} {...props} />
+      ))}
+    </DocSidebarItemsExpandedStateProvider>
+  );
+}
+
+// Optimize sidebar at each "level"
+export default memo(DocSidebarItems);

package/src/theme/EditThisPage/index.tsx

@@ -0,0 +1,50 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { JSX } from 'react';
+import { css } from '@emotion/react';
+import Translate from '@docusaurus/Translate';
+import type { Props } from '@theme-original/EditThisPage';
+import {
+  EuiButton,
+  euiButtonColor,
+  useEuiMemoizedStyles,
+  UseEuiTheme,
+} from '@elastic/eui';
+
+const getStyles = (theme: UseEuiTheme) => {
+  const buttonColor = euiButtonColor(theme, 'primary');
+
+  return {
+    editPage: css`
+      // overriding Docusaurus link hover styles to preserve button styles
+      --ifm-link-hover-color: ${buttonColor.color};
+    `,
+  };
+};
+
+export default function EditThisPage({ editUrl, ...rest }: Props): JSX.Element {
+  const styles = useEuiMemoizedStyles(getStyles);
+
+  return (
+    <EuiButton
+      {...rest}
+      href={editUrl}
+      iconType="pencil"
+      color="primary"
+      css={styles.editPage}
+    >
+      <Translate
+        id="theme.common.editThisPage"
+        description="The link label to edit the current page"
+      >
+        Edit this page
+      </Translate>
+    </EuiButton>
+  );
+}