@elastic/eui-docusaurus-theme 2.0.0

package/src/components/high_contrast_mode_toggle/index.tsx

@@ -0,0 +1,28 @@
+import { useContext } from 'react';
+import { useEuiTheme } from '@elastic/eui';
+
+import { NavbarItem } from '../navbar_item';
+import { AppThemeContext } from '../theme_context';
+
+export const HighContrastModeToggle = () => {
+  const euiThemeContext = useEuiTheme();
+
+  const appContext = useContext(AppThemeContext);
+  const { changeHighContrastMode } = appContext;
+
+  const isForcedContrastMode = euiThemeContext.highContrastMode === 'forced';
+  const _highContrastMode =
+    appContext.highContrastMode && !isForcedContrastMode
+      ? appContext.highContrastMode
+      : euiThemeContext.highContrastMode;
+
+  return (
+    <NavbarItem
+      title={'Toggle high contrast mode'}
+      icon="contrast"
+      isMenuItem={false}
+      isSelected={!!_highContrastMode}
+      onClick={() => changeHighContrastMode(!_highContrastMode)}
+    />
+  );
+};

package/src/components/icon/index.ts

@@ -0,0 +1,11 @@
+/*
+ * 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 { EuiIcon } from '@elastic/eui';
+
+export const Icon = EuiIcon;

package/src/components/index.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.
+ */
+
+export { AppThemeContext, useAppTheme } from './theme_context';
+export { Badge } from './badge';
+export { FigmaEmbed } from './figma_embed';
+export { Guideline, GuidelineText } from './guideline';
+export { Icon } from './icon';
+export { PropTable } from './prop_table';
+export { createDemo, Demo, DemoSource, type DemoProps } from './demo';

package/src/components/navbar_item/index.tsx

