compony 0.2.3 → 0.3.1

data/doc/top-level-namespace.html

@@ -102,7 +102,7 @@
 </div>
 
       <div id="footer">
-  Generated on Sat Apr 27 10:22:11 2024 by
+  Generated on Fri May 31 14:28:29 2024 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.2.2).
 </div>

data/lib/compony/component.rb

@@ -7,6 +7,7 @@ module Compony
 
     attr_reader :parent_comp
     attr_reader :comp_opts
+    attr_reader :content_blocks # needed in RequestContext for nesting
 
     # 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.
@@ -24,9 +25,9 @@ module Compony
       @sub_comps = []
       @index = index
       @comp_opts = comp_opts
-      @before_render_block = nil
-      @content_blocks = []
-      @actions = []
+      @before_render_blocks = NaturalOrdering.new
+      @content_blocks = NaturalOrdering.new
+      @actions = NaturalOrdering.new
       @skipped_actions = Set.new
 
       init_standalone
@@ -111,46 +112,51 @@ module Compony
       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
+    # Adds or overrides a before_render block.
+    # You can use controller.redirect_to to redirect away and halt the before_render/content chain
+    # @param [Symbol,String] name The name of the before_render block, defaults to `:main`
+    # @param [nil,Symbol,String] before If nil, the block will be added to the bottom of the before_render chain. Otherwise, pass the name of another block.
+    # @param [Proc] block The block that should be run as part of the before_render pipeline. Will run in the component's context.
+    def before_render(name = :main, before: nil, **kwargs, &block)
+      fail("`before_render` expects a block in #{inspect}.") unless block_given?
+      @before_render_blocks.natural_push(name, block, before:, **kwargs)
     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]
+    # Adds or overrides a content block.
+    # @param [Symbol,String] name The name of the content block, defaults to `:main`
+    # @param [nil,Symbol,String] before If nil, the block will be added to the bottom of the content chain. Otherwise, pass the name of another block.
+    # @param [Hash] kwargs If hidden is true, the content will not be rendered by default, allowing you to nest it in another content block.
+    # @param [Proc] block The block that should be run as part of the content pipeline. Will run in the component's context. You can use Dyny here.
+    def content(name = :main, before: nil, **kwargs, &block)
+      # A block is required here, but if this is an override (e.g. to hide another content block), we can tolerate the missing block.
+      if !block_given? && @content_blocks.find { |b| b.name == name }.nil?
+        fail("`content` expects a block in #{inspect}.")
+      end
+      @content_blocks.natural_push(name, block || :missing, before:, **kwargs)
     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)
+    # Removes a content block. Use this in subclasses if a content block defined in the parent should be removed from the child.
+    # @param [Symbol,String] name Name of the content block that should be removed
+    def remove_content(name)
+      name = name.to_sym
+      existing_index = @content_blocks.find_index { |el| el.name == name } || fail("Content block #{name.inspect} not found for removal in #{inspect}.")
+      @content_blocks.delete_at(existing_index)
     end
 
     # Renders the component using the controller passsed to it and returns it as a string.
     # @param [Boolean] standalone pass true iff `render` is called from `render_standalone`
     # Do not overwrite.
     def render(controller, standalone: false, **locals)
-      # Call before_render hook if any and backfire instance variables back to the component
-      # TODO: Can .request_context be removed from the next line? Test well!
-      RequestContext.new(self, controller, locals:).request_context.evaluate_with_backfire(&@before_render_block) if @before_render_block
+      # Call before_render hooks (if any) and backfire instance variables back to the component
+      @before_render_blocks.each do |element|
+        RequestContext.new(self, controller, locals:).evaluate_with_backfire(&element.payload)
+        # Stop if a `before_render` block issued a body (e.g. through redirecting)
+        break unless controller.response_body.nil?
+      end
+
       # Render, unless before_render has already issued a body (e.g. through redirecting).
       if controller.response_body.nil?
         fail "#{self.class.inspect} must define `content` or set a response body in `before_render`" if @content_blocks.none?
@@ -161,9 +167,9 @@ module Compony
             if Compony.content_before_root_comp_block && standalone
               Compony::RequestContext.new(component, controller, helpers: self, locals: render_locals).evaluate(&Compony.content_before_root_comp_block)
             end
-            content_blocks.each do |block|
+            content_blocks.reject{ |el| el.hidden }.each do |element|
               # 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)
+              Compony::RequestContext.new(component, controller, helpers: self, locals: render_locals).evaluate(&element.payload)
             end
             if Compony.content_after_root_comp_block && standalone
               Compony::RequestContext.new(component, controller, helpers: self, locals: render_locals).evaluate(&Compony.content_after_root_comp_block)
