Skip to content

Licensing: migrate the activation screen to @wordpress/ui - #50348

Merged
CGastrell merged 20 commits into
trunkfrom
update/licensing-wordpress-ui-components
Jul 13, 2026
Merged

CGastrell merged 20 commits into
trunkfrom
update/licensing-wordpress-ui-components

Conversation

@enejb

@enejb enejb commented Jul 9, 2026 •

Copy link
Copy Markdown
Member

Proposed changes

Migrate the Jetpack license activation screen (ActivationScreen in the @automattic/jetpack-licensing package) to the WordPress Design System (@wordpress/ui). This screen is shared by two entry points and both get the update:

  • Jetpack dashboard — admin.php?page=jetpack#/license/activation
  • My Jetpack — admin.php?page=my-jetpack#/add-license

Changes:

  • Activate button → @wordpress/ui Button (variant="solid"), using its built‑in loading state instead of an embedded Spinner.
  • License key inputs → @wordpress/ui InputControl / SelectControl.
  • "Do you need help? Contact us." → @wordpress/ui Text (body-md) + Link, fixing the previously too‑small copy. Added text-wrap: pretty to the subtext to avoid a single‑word orphan.
  • Card — wrap the screen in a @wordpress/ui Card.Root (border + radius) and drop the custom drop‑shadow.
  • Spacing — tighten the input‑to‑button gap and stop stretching the button to the bottom of the column (flex-start).
  • Retarget the validation‑border styling off @wordpress/components internal classes, trim the custom button SCSS in favour of the Design System defaults. (The field‑level validation border was dead CSS — it recoloured an input that @wordpress/ui gives border: none — so it was removed; error feedback is carried by the Notice.)
  • Update unit tests for the new components.

Because both entry points render the same ActivationScreen, the two screens now render an identical card.

Related product discussion/links

  • N/A

Does this pull request change what data or activity we track or use?

No.

Testing instructions

  • Activate Jetpack on a test site (the license screen is available pre‑purchase).
  • Go to wp-admin/admin.php?page=jetpack#/license/activation and confirm:
    • The Activate button renders as the @wordpress/ui solid button, is disabled with an empty field, and shows the built‑in loading state on submit.
    • Entering an invalid key and clicking Activate shows the red validation border and the error message.
    • The "Do you need help? Contact us." copy is body‑sized (matches the left column) with a working link.
  • Go to wp-admin/admin.php?page=my-jetpack#/add-license and confirm the card is identical to the one above (same button, spacing, card border, no drop‑shadow).

Before / After

Captured on a live Jurassic Ninja site.

Jetpack — page=jetpack#/license/activation

Before After
jetpack before jetpack after

My Jetpack — page=my-jetpack#/add-license

Before After
my jetpack before my jetpack after

Migrate the license activation screen (ActivationScreen) to the WordPress
Design System:

- Activate button -> @wordpress/ui Button (variant="solid", built-in loading
  state instead of an embedded Spinner).
- License key inputs -> @wordpress/ui InputControl / SelectControl.
- "Do you need help? Contact us." -> @wordpress/ui Text (body-md) + Link,
  fixing the previously too-small copy, plus text-wrap: pretty on the subtext.
- Wrap the screen in a @wordpress/ui Card.Root (border + radius), dropping the
  custom drop-shadow.
- Tighten the input-to-button gap and stop stretching the button to the bottom
  of the column (flex-start).
- Retarget validation border styling off @wordpress/components internal
  classes; trim the custom button SCSS in favour of the DS defaults.
- Update tests for the new components.
@github-actions

github-actions Bot commented Jul 9, 2026 •

Copy link
Copy Markdown
Contributor

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

  • To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the update/licensing-wordpress-ui-components branch.
  • To test on Simple, run the following command on your sandbox:
bin/jetpack-downloader test jetpack update/licensing-wordpress-ui-components

Interested in more tips and information?

  • In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
  • Read more about our development workflow here: PCYsg-eg0-p2
  • Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

@github-actions github-actions Bot added [JS Package] Licensing [Plugin] Jetpack Issues about the Jetpack plugin. https://wordpress.org/plugins/jetpack/ [Status] In Progress [Tests] Includes Tests RNA labels Jul 9, 2026
@github-actions

