@elastic/eui-docusaurus-theme 2.0.0

package/src/components/theme_context/index.tsx

@@ -0,0 +1,156 @@
+/*
+ * 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 {
+  createContext,
+  FunctionComponent,
+  PropsWithChildren,
+  useContext,
+  useEffect,
+  useState,
+} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import createCache from '@emotion/cache';
+import { CacheProvider } from '@emotion/react';
+import { EuiProvider, EuiThemeColorMode } from '@elastic/eui';
+import { EuiThemeBorealis } from '@elastic/eui-theme-borealis';
+import { type EUI_THEME } from '@elastic/eui-theme-common';
+
+import { EuiThemeOverrides } from './theme_overrides';
+
+export const AVAILABLE_THEMES: EUI_THEME[] = [
+  {
+    text: 'Borealis',
+    value: EuiThemeBorealis.key,
+    provider: EuiThemeBorealis,
+  },
+];
+
+const EUI_COLOR_MODES = ['light', 'dark'] as const;
+
+/**
+ * Get the initial color mode: localStorage | light
+ */
+const getInitialColorMode = (): EuiThemeColorMode => {
+  const storedColorMode = localStorage.getItem('colorMode');
+
+  if (storedColorMode === 'light' || storedColorMode === 'dark') {
+    return storedColorMode;
+  } else {
+    return defaultState.colorMode;
+  }
+};
+
+export interface AppThemeContextData {
+  colorMode: EuiThemeColorMode;
+  highContrastMode: boolean | undefined;
+  theme: EUI_THEME;
+  changeColorMode: (colorMode: EuiThemeColorMode) => void;
+  changeHighContrastMode: (highContrastMode: boolean) => void;
+  changeTheme: (themeValue: string) => void;
+}
+
+const defaultState: AppThemeContextData = {
+  colorMode: EUI_COLOR_MODES[0],
+  highContrastMode: undefined,
+  theme: AVAILABLE_THEMES[0] as EUI_THEME,
+  changeColorMode: () => {},
+  changeHighContrastMode: () => {},
+  changeTheme: () => {},
+};
+
+/**
+ * Creating a cache and passing it to EuiProvider ensures that injected
+ * Emotion style tags dev mode are in an expected order (global css before component css).
+ * This only applies for @emotion/react css styles, @emotion/css styles are separate.
+ */
+const cssCache = createCache({
+  key: 'website-css',
+  prepend: false,
+});
+
+export const cssGlobalCache = createCache({
+  key: 'website-css',
+  prepend: true,
+});
+
+export const AppThemeContext = createContext<AppThemeContextData>(defaultState);
+
+export const useAppTheme: () => AppThemeContextData = () => {
+  return useContext(AppThemeContext);
+};
+
+export const AppThemeProvider: FunctionComponent<PropsWithChildren> = ({
+  children,
+}) => {
+  const isBrowser = useIsBrowser();
+
+  const [colorMode, setColorMode] = useState<EuiThemeColorMode>(() => {
+    if (isBrowser) return getInitialColorMode();
+    return defaultState.colorMode;
+  });
+
+  const [highContrastMode, setHighContrastMode] = useState<boolean | undefined>(
+    false
+  );
+
+  const getHighContrastModeSetting = () => {
+    return localStorage?.getItem('highContrastMode')
+      ? localStorage?.getItem('highContrastMode') === 'true'
+      : defaultState.highContrastMode;
+  };
+
+  useEffect(() => {
+    if (isBrowser) {
+      setHighContrastMode(getHighContrastModeSetting());
+    }
+  }, [isBrowser]);
+
+  const [theme, setTheme] = useState<EUI_THEME>(defaultState.theme);
+
+  const handleChangeTheme = (themeValue: string) => {
+    const matchedTheme = AVAILABLE_THEMES.find((t) => t.value === themeValue);
+    setTheme((currentTheme) => matchedTheme ?? currentTheme);
+  };
+
+  const handleChangeHighContrastMode = (highContrastMode: boolean) => {
+    localStorage.setItem('highContrastMode', highContrastMode.toString());
+    setHighContrastMode(highContrastMode);
+  };
+
+  const handleColorMode = (colorMode: EuiThemeColorMode) => {
+    localStorage.setItem('colorMode', colorMode);
+    setColorMode(colorMode);
+  };
+
+  return (
+    <AppThemeContext.Provider
+      value={{
+        colorMode,
+        highContrastMode,
+        theme,
+        changeColorMode: handleColorMode,
+        changeHighContrastMode: handleChangeHighContrastMode,
+        changeTheme: handleChangeTheme,
+      }}
+    >
+      <EuiProvider
+        modify={EuiThemeOverrides}
+        colorMode={colorMode}
+        theme={theme.provider}
+        highContrastMode={highContrastMode}
+        cache={{
+          default: cssCache,
+          global: cssGlobalCache,
+        }}
+      >
+        <CacheProvider value={cssCache}>{children}</CacheProvider>
+      </EuiProvider>
+    </AppThemeContext.Provider>
+  );
+};

package/src/components/theme_context/theme_overrides.ts

@@ -0,0 +1,15 @@
+/*
+ * 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 { EuiThemeModifications } from '@elastic/eui';
+
+export const EuiThemeOverrides: EuiThemeModifications = {
+  font: {
+    lineHeightMultiplier: 1.75,
+  },
+};

package/src/components/version_switcher/index.tsx

@@ -0,0 +1,144 @@
+/*
+ * 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 { ComponentProps, useState } from 'react';
+import { css } from '@emotion/react';
+import { FixedSizeList } from 'react-window';
+import {
+  EuiButtonEmpty,
+  euiFocusRing,
+  EuiListGroupItem,
+  EuiPopover,
+  useEuiMemoizedStyles,
+  UseEuiTheme,
+} from '@elastic/eui';
+
+const getStyles = (euiThemeContext: UseEuiTheme) => {
+  const { euiTheme } = euiThemeContext;
+
+  return {
+    button: css`
+      font-weight: ${euiTheme.font.weight.bold};
+      color: ${euiTheme.colors.primary};
+    `,
+    listItem: css`
+      .euiListGroupItem__button:focus-visible {
+        // overriding the global "outset" style to ensure the focus style is not cut off
+        ${euiFocusRing(euiThemeContext, 'inset', {
+          color: euiTheme.colors.primary,
+        })};
+      }
+    `,
+  };
+};
+
+/**
+ * Addresses NVDA pronunciation issue
+ */
+const pronounceVersion = (version: string) => {
+  return `version ${version.replaceAll('.', ' point ')}`;
+};
+
+export type VersionSwitcherProps = {
+  /**
+   * Aria label for the version switcher popover
+   */
+  ariaLabel: string;
+  /*
+   * The current version of the documentation
+   */
+  currentVersion: string;
+  /**
+   * Extra action to be displayed in the version switcher
+   */
+  extraAction?: (
+    version?: string
+  ) => ComponentProps<typeof EuiListGroupItem>['extraAction'];
+  /**
+   * URL to the previous version of the documentation
+   * E.g. https://eui.elastic.co
+   */
+  previousVersionUrl?: string;
+  /**
+   * List of available versions to switch to
+   */
+  versions: string[];
+};
+
+export const VersionSwitcher = ({
+  ariaLabel,
+  currentVersion,
+  extraAction,
+  previousVersionUrl,
+  versions,
+}: VersionSwitcherProps) => {
+  const [isPopoverOpen, setPopoverOpen] = useState(false);
+  const styles = useEuiMemoizedStyles(getStyles);
+
+  if (!versions) return null;
+
+  const button = (
+    <EuiButtonEmpty
+      size="s"
+      color="text"
+      iconType="arrowDown"
+      iconSide="right"
+      css={styles.button}
+      onClick={() => setPopoverOpen((isOpen) => !isOpen)}
+      aria-label={`${pronounceVersion(
+        currentVersion
+      )}. Click to switch versions`}
+    >
+      v{currentVersion}
+    </EuiButtonEmpty>
+  );
+
+  return (
+    <EuiPopover
+      isOpen={isPopoverOpen}
+      closePopover={() => setPopoverOpen(false)}
+      button={button}
+      repositionOnScroll
+      panelPaddingSize="xs"
+      aria-label={ariaLabel}
+    >
+      <FixedSizeList
+        className="eui-yScroll"
+        itemCount={versions.length}
+        itemSize={24}
+        height={200}
+        width={120}
+        innerElementType="ul"
+      >
+        {({ index, style }) => {
+          const version = versions[index];
+          const isCurrentVersion = version === currentVersion;
+          const screenReaderVersion = pronounceVersion(version!);
+
+          const url = isCurrentVersion
+            ? '/'
+            : `${previousVersionUrl}/v${version}/`;
+
+          return (
+            <EuiListGroupItem
+              css={styles.listItem}
+              style={style}
+              size="xs"
+              label={`v${version}`}
+              aria-label={screenReaderVersion}
+              href={url}
+              isActive={isCurrentVersion}
+              color={isCurrentVersion ? 'primary' : 'text'}
+              extraAction={extraAction?.(version)}
+            />
+          );
+        }}
+      </FixedSizeList>
+    </EuiPopover>
+  );
+};