@@ -0,0 +1,164 @@
+/*
+ * 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 { useContext } from 'react';
+import { css } from '@emotion/react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {
+  CommonProps,
+  EuiIcon,
+  ExclusiveUnion,
+  IconType,
+  mathWithUnits,
+  PropsForAnchor,
+  PropsForButton,
+  useEuiMemoizedStyles,
+  UseEuiTheme,
+} from '@elastic/eui';
+
+import { AppThemeContext } from '../theme_context';
+
+type SharedProps = {
+  icon: IconType;
+  showLabel?: boolean;
+  isMenuItem?: boolean;
+  isSelected?: boolean;
+} & CommonProps;
+
+type Props = ExclusiveUnion<
+  PropsForAnchor<SharedProps>,
+  PropsForButton<SharedProps>
+>;
+
+// converted from css modules to Emotion
+export const getStyles = ({ euiTheme }: UseEuiTheme) => ({
+  item: css`
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+
+    -webkit-tap-highlight-color: transparent;
+    transition: background var(--ifm-transition-fast);
+
+    &:hover {
+      background-color: ${euiTheme.components.buttons.backgroundTextHover};
+      color: currentColor;
+    }
+  `,
+  navItem: css`
+    justify-content: center;
+    width: ${euiTheme.size.xl};
+    height: ${euiTheme.size.xl};
+    border-radius: 50%;
+  `,
+  menuItem: css`
+    justify-content: flex-start;
+    gap: ${euiTheme.size.s};
+
+    @media (min-width: 997px) {
+      justify-content: center;
+      width: ${euiTheme.size.xl};
+      height: ${euiTheme.size.xl};
+      border-radius: 50%;
+    }
+  `,
+  darkMode: css`
+    &:hover {
+      color: currentColor;
+    }
+  `,
+  disabled: css`
+    cursor: not-allowed;
+  `,
+  selected: css`
+    background-color: ${euiTheme.colors.backgroundFilledText};
+    color: ${euiTheme.colors.textInverse};
+  `,
+  title: css`
+    @media (min-width: 997px) {
+      display: none;
+    }
+  `,
+});
+
+// using a type guard to ensure proper typing from ExclusiveUnion
+const isAnchorClick = (
+  onClick: Props['onClick'],
+  href: Props['href']
+): onClick is PropsForAnchor<SharedProps>['onClick'] => href != null;
+
+export const NavbarItem = (props: Props) => {
+  const {
+    className,
+    title,
+    icon,
+    onClick,
+    href,
+    target,
+    showLabel,
+    isMenuItem = true,
+    isSelected,
+    css,
+  } = props;
+
+  const isBrowser = useIsBrowser();
+  const { colorMode } = useContext(AppThemeContext);
+
+  const isDarkMode = colorMode === 'dark';
+
+  const styles = useEuiMemoizedStyles(getStyles);
+  const cssStyles = [
+    styles.item,
+    isMenuItem ? styles.menuItem : styles.navItem,
+    !isBrowser && styles.disabled,
+    isSelected && styles.selected,
+    isDarkMode && styles.darkMode,
+  ];
+
+  const content = showLabel ? (
+    <>
+      <EuiIcon type={icon} />
+      <span css={styles.title}>{title}</span>
+    </>
+  ) : (
+    <EuiIcon type={icon} />
+  );
+
+  if (isAnchorClick(onClick, href)) {
+    return (
+      <a
+        href={href}
+        target={target ?? '_blank'}
+        title={title}
+        className={className}
+        css={cssStyles}
+        onClick={onClick}
+        aria-label={title}
+        aria-live="polite"
+      >
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      disabled={!isBrowser}
+      className={className}
+      css={cssStyles}
+      onClick={onClick}
+      title={title}
+      aria-label={title}
+      aria-live="polite"
+      aria-pressed={isSelected != null ? isSelected : undefined}
+    >
+      {content}
+    </button>
+  );
+};

package/src/components/prop_table/definition_types.ts

@@ -0,0 +1,53 @@
+/*
+ * 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.
+ */
+
+/**
+ * Represents a processed component prop with its metadata
+ */
+export type ProcessedComponentProp = {
+  /** Name of the prop */
+  name: string;
+  /** Description of the prop */
+  description: string;
+  /** Whether the prop is required */
+  isRequired?: boolean;
+  /** Type information for the prop */
+  type?: {
+    name: string;
+    raw?: string;
+    [key: string]: any; // Allow for additional type metadata
+  };
+  /** Default value of the prop */
+  defaultValue?: string;
+  /** Allow additional properties that might be needed in the future */
+  [key: string]: any;
+};
+
+/**
+ * Represents a type extension with display name and potentially other information
+ */
+export type ExtendedType = {
+  /** Display name of the type being extended */
+  displayName: string;
+  /** Any additional metadata about the extended type */
+  [key: string]: any;
+};
+
+/**
+ * Represents a processed component with its metadata
+ */
+export type ProcessedComponent = {
+  /** Display name of the component */
+  displayName: string;
+  /** Props of the component as a record of prop name to prop details */
+  props: Record<string, ProcessedComponentProp>;
+  /** Types that this component extends */
+  extends: ExtendedType[];
+  /** Allow additional properties that might be needed in the future */
+  [key: string]: any;
+};

package/src/components/prop_table/extended_types.tsx

