Introducing Semantic-UI-React-Storybook

[Maxhodges]

@levithomason @jlukic We've had to make a Semantic-UI dark theme for a new application we're making, and we've been developing and testing our React components with react-storybook, a wonderful tool that lets you develop and design React UI components without running your app. You just load your UI components into the React Storybook and start developing them. Thanks to hot reloading, we can design and iterate UI very quickly.

You can even deploy the whole storybook as a static app.

We're excited about stardust, but don't really see the point in writing React wrappers around the SUI modules which require jquery and semantic's javascript. Since you want to be jquery free eventually, why not start from the ground up?

We needed a progres bar for our SUI dark theme, but we wanted to avoid adding jquery so we made our own jquery-less Semantic-UI React Progress bar. We haven't added some of the behaviors yet, as they weren't needed. Some of the other things we needed, like the sidebar component, we were able to use other React components as a substitute.

We think Storybook would help you develop your components faster (it's certainly helped us), so we created a project with stories for our Progress bar component and added stories for the stardust Button component too. We think you should consider incorporating storybook in your project as a replacement for your docs guide. I think if you clone our repo and develop a component with it, you'll quickly see how it can accelerate the development process. If you add it to your repo I can help with migrating the stories of rest of your SUI components. Let us know if you have any questions.

Semantic-UI-React-Storybook

https://github.com/white-rabbit-japan/Semantic-UI-React-Storybook

We're hosting the storybook as a static site here on Github pages
https://white-rabbit-japan.github.io/Semantic-UI-React-Storybook/

[levithomason]

We're excited about stardust, but don't really see the point in writing React wrappers around the SUI modules which require jquery and semantic's javascript. Since you want to be jquery free eventually, why not start from the ground up?

Here at @TechnologyAdvice we use Stardust in production apps. Those apps were first built using React and SUI including the jQuery plugins. As you know, DOM manipulation is in opposition to React's virtual DOM. We initially thought we could marry the SUI JS lifecycle methods with the React Component lifecycle methods and gain the benefit of all the SUI JS features. This did in fact work, for a short time.

Once our applications grew so large and so dynamic, heavy issues began to arise trying to keep SUI jQuery DOM manipulations in sync with React's Virtual DOM. This got so bad, we had to face the facts. A rewrite of the SUI JS modules was necessary.

We must iteratively work ourselves away from jQuery. It is just not feasible to restart. Our production apps must migrate as we migrate Stardust. That said, I don't think migrating is slowing us down at all. We have to write jQuery free components one at a time, no matte the approach. It is just that we aren't going to remove the working jQuery Stardust modules all at once until there are jQuery free implementations completed.

Hopefully the back story helps explain where we are and where we're going here.

We needed a progres bar for our SUI dark theme, but we wanted to avoid adding jquery so we made our own jquery-less Semantic-UI React Progress bar.

I would love to have a PR for this 👍

We think you should consider incorporating storybook in your project as a replacement for your docs guide. I think if you clone our repo and develop a component with it, you'll quickly see how it can accelerate the development process.

In fact, I've already tested React Story book with Stardust a few months ago. I believe it was the day it was released. I really liked the idea behind .add()ing stories. There were also many things we'd have to give up with our current doc site if we were to move. I've tested out 2 more doc site approaches since. I have all 4 versions (storybook, the current site, the 2 new trials) cooking in my head.

Our first two priorities are to get our v1 API done and remove jQuery from our components. After this, I'll look back into the doc site and what improvements we can make there. It just may be that we extend Storybook to do what we need.

Thanks much @Maxhodges.

[Maxhodges]

@levithomason
Thanks for the back story. I can appreciate the situation better knowing how you got here. I looked around a bit more and can see your making good progress on the conversion. 

There were also many things we'd have to give up with our current doc site if we were to move.

Can you list a few things you feel you'd miss out on with storybook?  Maybe it's evolved since that early version you tried. We added an extension so you can write whatever supplemental text you want (in markdown) into your stories, along with writing out the component properties ("proptable"). If you let me know a few of your key needs I can look into solutions for you. 
Cheers,
Max

[levithomason]

I don't recall all the short comings, but our current docs handle:

• writing examples in actual js files, imports included. This let's us lint these examples and also render them exactly as end users would, making for very honest and complete example code. I'm not a fan of examples that lack all the required information.
• rendering the example files, and also stringifying / highlighting the example code. Similar to the SUI docs, there is a little code icon button for showing / hiding code.
• parsing prop types with react-docgen
• parsing doc blocks with doctrine. Includes resolving @see tags to link to related components (Select > Dropdown for example)
• generating links to source files on github
• generating links SUI docs for each component
• generating anchor links for examples

The "feature" I like most here isn't anything in this list, it is flexibility. Example, we'll be replacing our proprietary anchor links with anchors, this is a non issue since we have access to everything.

Lastly, the things we've been testing include variations of a component playground. These are either editable code in the examples, an in browser editor with autocomplete for trying components, or an auto generated form based on props and presets where you can try different component variations.

I'm not yet sold on any of these, more so, with the focus on v1 and dropping jQuery I don't have the time. I'd gladly review and PRs improving the doc site so long as we don't loose features in the process.

[levithomason]

@Maxhodges and any others landing here, I've pulled some of our other doc work into the open. See #427.