Theme: Restore public ThemeProvider export by ciampo · Pull Request #79620 · WordPress/gutenberg

ciampo · 2026-06-29T08:05:31Z

What?

Follow up to #79594.

Restores ThemeProvider as a public @wordpress/theme export while keeping the existing private API bridge temporarily available.

Why?

The previous stabilization in #78958 moved ThemeProvider to the public API but also removed the private export. That broke bundled/package consumers that still depended on the private API path, so #79594 temporarily restored the private-only state.

This PR lands the safer transition:

public API consumers can import ThemeProvider directly;
existing private API consumers keep working during a grace period;
newer @wordpress/ui consumers can still run against older WordPress runtimes where @wordpress/theme only exposes the private bridge;
private API access now warns through deprecations before removal in WordPress 7.3.

How?

Exports the runtime ThemeProvider from @wordpress/theme.
Keeps private API compatibility, but marks access as deprecated and points consumers to supported public theming APIs.
Removes the root CornerRadiusPreset type export; consumers can derive it from ThemeProvider's cornerRadius prop if needed.
Migrates Gutenberg-owned ThemeProvider and root configuration type consumers away from private/unstable root imports.
Uses no-restricted-imports to prevent new privateApis imports from @wordpress/theme.
Adds a temporary @wordpress/ui resolver that uses the public ThemeProvider when available and falls back to privateApis.ThemeProvider for older runtimes.

Testing Instructions

All unit tests pass.
All lint checks pass.
Build succeeds.

Testing Instructions for Keyboard

Not applicable; this changes package API wiring and lint coverage without changing UI behavior.

Screenshots or screencast

Not applicable.

Use of AI Tools

Created with assistance from OpenAI Codex. The diff and verification output were reviewed before opening this PR.

github-actions · 2026-06-29T08:19:03Z

Size Change: +655 B (+0.01%)

Total Size: 7.52 MB

📦 View Changed

Filename	Size	Change
`build/modules/boot/index.min.js`	51.1 kB	+45 B (+0.09%)
`build/modules/content-types/index.min.js`	160 kB	+46 B (+0.03%)
`build/scripts/block-directory/index.min.js`	44.1 kB	+56 B (+0.13%)
`build/scripts/block-editor/index.min.js`	383 kB	+65 B (+0.02%)
`build/scripts/edit-post/index.min.js`	52.3 kB	+72 B (+0.14%)
`build/scripts/edit-site/index.min.js`	298 kB	+54 B (+0.02%)
`build/scripts/editor/index.min.js`	487 kB	+35 B (+0.01%)
`build/scripts/media-utils/index.min.js`	115 kB	+76 B (+0.07%)
`build/scripts/theme/index.min.js`	22.6 kB	+206 B (+0.92%)

_{compressed-size-action}

github-actions · 2026-06-29T09:52:56Z

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: ciampo <[email protected]>
Co-authored-by: tyxla <[email protected]>
Co-authored-by: aduth <[email protected]>

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

ciampo · 2026-06-29T09:55:05Z

+
 export { privateApis } from './private-apis';
+export { ThemeProvider } from './theme-provider';
 export type * from './prebuilt/ts/token-types';


Not sure whether we should keep these types around. On one hand, they are the TS reflection of the CSS tokens and they are consumed by @wordpress/ui. On the other hand, we usually don't export types from DS packages.

In any case, changes such as adding a deprecation + lint errors can be handled in a separate PR.

cc @mirka @aduth

In any case, given that they are consumed by @wordpress/ui, we won't be able to simply delete them like done for the corner radius type.

I think we can/should keep these. It's different from component props, which can be extracted from the component exports themselves.

aduth

Tested that this works successfully both in Gutenberg-native screens using ThemeProvider stable API (Site Editor, no deprecation warning), as well as the AI plugin settings screen which bundles an older version of @wordpress/ui (logs deprecation warning).

aduth · 2026-06-29T12:39:50Z

+
+/**
+ * @deprecated This type is not part of the intended public API and will be
+ * removed in WordPress 7.3. Derive this type from `ThemeProvider`'s
+ * `cornerRadius` prop instead.
+ */
+export type CornerRadiusPreset = InternalCornerRadiusPreset;


I know we discussed this recently in #78958 (comment), but I'm less clear about needing to keep around the TypeScript types. It'd help to understand the failure scenario.

Ah, I just wrote a separate, related comment here.

I personally would like to remove it, but I intially adopted a more conversative approach.

The failure scenario here would be a build errors at TS compilation time, since the export would be missing?

ciampo · 2026-06-29T12:57:04Z

