@elastic/eui-docusaurus-theme 2.0.0

package/src/theme/DocBreadcrumbs/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 { type ReactNode, JSX } from 'react';
+import clsx from 'clsx';
+import { css } from '@emotion/react';
+import { ThemeClassNames } from '@docusaurus/theme-common';
+import { useSidebarBreadcrumbs } from '@docusaurus/plugin-content-docs/client';
+import { useHomePageRoute } from '@docusaurus/theme-common/internal';
+import Link from '@docusaurus/Link';
+import { translate } from '@docusaurus/Translate';
+import { EuiIcon, useEuiMemoizedStyles, UseEuiTheme } from '@elastic/eui';
+
+import HomeBreadcrumbItem from './Items/Home';
+import { getItemStyles } from './Items/item.styles';
+
+// converted from css modules to Emotion
+const getStyles = ({ euiTheme }: UseEuiTheme) => ({
+  breadcrumbsContainer: css`
+    --ifm-breadcrumb-size-multiplier: 0.8;
+
+    // align breadcrumb items with content
+    margin-inline-start: -${euiTheme.size.m};
+  `,
+});
+
+// TODO move to design system folder
+function BreadcrumbsItemLink({
+  children,
+  href,
+  isLast,
+}: {
+  children: ReactNode;
+  href: string | undefined;
+  isLast: boolean;
+}): JSX.Element {
+  const className = 'breadcrumbs__link';
+  if (isLast) {
+    return (
+      <span className={className} itemProp="name">
+        {children}
+      </span>
+    );
+  }
+  return href ? (
+    <Link className={className} href={href} itemProp="item">
+      <span itemProp="name">{children}</span>
+    </Link>
+  ) : (
+    // TODO Google search console doesn't like breadcrumb items without href.
+    // The schema doesn't seem to require `id` for each `item`, although Google
+    // insist to infer one, even if it's invalid. Removing `itemProp="item
+    // name"` for now, since I don't know how to properly fix it.
+    // See https://github.com/facebook/docusaurus/issues/7241
+    <span className={className}>{children}</span>
+  );
+}
+
+function BreadcrumbsItem({
+  children,
+  active,
+  index,
+  addMicrodata,
+}: {
+  children: ReactNode;
+  active?: boolean;
+  index: number;
+  addMicrodata: boolean;
+}): JSX.Element {
+  const styles = useEuiMemoizedStyles(getItemStyles);
+
+  return (
+    <li
+      {...(addMicrodata && {
+        itemScope: true,
+        itemProp: 'itemListElement',
+        itemType: 'https://schema.org/ListItem',
+      })}
+      className={clsx('breadcrumbs__item', {
+        'breadcrumbs__item--active': active,
+      })}
+      css={styles.item}
+    >
+      {children}
+      <meta itemProp="position" content={String(index + 1)} />
+      {!active && <EuiIcon type="arrowRight" css={styles.icon} />}
+    </li>
+  );
+}
+
+export default function DocBreadcrumbs(): JSX.Element | null {
+  const breadcrumbs = useSidebarBreadcrumbs();
+  const homePageRoute = useHomePageRoute();
+
+  const styles = useEuiMemoizedStyles(getStyles);
+
+  if (!breadcrumbs) {
+    return null;
+  }
+
+  return (
+    <nav
+      className={clsx(ThemeClassNames.docs.docBreadcrumbs)}
+      aria-label={translate({
+        id: 'theme.docs.breadcrumbs.navAriaLabel',
+        message: 'Breadcrumbs',
+        description: 'The ARIA label for the breadcrumbs',
+      })}
+      css={styles.breadcrumbsContainer}
+    >
+      <ul
+        className="breadcrumbs"
+        itemScope
+        itemType="https://schema.org/BreadcrumbList"
+      >
+        {homePageRoute && <HomeBreadcrumbItem />}
+        {breadcrumbs.map((item, idx) => {
+          const isLast = idx === breadcrumbs.length - 1;
+          const href =
+            item.type === 'category' && item.linkUnlisted
+              ? undefined
+              : item.href;
+          return (
+            <BreadcrumbsItem
+              key={idx}
+              active={isLast}
+              index={idx}
+              addMicrodata={!!href}
+            >
+              <BreadcrumbsItemLink href={href} isLast={isLast}>
+                {item.label}
+              </BreadcrumbsItemLink>
+            </BreadcrumbsItem>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}

package/src/theme/DocItem/Content/index.tsx

@@ -0,0 +1,75 @@
+/*
+ * 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 { useDoc } from '@docusaurus/plugin-content-docs/client';
+import MDXContent from '@theme-original/MDXContent';
+import {
+  EuiHorizontalRule,
+  useEuiMemoizedStyles,
+  UseEuiTheme,
+} from '@elastic/eui';
+import { Props } from '@theme-original/DocItem/Content';
+
+import Heading from '../../MDXComponents/Heading';
+
+/**
+ Title can be declared inside md content or declared through
+ front matter and added manually. To make both cases consistent,
+ the added title is added under the same div.markdown block
+ See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+
+ We render a "synthetic title" if:
+ - user doesn't ask to hide it with front matter
+ - the markdown content does not already contain a top-level h1 heading
+*/
+function useSyntheticTitle(): string | null {
+  const { metadata, frontMatter, contentTitle } = useDoc();
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === 'undefined';
+  if (!shouldRender) {
+    return null;
+  }
+  return metadata.title;
+}
+
+const getContentStyles = ({ euiTheme }: UseEuiTheme) => {
+  return {
+    header: css`
+      // required specificity to override docusaurus styles
+      & > h1.euiTitle {
+        --ifm-h1-font-size: var(--eui-font-size-xxl);
+        --ifm-h1-vertical-rhythm-bottom: 1.2;
+
+        line-height: 2.8rem;
+      }
+    `,
+  };
+};
+
+export default function DocItemContent({ children }: Props): JSX.Element {
+  const syntheticTitle = useSyntheticTitle();
+  const styles = useEuiMemoizedStyles(getContentStyles);
+
+  return (
+    <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
+      {syntheticTitle && (
+        <>
+          <header css={styles.header}>
+            <Heading as="h1">{syntheticTitle}</Heading>
+          </header>
+          <EuiHorizontalRule />
+        </>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

package/src/theme/DocItem/Footer/index.tsx

@@ -0,0 +1,59 @@
+/*
+ * 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 { ThemeClassNames } from '@docusaurus/theme-common';
+import { useDoc } from '@docusaurus/plugin-content-docs/client';
+import TagsListInline from '@theme-original/TagsListInline';
+
+import EditMetaRow from '@theme-original/EditMetaRow';
+
+export default function DocItemFooter(): JSX.Element | null {
+  const { metadata } = useDoc();
+  const { editUrl, lastUpdatedAt, lastUpdatedBy, tags } = metadata;
+
+  const canDisplayTagsRow = tags.length > 0;
+  const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy);
+
+  const canDisplayFooter = canDisplayTagsRow || canDisplayEditMetaRow;
+
+  if (!canDisplayFooter) {
+    return null;
+  }
+
+  return (
+    <footer
+      className={clsx(ThemeClassNames.docs.docFooter, 'docusaurus-mt-lg')}
+    >
+      {canDisplayTagsRow && (
+        <div
+          className={clsx(
+            'row margin-top--sm',
+            ThemeClassNames.docs.docFooterTagsRow
+          )}
+        >
+          <div className="col">
+            <TagsListInline tags={tags} />
+          </div>
+        </div>
+      )}
+      {canDisplayEditMetaRow && (
+        <EditMetaRow
+          className={clsx(
+            'margin-top--sm',
+            ThemeClassNames.docs.docFooterEditMetaRow
+          )}
+          editUrl={editUrl}
+          lastUpdatedAt={lastUpdatedAt}
+          lastUpdatedBy={lastUpdatedBy}
+        />
+      )}
+    </footer>
+  );
+}

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

@@ -0,0 +1,112 @@
+/*
+ * 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 { EuiHorizontalRule } from '@elastic/eui';
+import { css } from '@emotion/react';
+import { useWindowSize } from '@docusaurus/theme-common';
+import { useDoc } from '@docusaurus/plugin-content-docs/client';
+import DocItemPaginator from '@theme-original/DocItem/Paginator';
+import ContentVisibility from '@theme-original/ContentVisibility';
+import DocVersionBanner from '@theme-original/DocVersionBanner';
+import DocVersionBadge from '@theme-original/DocVersionBadge';
+import * as Props from '@theme-original/DocItem/Layout';
+
+import DocBreadcrumbs from '../../DocBreadcrumbs';
+import DocItemTOCMobile from '../TOC/Mobile';
+import DocItemTOCDesktop from '../TOC/Desktop';
+import DocItemContent from '../Content';
+import DocItemFooter from '../Footer';
+
+// At 1280px there's enough space to show the TOC,
+// until then we show the mobile/collapsible TOC
+const BREAKPOINT_TOC = 1280;
+
+// converted from css modules to emotion
+const styles = {
+  docItemContainer: css`
+    & header + *,
+    & article > *:first-child {
+      margin-top: 0;
+    }
+  `,
+  docItemRow: css`
+    justify-content: center;
+  `,
+  docItemCol: css`
+    @media (min-width: 997px) {
+      font-size: 100%;
+      max-width: 94ch;
+      /* Ensure TOC won't wrap */
+      overflow-x: auto;
+    }
+  `,
+  docItemTOCDesktopContainter: css`
+    display: none;
+
+    @media (min-width: ${BREAKPOINT_TOC}px) {
+      display: block;
+    }
+  `,
+  docItemTOCMobileContainter: css`
+    @media (min-width: ${BREAKPOINT_TOC}px) {
+      display: none;
+    }
+  `,
+};
+
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const { frontMatter, toc } = useDoc();
+  const windowSize = useWindowSize();
+
+  const hidden = frontMatter.hide_table_of_contents ?? false;
+  const canRender = !hidden && toc.length > 0;
+
+  // Hide/show for TOC elements is handled by media queries
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+  const desktop = canRender ? <DocItemTOCDesktop /> : undefined;
+
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({ children }: typeof Props): JSX.Element {
+  const docTOC = useDocTOC();
+  const { metadata } = useDoc();
+
+  return (
+    <div className="row" css={styles.docItemRow}>
+      <div className="col" css={styles.docItemCol}>
+        <ContentVisibility metadata={metadata} />
+        <DocVersionBanner />
+        <div css={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            <div css={styles.docItemTOCMobileContainter}>{docTOC.mobile}</div>
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <EuiHorizontalRule margin="xl" />
+          <DocItemPaginator />
+        </div>
+      </div>
+      {docTOC.desktop && (
+        <div className="col col--3" css={styles.docItemTOCDesktopContainter}>
+          {docTOC.desktop}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/theme/DocItem/Metadata/index.tsx

@@ -0,0 +1,23 @@
+/*
+ * 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 { PageMetadata } from '@docusaurus/theme-common';
+import { useDoc } from '@docusaurus/plugin-content-docs/client';
+
+export default function DocItemMetadata(): JSX.Element {
+  const { metadata, frontMatter, assets } = useDoc();
+  return (
+    <PageMetadata
+      title={metadata.title}
+      description={metadata.description}
+      keywords={frontMatter.keywords}
+      image={assets.image ?? frontMatter.image}
+    />
+  );
+}

package/src/theme/DocItem/Paginator/index.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 { JSX } from 'react';
+import { useDoc } from '@docusaurus/plugin-content-docs/client';
+import DocPaginator from '@theme-original/DocPaginator';
+
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+export default function DocItemPaginator(): JSX.Element {
+  const { metadata } = useDoc();
+  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+}

package/src/theme/DocItem/TOC/Desktop/index.tsx

@@ -0,0 +1,24 @@
+/*
+ * 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 { ThemeClassNames } from '@docusaurus/theme-common';
+import { useDoc } from '@docusaurus/plugin-content-docs/client';
+import TOC from '@theme-original/TOC';
+
+export default function DocItemTOCDesktop(): JSX.Element {
+  const { toc, frontMatter } = useDoc();
+  return (
+    <TOC
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={ThemeClassNames.docs.docTocDesktop}
+    />
+  );
+}

package/src/theme/DocItem/TOC/Mobile/index.tsx

@@ -0,0 +1,35 @@
+/*
+ * 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 { ThemeClassNames } from '@docusaurus/theme-common';
+import { useDoc } from '@docusaurus/plugin-content-docs/client';
+import TOCCollapsible from '@theme-original/TOCCollapsible';
+
+// converted from css modules to emotion
+const tocStyles = {
+  tocMobile: css`
+    @media print {
+      display: none;
+    }
+  `,
+};
+
+export default function DocItemTOCMobile(): JSX.Element {
+  const { toc, frontMatter } = useDoc();
+  return (
+    <TOCCollapsible
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={ThemeClassNames.docs.docTocMobile}
+      css={tocStyles.tocMobile}
+    />
+  );
+}

package/src/theme/DocItem/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 { JSX } from 'react';
+import { HtmlClassNameProvider } from '@docusaurus/theme-common';
+import { DocProvider } from '@docusaurus/plugin-content-docs/client';
+import type { Props } from '@theme/DocItem';
+
+import DocItemMetadata from './Metadata';
+import DocItemLayout from './Layout';
+
+export default function DocItem(props: Props): JSX.Element {
+  const docHtmlClassName = `docs-doc-id-${props.content.metadata.id}`;
+  const MDXComponent = props.content;
+  return (
+    <DocProvider content={props.content}>
+      <HtmlClassNameProvider className={docHtmlClassName}>
+        <DocItemMetadata />
+        <DocItemLayout>
+          <MDXComponent />
+        </DocItemLayout>
+      </HtmlClassNameProvider>
+    </DocProvider>
+  );
+}

package/src/theme/DocPaginator/index.tsx

@@ -0,0 +1,64 @@
+/*
+ * 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, { translate } from '@docusaurus/Translate';
+import PaginatorNavLink from '@theme-original/PaginatorNavLink';
+import type { Props } from '@theme-original/DocPaginator';
+
+const styles = {
+  pagination: css`
+    // docusaurus reset, we add spacing via the
+    // horizontal rule in Layout instead
+    margin-top: 0;
+  `,
+};
+
+export default function DocPaginator(props: Props): JSX.Element {
+  const { previous, next } = props;
+  return (
+    <nav
+      className="pagination-nav docusaurus-mt-lg"
+      css={styles.pagination}
+      aria-label={translate({
+        id: 'theme.docs.paginator.navAriaLabel',
+        message: 'Docs pages',
+        description: 'The ARIA label for the docs pagination',
+      })}
+    >
+      {previous && (
+        <PaginatorNavLink
+          {...previous}
+          subLabel={
+            <Translate
+              id="theme.docs.paginator.previous"
+              description="The label used to navigate to the previous doc"
+            >
+              Previous
+            </Translate>
+          }
+        />
+      )}
+      {next && (
+        <PaginatorNavLink
+          {...next}
+          subLabel={
+            <Translate
+              id="theme.docs.paginator.next"
+              description="The label used to navigate to the next doc"
+            >
+              Next
+            </Translate>
+          }
+          isNext
+        />
+      )}
+    </nav>
+  );
+}

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

@@ -0,0 +1,61 @@
+/*
+ * 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 { useDocsSidebar } from '@docusaurus/plugin-content-docs/client';
+import type { Props } from '@theme-original/DocRoot/Layout/Main';
+
+// converted from css modules to Emotion
+const styles = {
+  docMainContainer: css`
+    display: flex;
+    width: 100%;
+
+    @media (min-width: 997px) {
+      flex-grow: 1;
+      max-width: calc(100% - var(--doc-sidebar-width));
+    }
+  `,
+  docMainContainerEnhanced: css`
+    @media (min-width: 997px) {
+      max-width: calc(100% - var(--doc-sidebar-hidden-width));
+    }
+  `,
+  docItemWrapperEnhanced: css`
+    @media (min-width: 997px) {
+      max-width: calc(
+        var(--ifm-container-width) + var(--doc-sidebar-width)
+      ) !important;
+    }
+  `,
+};
+
+export default function DocRootLayoutMain({
+  hiddenSidebarContainer,
+  children,
+}: Props): JSX.Element {
+  const sidebar = useDocsSidebar();
+  return (
+    <main
+      className={clsx(styles.docMainContainer)}
+      css={[
+        styles.docMainContainer,
+        (hiddenSidebarContainer || !sidebar) && styles.docMainContainerEnhanced,
+      ]}
+    >
+      <div
+        className="container padding-top--md padding-bottom--lg"
+        css={[hiddenSidebarContainer && styles.docItemWrapperEnhanced]}
+      >
+        {children}
+      </div>
+    </main>
+  );
+}