@elastic/eui-docusaurus-theme 2.0.0

package/src/components/demo/demo.tsx

@@ -0,0 +1,143 @@
+/*
+ * 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 {
+  Children,
+  PropsWithChildren,
+  useCallback,
+  useMemo,
+  useState,
+} from 'react';
+import { isElement } from 'react-is';
+import { LiveProvider } from 'react-live';
+import { themes as prismThemes } from 'prism-react-renderer';
+import {
+  useEuiMemoizedStyles,
+  copyToClipboard,
+  UseEuiTheme,
+} from '@elastic/eui';
+import { css } from '@emotion/react';
+import { demoDefaultScope } from '@theme/Demo/default_scope';
+import { DemoContext, DemoContextObject } from './context';
+import { DemoEditor } from './editor';
+import { DemoPreview } from './preview';
+import { DemoSource } from './source';
+import { originalScope } from './scope';
+import { DemoActionsBar } from './actions_bar';
+import { demoCodeTransformer } from './code_transformer';
+import { DemoPreviewProps } from './preview/preview';
+
+export interface DemoSourceMeta {
+  code: string;
+  isActive: boolean;
+  filename?: string;
+}
+
+export interface DemoProps extends PropsWithChildren {
+  /**
+   * Whether the source code editor is open by default
+   */
+  isSourceOpen?: boolean;
+  /**
+   * Allows to extend the default scope of the rendered demo and pass additional
+   * properties available within the demo.
+   *
+   * The default scope exposes all React and EUI exports.
+   */
+  scope?: Record<string, unknown>;
+  previewPadding?: DemoPreviewProps['padding'];
+  previewWrapper?: DemoPreviewProps['wrapperComponent'];
+}
+
+const getDemoStyles = (euiTheme: UseEuiTheme) => ({
+  demo: css`
+    --docs-demo-border-color: ${euiTheme.euiTheme.border.color};
+    --docs-demo-border-radius: ${euiTheme.euiTheme.size.s};
+
+    border: 1px solid var(--docs-demo-border-color);
+    border-radius: var(--docs-demo-border-radius);
+    margin-block: ${euiTheme.euiTheme.size.xl};
+    word-break: break-word;
+  `,
+});
+
+export const Demo = ({
+  children,
+  scope,
+  isSourceOpen: _isSourceOpen = false,
+  previewPadding,
+  previewWrapper,
+}: DemoProps) => {
+  const styles = useEuiMemoizedStyles(getDemoStyles);
+  const [sources, setSources] = useState<DemoSourceMeta[]>([]);
+  const [isSourceOpen, setIsSourceOpen] = useState<boolean>(_isSourceOpen);
+  const activeSource = sources[0] || null;
+
+  // liveProviderKey restarts the demo to its initial state
+  const [liveProviderKey, setLiveProviderKey] = useState<number>(0);
+
+  const finalScope = useMemo(
+    () => ({
+      ...originalScope,
+      ...demoDefaultScope,
+      ...scope,
+    }),
+    [scope]
+  );
+
+  const addSource = useCallback<DemoContextObject['addSource']>(
+    (source: DemoSourceMeta) => {
+      setSources((sources) => [...sources, source]);
+    },
+    []
+  );
+
+  const onClickCopyToClipboard = useCallback(() => {
+    copyToClipboard(activeSource?.code || '');
+  }, [activeSource]);
+
+  const onClickReloadExample = useCallback(() => {
+    setLiveProviderKey((liveProviderKey) => liveProviderKey + 1);
+  }, []);
+
+  return (
+    <div css={styles.demo}>
+      <DemoContext.Provider value={{ sources, addSource }}>
+        <LiveProvider
+          key={liveProviderKey}
+          code={activeSource?.code || ''}
+          transformCode={demoCodeTransformer}
+          theme={prismThemes.dracula}
+          scope={finalScope}
+        >
+          <DemoPreview
+            padding={previewPadding}
+            wrapperComponent={previewWrapper}
+          />
+          <DemoActionsBar
+            isSourceOpen={isSourceOpen}
+            setSourceOpen={setIsSourceOpen}
+            activeSource={activeSource}
+            sources={sources}
+            onClickCopyToClipboard={onClickCopyToClipboard}
+            onClickReloadExample={onClickReloadExample}
+          />
+          {isSourceOpen && <DemoEditor />}
+        </LiveProvider>
+
+        {Children.map(children, (child, index) => {
+          if (isElement(child) && child.type === DemoSource) {
+            return child;
+          }
+
+          return <DemoSource isActive={index === 0}>{child}</DemoSource>;
+        })}
+      </DemoContext.Provider>
+    </div>
+  );
+};

