Open andrewn opened 4 years ago
.story
files - leaves components alone It seems like this doesn't work with React?
I think this project is for sharing components across projects by putting them into a library, which I don't think is necessary for the web editor.
found this comment relating Docz to Storybook, see whole thread
Also found this Front-end documentation post. Reading through this, I'm leaning towards React Styleguidist or Docx!
Storybook Learning curve - uses cutting-edge JavaScript that newer programmers may not be familiar with
What kind of "cutting edge" JavaScript do you mean? I've only used the same ES6/JSX when writing storybook stories.
I think a good next step would be to pick a fairly simple component that changes with different props (e.g. button) and try out our top-3 tools to see how it they work. It sounds like: Storybook, docz and React Styleguidist?
I've been setting up a component library on another project so had the opportunity to try out Docz and Storybook. Here are my thoughts.
I find that the Docz approach of writing MDX is less constrained, so better for a large style guide where there may be a lot of textual documentation for each component. For example:
Docz will fetch the props and comments from prop-types to describe the components. It will also embeds a code editor so you can edit the component code to see how the props change. But it's just a free-form text editor, which is flexible but not as nice as Storybook add-ons.
Overall, it felt that Docz has less add-ons.
I've mostly been using their Component Story Format (CDF) for writing stories. This is slightly more effort and structured, but I think that's maybe a good thing as it provides a template for everyone to follow.
Storybook has a lot of add-ons for adding things like accessibility checks, viewport resizing etc.
Storybook has a "knobs" add-on (click the "Knobs" tab at the bottom) that allow you to dynamically alter the props passed into the component. It's more work but gives you more control.
Storybook will also fetch the prop-types and comments and display them in a table.
The latest version also supports MDX, so you can do similar things to Docz if you want. It's not as mature yet, but it's interesting that this is also the direction they're going in.
I didn't try to set this up. Looking into the docs a bit more, I was concerned it was too "automatic" to work with a complex project.
@catarak I've opened two PRs #1244 (storybook) and #1294 (docz) for comparing the two component systems.
Both include a Button
component using styled-components
for comparison.
docz parses all the .md
files in the project and turns them into nicely formatted HTML which is a nice touch.
However, I think Storybook is a better tool for developing components, especially being able to switch the theme via the UI but I'm keen to hear what you think!
Thanks for trying out both of these options! Spent a bunch of time looking at your two PRs and I agree, I think Storybook is the way to go forward. Being able to change the themes is a huge plus, and the knobs are a nice feature as well.
I definitely want to try my own hand at making a story, but also I think we should spend some time thinking about we want to configure/design storybook. I was looking through the Storybook Examples and surprised by how different they are. Luckily the source is linked to in a lot of the examples so we could pull from those.
It's also really helpful to look at the examples for reference on how to actually make a component library 🙃
Storybook supports using "/" in titles to organise stories. The format is "Root/Group/Group/...". The groups can be nested arbitrarily, I think everything that doesn't contain actual stories turns into a folder.
The title "Components/Brand/RTL" would result in:
"without brand link", "with brand link", "with script link" are stories exported from the file with title Components/Brand
.
And "RTL - with brand link" is a story exported from the file with title Components/Brand/RTL
.
I'd suggest having a more consistent and shallower nesting for our component library:
<Root>/<Type>/ComponentName
Root:
client/components
client/modules/App
client/modules/IDE
client/modules/User
Type:
client/modules/*/pages/
client/modules/*/components
The aim is for Common to get bigger as we extract more reusable components from other parts of the app.
I'm not very convinced about Type
but I think it's simplest for the component library structure represents the file structure of the app. We might not create stories for the pages in the app.
I like this organization! I agree about the component organization being too nested, and I think this is more straightforward. As certain components are being moved off the main IDE view (like the sketches/collections) I wonder if it would make sense to have another folder. Or like... would that stuff go in "App"? What should go in "App"?
Also agree that pages don't need to have stories. I think it's the most important to have stories for the stuff in client/components
, as those are the things that new features would mainly be comprised of.
Nature of issue?
New feature details:
When developing features for the Editor, it can be challenging to figure out if the UI widget you need already exists in the project. If a component exists already, then copying it can cause subtle inconsistencies.
It'd be great to have a style guide in the projects that displays available components, and the different states they can be in. This should make the Editor more consistent, help reduce bugs and make contributing easier.
Possible choices
Considerations