view_component-storybook 1.0.0

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      ##
+      # A simple Control Config maps to one Storybook Control
+      # It has a value and pulls its value from params by key
+      class SimpleControl < Control
+        def initialize(param, default: nil, name: nil, description: nil, **opts)
+          super(param, default: default, name: name, description: description, **opts)
+        end
+
+        def to_csf_params
+          validate!
+          {
+            args: { param => csf_value },
+            argTypes: {
+              param => { control: csf_control_params, name: name, description: description }.compact
+            }
+          }
+        end
+
+        def parse_param_value(value)
+          value
+        end
+
+        private
+
+        # provide extension points for subclasses to vary the value
+        def type
+          # :nocov:
+          raise NotImplementedError
+          # :nocov:
+        end
+
+        def csf_value
+          default
+        end
+
+        def csf_control_params
+          { type: type }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    module Controls
+      class Text < SimpleControl
+        def type
+          :text
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/controls.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_support/dependencies/autoload"
+
+module ViewComponent
+  module Storybook
+    module Controls
+      extend ActiveSupport::Autoload
+
+      autoload :Control
+      autoload :SimpleControl
+      autoload :Text
+      autoload :Boolean
+      autoload :Color
+      autoload :Number
+      autoload :BaseOptions
+      autoload :Options
+      autoload :MultiOptions
+      autoload :Date
+      autoload :Object
+    end
+  end
+end

data/lib/view_component/storybook/engine.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "view_component"
+require "action_cable/engine"
+require "yard"
+
+module ViewComponent
+  module Storybook
+    class Engine < Rails::Engine
+      config.view_component_storybook = ActiveSupport::OrderedOptions.new
+      config.view_component_storybook.stories_paths ||= []
+
+      initializer "view_component_storybook.set_configs" do |app|
+        options = app.config.view_component_storybook
+
+        options.show_stories = Rails.env.development? if options.show_stories.nil?
+        options.stories_route ||= "/rails/stories"
+
+        if options.show_stories && (defined?(Rails.root) && Rails.root.join("test/components/stories").exist?)
+          options.stories_paths << Rails.root.join("test/components/stories").to_s
+
+        end
+
+        options.stories_title_generator ||= ViewComponent::Storybook.stories_title_generator
+
+        ActiveSupport.on_load(:view_component_storybook) do
+          options.each { |k, v| send("#{k}=", v) }
+        end
+      end
+
+      initializer "view_component_storybook.set_autoload_paths" do |app|
+        options = app.config.view_component_storybook
+
+        if options.show_stories && !options.stories_paths.empty?
+          paths_to_add = options.stories_paths - ActiveSupport::Dependencies.autoload_paths
+          ActiveSupport::Dependencies.autoload_paths.concat(paths_to_add) if paths_to_add.any?
+        end
+      end
+
+      initializer "view_component_storybook.parser.stories_load_callback" do
+        parser.after_parse do |code_objects|
+          Engine.stories.load(code_objects.all(:class))
+        end
+      end
+
+      config.after_initialize do
+        parser.parse
+      end
+
+      rake_tasks do
+        load File.join(__dir__, "tasks/view_component_storybook.rake")
+      end
+
+      def parser
+        @parser ||= StoriesParser.new(ViewComponent::Storybook.stories_paths)
+      end
+
+      class << self
+        def stories
+          @stories ||= Collections::StoriesCollection.new
+        end
+      end
+    end
+  end
+end
+
+# :nocov:
+unless defined?(ViewComponent::Storybook::Stories)
+  ActiveSupport::Deprecation.warn(
+    "This manually engine loading is deprecated and will be removed in v1.0.0. " \
+    "Remove `require \"view_component/storybook/engine\"`."
+  )
+
+  require "view_component/storybook"
+end
+# :nocov:

data/lib/view_component/storybook/stories.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    class Stories < ViewComponent::Preview
+      class << self
+        def title(title = nil)
+          @stories_title = title
+        end
+
+        def parameters(params, only: nil, except: nil)
+          parameters_collection.add(params, only: only, except: except)
+        end
+
+        def layout(layout, only: nil, except: nil)
+          layout_collection.add(layout, only: only, except: except)
+        end
+
+        def control(param, as:, **opts)
+          controls.add(param, as: as, **opts)
+        end
+
+        def stories_name
+          name.chomp("Stories").underscore
+        end
+
+        def preview_name
+          stories_name
+        end
+
+        def to_csf_params
+          csf_params = { title: stories_title }
+          csf_params[:parameters] = parameters_collection.for_all if parameters_collection.for_all.present?
+          csf_params[:stories] = stories.map(&:to_csf_params)
+          csf_params
+        end
+
+        def write_csf_json
+          File.write(stories_json_path, JSON.pretty_generate(to_csf_params))
+          stories_json_path
+        end
+
+        def stories
+          @stories ||= story_names.map { |name| Story.new(story_id(name), name, parameters_collection.for_story(name), controls.for_story(name)) }
+        end
+
+        # find the story by name
+        def find_story(name)
+          stories.find { |story| story.name == name.to_sym }
+        end
+
+        # Returns the arguments for rendering of the component in its layout
+        def render_args(story_name, params: {})
+          # mostly reimplementing the super method but adding logic to parse the params through the controls and find the layout
+          story_params_names = instance_method(story_name).parameters.map(&:last)
+          provided_params = params.slice(*story_params_names).to_h.symbolize_keys
+
+          story = find_story(story_name)
+
+          control_parsed_params = provided_params.to_h do |param, value|
+            control = story.controls.find { |c| c.param == param }
+            value = control.parse_param_value(value) if control
+
+            [param, value]
+          end
+
+          result = control_parsed_params.empty? ? new.public_send(story_name) : new.public_send(story_name, **control_parsed_params)
+          result ||= {}
+          result[:template] = preview_example_template_path(story_name) if result[:template].nil?
+          @layout = layout_collection.for_story(story_name.to_sym)
+          result.merge(layout: @layout)
+        end
+
+        attr_reader :code_object, :stories_json_path
+
+        def code_object=(object)
+          @code_object = object
+          @stories_json_path ||= begin
+            dir = File.dirname(object.file)
+            json_filename = object.path.demodulize.underscore
+
+            File.join(dir, "#{json_filename}.stories.json")
+          end
+
+          controls.code_object = object
+
+          # ordering of public_instance_methods isn't consistent
+          # use the code_object to sort the methods to the order that they're declared
+          @story_names = object.meths.select { |m| story_names.include?(m.name) }.map(&:name)
+        end
+
+        private
+
+        def controls
+          @controls ||= Collections::ControlsCollection.new
+        end
+
+        def stories_title
+          @stories_title ||= Storybook.stories_title_generator.call(self)
+        end
+
+        def parameters_collection
+          @parameters_collection ||= Collections::ParametersCollection.new
+        end
+
+        def layout_collection
+          @layout_collection ||= Collections::LayoutCollection.new
+        end
+
+        def story_names
+          @story_names ||= public_instance_methods(false)
+        end
+
+        def story_id(name)
+          "#{stories_name}/#{name.to_s.parameterize}".underscore
+        end
+      end
+    end
+  end
+end

data/lib/view_component/storybook/stories_parser.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "yard"
+
+module ViewComponent
+  module Storybook
+    class StoriesParser
+      def initialize(paths)
+        @paths = paths
+        @after_parse_callbacks = []
+        @after_parse_once_callbacks = []
+        @parsing = false
+
+        YARD::Parser::SourceParser.after_parse_list { run_callbacks }
+      end
+
+      def parse(&block)
+        return if @parsing
+
+        @parsing = true
+        @after_parse_once_callbacks << block if block
+        YARD::Registry.clear
+        YARD.parse(paths)
+      end
+
+      def after_parse(&block)
+        @after_parse_callbacks << block
+      end
+
+      attr_reader :paths
+
+      protected
+
+      def callbacks
+        [
+          *@after_parse_callbacks,
+          *@after_parse_once_callbacks
+        ]
+      end
+
+      def run_callbacks
+        callbacks.each { |cb| cb.call(YARD::Registry) }
+        @after_parse_once_callbacks = []
+        @parsing = false
+      end
+    end
+  end
+end