package/src/index.ts

@@ -0,0 +1,21 @@
+/*
+ * 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 { Plugin } from '@docusaurus/types';
+
+export default function euiDocusaurusTheme(): Plugin<void> {
+  return {
+    name: 'eui-docusaurus-theme',
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+  };
+}

package/src/theme/Admonition/Types.tsx

@@ -0,0 +1,85 @@
+/*
+ * 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 { css } from '@emotion/react';
+import { EuiCallOut, EuiText } from '@elastic/eui';
+import type { Props } from '@theme-original/Admonition';
+import type AdmonitionTypes from '@theme-original/Admonition/Types';
+
+type CalloutVariant =
+  | 'note'
+  | 'tip'
+  | 'info'
+  | 'accessibility'
+  | 'warning'
+  | 'danger'
+  | 'secondary'
+  | 'important'
+  | 'success'
+  | 'caution';
+type VariantColor = 'accent' | 'primary' | 'success' | 'warning' | 'danger';
+
+const VARIANT_TO_PROPS_MAP: Record<
+  CalloutVariant,
+  { iconType?: string; color?: VariantColor }
+> = {
+  note: { iconType: 'paperClip', color: 'accent' },
+  tip: { iconType: 'faceHappy', color: 'success' },
+  info: { iconType: 'info', color: 'primary' },
+  accessibility: { iconType: 'accessibility', color: 'primary' },
+  warning: { iconType: 'alert', color: 'warning' },
+  danger: { iconType: 'error', color: 'danger' },
+  // Undocumented legacy admonition type aliases
+  secondary: {},
+  important: {},
+  success: {},
+  caution: {},
+};
+
+// MDXComponents/Paragraph wraps <p> in <EuiText>,
+// this is a workaround to keep styles from <EuiText> in the admonition
+const nestedParagraphStyleReset = css`
+  p.euiText {
+    font-size: inherit;
+    line-height: inherit;
+  }
+`;
+
+const Callout = ({ title, type, children }: Props) => {
+  const variantProps = VARIANT_TO_PROPS_MAP[type as CalloutVariant];
+
+  return (
+    <EuiCallOut
+      title={title}
+      iconType="info"
+      color="primary"
+      {...variantProps}
+      css={css`
+        margin-block: var(--eui-theme-content-vertical-spacing);
+        ${nestedParagraphStyleReset}
+      `}
+    >
+      {children}
+    </EuiCallOut>
+  );
+};
+
+const admonitionTypes: typeof AdmonitionTypes = {
+  note: Callout,
+  tip: Callout,
+  info: Callout,
+  accessibility: Callout,
+  warning: Callout,
+  danger: Callout,
+  secondary: Callout,
+  important: Callout,
+  success: Callout,
+  caution: Callout,
+};
+
+export default admonitionTypes;

package/src/theme/CodeBlock/index.tsx

@@ -0,0 +1,57 @@
+/*
+ * 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, { isValidElement, type ReactNode, JSX } from 'react';
+import { css } from '@emotion/react';
+import { EuiCodeBlock } from '@elastic/eui';
+import type { Props } from '@theme/CodeBlock';
+
+import { Demo } from '../../components/demo';
+
+/**
+ * Best attempt to make the children a plain string so it is copyable. If there
+ * are react elements, we will not be able to copy the content, and it will
+ * return `children` as-is; otherwise, it concatenates the string children
+ * together.
+ */
+function maybeStringifyChildren(children: ReactNode): ReactNode {
+  if (React.Children.toArray(children).some((el) => isValidElement(el))) {
+    return children;
+  }
+  // The children is now guaranteed to be one/more plain strings
+  return Array.isArray(children) ? children.join('') : (children as string);
+}
+
+export default function CodeBlock({
+  children: rawChildren,
+  metastring,
+  className,
+  ...props
+}: Props): JSX.Element {
+  const children = maybeStringifyChildren(rawChildren);
+  const language = className?.replace('language-', '') || undefined;
+
+  if (metastring?.startsWith('interactive')) {
+    return <Demo {...props}>{children}</Demo>;
+  }
+
+  return (
+    <EuiCodeBlock
+      {...props}
+      fontSize="m"
+      overflowHeight={450}
+      language={language}
+      isCopyable
+      css={css`
+        word-break: break-word;
+      `}
+    >
+      {children}
+    </EuiCodeBlock>
+  );
+}

