Style guide view

[nicolas-brousse]

Do you think the gem could contain a style guide generator like mountain_view does? (Or kss)

Could be nice to have this kind of page, in development environment, that list all the components with some documentation and example(s).

[florentferry]

Hello,

I prefer to let users free to create their own styleguide page, it's simple to setup with a scaffold, and to customize with custom component wrapper. Each people have different needs in terms of layouts, styles and informations to show in styleguide. There are several ways to hydrate components in styleguide, from database, json files, or others.

We can add an entry in wiki to help guys make their own, but I see no advantage to make a generator for generic styleguide in Komponent.

[nicolas-brousse]

@florentferry I understand your point of view.

Yes, it could be fine to have a wiki page at least.

[Spone]

It's a good idea to think about it. Let's see how it can be implemented, then we can decide if we want to include it (or just document how to do it in the wiki).

How would we list the existing components?

1. We could list the folders in frontend/components (but it has to be recursive to support nested components)
2. We could parse the frontend/components/index.js file to extract the list of components.

What do you think?

[nicolas-brousse]

1. We could list the folders in frontend/components (but it has to be recursive to support nested components)

Looks like mountain_view simply use Dir.glob on components folder (https://github.com/devnacho/mountain_view/blob/master/app/helpers/mountain_view/styleguide_helper.rb#L31).

2. We could parse the frontend/components/index.js file to extract the list of components.

But what about the component helper methods and properties?

[Spone]

I think the first step is to get the list of components names (to build the styleguide navigation). We can use one of the two methods described above to achieve that.

Then, for each component, we need a list of examples to show how they can be used. I think the most flexible way would be to add a file to the component folder. It could be named examples.html.slim or usage.html.slim

It would contain the view to be rendered when you display the component in the styleguide (either as its own view, or as a partial if you want to display all components on the same page).

For instance, for a button you could have:

/ frontend/components/button/examples.html.slim

h1 Button

p This component displays a button element. It will be rendered as a `button` element, or a link if a `href` property is specified.

h2 As a button

= component "button", text: "Click here"

h2 As a link

= component "button", text: "Click here", href: "http://github.com"

h2 With a block

p This component accepts blocks for specifying the content of the button. You can use this to render an icon in the button.

= component "button", href: "http://github.com"
   = component "icon", icon: "close"
   | Close

[nicolas-brousse]

Sounds like a good idea. I was also thinking about a README.md file to have something also readable from a git repository in web view or simply in IDE. But it's more complicated to implement and more complicated, than simply list components folder and read an example.html.(slim|haml|erb) file if it exists.

If I have time this week, I think I could work on a PR draft if you want.

[Spone]

That would be awesome. In this case, we could include it with the gem as an optional engine that you can mount in your routes.rb (as Mountain View does).

This way, if you don't need the styleguide, just don't mount it. If you need the styleguide only in development your can mount it only if Rails.env.development?

[florentferry]

Seems good to me. :+1:

• Add an example template file when generating component (by default or with an option)
• Make a mountable engine with Komponent::StyleguideController handling responses
• Add a way to list all components in a project as an helper ?
• Add an index view listing all components
• Add a component view for each component

[nicolas-brousse]

Okay, sounds good. So I'll try to work on it in the next days if I found a bit of time. I'll keep in touch with you.