@@ -0,0 +1,66 @@
+/*
+ * 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 { Fragment, useMemo } from 'react';
+import { EuiLink, EuiText } from '@elastic/eui';
+
+import { extendedTypesInfo } from './extended_types_info';
+import { ProcessedComponent, ExtendedType } from './definition_types';
+
+export type PropTableExtendedTypesProps = {
+  definition: ProcessedComponent;
+};
+
+export const PropTableExtendedTypes = ({
+  definition,
+}: PropTableExtendedTypesProps) => {
+  const extendedTypes = useMemo(() => {
+    const types = definition.extends.filter((type: ExtendedType) =>
+      extendedTypesInfo.hasOwnProperty(type.displayName)
+    );
+
+    if (
+      types.every(
+        (type: ExtendedType) => type.displayName.indexOf('HTMLAttributes') > -1
+      )
+    ) {
+      const htmlAttributesIndex = types.findIndex(
+        (type: ExtendedType) => type.displayName === 'HTMLAttributes'
+      );
+      if (htmlAttributesIndex > -1 && types.length > 1) {
+        types.splice(htmlAttributesIndex, 1);
+      }
+    }
+
+    return types;
+  }, [definition.extends]);
+
+  if (!extendedTypes.length) {
+    return null;
+  }
+
+  return (
+    <EuiText size="s">
+      Extends{' '}
+      {extendedTypes.map((type, index) => (
+        <Fragment key={index}>
+          <EuiLink
+            href={
+              extendedTypesInfo[
+                type.displayName as keyof typeof extendedTypesInfo
+              ].url
+            }
+          >
+            {type.displayName}
+          </EuiLink>
+          {extendedTypes.length - 1 > index && ', '}
+        </Fragment>
+      ))}
+    </EuiText>
+  );
+};

package/src/components/prop_table/extended_types_info.ts

@@ -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.
+ */
+
+export const extendedTypesInfo = {
+  // HTMLAttributes is removed from display if any of the following elements also exist
+  HTMLAttributes: {
+    name: 'HTMLElement',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement',
+  },
+  SelectHTMLAttributes: {
+    name: 'HTMLSelectElement',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement',
+  },
+  TextareaHTMLAttributes: {
+    name: 'HTMLTextAreaElement',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextAreaElement',
+  },
+  InputHTMLAttributes: {
+    name: 'HTMLInputElement',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement',
+  },
+  AnchorHTMLAttributes: {
+    name: 'HTMLAnchorElement',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement',
+  },
+  ButtonHTMLAttributes: {
+    name: 'HTMLButtonElement',
+    url: 'https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement',
+  },
+};

package/src/components/prop_table/index.ts

@@ -0,0 +1,9 @@
+/*
+ * 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.
+ */
+
+export { PropTable } from './prop_table';

package/src/components/prop_table/prop_table.tsx

