compony 0.0.1

data/lib/compony/component.rb

@@ -0,0 +1,225 @@
+module Compony
+  class Component
+    # Include all functionality that was moved to default mixins for better overview
+    Compony::ComponentMixins::Default.constants.each { |cst| include Compony::ComponentMixins::Default.const_get(cst) }
+
+    class_attribute :setup_blocks
+
+    attr_reader :parent_comp
+    attr_reader :comp_opts
+
+    # root comp: component that is registered to be root of the application.
+    # parent comp: component that is registered to be the parent of this comp. If there is none, this is the root comp.
+
+    # DSL method
+    def self.setup(&block)
+      fail("`setup` expects a block in #{inspect}.") unless block_given?
+      self.setup_blocks ||= []
+      self.setup_blocks = setup_blocks.dup # This is required to prevent the parent class to see children's setup blocks.
+      setup_blocks << block
+    end
+
+    def initialize(parent_comp = nil, index: 0, **comp_opts)
+      @parent_comp = parent_comp
+      @sub_comps = []
+      @index = index
+      @comp_opts = comp_opts
+      @before_render_block = nil
+      @content_blocks = []
+      @actions = []
+      @skipped_actions = Set.new
+
+      init_standalone
+      init_labelling
+
+      fail "#{inspect} is missing a call to `setup`." unless setup_blocks&.any?
+
+      setup_blocks.each do |setup_block|
+        instance_exec(&setup_block)
+      end
+      check_config!
+    end
+
+    def inspect
+      "#<#{self.class.name}:#{hash}>"
+    end
+
+    # Returns the current root comp.
+    # Do not overwrite.
+    def root_comp
+      return self unless parent_comp
+      return parent_comp.root_comp
+    end
+
+    # Returns whether or not this is the root comp.
+    # Do not overwrite.
+    def root_comp?
+      parent_comp.nil?
+    end
+
+    # Returns an identifier describing this component. Must be unique among simplings under the same parent_comp.
+    # Do not override.
+    def id
+      "#{family_name}_#{comp_name}_#{@index}"
+    end
+
+    # Returns the id path from the root_comp.
+    # Do not overwrite.
+    def path
+      if root_comp?
+        id
+      else
+        "#{parent_comp.path}/#{id}"
+      end
+    end
+
+    # Returns a hash for the path. Used for params prefixing.
+    # Do not overwrite.
+    def path_hash
+      Digest::SHA1.hexdigest(path)[..4]
+    end
+
+    # Given an unprefixed name of a param, adds the path hash
+    # Do not overwrite.
+    def param_name(unprefixed_param_name)
+      "#{path_hash}_#{unprefixed_param_name}"
+    end
+
+    # Instanciate a component with `self` as a parent
+    def sub_comp(component_class, **comp_opts)
+      sub = component_class.new(self, index: @sub_comps.count, **comp_opts)
+      @sub_comps << sub
+      return sub
+    end
+
+    # Returns the name of the module constant (=family) of this component. Do not override.
+    def family_cst
+      self.class.module_parent.to_s.demodulize.to_sym
+    end
+
+    # Returns the family name
+    def family_name
+      family_cst.to_s.underscore
+    end
+
+    # Returns the name of the class constant of this component. Do not override.
+    def comp_cst
+      self.class.name.demodulize.to_sym
+    end
+
+    # Returns the component name
+    def comp_name
+      comp_cst.to_s.underscore
+    end
+
+    # @todo deprecate (check for usages beforehand)
+    def comp_class_for(...)
+      Compony.comp_class_for(...)
+    end
+
+    # @todo deprecate (check for usages beforehand)
+    def comp_class_for!(...)
+      Compony.comp_class_for!(...)
+    end
+
+    # DSL method
+    def before_render(&block)
+      @before_render_block = block
+    end
+
+    # DSL method
+    # Overrides previous content (also from superclasses). Will be the first content block to run.
+    # You can use dyny here.
+    def content(&block)
+      fail("`content` expects a block in #{inspect}.") unless block_given?
+      @content_blocks = [block]
+    end
+
+    # DSL method
+    # Adds a content block that will be executed after all previous ones.
+    # It is safe to use this method even if `content` has never been called
+    # You can use dyny here.
+    def add_content(index = -1, &block)
+      fail("`content` expects a block in #{inspect}.") unless block_given?
+      @content_blocks ||= []
+      @content_blocks.insert(index, block)
+    end
+
+    # Renders the component using the controller passsed to it and returns it as a string.
+    # Do not overwrite.
+    def render(controller, **locals)
+      # Call before_render hook if any and backfire instance variables back to the component
+      RequestContext.new(self, controller, locals:).request_context.evaluate_with_backfire(&@before_render_block) if @before_render_block
+      # Render, unless before_render has already issued a body (e.g. through redirecting).
+      if controller.response.body.blank?
+        fail "#{self.class.inspect} must define `content` or set a response body in `before_render`" if @content_blocks.none?
+        return controller.render_to_string(
+          type:   :dyny,
+          locals: { content_blocks: @content_blocks, component: self, render_locals: locals },
+          inline: <<~RUBY
+            content_blocks.each do |block|
+              # Instanciate and evaluate a fresh RequestContext in order to use the buffer allocated by the ActionView (needed for `concat` calls)
+              Compony::RequestContext.new(component, controller, helpers: self, locals: render_locals).evaluate(&block)
+            end
+          RUBY
+        )
+      else
+        return nil # Prevent double render errors
+      end
+    end
+
+    # DSL method
+    # Adds or replaces an action (for action buttons)
+    # If before: is specified, will insert the action before the named action. When replacing, an element keeps its position unless before: is specified.
+    def action(action_name, before: nil, &block)
+      action_name = action_name.to_sym
+      before_name = before&.to_sym
+      action = MethodAccessibleHash.new(name: action_name, block:)
+
+      existing_index = @actions.find_index { |el| el.name == action_name }
+      if existing_index.present? && before_name.present?
+        @actions.delete_at(existing_index) # Replacing an existing element with a before: directive - must delete before calculating indices
+      end
+      if before_name.present?
+        before_index = @actions.find_index { |el| el.name == before_name } || fail("Action #{before_name} for :before not found in #{inspect}.")
+      end
+
+      if before_index.present?
+        @actions.insert(before_index, action)
+      elsif existing_index.present?
+        @actions[existing_index] = action
+      else
+        @actions << action
+      end
+    end
+
+    # DSL method
+    # Marks an action for skip
+    def skip_action(action_name)
+      @skipped_actions << action_name.to_sym
+    end
+
+    # Used to render all actions of this component, each button wrapped in a div with the specified class
+    def render_actions(controller, wrapper_class: '', action_class: '')
+      h = controller.helpers
+      h.content_tag(:div, class: wrapper_class) do
+        button_htmls = @actions.map do |action|
+          next if @skipped_actions.include?(action.name)
+          Compony.with_button_defaults(feasibility_action: action.name.to_sym) do
+            h.content_tag(:div, action.block.call.render(controller), class: action_class)
+          end
+        end
+        next h.safe_join button_htmls
+      end
+    end
+
+    # Is true for resourceful components
+    def resourceful?
+      return false
+    end
+
+    protected
+
+    def check_config!; end
+  end
+end