github-actions Bot commented Jul 9, 2026 •

Copy link
Copy Markdown
Contributor

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

  • ✅ Include a description of your PR changes.
  • ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  • ✅ Add testing instructions.
  • ✅ Specify whether this PR includes any changes to data or privacy.
  • ✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖


Follow this PR Review Process:

  1. Ensure all required checks appearing at the bottom of this PR are passing.
  2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
  3. You can use GitHub's Reviewers functionality to request a review.
  4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!


Jetpack plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

@github-actions github-actions Bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Jul 9, 2026
@jp-launch-control

jp-launch-control Bot commented Jul 9, 2026 •

Copy link
Copy Markdown

Code Coverage Summary

Coverage changed in 5 files.

File Coverage Δ% Δ Uncovered
projects/js-packages/licensing/components/activation-screen-controls/index.jsx 35/41 (85.37%) -1.12% 1 ❤️‍🩹
projects/js-packages/licensing/components/activation-screen-success-info/primary-link/index.jsx 18/23 (78.26%) -2.69% 1 ❤️‍🩹
projects/js-packages/licensing/components/activation-screen/index.jsx 48/55 (87.27%) -0.23% 1 ❤️‍🩹
projects/js-packages/licensing/components/activation-screen-error/index.tsx 9/9 (100.00%) 9.09% -1 💚
projects/js-packages/licensing/components/activation-screen-error/use-get-error-content.tsx 8/15 (53.33%) 20.00% -3 💚

Full summary · PHP report · JS report

@enejb
enejb marked this pull request as ready for review July 9, 2026 02:37
LiamSarsfield
LiamSarsfield previously approved these changes Jul 9, 2026

