feat(card)!: modernize game and hub tooltips

[wescopeland]

This PR reimplements game and hub tooltips throughout the entire site. Presently, these tooltips feature largely redundant data (such as simply game and console name). Now, the tooltips show dynamic data related the game's achievement set as well as data pertinent to a currently authenticated or otherwise context-adjacent user.

UX Walkthrough

Use Case 1: No Active Core Set

If a game has no active core set, this is valuable contextual information for a user. This use case will commonly occur on game lists and game tables, especially lists of similar games on game pages. They are presented with the game title, console name, and copy stating there are no achievements for the game.

Use Case 2: No Active Core Set + Has Active Claim

If a game has no active core set but has a claim, this is valuable contextual information for a user. This use case will commonly occur on the claims list (including the home page). Users will be presented with similar information as Use Case 1, however now they will see basic metadata about the claimants.

Collaboration claims also have a dedicated experience, which is driven by using a new "avatar stack" common component.

Use Case 3: Active Core Set

This is by far the most common use case that everyday users will see. Once a game has an active core set, we can start showing basic metadata about the core set such as achievements count, points sum, RetroPoints sum, retro ratio, and last updated date.

Use Case 4: Active Core Set + Site Award

This is likely the second most common use case that everyday users will see. Once a user has earned a completion or mastery badge for a game, it is noted on the card. This use case is also visible when a user visits another player's profile and views their badges: the username that the card receives to check for awards status is dynamic and context-driven.

Use Case 5: Active Core Set + Revision Claim

If a game has an active core set but also has a revision claim, this is valuable contextual information for a user. Users will be presented with similar information as Use Case 2, however now they will see basic metadata about the claimants.

Collaboration claims also have a dedicated experience nearly identical to Use Case 2. Award displays from Use Case 4 are still respected. The revision metadata is "bolted on".

Use Case 6: Retired Sets

If a set has been Z'd out, it will be shown as being retired in the tooltip. This will most commonly occur on longstanding users' profile pages, where site awards are present for games that now have deprecated sets.

Use Case 7: Hubs

Hubs now have a slightly improved treatment, showing the count of links (alt game IDs) and when the hub was last updated.

Technical Implementation

• Game tooltip cards no longer render statically via useCard(). Each avatar component now makes a call to the card.php endpoint, similar to user cards. The game ID is used to dynamically fetch the card template. For documents containing many game avatars, this results in a non-trivial load-time performance improvement.

NES Console Game List (862 games):
Before - 104kB
After - 84kB (21% reduction)

Large User Profile (701 badges):
Before - 162kB
After: 106kB (42% reduction)

• The context input for game cards is now dedicated to the username. Previously, it was statically-rendered mastery metadata. This is used for fetching metadata about other users' site awards, such as on user profiles.

• The cards test page has been updated with lots of examples from the use cases listed above.

• To further improve performance, a polyfill has been added for requestIdleCallback() that should mitigate UI thread locking on every browser except Safari.

• A bug has been fixed in updateTooltipPosition() that could cause some game cards on user profiles to render in an infinite loop (note: this does not happen in prod today, it is surfaced by the new game cards themselves).

• The "Last Updated" metadata is still contentious and will differ from what is shown on game lists. @Jamiras: I implemented the suggestion from https://discord.com/channels/476211979464343552/1026595325038833725/1134272667780919427, however this caused some bizarre readings on older sets that have never been subject to the claim system (such as game ID 1), so I rolled back to the implementation that is checking for achievement last updates. I know this solution is also fraught with trade-offs.

• I have checked everywhere I can find on the site that I know that renders game avatars to ensure they're working properly. I've also attached the tooltips to the AOTW component.

• I've written a fairly thorough set of integration tests covering all of the use cases listed above.

[Alexdatadestroyer]

I have some feedback regarding this feature:

a) How Events pages (ConsoleID = 101) will be treated on Card Tooltip when an Event is highlighted? It's not an ordinary set and neither a Hub case. I don't think that showing it like an ordinary set (achievements, points, retro ratio, last updated) would be good: Maybe, only showing if the Event was mastered or not and when was last updated then?

b) Is it possible to replace the blue dot and yellow dot for a medal and a crown on their respective cases? Softcore completion is already represented by a Medal while Hardcore completion is represented as a Crown on User Profile pages. Their icon is tiny enough to fit on Card Tooltip, so why not?

