Merge branch 'master' of github.com:komposable/komponent into fix-ins…

…tall-generator

.editorconfig

@@ -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

.rubocop.yml

@@ -55,9 +55,6 @@ Naming/PredicateName:
 Naming/VariableName:
   Enabled: true
 
-Lint/DeprecatedClassMethods:
-  Enabled: true
-
 Layout/AlignParameters:
   Enabled: true
 
@@ -118,3 +115,6 @@ Layout/SpaceInsideParens:
 
 Layout/TrailingWhitespace:
   Enabled: true
+
+Lint/DeprecatedClassMethods:
+  Enabled: true

Appraisals

@@ -9,3 +9,7 @@ end
 appraise "rails-5.2.x" do
   gem "rails", "~> 5.2"
 end
+
+appraise "rails-6.0.x" do
+  gem "rails", "~> 6.0.0.beta1"
+end

CHANGELOG.md

@@ -8,6 +8,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

README.md

@@ -34,13 +34,15 @@ 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)
     - [Change default stylesheet engine](#change-default-stylesheet-engine)
     - [Force default templating engine](#force-default-templating-engine)
     - [Additional paths](#additional-paths)
 - [Contributing](#contributing)
+- [Releasing a new version](#releasing-a-new-version)
 - [License](#license)
 </details>
 
@@ -313,6 +315,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
@@ -425,10 +455,30 @@ resolved_paths:
   - engine/frontend
 ```
 
+## Running tests
+
+Run all Cucumber features and unit tests with `bundle exec appraisal rake test`
+
+Run the full test matrix with `bundle exec appraisal rake test`
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/komposable/komponent.
 
+## Releasing a new version
+
+- Update the CHANGELOG (add a title and a date for the new version)
+- Update the version number in `lib/komponent/version`
+- Install the `gem-release` gem if you haven't already
+- Run `gem release --tag --push`
+- Create or update the release on Github with the same version number and copy-paste the description from the CHANGELOG
+
+Please note:
+
+If you're releasing a patch version (eg. from 2.0.1 to 2.0.2) you can run `gem bump patch --release --tag --push --sign` so you don't have to manually change the version number.
+
+If you want to release a specific version (eg. beta, RC...), you can run `gem bump 3.0.0.beta1 --release --tag --push --sign`
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

app/controllers/komponent/styleguide_controller.rb

@@ -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

app/views/komponent/styleguide/index.html.erb

@@ -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 %>

app/views/komponent/styleguide/missing_template.html.erb

@@ -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>

app/views/komponent/styleguide/show.html.erb

@@ -0,0 +1 @@
+<%= render partial: @component.examples_view %>

app/views/layouts/komponent.html.erb

@@ -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>

config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Komponent::Engine.routes.draw do
+  resources :styleguide, only: %i[index show]
+end

features/component_generator.feature

@@ -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";
@@ -113,10 +115,39 @@ Feature: Component generator
     import "components/world/world";
     """
 
+  Scenario: relative `imports` in JavaScript files kept at the end when generating a component
+    When I cd to "frontend/components"
+    And a file named "index.js" with:
+    """
+    import "../a_relative_file.js";
+    import "../other_relative_file.js";
+    """
+    Then the file named "index.js" should contain:
+    """
+    import "../a_relative_file.js";
+    import "../other_relative_file.js";
+    """
+    When I run `rails generate component button`
+    Then the file named "index.js" should contain:
+    """
+    import "components/button/button";
+    import "../a_relative_file.js";
+    import "../other_relative_file.js";
+    """
+    When I run `rails generate component awesome_button`
+    Then the file named "index.js" should contain:
+    """
+    import "components/awesome_button/awesome_button";
+    import "components/button/button";
+    import "../a_relative_file.js";
+    import "../other_relative_file.js";
+    """
+
   Scenario: Generate component with `erb` template engine
     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 +157,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 +167,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:

gemfiles/rails_6.0.x.gemfile

@@ -0,0 +1,17 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 6.0.0.beta1"
+gem "rake", ">= 11.1"
+gem "rubocop", require: false
+gem "webpacker"
+
+group :test do
+  gem "aruba"
+  gem "cucumber"
+  gem "simplecov", require: false
+  gem "coveralls", require: false
+end
+
+gemspec path: "../"