[ES|QL] Enhances the inline documentation experience

packages/kbn-language-documentation-popover/index.ts

@@ -6,7 +6,8 @@
  * your election, the "Elastic License 2.0", the "GNU Affero General Public
  * License v3.0 only", or the "Server Side Public License, v 1".
  */
-
-export { LanguageDocumentationPopover } from './src/components/documentation_popover';
-export { LanguageDocumentationPopoverContent } from './src/components/documentation_content';
-export type { LanguageDocumentationSections } from './src/components/documentation_content';
+export { LanguageDocumentationPopover } from './src/components/as_popover';
+export { LanguageDocumentationPopoverContent } from './src/components/as_popover/popover_content';
+export { LanguageDocumentationFlyout } from './src/components/as_flyout';
+export { LanguageDocumentationInline } from './src/components/as_inline';
+export type { LanguageDocumentationSections } from './src/types';

packages/kbn-language-documentation-popover/setup_tests.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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+import '@testing-library/jest-dom';

packages/kbn-language-documentation-popover/src/__stories__/language_documentation_popover.stories.tsx

@@ -9,7 +9,7 @@
 
 import React from 'react';
 import { storiesOf } from '@storybook/react';
-import { LanguageDocumentationPopover } from '../components/documentation_popover';
+import { LanguageDocumentationPopover } from '../components/as_popover';
 
 const sections = {
   groups: [

packages/kbn-language-documentation-popover/src/components/as_flyout/index.test.tsx

@@ -0,0 +1,94 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import React from 'react';
+import { screen, render, fireEvent } from '@testing-library/react';
+import { Markdown } from '@kbn/shared-ux-markdown';
+import { LanguageDocumentationFlyout } from '.';
+
+describe('###Documentation flyout component', () => {
+  const sections = {
+    groups: [
+      {
+        label: 'Section one',
+        description: 'Section 1 description',
+        items: [],
+      },
+      {
+        label: 'Section two',
+        items: [
+          {
+            label: 'Section two item 1',
+            description: (
+              <Markdown readOnly markdownContent={`## Section two item 1 description `} />
+            ),
+          },
+          {
+            label: 'Section two item 2',
+            description: (
+              <Markdown readOnly markdownContent={`## Section two item 2 description `} />
+            ),
+          },
+        ],
+      },
+      {
+        label: 'Section three',
+        items: [
+          {
+            label: 'Section three item 1',
+            description: (
+              <Markdown readOnly markdownContent={`## Section three item 1 description `} />
+            ),
+          },
+          {
+            label: 'Section three item 2',
+            description: (
+              <Markdown readOnly markdownContent={`## Section three item 2 description `} />
+            ),
+          },
+        ],
+      },
+    ],
+    initialSection: <span>Here is the initial section</span>,
+  };
+  const renderFlyout = (linkToDocumentation?: string) => {
+    return render(
+      <LanguageDocumentationFlyout
+        isHelpMenuOpen={true}
+        onHelpMenuVisibilityChange={jest.fn()}
+        sections={sections}
+        linkToDocumentation={linkToDocumentation}
+      />
+    );
+  };
+  it('has a header element for navigation through the sections', () => {
+    renderFlyout();
+    expect(screen.getByTestId('language-documentation-navigation-search')).toBeInTheDocument();
+    expect(screen.getByTestId('language-documentation-navigation-dropdown')).toBeInTheDocument();
+    expect(screen.queryByTestId('language-documentation-navigation-link')).not.toBeInTheDocument();
+  });
+
+  it('has a link if linkToDocumentation prop is given', () => {
+    renderFlyout('meow');
+    expect(screen.getByTestId('language-documentation-navigation-link')).toBeInTheDocument();
+  });
+
+  it('contains the two last sections', () => {
+    renderFlyout();
+    expect(screen.getByText('Section two')).toBeInTheDocument();
+    expect(screen.getByText('Section three')).toBeInTheDocument();
+  });
+
+  it('contains the correct section if user updates the search input', () => {
+    renderFlyout();
+    const input = screen.getByTestId('language-documentation-navigation-search');
+    fireEvent.change(input, { target: { value: 'two' } });
+    expect(screen.getByText('Section two')).toBeInTheDocument();
+  });
+});

packages/kbn-language-documentation-popover/src/components/as_flyout/index.tsx

@@ -0,0 +1,88 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+import React, { useCallback, useEffect, useState, useRef, useMemo } from 'react';
+import { EuiFlyout, useEuiTheme, EuiFlyoutBody, EuiFlyoutHeader } from '@elastic/eui';
+import { getFilteredGroups } from '../../utils/get_filtered_groups';
+import { DocumentationMainContent, DocumentationNavigation } from '../shared';
+import type { LanguageDocumentationSections } from '../../types';
+
+interface DocumentationFlyoutProps {
+  isHelpMenuOpen: boolean;
+  onHelpMenuVisibilityChange: (status: boolean) => void;
+  sections?: LanguageDocumentationSections;
+  searchInDescription?: boolean;
+  linkToDocumentation?: string;
+}
+
+function DocumentationFlyout({
+  sections,
+  searchInDescription,
+  linkToDocumentation,
+  isHelpMenuOpen,
+  onHelpMenuVisibilityChange,
+}: DocumentationFlyoutProps) {
+  const { euiTheme } = useEuiTheme();
+  const DEFAULT_WIDTH = euiTheme.base * 34;
+
+  const [selectedSection, setSelectedSection] = useState<string | undefined>();
+  const [searchText, setSearchText] = useState('');
+
+  const scrollTargets = useRef<Record<string, HTMLElement>>({});
+
+  const filteredGroups = useMemo(() => {
+    return getFilteredGroups(searchText, searchInDescription, sections, 1);
+  }, [sections, searchText, searchInDescription]);
+
+  const onNavigationChange = useCallback((selectedOptions) => {
+    setSelectedSection(selectedOptions.length ? selectedOptions[0].label : undefined);
+    if (selectedOptions.length) {
+      const scrollToElement = scrollTargets.current[selectedOptions[0].label];
+      scrollToElement.scrollIntoView();
+    }
+  }, []);
+
+  useEffect(() => {
+    onHelpMenuVisibilityChange(isHelpMenuOpen ?? false);
+  }, [isHelpMenuOpen, onHelpMenuVisibilityChange]);
+
+  return (
+    <>
+      {isHelpMenuOpen && (
+        <EuiFlyout
+          ownFocus
+          onClose={() => onHelpMenuVisibilityChange(false)}
+          aria-labelledby="esqlInlineDocumentationFlyout"
+          type="push"
+          size={DEFAULT_WIDTH}
+        >
+          <EuiFlyoutHeader hasBorder>
+            <DocumentationNavigation
+              searchText={searchText}
+              setSearchText={setSearchText}
+              onNavigationChange={onNavigationChange}
+              filteredGroups={filteredGroups}
+              linkToDocumentation={linkToDocumentation}
+              selectedSection={selectedSection}
+            />
+          </EuiFlyoutHeader>
+          <EuiFlyoutBody>
+            <DocumentationMainContent
+              searchText={searchText}
+              scrollTargets={scrollTargets}
+              filteredGroups={filteredGroups}
+              sections={sections}
+            />
+          </EuiFlyoutBody>
+        </EuiFlyout>
+      )}
+    </>
+  );
+}
+
+export const LanguageDocumentationFlyout = React.memo(DocumentationFlyout);

packages/kbn-language-documentation-popover/src/components/as_inline/index.test.tsx

@@ -0,0 +1,88 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import React from 'react';
+import { screen, render, fireEvent } from '@testing-library/react';
+import { Markdown } from '@kbn/shared-ux-markdown';
+import { LanguageDocumentationInline } from '.';
+
+describe('###Documentation flyout component', () => {
+  const sections = {
+    groups: [
+      {
+        label: 'Section one',
+        description: 'Section 1 description',
+        items: [],
+      },
+      {
+        label: 'Section two',
+        items: [
+          {
+            label: 'Section two item 1',
+            description: (
+              <Markdown readOnly markdownContent={`## Section two item 1 description `} />
+            ),
+          },
+          {
+            label: 'Section two item 2',
+            description: (
+              <Markdown readOnly markdownContent={`## Section two item 2 description `} />
+            ),
+          },
+        ],
+      },
+      {
+        label: 'Section three',
+        items: [
+          {
+            label: 'Section three item 1',
+            description: <Markdown readOnly markdownContent={`## Section three blah blah `} />,
+          },
+          {
+            label: 'Section three item 2',
+            description: (
+              <Markdown readOnly markdownContent={`## Section three item 2 description `} />
+            ),
+          },
+        ],
+      },
+    ],
+    initialSection: <span>Here is the initial section</span>,
+  };
+  const renderInlineComponent = (searchInDescription = false) => {
+    return render(
+      <LanguageDocumentationInline sections={sections} searchInDescription={searchInDescription} />
+    );
+  };
+  it('has a header element for navigation through the sections', () => {
+    renderInlineComponent();
+    expect(screen.getByTestId('language-documentation-navigation-search')).toBeInTheDocument();
+    expect(screen.getByTestId('language-documentation-navigation-dropdown')).toBeInTheDocument();
+  });
+
+  it('contains the two last sections', () => {
+    renderInlineComponent();
+    expect(screen.getByText('Section two')).toBeInTheDocument();
+    expect(screen.getByText('Section three')).toBeInTheDocument();
+  });
+
+  it('contains the correct section if user updates the search input', () => {
+    renderInlineComponent();
+    const input = screen.getByTestId('language-documentation-navigation-search');
+    fireEvent.change(input, { target: { value: 'two' } });
+    expect(screen.getByText('Section two')).toBeInTheDocument();
+  });
+
+  it('contains the correct section if user updates the search input with a text that exist in the description', () => {
+    renderInlineComponent(true);
+    const input = screen.getByTestId('language-documentation-navigation-search');
+    fireEvent.change(input, { target: { value: 'blah' } });
+    expect(screen.getByText('Section three')).toBeInTheDocument();
+  });
+});

packages/kbn-language-documentation-popover/src/components/as_inline/index.tsx

@@ -0,0 +1,70 @@
+/*
+ * 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", the "GNU Affero General Public License v3.0 only", 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", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+import React, { useCallback, useState, useRef, useMemo } from 'react';
+import { css } from '@emotion/react';
+import { useEuiTheme, euiScrollBarStyles, EuiSpacer } from '@elastic/eui';
+import { getFilteredGroups } from '../../utils/get_filtered_groups';
+import { DocumentationMainContent, DocumentationNavigation } from '../shared';
+import type { LanguageDocumentationSections } from '../../types';
+
+interface DocumentationInlineProps {
+  sections?: LanguageDocumentationSections;
+  searchInDescription?: boolean;
+}
+
+const MAX_HEIGHT = 250;
+
+function DocumentationInline({ sections, searchInDescription }: DocumentationInlineProps) {
+  const theme = useEuiTheme();
+  const scrollBarStyles = euiScrollBarStyles(theme);
+  const [selectedSection, setSelectedSection] = useState<string | undefined>();
+  const [searchText, setSearchText] = useState('');
+
+  const scrollTargets = useRef<Record<string, HTMLElement>>({});
+
+  const filteredGroups = useMemo(() => {
+    return getFilteredGroups(searchText, searchInDescription, sections, 1);
+  }, [sections, searchText, searchInDescription]);
+
+  const onNavigationChange = useCallback((selectedOptions) => {
+    setSelectedSection(selectedOptions.length ? selectedOptions[0].label : undefined);
+    if (selectedOptions.length) {
+      const scrollToElement = scrollTargets.current[selectedOptions[0].label];
+      scrollToElement.scrollIntoView();
+    }
+  }, []);
+
+  return (
+    <div
+      css={css`
+        padding: ${theme.euiTheme.size.base};
+        max-height: ${MAX_HEIGHT}px;
+        overflow-y: auto;
+        ${scrollBarStyles}
+      `}
+    >
+      <DocumentationNavigation
+        searchText={searchText}
+        setSearchText={setSearchText}
+        onNavigationChange={onNavigationChange}
+        filteredGroups={filteredGroups}
+        selectedSection={selectedSection}
+      />
+      <EuiSpacer size="s" />
+      <DocumentationMainContent
+        searchText={searchText}
+        scrollTargets={scrollTargets}
+        filteredGroups={filteredGroups}
+        sections={sections}
+      />
+    </div>
+  );
+}
+
+export const LanguageDocumentationInline = React.memo(DocumentationInline);

packages/kbn-language-documentation-popover/src/components/documentation_popover.tsx → packages/kbn-language-documentation-popover/src/components/as_popover/index.tsx

@@ -16,10 +16,8 @@ import {
   EuiButtonIconProps,
   EuiOutsideClickDetector,
 } from '@elastic/eui';
-import {
-  type LanguageDocumentationSections,
-  LanguageDocumentationPopoverContent,
-} from './documentation_content';
+import { LanguageDocumentationPopoverContent } from './popover_content';
+import type { LanguageDocumentationSections } from '../../types';
 
 interface DocumentationPopoverProps {
   language: string;

packages/kbn-language-documentation-popover/src/components/documentation_content.test.tsx → packages/kbn-language-documentation-popover/src/components/as_popover/popover_content.test.tsx

@@ -11,7 +11,7 @@ import React from 'react';
 import { mountWithIntl, findTestSubject } from '@kbn/test-jest-helpers';
 import { act } from 'react-dom/test-utils';
 import { Markdown } from '@kbn/shared-ux-markdown';
-import { LanguageDocumentationPopoverContent } from './documentation_content';
+import { LanguageDocumentationPopoverContent } from './popover_content';
 
 describe('###Documentation popover content', () => {
   const sections = {