[Discover] Add a tour for Document Explorer

src/plugins/discover/common/index.ts

@@ -6,6 +6,7 @@
  * Side Public License, v 1.
  */
 
+export const PLUGIN_ID = 'discover';
 export const APP_ICON = 'discoverApp';
 export const DEFAULT_COLUMNS_SETTING = 'defaultColumns';
 export const SAMPLE_SIZE_SETTING = 'discover:sampleSize';

src/plugins/discover/public/application/main/components/document_explorer_callout/document_explorer_update_callout.test.tsx

@@ -7,19 +7,20 @@
  */
 
 import React from 'react';
-import { mountWithIntl } from '@kbn/test-jest-helpers';
+import { mountWithIntl, findTestSubject } from '@kbn/test-jest-helpers';
 import { KibanaContextProvider } from '@kbn/kibana-react-plugin/public';
 import {
   CALLOUT_STATE_KEY,
   DocumentExplorerUpdateCallout,
 } from './document_explorer_update_callout';
 import { LocalStorageMock } from '../../../../__mocks__/local_storage_mock';
 import { DiscoverServices } from '../../../../build_services';
+import { discoverServiceMock } from '../../../../__mocks__/services';
+import { DiscoverTourProvider } from '../../../../components/discover_tour';
 
 const defaultServices = {
-  addBasePath: () => '',
-  docLinks: { links: { discover: { documentExplorer: '' } } },
-  capabilities: { advancedSettings: { save: true } },
+  ...discoverServiceMock,
+  capabilities: { ...discoverServiceMock.capabilities, advancedSettings: { save: true } },
   storage: new LocalStorageMock({ [CALLOUT_STATE_KEY]: false }),
 } as unknown as DiscoverServices;
 
@@ -57,4 +58,18 @@ describe('Document Explorer Update callout', () => {
 
     expect(result.find('.dscDocumentExplorerCallout').exists()).toBeFalsy();
   });
+
+  it('should start a tour when the button is clicked', () => {
+    const result = mountWithIntl(
+      <KibanaContextProvider services={defaultServices}>
+        <DiscoverTourProvider>
+          <DocumentExplorerUpdateCallout />
+        </DiscoverTourProvider>
+      </KibanaContextProvider>
+    );
+
+    expect(result.find({ isStepOpen: true })).toHaveLength(0);
+    findTestSubject(result, 'discoverTakeTourButton').simulate('click');
+    expect(result.find({ isStepOpen: true })).toHaveLength(1);
+  });
 });

src/plugins/discover/public/application/main/components/document_explorer_callout/document_explorer_update_callout.tsx

@@ -6,22 +6,21 @@
  * Side Public License, v 1.
  */
 
-import React, { useCallback, useMemo, useState } from 'react';
+import React, { useCallback, useState } from 'react';
 import './document_explorer_callout.scss';
 import { i18n } from '@kbn/i18n';
 import { FormattedMessage } from '@kbn/i18n-react';
 import {
   EuiButton,
+  EuiButtonEmpty,
   EuiButtonIcon,
   EuiCallOut,
   EuiFlexGroup,
   EuiFlexItem,
-  EuiLink,
-  useEuiTheme,
 } from '@elastic/eui';
-import { css } from '@emotion/react';
 import { Storage } from '@kbn/kibana-utils-plugin/public';
 import { useDiscoverServices } from '../../../../utils/use_discover_services';
+import { useDiscoverTourContext } from '../../../../components/discover_tour';
 
 export const CALLOUT_STATE_KEY = 'discover:docExplorerUpdateCalloutClosed';
 
