-
Notifications
You must be signed in to change notification settings - Fork 8.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[ES|QL] Enhances the inline documentation experience (#192156)
## Summary Closes #166907 This PR: 1. Changes the inline docs implementation to a flyout for Discover <img width="1256" alt="image" src="https://github.com/user-attachments/assets/3665c73a-82d5-49b9-88c3-e129eda63885"> 2. Adds the flyout to open from the help menu and removes it from the editor footer 3. For the inline editing changes the docs to be rendered as a component inside the editor (exactly as the history component) Note: The documentation in the inline editing has limited space (same problem has the history component). I need to sync with Ryan to see what we can do, I am exploring some ideas in follow up PRs <img width="647" alt="image" src="https://github.com/user-attachments/assets/2fa9fcc3-2a07-4bea-b675-5ae6578696d3"> 4. Moves the esql docs to the language package and the script associated to this ### Follow up - The language package should be renamed as the `popover` makes sense only for the formula implementation now. I will do it after this PR gets merged - See how we can give more space to the docs / history container when in inline mode ### Note The async bundle got increased as we want the ES|QL docs in unified search too. It wont be a problem as is loaded asynchronously. ### Checklist - [ ] Any text added follows [EUI's writing guidelines](https://elastic.github.io/eui/#/guidelines/writing), uses sentence case text and includes [i18n support](https://github.com/elastic/kibana/blob/main/packages/kbn-i18n/README.md) - [ ] [Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html) was added for features that require explanation or tutorials - [ ] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios - [ ] Any UI touched in this PR is usable by keyboard only (learn more about [keyboard accessibility](https://webaim.org/techniques/keyboard/)) - [ ] Any UI touched in this PR does not create any new axe failures (run axe in browser: [FF](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/), [Chrome](https://chrome.google.com/webstore/detail/axe-web-accessibility-tes/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US)) - [ ] This renders correctly on smaller devices using a responsive layout. (You can test this [in your browser](https://www.browserstack.com/guide/responsive-testing-on-local-server)) - [ ] This was checked for [cross-browser compatibility](https://www.elastic.co/support/matrix#matrix_browsers) --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Ryan Keairns <contactryank@gmail.com> Co-authored-by: Drew Tate <andrew.tate@elastic.co> Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
- Loading branch information
5 people
committed
Sep 19, 2024
1 parent
f785002
commit dfbd7de
Showing
41 changed files
with
2,199 additions
and
1,850 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
11 changes: 11 additions & 0 deletions
11
packages/kbn-language-documentation-popover/setup_tests.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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'; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
95 changes: 95 additions & 0 deletions
95
packages/kbn-language-documentation-popover/src/components/as_flyout/index.test.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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(); | ||
| }); | ||
| }); | ||
| }); |
117 changes: 117 additions & 0 deletions
117
packages/kbn-language-documentation-popover/src/components/as_flyout/index.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| /* | ||
| * 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, | ||
| EuiTitle, | ||
| EuiSpacer, | ||
| } from '@elastic/eui'; | ||
| import { i18n } from '@kbn/i18n'; | ||
| 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} | ||
| paddingSize="m" | ||
| > | ||
| <EuiFlyoutHeader hasBorder> | ||
| <EuiTitle size="s"> | ||
| <h3> | ||
| {i18n.translate('languageDocumentationPopover.documentationFlyoutTitle', { | ||
| defaultMessage: 'ES|QL quick reference', | ||
| })} | ||
| </h3> | ||
| </EuiTitle> | ||
| <EuiSpacer size="m" /> | ||
| <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); |
Oops, something went wrong.