data/lib/view_component/storybook/story.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    class Story
+      attr_reader :id, :name, :parameters, :controls
+
+      def initialize(id, name, parameters, controls)
+        @id = id
+        @name = name
+        @parameters = parameters
+        @controls = controls
+      end
+
+      def to_csf_params
+        csf_params = { name: name, parameters: { server: { id: id } } }
+        csf_params.deep_merge!(parameters: parameters) if parameters.present?
+        controls.each do |control|
+          csf_params.deep_merge!(control.to_csf_params)
+        end
+        csf_params
+      end
+    end
+  end
+end

data/lib/view_component/storybook/tasks/view_component_storybook.rake

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+namespace :view_component_storybook do
+  desc "Write CSF JSON stories for all Stories"
+  task write_stories_json: :environment do
+    puts "Writing Stories JSON"
+    exceptions = []
+    ViewComponent::Storybook::Engine.stories.each do |stories|
+      json_path = stories.write_csf_json
+      puts "#{stories.name} => #{json_path}"
+    rescue StandardError => e
+      exceptions << e
+    end
+
+    raise StandardError, exceptions.map(&:message).join(", ") if exceptions.present?
+
+    puts "Done"
+  end
+
+  desc "Remove all existing CSF JSON Stories"
+  task remove_stories_json: :environment do
+    puts "Removing old Stories JSON"
+    exceptions = []
+    Dir["#{ViewComponent::Storybook.stories_path}/**/*.stories.json"].sort.each do |file|
+      puts file
+      File.unlink(file)
+    rescue StandardError => e
+      exceptions << e
+    end
+
+    raise StandardError, exceptions.map(&:message).join(", ") if exceptions.present?
+
+    puts "Done"
+  end
+end

data/lib/view_component/storybook/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module Storybook
+    VERSION = "1.0.0"
+  end
+end

data/lib/view_component/storybook.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/dependencies/autoload"
+
+module ViewComponent
+  module Storybook
+    extend ActiveSupport::Autoload
+
+    autoload :Controls
+    autoload :Collections
+    autoload :Stories
+    autoload :StoriesParser
+
+    autoload :Story
+    autoload :Slots
+
+    include ActiveSupport::Configurable
+    # Set the location of component previews through app configuration:
+    #
+    #     config.view_component_storybook.stories_path = Rails.root.join("lib/component_stories")
+    #
+    mattr_accessor :stories_paths, instance_writer: false
+
+    # Enable or disable component previews through app configuration:
+    #
+    #     config.view_component_storybook.show_stories = true
+    #
+    # Defaults to +true+ for development environment
+    #
+    mattr_accessor :show_stories, instance_writer: false
+
+    # Set the entry route for component stories:
+    #
+    #     config.view_component_storybook.stories_route = "/stories"
+    #
+    # Defaults to `/rails/stories` when `show_stories` is enabled.
+    #
+    mattr_accessor :stories_route, instance_writer: false
+
+    # :nocov:
+    if defined?(ViewComponent::Storybook::Engine)
+      ActiveSupport::Deprecation.warn(
+        "This manually engine loading is deprecated and will be removed in v1.0.0. " \
+        "Remove `require \"view_component/storybook/engine\"`."
+      )
+    elsif defined?(Rails::Engine)
+      require "view_component/storybook/engine"
+    end
+    # :nocov:
+
+    # Define how component stories titles are generated:
+    #
+    #     config.view_component_storybook.stories_title_generator = lambda { |stories|
+    #       stories.stories_name.humanize.upcase
+    #     }
+    #
+    mattr_accessor :stories_title_generator, instance_writer: false,
+                                             default: ->(stories) { stories.stories_name.humanize.titlecase }
+
+    ActiveSupport.run_load_hooks(:view_component_storybook, self)
+  end
+end