@@ -37,22 +36,19 @@ const updateStoredCalloutState = (newState: boolean, storage: Storage) => {
  * The callout that's displayed when Document explorer is enabled
  */
 export const DocumentExplorerUpdateCallout = () => {
-  const { euiTheme } = useEuiTheme();
-  const { storage, capabilities, docLinks } = useDiscoverServices();
+  const { storage, capabilities } = useDiscoverServices();
   const [calloutClosed, setCalloutClosed] = useState(getStoredCalloutState(storage));
-
-  const semiBoldStyle = useMemo(
-    () => css`
-      font-weight: ${euiTheme.font.weight.semiBold};
-    `,
-    [euiTheme.font.weight.semiBold]
-  );
+  const onStartTour = useDiscoverTourContext().onStartTour;
 
   const onCloseCallout = useCallback(() => {
     updateStoredCalloutState(true, storage);
     setCalloutClosed(true);
   }, [storage]);
 
+  const onTakeTour = useCallback(() => {
+    onStartTour();
+  }, [onStartTour]);
+
   if (calloutClosed || !capabilities.advancedSettings.save) {
     return null;
   }
@@ -67,44 +63,37 @@ export const DocumentExplorerUpdateCallout = () => {
     >
       <p>
         <FormattedMessage
-          id="discover.docExplorerUpdateCallout.bodyMessage"
-          defaultMessage="Perform multi-column sorting, resize columns, set row height, and view data in fullscreen with the {documentExplorer}.
-          Learn more about the structure of your data with {fieldStatistics}."
-          values={{
-            fieldStatistics: (
-              <EuiLink href={docLinks.links.discover.fieldStatistics} target="_blank">
-                <span css={semiBoldStyle}>
-                  <FormattedMessage
-                    id="discover.docExplorerUpdateCallout.fieldStatistics"
-                    defaultMessage="field statistics"
-                  />
-                </span>
-              </EuiLink>
-            ),
-            documentExplorer: (
-              <EuiLink href={docLinks.links.discover.documentExplorer} target="_blank">
-                <span css={semiBoldStyle}>
-                  <FormattedMessage
-                    id="discover.docExplorerUpdateCallout.documentExplorer"
-                    defaultMessage="new document table"
-                  />
-                </span>
-              </EuiLink>
-            ),
-          }}
+          id="discover.docExplorerUpdateCallout.description"
+          defaultMessage="Add relevant fields, reorder and sort columns, resize rows, and more in the document table."
         />
       </p>
-      <EuiButton
-        data-test-subj="document-explorer-update-callout-dismiss-button"
-        iconType="check"
-        size="s"
-        onClick={onCloseCallout}
+      <EuiFlexGroup
+        justifyContent="flexStart"
+        alignItems="center"
+        responsive={false}
+        gutterSize="s"
       >
-        <FormattedMessage
-          id="discover.docExplorerUpdateCallout.dismissButtonLabel"
-          defaultMessage="Got it"
-        />
-      </EuiButton>
+        <EuiFlexItem grow={false}>
+          <EuiButton size="s" onClick={onTakeTour} data-test-subj="discoverTakeTourButton">
+            <FormattedMessage
+              id="discover.docExplorerUpdateCallout.takeTourButtonLabel"
+              defaultMessage="Take the tour"
+            />
+          </EuiButton>
+        </EuiFlexItem>
+        <EuiFlexItem grow={false}>
+          <EuiButtonEmpty
+            size="xs"
+            onClick={onCloseCallout}
+            data-test-subj="document-explorer-update-callout-dismiss-button"
+          >
+            <FormattedMessage
+              id="discover.docExplorerUpdateCallout.dismissButtonLabel"
+              defaultMessage="Dismiss"
+            />
+          </EuiButtonEmpty>
+        </EuiFlexItem>
+      </EuiFlexGroup>
     </EuiCallOut>
   );
 };
@@ -114,8 +103,8 @@ function CalloutTitle({ onCloseCallout }: { onCloseCallout: () => void }) {
     <EuiFlexGroup justifyContent="spaceBetween" gutterSize="none" responsive={false}>
       <EuiFlexItem grow={false}>
         <FormattedMessage
-          id="discover.docExplorerUpdateCallout.headerMessage"
-          defaultMessage="Exploring your data just got better"
+          id="discover.docExplorerUpdateCallout.title"
+          defaultMessage="Get the best look at your search results"
         />
       </EuiFlexItem>
       <EuiFlexItem grow={false}>

src/plugins/discover/public/application/main/components/layout/discover_documents.tsx

@@ -35,6 +35,7 @@ import { SortPairArr } from '../../../../components/doc_table/lib/get_sort';
 import { ElasticSearchHit } from '../../../../types';
 import { DocumentExplorerCallout } from '../document_explorer_callout';
 import { DocumentExplorerUpdateCallout } from '../document_explorer_callout/document_explorer_update_callout';
+import { DiscoverTourProvider } from '../../../../components/discover_tour';
 
 const DocTableInfiniteMemoized = React.memo(DocTableInfinite);
 const DataGridMemoized = React.memo(DiscoverGrid);
@@ -157,7 +158,9 @@ function DiscoverDocumentsComponent({
       )}
       {!isLegacy && (
         <>
-          <DocumentExplorerUpdateCallout />
+          <DiscoverTourProvider>
+            <DocumentExplorerUpdateCallout />
+          </DiscoverTourProvider>
           <div className="dscDiscoverGrid">
             <DataGridMemoized
               ariaLabelledBy="documentsAriaLabel"

src/plugins/discover/public/application/main/components/sidebar/discover_sidebar.tsx

@@ -39,6 +39,7 @@ import { FieldFilterState, getDefaultFieldFilter, setFieldFilterProp } from './l
 import { getIndexPatternFieldList } from './lib/get_index_pattern_field_list';
 import { DiscoverSidebarResponsiveProps } from './discover_sidebar_responsive';
 import { VIEW_MODE } from '../../../../components/view_mode_toggle';
+import { DISCOVER_TOUR_STEP_ANCHOR_IDS } from '../../../../components/discover_tour';
 import { ElasticSearchHit } from '../../../../types';
 
 /**
@@ -412,7 +413,7 @@ export function DiscoverSidebarComponent({
                   initialIsOpen={true}
                   buttonContent={
                     <EuiText size="xs" id="available_fields">
-                      <strong>
+                      <strong id={DISCOVER_TOUR_STEP_ANCHOR_IDS.addFields}>
                         <FormattedMessage
                           id="discover.fieldChooser.filter.availableFieldsTitle"
                           defaultMessage="Available fields"

src/plugins/discover/public/application/main/components/sidebar/discover_sidebar_responsive.tsx

@@ -32,6 +32,7 @@ import { AvailableFields$, DataDocuments$ } from '../../utils/use_saved_search';
 import { calcFieldCounts } from '../../utils/calc_field_counts';
 import { VIEW_MODE } from '../../../../components/view_mode_toggle';
 import { FetchStatus } from '../../../types';
+import { DISCOVER_TOUR_STEP_ANCHOR_IDS } from '../../../../components/discover_tour';
 
 export interface DiscoverSidebarResponsiveProps {
   /**
@@ -276,7 +277,10 @@ export function DiscoverSidebarResponsive(props: DiscoverSidebarResponsiveProps)
       <EuiShowFor sizes={['xs', 's']}>
         <div className="dscSidebar__mobile">
           <EuiButton
-            contentProps={{ className: 'dscSidebar__mobileButton' }}
+            contentProps={{
+              className: 'dscSidebar__mobileButton',
+              id: DISCOVER_TOUR_STEP_ANCHOR_IDS.addFields,
+            }}
             fullWidth
             onClick={() => setIsFlyoutVisible(true)}
           >

src/plugins/discover/public/components/discover_grid/discover_grid_expand_button.tsx

@@ -12,6 +12,8 @@ import { euiLightVars as themeLight, euiDarkVars as themeDark } from '@kbn/ui-th
 import { i18n } from '@kbn/i18n';
 import { DiscoverGridContext } from './discover_grid_context';
 import { EsHitRecord } from '../../application/types';
+import { DISCOVER_TOUR_STEP_ANCHOR_IDS } from '../discover_tour';
+
 /**
  * Button to expand a given row
  */
@@ -42,6 +44,7 @@ export const ExpandButton = ({ rowIndex, setCellProps }: EuiDataGridCellValueEle
   return (
     <EuiToolTip content={buttonLabel} delay="long">
       <EuiButtonIcon
+        id={rowIndex === 0 ? DISCOVER_TOUR_STEP_ANCHOR_IDS.expandDocument : undefined}
         size="xs"
         iconSize="s"
         aria-label={buttonLabel}

src/plugins/discover/public/components/discover_tour/discover_tour.test.tsx

@@ -0,0 +1,63 @@
+/*
+ * 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 React from 'react';
+import { EuiTourStep, EuiButton } from '@elastic/eui';
+import { mountWithIntl } from '@kbn/test-jest-helpers';
+import { KibanaContextProvider } from '@kbn/kibana-react-plugin/public';
+import { discoverServiceMock } from '../../__mocks__/services';
+import { DiscoverTourProvider } from './discover_tour_provider';
+import { useDiscoverTourContext } from './discover_tour_context';
+import { DISCOVER_TOUR_STEP_ANCHORS } from './discover_tour_anchors';
+
+describe('Discover tour', () => {
+  const mountComponent = (innerContent?: JSX.Element) => {
+    return mountWithIntl(
+      <KibanaContextProvider services={discoverServiceMock}>
+        <DiscoverTourProvider>{innerContent}</DiscoverTourProvider>
+      </KibanaContextProvider>
+    );
+  };
+
+  it('should start successfully', () => {
+    const buttonSubjToTestStart = 'discoverTourButtonTestStart';
+    const InnerComponent = () => {
+      const tourContext = useDiscoverTourContext();
+
+      return (
+        <EuiButton onClick={tourContext.onStartTour} data-test-subj={buttonSubjToTestStart}>
+          {'Start the tour'}
+        </EuiButton>
+      );
+    };
+
+    const component = mountComponent(<InnerComponent />);
+    // all steps are hidden by default
+    expect(component.find(EuiTourStep)).toHaveLength(0);
+
+    // one step should become visible after the tour is triggered
+    component.find(`[data-test-subj="${buttonSubjToTestStart}"]`).at(0).simulate('click');
+
+    expect(component.find(EuiTourStep)).toHaveLength(5);
+    expect(
+      component.find({ anchor: DISCOVER_TOUR_STEP_ANCHORS.addFields, isStepOpen: true })
+    ).toHaveLength(1);
+    expect(
+      component.find({ anchor: DISCOVER_TOUR_STEP_ANCHORS.reorderColumns, isStepOpen: false })
+    ).toHaveLength(1);
+    expect(
+      component.find({ anchor: DISCOVER_TOUR_STEP_ANCHORS.sort, isStepOpen: false })
+    ).toHaveLength(1);
+    expect(
+      component.find({ anchor: DISCOVER_TOUR_STEP_ANCHORS.changeRowHeight, isStepOpen: false })
+    ).toHaveLength(1);
+    expect(
+      component.find({ anchor: DISCOVER_TOUR_STEP_ANCHORS.expandDocument, isStepOpen: false })
+    ).toHaveLength(1);
+  });
+});

src/plugins/discover/public/components/discover_tour/discover_tour_anchors.tsx

@@ -0,0 +1,22 @@
+/*
+ * 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 { htmlIdGenerator } from '@elastic/eui';
+
+export const DISCOVER_TOUR_STEP_ANCHOR_IDS = {
+  addFields: htmlIdGenerator('dsc-tour-step-add-fields')(),
+  expandDocument: htmlIdGenerator('dsc-tour-step-expand')(),
+};
+
+export const DISCOVER_TOUR_STEP_ANCHORS = {
+  addFields: `#${DISCOVER_TOUR_STEP_ANCHOR_IDS.addFields}`,
+  reorderColumns: '[data-test-subj="dataGridColumnSelectorButton"]',
+  sort: '[data-test-subj="dataGridColumnSortingButton"]',
+  changeRowHeight: '[data-test-subj="dataGridDisplaySelectorButton"]',
+  expandDocument: `#${DISCOVER_TOUR_STEP_ANCHOR_IDS.expandDocument}`,
+};

src/plugins/discover/public/components/discover_tour/discover_tour_context.ts

@@ -0,0 +1,25 @@
+/*
+ * 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';
+
+export interface DiscoverTourContextProps {
+  onStartTour: () => void;
+  onNextTourStep: () => void;
+  onFinishTour: () => void;
+}
+
+export const DiscoverTourContext = createContext<DiscoverTourContextProps>({
+  onStartTour: () => {},
+  onNextTourStep: () => {},
+  onFinishTour: () => {},
+});
+
+export const useDiscoverTourContext = () => {
+  return useContext(DiscoverTourContext);
+};