package/src/theme/ColorModeToggle/index.tsx

@@ -0,0 +1,93 @@
+/*
+ * 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, { useCallback, useContext, useEffect, JSX } from 'react';
+import type ColorModeToggleType from '@theme-init/ColorModeToggle';
+import type { Props } from '@theme-original/ColorModeToggle';
+import type { WrapperProps } from '@docusaurus/types';
+import { EuiThemeColorMode } from '@elastic/eui';
+import { translate } from '@docusaurus/Translate';
+
+import { NavbarItem } from '../../components/navbar_item';
+import { AppThemeContext } from '../../components/theme_context';
+
+type WrappedProps = WrapperProps<typeof ColorModeToggleType>;
+
+/**
+ * Additional wrapper to connect Docusaurus color mode with EUI theme
+ */
+function ColorModeToggle({
+  value,
+  onChange,
+  ...rest
+}: WrappedProps): JSX.Element {
+  const { colorMode, changeColorMode } = useContext(AppThemeContext);
+
+  useEffect(() => {
+    changeColorMode(value);
+  }, [value, colorMode, changeColorMode]);
+
+  const handleOnChange = (colorMode: EuiThemeColorMode) => {
+    changeColorMode(colorMode);
+    onChange?.(colorMode);
+  };
+
+  return (
+    <OriginalColorModeToggle
+      value={colorMode}
+      onChange={handleOnChange}
+      {...rest}
+    />
+  );
+}
+
+function OriginalColorModeToggle({
+  className,
+  value,
+  onChange,
+}: Props): JSX.Element {
+  const isDarkMode = value === 'dark';
+
+  const title = translate(
+    {
+      message: 'Switch between dark and light mode (currently {mode})',
+      id: 'theme.colorToggle.ariaLabel',
+      description: 'The ARIA label for the navbar color mode toggle',
+    },
+    {
+      mode:
+        value === 'dark'
+          ? translate({
+              message: 'dark mode',
+              id: 'theme.colorToggle.ariaLabel.mode.dark',
+              description: 'The name for the dark color mode',
+            })
+          : translate({
+              message: 'light mode',
+              id: 'theme.colorToggle.ariaLabel.mode.light',
+              description: 'The name for the light color mode',
+            }),
+    }
+  );
+
+  const handleOnChange = useCallback(() => {
+    onChange(value === 'dark' ? 'light' : 'dark');
+  }, [value, onChange]);
+
+  return (
+    <NavbarItem
+      className={className}
+      title={title}
+      icon={isDarkMode ? 'sun' : 'moon'}
+      isMenuItem={false}
+      onClick={handleOnChange}
+    />
+  );
+}
+
+export default React.memo(ColorModeToggle);

