Permalink
Browse files

Styleguide (#95)

  • Loading branch information...
nicolas-brousse authored and florentferry committed Feb 4, 2019
1 parent 8a61f6f commit 0f97be1a1c2dd88dbb6f9586b39443e81e5aa250
Showing with 588 additions and 49 deletions.
  1. +14 −0 .editorconfig
  2. +3 −3 .rubocop.yml
  3. +4 −0 CHANGELOG.md
  4. +29 −0 README.md
  5. +20 −0 app/controllers/komponent/styleguide_controller.rb
  6. +9 −0 app/views/komponent/styleguide/index.html.erb
  7. +3 −0 app/views/komponent/styleguide/missing_template.html.erb
  8. +1 −0 app/views/komponent/styleguide/show.html.erb
  9. +17 −0 app/views/layouts/komponent.html.erb
  10. +5 −0 config/routes.rb
  11. +5 −0 features/component_generator.feature
  12. +4 −0 lib/generators/component/component_generator.rb
  13. +3 −0 lib/generators/component/templates/examples.html.erb.erb
  14. +3 −0 lib/generators/component/templates/examples.html.haml.erb
  15. +3 −0 lib/generators/component/templates/examples.html.slim.erb
  16. +40 −0 lib/generators/komponent/examples_generator.rb
  17. +3 −37 lib/generators/komponent/install_generator.rb
  18. +41 −0 lib/generators/komponent/styleguide_generator.rb
  19. +3 −0 lib/generators/komponent/templates/styleguide/components/container/_komponent_container.html.erb
  20. +17 −0 lib/generators/komponent/templates/styleguide/components/container/komponent_container.css
  21. +1 −0 lib/generators/komponent/templates/styleguide/components/container/komponent_container.js
  22. +5 −0 lib/generators/komponent/templates/styleguide/components/container/komponent_container_component.rb
  23. +3 −0 lib/generators/komponent/templates/styleguide/components/footer/_komponent_footer.html.erb
  24. +27 −0 lib/generators/komponent/templates/styleguide/components/footer/komponent_footer.css
  25. +1 −0 lib/generators/komponent/templates/styleguide/components/footer/komponent_footer.js
  26. +5 −0 lib/generators/komponent/templates/styleguide/components/footer/komponent_footer_component.rb
  27. +3 −0 lib/generators/komponent/templates/styleguide/components/header/_komponent_header.html.erb
  28. +15 −0 lib/generators/komponent/templates/styleguide/components/header/komponent_header.css
  29. +1 −0 lib/generators/komponent/templates/styleguide/components/header/komponent_header.js
  30. +5 −0 lib/generators/komponent/templates/styleguide/components/header/komponent_header_component.rb
  31. +4 −0 lib/generators/komponent/templates/styleguide/components/index.js
  32. +10 −0 lib/generators/komponent/templates/styleguide/components/sidebar/_komponent_sidebar.html.erb
  33. +43 −0 lib/generators/komponent/templates/styleguide/components/sidebar/komponent_sidebar.css
  34. +1 −0 lib/generators/komponent/templates/styleguide/components/sidebar/komponent_sidebar.js
  35. +5 −0 lib/generators/komponent/templates/styleguide/components/sidebar/komponent_sidebar_component.rb
  36. +2 −0 lib/generators/komponent/templates/styleguide/packs/komponent.js
  37. +49 −0 lib/generators/komponent/utils.rb
  38. +2 −2 lib/komponent.rb
  39. +55 −0 lib/komponent/component.rb
  40. +6 −6 lib/komponent/component_path_resolver.rb
  41. +17 −1 lib/komponent/{railtie.rb → engine.rb}
  42. +28 −0 lib/komponent/komponent_helper.rb
  43. +46 −0 test/komponent/component_test.rb
  44. +27 −0 test/komponent/komponent_helper_test.rb
@@ -0,0 +1,14 @@
; top-most EditorConfig file
root = true

; Unix-style newlines
[*]
end_of_line = LF
indent_style = space
indent_size = 2
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false
@@ -54,9 +54,6 @@ Naming/PredicateName:
Naming/VariableName:
Enabled: true

Lint/DeprecatedClassMethods:
Enabled: true

Layout/AlignParameters:
Enabled: true

@@ -117,3 +114,6 @@ Layout/SpaceInsideParens:

Layout/TrailingWhitespace:
Enabled: true

Lint/DeprecatedClassMethods:
Enabled: true
@@ -7,6 +7,10 @@

**Enhancements:**
- Komponent now reports component stats when you run `bin/rails stats`
- Komponent now includes a styleguide engine that you can mount to your project
to document your components, and 2 new generators:
- `rails g komponent:styleguide` to set it up
- `rails g komponent:examples` to generate an `examples` file for each existing component

**Bug fixes:**
- Removed redundant `class` attribute in HAML templates
@@ -34,6 +34,7 @@ This gem has been inspired by our Rails development practices at [Ouvrages](http
- [Stimulus integration](#stimulus-integration)
- [Internationalization](#internationalization)
- [Available locales configuration](#available-locales-configuration)
- [Styleguide](#styleguide)
- [Configuration](#configuration)
- [Change default root path](#change-default-root-path)
- [Default options for the generators](#default-options-for-the-generators)
@@ -313,6 +314,34 @@ I18n.available_locales = [:en, :fr]
> If you have the `rails-i18n` gem in your `Gemfile`, you should whitelist locales to prevent creating a lot of
> locale files when you generate a new component.
### Styleguide

Komponent includes a basic styleguide engine that you can use in your project to document your components.

![Komponent styleguide UI](https://user-images.githubusercontent.com/38524/41193700-45909330-6c10-11e8-87b7-59e628529200.png)

To set it up, you can use the generator:

```sh
rails generate komponent:styleguide
```

This command will:

* copy the styleguide components (`komponent/container`, `komponent/footer`, `komponent/header` and `komponent/sidebar`) to your components folder, so you can customize them
* add a new `komponent.js` pack to your packs folder
* mount the engine in your routes

Then, for each component, you can describe it and render examples for each state in the `_example.html.slim` file from the component folder. The engine will then render it on the component page.

If you have existing components, you can generate all their example files at once with:

```sh
rails generate komponent:examples
```

Finally, visit `http://localhost:3000/styleguide` to access your styleguide.

### Configuration

#### Change default root path
@@ -0,0 +1,20 @@
# frozen_string_literal: true

module Komponent
class StyleguideController < ::ApplicationController
layout 'komponent'
rescue_from ActionView::MissingTemplate, with: :missing_template

def index; end

def show
@component = Komponent::Component.find(params[:id])
end

private

def missing_template
render 'komponent/styleguide/missing_template', status: :not_found
end
end
end
@@ -0,0 +1,9 @@
<h1>Styleguide</h1>

<% if components.any? %>
<p>Select one of the components from the side to view its examples and documentation.</p>
<% else %>
<p><<strong>Hint:</strong> You haven't created any component yet</h2>
<p>You can generate your first component by running:</p>
<pre>rails generate component component-name</pre>
<% end %>
@@ -0,0 +1,3 @@
<h1>Examples missing</h1>

<p>Please create <code><%= @component.path %>/_examples.html.<%= Rails.application.config.app_generators.rails[:template_engine] || :erb %></code> file.</p>
@@ -0,0 +1 @@
<%= render partial: @component.examples_view %>
@@ -0,0 +1,17 @@
<!DOCTYPE html>
<html>
<head>
<title>Styleguide</title>
<%= javascript_pack_tag 'komponent' %>
<%= stylesheet_pack_tag 'komponent', media: 'all' %>
<%= csrf_meta_tags %>
</head>
<body>
<%= c 'komponent/header' %>
<%= c 'komponent/sidebar' %>
<%= c 'komponent/container' do %>
<%= yield %>
<% end %>
<%= c 'komponent/footer' %>
</body>
</html>
@@ -0,0 +1,5 @@
# frozen_string_literal: true

Komponent::Engine.routes.draw do
resources :styleguide, only: %i[index show]
end
@@ -11,6 +11,7 @@ Feature: Component generator
| awesome_button/awesome_button.css |
| awesome_button/awesome_button.js |
| awesome_button/awesome_button_component.rb |
| awesome_button/_examples.html.erb |
And the file named "index.js" should contain:
"""
import "components/awesome_button/awesome_button";
@@ -30,6 +31,7 @@ Feature: Component generator
| admin/sub_admin/awesome_button/admin_sub_admin_awesome_button.css |
| admin/sub_admin/awesome_button/admin_sub_admin_awesome_button.js |
| admin/sub_admin/awesome_button/admin_sub_admin_awesome_button_component.rb |
| admin/sub_admin/awesome_button/_examples.html.erb |
And the file named "index.js" should contain:
"""
import "components/admin";
@@ -117,6 +119,7 @@ Feature: Component generator
When I run `rails generate component AwesomeButton`
And I cd to "frontend/components/awesome_button"
Then a file named "_awesome_button.html.erb" should exist
And a file named "_examples.html.erb" should exist

Scenario: Generate component with custom template engine defined to `haml`
Given a file named "config/initializers/custom_configuration.rb" with:
@@ -126,6 +129,7 @@ Feature: Component generator
When I run `rails generate component AwesomeButton`
And I cd to "frontend/components/awesome_button"
Then a file named "_awesome_button.html.haml" should exist
And a file named "_examples.html.haml" should exist

Scenario: Generate component with custom template engine defined to `slim`
Given a file named "config/initializers/custom_configuration.rb" with:
@@ -135,6 +139,7 @@ Feature: Component generator
When I run `rails generate component AwesomeButton`
And I cd to "frontend/components/awesome_button"
Then a file named "_awesome_button.html.slim" should exist
And a file named "_examples.html.slim" should exist

Scenario: Generate component with custom stylesheet engine defined to `scss`
Given a file named "config/initializers/custom_configuration.rb" with:
@@ -34,6 +34,10 @@ def create_locale_files
end
end

def create_examples_view_file
template "examples.html.#{template_engine}.erb", component_path + "_examples.html.#{template_engine}"
end

def import_to_packs
root_path = default_path
base_path = root_path + "components"
@@ -0,0 +1,3 @@
<h1><%= @component_name %></h1>

<%%= cdoc "<%= component_name %>" %>
@@ -0,0 +1,3 @@
%h1 <%= @component_name %>

= cdoc "<%= component_name %>"
@@ -0,0 +1,3 @@
h1 <%= @component_name %>

= cdoc "<%= component_name %>"
@@ -0,0 +1,40 @@
# frozen_string_literal: true

require 'komponent/component'
require File.expand_path('../utils', __FILE__)

module Komponent
module Generators
class ExamplesGenerator < Rails::Generators::Base
include Utils

source_root File.expand_path('../../component/templates', __FILE__)

def create_examples_files
Komponent::Component.all.each do |name, component|
create_examples_view_file(name)
end
end

protected

def split_name(name)
name.split(/[:,::,\/]/).reject(&:blank?).map(&:underscore)
end

def component_path(component_name)
path_parts = [default_path, 'components', *split_name(component_name)]

Pathname.new(path_parts.join('/'))
end

private

def create_examples_view_file(component_name)
@component_name = split_name(component_name).last.underscore

template "examples.html.#{template_engine}.erb", component_path(component_name) + "_examples.html.#{template_engine}"
end
end
end
end
@@ -1,8 +1,11 @@
# frozen_string_literal: true
require File.expand_path('../utils', __FILE__)

module Komponent
module Generators
class InstallGenerator < Rails::Generators::Base
include Utils

class_option :stimulus, type: :boolean, default: false

def check_webpacker_dependency
@@ -80,14 +83,6 @@ def application_pack_path
komponent_root_directory.join("packs", "application.js")
end

def komponent_root_directory
default_path
end

def components_directory
Rails.root.join(komponent_root_directory, "components")
end

def webpacker_configuration_file
Rails.root.join("config", "webpacker.yml")
end
@@ -96,10 +91,6 @@ def webpacker_default_structure
Rails.root.join("app", "javascript")
end

def komponent_already_installed?
File.directory?(relative_path_from_rails)
end

def dependencies_not_met_error_message
"Seems you don't have webpacker installed in your project. Please install webpacker, and follow instructions at https://github.com/rails/webpacker"
end
@@ -108,31 +99,6 @@ def stimulus?
return options[:stimulus] if options[:stimulus]
komponent_configuration[:stimulus]
end

def default_path
rails_configuration.komponent.root
end

def relative_path_from_rails
default_path.relative_path_from(Rails.root)
end

private

def komponent_configuration
{
stimulus: nil,
locale: nil,
}.merge(app_generators.komponent)
end

def rails_configuration
Rails.application.config
end

def app_generators
rails_configuration.app_generators
end
end
end
end
@@ -0,0 +1,41 @@
# frozen_string_literal: true

require File.expand_path('../utils', __FILE__)

module Komponent
module Generators
class StyleguideGenerator < Rails::Generators::Base
include Utils

source_root File.expand_path('../templates/styleguide', __FILE__)

def check_komponent_dependency
unless komponent_already_installed?
raise Thor::Error, dependencies_not_met_error_message
end
end

def copy_styleguide_components
directory 'components', components_directory.join('komponent')
end

def create_komponent_pack
template 'packs/komponent.js', komponent_pack_path
end

def append_to_application_routes
route 'mount Komponent::Engine => \'/\' if Rails.env.development?'
end

protected

def komponent_pack_path
komponent_root_directory.join('packs', 'komponent.js')
end

def dependencies_not_met_error_message
'Seems you don\'t have komponent installed in your project. Please install komponent, and follow instructions at https://github.com/komposable/komponent'
end
end
end
end
@@ -0,0 +1,3 @@
<div class="komponent-container">
<%= yield %>
</div>
@@ -0,0 +1,17 @@
/* stylelint-disable value-list-comma-newline-after */

.komponent-container {
font-size: 16px;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
margin: 40px 60px 0 300px;

.komponent-code {
background-color: #333;
color: #fff;
margin: 10px 0;
padding: 10px;
}
}

/* stylelint-enable */
@@ -0,0 +1 @@
import "./komponent_container.css";
@@ -0,0 +1,5 @@
# frozen_string_literal: true

module KomponentContainerComponent
extend ComponentHelper
end
@@ -0,0 +1,3 @@
<div class="komponent-footer">
Built with <%= link_to "Komponent", "http://komponent.io", target: "_blank" %>
</div>
Oops, something went wrong.

0 comments on commit 0f97be1

Please sign in to comment.