data/lib/compony/component_mixins/default/labelling.rb

@@ -0,0 +1,77 @@
+require 'active_support/concern'
+
+module Compony
+  module ComponentMixins
+    module Default
+      # This module contains all methods for Component that concern labelling and look
+      module Labelling
+        extend ActiveSupport::Concern
+
+        # DSL method and accessor
+        # When assigning via DSL, pass format as first parameter.
+        # When accessing the value, pass foramt as named parameter
+        def label(data_or_format = nil, format: :long, &block)
+          format = data_or_format if block_given?
+          format ||= :long
+          format = format.to_sym
+
+          if block_given?
+            # Assignment via DSL
+            if format == :all
+              @label_blocks[:short] = block
+              @label_blocks[:long] = block
+            else
+              @label_blocks[format] = block
+            end
+          else
+            # Retrieval of the actual label
+            fail('Label format :all may only be used for setting a label (with a block), not for retrieving it.') if format == :all
+            label_block = @label_blocks[format] || fail("Format #{format} was not found for #{inspect}.")
+            case label_block.arity
+            when 0
+              label_block.call
+            when 1
+              data_or_format ||= data
+              if data_or_format.blank?
+                fail "Label block of #{inspect} takes an argument, but no data was provided and a call to `data` did not return any data either."
+              end
+              label_block.call(data_or_format)
+            else
+              fail "#{inspect} has a label block that takes 2 or more arguments, which is unsupported."
+            end
+          end
+        end
+
+        # DSL method and accessor
+        def icon(&block)
+          if block_given?
+            @icon_block = block
+          else
+            @icon_block.call
+          end
+        end
+
+        # DSL method and accessor
+        def color(&block)
+          if block_given?
+            @color_block = block
+          else
+            @color_block.call
+          end
+        end
+
+        private
+
+        def init_labelling
+          # Provide defaults
+          @label_blocks = {
+            long:  -> { "#{I18n.t(family_name.humanize)}: #{I18n.t(comp_name.humanize)}" },
+            short: -> { I18n.t(comp_name.humanize) }
+          }
+          @icon_block = -> { :'arrow-right' }
+          @color_block = -> { :primary }
+        end
+      end
+    end
+  end
+end

