[New docs] Global site and docusaurus theme improvements (#8093)

packages/docusaurus-theme/package.json

@@ -34,7 +34,7 @@
     "@docusaurus/theme-common": "^3.5.2",
     "@docusaurus/utils-validation": "^3.5.2",
     "@elastic/datemath": "^5.0.3",
-    "@elastic/eui": "94.5.0",
+    "@elastic/eui": "97.2.0",
     "@elastic/eui-docgen": "workspace:^",
     "@emotion/css": "^11.11.2",
     "@emotion/react": "^11.11.4",

packages/docusaurus-theme/src/components/demo/actions_bar/actions_bar.tsx

@@ -1,3 +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 {
   EuiButton,
   EuiButtonIcon,

packages/docusaurus-theme/src/components/demo/actions_bar/index.ts

@@ -1 +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 { DemoActionsBar, type DemoActionsBarProps } from './actions_bar';

packages/docusaurus-theme/src/components/demo/code_transformer.ts

@@ -1,3 +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.
+ */
+
 const IMPORT_REGEX = /^import [^'"]* from ['"]([^.'"\n ][^'"\n ]*)['"];?/gm;
 const DEFAULT_EXPORT_REGEX = /export default /;
 const COMPONENT_ONLY_REGEX = /^\(?</;

packages/docusaurus-theme/src/components/demo/context.ts

@@ -1,3 +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 { createContext, useContext } from 'react';
 import { DemoSourceMeta } from './demo';
 

packages/docusaurus-theme/src/components/demo/create_demo.tsx

@@ -0,0 +1,17 @@
+/*
+ * 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 { Demo, DemoProps } from './demo';
+
+/**
+ * Creates a custom <Demo /> component with predefined props.
+ */
+export const createDemo =
+  (defaultProps: Partial<DemoProps>): typeof Demo =>
+  (props: DemoProps) =>
+    <Demo {...defaultProps} {...props} />;

packages/docusaurus-theme/src/components/demo/demo.tsx

@@ -1,3 +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 {
   Children,
   PropsWithChildren,
@@ -42,6 +50,7 @@ export interface DemoProps extends PropsWithChildren {
    */
   scope?: Record<string, unknown>;
   previewPadding?: DemoPreviewProps['padding'];
+  previewWrapper?: DemoPreviewProps['wrapperComponent'];
 }
 
 const getDemoStyles = (euiTheme: UseEuiTheme) => ({
@@ -60,6 +69,7 @@ export const Demo = ({
   scope,
   isSourceOpen: _isSourceOpen = false,
   previewPadding,
+  previewWrapper,
 }: DemoProps) => {
   const styles = useEuiMemoizedStyles(getDemoStyles);
   const [sources, setSources] = useState<DemoSourceMeta[]>([]);
@@ -69,16 +79,19 @@ export const Demo = ({
   // liveProviderKey restarts the demo to its initial state
   const [liveProviderKey, setLiveProviderKey] = useState<number>(0);
 
-  const finalScope = useMemo(() => ({
-    ...demoDefaultScope,
-    ...scope,
-  }), [scope]);
+  const finalScope = useMemo(
+    () => ({
+      ...demoDefaultScope,
+      ...scope,
+    }),
+    [scope]
+  );
 
   const addSource = useCallback<DemoContextObject['addSource']>(
     (source: DemoSourceMeta) => {
-      setSources((sources) => ([...sources, source]));
+      setSources((sources) => [...sources, source]);
     },
-    [],
+    []
   );
 
   const onClickCopyToClipboard = useCallback(() => {
@@ -104,7 +117,10 @@ export const Demo = ({
           theme={prismThemes.dracula}
           scope={finalScope}
         >
-          <DemoPreview padding={previewPadding} />
+          <DemoPreview
+            padding={previewPadding}
+            wrapperComponent={previewWrapper}
+          />
           <DemoActionsBar
             isSourceOpen={isSourceOpen}
             setSourceOpen={setIsSourceOpen}

packages/docusaurus-theme/src/components/demo/editor/index.ts

@@ -1 +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';

packages/docusaurus-theme/src/components/demo/index.ts

@@ -1,2 +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';

packages/docusaurus-theme/src/components/demo/preview/index.ts

@@ -1 +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';

packages/docusaurus-theme/src/components/demo/preview/preview.tsx

@@ -1,13 +1,32 @@
+/*
+ * 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';
-import { CSSProperties } from 'react';
+import {
+  UseEuiTheme,
+  useEuiTheme,
+  EuiPaddingSize,
+  euiPaddingSize,
+} from '@elastic/eui';
 
 export interface DemoPreviewProps {
   padding?: EuiPaddingSize;
+  wrapperComponent?: ComponentType<PropsWithChildren>;
 }
 
 const getPreviewStyles = (euiTheme: UseEuiTheme) => ({
@@ -22,11 +41,12 @@ const getPreviewStyles = (euiTheme: UseEuiTheme) => ({
  * 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>
-);
+const PreviewLoader = () => <div>Loading...</div>;
 
-export const DemoPreview = ({ padding = 'l' }: DemoPreviewProps) => {
+export const DemoPreview = ({
+  padding = 'l',
+  wrapperComponent: WrapperComponent = Fragment,
+}: DemoPreviewProps) => {
   const euiTheme = useEuiTheme();
   const styles = getPreviewStyles(euiTheme);
   const paddingSize = euiPaddingSize(euiTheme, padding);
@@ -39,9 +59,15 @@ export const DemoPreview = ({ padding = 'l' }: DemoPreviewProps) => {
     <BrowserOnly fallback={<PreviewLoader />}>
       {() => (
         <>
-          <ErrorBoundary fallback={(params: any) => <ErrorBoundaryErrorMessageFallback {...params} />}>
+          <ErrorBoundary
+            fallback={(params: any) => (
+              <ErrorBoundaryErrorMessageFallback {...params} />
+            )}
+          >
             <div css={styles.previewWrapper} style={style}>
-              <LivePreview />
+              <WrapperComponent>
+                <LivePreview />
+              </WrapperComponent>
             </div>
           </ErrorBoundary>
         </>

packages/docusaurus-theme/src/components/demo/scope.ts

@@ -1,3 +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 React from 'react';
 import * as EUI from '@elastic/eui';
 import * as EmotionReact from '@emotion/react';

packages/docusaurus-theme/src/components/demo/source/get_source_from_children.ts

@@ -1,3 +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 { Children, ReactElement, ReactNode } from 'react';
 import { isElement } from 'react-is';
 

packages/docusaurus-theme/src/components/demo/source/index.ts

@@ -1 +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';

packages/docusaurus-theme/src/components/demo/source/source.tsx

@@ -1,3 +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 { PropsWithChildren, useEffect } from 'react';
 import { useDemoContext } from '../context';
 import { getSourceFromChildren } from './get_source_from_children';

packages/docusaurus-theme/src/components/guideline/guideline.tsx

@@ -0,0 +1,96 @@
+import { PropsWithChildren, ReactNode, useMemo } from 'react';
+import {
+  EuiFlexItem,
+  EuiSplitPanel,
+  EuiPanelProps,
+  useEuiMemoizedStyles,
+  UseEuiTheme,
+} 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 = ({ euiTheme }: UseEuiTheme) => ({
+  root: css`
+    margin-block: var(--eui-theme-content-vertical-spacing);
+  `,
+  wrapper: css`
+    border-block-end: 2px solid ${euiTheme.colors.lightShade};
+  `,
+  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>
+  );
+};