package/src/components/demo/editor/editor.tsx

@@ -0,0 +1,51 @@
+/*
+ * 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 { LiveEditor, LiveError } from 'react-live';
+import { css } from '@emotion/react';
+import { useEuiMemoizedStyles } from '@elastic/eui';
+
+const getEditorStyles = () => ({
+  editor: css`
+    font-family: var(--ifm-font-family-monospace);
+    border-radius: 0 0 var(--docs-demo-border-radius) var(--docs-demo-border-radius);
+
+    & .prism-code {
+      border-radius: 0 0 calc(var(--docs-demo-border-radius) - 1px) calc(var(--docs-demo-border-radius) - 1px);
+      max-height: 450px;
+      overflow: auto;
+    }
+  `,
+  error: css`
+    // docusaurus overrides the default pre styles
+    // forcing us to use higher specificity here
+    && > pre {
+      font-size: var(--eui-font-size-s);
+      background: var(--eui-background-color-danger);
+      color: var(--eui-color-danger-text);
+      padding: var(--eui-size-xs) var(--eui-size-s);
+      margin: 0;
+      border-radius: 0;
+    }
+  `,
+});
+
+export const DemoEditor = () => {
+  const styles = useEuiMemoizedStyles(getEditorStyles);
+
+  return (
+    <div css={styles.editor}>
+      <div css={styles.error}>
+        <LiveError />
+      </div>
+      <div>
+        <LiveEditor tabMode="focus" />
+      </div>
+    </div>
+  );
+}

package/src/components/demo/editor/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 { DemoEditor } from './editor';

package/src/components/demo/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.
+ */
+
+export { Demo, type DemoProps } from './demo';
+export { DemoSource } from './source';
+export { createDemo } from './create_demo';

package/src/components/demo/preview/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 { DemoPreview } from './preview';

package/src/components/demo/preview/preview.tsx

@@ -0,0 +1,77 @@
+/*
+ * 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 { LivePreview } from 'react-live';
+import {
+  ComponentType,
+  CSSProperties,
+  Fragment,
+  PropsWithChildren,
+} from 'react';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import { ErrorBoundaryErrorMessageFallback } from '@docusaurus/theme-common';
+import {
+  UseEuiTheme,
+  useEuiTheme,
+  EuiPaddingSize,
+  euiPaddingSize,
+} from '@elastic/eui';
+
+export interface DemoPreviewProps {
+  padding?: EuiPaddingSize;
+  wrapperComponent?: ComponentType<PropsWithChildren>;
+}
+
+const getPreviewStyles = (euiTheme: UseEuiTheme) => ({
+  previewWrapper: css`
+    padding: var(--docs-demo-preview-padding);
+    border-radius: var(--docs-demo-border-radius);
+  `,
+});
+
+/**
+ * PreviewLoader provides a fallback content for the server-side render
+ * of the live component preview component.
+ * Due to the limitations of react-live the demo is only rendered client-side.
+ */
+const PreviewLoader = () => <div>Loading...</div>;
+
+export const DemoPreview = ({
+  padding = 'l',
+  wrapperComponent: WrapperComponent = Fragment,
+}: DemoPreviewProps) => {
+  const euiTheme = useEuiTheme();
+  const styles = getPreviewStyles(euiTheme);
+  const paddingSize = euiPaddingSize(euiTheme, padding);
+
+  const style = {
+    '--docs-demo-preview-padding': paddingSize,
+  } as CSSProperties;
+
+  return (
+    <BrowserOnly fallback={<PreviewLoader />}>
+      {() => (
+        <>
+          <ErrorBoundary
+            fallback={(params: any) => (
+              <ErrorBoundaryErrorMessageFallback {...params} />
+            )}
+          >
+            <div css={styles.previewWrapper} style={style}>
+              <WrapperComponent>
+                <LivePreview />
+              </WrapperComponent>
+            </div>
+          </ErrorBoundary>
+        </>
+      )}
+    </BrowserOnly>
+  );
+};

package/src/components/demo/scope.ts

