@elastic/eui-docusaurus-theme 2.0.0 → 2.2.0

package/lib/components/demo/actions_bar/actions_bar.d.ts

@@ -1,10 +1,11 @@
-import { DemoSourceMeta } from '../demo';
+import { DemoSourceMeta, ExtraFiles } from '../demo';
 export interface DemoActionsBarProps {
     activeSource: DemoSourceMeta | null;
     sources: DemoSourceMeta[];
+    extraFiles?: ExtraFiles;
     isSourceOpen: boolean;
     setSourceOpen(isOpen: boolean): void;
     onClickReloadExample(): void;
     onClickCopyToClipboard(): void;
 }
-export declare const DemoActionsBar: ({ isSourceOpen, setSourceOpen, activeSource, sources, onClickReloadExample, onClickCopyToClipboard, }: DemoActionsBarProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const DemoActionsBar: ({ isSourceOpen, setSourceOpen, activeSource, sources, extraFiles, onClickReloadExample, onClickCopyToClipboard, }: DemoActionsBarProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/lib/components/demo/actions_bar/actions_bar.js

@@ -28,7 +28,7 @@ const getDemoActionsBarStyles = (euiTheme) => {
     `,
     };
 };
-export const DemoActionsBar = ({ isSourceOpen, setSourceOpen, activeSource, sources, onClickReloadExample, onClickCopyToClipboard, }) => {
+export const DemoActionsBar = ({ isSourceOpen, setSourceOpen, activeSource, sources, extraFiles, onClickReloadExample, onClickCopyToClipboard, }) => {
     const styles = useEuiMemoizedStyles(getDemoActionsBarStyles);
-    return (_jsxs(EuiFlexGroup, { alignItems: "center", css: styles.actionsBar, gutterSize: "s", children: [_jsx(EuiButton, { css: styles.button, onClick: () => setSourceOpen(!isSourceOpen), size: "s", color: "text", minWidth: false, children: isSourceOpen ? 'Hide source' : 'Show source' }), extraActions.map((ActionComponent) => (_jsx(ActionComponent, { sources: sources, activeSource: activeSource }))), _jsx(EuiToolTip, { content: "Copy to clipboard", children: _jsx(EuiButtonIcon, { size: "s", iconType: "copyClipboard", color: "text", onClick: onClickCopyToClipboard, "aria-label": "Copy code to clipboard" }) }), _jsx(EuiToolTip, { content: "Reload example", children: _jsx(EuiButtonIcon, { size: "s", iconType: "refresh", color: "text", onClick: onClickReloadExample, "aria-label": "Reload example" }) })] }));
+    return (_jsxs(EuiFlexGroup, { alignItems: "center", css: styles.actionsBar, gutterSize: "s", children: [_jsx(EuiButton, { css: styles.button, onClick: () => setSourceOpen(!isSourceOpen), size: "s", color: "text", minWidth: false, children: isSourceOpen ? 'Hide source' : 'Show source' }), extraActions.map((ActionComponent) => (_jsx(ActionComponent, { sources: sources, extraFiles: extraFiles, activeSource: activeSource }))), _jsx(EuiToolTip, { content: "Copy to clipboard", children: _jsx(EuiButtonIcon, { size: "s", iconType: "copyClipboard", color: "text", onClick: onClickCopyToClipboard, "aria-label": "Copy code to clipboard" }) }), _jsx(EuiToolTip, { content: "Reload example", children: _jsx(EuiButtonIcon, { size: "s", iconType: "refresh", color: "text", onClick: onClickReloadExample, "aria-label": "Reload example" }) })] }));
 };

package/lib/components/demo/code_transformer.js

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

package/lib/components/demo/codesandbox/open_action.js

@@ -61,11 +61,14 @@ const processTsxSource = (source) => {
     // to support that setting via tsconfig.json
     return `/** @jsxImportSource @emotion/react */\n${source}`;
 };
-export const createOpenInCodeSandboxAction = ({ files = {}, dependencies }) => ({ activeSource }) => {
+export const createOpenInCodeSandboxAction = ({ files = {}, dependencies }) => ({ extraFiles, activeSource }) => {
     const parameters = useMemo(() => {
         const source = activeSource?.code || '';
         // Compute list of extra files that may be passed
-        const extraFiles = Object.entries(files).reduce((acc, [file, content]) => {
+        const codeSandboxFiles = Object.entries({
+            ...files,
+            ...extraFiles,
+        }).reduce((acc, [file, content]) => {
             acc[file] = { content };
             return acc;
         }, {});
@@ -83,9 +86,9 @@ export const createOpenInCodeSandboxAction = ({ files = {}, dependencies }) => (
                         },
                     },
                 },
-                ...extraFiles,
+                ...codeSandboxFiles,
             },
         });
-    }, [activeSource]);
+    }, [activeSource, extraFiles]);
     return (_jsxs("form", { action: "https://codesandbox.io/api/v1/sandboxes/define", method: "POST", target: "_blank", children: [_jsx("input", { type: "hidden", name: "parameters", value: parameters }), _jsx("input", { type: "hidden", name: "query", value: `module=/demo.tsx&view=split` }), _jsx(EuiToolTip, { content: "Open in CodeSandbox", children: _jsx(EuiButtonIcon, { type: "submit", size: "s", iconType: CodeSandboxIcon, color: "text", "aria-label": "Open in CodeSandbox" }) })] }));
 };

package/lib/components/demo/demo.d.ts

@@ -5,19 +5,45 @@ export interface DemoSourceMeta {
     isActive: boolean;
     filename?: string;
 }
+export type ExtraFiles = Record<string, 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.
+     * Allows to pass additional variables available within the demo.
+     * The key is the variable name and the value is the variable itself (component, function, object, etc).
      *
-     * The default scope exposes all React and EUI exports.
+     * @example
+     * ````mdx
+     * ```mdx-code-block
+     * import { MyComponent } from './my_component';
+     * ```
+     *
+     * <Demo scope={{ MyComponent }}>
+     *   ```tsx
+     *   export default () => <MyComponent />
+     *   ```
+     * </Demo>
+     * ````
      */
     scope?: Record<string, unknown>;
+    /**
+     * Allows to pass extra files that will be added to the Codesandbox instance.
+     * The key is the filename and the value is the serialized file content.
+     *
+     * @example
+     * ````mdx
+     * ```mdx-code-block
+     * import iconSvgSource from '!raw-loader!./icon.svg';
+     * ```
+     *
+     * <Demo extraFiles={{ 'icon.svg': iconSvgSource }} />
+     * ````
+     */
+    extraFiles?: ExtraFiles;
     previewPadding?: DemoPreviewProps['padding'];
     previewWrapper?: DemoPreviewProps['wrapperComponent'];
 }
-export declare const Demo: ({ children, scope, isSourceOpen: _isSourceOpen, previewPadding, previewWrapper, }: DemoProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const Demo: ({ children, scope, extraFiles, isSourceOpen: _isSourceOpen, previewPadding, previewWrapper, }: DemoProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/lib/components/demo/demo.js

@@ -31,7 +31,7 @@ const getDemoStyles = (euiTheme) => ({
     word-break: break-word;
   `,
 });
-export const Demo = ({ children, scope, isSourceOpen: _isSourceOpen = false, previewPadding, previewWrapper, }) => {
+export const Demo = ({ children, scope, extraFiles, isSourceOpen: _isSourceOpen = false, previewPadding, previewWrapper, }) => {
     const styles = useEuiMemoizedStyles(getDemoStyles);
     const [sources, setSources] = useState([]);
     const [isSourceOpen, setIsSourceOpen] = useState(_isSourceOpen);
@@ -52,7 +52,7 @@ export const Demo = ({ children, scope, isSourceOpen: _isSourceOpen = false, pre
     const onClickReloadExample = useCallback(() => {
         setLiveProviderKey((liveProviderKey) => liveProviderKey + 1);
     }, []);
-    return (_jsx("div", { css: styles.demo, children: _jsxs(DemoContext.Provider, { value: { sources, addSource }, children: [_jsxs(LiveProvider, { code: activeSource?.code || '', transformCode: demoCodeTransformer, theme: prismThemes.dracula, scope: finalScope, children: [_jsx(DemoPreview, { padding: previewPadding, wrapperComponent: previewWrapper }), _jsx(DemoActionsBar, { isSourceOpen: isSourceOpen, setSourceOpen: setIsSourceOpen, activeSource: activeSource, sources: sources, onClickCopyToClipboard: onClickCopyToClipboard, onClickReloadExample: onClickReloadExample }), isSourceOpen && _jsx(DemoEditor, {})] }, liveProviderKey), Children.map(children, (child, index) => {
+    return (_jsx("div", { css: styles.demo, children: _jsxs(DemoContext.Provider, { value: { sources, addSource }, children: [_jsxs(LiveProvider, { code: activeSource?.code || '', transformCode: demoCodeTransformer, theme: prismThemes.dracula, scope: finalScope, children: [_jsx(DemoPreview, { padding: previewPadding, wrapperComponent: previewWrapper }), _jsx(DemoActionsBar, { isSourceOpen: isSourceOpen, setSourceOpen: setIsSourceOpen, activeSource: activeSource, extraFiles: extraFiles, sources: sources, onClickCopyToClipboard: onClickCopyToClipboard, onClickReloadExample: onClickReloadExample }), isSourceOpen && _jsx(DemoEditor, {})] }, liveProviderKey), Children.map(children, (child, index) => {
                     if (isElement(child) && child.type === DemoSource) {
                         return child;
                     }

package/lib/theme/Demo/actions.d.ts

@@ -1,8 +1,9 @@
 import { ComponentType } from 'react';
-import { DemoSourceMeta } from '../../components/demo/demo';
+import { DemoSourceMeta, ExtraFiles } from '../../components/demo/demo';
 export type ActionComponentProps = {
     activeSource: DemoSourceMeta | null;
     sources: DemoSourceMeta[];
+    extraFiles?: ExtraFiles;
 };
 export type ActionComponent = ComponentType<ActionComponentProps>;
 export declare const extraActions: ActionComponent[];

package/lib/theme/DocBreadcrumbs/Items/Home/index.js

@@ -3,13 +3,16 @@ import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import { translate } from '@docusaurus/Translate';
 import { EuiIcon, useEuiMemoizedStyles } from '@elastic/eui';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import { getItemStyles } from '../item.styles';
 export default function HomeBreadcrumbItem() {
     const homeHref = useBaseUrl('/');
+    const { siteConfig } = useDocusaurusContext();
+    const { title } = siteConfig;
     const styles = useEuiMemoizedStyles(getItemStyles);
     return (_jsxs("li", { className: "breadcrumbs__item", css: styles.item, children: [_jsx(Link, { "aria-label": translate({
                     id: 'theme.docs.breadcrumbs.home',
                     message: 'Home page',
                     description: 'The ARIA label for the home page in the breadcrumbs',
-                }), className: "breadcrumbs__link", href: homeHref, children: "EUI" }), _jsx(EuiIcon, { type: "arrowRight", size: "s", css: styles.icon })] }));
+                }), className: "breadcrumbs__link", href: homeHref, children: title }), _jsx(EuiIcon, { type: "arrowRight", size: "s", css: styles.icon })] }));
 }

package/lib/theme/DocCard/index.d.ts

@@ -0,0 +1,5 @@
+import { type ReactNode } from 'react';
+import type { PropSidebarItemCategory, PropSidebarItemLink } from '@docusaurus/plugin-content-docs';
+export default function DocCard({ item, }: {
+    item: PropSidebarItemCategory | PropSidebarItemLink;
+}): ReactNode;

package/lib/theme/DocCard/index.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+import { useDocById, findFirstSidebarItemLink, } from '@docusaurus/plugin-content-docs/client';
+import { usePluralForm } from '@docusaurus/theme-common';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import { translate } from '@docusaurus/Translate';
+import { EuiCard, EuiIcon } from '@elastic/eui';
+function useCategoryItemsPlural() {
+    const { selectMessage } = usePluralForm();
+    return (count) => selectMessage(count, translate({
+        message: '1 item|{count} items',
+        id: 'theme.docs.DocCard.categoryDescription.plurals',
+        description: 'The default description for a category card in the generated index about how many items this category includes',
+    }, { count }));
+}
+function CardLayout({ href, icon, title, description, }) {
+    return (_jsx(EuiCard, { icon: _jsx(EuiIcon, { size: "l", type: icon }), title: title, description: description || '', titleSize: "xs", layout: "horizontal", href: href }));
+}
+function CardCategory({ item }) {
+    const href = findFirstSidebarItemLink(item);
+    const categoryItemsPlural = useCategoryItemsPlural();
+    // Unexpected: categories that don't have a link have been filtered upfront
+    if (!href) {
+        return null;
+    }
+    return (_jsx(CardLayout, { href: href, 
+        // Coincidentally, `folderOpen` is the same icon in EUI icon library
+        icon: "folderOpen", title: item.label, description: item.description ?? categoryItemsPlural(item.items.length) }));
+}
+function CardLink({ item }) {
+    // We update Docusaurus `link` icon to EUI `popout` icon
+    const icon = isInternalUrl(item.href) ? 'document' : 'popout';
+    const doc = useDocById(item.docId ?? undefined);
+    return (_jsx(CardLayout, { href: item.href, icon: icon, title: item.label, description: item.description ?? doc?.description }));
+}
+export default function DocCard({ item, }) {
+    switch (item.type) {
+        case 'link':
+            return _jsx(CardLink, { item: item });
+        case 'category':
+            return _jsx(CardCategory, { item: item });
+        default:
+            throw new Error(`unknown item type ${JSON.stringify(item)}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elastic/eui-docusaurus-theme",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "EUI theme for Docusaurus",
   "license": "SEE LICENSE IN LICENSE.txt",
   "scripts": {
@@ -40,8 +40,8 @@
     "@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",
+    "@elastic/eui": "^112.1.0",
+    "@elastic/eui-theme-borealis": "^5.4.0",
     "@emotion/css": "^11.11.2",
     "@emotion/react": "^11.11.4",
     "@types/react-window": "^1.8.8",

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

@@ -17,11 +17,12 @@ import {
 } from '@elastic/eui';
 import { css } from '@emotion/react';
 import { extraActions } from '@theme/Demo/actions';
-import { DemoSourceMeta } from '../demo';
+import { DemoSourceMeta, ExtraFiles } from '../demo';
 
 export interface DemoActionsBarProps {
   activeSource: DemoSourceMeta | null;
   sources: DemoSourceMeta[];
+  extraFiles?: ExtraFiles;
   isSourceOpen: boolean;
   setSourceOpen(isOpen: boolean): void;
   onClickReloadExample(): void;
@@ -53,6 +54,7 @@ export const DemoActionsBar = ({
   setSourceOpen,
   activeSource,
   sources,
+  extraFiles,
   onClickReloadExample,
   onClickCopyToClipboard,
 }: DemoActionsBarProps) => {
@@ -70,7 +72,11 @@ export const DemoActionsBar = ({
         {isSourceOpen ? 'Hide source' : 'Show source'}
       </EuiButton>
       {extraActions.map((ActionComponent) => (
-        <ActionComponent sources={sources} activeSource={activeSource} />
+        <ActionComponent
+          sources={sources}
+          extraFiles={extraFiles}
+          activeSource={activeSource}
+        />
       ))}
       <EuiToolTip content="Copy to clipboard">
         <EuiButtonIcon

package/src/components/demo/code_transformer.ts

@@ -6,7 +6,7 @@
  * Side Public License, v 1.
  */
 
-const IMPORT_REGEX = /^import [^'"]* from ['"]([^.'"\n ][^'"\n ]*)['"];?/gm;
+const IMPORT_REGEX = /^import [^'"]* from ['"]([^'"\n ]*)['"];?/gm;
 const DEFAULT_EXPORT_REGEX = /export default /;
 const COMPONENT_ONLY_REGEX = /^\(?</;
 

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

@@ -74,17 +74,20 @@ const processTsxSource = (source: string) => {
 
 export const createOpenInCodeSandboxAction =
   ({ files = {}, dependencies }: Options): ActionComponent =>
-  ({ activeSource }) => {
+  ({ extraFiles, activeSource }) => {
     const parameters: string = useMemo(() => {
       const source = activeSource?.code || '';
 
       // Compute list of extra files that may be passed
-      const extraFiles = Object.entries(files).reduce(
+      const codeSandboxFiles = Object.entries({
+        ...files,
+        ...extraFiles,
+      }).reduce(
         (acc, [file, content]) => {
           acc[file] = { content };
           return acc;
         },
-        {} as Record<string, { content: string }>
+        {} as Record<string, { content: unknown }>
       );
 
       return getParameters({
@@ -101,10 +104,10 @@ export const createOpenInCodeSandboxAction =
               },
             },
           },
-          ...extraFiles,
+          ...codeSandboxFiles,
         },
       } as any);
-    }, [activeSource]);
+    }, [activeSource, extraFiles]);
 
     return (
       <form

package/src/components/demo/demo.tsx

@@ -38,18 +38,45 @@ export interface DemoSourceMeta {
   filename?: string;
 }
 
+export type ExtraFiles = Record<string, 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.
+   * Allows to pass additional variables available within the demo.
+   * The key is the variable name and the value is the variable itself (component, function, object, etc).
+   *
+   * @example
+   * ````mdx
+   * ```mdx-code-block
+   * import { MyComponent } from './my_component';
+   * ```
    *
-   * The default scope exposes all React and EUI exports.
+   * <Demo scope={{ MyComponent }}>
+   *   ```tsx
+   *   export default () => <MyComponent />
+   *   ```
+   * </Demo>
+   * ````
    */
   scope?: Record<string, unknown>;
+  /**
+   * Allows to pass extra files that will be added to the Codesandbox instance.
+   * The key is the filename and the value is the serialized file content.
+   *
+   * @example
+   * ````mdx
+   * ```mdx-code-block
+   * import iconSvgSource from '!raw-loader!./icon.svg';
+   * ```
+   *
+   * <Demo extraFiles={{ 'icon.svg': iconSvgSource }} />
+   * ````
+   */
+  extraFiles?: ExtraFiles;
   previewPadding?: DemoPreviewProps['padding'];
   previewWrapper?: DemoPreviewProps['wrapperComponent'];
 }
@@ -69,6 +96,7 @@ const getDemoStyles = (euiTheme: UseEuiTheme) => ({
 export const Demo = ({
   children,
   scope,
+  extraFiles,
   isSourceOpen: _isSourceOpen = false,
   previewPadding,
   previewWrapper,
@@ -123,6 +151,7 @@ export const Demo = ({
             isSourceOpen={isSourceOpen}
             setSourceOpen={setIsSourceOpen}
             activeSource={activeSource}
+            extraFiles={extraFiles}
             sources={sources}
             onClickCopyToClipboard={onClickCopyToClipboard}
             onClickReloadExample={onClickReloadExample}

package/src/theme/Demo/actions.tsx

@@ -8,11 +8,12 @@
 
 import { ComponentType } from 'react';
 
-import { DemoSourceMeta } from '../../components/demo/demo';
+import { DemoSourceMeta, ExtraFiles } from '../../components/demo/demo';
 
 export type ActionComponentProps = {
   activeSource: DemoSourceMeta | null;
   sources: DemoSourceMeta[];
+  extraFiles?: ExtraFiles;
 };
 
 export type ActionComponent = ComponentType<ActionComponentProps>;

package/src/theme/DocBreadcrumbs/Items/Home/index.tsx

@@ -11,11 +11,14 @@ import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import { translate } from '@docusaurus/Translate';
 import { EuiIcon, useEuiMemoizedStyles } from '@elastic/eui';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
 import { getItemStyles } from '../item.styles';
 
 export default function HomeBreadcrumbItem(): JSX.Element {
   const homeHref = useBaseUrl('/');
+  const { siteConfig } = useDocusaurusContext();
+  const { title } = siteConfig;
 
   const styles = useEuiMemoizedStyles(getItemStyles);
 
@@ -30,7 +33,7 @@ export default function HomeBreadcrumbItem(): JSX.Element {
         className="breadcrumbs__link"
         href={homeHref}
       >
-        EUI
+        {title}
       </Link>
       <EuiIcon type="arrowRight" size="s" css={styles.icon} />
     </li>

package/src/theme/DocCard/index.tsx

@@ -0,0 +1,104 @@
+import { type ReactNode } from 'react';
+import {
+  useDocById,
+  findFirstSidebarItemLink,
+} from '@docusaurus/plugin-content-docs/client';
+import { usePluralForm } from '@docusaurus/theme-common';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import { translate } from '@docusaurus/Translate';
+
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+
+import { EuiCard, EuiIcon } from '@elastic/eui';
+
+function useCategoryItemsPlural() {
+  const { selectMessage } = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          message: '1 item|{count} items',
+          id: 'theme.docs.DocCard.categoryDescription.plurals',
+          description:
+            'The default description for a category card in the generated index about how many items this category includes',
+        },
+        { count }
+      )
+    );
+}
+
+function CardLayout({
+  href,
+  icon,
+  title,
+  description,
+}: {
+  href: string;
+  icon: string;
+  title: string;
+  description?: string;
+}): ReactNode {
+  return (
+    <EuiCard
+      icon={<EuiIcon size="l" type={icon} />}
+      title={title}
+      description={description || ''}
+      titleSize="xs"
+      layout="horizontal"
+      href={href}
+    />
+  );
+}
+
+function CardCategory({ item }: { item: PropSidebarItemCategory }): ReactNode {
+  const href = findFirstSidebarItemLink(item);
+  const categoryItemsPlural = useCategoryItemsPlural();
+
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+
+  return (
+    <CardLayout
+      href={href}
+      // Coincidentally, `folderOpen` is the same icon in EUI icon library
+      icon="folderOpen"
+      title={item.label}
+      description={item.description ?? categoryItemsPlural(item.items.length)}
+    />
+  );
+}
+
+function CardLink({ item }: { item: PropSidebarItemLink }): ReactNode {
+  // We update Docusaurus `link` icon to EUI `popout` icon
+  const icon = isInternalUrl(item.href) ? 'document' : 'popout';
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={item.description ?? doc?.description}
+    />
+  );
+}
+
+export default function DocCard({
+  item,
+}: {
+  item: PropSidebarItemCategory | PropSidebarItemLink;
+}): ReactNode {
+  switch (item.type) {
+    case 'link':
+      return <CardLink item={item} />;
+    case 'category':
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

package/src/theme/theme.d.ts

@@ -585,11 +585,15 @@ declare module '@theme/Demo/default_scope' {
 
 declare module '@theme/Demo/actions' {
   import type { ComponentType } from 'react';
-  import type { DemoSourceMeta } from '@elastic/eui-docusaurus-theme/components/demo/demo';
+  import type {
+    DemoSourceMeta,
+    ExtraFiles,
+  } from '@elastic/eui-docusaurus-theme/components/demo/demo';
 
   export type ActionComponentProps = {
     activeSource: DemoSourceMeta;
     sources: DemoSourceMeta[];
+    extraFiles?: ExtraFiles;
   };
 
   export type ActionComponent = ComponentType<ActionComponentProps>;