(PS: I know that Blue indicates Softcore while Yellow indicated Hardcore, indeed. However, on UP is represented differently for some reason: Hardcore progress is Blue while Softcore progress is Grey.)

c) For Use Case 6 (Retired Sets), if the idea is using dark-white color style (similar to when an achievement is still locked) to let the user know that the Set is now deprecated, then, why not suppressing the Z tag after Set Name knowing that an Available Set will never be shown like this?

A bolded effect on "This achievement set has been retired" message would be nice to give it an extra attention to the user.

Looking forward! 🚀

[Alexdatadestroyer]

[Easter Egg Proposal]

Now, I was thinking about something fun which would be great if this comes to reality using this feature...

Well, you know... Some games might have easter eggs. We are on a (retro) gaming website. So why not create an easter egg thing on RAWeb? This can be a fun part of helping this site overall!

As far as I know, the only easter egg that RAWeb has it's the random reactions of RA Mascot on such error pages. Some specific pages have static reaction though (Like HTTP 403 Forbidden case). The sentence "Git gud" can be seem on such situations.

I am saying that because I figured a chance of another easter egg creation:

• There is a bugged set page (Some Errors Are More Error Than Others) which was created due to a Database Error in past without ConsoleID at the time. Now, it's filed on Event console category. Knowing that this will remain forever as invalid set page, then, it's comes the idea of addition of an easter egg feature on it: It will show to any user that finds the page using Site Search feature:

Instead of Card Tooltip showing Event details like it was expected to when hovering the element, it could show something like:

Some Errors Are More Error Than Others
Events

Whoa dude! You just found the RetroAchievements Secret Set! Congratulations dude, you are a legend! :)

Some time ago, a similar sentence like posted above used to be a meme spread by some users on RA community to ironically congratulate a user that have mastered such a meme/easy set or just to make fun of a friend.

[wescopeland]

Hello @Alexdatadestroyer,

Thanks for leaving your thoughts. I will respond to each line item individually below.

How Events pages (ConsoleID = 101) will be treated on Card Tooltip when an Event is highlighted? It's not an ordinary set and neither a Hub case. I don't think that showing it like an ordinary set (achievements, points, retro ratio, last updated) would be good: Maybe, only showing if the Event was mastered or not and when was last updated then?

This is how event awards currently appear:

Unless a web maintainer feels otherwise, I don't think we should change any of this. I don't want the cards to be prescriptive to event organizers on achievement counts or whether an event can be mastered or completed.

Is it possible to replace the blue dot and yellow dot for a medal and a crown on their respective cases?

I am earnestly against this recommendation for two reasons. One, emoji are difficult to get right when it comes to accessibility. Two, emoji are not vendor-standardized and render differently on every browser and OS.

This is probably the appropriate time to say I'm in favor of removing all emoji from the app and replacing them with standardized icons that better represent our brand.

For Use Case 6 (Retired Sets), if the idea is using dark-white color style (similar to when an achievement is still locked) to let the user know that the Set is now deprecated, then, why not suppressing the Z tag after Set Name knowing that an Available Set will never be shown like this?

The game badge images have not been altered in these screenshots, and the component applies no filters to them.

I agree with you that the Z tag is confusing and unhelpful. However, changing it or suppressing it requires adding conditional logic to the renderGameTitle() function, which is called on nearly every page of the site. This PR is already large; I don't want to increase its scope or size.

I would like to revisit this in a future PR, as the Z tag is something that has room for improvement.

A bolded effect on "This achievement set has been retired" message would be nice to give it an extra attention to the user.

Under the current design, labels are bolded and descriptions are using the base font weight. Subjective: the Z tag is uncommon enough that it probably isn't worth adding an exception here.

[Easter Egg Proposal]

A few of the site's event awards are fairly prominent on developer profiles, and some of them (such as DevQuest awards) take months, if not years, of hard work and steady contributions to earn. My personal opinion is adjusting their design in this way would be contentious at best. I would only be willing to make this change if the community was asking for it.

[Jamiras]

How Events pages (ConsoleID = 101) will be treated on Card Tooltip when an Event is highlighted? It's not an ordinary set and neither a Hub case. I don't think that showing it like an ordinary set (achievements, points, retro ratio, last updated) would be good: Maybe, only showing if the Event was mastered or not and when was last updated then?

This is how event awards currently appear:

Unless a web maintainer feels otherwise, I don't think we should change any of this. I don't want the cards to be prescriptive to event organizers on achievement counts or whether an event can be mastered or completed.