@LiamSarsfield LiamSarsfield left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice migration, the SelectControl string/item-object mapping came out clean, and the manual-entry fallback is handled well. Since the whole point is landing on @wordpress/ui, I read the visual shifts (no field error-border, flatter card) as intentional: @wordpress/ui hasn't shipped a field validation state yet (it's a TODO in the Field types) and Card.Root is flat by design, so matching that is the consistent call. A couple of small cleanups in that spirit:

  1. The error/success border rules in activation-screen-controls/style.scss are dead now. They recolor an input that @wordpress/ui gives border: none, so nothing paints. Worth deleting them (and the -with-error/-with-success class plumbing if it's unused now) so the next person doesn't assume field-level error styling exists. The red "Unable to validate" message still carries the feedback, which is the DS-consistent pattern anyway.

  2. activation-screen/style.scss has a comment saying the file adds the elevation, but nothing does and Card.Root is flat. Worth fixing the comment so it matches, or dropping a shadow back if you'd rather keep the depth.

  3. Tiny one: the new margin-top: 8px should be margin-block-start to stay RTL-safe.

  4. Optional: since you added loading to the Button, disabled={ ! license || isActivating } would keep it non-interactive during activation. Right now loading only draws the spinner, because disabled is always defined and the DS's disabled ?? loading never falls through.

The core change itself LGTM though so these can be fast follows if need be.

CGastrell and others added 10 commits July 9, 2026 18:51
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Primary CTA uses a @wordpress/ui Button with onClick navigation (native button;
a LinkButton follow-up is flagged for when it ships), and the companion link
uses a native @wordpress/ui Link.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ping

Use a sentinel value for the 'add a license key manually' option so the
SelectControl trigger reads that option (not the empty-value placeholder) while
the manual text input is shown, and clear the stored license on that pick.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The @wordpress/ui Button stays clickable in its loading state; gate it on
isActivating so a submission can't be re-triggered mid-request.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…rol doesn't reflow

Without a fixed column width, a long selected license value widens the controls
column (skewing the split). Give each column flex:1 + min-width:0 so the value
truncates via the trigger's built-in ellipsis instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Route license changes (select pick or manual input) through a handler that also
clears licenseError, so a stale 'invalid key' notice doesn't linger after the
user picks or types a different key.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the raw heading/paragraph and flex containers with @wordpress/ui
primitives: the h1 and intro copy become Text, and the column layout becomes
nested Stacks (outer space-between; a logo+heading group; a main-content group),
dropping the per-element margins/paddings in favour of Stack gap. Keeps the
validation border and the Button as-is; bumps the field labels from xs to md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- The validation-border rules targeted the <input>, but the @wordpress/ui input
  has border:none (the border sits on the .input-layout wrapper), so they never
  rendered — drop them.
- Card.Root already supplies the panel background, so the controls no longer need
  their own; drop the base-styles @use, the min-height, and the button margin.
- The error notice styles are unnecessary now that Notice + browser defaults
  render the message and lists cleanly — delete the stylesheet and its import.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@wordpress/ui Link with openInNewTab already sets rel appropriately, and modern
browsers imply noopener for target=_blank — matching the ExternalLink change in
Gutenberg (WordPress/gutenberg#79743).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fix the license-error assertion for the new @wordpress/ui Notice, cover the
disabled-while-activating button, and add an ActivationScreenError suite for the
generic, not-same-owner (ordered steps), and already-active (success) variants.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@CGastrell

Copy link
Copy Markdown
Contributor

Hey @enejb 👋 — since our two PRs (#50343 and this one) overlapped heavily, we've folded the parts of our work that weren't in your scope on top of your branch, as 10 discrete, individually-removable commits. Nothing here touches your form-controls migration, Card.Root, or the tests you already updated — it's all additive. Happy to reshape/drop any of it.

What we added (each is its own commit)

Commit What it does
error notice → Notice Replaces the hand-rolled __message/__info markup (and the green links) with a @wordpress/ui Notice — intent drives the red/green treatment + icon
success-screen links → @wordpress/ui PrimaryLink uses a ui Button with onClick navigation (native button; a LinkButton TODO is flagged), companion link uses a native ui Link
SelectControl manual-entry Sentinel value so the trigger reads "I want to add a license key manually" while the manual input shows (was the empty-value "Select" placeholder)
disable Activate while activating The ui Button stays clickable in its loading state; gate it on isActivating
two-column determinate width flex:1 + min-width:0 on the columns so a long selected key truncates via the trigger's ellipsis instead of reflowing the split
clear error on license change Route license changes through a handler that also clears licenseError, so a stale "invalid key" notice doesn't linger
controls layout → Text + Stack Heading/paragraph become Text; the column becomes nested Stacks (gap-based spacing); field labels bumped xs → md
remove dead/redundant CSS see notes below
drop rel=noopener from the error links matches the ExternalLink change in WordPress/gutenberg#79743
update + extend tests fixes the license-error assertion for Notice, adds an ActivationScreenError suite (generic / not-same-owner ordered steps / already-active success) + disable-while-activating

Before / after

(before = this branch's base; after = with our commits)

State Before After
Controls (resting) before-resting after-resting
Loading before-loading after-loading
License selector before-select after-select
Error — generic before-error-generic after-error-generic
Error — resolution steps ([not_same_owner]) before-error-ol after-error-ol
Error — list ([attached_license]) before-error-ul after-error-ul
Already-active (success notice) before-success-notice after-success-notice
Success screen — Backup before-success-backup after-success-backup
Success screen — Scan before-success-scan after-success-scan

A few things to flag for your call

  1. Drop shadow is gone. Trunk had box-shadow: 0 4px 24px 0 #00000026; Card.Root supplies only border + radius (no shadow, no elevation prop), and the SCSS comment "we only add the elevation…" doesn't actually add any. Worth restoring (a box-shadow or a WPDS elevation token) if the elevation was intended.
  2. The validation border never rendered. .license-field-with-error input { border-color } targets the <input>, but the @wordpress/ui input has border: none — the visible border lives on the .input-layout wrapper. So the red/green tint was dead CSS; we removed it. To actually tint it, target .input-layout (e.g. keyed off aria-invalid). Given the Notice already carries the red/green signal, dropping it seemed fine.
  3. LinkButton follow-up: the success-screen buttons use onClick navigation for now; they should become @wordpress/ui LinkButton once it ships (UI: Add LinkButton, IconLinkButton components WordPress/gutenberg#77098). TODO left in primary-link/index.jsx.

@LiamSarsfield LiamSarsfield left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice cleanup here. Dropping all that bespoke CSS and moving the error states onto Notice makes this much easier to follow.

One thing I think we need to sort before merge: pulling in SelectControl brings @wordpress/ui into the main admin bundle, which drags @wordpress/theme and @wordpress/private-apis in as externalized script handles (wp-theme / wp-private-apis). Those aren't registered on the Jetpack admin path on WP 6.9/7.0, so the dashboard script can fail to load there. The AI-admin build already hit this and sets both to external: false in its DependencyExtractionPlugin. The main admin build in tools/webpack.config.js needs the same requestMap. Build it, check the generated admin.asset.php, then smoke-test the activation screen on 6.9.

Two smaller ones I'd do while you're in here:

  • The support links lost rel="noopener noreferrer". @wordpress/ui's Link sets target=_blank and no rel, so it's gone now rather than redundant. Cheap to add back.
  • The success CTAs went from real <a href> to buttons that set window.location.href, so cmd/middle-click and copy-link stop working on every success visit. A real anchor (or Link styled as the CTA) brings them back. Watch out that Button with render={} still comes out as role=button, so that alone won't restore link semantics.

One more: the description still calls out the red validation border, text-wrap, and the button placement change, but none of those are at the current head. Worth syncing the description and UAT so reviewers test what's actually shipping.

Everything else I saw is minor (changelog prefix, a couple of physical CSS props) and not worth holding this up.

@CGastrell

Copy link
Copy Markdown
Contributor

Nice catch there @LiamSarsfield , I thought I've handled the wp-theme polyfill on a previous PR, but this is a different build. I'll double check that and reinstate the rel props (also assumed here that ui's Link already provided those). As for the button rendering instead of <a>, that's a deliberate trade off. We'll soon switch those for a new component.

CGastrell and others added 2 commits July 10, 2026 11:46
The licensing activation screen pulls @wordpress/ui into the main Jetpack
admin bundle, which drags @wordpress/theme and @wordpress/private-apis in as
externalized script handles (wp-theme / wp-private-apis). Those handles are
not registered on the main Jetpack admin path — WP <= 7.0 has no core wp-theme,
and this page does not load the wp-build-polyfills shim — so the dashboard
script fails to enqueue there.

Add the same DependencyExtractionPlugin requestMap the AI admin build already
uses so both packages are bundled inline instead of externalized.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reverses the earlier drop: the @wordpress/ui Link does not add rel when
openInNewTab is set (it only sets target=_blank), so these new-tab links were
left without noreferrer. Modern browsers imply noopener for target=_blank, but
noreferrer is not implied, so restore rel="noopener noreferrer" explicitly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@LiamSarsfield LiamSarsfield left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is looking great after the latest push. The admin bundle fix does the job (built it locally, admin.asset.php comes out clean, no wp-theme/wp-private-apis), and the rel restore on the error links looks spot on. Thanks for turning it around so fast.

Just a few bits before it's good to merge:

Changelog will fail CI. changelog/fix-licensing-admin-bundle-wp-theme-external uses Type: fixed, but the Jetpack plugin only accepts major/enhancement/compat/bugfix/other, so changelogger validate errors out. bugfix (or compat) sorts it. Two more while you're in those files: the migration entry is filed as other, which keeps a visible redesign out of the user-facing changelog, so enhancement reads truer; and the separate rel entry documents a fix that never shipped (the links already had rel on trunk), so fold it into the migration entry or drop it.

Looks like one rel slipped through. activation-screen-success-info/product-link/index.jsx opens in a new tab (openInNewTab) with no rel, the same gap you closed on the error links. One line finishes it.

Stale error can linger. In activation-screen/index.jsx, the availableLicenses effect calls setLicense directly, which skips onLicenseChange, the only path that clears licenseError. So if the list refetches while an error is showing, you can land on a new key with the old key's error still under it. Route that through the clearing path (or clear it in the effect) and it's closed.

On the success CTAs becoming buttons: saw your note about moving to LinkButton later, no rush. If you want link behavior back before then, Button nativeButton={false} render={<a href={url} />} gets you there, but happy to leave it for the follow-up.

Nothing else blocking from me, the rest is just polish. Really nice work on this one.

@LiamSarsfield

Copy link
Copy Markdown
Contributor

Thanks for the changes @CGastrell I've put another round of a review here

CGastrell and others added 4 commits July 10, 2026 14:24
- The Jetpack plugin only accepts major/enhancement/compat/bugfix/other, so
  the admin-bundle entry's invalid 'fixed' type would fail changelogger; use
  'bugfix'.
- File the activation-screen migration as 'enhancement' rather than 'other' so
  the visible redesign lands in the user-facing changelog.
- Drop the error-links 'rel' entry: the links already had rel on trunk, so the
  net change is zero and it documented a fix that never shipped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Jetpack plugin only accepts major/enhancement/compat/bugfix/other, so the
admin-bundle entry's invalid 'fixed' type would fail changelogger validate; use
'bugfix'. Also file the activation-screen migration as 'enhancement' rather than
'other' so the visible redesign lands in the user-facing changelog.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The product-link CTA opens in a new tab (openInNewTab) but the @wordpress/ui
Link never sets rel, so it lacked noopener/noreferrer — the same gap that was
closed on the error links. One attribute finishes it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The availableLicenses effect calls setLicense directly, bypassing
onLicenseChange — the only path that clears licenseError. So a refetch while an
error is showing could land on a new key with the previous key's error still
under it. Clear the error in the effect too.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
LiamSarsfield
LiamSarsfield previously approved these changes Jul 10, 2026
@LiamSarsfield

Copy link
Copy Markdown
Contributor

@CGastrell LGTM! The changelog types are sorted and the rel restore covers all the new-tab links. Nice turnaround on those. The below are just nits:

One thing the last error-clear commit brought in. In activation-screen/index.jsx, the availableLicenses effect clears licenseError whenever that array changes reference, not when the selected key changes. React Query hands back a new array on any license change (and refetchOnReconnect is on by default), so a background refetch that touches some unrelated license wipes a valid error off the current key while it's still on screen. Tying the clear to a real key change (only clear when availableLicenses[0].license_key !== license) closes it and keeps the stale-error fix you added. A small test on that path would lock it in.

A couple of tiny ones if you're already in there:

  • The loading success button renders with no text or aria-label during the plugins fetch, so screen readers get an unnamed button. An aria-label covers it.
  • The webpack comment says wp-theme is missing on WP <= 7.0, but the my-jetpack shim notes say < 7.0. Worth matching so the next person knows when the bundling can drop.

Nothing else blocking from me, the rest is polish. Nice work getting this over the line 🚀

CGastrell and others added 3 commits July 13, 2026 11:40
The availableLicenses effect cleared licenseError whenever that array changed
reference. React Query hands back a new array on any refetch (refetchOnReconnect
is on by default), so a background refetch touching an unrelated license could
wipe a valid error off the current key. Track the last selected key in a ref and
only re-select + clear when the first available key actually changes. Add a test
covering the same-key refetch path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The success CTA renders with only a spinner during the plugins fetch, leaving
screen readers an unnamed button. Add an aria-label.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The my-jetpack shim notes say WP < 7.0; align the admin-build comment so it's
clear when the inline bundling can be dropped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@CGastrell
CGastrell merged commit ba13746 into trunk Jul 13, 2026
119 of 120 checks passed
@CGastrell
CGastrell deleted the update/licensing-wordpress-ui-components branch July 13, 2026 17:03
@github-actions github-actions Bot removed [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. [Status] In Progress labels Jul 13, 2026
Comment on lines +167 to +172
// Match the AI admin build: @wordpress/ui (pulled in via the licensing
// activation screen) drags in @wordpress/theme and @wordpress/private-apis.
// They are not registered as WP script handles on the main Jetpack admin
// path (WP < 7.0 has no core wp-theme, and this page does not load the
// wp-build-polyfills shim), so bundle them instead of externalizing to
// avoid the whole dashboard script failing to enqueue.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment seems really odd for the generic Jetpack modules webpack config? Talks about "this page" and unnamed "dashboard". etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[JS Package] Licensing [Plugin] Jetpack Issues about the Jetpack plugin. https://wordpress.org/plugins/jetpack/ RNA [Tests] Includes Tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants