Add Entity search to Unified Dashboard Header

Feature Description

The “Entity Search” should be added to the Unified Dashboard Header, implemented in #4048.

Not expanded:

Expanded:

Expanded with search results:

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• These features should all be implemented behind the unifiedDashboard feature flag.
  • The Entity Search should normally appear “not expanded” (see above). This should be covered by #4048.
  • The Entity Search “URL Search”/magnifying glass icon button should show the search input when clicked—this is also covered in #4048, but highlighting it here.
• A new component for the Entity Search Input can be created in assets/js/components/EntitySearchInput.
• The Entity Search Input implemented in the header should behave similarly to the existing URLSearchWidget’s PostSearcherAutoSuggest—that component can likely serve as the basis for this component. Key difference between that component and this new one are:
  • Styling as per the Figma files for both desktop and mobile views:
    • The desktop Figma file is here: https://www.figma.com/file/kKYqiUL7Fj3yAF8HHBRUhz/Custom-Dashboard?node-id=1944%3A17087 (under the “Single Search: Full frames” section).
    • The mobile versions are available here: https://www.figma.com/file/VILRieNSLg2DOVyEgFBkXe/[MVP]-Generic-Dashboard?node-id=382%3A1699
    • There are no dedicated tablet styles, so the mobile styles should be used for tablet sizes, essentially until all header content can fit alongside the input (as seen in the Desktop styles).
  • A “Loading” state should be added to this component featuring preview blocks, instead of the current behaviour when shows “No results” when first searching, and then later shows the previous results while searching. It’s clear that whatever the past results were are being shown in the search results; they should be cleared when the input changes in this new widget and “No results” should only be shown once the result is complete and empty. Essentially, where it currently says “No results” in this screencast, should be preview/loading lines instead.
  • There should be no “View data” submit button like in the URLSearchWidget. Instead, clicking on an item in the search results should navigate to the Entity Dashboard immediately.
    • Before this navigation occurs, the GA event open_urldetails (currently also exists in the widget) should be triggered. The event category for this new event should be “${viewContext}_headerbar” (using the current view context for the viewContext placeholder). The code to create this event would be:

const viewContext = useContext( ViewContextContext );

trackEvent( `${ viewContext }_headerbar`, 'open_urldetails' );

Implementation Brief

• Using assets/js/components/PostSearcherAutoSuggest.js,
  • Add 3 new props:
    • placeholder: empty string by default, used to display placeholder text for the input.
    • setIsLoading: optional function. This should be provided from the parent component to set a loading flag.
    • onKeyDown: optional function for keyboard events for the input.
  • In the useEffect hook which calls the API passing on debouncedValue, call setIsLoading if defined, with true. When we have a response, then set setIsLoading to false.
  • Using useEffect, check if searchTerm is empty to clear the results, by setting setResults to []. This is to clear previous search results when the user starts typing a new term.
  • Add placeholder and onKeyDown props to the ComboboxInput, and calling the namesake props if they are defined.
  • Using the useFeature hook, passing unifiedDashboard as parameter, display ComboboxOption rendering noResultsMessage only if they flag is not enabled. This means that current functionality will remain the same, but for the unified dashboard, it will not be displayed. Instead the loading state will be displayed in the parent component.
