Product Collection: Implement Preview Mode

[imanish003]

Changes proposed in this Pull Request:

Introduction

We are working on Preview mode for Product Collection block. Here's the scoop: some collections might look a bit different in the Editor than they do on the Frontend. Take the Recently Viewed collection as an example; its appearance in the Editor might not exactly mirror its Frontend display. To bridge this gap, we're introducing a label, which you can peek at in the screenshot below.

Tooltip
A message will be shown when the merchant hovers over the "preview" label in Editor as shown in screenshot below:

What is implemented in this PR?

For all Product Collection blocks that inherit query from the template, we are showing a preview message in the editor if the block is in a generic archive template, i.e.

• Products by category
• Products by tag
• Products by attribute

Here is what it should look like:

Technical details

I have abstracted logic to register a new collection into registerProductCollection. This function will allow us to register a new collection. For now, it's not public, but in follow-up PR, we plan to make it public (i.e., usable by 3PDs). For now, this function accepts all the arguments which are accepted by Block Variation. Also, registerProductCollection accepts an preview argument. Here are some examples of how preview can be used:

Example 1:
As you can see in the example below, you can pass preview object to registerProductCollection to set the initial state of the preview mode.

• isPreview is a boolean that will determine if the collection is in preview mode.
• previewMessage is a string that will be shown as a tooltip when the merchant hovers over the preview label in the Editor.

registerProductCollection(
	...,
	preview: {
		initialPreviewState: {
			isPreview: true,
			previewMessage: 'On sale Collection Preview',
		},
	},
)

Example 2:

In the example below, you can see how you can use setPreviewState to set the preview state. In setPreviewState, you can access attributes and location in the preview state, utilize async operations, and implement a cleanup function as a return value.

/**
 * Example:
 * - How to access attributes and location in the preview state?
 * - How to use async operations?
 * - How to use cleanup function as a return value?
 */
registerProductCollection(
	...,
	preview: {
		setPreviewState: ( {
			setState,
			attributes: currentAttributes,
			location,
		}: SetPreviewStateArgs ) => {
			// setPreviewState has access to the current attributes and location.
			console.log( 'setPreviewState' );
			console.log( currentAttributes, location );

			const timeoutID = setTimeout( () => {
				setState( {
					isPreview: false,
					previewMessage: '',
				} );
			}, 5000 );

			return () => clearTimeout( timeoutID );
		},
		initialPreviewState: {
			isPreview: true,
			previewMessage: 'This is in preview mode',
		},
	}
)

When setPreviewState will be triggered?

1. On initial load: When either Collection is added or editor page is refreshed, then setPreviewState will be triggered.
2. When block is moved: IMO it's needed because location of block might change when block is moved. For example, if it's moved to Single Products block then location type will become:

{
  type: "product",
  sourceData: {
    productId: 2777
  }
};

What isn't part of this PR?

Preview argument validation

In followup PR, we will add validation for preview argument passed in registerProductCollection function. For now, this is still a private API, but before making it public, we will need to add some validation, as incorrect data is possible.

Required context

As mentioned by Karol in #45703 (review), collection should be able to specify requiredContext or requiredLocation. In case it's not satisfied we should not even call setPreviewState and set the preview ourselves.
For now, there is no way for collection to specify require context but when it will be implemented, we will need to handle this case, i.e. we will need to show preview label when required context isn't satisfied.

Expose registerProductCollection for 3PDs

This will require a bit more discussion about what is the best way to expose it. Therefore, I will be implementing it in a follow-up PR.

Closes #46368

How to test the changes in this Pull Request:

Using the WooCommerce Testing Instructions Guide, include your detailed testing instructions:

1. Open Editor & Go to any of the following templates
   1. Products by category
   2. Products by tag
   3. Products by attribute
2. Add Product Collection block & choose "Product Catalog" collection
3. Verify the "Preview" label is showing at top-right corner of Product Collection block as shown in screenshot below:

4. Also, verify that hovering over "preview" label shows following tooltip: "Actual products will vary depending on the page being viewed."
   

5. Save and go to frontend. Verify that "preview" label isn't visible on frontend. It should be only visible on Editor side. Also, verify that everything is working as expected in Product Collection block and there are no errors.

   • For example, if you modify the "Product by Category" template, then you can check the frontend URLs like "/product-category/clothing/accessories/"

6. Now, Toggle "Sync with current query" to off using inspector control. Verify that:

   • If toggle is off, then preview label should not be visible.
   • If toggle is on, then preview label should be visible.

Changelog entry

• Automatically create a changelog entry from the details below.

Significance

• Patch
• Minor
• Major

Type

• Fix - Fixes an existing bug
• Add - Adds functionality
• Update - Update existing functionality
• Dev - Development related task
• Tweak - A minor adjustment to the codebase
• Performance - Address performance issues
• Enhancement - Improvement to existing functionality

Message

Product Collection: Add preview mode on Editor side

Comment

[imanish003]

Hi @samueljseay @xristos3490 👋

I have made following requested changes:

• Added E2E tests
• I changed the preview label position as suggested by @jarekmorawski in p1714028491661149/1714028083.983709-slack-C05UMTA7W0P.
• Now, the Preview label will only be visible if either the Product Collection block is selected or any of its inner blocks are selected to avoid cluttering the UI.
• Added __private prefix with Attribute name to make it clear that this attribute is for internal use only. As I mentioned in this comment above, I will come back to this.
• Moved styles to a class
• Some Typescript types improvements
• Other minor improvements as requests in feedback.

PR is now ready for review again. Can you please review it again? Please let me know in case I missed something. Thank you for the helpful feedback so far 🙂

[samueljseay]

I don't have much else to add, it's looking great. A few suggestions but they're mostly minor and won't block approval from me.

[samueljseay]

If it helps, I tried to use ComponentType from `'@wordpress/element' as we aren't supposed to import directly from "react", right?

as i mentioned in another comment, you absolutely can import types from react. types are erased at compilation. For some reason wp element is erasing the generics of the ComponentType so the fix here would indeed be to import from react (I tested and it works well).

[github-actions]

Test using WordPress Playground

The changes in this pull request can be previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Test this pull request with WordPress Playground.

Note that this URL is valid for 30 days from when this comment was last updated. You can update it by closing/reopening the PR or pushing a new commit.

[xristos3490]

Overall looking good, @imanish003! I couldn't test this in a 3PD environment of course but it seems to be checking all the boxes! Fingers crossed, things should work as expected!

Left some comments before approving!

[xristos3490]

Left some comments before giving the final approval.

[xristos3490]

Works as expected! Nice work, @imanish003!