@@ -0,0 +1,235 @@
+/*
+ * 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 {
+  EuiBasicTable,
+  EuiMarkdownFormat,
+  EuiBasicTableColumn,
+  EuiTextColor,
+  EuiFlexGroup,
+  EuiCode,
+  UseEuiTheme,
+  useEuiMemoizedStyles,
+  EuiLink,
+  EuiPanel,
+} from '@elastic/eui';
+import { useCallback, useMemo } from 'react';
+import { css } from '@emotion/react';
+import Heading from '@theme/Heading';
+
+import { PropTableExtendedTypes } from './extended_types';
+import { ProcessedComponent, ProcessedComponentProp } from './definition_types';
+
+export type PropTableProps = {
+  definition: ProcessedComponent;
+  headingLevel?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  showTitle?: boolean;
+  parseDescription?: (description: string) => string | undefined;
+};
+
+const getPropId = (prop: ProcessedComponentProp, componentName: string) =>
+  `${encodeURIComponent(componentName)}-prop-${prop.name}`;
+
+const getPropTableStyles = ({ euiTheme }: UseEuiTheme) => ({
+  propTable: css`
+    margin-block: ${euiTheme.size.xl};
+  `,
+  header: css`
+    // Increased specificity is needed here to override default
+    // content heading styles
+    && h1,
+    && h2,
+    && h3,
+    && h4,
+    && h5,
+    && h6 {
+      margin-block: 0;
+    }
+  `,
+  table: css`
+    vertical-align: top;
+  `,
+  propName: css`
+    font-family: ${euiTheme.font.familyCode};
+    font-weight: ${euiTheme.font.weight.semiBold};
+  `,
+  description: css`
+    p,
+    ul {
+      font-size: var(--eui-font-size-s);
+    }
+
+    p {
+      margin-block-end: var(--eui-size-s);
+    }
+
+    p:first-child {
+      margin-block-start: 0;
+    }
+  `,
+  required: css`
+    font-family: ${euiTheme.font.familyCode};
+    color: ${euiTheme.colors.textDanger};
+  `,
+  type: css`
+    font-weight: ${euiTheme.font.weight.semiBold};
+  `,
+  tableNameLink: css`
+    display: none;
+    margin-inline-start: ${euiTheme.size.xs};
+  `,
+  tableRow: css`
+    scroll-margin-block-start: calc(var(--ifm-navbar-height) + 0.5rem);
+
+    &:hover .propLink {
+      display: inline-block;
+    }
+  `,
+  tableCell: css`
+    vertical-align: text-top;
+  `,
+});
+
+export const PropTable = ({
+  definition,
+  headingLevel = 'h3',
+  showTitle = true,
+  parseDescription,
+}: PropTableProps) => {
+  const styles = useEuiMemoizedStyles(getPropTableStyles);
+
+  const tableItems = useMemo<Array<ProcessedComponentProp>>(
+    () =>
+      Object.values(definition.props).sort(
+        (a, b) => +(b.isRequired ?? false) - +(a.isRequired ?? false)
+      ),
+    [definition.props]
+  );
+
+  const columns = useMemo<Array<EuiBasicTableColumn<ProcessedComponentProp>>>(
+    () => [
+      {
+        field: 'name',
+        name: 'Prop',
+        width: '150',
+        render(
+          value: ProcessedComponentProp['name'],
+          prop: ProcessedComponentProp
+        ) {
+          return (
+            <span css={styles.propName}>
+              {value}
+              <EuiLink
+                href={`#${getPropId(prop, definition.displayName)}`}
+                css={styles.tableNameLink}
+                className="propLink"
+                aria-label={`Direct link to the ${prop.name} prop`}
+                title={`Direct link to the ${prop.name} prop`}
+              >
+                #
+              </EuiLink>
+            </span>
+          );
+        },
+      },
+      {
+        field: 'description',
+        name: 'Description and type',
+        render(
+          value: ProcessedComponentProp['description'],
+          prop: ProcessedComponentProp
+        ) {
+          const result = parseDescription ? parseDescription(value) : value;
+
+          return (
+            <EuiFlexGroup
+              direction="column"
+              alignItems="flexStart"
+              gutterSize="s"
+            >
+              {result && (
+                <EuiMarkdownFormat css={styles.description}>
+                  {result}
+                </EuiMarkdownFormat>
+              )}
+              {prop.type && (
+                <span css={styles.type}>
+                  Type:{' '}
+                  <EuiCode language="ts">
+                    {prop.type.raw || prop.type.name}
+                  </EuiCode>
+                </span>
+              )}
+            </EuiFlexGroup>
+          );
+        },
+      },
+      {
+        field: 'defaultValue',
+        name: 'Default value',
+        width: '120',
+        render(
+          value: ProcessedComponentProp['defaultValue'],
+          prop: ProcessedComponentProp
+        ) {
+          if (prop.isRequired && !value?.trim().length) {
+            return <EuiTextColor css={styles.required}>Required</EuiTextColor>;
+          }
+
+          return value && <EuiCode>{value}</EuiCode>;
+        },
+      },
+    ],
+    []
+  );
+
+  const rowProps = useCallback(
+    (item: ProcessedComponentProp) => ({
+      id: getPropId(item, definition.displayName),
+      css: styles.tableRow,
+    }),
+    [definition.displayName]
+  );
+
+  const cellProps = useCallback(
+    (item: ProcessedComponentProp) => ({
+      id: getPropId(item, definition.displayName),
+      css: styles.tableCell,
+    }),
+    [definition.displayName]
+  );
+
+  return (
+    <EuiFlexGroup
+      aria-label={`Component properties table for ${definition.displayName}`}
+      gutterSize="s"
+      direction="column"
+      css={styles.propTable}
+    >
+      <header css={styles.header}>
+        {showTitle && (
+          <Heading as={headingLevel} id={definition.displayName}>
+            {definition.displayName}
+          </Heading>
+        )}
+        <PropTableExtendedTypes definition={definition} />
+      </header>
+      <EuiPanel color="plain" hasBorder>
+        <EuiBasicTable
+          css={styles.table}
+          width="100%"
+          items={tableItems}
+          columns={columns}
+          rowProps={rowProps}
+          cellProps={cellProps}
+          compressed
+        />
+      </EuiPanel>
+    </EuiFlexGroup>
+  );
+};