I don't feel that the achievement count matters, most events will have exactly 6 achievements as that's how many are required to award a badge. You could also change the wording from "Completed"/"Mastered" to "Awarded" (for both hardcore and softcore).

Do you have any plans to spruce up the psuedo-awards? (also note the 'Awarded' phrasing)

[wescopeland]

I don't feel that the achievement count matters, most events will have exactly 6 achievements as that's how many are required to award a badge. You could also change the wording from "Completed"/"Mastered" to "Awarded" (for both hardcore and softcore).

Fair enough, I agree that it does seem reasonable to align the language with the non-event/non-game site awards. I've made the changes in 504938a which include adding an event card to the cards test page and adding another test case to handle this code path.

Do you have any plans to spruce up the psuedo-awards? (also note the 'Awarded' phrasing)

Yes, most certainly! I would like to touch up every remaining tooltip kind on the site, which to my knowledge leaves achievements, tickets, and these straggler site award native tooltips as the ones outstanding. My intention is to tackle these tooltip kinds in subsequent PRs.

[luchaos]

Awesome stuff!

This is probably the appropriate time to say I'm in favor of removing all emoji from the app and replacing them with standardized icons that better represent our brand.

I really like those dots; yet, maybe we implement different icons for completion? I think the current dot might resemble future points icons too closely.

Use Case 4: Active Core Set + Site Award

When hovering the game "Super Mario 64" in "Completion Progress" first and the badge afterwards it will not contain the mastery information, when doing it the other way around after a reload it will - is it missing a context specifier for the cache key or is this by design?

Currently deployed at https://preview.retroachievements.org/user/luchaos

[wescopeland]

I really like those dots; yet, maybe we implement different icons for completion? I think the current dot might resemble future points icons too closely.

I appreciate this suggestion; I want to propose a different approach due to several considerations.

1. The visual identity for Points branding remains an open discussion. Although it seems likely it'll incorporate a spherical or rectangular shape, it does seem to remain unsettled.
2. I believe we should not determine completion branding before reaching a consensus on Points branding. Establishing one before the other might lead to inconsistencies in our design language.
3. A pivot from the dot, in the absence of a decided completion branding, would likely mean defaulting to the emoji(s). This is an option I'm not in favor of.

I propose that, similar to the vote that recently occurred on RetroPoints branding (which we collected a lot of great feedback from), we perform a similar study/review on completion branding. For something this important, I am guarded and would like to gather community feedback and go through an iteration or two. In my view, the dots are temporary placeholders until we find a branding that suits our needs. That said, I'm hesitant to implement something more definitive without first conducting the surveys mentioned earlier.

Perhaps we can meet closer in the middle on this though. What if we create a common component, similar to our approach with the RetroPoints container? This way, once we agree on a branding or visual identity for completion indicators, we have a ready-to-go component for the new design. If it helps, maybe we can also change the dot to a square? Meanwhile, this common component can retain the dots as a placeholder.

[wescopeland]

When hovering the game "Super Mario 64" in "Completion Progress" first and the badge afterwards it will not contain the mastery information, when doing it the other way around after a reload it will - is it missing a context specifier for the cache key or is this by design?

Great catch, this is a bug caused by a missing context specifier. Resolved in latest.

[wescopeland]

Hi @Alexdatadestroyer,

I appreciate you taking the time to share your thoughts. I want to provide further clarity of the scope of this PR.

The purpose of this PR is specifically to implement the new game tooltip designs, which I outlined in detail in the initial description. Feedback on these designs was solicited from numerous stakeholders before and during implementation. While I always welcome and desire constructive feedback, I'd like to keep the discussion focused on the changes in this PR. This is not the appropriate venue to raise other issues or propose new features.

I've written in detail my opinion on completion icons here #1700 (comment). I suggest creating separate issues or discussions for those ideas so they can get proper consideration. Pull requests work best when kept focused on the code at hand.

I don't want you to feel discouraged - on the contrary, we are fortunate to have someone who is energized and willing to help test issues on the site. But for this PR specifically, I'd like to keep the conversation centered on the code changes and implementation details contained therein.

Please let me know if I have not clarified this well enough. I appreciate you taking the time to provide feedback in RAWeb and the development process.

[luchaos]

I appreciate this suggestion; I want to propose a different approach due to several considerations.
...

Very good reasoning - thanks for all the context! Let's go with the dots 👍