[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/package.json

@@ -5,5 +5,10 @@
   "private": true,
   "sideEffects": [
     "*.scss"
-  ]
+  ],
+  "scripts": {
+    "make:docs": "ts-node --transpileOnly scripts/generate_esql_docs.ts",
+    "postmake:docs": "yarn run lint:fix",
+    "lint:fix": "cd ../.. && node ./scripts/eslint --fix ./packages/kbn-text-based-editor/src/esql_documentation_sections.tsx"
+  }
 }

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,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", 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, waitFor } from '@testing-library/react';
+import { LanguageDocumentationFlyout } from '.';
+
+jest.mock('../../sections', () => {
+  const module = jest.requireActual('../../sections');
+  return {
+    ...module,
+    getESQLDocsSections: () => ({
+      groups: [
+        {
+          label: 'Section one',
+          description: 'Section 1 description',
+          items: [],
+        },
+        {
+          label: 'Section two',
+          items: [
+            {
+              label: 'Section two item 1',
+              description: 'Section two item 1 description',
+            },
+            {
+              label: 'Section two item 2',
+              description: 'Section two item 2 description',
+            },
+          ],
+        },
+        {
+          label: 'Section three',
+          items: [
+            {
+              label: 'Section three item 1',
+              description: 'Section three item 1 description',
+            },
+            {
+              label: 'Section three item 2',
+              description: 'Section three item 2 description',
+            },
+          ],
+        },
+      ],
+      initialSection: <span>Here is the initial section</span>,
+    }),
+  };
+});
+
+describe('###Documentation flyout component', () => {
+  const renderFlyout = (linkToDocumentation?: string) => {
+    return render(
+      <LanguageDocumentationFlyout
+        isHelpMenuOpen={true}
+        onHelpMenuVisibilityChange={jest.fn()}
+        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', async () => {
+    renderFlyout();
+    await waitFor(() => {
+      expect(screen.getByText('Section two')).toBeInTheDocument();
+      expect(screen.getByText('Section three')).toBeInTheDocument();
+    });
+  });
+
+  it('contains the correct section if user updates the search input', async () => {
+    renderFlyout();
+    const input = screen.getByTestId('language-documentation-navigation-search');
+    fireEvent.change(input, { target: { value: 'two' } });
+    await waitFor(() => {
+      expect(screen.getByText('Section two')).toBeInTheDocument();
+    });
+  });
+});

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

@@ -0,0 +1,100 @@
+/*
+ * 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 { getESQLDocsSections } from '../../sections';
+import type { LanguageDocumentationSections } from '../../types';
+
+interface DocumentationFlyoutProps {
+  isHelpMenuOpen: boolean;
+  onHelpMenuVisibilityChange: (status: boolean) => void;
+  searchInDescription?: boolean;
+  linkToDocumentation?: string;
+}
+
+function DocumentationFlyout({
+  searchInDescription,
+  linkToDocumentation,
+  isHelpMenuOpen,
+  onHelpMenuVisibilityChange,
+}: DocumentationFlyoutProps) {
+  const [documentationSections, setDocumentationSections] =
+    useState<LanguageDocumentationSections>();
+
+  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 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]);
+
+  useEffect(() => {
+    async function getDocumentation() {
+      const sections = await getESQLDocsSections();
+      setDocumentationSections(sections);
+    }
+    if (!documentationSections) {
+      getDocumentation();
+    }
+  }, [documentationSections]);
+
+  const filteredGroups = useMemo(() => {
+    return getFilteredGroups(searchText, searchInDescription, documentationSections, 1);
+  }, [documentationSections, searchText, searchInDescription]);
+
+  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={documentationSections}
+            />
+          </EuiFlyoutBody>
+        </EuiFlyout>
+      )}
+    </>
+  );
+}
+
+export const LanguageDocumentationFlyout = React.memo(DocumentationFlyout);

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

@@ -0,0 +1,97 @@
+/*
+ * 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, waitFor } from '@testing-library/react';
+import { Markdown } from '@kbn/shared-ux-markdown';
+import { LanguageDocumentationInline } from '.';
+
+const mockMarkDownDescription = () => (
+  <Markdown markdownContent="Section three item 1 blah blah blah" />
+);
+
+jest.mock('../../sections', () => {
+  const module = jest.requireActual('../../sections');
+  return {
+    ...module,
+    getESQLDocsSections: () => ({
+      groups: [
+        {
+          label: 'Section one',
+          description: 'Section 1 description',
+          items: [],
+        },
+        {
+          label: 'Section two',
+          items: [
+            {
+              label: 'Section two item 1',
+              description: 'Section two item 1 description',
+            },
+            {
+              label: 'Section two item 2',
+              description: 'Section two item 2 description',
+            },
+          ],
+        },
+        {
+          label: 'Section three',
+          items: [
+            {
+              label: 'Section three item 1',
+              description: mockMarkDownDescription(),
+            },
+            {
+              label: 'Section three item 2',
+              description: 'Section three item 2 description',
+            },
+          ],
+        },
+      ],
+      initialSection: <span>Here is the initial section</span>,
+    }),
+  };
+});
+
+describe('###Documentation flyout component', () => {
+  const renderInlineComponent = (searchInDescription = false) => {
+    return render(<LanguageDocumentationInline 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', async () => {
+    renderInlineComponent();
+    await waitFor(() => {
+      expect(screen.getByText('Section two')).toBeInTheDocument();
+      expect(screen.getByText('Section three')).toBeInTheDocument();
+    });
+  });
+
+  it('contains the correct section if user updates the search input', async () => {
+    renderInlineComponent();
+    const input = screen.getByTestId('language-documentation-navigation-search');
+    fireEvent.change(input, { target: { value: 'two' } });
+    await waitFor(() => {
+      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', async () => {
+    renderInlineComponent(true);
+    const input = screen.getByTestId('language-documentation-navigation-search');
+    fireEvent.change(input, { target: { value: 'blah' } });
+    await waitFor(() => {
+      expect(screen.getByText('Section three')).toBeInTheDocument();
+    });
+  });
+});