@@ -0,0 +1,14 @@
+/*
+ * 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 from 'react';
+
+export const originalScope: Record<string, unknown> = {
+  React,
+  ...React,
+};

package/src/components/demo/source/get_source_from_children.ts

@@ -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 { Children, ReactElement, ReactNode } from 'react';
+import { isElement } from 'react-is';
+
+export interface SourceMeta {
+  /**
+   * The source code
+   */
+  code: string;
+}
+
+/**
+ * Get source string from given children.
+ */
+export const getSourceFromChildren = (children: ReactNode): string | null => {
+  // Direct (non-MDX) usage almost always passes a string
+  if (typeof children === 'string') {
+    return children;
+  }
+
+  if (Children.count(children) !== 1 || !isElement(children)) {
+    // This should never happen
+    return null;
+  }
+
+  const element = children as ReactElement;
+  const functionName = (element.type as Function).name;
+  // The code block content could render in either MDXPre (development builds)
+  // or pre (optimized production builds)
+  if (
+    typeof element.type !== 'function' ||
+    (functionName !== 'MDXPre' && functionName !== 'pre')
+  ) {
+    return null;
+  }
+
+  if (!isElement(element.props.children)) {
+    return null;
+  }
+
+  const codeElement = element.props.children as ReactElement;
+  if (!codeElement || !codeElement.props.children) {
+    return null;
+  }
+
+  const code = codeElement.props.children;
+  if (typeof code !== 'string') {
+    return null;
+  }
+
+  return code;
+};

package/src/components/demo/source/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 { DemoSource, type DemoSourceProps } from './source';

package/src/components/demo/source/source.tsx