data/lib/compony/component_mixins/default/standalone/resourceful_verb_dsl.rb

@@ -0,0 +1,55 @@
+module Compony
+  module ComponentMixins
+    module Default
+      module Standalone
+        class ResourcefulVerbDsl < VerbDsl
+          def initialize(...)
+            # All resourceful components have a load_data_block, which defaults to the one defined in Resource, defaulting to finding the record.
+            @load_data_block = proc { evaluate_with_backfire(&@global_load_data_block) }
+            super
+          end
+
+          def to_conf(&)
+            return super.deep_merge({
+                                      load_data_block:         @load_data_block,
+                                      assign_attributes_block: @assign_attributes_block,
+                                      store_data_block:        @store_data_block
+                                    }).compact
+          end
+
+          protected
+
+          # DSL
+          # This is the first step in the life cycle. The block is expected to assign something to `@data`.
+          def load_data(&block)
+            @load_data_block = block
+          end
+
+          # DSL
+          # This is called after `load_data`. The block is expected to assign data from `params` as attributes of `@data`.
+          # If this method gets never called, the verb config will not contain a assign_attributes block.
+          # If called without a block, the verb config will call the global_assign_attributes block defined in Resource.
+          def assign_attributes(&block)
+            if block_given?
+              @assign_attributes_block = block
+            else
+              @assign_attributes_block = proc { evaluate_with_backfire(&@global_assign_attributes_block) }
+            end
+          end
+
+          # DSL
+          # This is called after authorization. The block is expected to write back to the database.
+          # If this method gets never called, the verb config will not contain a store_data block.
+          # If called without a block, the verb config will call the global_store_data block defined in Resource.
+          def store_data(&block)
+            if block_given?
+              @store_data_block = block
+            else
+              @store_data_block = proc { evaluate_with_backfire(&@global_store_data_block) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/compony/component_mixins/default/standalone/standalone_dsl.rb

@@ -0,0 +1,56 @@
+module Compony
+  module ComponentMixins
+    module Default
+      module Standalone
+        # @api description
+        # Wrapper and DSL helper for component's standalone config
+        class StandaloneDsl < Dslblend::Base
+          def initialize(component, name = nil, path: nil)
+            super()
+            @component = component
+            @name = name&.to_sym
+            @path = path
+            @verbs = {}
+            @skip_authentication = false
+            @layout = true # can be overriden by false or a string
+          end
+
+          def to_conf(&block)
+            evaluate(&block)
+            @component = block.binding.eval('self') # Fetches the component holding this DSL call (via the block)
+            return {
+              name:                @name,
+              path:                @path,
+              verbs:               @verbs,
+              rails_action_name:   Compony.rails_action_name(comp_name, family_name, @name),
+              path_helper_name:    Compony.path_helper_name(comp_name, family_name, @name),
+              skip_authentication: @skip_authentication,
+              layout:              @layout
+            }.compact
+          end
+
+          protected
+
+          # DSL
+          def verb(verb, *args, **nargs, &)
+            verb = verb.to_sym
+            verb_dsl_class = @component.resourceful? ? ResourcefulVerbDsl : VerbDsl
+            @verbs[verb] ||= Compony::MethodAccessibleHash.new
+            @verbs[verb].deep_merge! verb_dsl_class.new(@component, verb, *args, **nargs).to_conf(&)
+          end
+
+          # DSL
+          def skip_authentication!
+            @skip_authentication = true
+          end
+
+          # DSL
+          # Defaults to Rails' default (layouts/application)
+          def layout(layout)
+            @layout = layout.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/compony/component_mixins/default/standalone/verb_dsl.rb

@@ -0,0 +1,47 @@
+module Compony
+  module ComponentMixins
+    module Default
+      module Standalone
+        class VerbDsl < Dslblend::Base
+          AVAILABLE_VERBS = %i[get head post put delete connect options trace patch].freeze
+
+          def initialize(component, verb)
+            super()
+
+            verb = verb.to_sym
+            fail "Unknown HTTP verb #{verb.inspect}, use one of #{AVAILABLE_VERBS.inspect}" unless AVAILABLE_VERBS.include?(verb)
+
+            @component = component
+            @verb = verb
+            @respond_blocks = { nil => proc { render_standalone(controller) } } # default format
+            @authorize_block = nil
+          end
+
+          def to_conf(&)
+            evaluate(&) if block_given?
+            return {
+              verb:            @verb,
+              authorize_block: @authorize_block || proc { can?(comp_name.to_sym, family_name.to_sym) },
+              respond_blocks:  @respond_blocks
+            }.compact
+          end
+
+          protected
+
+          # DSL
+          # This block is expected to return true if and only if current_ability has the right to access the component over the given verb.
+          def authorize(&block)
+            @authorize_block = block
+          end
+
+          # DSL
+          # This is the last step in the life cycle. It may redirect or render. If omitted, the default is standalone_render.
+          # @param format [String, Symbol] Format this block should respond to, defaults to `nil` which means "all other formats".
+          def respond(format = nil, &block)
+            @respond_blocks[format&.to_sym] = block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/compony/component_mixins/default/standalone.rb

@@ -0,0 +1,117 @@
+module Compony
+  module ComponentMixins
+    module Default
+      # This contains all default component logic concerning standalone functionality
+      module Standalone
+        extend ActiveSupport::Concern
+
+        included do
+          # Called in routes.rb
+          # Returns the compiled standalone config for this component
+          # If the components have an inheritance hierarchy, the configs are merged in the right order to perform proper overrides.
+          attr_reader :standalone_configs
+        end
+
+        # Called by fab_controller when a request is issued.
+        # This is the entrypoint where a request enters the Component world.
+        def on_standalone_access(verb_config, controller)
+          # Register as root comp
+          if parent_comp.nil?
+            fail "#{inspect} is attempting to become root component, but #{root_comp.inspect} is already root." if Compony.root_comp.present?
+            RequestStore.store[:compony_root_comp] = self
+          end
+
+          # Prepare the request context in which the innermost DSL calls will be executed
+          request_context = RequestContext.new(self, controller)
+
+          ###===---
+          # Dispatch request to component. Empty Dslblend base objects are used to provide multiple contexts to the authorize and respond blocks.
+          # Lifecycle is (see also "doc/Resourceful Lifecycle.pdf"):
+          #   - load data (optional, speficied ResourcefulVerbDsl, by convention, should default to the implementation in Resourceful)
+          #     - after_load_data (optional, specified in Resourceful)
+          #   - assign_attributes (optional, speficied ResourcefulVerbDsl, by convention, should default to the implementation in Resourceful)
+          #     - after_assign_attributes (optional, specified in Resourceful)
+          #   - authorize
+          #   - store_data (optional, speficied ResourcefulVerbDsl, by convention, should default to the implementation in Resourceful)
+          #   - respond (typically either redirect or render standalone, specified in VerbDsl), which defaults to render_standalone, performing:
+          #     - before_render
+          #     - render (unless before_render already redirected)
+          ###===---
+
+          if verb_config.load_data_block
+            request_context.evaluate_with_backfire(&verb_config.load_data_block)
+            if global_after_load_data_block
+              request_context.evaluate_with_backfire(&global_after_load_data_block)
+            end
+          end
+
+          if verb_config.assign_attributes_block
+            request_context.evaluate_with_backfire(&verb_config.assign_attributes_block)
+            if global_after_assign_attributes_block
+              request_context.evaluate_with_backfire(&global_after_assign_attributes_block)
+            end
+          end
+
+          # TODO: Make much prettier, providing message, action, subject and conditions
+          fail CanCan::AccessDenied, inspect unless request_context.evaluate(&verb_config.authorize_block)
+
+          if verb_config.store_data_block
+            request_context.evaluate_with_backfire(&verb_config.store_data_block)
+          end
+
+          # Check if there is a specific respond block for the format.
+          # If there isn't, fallback to the nil respond block, which defaults to `render_standalone`.
+          respond_block = verb_config.respond_blocks[controller.request.format.symbol] || verb_config.respond_blocks[nil]
+          request_context.evaluate(&respond_block)
+        end
+
+        # Call this on a standalone component to find out whether default GET access is permitted for the current user.
+        # This is useful to hide/disable buttons leading to components a user may not press.
+        # For resourceful components, before calling this, you must have loaded date beforehand, for instance in one of the following ways:
+        # - when called standalone (via request to the component), the load data step must be completed
+        # - when called to check for permission only, e.g. to display a button to it, initialize the component by passing the :data keyword to `new`
+        # By default, this checks the authorization to access the main standalone entrypoint (with name `nil`) and HTTP verb GET.
+        def standalone_access_permitted_for?(controller, standalone_name: nil, verb: :get)
+          standalone_name = standalone_name&.to_sym
+          verb = verb.to_sym
+          standalone_config = standalone_configs[standalone_name] || fail("#{inspect} does not provide the standalone config #{standalone_config.inspect}.")
+          verb = standalone_config.verbs[verb] || fail("#{inspect} standalone config #{standalone_config.inspect} does not provide verb #{verb.inspect}.")
+          return RequestContext.new(self, controller).evaluate(&verb.authorize_block)
+        end
+
+        # Renders the component using the controller passed to it upon instanciation (calls the controller's render)
+        # Do not overwrite
+        def render_standalone(controller, status: nil, standalone_name: nil)
+          # Start the render process. This produces a nil value if before_render has already produced a response, e.g. a redirect.
+          rendered_html = render(controller)
+          if rendered_html.present? # If nil, a response body was already produced in the controller and we take no action here (would have DoubleRenderError)
+            opts = { html: rendered_html, layout: @standalone_configs[standalone_name].layout }
+            opts[:status] = status if status.present?
+            controller.respond_to do |format|
+              # Form posts trigger format types turbo stream and then html, turbo stream wins.
+              # For this reason, Rails prefers stream, in which case the layout is disabled, regardless of the option.
+              # To mitigate this, we use respond_to to force a HTML-only response.
+              format.html { controller.render(**opts) }
+            end
+          end
+        end
+
+        protected
+
+        # DSL method
+        def standalone(name = nil, *args, **nargs, &block)
+          block = proc {} unless block_given? # If called without a block, must default to an empty block to provide a binding to the DSL.
+          name = name&.to_sym # nil name is the most common case
+          @standalone_configs[name] ||= Compony::MethodAccessibleHash.new
+          @standalone_configs[name].deep_merge! StandaloneDsl.new(self, name, *args, **nargs).to_conf(&block)
+        end
+
+        private
+
+        def init_standalone
+          @standalone_configs = {}
+        end
+      end
+    end
+  end
+end

data/lib/compony/component_mixins/resourceful.rb

@@ -0,0 +1,92 @@
+module Compony
+  module ComponentMixins
+    # Include this when your component's family name corresponds to the pluralized Rails model name the component's family is responsible for.
+    # When including this, the component gets an attribute @data which contains a record or a collection of records.
+    # Resourceful components are always aware of a data_class, corresponding to the expected @data.class and used e.g. to render lists or for `.new`.
+    module Resourceful
+      extend ActiveSupport::Concern
+
+      attr_reader :data
+
+      # Must prefix the following instance variables with global_ in order to avoid overwriting VerbDsl inst vars due to Dslblend.
+      attr_reader :global_load_data_block
+      attr_reader :global_after_load_data_block
+      attr_reader :global_assign_attributes_block
+      attr_reader :global_after_assign_attributes_block
+      attr_reader :global_store_data_block
+
+      def initialize(*args, data: nil, data_class: nil, **nargs, &block)
+        @data = data
+        @data_class = data_class
+
+        # Provide defaults for hook blocks
+        @global_load_data_block ||= proc { @data = self.data_class.find(controller.params[:id]) }
+
+        super(*args, **nargs, &block)
+      end
+
+      # DSL method
+      # Sets or calculates the model class based on the component's family name
+      def data_class(new_data_class = nil)
+        @data_class ||= new_data_class || family_cst.to_s.singularize.constantize
+      end
+
+      # Instanciate a component with `self` as a parent and render it, having it inherit the resource
+      def resourceful_sub_comp(component_class, **comp_opts)
+        comp_opts[:data] ||= data # Inject additional param before forwarding all of them to super
+        comp_opts[:data_class] ||= data_class # Inject additional param before forwarding all of them to super
+        sub_comp(component_class, **comp_opts)
+      end
+
+      def resourceful?
+        return true
+      end
+
+      protected
+
+      # DSL method
+      # Sets a default load_data block for all standalone paths and verbs.
+      # Can be overwritten for a specific path and verb in the
+      # {Compony::ComponentMixins::Default::Standalone::VerbDsl}.
+      # The block is expected to assign `@data`.
+      # @see Compony::ComponentMixins::Default::Standalone::VerbDsl#load_data
+      def load_data(&block)
+        @global_load_data_block = block
+      end
+
+      # DSL method
+      # Runs after loading data and before authorization for all standalone paths and verbs.
+      # Example use case: if `load_data` produced an AR collection proxy, can still refine result here before `to_sql` is called.
+      def after_load_data(&block)
+        @global_after_load_data_block = block
+      end
+
+      # DSL method
+      # Sets a default default assign_attributes block for all standalone paths and verbs.
+      # Can be overwritten for a specific path and verb in the
+      # {Compony::ComponentMixins::Default::Standalone::VerbDsl}.
+      # The block is expected to assign suitable `params` to attributes of `@data`.
+      # @see Compony::ComponentMixins::Default::Standalone::VerbDsl#assign_attributes
+      def assign_attributes(&block)
+        @global_assign_attributes_block = block
+      end
+
+      # DSL method
+      # Runs after `assign_attributes` and before `store_data` for all standalone paths and verbs.
+      # Example use case: prefilling some fields for a form
+      def after_assign_attributes(&block)
+        @global_after_assign_attributes_block = block
+      end
+
+      # DSL method
+      # Sets a default store_data block for all standalone paths and verbs.
+      # Can be overwritten for a specific path and verb in the
+      # {Compony::ComponentMixins::Default::Standalone::VerbDsl}.
+      # The block is expected save `@data` to the database.
+      # @see Compony::ComponentMixins::Default::Standalone::VerbDsl#store_data
+      def store_data(&block)
+        @global_store_data_block = block
+      end
+    end
+  end
+end