New block: Favorite button #635

ryelle · 2024-07-02T20:41:58Z

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:

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

jasmussen · 2024-07-03T06:43:31Z

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

adamwoodnz · 2024-07-04T22:12:18Z

mu-plugins/blocks/favorite-button/index.php

+	return new \WP_Error(
+		'favorite-failed',
+		// Users should never see this error, so we can leave it untranslated.
+		'Unable to favorite this item.',


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

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 🙂

Updated error messaging: 0ebb8f2

adamwoodnz · 2024-07-04T22:15:55Z

mu-plugins/blocks/favorite-button/render.php

+$show_count = $attributes['showCount'] ?? false;
+$variant = $attributes['variant'] ?? 'default';
+
+if ( ! $user_id && ! $show_count && 'small' !== $variant ) {


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

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.

Simplified condition slightly by removing the variant check: 2dcb8ee

adamwoodnz · 2024-07-04T22:18:42Z

mu-plugins/blocks/favorite-button/src/block.json

+		},
+		"variant": {
+			"type": "string",
+			"enum": [ "default", "small" ],


For me the variants are more obvious as

Suggested change

"enum": [ "default", "small" ],

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

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 · 2024-07-04T22:23:16Z

mu-plugins/blocks/favorite-button/src/style.scss

+		&.is-heart-outline {
+			display: block;
+		}
+
+		&.is-heart-filled {
+			display: none;
+		}
+	}
+
+	&.is-favorite {
+		svg.is-heart-outline {
+			display: none;
+		}
+
+		svg.is-heart-filled {
+			display: block;
+		}


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

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 · 2024-07-04T23:36:48Z

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

ryelle · 2024-07-05T02:57:44Z

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 · 2024-07-05T04:59:15Z

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 · 2024-07-06T17:43:44Z

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 · 2024-07-08T07:38:49Z

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 · 2024-07-08T10:46:27Z

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 · 2024-07-08T22:57:10Z

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 · 2024-07-16T15:35:09Z

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.

New block: Favorite button

89b2c93

This was referenced Jul 2, 2024

Remove the Favorite API & block, use shared block WordPress/wporg-theme-directory#148

Merged

Remove favorite button block, use shared block WordPress/pattern-directory#697

Merged

ryelle self-assigned this Jul 2, 2024

ryelle requested review from a team, adamwoodnz, StevenDufresne and renintw July 2, 2024 20:51

ryelle added the [Block] New Block label Jul 2, 2024

adamwoodnz reviewed Jul 4, 2024

View reviewed changes

ryelle added 3 commits July 8, 2024 18:45

Update the fallback API error

0ebb8f2

Remove variant check for rendering

2dcb8ee

Determine icon visibility with interactivity API binding

ad75039

ryelle merged commit c944d1e into trunk Jul 16, 2024
2 checks passed

ryelle deleted the add/block-favorite-button branch July 16, 2024 15:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New block: Favorite button #635

New block: Favorite button #635

ryelle commented Jul 2, 2024 •

edited

Loading

jasmussen commented Jul 3, 2024

adamwoodnz Jul 4, 2024 •

edited

Loading

ryelle Jul 8, 2024

ryelle Jul 8, 2024

adamwoodnz Jul 4, 2024

ryelle Jul 8, 2024

ryelle Jul 8, 2024

adamwoodnz Jul 4, 2024

ryelle Jul 8, 2024

adamwoodnz Jul 4, 2024

ryelle Jul 8, 2024

adamwoodnz left a comment

StevenDufresne commented Jul 4, 2024

ryelle commented Jul 5, 2024

StevenDufresne commented Jul 5, 2024

ryelle commented Jul 6, 2024

jasmussen commented Jul 8, 2024

fcoveram commented Jul 8, 2024

ryelle commented Jul 8, 2024 •

edited

Loading

ryelle commented Jul 16, 2024

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

New block: Favorite button #635

New block: Favorite button #635

Conversation

ryelle commented Jul 2, 2024 • edited Loading

jasmussen commented Jul 3, 2024

adamwoodnz Jul 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adamwoodnz left a comment

Choose a reason for hiding this comment

StevenDufresne commented Jul 4, 2024

ryelle commented Jul 5, 2024

StevenDufresne commented Jul 5, 2024

ryelle commented Jul 6, 2024

jasmussen commented Jul 8, 2024

fcoveram commented Jul 8, 2024

ryelle commented Jul 8, 2024 • edited Loading

ryelle commented Jul 16, 2024

ryelle commented Jul 2, 2024 •

edited

Loading

adamwoodnz Jul 4, 2024 •

edited

Loading

ryelle commented Jul 8, 2024 •

edited

Loading