• Create assets/js/components/EntitySearchInput.js which exports the EntitySearchInput functional component.
  • EntitySearchInput uses most of the code from assets/js/googlesitekit/widgets/components/URLSearchWidget.js with the following changes:
    • Remove the Widget component, Title or URL label and all mdc-layout-* markup.
    • Primarily the PostSearcherAutoSuggest and Button will be used.
    • The class name for the main parent container should be googlesitekit-entity-search instead of googlesitekit-post-searcher.
  • Add 2 new state variables:
    • isOpen: boolean with false as default value.
    • isLoading: boolean with false as default value.
  • Using the useEffect hook, with match as dependency, check if there’s a permalink to navigate the user to the details URL and track the necessary event. It’s the same logic used in the onClick function.
  • For the tracking, refer to the AC for the new event category to be used.
  • Update the onClick callback function to toggle isOpen.
  • Update the Button component used:
    • Add the trailingIcon prop to render the appropriate icon using the following logic:
      • If isOpen is true, display the close icon. Refer to the mobile designs in Figma which contains the close icon, compared to the desktop one where the incorrect icon is displayed when the search is in the expanded state.
      • If isOpen is false, then display the search icon.
      • The icon SVGs should be placed in assets/svg/.
    • The label should be URL Search. The latter should be visible only when isOpen is true, meaning when the input is displayed, only the icon is displayed and the label is hidden.
  • Update PostSearcherAutoSuggest to:
    • add the placeholder prop, passing Enter title or URL… as value.
    • set the setCanSubmit to an anonymous function which does nothing.
    • add the setIsLoading prop, passing the function to change the isLoading state variable.
    • update the id prop to entity-urlsearch-autocomplete.
    • add the onKeyDown prop which the callback function will check if the ESCAPE key (imported from @wordpress/keycodes) has been pressed and isOpen is true to set isOpen to false.
  • PostSearcherAutoSuggest should be visible only when isLoading is false.
  • If isLoading is true, then render the ProgressBar component, with small and compress as props within the googlesitekit-entity-search container.
  • Using the useRef hook, attach a ref to the googlesitekit-entity-search container.
  • Using the useEffect hook, listen when isOpen changes. If isOpen is true, set the focus to the input text, else set the focus to the button. This means when the user clicks on button to display the input text, the focus is already set on the input for the user to start typing.
  • The googlesitekit-entity-search--is-open class name is added to the parent container rendering the markup when isOpen is true.
• Create assets/js/components/EntitySearchInput.stories.js which contains the story for EntitySearchInput.
• Create assets/sass/components/entity-search/_googlesitekit-entity-search.scss which will contain the styles for EntitySearchInput as per the designs in Figma.
  • When the search is in expanded state, i.e isOpen is true and thus having the googlesitekit-entity-search--is-open class name, set the button to use position: absolute so that the button is now displayed within the input.
  • The ProgressBar component should be absolutely positioned within the input text, below the close icon, having the same width as the icon. Refer to this comment for an example: https://github.com/google/site-kit-wp/issues/4049#issuecomment-935725206

UPDATE: when working on the new entity search component, add the event tracking defined in for the URLSearchWidget component.

Test Coverage

• No new tests to be added.

QA Brief

• The Entity Search component in the Unified Dashboard should look and behave as per AC/IB.
• Should work on all screen sizes.
• Some design elements are incorrect in the Screenshot/Figma, see discussion below.
  • Desktop View shows search icon instead of close icon when search is expended/open.
  • See comment for the loaders’ appearance hint (not available on Figma).
• Check for Keyboard navigation that was added in the Code Review Phase.
  • Press ESC to close the expended search.
  • Press Up / Down to to select result from the list. Should have visual feedback.
    • Pressing Enter should navigate to the selected entity page.
  • Pressing Enter when the search term is a (case insensitive) match should result in navigating to the entity page. If it’s not ma match, pressing Enter should do nothing.
• The appropriate tracking even should be sent to GA on navigating to an entity page. (Use Google Analytics Debugger to verify this).

Changelog entry

• Add Entity search to Unified Dashboard Header

[felixarntz]

@wpdarren Creating a new issue to review the loading indicator placement sounds good to me. Let’s focus on your QA feedback points 1.-3. in this issue here as @tofumatt mentioned.

[tofumatt]

I definitely prefer the subtle loading indicator (option 1), especially for mobile screens where the autocomplete will really dominate the whole screen. I think it’s visible enough and it’s fine that it’s subtle. Let’s go with that option where it’s below the icon, I think that’s really slick. 👍🏻