Composite: stabilize new ariakit implementation #63564

ciampo · 2024-07-15T13:16:46Z

What?

Extracted from #63364

Part of #58850

Export the new ariakit-based Composite component from the @wordpress/components package.

Why?

The component has been available via private APIs for a while without causing issues. It's time to stabilize it!

How?

Renamed the component's exports following the compound components naming convention;
Updated all internal references to the component package, including private APIs;
Exported the new component from the @wordpress/components package
Updated storybook files
Added documentation where needed

Note: from the point of view of a consumer of @wordpress/components, this PR only adds new APIs and shouldn't require any code changes.

Follow-ups

Testing Instructions

No changes were made to how the component works, only to how it's exported / imported.

Smoke test that usages of the component both in Storybook and in the editor work as on trunk.

Reviewing commit-by-commit may help.

packages/components/src/alignment-matrix-control/index.tsx

ciampo · 2024-07-15T13:19:36Z

packages/components/src/circular-option-picker/types.ts

@@ -14,7 +14,7 @@ import type { Icon } from '@wordpress/icons';
 import type { ButtonAsButtonProps } from '../button/types';
 import type { DropdownProps } from '../dropdown/types';
 import type { WordPressComponentProps } from '../context';
-import type { CompositeStore } from '../composite/v2';
+import type { Store as CompositeStore } from '../composite';


Same as above for types — I went for Store as I expect consumers to consume this API as Composite.Store (or by aliasing the import like in this case)

packages/components/src/composite/current/stories/index.story.tsx

ciampo · 2024-07-15T13:24:33Z

packages/components/src/composite/legacy/stories/index.story.tsx

