storybook_rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3156e720148b32541cf3a26364ab48422d8578c0f77ed0a5af2b79d6464c389c
+  data.tar.gz: 5c8aca3a712de9a7b937967629e465cac1319f339163f3a3e81fcd6877098ac6
+SHA512:
+  metadata.gz: 1f4973da1272dfb432b3a6cbd8d9fc09430aad699887885f947550c95a6a5045e520c4cf200c2f34b876fb553e4e257d53a32efb5bb173dbaf3653078374d940
+  data.tar.gz: 277c3bf438cc3f5f438072abd7066a76d4b4242e3754d7b0d24cc48123afd037de985aff8a996b146bfb016b1af91b239c580cd6d5ac460d2269db3ddea6835c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Jon Palmer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,223 @@
+# storybook_rails
+
+The `storybook_rails` gem provides a Ruby DSL for writing Storybook stories, allowing you to develop, preview, and test standard Rails view partials in [Storybook](https://github.com/storybookjs/storybook/).
+
+## Prior Art
+This gem is a fork of [ViewComponent::Storybook](https://github.com/jonspalmer/view_component_storybook) and has been adapted to work with standard Rails view partials.
+
+## Features
+* A Ruby DSL for writing Stories describing standard Rails view templates/partials
+* A Rails controller backend for Storybook Server compatible with Storybook Controls Addon parameters
+* More to come...
+
+## Installation
+
+### Rails Installation
+
+1. Add the `storybook_rails` gem, to your Gemfile: `gem 'storybook_rails'`
+2. Run `bundle install`.
+3. Add `require "action_view/storybook/engine"` to `config/application.rb`
+4. Add `**/*.stories.json` to `.gitignore`
+
+#### Configure Asset Hosts
+
+If your views depend on Javascript, CSS or other assets served by the Rails application you will need to configure `asset_hosts`
+apporpriately for your various environments. For local development this is a simple as adding to `config/development.rb`:
+```ruby
+Rails.application.configure do
+  ...
+  config.action_controller.asset_host =  'http://localhost:3000'
+  ...
+end
+```
+Equivalent configuration will be necessary in `config/production.rb` or `application.rb` based you your deployment environments.
+
+### Storybook Installation
+
+1. Add Storybook server as a dev dependedncy. The Storybook Controls addon isn't needed but is strongly recommended
+   ```sh
+   yarn add @storybook/server @storybook/addon-controls --dev
+   ```
+2. Add an NPM script to your package.json in order to start the storybook later in this guide
+   ```json
+   {
+     "scripts": {
+       "storybook": "start-storybook"
+     }
+   }
+   ```
+3. Create the .storybook/main.js file to configure Storybook to find the json stories the gem creates. Also configure the Controls addon:
+   ```javascript
+   module.exports = {
+     stories: ['../test/components/**/*.stories.json'],
+     addons: [
+       '@storybook/addon-controls',
+     ],
+   };
+   ```
+4. Create the .storybook/preview.js file to configure Storybook with the Rails application url to call for the html content of the stories
+   ```javascript
+
+   export const parameters = {
+     server: {
+       url: `http://localhost:3000/storybook`,
+     },
+   };
+   ```
+
+#### Webpacker
+If your application uses Webpacker to compile your JavaScript and/or CSS, you will need to modify the default Storybook webpack configuration. Please see the [Storybook Webpack config](https://storybook.js.org/docs/react/configure/webpack) for more information on how to do that. Here's an example:
+
+```javascript
+// .storybook/main.js
+
+const path = require('path');
+const environment = require('../config/webpack/environment');
+const { merge } = require('webpack-merge');
+
+module.exports = {
+  webpackFinal: async (config, { configType }) => {
+    // `configType` has a value of 'DEVELOPMENT' or 'PRODUCTION'
+    // You can change the configuration based on that.
+    // 'PRODUCTION' is used when building the static version of storybook.
+    let envConfig = environment.toWebpackConfig();
+
+    let entries = {
+      main: config.entry,
+      application: path.resolve(__dirname, '../app/javascript/packs/application.js')
+    }
+
+    config.entry = entries
+
+    // Storybook doesn't support .scss out of the box
+    config.module.rules.push({
+      test: /\.scss$/,
+      use: ['style-loader', 'css-loader', 'sass-loader'],
+      include: path.resolve(__dirname, '../'),
+    });
+
+    // merge Webpacker's config with Storybook's Webpack config
+    let merged = merge(config, {module: envConfig.module}, {plugins: envConfig.plugins}, {devtool: 'cheap-module-source-map'})
+
+    // Return the altered config
+    return config;
+  },
+};
+```
+
+## Usage
+
+### Writing Stories
+
+Suppose our app has a shared `app/views/shared/_button.html.erb` partial:
+
+```erb
+<% variant_class_map = {
+  primary: "button",
+  secondary: "button-secondary",
+  outline: "button-outline",
+} %>
+
+<button class="<%= variant_class_map[variant.to_sym] %>">
+  <%= button_text %>
+</button>
+```
+
+We can write a stories describing the `_button.html.erb` partial:
+
+```ruby
+# buttons/button_stories.rb
+
+class Buttons::ButtonStories < ActionView::Storybook::Stories
+  self.title = "Buttons"
+
+  story(:primary) do
+    controls do
+      text(:button_text, "Primary")
+    end
+  end
+
+  story(:secondary) do
+    controls do
+      text(:button_text, "Secondary")
+    end
+  end
+
+  story(:outline) do
+    controls do
+      text(:button_text, "Outline")
+    end
+  end
+end
+```
+
+And a story template to render individual stories:
+```erb
+# buttons/button_stories.html.erb
+
+<% story_name_class_map = {
+    primary: "button",
+    secondary: "button-secondary",
+    outline: "button-outline"
+  } %>
+
+<%= render partial: 'shared/button',
+    locals: { variant: story_params[:story_name], button_text: story_params[:button_text] } %>
+```
+
+It's up to you how handle rendering your partials in Storybook, but `storybook_rails` will look for a view template that matches the story name (`buttons/button_stories.html.erb` in the example above. In addition, `storybook_rails` provides a `story_params` helper which provides quick access to the params and args specified in the story config. You can use these parameters in your view template to render each story dynamically. Or not. It's up to you.
+
+### Generating Storybook Stories JSON
+
+Generate the Storybook JSON stories by running the rake task:
+```sh
+rake storybook_rails:write_stories_json
+```
+
+### Start the Rails app and Storybook
+
+In separate shells start the Rails app and Storybook
+
+```sh
+rails s
+```
+```sh
+yarn start-storybook
+```
+
+Alternatively you can use tools like [Foreman](https://github.com/ddollar/foreman) to start both Rails and Storybook with one command.
+
+### Configuration
+
+By Default `storybook_rails` expects to find stories in the folder `test/components/stories`. This can be configured but setting `config.storybook_rails.stories_path` in `config/applicaion.rb`. For example, if you're using RSpec you might set the following configuration:
+
+```ruby
+config.storybook_rails.stories_path = Rails.root.join("spec/components/stories")
+```
+
+### The Story DSL
+
+Coming Soon
+
+#### Parameters
+#### Layout
+#### Controls
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/danieldpence/storybook_rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the `storybook_rails` project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/danieldpence/storybook_rails/blob/master/CODE_OF_CONDUCT.md).

data/app/controllers/action_view/storybook/stories_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rails/application_controller"
+
+module ActionView
+  module Storybook
+    class StoriesController < Rails::ApplicationController
+      prepend_view_path File.expand_path("../../../views", __dir__)
+      prepend_view_path Rails.root.join("app/views") if defined?(Rails.root)
+      prepend_view_path Rails.application.config.storybook_rails.stories_path
+
+      before_action :find_stories, :find_story, only: :show
+      before_action :require_local!, unless: :show_stories?
+
+      content_security_policy(false) if respond_to?(:content_security_policy)
+
+      def show
+        story_params = @story.values_from_params(params.permit!.to_h)
+        story_params.deep_merge!(story_name: params[:story_name])
+
+        render template: "#{@story.template}", layout: @story.layout, locals: { story_params: story_params }
+      end
+
+      private
+
+      def show_stories?
+        ActionView::Storybook.show_stories
+      end
+
+      def find_stories
+        stories_name = params[:stories]
+        @stories = ActionView::Storybook::Stories.find_stories(stories_name)
+
+        head :not_found unless @stories
+      end
+
+      def find_story
+        story_name = params[:story]
+        @story = @stories.find_story(story_name)
+        head :not_found unless @story
+      end
+    end
+  end
+end

data/app/views/action_view/storybook/stories/show.html.erb

@@ -0,0 +1 @@
+<!-- Template rendered by host application -->

data/lib/action_view/storybook.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/dependencies/autoload"
+
+module ActionView
+  module Storybook
+    extend ActiveSupport::Autoload
+
+    autoload :Controls
+    autoload :Stories
+    autoload :StoryConfig
+    autoload :Dsl
+    autoload :Helpers
+
+    include ActiveSupport::Configurable
+    # Set the location of component previews through app configuration:
+    #
+    # config.storybook_rails.stories_path = Rails.root.join("app/views/storybook/stories")
+    #
+    mattr_accessor :stories_path, instance_writer: false
+
+    # Enable or disable component previews through app configuration:
+    #
+    # config.storybook_rails.show_stories = false
+    #
+    # Defaults to +true+ for development environment
+    #
+    mattr_accessor :show_stories, instance_writer: false
+
+    ActiveSupport.run_load_hooks(:storybook_rails, self)
+  end
+end

data/lib/action_view/storybook/controls.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "active_support/dependencies/autoload"
+
+module ActionView
+  module Storybook
+    module Controls
+      extend ActiveSupport::Autoload
+
+      autoload :ControlConfig
+      autoload :TextConfig
+      autoload :BooleanConfig
+      autoload :ColorConfig
+      autoload :NumberConfig
+      autoload :OptionsConfig
+      autoload :ArrayConfig
+      autoload :DateConfig
+      autoload :ObjectConfig
+    end
+  end
+end

data/lib/action_view/storybook/controls/array_config.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActionView
+  module Storybook
+    module Controls
+      class ArrayConfig < ControlConfig
+        attr_reader :separator
+
+        validates :separator, presence: true
+
+        def initialize(param, value, separator = ",", name: nil)
+          super(param, value, name: name)
+          @separator = separator
+        end
+
+        def type
+          :array
+        end
+
+        def value_from_param(param)
+          if param.is_a?(String)
+            param.split(separator)
+          else
+            super(param)
+          end
+        end
+
+        private
+
+        def csf_control_params
+          super.merge(separator: separator)
+        end
+      end
+    end
+  end
+end

data/lib/action_view/storybook/controls/boolean_config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActionView
+  module Storybook
+    module Controls
+      class BooleanConfig < ControlConfig
+        BOOLEAN_VALUES = [true, false].freeze
+
+        validates :value, inclusion: { in: BOOLEAN_VALUES }, unless: -> { value.nil? }
+
+        def type
+          :boolean
+        end
+
+        def value_from_param(param)
+          if param.is_a?(String) && param.present?
+            case param
+            when "true"
+              true
+            when "false"
+              false
+            end
+          else
+            super(param)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_view/storybook/controls/color_config.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActionView
+  module Storybook
+    module Controls
+      class ColorConfig < ControlConfig
+        attr_reader :preset_colors
+
+        def initialize(param, value, name: nil, preset_colors: nil)
+          super(param, value, name: name)
+          @preset_colors = preset_colors
+        end
+
+        def type
+          :color
+        end
+
+        private
+
+        def csf_control_params
+          params = super
+          params.merge(presetColors: preset_colors).compact
+        end
+      end
+    end
+  end
+end