@elastic/eui-docusaurus-theme 2.0.0

package/lib/theme/reset.styles.d.ts

@@ -0,0 +1,2 @@
+import { UseEuiTheme } from '@elastic/eui';
+export declare const getResetStyles: (theme: UseEuiTheme) => import("@emotion/react").SerializedStyles;

package/lib/theme/reset.styles.js

@@ -0,0 +1,79 @@
+/*
+ * 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 { euiFocusRing } from '@elastic/eui';
+import { css } from '@emotion/react';
+export const getResetStyles = (theme) => {
+    const { euiTheme } = theme;
+    return css `
+    button {
+      background: none;
+      border: none;
+      padding: 0;
+      margin: 0;
+      color: inherit;
+      border-radius: 0;
+      font-size: inherit;
+      font-family: inherit;
+    }
+
+    input,
+    textarea,
+    select {
+      font-size: 1rem; // Inherit from html root
+      font-family: inherit;
+    }
+
+    dd {
+      margin: 0;
+    }
+
+    figure {
+      margin: 0;
+    }
+
+    img {
+      max-inline-size: 100%;
+      height: auto;
+    }
+
+    ul, ol {
+      list-style: none;
+    }
+
+    * {
+      ${euiFocusRing(theme, 'outset', { color: euiTheme.colors.primary })};
+    }
+
+    /**
+     * Resets globals in theme/Layout
+     * https://github.com/facebook/docusaurus/blob/e64e0e7c96f695f9d63b22c0d0ee2e4001852ac6/packages/docusaurus-theme-classic/src/theme/Layout/styles.module.css#L8-L11
+     */
+    body {
+      height: initial;
+    }
+
+    html, body, div, span, applet, object, iframe,
+    h1, h2, h3, h4, h5, h6, p, blockquote, pre,
+    a, abbr, acronym, address, big, cite, code,
+    del, dfn, em, img, ins, kbd, q, s, samp,
+    small, strike, strong, sub, sup, tt, var,
+    b, u, i, center,
+    dl, dt, dd, ol, ul, li,
+    fieldset, form, label, legend,
+    table, caption, tbody, tfoot, thead, tr, th, td,
+    article, aside, canvas, details, embed,
+    figure, figcaption, footer, header, hgroup,
+    menu, nav, output, ruby, section, summary,
+    time, mark, audio, video {
+      margin: 0;
+      padding: 0;
+      border: none;
+      vertical-align: baseline;
+    }
+  `;
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@elastic/eui-docusaurus-theme",
+  "version": "2.0.0",
+  "description": "EUI theme for Docusaurus",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc --build",
+    "start": "tsc --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elastic/eui.git",
+    "directory": "packages/docusaurus-theme"
+  },
+  "devDependencies": {
+    "@docusaurus/types": "^3.7.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@types/react-is": "^18",
+    "typedoc": "^0.28.4",
+    "typescript": "~5.5.4"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./components/*": "./lib/components/*",
+    "./components": "./lib/components/index.js",
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "src",
+    "!**/.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@docusaurus/core": "^3.7.0",
+    "@docusaurus/module-type-aliases": "^3.7.0",
+    "@docusaurus/plugin-content-docs": "^3.7.0",
+    "@docusaurus/theme-common": "^3.7.0",
+    "@docusaurus/utils-validation": "^3.7.0",
+    "@elastic/datemath": "^5.0.3",
+    "@elastic/eui": "^109.1.0",
+    "@elastic/eui-theme-borealis": "^5.0.0",
+    "@emotion/css": "^11.11.2",
+    "@emotion/react": "^11.11.4",
+    "@types/react-window": "^1.8.8",
+    "clsx": "^2.1.1",
+    "codesandbox": "^2.2.3",
+    "dedent": "^1.5.3",
+    "moment": "^2.30.1",
+    "prism-react-renderer": "^2.3.1",
+    "react-is": "^18.3.1",
+    "react-live": "patch:react-live@npm%3A4.1.7#~/.yarn/patches/react-live-npm-4.1.7-7b41625faa.patch",
+    "react-window": "^1.8.10"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  }
+}

package/src/components/badge/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 { EuiBadge } from '@elastic/eui';
+
+export const Badge = EuiBadge;

package/src/components/codesandbox_icon/codesandbox_icon.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 { HTMLAttributes } from 'react';
+
+type Props = HTMLAttributes<SVGElement>;
+
+export const CodeSandboxIcon = (props: Props) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="16"
+    height="16"
+    preserveAspectRatio="xMidYMid"
+    viewBox="-20 0 296 296"
+    {...props}
+  >
+    <path d="M115.498 261.088v-106.61L23.814 101.73v60.773l41.996 24.347v45.7l49.688 28.54Zm23.814.627 50.605-29.151V185.78l42.269-24.495v-60.011l-92.874 53.621v106.82Zm80.66-180.887-48.817-28.289-42.863 24.872-43.188-24.897-49.252 28.667 91.914 52.882 92.206-53.235ZM0 222.212V74.495L127.987 0 256 74.182v147.797l-128.016 73.744L0 222.212Z" />
+  </svg>
+);

package/src/components/codesandbox_icon/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 { CodeSandboxIcon } from './codesandbox_icon';

package/src/components/demo/actions_bar/actions_bar.tsx

@@ -0,0 +1,95 @@
+/*
+ * 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,
+  EuiFlexGroup,
+  EuiToolTip,
+  useEuiMemoizedStyles,
+  UseEuiTheme,
+  darken,
+} from '@elastic/eui';
+import { css } from '@emotion/react';
+import { extraActions } from '@theme/Demo/actions';
+import { DemoSourceMeta } from '../demo';
+
+export interface DemoActionsBarProps {
+  activeSource: DemoSourceMeta | null;
+  sources: DemoSourceMeta[];
+  isSourceOpen: boolean;
+  setSourceOpen(isOpen: boolean): void;
+  onClickReloadExample(): void;
+  onClickCopyToClipboard(): void;
+}
+
+const getDemoActionsBarStyles = (euiTheme: UseEuiTheme) => {
+  return {
+    actionsBar: css`
+      padding: var(--eui-size-s);
+      background: ${darken(euiTheme.euiTheme.colors.body, 0.05)};
+      border-top: 1px solid var(--docs-demo-border-color);
+
+      &:last-child {
+        // border radius should be 1px smaller to work nicely
+        // with the wrapper border width of 1px
+        border-radius: 0 0 calc(var(--docs-demo-border-radius) - 1px)
+          calc(var(--docs-demo-border-radius) - 1px);
+      }
+    `,
+    button: css`
+      margin-right: auto;
+    `,
+  };
+};
+
+export const DemoActionsBar = ({
+  isSourceOpen,
+  setSourceOpen,
+  activeSource,
+  sources,
+  onClickReloadExample,
+  onClickCopyToClipboard,
+}: DemoActionsBarProps) => {
+  const styles = useEuiMemoizedStyles(getDemoActionsBarStyles);
+
+  return (
+    <EuiFlexGroup alignItems="center" css={styles.actionsBar} gutterSize="s">
+      <EuiButton
+        css={styles.button}
+        onClick={() => setSourceOpen(!isSourceOpen)}
+        size="s"
+        color="text"
+        minWidth={false}
+      >
+        {isSourceOpen ? 'Hide source' : 'Show source'}
+      </EuiButton>
+      {extraActions.map((ActionComponent) => (
+        <ActionComponent sources={sources} activeSource={activeSource} />
+      ))}
+      <EuiToolTip content="Copy to clipboard">
+        <EuiButtonIcon
+          size="s"
+          iconType="copyClipboard"
+          color="text"
+          onClick={onClickCopyToClipboard}
+          aria-label="Copy code to clipboard"
+        />
+      </EuiToolTip>
+      <EuiToolTip content="Reload example">
+        <EuiButtonIcon
+          size="s"
+          iconType="refresh"
+          color="text"
+          onClick={onClickReloadExample}
+          aria-label="Reload example"
+        />
+      </EuiToolTip>
+    </EuiFlexGroup>
+  );
+};

package/src/components/demo/actions_bar/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 { DemoActionsBar, type DemoActionsBarProps } from './actions_bar';

package/src/components/demo/code_transformer.ts

@@ -0,0 +1,44 @@
+/*
+ * 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 = /^\(?</;
+
+/**
+ * Transforms input JS/TS source code to a react-live compatible syntax.
+ * react-live uses the surcase library to transform input source code into
+ * browser-readable JavaScript.
+ *
+ * While surcase does support CommonJS and ESM import/export statements,
+ * it's not trivial to expose our internal React and EUI exports through it
+ * and because we already control the execution scope of the interactive demos
+ * it isn't really necessary to implement a smart `require()` replacement.
+ *
+ * Returning an IIFE is necessary when the source code is more than just
+ * a JSX component definition (e.g. it contains a variable definition
+ * or `export default` statement).
+ *
+ * @see https://github.com/alangpierce/sucrase
+ * @see https://github.com/FormidableLabs/react-live/blob/master/packages/react-live/src/utils/transpile/index.ts
+ */
+export const demoCodeTransformer = (code: string) => {
+  // Remove ESM imports
+  code = code.replace(IMPORT_REGEX, '');
+
+  // Handle ESM default exports
+  code = code.replace(DEFAULT_EXPORT_REGEX, 'return ');
+
+  // If the demo is JSX only return as-is
+  if (COMPONENT_ONLY_REGEX.test(code)) {
+    return code;
+  }
+
+  // If the demo is more than just JSX wrap in an immediately invoked function expression
+  return `(() => { ${code} })()`;
+}

package/src/components/demo/codesandbox/find_external_dependencies.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 importRegex =
+  /import([ \n\t]*(?:[^ \n\t\{\}]+[ \n\t]*,?)?(?:[ \n\t]*\{(?:[ \n\t]*[^ \n\t"'\{\}]+[ \n\t]*,?)+\})?[ \n\t]*)from[ \n\t]*(['"])(?<dependency>[^'"\n]+)(?:['"])/g;
+
+/**
+ * Find dependencies in import statements and return
+ * a package.json-like dependencies object.
+ */
+export const findExternalDependencies = (source: string) => {
+  return [...source.matchAll(importRegex)].reduce((acc, item) => {
+    const dependency = item.groups?.dependency;
+    if (!dependency) {
+      return acc;
+    }
+
+    const splitDependency = dependency.split('/');
+    if (dependency[0] === '@') {
+      // org-scoped dependencies have a single slash; ignore subsequent ones
+      acc[splitDependency.slice(0, 2).join('/')] = 'latest';
+    } else if (splitDependency[0] && /^[a-z]/i.test(splitDependency[0])) {
+      // non org-scoped dependencies should have no slashes
+      acc[splitDependency[0]] = 'latest';
+    }
+
+    return acc;
+  }, {} as Record<string, string>);
+};

package/src/components/demo/codesandbox/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 { createOpenInCodeSandboxAction } from './open_action';

package/src/components/demo/codesandbox/open_action.tsx

@@ -0,0 +1,132 @@
+/*
+ * 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 { useMemo } from 'react';
+import { getParameters } from 'codesandbox/lib/api/define';
+import dedent from 'dedent';
+import { EuiButtonIcon, EuiToolTip } from '@elastic/eui';
+import type { ActionComponent } from '../../../theme/Demo/actions';
+import { CodeSandboxIcon } from '../../codesandbox_icon';
+import { findExternalDependencies } from './find_external_dependencies';
+
+const indexTsxSource = dedent`
+  import React from 'react';
+  import { createRoot } from 'react-dom/client';
+  import createCache from '@emotion/cache';
+  import { EuiProvider, euiStylisPrefixer } from '@elastic/eui';
+
+  import Demo from './demo';
+
+  const cache = createCache({
+    key: 'codesandbox',
+    stylisPlugins: [euiStylisPrefixer],
+    container: document.querySelector('meta[name="emotion-styles"]')!,
+  });
+  cache.compat = true;
+
+  const root = createRoot(document.getElementById('root')!);
+  root.render(
+    <EuiProvider cache={cache}>
+      <Demo />
+    </EuiProvider>
+  );`;
+
+const publicIndexHtmlSource = dedent`
+  <head>
+    <title>@elastic/eui component demo</title>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300..700&family=Roboto+Mono:ital,wght@0,400..700;1,400..700&display=swap" rel="stylesheet" />
+    <meta name="emotion-styles">
+  </head>
+  <body>
+    <div id="root" />
+  </body>
+`;
+
+export const defaultCodeSandboxParameters = {
+  files: {
+    'index.tsx': {
+      content: indexTsxSource,
+    },
+    'public/index.html': {
+      content: publicIndexHtmlSource,
+    },
+  },
+};
+
+export type Options = {
+  files?: Record<string, string>;
+  dependencies: Record<string, string>;
+};
+
+const processTsxSource = (source: string) => {
+  // jsxImportSource pragma is needed in CodeSandbox as it doesn't seem
+  // to support that setting via tsconfig.json
+  return `/** @jsxImportSource @emotion/react */\n${source}`;
+};
+
+export const createOpenInCodeSandboxAction =
+  ({ files = {}, dependencies }: Options): ActionComponent =>
+  ({ activeSource }) => {
+    const parameters: string = useMemo(() => {
+      const source = activeSource?.code || '';
+
+      // Compute list of extra files that may be passed
+      const extraFiles = Object.entries(files).reduce(
+        (acc, [file, content]) => {
+          acc[file] = { content };
+          return acc;
+        },
+        {} as Record<string, { content: string }>
+      );
+
+      return getParameters({
+        files: {
+          ...defaultCodeSandboxParameters.files,
+          'demo.tsx': {
+            content: processTsxSource(source),
+          },
+          'package.json': {
+            content: {
+              dependencies: {
+                ...findExternalDependencies(source),
+                ...dependencies,
+              },
+            },
+          },
+          ...extraFiles,
+        },
+      } as any);
+    }, [activeSource]);
+
+    return (
+      <form
+        action="https://codesandbox.io/api/v1/sandboxes/define"
+        method="POST"
+        target="_blank"
+      >
+        <input type="hidden" name="parameters" value={parameters} />
+        <input
+          type="hidden"
+          name="query"
+          value={`module=/demo.tsx&view=split`}
+        />
+        <EuiToolTip content="Open in CodeSandbox">
+          <EuiButtonIcon
+            type="submit"
+            size="s"
+            iconType={CodeSandboxIcon}
+            color="text"
+            aria-label="Open in CodeSandbox"
+          />
+        </EuiToolTip>
+      </form>
+    );
+  };

package/src/components/demo/context.ts

@@ -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 { createContext, useContext } from 'react';
+import { DemoSourceMeta } from './demo';
+
+export interface DemoContextObject {
+  /**
+   * Array of all available sources for this demo instance
+   */
+  sources: DemoSourceMeta[];
+
+  /**
+   * Add source to the list of available sources
+   * This should only be used internally when initializing the component!
+   */
+  addSource(source: DemoSourceMeta): void;
+}
+
+export const DemoContext = createContext<DemoContextObject>({
+  sources: [],
+  addSource: () => {},
+});
+
+export const useDemoContext = () => useContext(DemoContext);

package/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} />;