New block: Favorite button

[ryelle]

The favorite button is used across the pattern, theme, and plugin directories. This PR combines the Favorite block from the Theme Directory & Pattern Directory to create a shared component that can be used across all 3 sites.

See #617

To solve the issue of each directory having their own favoriting method, this block adds a simple API endpoint to create/delete, which calls callbacks that the child themes can set up to handle the favorite process. If they're not set up, the API errors, but doesn't do anything visually. The callbacks receive the current post ID & request object, and can return true (success), a WP_Error (failure), or the new count of favorites (also a success).

This uses the same filter process as our other blocks (Query Filters, Ratings, etc) to set up configuration, including the callbacks. Child themes should filter wporg_favorite_button_settings, and return:

Type	Name	Description
callable	add_callback	Callback function to handle adding the current item to a user's favorites. The function will be passed the post ID and request object. It should return a WP_Error, true, or the updated count of favorite items.
callable	delete_callback	Callback function to handle removing the current item from a user's favorites. Same arguments and return value as the add_callback.
int	count	Number of times this item has been favorited.
bool	is_favorite	Check if the current item is favorited.

The count can be omitted if showCount is not used.

Attributes

• showCount, default false
  Controls whether the favorite count is visible. If this is used, the callback should return the favorite count, and settings should include count.
• variant
  The block has two variants, default (outlined button, on single patterns & themes) and small (no outline, small padding, on patterns grid).

See https://github.com/WordPress/wporg-theme-directory/compare/try/mu-plugins-favorite-button, https://github.com/WordPress/pattern-directory/compare/try/mu-plugins-favorite-button for examples in use.

Screenshots

Themes (no visual changes)

Before	After

Patterns (keeping the count)

Before	After

To test:

It's probably easiest to test with one of the other repos, I've set up the new block in themes and patterns in the following branches:

• Remove the Favorite API & block, use shared block wporg-theme-directory#148
• Remove favorite button block, use shared block pattern-directory#697

There are site-specific test instructions in the above PRs ^

[jasmussen]

Looks good, and is, I believe, where consensus arrived. 👍 👍

[adamwoodnz]

Will $result include any more info that might be useful to a developer?

[ryelle]

If $result is a WP_Error (maybe-useful error info), it's returned as-is in the conditional above. Really, the only reason anyone would reach this code is if the callbacks aren't implemented… which is probably a good error message for devs. I'll update it 🙂

[ryelle]

Updated error messaging: 0ebb8f2

[adamwoodnz]

Do we display anything if the user is logged out? I think I get the state this is aimed at, but I wonder if we should bail early if there is no user_id

[ryelle]

If the block displays favorite count, it should appear regardless of login state (there's code below to switch between a button & span wrapper, if the user is logged in). If the block is not showing the favorite count, it should be hidden for non-logged-in users, because it would just be a heart icon.

The idea is to still display the favorite count, even if the user can't interact with it.

I can remove the variant detection though, that was leftover from before the variant + count display were split out.

[ryelle]

Simplified condition slightly by removing the variant check: 2dcb8ee

[adamwoodnz]

For me the variants are more obvious as

Suggested change

	"enum": [ "default", "small" ],
	"enum": [ "default", "no-outline" ],

[ryelle]

It does also use a smaller padding, and is designed for "small" spaces, so I would still prefer small. Along the lines of the is-small helper class for buttons.

[adamwoodnz]

Use logic in render to switch this instead, to reduce DOM?

[ryelle]

I've switched this to use the interactivity API + a binding on hidden, which simplifies the CSS at least. Since the JS doesn't re-render, just update, both icons need to be on the page to switch between. ad75039

[adamwoodnz]

Looking good! Tested on Pattern directory and appears to work, although my existing count data (from repo setup) got cleared, not sure why:

Kapture.2024-07-05.at.10.54.19.mp4

A few comments inline.

[StevenDufresne]

Looking at @adamwoodnz's video, that button state flashes black. If that's the case, can we prevent that?

[ryelle]

that button state flashes black. If that's the case, can we prevent that?

That's the active state, it was designed that way for all buttons. Here are two other places this happens (the first two I happened to grab in my recording view):

button-active.mp4

although my existing count data (from repo setup) got cleared, not sure why:

It re-tallies all the users who have a pattern favorited when updating the count, so when you update it locally, the count goes back to 1 as you're the only user on the local site to favorite it.

[StevenDufresne]

That's the active state, it was designed that way for all buttons. Here are two other places this happens (the first two I happened to grab in my recording view):

I understand that but it feels distracting in this case. Looking at Adam's video, the third button doesn't have that flash (is that a video problem?) and it feels like a better experience.

[ryelle]

Looking at Adam's video, the third button doesn't have that flash (is that a video problem?) and it feels like a better experience.

It's probably a faster click, the active state only appears as long as you're holding the mouse button down. Is the active state a blocker for this PR? If so, we'll probably need a different active state from design.

I'm still planning on addressing @adamwoodnz's feedback, I appreciate the suggestions!

[jasmussen]

I'd tend to agree, that active state is a bit curious. I wonder: do we actually need one? CC: @fcoveram as I think you have past knowledge on buttons.

[fcoveram]

I've been adding the active state to almost all new components created in the Design Library to follow what was already implemented. I'm unaware of any principle we're attached to or any discussions on pros and cons.

[ryelle]

I'd tend to agree, that active state is a bit curious. I wonder: do we actually need one?

I believe they're useful on mobile where there is no hover state, so active works to indicate what you tapped. I've also seen that it can be helpful for users with mobility issues, to make it clear when the click is happening. That said, we could probably make it less dramatic, either here or in general.

[ryelle]

I've merged this to move forward, but if we want to update anything (like the active state), let's continue that in a new issue.