Document @wordpress/components structure
#33111
Comments
sarayourfriend
added
[Status] In Progress
|
skorasaurus
added
the
[Type] Developer Documentation
|
@ciampo When you have time to review my indications, please do! Thanks! |
|
Hey @sarayourfriend, I agree with your proposal of splitting the components into "low-level" UI primitives and "high-level" UI blocks, but I'm finding it hard to draw a line between the 2 groups. I also compared the list from your comment above against the contents of A few components seem to be missing:
Finally, while reviewing your work I took some notes and prepared the following questions:
|
I think we should focus on web first, just to keep it with what we're already familiar with at least. Native can follow the lead once we've hammered out the details for the web components, which is already a big task.
I don't think so, they're just HoCs.
StyleProvider should be mentioned as a primitive or maybe one of the "in between/utility" ones (I think there's a few of these, maybe Draggable and Disabled count as these as well)
I don't think we should document anything we don't have control over.
I don't think we'll find that the sub-components are different than the parents. They work together. If
I believe that we are 🙂
They'll eventually be moved out of that folder so I believe yes they should be.
We don't refactor just to refactor, I think we should leave it alone.
We can open a separate task for those. View however is internal and should not have a README.
No. This is meant to document the external structure of the package to make it easier for block developers to know what to use.
Probably we shouldn't spend time on deprecated components. |
|
Thank you for clarifying! I went ahead and added
Makes sense. The same should apply for the contents of
Yes, we should probably create a third category for "non-UI" utils.
I agree with that, I was just wondering if, when listing a component (e.g.
I went ahead and created #33263 to track this task
Makes sense — I believe that
If we are not listing deprecated components, I believe we should also remove |
|
Great! I update the list to call out some things I think are utils. Do you mind having another review of it? |
|
The list looks good! I'm just still having a hard time finding a clear way to define UI primitives vs UI blocks |
|
@sarayourfriend is there work to be done for this issue? Related: #48998 |
|
Hey @ryanwelcher , this is still something that we'd like to explore at some point. Perhaps, as we look into rewriting some of our components using headless component libraries, we could tidy the package up a bit — which would also include documenting its structure after the tidy up. |
|
👋 I'm planning on picking up some of this work to move the project forward, and wanted to share some initial thoughts (mostly so Future Me has somewhere to find them 😆 ). Thank you for laying such a solid foundation @sarahmonster, that list you made is a huge head start.
Two potential alternatives:
Knowing the list on this issue is already a couple of years old, I've gone through to check for any new or moved components that need to be added. I didn't find a ton, but here they are, with how I'd classify them. If that makes sense (cc @ciampo), I can add them to the official list above.
My logic/reasoning on which of those belongs in which category may not be rock solid, and it's likely something that will shift as this work continues and we formalize the differences and definitions, but if anyone has strong opinions before I add them to the main list above, please let me know! Items I'm planning to remove from the list:
|
|
Adding my thoughts before we continue 🙂 GroupingsAssuming that the point of these groupings is to help a developer find what they need, I don't think that a low-level/high-level classification is necessarily the best way. It can be difficult to predict whether a thing you're looking for is primitive or composed if you have no idea how they're implemented. One iterative approach I might suggest is to not try and classify everything all at once, but to identify a group of commonly used components and start with that. For example, make a group for the "Controls" (aka "Inputs" or "Forms"). We can take inspiration from Chakra or MUI for more common groupings. Just having this one grouping will already make life easier for the vast majority because most devs are looking for form components. How the groupings are manifestedI suggest we start by expressing these groupings only in the Storybook, not in actual codebase folder structure or readme files. This will help us stay agile with our groupings, since we will likely find better ways of classification as things change. Our efforts here should be as low-stakes as possible, rather than high-stakes commitment to a classification system set in stone. Experimental componentsAs we start doing functional groupings in the Storybook, I think we should remove the "Experimental" grouping and instead suffix the experimental components with a 🧪 emoji. |
|
That sounds logical to me, but I'll hold off on actually grouping things until we've had a chance to discuss further. I do really like the idea of moving experimental components into the groupings they'd naturally exist in and just highlighting/labelling them individually as experiments. That will make them much easier to identify and locate! One question that I know was raised in the individual issue was guidance on how to use or interact with a given component, specifically in terms of |
|
For the short term, I agree with @mirka 's suggestion to work iteratively and:
We can discuss those new groupings directly in this issue. In the long term, I'd like to find a better way to showcase the offering of components to consumers of the package. There are many ways to achieve this, and low-level primitives vs high-level block is just one of them. In the future, I'd also like to investigate further how we document our components. One idea that I have in mind is to use Storybook as our canonical way to publish documentation, and then find a way to mirror the same information in READMEs (maybe by statically exporting the Storybook docs pages?).
We could start by adding a section in the package's README about it? At a high level, it sounds like the topics to cover would be:
(Although this would definitely need to get fact-checked) |
Here are some ideas to maintain existing permalinks when moving everything out of the "experimental" grouping. |
What problem does this address?
@wordpress/componentsis a package with roughly two (maybe even three, but I'm not sure) "levels" of components:Currently there is zero delineation between these two types of components. For block developers and other consumers of
@wordpress/componentsthis means there's no clear guidance as far as which components to use and when. Furthermore, there's no guidance around where and when to use things like thei18nlibrary for default values.On a very basic level, UI primitives are usually more complicated to use/have many more props, whereas UI blocks usually have very few props (probably an onChange, value, and some other minor configuration props). UI blocks also often times contain translated text, whereas UI primitives most often do not (instead opting for labels and other text to be passed in as props).
Documenting the difference between these two styles of components and classifying each of the components in
@wordpress/componentsunder one or the other could help future developers understand expectations as far as what technologies to use in each instance (particularly aroundi18n). It could also help consumers of@wordpress/componentsunderstand how to best utilize the library. If they just want to build an app with all new UI that looks and feels like WordPress but isn't powered by other WordPress technologies like@wordpress/i18n, then they can stick to the primitives alone and not worry about also having to adopt a whole new i18n solution. If they're working inside a WordPress environment already, then they can use the blocks as well to achieve seamless integration with Gutenberg.What is your proposed solution?
Document the above differences:
The text was updated successfully, but these errors were encountered: