Components: Remove "Experimental" designation

[mirka]

Related: Tracking: stabilization of @wordpress/components props

What problem does this address?

We used to designate a component as "Experimental" as a kind of backdoor to the back-compat policy, but since the policy was made more explicit and the Private API system was introduced, the "Experimental" has become meaningless. We will need to keep supporting them as regular, shipped components.

What is your proposed solution?

1. Add non-prefixed exports for all the __experimental prefixed exports. (We will still need to keep the prefixed versions for back-compat.)
2. Update all documentation so they don't include __experimental in the import statements.
3. In Storybook, move all the "Components (Experimental)" items into the main "Components" group. (Use the Storybook redirect mechanism in Storybook: Add mechanism to redirect moved stories #59181 to maintain permalinks.)

Note

This particular issue is only for the components themselves, not the __experimental props, which should be addressed separately.

PRs:

• AlignmentMatrixControl: Promote to stable #60913
• BorderBoxControl: Promote to stable #65586
• BorderControl: Promote to stable #65475
• BoxControl: Promote to stable #65469
• Navigator
  • Components: Assess stabilization of Navigator #60927
  • Navigator: simplify backwards navigation APIs #63317
  • Navigator: remove location history, simplify internal logic #64675
  • Navigator: fix isInitial, refine focusSelector logic #64786
  • Navigator: polish Storybook examples #64798
  • Navigator: add support for exit animation #64777
  • Navigator: internal refactor in preparation for stabilization #65671
  • Navigator: stabilize and export APIs #64613
  • Remove old links from Block Editor handbook: Navigator: stabilize and export APIs #64613 (comment)
  • Navigator: use stable export instead of experimental export #65753
  • Navigator: mark experimental exports as deprecated #65802
  • Write dev note
• Components: Assess stabilization of ConfirmDialog #61014;
• Deprecate DimensionControl #64951
• Components: Assess stabilization of Divider #61016;
• Components: Assess stabilization of Elevation #61017;
• Components: Assess stabilization of Grid #61018;
• Components: Assess stabilization of HStack #61019;
• Components: Assess stabilization of Heading #61020;
• Components: Assess stabilization of InputControl #61059;
• Components: Assess stabilization of ItemGroup #61060;
• Components: Assess stabilization of NumberControl #61061;
• Components: Make the ProgressBar public #61062;
• Components: Assess stabilization of Scrollable #61063;
• Components: Assess stabilization of Spacer #61064;
• Components: Assess stabilization of Surface #61065;
• Components: Assess stabilization of Text #61066;
• Components: Assess stabilization of ToggleGroupControl #61067;
• Components: Assess stabilization of ToolsPanel #61068;
• Components: Assess stabilization of TreeGrid #61069;
• Components: Assess stabilization of Truncate #61070;
• Components: Assess stabilization of UnitControl #61071;
• Tabs
  • Components: Assess stabilization of Tabs #61072
  • Components: Introduce a more composable V2 of the TabPanel #52997
• Components: Assess stabilization of VStack #61073;
• Components: Assess stabilization of View #61074;
• Components: Assess stabilization of ZStack #61075;
• Components: Assess stabilization of DropdownMenuV2 #61076;
• Components: Assess stabilization of Theme #61077;
• Components: Remove "experimental" designation for CustomSelectControlV2 #61078.

[youknowriad]

I think we should be careful here. Experimental APIs were introduced indeed in a time where they were not considered stable and any new experimental APIs will be considered stable but there's still an exception for the old experimental APIs. We have more room there to think about each component in isolation, how much it's used, whether it has an alternative, whether we should keep it or deprecate it.

In other words, I don't think we should be blindly renaming these components, we should only rename and stabilize the ones we're certain that we want to keep.

[mirka]

Yes, we will be using some discretion on a per-component basis, taking into account any alternatives and current usage levels 👍

[fullofcaffeine]

Thanks for sharing your thoughts, @youknowriad! I'll keep what you said in mind as I work through these, but could you clarify the following points?

how much it's used

What criterion do you have in mind here, and what would be the actions for each case? E.g for components that are not being used, should we just remove them or perhaps we should remove the __experimental prefix without keeping the backwards-compatibility deprecated export?

How do we confidently gauge the usage frequency of components? We can check references in the GB app/repo, but there might be consumers in third-party packages we are not aware of.

whether it has an alternative, whether we should keep it or deprecate it.

Alternatives within our own library of components? How do we decide between one of another? I assume API design/simplicity, features, and code quality/maintainability (i.e., is it a newer version?).

Thanks!

[youknowriad]

How do we confidently gauge the usage frequency of components?

In general I'd recommend using wpdirectory.net and check whether any plugins use the components (you have to dig through the results as some are false positives, plugins bundling Gutenberg).

I would recommend a deprecation for all the components regardless of the results:

• If there's a component that we want to remove and its usage is very low/inexistant, we should write a Dev note about it and add a "version" (like 4 WP versions from now or so)
• If a component is used, we'll probably have to keep it in the code base forever as deprecated (or at least for a very long time) but a Dev note can also help reduce its usage.

Before adding deprecations, we should first remove all existing usages from our own code base though.

[fullofcaffeine]

If there's a component that we want to remove and its usage is very low/inexistant, we should write a Dev note about it and add a "version" (like 4 WP versions from now or so)

Can you expand on the "add a "version" (like 4 WP versions from now or so)" part? Not sure I follow.

If a component is used, we'll probably have to keep it in the code base forever as deprecated (or at least for a very long time) but a Dev note can also help reduce its usage.

Makes sense. I think this is essentially what we're doing here: #60913 (for example). The only difference (apart from the lack of a dev note, see below) is that we're also deprecating using @deprecate tsdoc annotation in the same changeset, and you're suggesting only adding that after we change the imports within the GB codebase, right?

write a Dev note about it

How do I add a dev note? It's different from a changelog, right?

[youknowriad]

Can you expand on the "add a "version" (like 4 WP versions from now or so)" part? Not sure I follow.

There's a "version" argument you can add the "deprecated" function call to mark the version where the API is supposed to be removed. For instance 4 versions from now would be "6.9"

Makes sense. I think this is essentially what we're doing here: #60913 (for example). The only difference (apart from the lack of a dev note, see below) is that we're also deprecating using @deprecate tsdoc annotation in the same changeset, and you're suggesting only adding that after we change the imports within the GB codebase, right?

Yes, and we should be calling "deprecated" function as well to log the deprecation message in the console for plugin authors still using the API.

How do I add a dev note? It's different from a changelog, right?

Changelog is targeted towards package users, Dev notes are targeted towards WP plugins developers using the APIs through the scripts in WP. They're published before every WP major release. For PRs that require dev notes, you don't have to write the dev notes today, but you should be adding a "Needs Dev Note" label and you'll get pinged later when it's time to write the dev note.

[mirka]

@fullofcaffeine and I agreed on having some kind of prioritization here since there is a lot of work to be done. I attempted to group the experimental components into categories to help with priority and efficiency.

Controls

• AlignmentMatrixControl
• BorderBoxControl
• BorderControl
• BoxControl
• DimensionControl
• InputControl
• NumberControl
• ToggleGroupControl
• UnitControl

Layout

• Divider
• Elevation
• Grid
• HStack
• Scrollable
• Spacer
• Surface
• VStack
• View
• ZStack

Typography

• Heading
• Text
• Truncate

Misc

• ConfirmDialog
• DropdownMenuV2
• ItemGroup
• Navigator
• ProgressBar
• Tabs
• ToolsPanel
• TreeGrid

I think a good order would be to start with the Controls, since those are pretty straightforward and high impact. There are some prop tweaks that I want to discuss, and I'll note them in the individual PRs.

Next group would be Misc.

Layout and Typography, we should to first discuss and align on a long-term vision (with @DaniGuardiola too) before we decide what to do with individual components. At the moment, there is not enough clarity to say whether we want these types of components at all, and even if we do, what the APIs should look like ideally.