@@ -179,25 +185,7 @@ module Compony
     # 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
+      @actions.natural_push(action_name, block, before:)
     end
 
     # DSL method
@@ -213,7 +201,7 @@ module Compony
         button_htmls = @actions.map do |action|
           next if @skipped_actions.include?(action.name)
           Compony.with_button_defaults(feasibility_action: action.name.to_sym) do
-            action_button = action.block.call(controller)
+            action_button = action.payload.call(controller)
             next unless action_button
             button_html = action_button.render(controller)
             next if button_html.blank?

data/lib/compony/components/destroy.rb

@@ -26,8 +26,11 @@ module Compony
         icon { :trash }
         color { :danger }
 
-        content do
+        content :confirm_question, hidden: true do
           div I18n.t('compony.components.destroy.confirm_question', data_label: @data.label)
+        end
+
+        content :confirm_button, hidden: true do
           div do
             concat compony_button(comp_cst,
                                   @data,
@@ -36,6 +39,11 @@ module Compony
           end
         end
 
+        content do
+          content :confirm_question
+          content :confirm_button
+        end
+
         action :back_to_owner do
           next if data_class.owner_model_attr.blank?
           Compony.button(:show, @data.send(data_class.owner_model_attr), icon: :xmark, color: :secondary, label: I18n.t('compony.cancel'))

data/lib/compony/components/edit.rb

@@ -50,10 +50,8 @@ module Compony
             end
             hsh? local_form_comp.schema_wrapper_key_for(local_data), &local_form_comp.schema_block_for(local_data)
           end
-          schema.validate!(controller.request.params)
-
-          # TODO: Why are we not saving the validated params?
-          attrs_to_assign = controller.request.params[form_comp.schema_wrapper_key_for(@data)]
+          validated_params = schema.validate!(controller.request.params)
+          attrs_to_assign = validated_params[form_comp.schema_wrapper_key_for(@data)]
           @data.assign_attributes(attrs_to_assign) if attrs_to_assign
         end
 

data/lib/compony/components/form.rb

@@ -13,19 +13,30 @@ module Compony
           # Make sure the error message is going to be nice if form_fields were not implemented
           fail "#{component.inspect} requires config.form_fields do ..." if @form_fields.nil?
 
-          # Must render the buttons now as the rendering within simple form breaks the form
-          @submit_button = Compony.button_component_class.new(
-            label: @submit_label || I18n.t('compony.components.form.submit'), icon: 'arrow-right', type: :submit
-          ).render(controller)
+          # Calculate paths
           @submit_path = @comp_opts[:submit_path]
           @submit_path = @submit_path.call(controller) if @submit_path.respond_to?(:call)
         end
 
+        # Override this to provide a custom submit button
+        content :submit_button, hidden: true do
+          concat Compony.button_component_class.new(
+            label: @submit_label || I18n.t('compony.components.form.submit'), icon: 'arrow-right', type: :submit
+          ).render(controller)
+        end
+
+        # Override this to provide additional submit buttons.
+        content :buttons, hidden: true do
+          content(:submit_button)
+        end
+
         content do
           form_html = simple_form_for(data, method: @comp_opts[:submit_verb], url: @submit_path) do |f|
             component.with_simpleform(f) do
               instance_exec(&form_fields)
-              div @submit_button, class: 'compony-form-buttons'
+              div class: 'compony-form-buttons' do
+                content(:buttons)
+              end
             end
           end
           concat form_html

data/lib/compony/components/new.rb

@@ -32,10 +32,11 @@ module Compony
         label(:short) { I18n.t('compony.components.new.label.short') }
         icon { :plus }
 
-        add_content do
+        content :label do
           h2 component.label
         end
-        add_content do
+
+        content do
           concat form_comp.render(controller, data: @data)
         end
 
@@ -45,10 +46,8 @@ module Compony
           schema = Schemacop::Schema3.new :hash, additional_properties: true do
             hsh? local_form_comp.schema_wrapper_key_for(local_data), &local_form_comp.schema_block_for(local_data)
           end
-          schema.validate!(controller.request.params)
-
-          # TODO: Why are we not saving the validated params?
-          attrs_to_assign = controller.request.params[form_comp.schema_wrapper_key_for(@data)]
+          validated_params = schema.validate!(controller.request.params)
+          attrs_to_assign = validated_params[form_comp.schema_wrapper_key_for(@data)]
           @data.assign_attributes(attrs_to_assign) if attrs_to_assign
         end
 

data/lib/compony/components/with_form.rb

@@ -13,7 +13,7 @@ module Compony
       # Returns an instance of the form component responsible for rendering the form.
       # Feel free to override this in subclasses.
       def form_comp
-        @form_comp ||= (form_comp_class || comp_class_for!(:form, family_cst)).new(
+        @form_comp ||= (form_comp_class || Compony.comp_class_for!(:form, family_cst)).new(
           self,
           submit_verb:,
           # If applicable, Rails adds the route keys automatically, thus, e.g. :id does not need to be passed here, as it comes from the request.

data/lib/compony/natural_ordering.rb

@@ -0,0 +1,60 @@
+module Compony
+  # @api description
+  # This class provides an array-based data structure where elements have symbol names. New elements can be appended or placed at a location using `before:`.
+  # Important: do not mutate this class with any other method call than the natural_-prefixed methods defined below.
+  # Example:<br>
+  # ```ruby
+  # collection = Compony::NaturalOrdering.new
+  # collection.natural_push(:a, a_payload)
+  # collection.natural_push(:c, c_payload)
+  # collection.natural_push(:b, b_payload, before: :c)
+  # collection.natural_push(:d, d_payload, hidden: true)
+  # collection.natural_push(:a, a_new_payload) # overwrites :a
+  #
+  # collection.reject{|el| el.hidden}.map(&:name) # --> :a, :b, :c
+  # collection.map(&:payload) # --> a_new_payload, b_payload, c_payload, d_payload
+  # ```
+  class NaturalOrdering < Array
+    def natural_push(name, payload = :missing, before: nil, **kwargs)
+      name = name.to_sym
+      before_name = before&.to_sym
+      old_kwargs = {}
+      old_payload = nil
+
+      # Fetch existing element if any
+      existing_index = find_index { |el| el.name == name }
+      if existing_index.present?
+        # Copy all non-mentionned kwargs from the element we are about to overwrite
+        old_kwargs = self[existing_index].except(:name, :payload)
+        old_payload = self[existing_index].payload
+
+        # Replacing an existing element with a before: directive - must delete before calculating indices
+        if before_name.present?
+          delete_at(existing_index)
+        end
+      elsif payload == :missing
+        fail("Cannot insert new element #{name} without a payload (payload can only omitted if overriding another element) in #{inspect}.")
+      end
+
+      # Fetch before element
+      if before_name.present?
+        before_index = find_index { |el| el.name == before_name } || fail("Element #{before_name.inspect} for :before not found in #{inspect}.")
+      end
+
+      # Create the element to insert
+      element = MethodAccessibleHash.new(name:, payload: payload == :missing ? old_payload : payload, **old_kwargs.merge(kwargs))
+
+      # Insert new element
+      if before_index.present?
+        # Insert before another element
+        insert(before_index, element)
+      elsif existing_index.present?
+        # Override another element
+        self[existing_index] = element
+      else
+        # Append at the end
+        self << element
+      end
+    end
+  end
+end

data/lib/compony/request_context.rb

@@ -41,5 +41,19 @@ module Compony
       return true if @local_assigns.key?(method)
       return super
     end
+
+    # Renders a content block from the current component.
+    def content(name)
+      name = name.to_sym
+      content_block = component.content_blocks.find { |el| el.name == name } || fail("Content block #{name.inspect} not found in #{component.inspect}.")
+      # We have to clear Rails' output_buffer to prevent double rendering of blocks. To achieve this, a fresh render context is instanciated.
+      concat controller.render_to_string(
+        type:   :dyny,
+        locals: { render_component: component, render_controller: controller, render_locals: local_assigns, render_block: content_block },
+        inline: <<~RUBY
+          Compony::RequestContext.new(render_component, render_controller, helpers: self, locals: local_assigns).evaluate_with_backfire(&render_block.payload)
+        RUBY
+      )
+    end
   end
 end

data/lib/compony.rb

@@ -300,6 +300,7 @@ require 'compony/components/new'
 require 'compony/components/edit'
 require 'compony/components/destroy'
 require 'compony/method_accessible_hash'
+require 'compony/natural_ordering'
 require 'compony/model_mixin'
 require 'compony/request_context'
 require 'compony/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: compony
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - Sandro Kalbermatter
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-27 00:00:00.000000000 Z
+date: 2024-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -233,6 +233,7 @@ files:
 - doc/Compony/ModelFields/Time.html
 - doc/Compony/ModelFields/Url.html
 - doc/Compony/ModelMixin.html
+- doc/Compony/NaturalOrdering.html
 - doc/Compony/RequestContext.html
 - doc/Compony/Version.html
 - doc/Compony/ViewHelpers.html
@@ -297,6 +298,7 @@ files:
 - lib/compony/model_fields/time.rb
 - lib/compony/model_fields/url.rb
 - lib/compony/model_mixin.rb
+- lib/compony/natural_ordering.rb
 - lib/compony/request_context.rb
 - lib/compony/version.rb
 - lib/compony/view_helpers.rb