@@ -15,7 +15,8 @@ import {
 import { UseCompositeStatePlaceholder, transform } from './utils';

 const meta: Meta< typeof UseCompositeStatePlaceholder > = {
-	title: 'Components/Composite',
+	// TODO: should we keep this story around? If so, how should we call it?
+	title: 'Components/Composite/Legacy',


Probably @mirka is best-suited for the above TODO question. Also, see other comment on the current implementation's Storybook title

Maybe we should keep it like we keep other deprecated component stories (like Navigation)?

Yes, I think we should keep it as long as it's available in the package. As for how, my recommendation would be like this:

diff --git a/packages/components/src/composite/legacy/stories/index.story.tsx b/packages/components/src/composite/legacy/stories/index.story.tsx index 08eebc65ed..d3d3205afe 100644 --- a/packages/components/src/composite/legacy/stories/index.story.tsx +++ b/packages/components/src/composite/legacy/stories/index.story.tsx @@ -15,8 +15,8 @@ import { import { UseCompositeStatePlaceholder, transform } from './utils'; const meta: Meta< typeof UseCompositeStatePlaceholder > = { - // TODO: should we keep this story around? If so, how should we call it? - title: 'Components/Composite/Legacy', + title: 'Components (Deprecated)/Composite (Unstable)', + id: 'components-composite-unstable', component: UseCompositeStatePlaceholder, subcomponents: { // @ts-expect-error Storybook doesn't like overloaded exports as subcomponents diff --git a/packages/components/src/composite/legacy/stories/utils.tsx b/packages/components/src/composite/legacy/stories/utils.tsx index 06edd34863..2fb51c845f 100644 --- a/packages/components/src/composite/legacy/stories/utils.tsx +++ b/packages/components/src/composite/legacy/stories/utils.tsx @@ -8,6 +8,25 @@ import type { StoryContext } from '@storybook/react'; */ import type { LegacyStateOptions } from '..'; +/** + * Renders a composite widget. + * + * This unstable component is deprecated. Use `Composite` instead. + * + * ```jsx + * import { + * __unstableUseCompositeState as useCompositeState, + * __unstableComposite as Composite, + * __unstableCompositeItem as CompositeItem, + * } from '@wordpress/components'; + * + * const state = useCompositeState(); + * <Composite state={ state }> + * <CompositeItem>Item 1</CompositeItem> + * <CompositeItem>Item 2</CompositeItem> + * </Composite>; + * ``` + */ export function UseCompositeStatePlaceholder( props: LegacyStateOptions ) { return ( <dl>

The important points being:

It needs to be clear that we're referring to the __unstable version, and that it's deprecated.

Usually we want to ensure that we don't break permalinks, but in this specific case I think we would cause the less damage if we just made a clean break and changed the URLs so it reflects the new situation.

Sounds good, done in b3e58bc

packages/components/src/composite/current/stories/index.story.tsx

github-actions · 2024-07-15T13:35:04Z

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: mirka <[email protected]>

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

tyxla

Thanks for working on this one @ciampo! Excited about stabilizing the Ariakit version of Composite!

This looks and works great overall!

Left some comments and questions, some might be naive, so take them with a grain of salt 😉

packages/components/src/composite/legacy/index.tsx

packages/dataviews/src/layouts/list/index.tsx

packages/components/src/composite/README.md

packages/components/src/composite/stories/utils.tsx

packages/components/src/composite/stories/index.story.tsx

packages/components/src/composite/index.ts

packages/components/src/composite/stories/index.story.tsx

tyxla

This LGTM, and tests well 👍

I acknowledge that there are a bunch of follow-ups after merging this one, and that's more than fine. Smaller changes always win!

🚀

mirka

Waiting for an agreement on #63714, but just to add a concrete example to what I'm suggesting in #63714 (comment), I think Composite is a case where we don't need a .Root. The basic, default API should always start with MyComponent, and only when we need to provide a more low-level API in parallel, do we need a MyComponent.Root. Most consumers should never have to deal with a .Root. It's almost like the escape hatch for us as a component library. What do you think?

packages/components/src/composite/stories/index.story.tsx

packages/components/src/composite/index.ts

tyxla · 2024-07-20T09:46:30Z

Waiting for an agreement on #63714, but just to add a concrete example to what I'm suggesting in #63714 (comment), I think Composite is a case where we don't need a .Root. The basic, default API should always start with MyComponent, and only when we need to provide a more low-level API in parallel, do we need a MyComponent.Root. Most consumers should never have to deal with a .Root. It's almost like the escape hatch for us as a component library. What do you think?

Just pointing out that I agree with that and brought a similar point up previously in my review here.

ciampo · 2024-07-31T16:44:37Z

Hey @tyxla and @mirka , I updated the PR using the overloaded naming convention. Could you take another look?

tyxla

With a bunch of follow-ups to come as discussed earlier, this looks good to me! 🚀

Excited to see it stable!

tyxla · 2024-08-01T11:08:16Z

packages/components/src/composite/legacy/stories/index.story.tsx

@@ -15,7 +15,8 @@ import {
 import { UseCompositeStatePlaceholder, transform } from './utils';

 const meta: Meta< typeof UseCompositeStatePlaceholder > = {
-	title: 'Components/Composite',
+	// TODO: should we keep this story around? If so, how should we call it?
+	title: 'Components/Composite/Legacy',


Maybe we should keep it like we keep other deprecated component stories (like Navigation)?

…ect results in Storybook

Composite.Item should pick up the store from context without explicit prop

…call

ciampo · 2024-08-09T09:44:22Z

Thank you for the final round of review.

I've updated the README and marked the store prop on Composite as required as final tweaks.

I'll merge as soon as CI checks pass 🟢

github-actions · 2024-08-09T10:04:34Z

Flaky tests detected in c41ff65.
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/10317162077
📝 Reported issues:

[Flaky Test] passes the search value in the main inserter when clicking Browse all #45332 in /test/e2e/specs/editor/various/inserting-blocks.spec.js

* Point legacy exports directly to the source (instead of folder root) * Swap default folder export to new version * Apply compound component naming * Export new version from the package * Update (fix) private APIs exports * Update composite implementation to use new compound naming * Update references to Composite inside components package * Update Storybook entry points for both legacy and current * Fix Storybook generated docs * Add todo * Remove unncecessary code * CHANGELOG * README * Add JSDocs to Composite exports * Move current implementation out of `current` folder * Fix import in the legacy implementation * Update docs manifest * Fix type in Storybook example * Add JSDocs for Storybook docs * Apply Overloaded naming convention * Update README * Fix typo * Update legacy storybook title/id, make sure JSDocs refer to unstable version * Derive types instead of importing them directly from ariakit * Add JSDoc snippet for stable component * Remove unnecessary JSDoc code * Remove unnecessary display name * Assign display names via Object.assign to comply with TS and get correct results in Storybook * Update subcomponent TS ignore comment to align with other components * Remove unnecessary store prop in circular option picker Composite.Item should pick up the store from context without explicit prop * Add first-party types, rewrite components with one unique forwardRef call * Use the newly added types instead of using the Parameters<> util * Fix Storybook story type * Remove unnecessary ts-expect-error * Use `CompositeStore` type directly * Manual Storybook args table * Tweak display name fallback * README * Mark `store` prop on `Composite` as required --- Co-authored-by: ciampo <[email protected]> Co-authored-by: tyxla <[email protected]> Co-authored-by: mirka <[email protected]>

ciampo commented Jul 15, 2024

View reviewed changes

packages/components/src/alignment-matrix-control/index.tsx Outdated Show resolved Hide resolved

ciampo commented Jul 15, 2024

View reviewed changes

packages/components/src/composite/current/stories/index.story.tsx Outdated Show resolved Hide resolved

ciampo commented Jul 15, 2024

View reviewed changes

packages/components/src/composite/current/stories/index.story.tsx Show resolved Hide resolved

ciampo mentioned this pull request Jul 15, 2024

Make Ariakit Composite API standard #58850

Closed

3 tasks

ciampo self-assigned this Jul 15, 2024

ciampo added the [Package] Components /packages/components label Jul 15, 2024

ciampo requested a review from a team July 15, 2024 13:34

ciampo added the [Type] New API New API to be used by plugin developers or package users. label Jul 15, 2024

ciampo marked this pull request as ready for review July 15, 2024 13:34

ciampo requested a review from ajitbohra as a code owner July 15, 2024 13:34

This was referenced Jul 15, 2024

Composite: export new stable version, deprecate unstable version #63364

Closed

Composite: stabilize APIs #63569

Merged

Composite: deprecate legacy, unstable version #63572

Merged

ciampo requested review from ryanwelcher, juanmaguitar, fabiankaegy and ndiego as code owners July 15, 2024 14:55

tyxla reviewed Jul 18, 2024

View reviewed changes

tyxla approved these changes Jul 19, 2024

View reviewed changes

mirka reviewed Jul 20, 2024

View reviewed changes

packages/components/src/composite/stories/index.story.tsx Outdated Show resolved Hide resolved

packages/components/src/composite/index.ts Outdated Show resolved Hide resolved

ciampo force-pushed the feat/stabilize-composite/promote branch from 760fbb8 to fde527a Compare July 31, 2024 16:42

ciampo requested review from mirka and tyxla July 31, 2024 16:42

tyxla approved these changes Aug 1, 2024

View reviewed changes

ciampo added 16 commits August 9, 2024 11:43

Derive types instead of importing them directly from ariakit

ae1f17f

Add JSDoc snippet for stable component

e1ba58d

Remove unnecessary JSDoc code

ea4461b

Remove unnecessary display name

f8d6d18

Assign display names via Object.assign to comply with TS and get corr…

70bb89c

…ect results in Storybook

Update subcomponent TS ignore comment to align with other components

d91a679

Remove unnecessary store prop in circular option picker

68650df

Composite.Item should pick up the store from context without explicit prop

Add first-party types, rewrite components with one unique forwardRef …

0b4cb3e

…call

Use the newly added types instead of using the Parameters<> util

9bafd47

Fix Storybook story type

f511dc3

Remove unnecessary ts-expect-error

09c07af

Use CompositeStore type directly

db9d27d

Manual Storybook args table

918ae6a

Tweak display name fallback

7586d54

README

176314a

Mark store prop on Composite as required

c41ff65

ciampo force-pushed the feat/stabilize-composite/promote branch from e9e14e5 to c41ff65 Compare August 9, 2024 09:43

ciampo enabled auto-merge (squash) August 9, 2024 09:44

ciampo merged commit 22e4cc2 into trunk Aug 9, 2024
61 checks passed

ciampo deleted the feat/stabilize-composite/promote branch August 9, 2024 10:18

github-actions bot added this to the Gutenberg 19.1 milestone Aug 9, 2024

This was referenced Aug 9, 2024

Composite: improve Storybook examples and clean up prop docs #64397

Merged

Composite: add Hover and Typeahead subcomponents #64399

Merged

ciampo added the Needs Dev Note Requires a developer note for a major WordPress release cycle label Aug 12, 2024

This was referenced Aug 14, 2024

Composite v2: undo stabilizing new version #64510

Merged

@wordpress/components: high-level API strategy for compound components #63704

Open

fabiankaegy mentioned this pull request Oct 1, 2024

6.7 Dev Note Tracking Issue #65784

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Composite: stabilize new ariakit implementation #63564

Composite: stabilize new ariakit implementation #63564

ciampo commented Jul 15, 2024 •

edited

Loading

ciampo Jul 15, 2024

ciampo Jul 15, 2024

tyxla Aug 1, 2024

mirka Aug 1, 2024

ciampo Aug 8, 2024

github-actions bot commented Jul 15, 2024 •

edited

Loading

tyxla left a comment

tyxla left a comment

mirka left a comment

tyxla commented Jul 20, 2024

ciampo commented Jul 31, 2024

tyxla left a comment

tyxla Aug 1, 2024

ciampo commented Aug 9, 2024

github-actions bot commented Aug 9, 2024

Composite: stabilize new ariakit implementation #63564

Composite: stabilize new ariakit implementation #63564

Conversation

ciampo commented Jul 15, 2024 • edited Loading

What?

Why?

How?

Follow-ups

Testing Instructions

ciampo Jul 15, 2024

Choose a reason for hiding this comment

ciampo Jul 15, 2024

Choose a reason for hiding this comment

tyxla Aug 1, 2024

Choose a reason for hiding this comment

mirka Aug 1, 2024

Choose a reason for hiding this comment

ciampo Aug 8, 2024

Choose a reason for hiding this comment

github-actions bot commented Jul 15, 2024 • edited Loading

tyxla left a comment

Choose a reason for hiding this comment

tyxla left a comment

Choose a reason for hiding this comment

mirka left a comment

Choose a reason for hiding this comment

tyxla commented Jul 20, 2024

ciampo commented Jul 31, 2024

tyxla left a comment

Choose a reason for hiding this comment

tyxla Aug 1, 2024

Choose a reason for hiding this comment

ciampo commented Aug 9, 2024

github-actions bot commented Aug 9, 2024

ciampo commented Jul 15, 2024 •

edited

Loading

github-actions bot commented Jul 15, 2024 •

edited

Loading