Spike: investigate how we are importing & overriding styles from @wordpress/components

[mgascam]

Refocusing this as a spike to better understand the problem. Spike will need to answer these questions:

1. How are we importing @wordpress/components.
   • Are we on a recent version, i.e. should we update.
   • Do we import from npm i.e. bundle, or do we depend on core (or do we do both!)
2. What is the recommended way to use @wordpress/components and get the styles.
   • It's not clear what the correct approach is. I would expect that we should be able to get styles "for free" if we bundle, or if we use the version built in to WordPress core.
3. What styles we are overriding (from @wordpress/components).
   • Based on info below, it seems we are overriding (customising) some styles, and this is causing problems.
   • This should include a mini-audit to understand the extent – i.e. do we have 1-5 minor tweaks or are we overriding lots of components (and then overriding those overrides internally… 😁 )

Once we know the options for reusing styles from the package (1 and 2 above), then we can make a plan for how to iterate towards reducing or removing our customisations/overrides (3).

Read on for more info in original bug report (i.e. a symptom caused by current situation).

Describe the bug

There are missing CSS rules from the wordpress/components package in the compiled stylesheet for WC Admin that cause visual issues.

For context, we noticed this issue while working on #7742. One of the requirements was to introduce a dropdown menu on the payment details screen. We decided to use the DropdownMenu from the wordpress/components package, but noticed that the positioning was not working. After investigation, it seemed that there were missing rule definitions in the CSS stylesheet of the WP Admin related to the wordpress/components.

In my Docker based dev environment, these styles are loaded in http://localhost:8082/wp-includes/css/dist/components/style.css?ver=6.4.2

To fix the missing styles we started importing the missing styles from the node_modules in the React component (here), but we needed to revert since this was causing visual issues in other instances of DropdownMenu.

To Reproduce

N.B: This has been spotted in the payment details page with the DropdownMenu component, but potentially affects other parts of the codebase where wordpress/components are utilized.

1. In your local WooPayments instance, remove the CSS workaround here and rebuild CSS (i.e. npm start)
2. Navigate to Transactions > Payment Details page
3. Click on the three-dots menu on the top right corner of the payment summary.

Actual behavior

The DropdownMenu is misplaced in the layout:

Screenshots

Expected behavior

The DropdownMenu is properly placed in the layout:

Additional context

Slack discussion: https://a8c.slack.com/archives/C053VQPD74J/p1700490601899939

[jessy-p]

@mgascam Could you please add the details under TODO so that the issue can be assigned to the responsible team.

[mgascam]

@mgascam Could you please add the details under TODO so that the issue can be assigned to the responsible team.

Thanks for the ping @jessy-p, I added more context. Hopefully it's more clear now, but It's kind of a tricky issue so please let me know if you have further questions.

[kalessil]

This should be a coordinated effort here, as this is related to the JS components version used in the development and provided by the runtime.

EDIT: removing from Pulsars board, this issue is for our JS guild lo look into.

[vbelolapotkov]

@haszari sending this one to your team's maintenance backlog. I've assigned the issue to you for this, please take care of adding it to the team board.

[haszari]

Thanks @vbelolapotkov – added to our board, will set a priority soon.

[haszari]

I will take another look at this to better understand the problem so helix can estimate and action. @haszari

[haszari]

A good next step here is a spike to understand:

1. How are we importing @wordpress/components.
   • Are we on a recent version, i.e. should we update.
   • Do we import from npm i.e. bundle, or do we depend on core (or do we do both!)
2. What is the recommended way to use @wordpress/components and get the styles.
   • It's not clear from issue description what the correct approach is. I would expect that we should be able to get styles "for free" if we bundle, or if we use the version built in to WordPress core (or potentially via WooCommerce core??).
3. What styles we are overriding (from @wordpress/components).
   • It's clear from the description that we are overriding (customising) some styles, and this is causing problems.
   • This should include a mini-audit to understand the extent – i.e. do we have 1-5 minor tweaks or are we overriding lots of components (and then overriding those overrides internally… 😁 )

Once we know the options for reusing styles from the package (1 and 2 above), then we can make a plan for how to iterate towards reducing or removing our customisations/overrides (3).

I'll update the title and description to focus on this spike, we can log other issues once we have more info! FYI @mgascam let me know if I'm missing anything, any feedback you have on this plan of action.

[haszari]

Prioritised as medium, since it could have a positive impact – i.e. speed up development if we just depend on components, reduced or no overrides.

That said, there's no urgency here, this could be low.

[Jinksi]

Are we on a recent version, i.e. should we update.

A quick answer to this, as I was investigating for a discussion in #8382

WooPayments is importing @wordpress/components 19.8.5, published 2 years ago.

The current version of @wordpress/components is 29.0.0.

Unfortunately, WooPayments has not kept up-to-date with component library versions as part of regular maintenance, and so an update to the current version will require effort that has not been easy to prioritise in the past – @Automattic/helix talked about this at our last meetup pdjTHR-3SB-p2.

[Jinksi]

I'll post the complete details in a P2 and link here

Hot off the press, best practices for building with @wordpress/components were shared here: p7H4VZ-5aZ-p2.

I'll incorporate these best practices into this investigation before posting.

[Jinksi]

I've posted a P2 with the spike results that can be found here: paJDYF-gpC-p2.

To summarise:

• WooPayments bundles an outdated version of @wordpress/components, which conflicts with the globally available version in WP-admin, used by WC.
• This causes style conflicts, due to how styles are loaded for different components:
  • For .scss-styled @wordpress/components imported by WooPayments, styles may be incomplete or incorrect, since the styles specific to the imported version of @wordpress/components are not bundled along with the JS/React components. ⚠️
  • For CSS-in-JS @wordpress/components, the outdated version of the component styles will apply. This, however, results in outdated versions of the UI being rendered and inconsistent UI across WooPayments & Woo. ⚠️
  • Direct imports of legacy styles (e.g. @import 'node_modules/@wordpress/components/**/style.scss') causes style conflict issues because these outdated styles will also be applied to other product areas that expect the globally available @wordpress/components styles. ⚠️
• The appropriate long-term fix for these issues is to take the same approach as WC core – unbundle @wordpress/components and use the globally available wp.components and associated styles that are used by WP-admin and WC.
  • Where possible, code should be modified to follow @wordpress/components best practices (p7H4VZ-5aZ-p2) during the unbundling process and processes should be in place to ensure WooPayments follows these best practices in the future.
  • Unbundling @wordpress/components may cause unexpected WooPayments admin UI bugs and instability since we will be relinquishing control of the package version to that which is available globally via wp.components. These risks can be mitigated by following best practices (p7H4VZ-5aZ-p2) and applying thorough testing (including e2e, visual regression and manual testing) of supported WP versions. It would be worth understanding how WC handles this risk and following a similar approach for WooPayments.