+ * removed in WordPress 7.3. Derive this type from `ThemeProvider`'s
+ * `cornerRadius` prop instead.
+ */
+export type CornerRadiusPreset = InternalCornerRadiusPreset;


This is also a partially separate conversation to have. In short, we should not have a CornerRadiusPreset type export, since it can be derived (if needed) via React.ComponentProps< typeof ThemeProvider >[ 'cornerRadius' ].

Given that this export was added recently (#78816) and didn't make it to a WP release yet, I wonder if we can be more aggressive and just remove it from the package directly, especially given that its only usages in the repo were "internal" (storybook/decorators/with-design-system-theme.tsx and storybook/stories/design-system/theme-example-application.story.tsx). The potential to cause build errors here is much lower.

cc @WordPress/gutenberg-components and @tyxla

Update: I tentatively removed CornerRadiusPreset entirely and marked it as a breaking change

I'm inclined to remove it too. Particularly since the rationale you suggested in #78958 (comment) for why TypeScript types would need to be sensitive to backwards-compatibility has to do with plugins supporting multiple versions of WordPress. If this has never landed in a WordPress release, combined with the fact that TypeScript types don't ever get exposed on window.wp.theme, it seems fine to remove.

Agreed 👍

CGastrell · 2026-06-29T22:03:05Z

Any chance we cherry-pick this for RC.2?

* Theme: Restore public ThemeProvider export * Theme: Add ThemeProvider public export changelog * Theme: Use warning package for ThemeProvider deprecation * Theme: Use restricted import for private APIs * Theme: Deprecate unstable root type exports * Storybook: Derive ThemeProvider corner radius type * Theme: Keep token type exports unrestricted * Theme: Warn for all private API access * Theme: Simplify private API warning message * Theme: Clarify private API warning source * Theme: Clarify private API changelog entry * Theme: Simplify private API warning tests * UI: Remove internal ThemeProvider changelog entry * Theme: Remove redundant SCRIPT_DEBUG test setup * Theme: Use deprecated package for private API warnings * Theme: Align deprecation timeline wording * Theme: Retarget private API removal to WordPress 7.3 * UI: Add ThemeProvider compatibility fallback * Storybook: Tighten corner radius preset types * Storybook: Clarify optional corner radius type * Build: Add missing TypeScript project references * Theme: Reclassify private API changelog entry * UI: Reuse lock-unlock helper * Theme: Clarify private hook deprecation message * Theme: Add CornerRadiusPreset changelog deprecation * Theme: Remove root CornerRadiusPreset export * Theme: Add CornerRadiusPreset breaking change * Theme: Clean up compatibility metadata --- Co-authored-by: ciampo <[email protected]> Co-authored-by: tyxla <[email protected]> Co-authored-by: aduth <[email protected]> # Conflicts: # packages/theme/CHANGELOG.md # packages/ui/CHANGELOG.md

tyxla · 2026-06-30T07:34:14Z

I just cherry-picked this PR to the release/23.5 branch to get it included in the next release: 9fccd4f

* Theme: Restore public ThemeProvider export * Theme: Add ThemeProvider public export changelog * Theme: Use warning package for ThemeProvider deprecation * Theme: Use restricted import for private APIs * Theme: Deprecate unstable root type exports * Storybook: Derive ThemeProvider corner radius type * Theme: Keep token type exports unrestricted * Theme: Warn for all private API access * Theme: Simplify private API warning message * Theme: Clarify private API warning source * Theme: Clarify private API changelog entry * Theme: Simplify private API warning tests * UI: Remove internal ThemeProvider changelog entry * Theme: Remove redundant SCRIPT_DEBUG test setup * Theme: Use deprecated package for private API warnings * Theme: Align deprecation timeline wording * Theme: Retarget private API removal to WordPress 7.3 * UI: Add ThemeProvider compatibility fallback * Storybook: Tighten corner radius preset types * Storybook: Clarify optional corner radius type * Build: Add missing TypeScript project references * Theme: Reclassify private API changelog entry * UI: Reuse lock-unlock helper * Theme: Clarify private hook deprecation message * Theme: Add CornerRadiusPreset changelog deprecation * Theme: Remove root CornerRadiusPreset export * Theme: Add CornerRadiusPreset breaking change * Theme: Clean up compatibility metadata --- Co-authored-by: ciampo <[email protected]> Co-authored-by: tyxla <[email protected]> Co-authored-by: aduth <[email protected]>

ciampo · 2026-06-30T12:50:01Z

I just cherry-picked this PR to the wp/latest branch (92529df) to get it included in the latest npm package releases (@wordpress/[email protected], @wordpress/[email protected])

Theme: Restore public ThemeProvider export

9fe7e18

github-actions Bot added [Package] Edit Site /packages/edit-site [Package] Theme /packages/theme [Package] UI /packages/ui labels Jun 29, 2026

ciampo added 2 commits June 29, 2026 10:06

Theme: Add ThemeProvider public export changelog

9368815

Theme: Use warning package for ThemeProvider deprecation

3427a2d

ciampo added 11 commits June 29, 2026 10:22

Theme: Use restricted import for private APIs

a73e43e

Theme: Deprecate unstable root type exports

c02f94b

Storybook: Derive ThemeProvider corner radius type

9ee3bce

Theme: Keep token type exports unrestricted

57715bd

Theme: Warn for all private API access

ab8e694

Theme: Simplify private API warning message

5e1c566

Theme: Clarify private API warning source

4866d05

Theme: Clarify private API changelog entry

27733eb

Theme: Simplify private API warning tests

a70f380

UI: Remove internal ThemeProvider changelog entry

6d56aac

Theme: Remove redundant SCRIPT_DEBUG test setup

5d2a903

ciampo self-assigned this Jun 29, 2026

ciampo added [Type] Code Quality Issues or PRs that relate to code quality Backport to Gutenberg RC Pull request that needs to be backported to a Gutenberg release candidate (RC) labels Jun 29, 2026

ciampo marked this pull request as ready for review June 29, 2026 09:52

ciampo requested review from a team and manzoorwanijk as code owners June 29, 2026 09:52

ciampo requested a review from tyxla June 29, 2026 09:52

ciampo commented Jun 29, 2026

View reviewed changes

tyxla reviewed Jun 29, 2026

View reviewed changes

Comment thread packages/theme/src/test/private-apis.test.ts Outdated

Comment thread packages/theme/src/private-apis.ts Outdated

Comment thread storybook/decorators/with-design-system-theme.tsx Outdated

Comment thread packages/theme/CHANGELOG.md Outdated

ciampo added 2 commits June 29, 2026 13:22

Theme: Use deprecated package for private API warnings

07a6f24

Theme: Align deprecation timeline wording

2c18621

ciampo added 8 commits June 29, 2026 13:52

UI: Add ThemeProvider compatibility fallback

5e3a1ba

Storybook: Tighten corner radius preset types

acc5316

Storybook: Clarify optional corner radius type

4b2dcb5

Build: Add missing TypeScript project references

9b0675e

Theme: Reclassify private API changelog entry

cf72026

UI: Reuse lock-unlock helper

54eb383

Theme: Clarify private hook deprecation message

1367e9d

Theme: Add CornerRadiusPreset changelog deprecation

2d11ce6

aduth approved these changes Jun 29, 2026

View reviewed changes

ciampo commented Jun 29, 2026

View reviewed changes

ciampo added 3 commits June 29, 2026 15:02

Theme: Remove root CornerRadiusPreset export

13cf1c4

Theme: Add CornerRadiusPreset breaking change

0fbd30d

Theme: Clean up compatibility metadata

0ef91a0

simison mentioned this pull request Jun 29, 2026

Private api docs: elaborate on how to add/deprecate private APIs between bundled and externalized packages #79634

Open

ciampo enabled auto-merge (squash) June 29, 2026 14:27

ciampo merged commit 9f77aaa into trunk Jun 29, 2026
54 of 62 checks passed

ciampo deleted the codex/theme-provider-public-bridge branch June 29, 2026 14:27

github-actions Bot added this to the Gutenberg 23.6 milestone Jun 29, 2026

bgrgicak modified the milestones: Gutenberg 23.6, Gutenberg 23.5 Jun 30, 2026

tyxla removed the Backport to Gutenberg RC Pull request that needs to be backported to a Gutenberg release candidate (RC) label Jun 30, 2026

ciampo mentioned this pull request Jun 30, 2026

Packages: Backport UI and theme release changelogs #79690

Merged

simison mentioned this pull request Jun 30, 2026

Theme: document as stable in storybook & readme #79700

Open

This was referenced Jul 2, 2026

Backport changelog and package version updates from NPM #79816

Open

Fix wp/latest release metadata #79821

Open

Uh oh!

Conversation

ciampo commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Use of AI Tools

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ciampo Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aduth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CGastrell commented Jun 29, 2026

Uh oh!

tyxla commented Jun 30, 2026

Uh oh!

ciampo commented Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ciampo commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading

ciampo Jun 29, 2026 •

edited

Loading