package/src/theme/Demo/actions.tsx

@@ -0,0 +1,20 @@
+/*
+ * 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 { ComponentType } from 'react';
+
+import { DemoSourceMeta } from '../../components/demo/demo';
+
+export type ActionComponentProps = {
+  activeSource: DemoSourceMeta | null;
+  sources: DemoSourceMeta[];
+};
+
+export type ActionComponent = ComponentType<ActionComponentProps>;
+
+export const extraActions: ActionComponent[] = [];

package/src/theme/Demo/default_scope.ts

@@ -0,0 +1,19 @@
+/*
+ * 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.
+ */
+
+/**
+ * A custom client-side require() alternative to inform users it's not available
+ * in our demo environment
+ */
+const clientSideRequire = () => {
+  throw new Error('require() is not accessible in the interactive demo environment! All EUI and React exports are available in the global scope for you to use without the need to import them.');
+}
+
+export const demoDefaultScope = {
+  require: clientSideRequire,
+};

package/src/theme/DocBreadcrumbs/Items/Home/index.tsx

@@ -0,0 +1,38 @@
+/*
+ * 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 Link from '@docusaurus/Link';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import { translate } from '@docusaurus/Translate';
+import { EuiIcon, useEuiMemoizedStyles } from '@elastic/eui';
+
+import { getItemStyles } from '../item.styles';
+
+export default function HomeBreadcrumbItem(): JSX.Element {
+  const homeHref = useBaseUrl('/');
+
+  const styles = useEuiMemoizedStyles(getItemStyles);
+
+  return (
+    <li className="breadcrumbs__item" css={styles.item}>
+      <Link
+        aria-label={translate({
+          id: 'theme.docs.breadcrumbs.home',
+          message: 'Home page',
+          description: 'The ARIA label for the home page in the breadcrumbs',
+        })}
+        className="breadcrumbs__link"
+        href={homeHref}
+      >
+        EUI
+      </Link>
+      <EuiIcon type="arrowRight" size="s" css={styles.icon} />
+    </li>
+  );
+}

package/src/theme/DocBreadcrumbs/Items/item.styles.ts

@@ -0,0 +1,43 @@
+/*
+ * 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 { css } from '@emotion/react';
+import { UseEuiTheme } from '@elastic/eui';
+
+export const getItemStyles = ({ euiTheme }: UseEuiTheme) => ({
+  item: css`
+    --ifm-breadcrumb-item-background: transparent;
+    --ifm-breadcrumb-item-background-active: transparent;
+
+    // overwrite global styles
+    &.breadcrumbs__item:not(:last-child):after {
+      content: none;
+    }
+
+    .breadcrumbs__link {
+      padding: 0 ${euiTheme.size.m};
+      font-size: var(--eui-font-size-xs);
+      line-height: var(--eui-line-height-m);
+    }
+
+    a.breadcrumbs__link {
+      color: ${euiTheme.colors.link};
+      font-weight: ${euiTheme.font.weight.bold};
+      text-decoration: underline;
+    }
+
+    &.breadcrumbs__item--active .breadcrumbs__link {
+      color: ${euiTheme.colors.text};
+    }
+  `,
+  icon: css`
+    block-size: ${euiTheme.size.s};
+    inline-size: ${euiTheme.size.s};
+    fill: ${euiTheme.colors.text};
+  `,
+});