feat: add an AutocompleteWithSuggestions component for reusability

[dkoo]

All Submissions:

• Have you followed the Newspack Contributing guideline?
• Does your code follow the WordPress' coding standards and VIP Go coding standards?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Changes proposed in this Pull Request:

Adds a new component to the Newspack Components library, which is an extension of the AutocompleteTokenfield that also renders a list of suggestions to choose from. Takes functions as props for fetching suggestions, fetching saved tokens, and what to do when the AutocompleteTokenfield value changes.

This UI pattern is something that @thomasguillot has suggested for several features in progress, including this Author Profile block (not yet begun) and the Newspack Listings parent/child UI.

After this lands, we'll want to push a new version of the package to the NPM library.

How to test the changes in this Pull Request:

It's somewhat hard to test this as an NPM package, but you can test within the Newspack Plugin.

1. In some wizard view, import an AutocompleteWithSuggestions component from the newspack-components directory. Here's an example of some working code (may need to import additional dependencies such as apiFetch, addQueryArgs, decodeEntities, etc.):

<AutocompleteWithSuggestions
	label={ __( 'Search for a post', 'newspack' ) }
	help={ __(
		'Begin typing post title, click autocomplete result to select.',
		'newspack'
	) }
	fetchSavedPosts={ async postIDs => {
		const posts = await apiFetch( {
			path: addQueryArgs( '/wp/v2/posts', {
				per_page: 100,
				include: postIDs.join( ',' ),
				_fields: 'id,title',
			} ),
		} );

		return posts.map( post => ( {
			value: post.id,
			label: decodeEntities( post.title ) || __( '(no title)', 'newspack' ),
		} ) );
	} }
	fetchSuggestions={ async search => {
		const posts = await apiFetch( {
			path: addQueryArgs( '/wp/v2/posts', {
				search,
				per_page: 10,
				_fields: 'id,title',
			} ),
		} );

		// Format suggestions for FormTokenField display.
		const result = posts.reduce( ( acc, post ) => {
			acc.push( {
				value: post.id,
				label: decodeEntities( post.title.rendered ) || __( '(no title)', 'newspack' ),
			} );

			return acc;
		}, [] );
		return result;
	} }
	postType={ 'post' }
	postTypeLabel={ 'Post' }
	maxLength={ 1 }
	onChange={ _value => console.log( _value ) }
	selectedPost={ null }
/>

2. In the editor view, observe a component that looks like this, showing your 10 most recent posts in the suggestions list (as returned by the fetchSuggestions prop in the above example):

3. To test as an NPM package, you can fudge it by cding into the ./assets/components folder in this repo and running npm install && run prepublishOnly. Then, in another repo that already uses components from the newspack-components NPM package, copy the contents of the ./assets/components folder into your node_modules/newspack-components folder in the second repo. You can then import like import { AutocompleteWithSuggestions } from 'newspack-components' and test using the above example code in an editor page.

Other information:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes, as applicable?
• Have you successfully ran tests with your changes locally?

[dkoo]

Putting this in [WIP] mode because we want to extend this component further. A new feature for Newspack Listings needs this component to be able to handle multiple selections at once, like so:

In this use case, the list of suggestions looks and behaves more like a taxonomy select component. I believe it would be possible to extend the component to handle this as well if we provide certain props (perhaps multiSelect={ true } or something similar). If the required props are passed, then the component would render everything in the above screenshot that appears inside the modal, from the "4 listings selected" message and the optional data type selector (which could let you choose which post type or other data type to query), through the list of checkbox options to select multiple options.

EDIT: Let's move forward with this with the single-select functionality only, as other PRs are currently blocked by this.

[dkoo]

Actually, @thomasguillot—would you mind if we tackled the multiselect enhancement of this component in a separate PR (and a second, subsequent NPM package release)? I ask because the single-item component is going to be a dependency of this Campaigns feature in the works, and it'd be great to not block that feature in the meantime.

EDIT: opened an issue for the multiselect: #954

[thomasguillot]

Actually, @thomasguillot—would you mind if we tackled the multiselect enhancement of this component in a separate PR (and a second, subsequent NPM package release)? I ask because the single-item component is going to be a dependency of this Campaigns feature in the works, and it'd be great to not block that feature in the meantime.

Yep, no problem @dkoo

[adekbadek]

Found some issues:

1. After the component loads, but before typing anything into the input, selecting a post results in an empty item rendered:

2. After selecting a post and typing in characters to select another one, user has to first remove the previously-selected post to insert the post from search results.
3. The UI suggests that multiple items can be selected, while it's not true:

you can test within the Newspack Plugin

We do have a components demo page just for that purpose - I've added it there in 881d816

[adekbadek]

Nit: would've expected any new components we add to be functional (non-class-based) components, but besides developer experience that's not that important.

[dkoo]

Refactored to a functional component in 74b51b9.

[dkoo]

1. After the component loads, but before typing anything into the input, selecting a post results in an empty item rendered:

Ah, there was some weirdness in the interaction with the AutocompleteTokenfield. In 51bf59f I've extended that component to be able to take an array of tokens that include labels, and if the tokens include labels already, it just displays those instead of trying to fetch the labels.

2. After selecting a post and typing in characters to select another one, user has to first remove the previously-selected post to insert the post from search results.

Also fixed in 51bf59f. Now, you should be able to type in a search term, select a suggestion, and it will overwrite the existing value.

3. The UI suggests that multiple items can be selected, while it's not true

That's true, but for all use cases of the single-select version of this component, we immediately unmount the component and render something else as soon as a selected value exists, so it hasn't been an issue so far. I'm open to suggestions on how to display a selected state for this component when in single-select mode (maybe we separate the AutocompleteTokenfield from the selected tokens as in Thomas's multi-select design?).

We do have a components demo page just for that purpose - I've added it there in 881d816

Ah, I forgot about the demo page! Thanks for adding.

[adekbadek]

👌

[matticbot]

🎉 This PR is included in version 1.40.0-alpha.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[matticbot]

🎉 This PR is included in version 1.40.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