@@ -0,0 +1,36 @@
+/*
+ * 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 { PropsWithChildren, useEffect } from 'react';
+import { useDemoContext } from '../context';
+import { getSourceFromChildren } from './get_source_from_children';
+
+export interface DemoSourceProps extends PropsWithChildren {
+  filename?: string;
+  isActive?: boolean;
+}
+
+export const DemoSource = ({ children, filename, isActive = false }: DemoSourceProps) => {
+  const demoContext = useDemoContext();
+
+  useEffect(() => {
+    const source = getSourceFromChildren(children);
+
+    if (source) {
+      const transformedSource = source.replace(/\n$/, '');
+
+      demoContext.addSource({
+        code: transformedSource,
+        isActive,
+        filename,
+      });
+    }
+  }, [children]);
+
+  return null;
+}

package/src/components/figma_embed/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 { IframeHTMLAttributes, useMemo } from 'react';
+import { useEuiMemoizedStyles, UseEuiTheme } from '@elastic/eui';
+import { css } from '@emotion/react';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+export interface FigmaEmbedProps
+  extends IframeHTMLAttributes<HTMLIFrameElement> {
+  url: string;
+}
+
+const getFigmaEmbedStyles = (euiTheme: UseEuiTheme) => ({
+  wrapper: css`
+    border: 1px solid ${euiTheme.euiTheme.colors.lightShade};
+    border-radius: ${euiTheme.euiTheme.size.s};
+    margin: ${euiTheme.euiTheme.size.xl} 0;
+  `,
+  iframe: css`
+    border-radius: ${euiTheme.euiTheme.size.s};
+    display: block;
+  `,
+});
+
+export const FigmaEmbed = ({ url, ...rest }: FigmaEmbedProps) => {
+  const baseUrl = useBaseUrl('/', { absolute: true });
+  const styles = useEuiMemoizedStyles(getFigmaEmbedStyles);
+
+  const src = useMemo(() => {
+    const params = new URLSearchParams({
+      embed_host: 'eui.elastic.co',
+      embed_origin: baseUrl,
+      url,
+    });
+
+    return `https://www.figma.com/embed?${params.toString()}`;
+  }, [url, baseUrl]);
+
+  return (
+    <div css={styles.wrapper}>
+      <iframe
+        {...rest}
+        css={styles.iframe}
+        height="450"
+        width="100%"
+        src={src}
+        allowFullScreen
+      />
+    </div>
+  );
+};

package/src/components/guideline/guideline.tsx

@@ -0,0 +1,121 @@
+/*
+ * 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 { PropsWithChildren, ReactNode, useMemo } from 'react';
+import {
+  EuiFlexItem,
+  EuiSplitPanel,
+  EuiPanelProps,
+  useEuiMemoizedStyles,
+  UseEuiTheme,
+  highContrastModeStyles,
+} from '@elastic/eui';
+import { css } from '@emotion/react';
+
+import { GuidelineType } from './types';
+import { GuidelineText } from './guideline_text';
+
+export interface GuidelineProps extends PropsWithChildren {
+  type: GuidelineType;
+  text: string | ReactNode;
+  panelPadding?: EuiPanelProps['paddingSize'];
+  panelStyle?: EuiPanelProps['style'];
+}
+
+const getGuidelineStyles = (euiThemeContext: UseEuiTheme) => {
+  const { euiTheme } = euiThemeContext;
+  return {
+    root: css`
+      margin-block: var(--eui-theme-content-vertical-spacing);
+    `,
+    wrapper: css`
+      border-block-end: ${euiTheme.border.thick};
+      border-start-start-radius: ${euiTheme.border.radius.medium};
+      border-start-end-radius: ${euiTheme.border.radius.medium};
+      overflow: hidden;
+
+      ${highContrastModeStyles(euiThemeContext, {
+        // Code block is used within a panel which already has a border - skip doubling up
+        preferred: `
+          & > .euiCodeBlock {
+            border: none;
+          }
+        `,
+      })}
+    `,
+    wrapperDo: css`
+      border-color: ${euiTheme.colors.success};
+    `,
+    wrapperDont: css`
+      border-color: ${euiTheme.colors.danger};
+    `,
+    textWrapper: css`
+      margin-block-start: var(--eui-size-xs);
+    `,
+  };
+};
+
+export const Guideline = ({
+  children,
+  text,
+  type = 'default',
+  panelPadding = 'm',
+  panelStyle,
+}: GuidelineProps) => {
+  const styles = useEuiMemoizedStyles(getGuidelineStyles);
+
+  const panelColor = useMemo((): EuiPanelProps['color'] => {
+    if (type === 'do') {
+      return 'success';
+    }
+
+    if (type === 'dont') {
+      return 'danger';
+    }
+
+    return 'subdued';
+  }, [type]);
+
+  const textElement = useMemo(() => {
+    if (typeof text === 'string') {
+      return <GuidelineText type={type}>{text}</GuidelineText>;
+    }
+
+    return text;
+  }, [text]);
+
+  const wrapperStyles = [
+    styles.wrapper,
+    type === 'do' && styles.wrapperDo,
+    type === 'dont' && styles.wrapperDont,
+  ];
+
+  return (
+    <EuiFlexItem css={styles.root} style={{ flexBasis: 300 }}>
+      <EuiSplitPanel.Outer
+        color="transparent"
+        hasBorder={false}
+        hasShadow={false}
+      >
+        <figure>
+          <EuiSplitPanel.Inner
+            css={wrapperStyles}
+            color={panelColor}
+            paddingSize={panelPadding}
+            style={panelStyle}
+          >
+            {children}
+          </EuiSplitPanel.Inner>
+          <EuiSplitPanel.Inner paddingSize="none" css={styles.textWrapper}>
+            {textElement}
+          </EuiSplitPanel.Inner>
+        </figure>
+      </EuiSplitPanel.Outer>
+    </EuiFlexItem>
+  );
+};

package/src/components/guideline/guideline_text.tsx

@@ -0,0 +1,51 @@
+/*
+ * 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 { PropsWithChildren, useMemo } from 'react';
+import { EuiText, EuiTextProps } from '@elastic/eui';
+
+import { GuidelineType } from './types';
+
+export interface GuidelineTextProps extends PropsWithChildren {
+  type: GuidelineType;
+}
+
+export const GuidelineText = ({ type, children }: GuidelineTextProps) => {
+  const textPrefix = useMemo(() => {
+    if (type === 'default') {
+      return undefined;
+    }
+
+    return (
+      <>
+        <strong>{type === 'do' ? 'Do:' : `Don't:`}</strong>&nbsp;
+      </>
+    );
+  }, [type]);
+
+  const textColor = useMemo((): EuiTextProps['color'] => {
+    if (type === 'do') {
+      return 'success';
+    }
+
+    if (type === 'dont') {
+      return 'danger';
+    }
+
+    return 'text';
+  }, [type]);
+
+  return (
+    <EuiText size="s" color={textColor}>
+      <p>
+        {textPrefix}
+        {children}
+      </p>
+    </EuiText>
+  );
+};

package/src/components/guideline/index.ts

@@ -0,0 +1,10 @@
+/*
+ * 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 { Guideline, type GuidelineProps } from './guideline';
+export { GuidelineText, type GuidelineTextProps } from './guideline_text';

package/src/components/guideline/types.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 type GuidelineType = 'do' | 'dont' | 'default';