Composite: improve Storybook examples and clean up prop docs #64397
Conversation
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
ciampo
added
[Type] Developer Documentation
There was a problem hiding this comment.
Can we have a better description for this too? Suggestion:
diff --git a/packages/components/src/composite/stories/utils.tsx b/packages/components/src/composite/stories/utils.tsx
index febbffd00b..8ce0410bf7 100644
--- a/packages/components/src/composite/stories/utils.tsx
+++ b/packages/components/src/composite/stories/utils.tsx
@@ -9,7 +9,9 @@ import type { StoryContext } from '@storybook/react';
import type { CompositeStoreProps } from '../types';
/**
- * Renders a composite widget.
+ * Renders a widget based on the WAI-ARIA [`composite`](https://w3c.github.io/aria/#composite) role,
+ * which provides a single tab stop on the page and arrow key navigation through the
+ * focusable descendants.
*
* ```jsx
* const store = useCompositeStore();
Also a few docs nits I noticed (sorry to piggyback):
- The JSDoc/README snippets need to include the import statement (
import { Composite, useCompositeStore } from '@wordpress/components';). - The README contains a link to the Ariakit docs, which we should remove.
There was a problem hiding this comment.
Good points! I went ahead, implemented your suggestions:
- better composite description
- removed existing ariakit references from JSDocs and readmes
- added imports in all code examples
After that, I released that the prop description that came via Ariakit also referenced the ariakit website, other ariakit components / examples, or even other Composite props that we are not exposing. And therefore, I pushed a few more changes:
- instead of
Pick-ing prop types, I added them explicitly (still re-using the original type) so that I could re-write the prop description in the JSDoc. In the process, I also updated Storybook and README with the updated JSDocs (which are not much more complete and closer to the original, but without ariakit references)(ad9fbb4 and 929fb4c) - For correctness, I added explicit default values in our implementation to make sure that our runtime code is true to the default values that we declare in the docs (32dd868)
@tyxla :
They should not affect the component visually. That should be reflected in the props' description |
|
🤦 of course, that makes a lot of sense! Tests well and as expected ✅ Thanks! |
Instead of using Ariakit's definitions and descriptions, we use our own version, which a copy or Ariakit's without any references to Ariakit, its examples, or any other props that we don't expose.
Along the same fashion as the previous commit, setting explicit default values will give us more control when propagating ariakit changes, and will allows to stay true to our first-part props docs.
ciampo
force-pushed
the
feat/stabilize-composite/storybook
branch
from
33c485c to
ad9fbb4
Compare
ciampo
changed the title
|
Flaky tests detected in 162fd12. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/10322121415
|
* More clear tranform function comments * Add interactive controls * Add simpler default Storybook example * Improve `activeId`'s prop description * Add Groups example * CHANGELOG * Removed actions config in Storybook * Better composite description * Remove direct references to Ariakit's docs in JSDocs and README * Add import from `@wordpress/components` in all code snippets * useCompositeStore: update prop docs by using first-party docs Instead of using Ariakit's definitions and descriptions, we use our own version, which a copy or Ariakit's without any references to Ariakit, its examples, or any other props that we don't expose. * useCompositeStore: set explicit default values Along the same fashion as the previous commit, setting explicit default values will give us more control when propagating ariakit changes, and will allows to stay true to our first-part props docs. * Remove unnecessary space * Provide first-party prop descriptions also for other composite components * Add default value for store props to avoid errors while destructuring --- Co-authored-by: ciampo <[email protected]> Co-authored-by: mirka <[email protected]> Co-authored-by: tyxla <[email protected]>
What?
Follow-up to #63564
Improve Storybook examples for the
Compositecomponent.Why?
Better documentation for
CompositeHow?
Testing Instructions
Open Storybook, go to the
Compositecomponent:This PR doesn't include runtime changes to the actual component.