Theme: Promote ThemeProvider to stable API

[aduth]

What?

Closes #76840
Closes #75319

Updates @wordpress/theme to export ThemeProvider and useThemeProviderStyles as part of its stable API.

Why?

• As described in Design system theming for WordPress 7.1 #76941, ThemeProvider stabilization is an expected deliverable of WordPress 7.1
• With WordPress 7.1 release development officially started as of May 20, landing this early in the release cycle allows for a longer testing cycle
• Using private APIs in bundled packages causes issues, as described in UI: Remove usage of private APIs #75319

How?

• Removes lock-ing of private APIs from @wordpress/theme
• Updates consumers to replace unlock-ing private APIs with direct import of the stable members

Testing Instructions

Verify no regressions in surfaces where ThemeProvider is used, for example the Fonts screen or Storybook Theme pages.

In Storybook:

1. npm run storybook:dev
2. Go to http://localhost:50240/?path=/docs/design-system-theme-theme-provider--docs

In Fonts screen:

1. npm run dev
2. Go to http://localhost:8888/wp-admin/themes.php?page=font-library-wp-admin&p=%2Ffont-list
3. Verify that "Update" button color follows the current user theme color

Use of AI Tools

No AI was used.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: -1.24 kB (-0.02%)

Total Size: 7.5 MB

📦 View Changed

Filename	Size	Change
build/modules/boot/index.min.js	52.9 kB	-63 B (-0.12%)
build/modules/content-types/index.min.js	159 kB	-182 B (-0.11%)
build/scripts/block-directory/index.min.js	43.5 kB	-198 B (-0.45%)
build/scripts/block-editor/index.min.js	381 kB	-183 B (-0.05%)
build/scripts/customize-widgets/index.min.js	14.6 kB	+6 B (+0.04%)
build/scripts/edit-post/index.min.js	52.9 kB	-47 B (-0.09%)
build/scripts/edit-site/index.min.js	299 kB	-135 B (-0.05%)
build/scripts/editor/index.min.js	475 kB	-202 B (-0.04%)
build/scripts/format-library/index.min.js	30.8 kB	-1 B (0%)
build/scripts/media-utils/index.min.js	114 kB	-55 B (-0.05%)
build/scripts/theme/index.min.js	22.1 kB	-180 B (-0.81%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in b43c2be.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/26975139006
📝 Reported issues:

• [Flaky Test] Should insert content using the global inserter #78924 in /test/e2e/specs/widgets/editing-widgets.spec.js

[ciampo]

I guess this is unrelated from the the package README that mentions This package is still experimental. "Experimental" means this is an early implementation subject to drastic and breaking changes, right?

[ciampo]

Now that it;s a public API, we should probably add JSDocs to the ThemeProvider component

[aduth]

Now that it;s a public API, we should probably add JSDocs to the ThemeProvider component

Yeah, good call. And this will benefit the MCP server once we expose it there.

[aduth]

Now that it;s a public API, we should probably add JSDocs to the ThemeProvider component

Yeah, good call. And this will benefit the MCP server once we expose it there.

Added in b7cdc2f. Feedback welcome on wording. I originally started from how we describe it in README.md but refined it a bit. Maybe we want to revisit the README phrasing as well. "provide design tokens" isn't exactly accurate, because the provider doesn't generate a full set of tokens.

I also altered the ESLint configuration in 2158b04 to support this, and add a more complex explanation of why that exclusion applies.

[aduth]

I guess this is unrelated from the the package README that mentions This package is still experimental. "Experimental" means this is an early implementation subject to drastic and breaking changes, right?

I overlooked that and my instinct would be to remove it, as the intention here is stabilizing the API. What do you think?

[ciampo]

I overlooked that and my instinct would be to remove it, as the intention here is stabilizing the API. What do you think?

Given that we're potentially going to apply breaking changes to the DS tokens in the upcoming weeks, we could leave it around and remove it only when we stabilize the whole package (ie. version 1.0?), leaving this PR focused on making ThemeProvider a public API.

[aduth]

I overlooked that and my instinct would be to remove it, as the intention here is stabilizing the API. What do you think?

Given that we're potentially going to apply breaking changes to the DS tokens in the upcoming weeks, we could leave it around and remove it only when we stabilize the whole package (ie. version 1.0?), leaving this PR focused on making ThemeProvider a public API.

Yeah, that makes sense. It was also an oversight on my part that this doesn't do anything toward actually marking the package for 1.0 release, so we could make the promotion to 1.x and removal of the "experimental" banner a separate follow-on task closer to the 7.1 public release. Maybe tying it with a specific milestone like beta or RC ?

[aduth]

@ciampo Do you think we're good to move forward with this, or were you considering this blocked by other theme stabilization work?

[ciampo]

#79254 should be the last PR introducing breaking changes in the tokens, should we wait for it to be merged first?

[ciampo]

#79254 is now merged, let's go!

LGTM 🚀

[ciampo]

@aduth do you think we still need to

export type * from './prebuilt/ts/token-types';

from the package?

[ciampo]

Also, it looks like packages/private-apis/src/implementation.ts still mentions @wordpress/theme ?

[aduth]

@aduth do you think we still need to

export type * from './prebuilt/ts/token-types';

from the package?

Do you think we shouldn't? Personally I don't view that as related to the ThemeProvider component if the thinking is that we only needed those types because the component was private. Whether we want it in the public API in general though, I'm open to revisiting. They could certainly provide some value, though their original introduction was largely around the Box component and tying its typings to what's available through prebuilt token types, and we've since moved away from that.

Also, it looks like packages/private-apis/src/implementation.ts still mentions @wordpress/theme ?

Good catch, I'll update that 👍

[ciampo]

They could certainly provide some value, though their original introduction was largely around the Box component and tying its typings to what's available through prebuilt token types, and we've since moved away from that.

I agree that they can provide value, but (especially given the nature of the package) I think we should only export what we know is needed as of now, and add more exports if necessary. The opposite won't be possible once the package is marked as stable

[aduth]

The opposite won't be possible once the package is marked as stable

We could still make backwards-incompatible changes to TypeScript typings, no? Since they're not part of the window.wp.theme global.

[ciampo]

The opposite won't be possible once the package is marked as stable

We could still make backwards-incompatible changes to TypeScript typings, no? Since they're not part of the window.wp.theme global.

Not sure, we received complaints in the past about breaking type changes, too — especially form the point of view of third party maintainers that need to support multiple versions of WP and therefore woulnd't be able to have a single implementation that satisfies all versions at the same time (cc @mirka)

[aduth]

That might be improved separately with #79455.

In any case, let's take a look. I know we use a couple of the types ourselves at the moment, but most of them are likely unused.