view_component-storybook 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd438eab6c92e5e41e9df2b06d53c5702cb9f3121e7af553a743512058c1ef2c
+  data.tar.gz: 66a3827dd5f7522da5fd429d79a2d1c590e26d142395ab757d57bb7eee391b76
+SHA512:
+  metadata.gz: be57cabc078e464195eee2ae30b63dfd8629807eea2c15e2dd260ac80e545104bce41b2e51d5aa71b429fc7504cf41e2fc018292a2088a70ce29d0d24c59369a
+  data.tar.gz: 27d2af2dcb91f2acf6c22b083130650e440330bbf649974a746f634e22e9e135f933342fe1a84302d0640b2498f8669fe0c5e39150a18a9a85e6b6cb0d386f51

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,21 @@
+# ViewComponent::Storybook
+
+The ViewComponent::Storybook gem provides Ruby api for writing stories describing [View Components](https://github.com/github/view_component) and allowing them to be previewed and tested in [Storybook](https://github.com/storybookjs/storybook/) via its [Server](https://github.com/storybookjs/storybook/tree/next/app/server) support.
+
+## Features
+
+- A Ruby DSL for writing Stories describing View Components
+- A Rails controller backend for Storybook Server compatible with Storybook Controls Addon parameters
+- Coming Soon: Rake tasks to watch View Components and Stories and trigger Storybook hot reloading
+
+## Documentation
+
+See [jonspalmer.github.io/view_component-storybook](https://jonspalmer.github.io/view_component-storybook) for documentation.
+
+## Contributing
+
+This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. We recommend reading the [contributing guide](./docs/CONTRIBUTING.md) as well.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/docs/CHANGELOG.md

@@ -0,0 +1,69 @@
+---
+layout: default
+title: Changelog
+---
+
+# Changelog
+
+## main
+
+## 0.12.1
+
+Last 0.x release
+* Prepare for renaming to `view_component-storybook` to align with Rubygems naming conventions and simpler installation.
+
+## 0.12.0
+
+* Allow configuration of story titles via new `stories_title_generator` configuration lambda
+* Added control descriptions
+* Fixed bug with autoload paths
+* Fixed Documentation typos
+
+## 0.11.1
+
+* Fix for stories_route by when using deprecated `require "view_component/storybook/engine"`
+
+## 0.11.0
+
+* Add support for dry-initializer
+* Validate Slots
+
+## 0.10.1
+
+* Allow Object Controls with arrays of simple values
+
+## 0.10.0
+
+* New Stories API
+  * `title` - custom stories title 
+  * `constructor` - component args
+  * `slot` - args and content for slots
+  * component and slot content accepts controls
+* New Controls
+  * Custom Control
+  * Klazz Control
+* Deprecated Controls DSL
+* Add support for Object Controls with array values
+* Remove ArrayConfig - array aliases Object
+* Updated Options Control to match Storybook 6.2 syntax
+  * `options` as array
+  * add `labels` option
+  * deprecate `options` as Hash
+  * multi select types accept and return array values
+* Improved validation errors with i18n support
+* Add `stories_route` config to configure stories endpoint
+* Jekyll docs
+
+## 0.9.0
+
+* Allow view helpers in content blocks
+
+## 0.8.0
+
+* Add support for components with keyword argument constructors
+
+## 0.7.0
+
+* Add inclusion validation to Number type
+* Support Objects with nested values
+* Support nil control values

data/lib/view_component/storybook/collections/controls_collection.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Collections
+      class ControlsCollection
+        include Collections::ValidForStoryConcern
+
+        attr_reader :controls
+
+        attr_accessor :code_object
+
+        def initialize
+          @controls = []
+        end
+
+        def add(param, as:, only: nil, except: nil, **opts)
+          controls << { param: param, as: as, only: only, except: except, **opts }
+        end
+
+        def for_story(story_name)
+          # build the controls for the story_name
+          # pass through a hash to get the last valid control declared for each param
+          controls.map do |opts|
+            next unless valid_for_story?(story_name, **opts.slice(:only, :except))
+
+            param = opts[:param]
+            unless opts.key?(:default)
+              opts = opts.merge(default: parse_default(story_name, param))
+            end
+            [param, build_control(param, **opts.except(:param, :only, :except))]
+          end.compact.to_h.values
+        end
+
+        private
+
+        def parse_default(story_name, param)
+          code_method = code_object.meths.find { |m| m.name == story_name }
+          default_value_parts = code_method.parameters.find { |parts| parts[0].chomp(":") == param.to_s }
+          return unless default_value_parts
+
+          code_method.instance_eval(default_value_parts[1])
+        end
+
+        def build_control(param, as:, **opts)
+          case as
+          when :text
+            Controls::Text.new(param, **opts)
+          when :boolean
+            Controls::Boolean.new(param, **opts)
+          when :number
+            Controls::Number.new(param, type: :number, **opts)
+          when :range
+            Controls::Number.new(param, type: :range, **opts)
+          when :color
+            Controls::Color.new(param, **opts)
+          when :object, :array
+            Controls::Object.new(param, **opts)
+          when :select
+            Controls::Options.new(param, type: :select, **opts)
+          when :multi_select
+            Controls::MultiOptions.new(param, type: :'multi-select', **opts)
+          when :radio
+            Controls::Options.new(param, type: :radio, **opts)
+          when :inline_radio
+            Controls::Options.new(param, type: :'inline-radio', **opts)
+          when :check
+            Controls::MultiOptions.new(param, type: :check, **opts)
+          when :inline_check
+            Controls::MultiOptions.new(param, type: :'inline-check', **opts)
+          when :date
+            Controls::Date.new(param, **opts)
+          else
+            raise "Unknonwn control type '#{as}'"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/collections/layout_collection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Collections
+      class LayoutCollection
+        include Collections::ValidForStoryConcern
+
+        def initialize
+          @default = nil
+          @layouts = []
+        end
+
+        def add(layout, only: nil, except: nil)
+          if only.nil? && except.nil?
+            @default = layout
+          else
+            layouts << { layout: layout, only: only, except: except }
+          end
+        end
+
+        # Parameters set for the story method
+        def for_story(story_name)
+          story_layout = default
+          layouts.each do |opts|
+            story_layout = opts[:layout] if valid_for_story?(story_name, **opts.slice(:only, :except))
+          end
+          story_layout
+        end
+
+        private
+
+        attr_reader :default, :layouts
+      end
+    end
+  end
+end

data/lib/view_component/storybook/collections/parameters_collection.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Collections
+      class ParametersCollection
+        include Collections::ValidForStoryConcern
+
+        def initialize
+          @all_paramsters = {}
+          @parameters = []
+        end
+
+        def add(params, only: nil, except: nil)
+          if only.nil? && except.nil?
+            all_paramsters.merge!(params)
+          else
+            parameters << { params: params, only: only, except: except }
+          end
+        end
+
+        # Parameters set for all stories
+        def for_all
+          all_paramsters
+        end
+
+        # Parameters set for the story method
+        def for_story(story_name)
+          parameters.each_with_object({}) do |opts, accum|
+            accum.merge!(opts[:params]) if valid_for_story?(story_name, **opts.slice(:only, :except))
+          end
+        end
+
+        private
+
+        attr_reader :all_paramsters, :parameters
+      end
+    end
+  end
+end

data/lib/view_component/storybook/collections/stories_collection.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Collections
+      class StoriesCollection
+        include Enumerable
+
+        delegate_missing_to :stories
+
+        attr_reader :stories
+
+        def load(code_objects)
+          @stories = Array(code_objects).map { |obj| StoriesCollection.stories_from_code_object(obj) }.compact
+        end
+
+        def self.stories_from_code_object(code_object)
+          klass = code_object.path.constantize
+          klass.code_object = code_object
+          klass
+        end
+
+        def self.stories_class?(klass)
+          return unless klass.ancestors.include?(ViewComponent::Storybook::Stories)
+
+          !klass.respond_to?(:abstract_class) || klass.abstract_class != true
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/collections/valid_for_story_concern.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Collections
+      module ValidForStoryConcern
+        extend ActiveSupport::Concern
+
+        def valid_for_story?(story_name, only:, except:)
+          (only.nil? || Array.wrap(only).include?(story_name)) && Array.wrap(except).exclude?(story_name)
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/collections.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "active_support/dependencies/autoload"
+
+module ViewComponent
+  module Storybook
+    module Collections
+      extend ActiveSupport::Autoload
+
+      autoload :ValidForStoryConcern
+      autoload :StoriesCollection
+      autoload :ControlsCollection
+      autoload :ParametersCollection
+      autoload :LayoutCollection
+    end
+  end
+end

data/lib/view_component/storybook/controls/base_options.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class BaseOptions < SimpleControl
+        attr_reader :type, :options, :labels
+
+        validates :type, :options, presence: true
+
+        def initialize(param, type:, options:, default: nil, labels: nil, name: nil, description: nil, **opts)
+          super(param, default: default, name: name, description: description, **opts)
+          @type = type
+          @options = options
+          @labels = labels
+        end
+
+        def to_csf_params
+          super.deep_merge(argTypes: { param => { options: options } })
+        end
+
+        private
+
+        def csf_control_params
+          labels.nil? ? super : super.merge(labels: labels)
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls/boolean.rb

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

data/lib/view_component/storybook/controls/color.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class Color < SimpleControl
+        attr_reader :preset_colors
+
+        def initialize(param, default: nil, preset_colors: nil, name: nil, description: nil, **opts)
+          super(param, default: default, name: name, description: description, **opts)
+          @preset_colors = preset_colors
+        end
+
+        def type
+          :color
+        end
+
+        private
+
+        def csf_control_params
+          super.merge(presetColors: preset_colors).compact
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls/control.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class Control
+        include ActiveModel::Validations
+
+        validates :param, presence: true
+
+        attr_reader :param, :name, :description, :default
+
+        def initialize(param, default:, name: nil, description: nil)
+          @param = param
+          @default = default
+          @name = name || param.to_s.humanize.titlecase
+          @description = description
+        end
+
+        def to_csf_params
+          # :nocov:
+          raise NotImplementedError
+          # :nocov:
+        end
+
+        def parse_param_value(value)
+          # :nocov:
+          raise NotImplementedError
+          # :nocov:
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls/date.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class Date < SimpleControl
+        def type
+          :date
+        end
+
+        def parse_param_value(value)
+          if value.is_a?(String)
+            DateTime.iso8601(value)
+          else
+            value
+          end
+        end
+
+        private
+
+        def csf_value
+          case default
+          when ::Date
+            default.in_time_zone
+          when Time
+            default.iso8601
+          end
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls/multi_options.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class MultiOptions < BaseOptions
+        TYPES = %i[multi-select check inline-check].freeze
+
+        validates :type, inclusion: { in: TYPES }, unless: -> { type.nil? }
+        validate :validate_default, unless: -> { options.nil? || default.nil? }
+
+        def initialize(param, type:, options:, default: nil, labels: nil, name: nil, description: nil, **opts)
+          super(param, type: type, options: options, default: Array.wrap(default), labels: labels, name: name, description: description, **opts)
+        end
+
+        def parse_param_value(value)
+          if value.is_a?(String)
+            value = value.split(',')
+            value = value.map(&:to_sym) if symbol_values
+          end
+          value
+        end
+
+        def to_csf_params
+          super.deep_merge(argTypes: { param => { options: options } })
+        end
+
+        private
+
+        def csf_control_params
+          labels.nil? ? super : super.merge(labels: labels)
+        end
+
+        def symbol_values
+          options.first.is_a?(Symbol)
+        end
+
+        def validate_default
+          errors.add(:default, :inclusion) unless default.to_set <= options.to_set
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls/number.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class Number < SimpleControl
+        TYPES = %i[number range].freeze
+
+        attr_reader :type, :min, :max, :step
+
+        validates :type, presence: true
+        validates :type, inclusion: { in: TYPES }, unless: -> { type.nil? }
+
+        def initialize(param, type:, default: nil, min: nil, max: nil, step: nil, name: nil, description: nil, **opts)
+          super(param, default: default, name: name, description: description, **opts)
+          @type = type
+          @min = min
+          @max = max
+          @step = step
+        end
+
+        def parse_param_value(value)
+          if value.is_a?(String) && value.present?
+            (value.to_f % 1) > 0 ? value.to_f : value.to_i
+          else
+            value
+          end
+        end
+
+        private
+
+        def csf_control_params
+          super.merge(min: min, max: max, step: step).compact
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls/object.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class Object < SimpleControl
+        def type
+          :object
+        end
+
+        def parse_param_value(value)
+          if value.is_a?(String)
+            parsed_json = JSON.parse(value)
+            if parsed_json.is_a?(Array)
+              parsed_json.map do |item|
+                item.is_a?(Hash) ? item.deep_symbolize_keys : item
+              end
+            else
+              parsed_json.deep_symbolize_keys
+            end
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls/options.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class Options < BaseOptions
+        TYPES = %i[select radio inline-radio].freeze
+
+        validates :type, inclusion: { in: TYPES }, unless: -> { type.nil? }
+        validates :default, inclusion: { in: ->(config) { config.options } }, unless: -> { options.nil? || default.nil? }
+
+        def parse_param_value(value)
+          if value.is_a?(String) && symbol_value
+            value.to_sym
+          else
+            value
+          end
+        end
+
+        def to_csf_params
+          super.deep_merge(argTypes: { param => { options: options } })
+        end
+
+        private
+
+        def csf_control_params
+          labels.nil? ? super : super.merge(labels: labels)
+        end
+
+        def symbol_value
+          @symbol_value ||= default.is_a?(Symbol)
+        end
+      end
+    end
+  end
+end