cocooned 1.4.1 → 2.0.0

data/app/assets/stylesheets/cocooned.css

@@ -1,9 +1 @@
-
-.cocooned-visible-item {
-  transition: opacity .45s ease-out;
-  opacity: 1;
-}
-
-.cocooned-hidden-item {
-  opacity: 0;
-}
+/* TODO: Remove in 3.0 */

data/cocooned.gemspec

@@ -11,32 +11,41 @@ Gem::Specification.new do |spec|
   spec.authors      = ['Gaël-Ian Havard', 'Nathan Van der Auwera']
   spec.email        = ['gael-ian@notus.sh', 'nathan@dixis.com']
 
-  spec.summary      = 'Unobtrusive Rails nested forms handling, with or without jQuery.'
-  spec.description  = 'Easier nested form. Supports standard Rails forms, Formtastic and SimpleForm.'
-  spec.homepage     = 'http://github.com/notus-sh/cocooned'
+  spec.summary      = 'Form builder agnostic handling of Rails nested forms'
+  spec.description  = <<-DESC.gsub(/\s+/, ' ')
+    Easier nested form in Rails with capabilities to add, remove, reorder or limit nested items.
+    Works with standard Rails form builder, Formtastic or SimpleForm, and with or without jQuery.
+  DESC
+  spec.homepage     = 'https://github.com/notus-sh/cocooned'
 
   raise 'RubyGems 2.0 or newer is required.' unless spec.respond_to?(:metadata)
 
-  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata = {
+    'allowed_push_host' => 'https://rubygems.org',
+    'rubygems_mfa_required' => 'true',
+
+    'bug_tracker_uri' => 'https://github.com/notus-sh/cocooned/issues',
+    'changelog_uri' => 'https://github.com/notus-sh/cocooned/blob/main/CHANGELOG.md',
+    'homepage_uri' => 'https://github.com/notus-sh/cocooned',
+    'source_code_uri' => 'https://github.com/notus-sh/cocooned',
+    'funding_uri' => 'https://opencollective.com/notus-sh'
+  }
 
   spec.require_paths = ['lib']
+
+  excluded_dirs = %r{^(.github|dev|npm|spec)/}
+  excluded_files = %w[.gitignore .rspec Gemfile Gemfile.lock Rakefile package.json yarn.lock]
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(config|gemfiles|npm|spec)/}) ||
-      %w[.gitignore .rspec .travis.yml].include?(f) ||
-      %w[Gemfile Gemfile.lock package.json yarn.lock].include?(f)
+    f.match(excluded_dirs) || excluded_files.include?(f)
   end
-  spec.required_ruby_version = '>= 2.5'
+  spec.required_ruby_version = '>= 2.6'
 
-  spec.add_dependency 'rails', '>= 5.0', '<= 7.1'
+  spec.add_dependency 'rails', '>= 6.0', '<= 7.1'
 
   spec.add_development_dependency 'bundler', '~> 2.1'
-  spec.add_development_dependency 'jasmine', '~> 3.2'
-  spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'rspec', '~> 3.10.0'
-  spec.add_development_dependency 'rspec-rails', '~> 5.0.0'
-  spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'rubocop-performance'
-  spec.add_development_dependency 'rubocop-rails'
-  spec.add_development_dependency 'rubocop-rake'
-  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'formtastic', '~> 4.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.11'
+  spec.add_development_dependency 'rspec-rails', '>= 5.0'
+  spec.add_development_dependency 'simple_form', '~> 5.1'
 end

data/lib/cocooned/association/builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Cocooned
+  module Association
+    class Builder # :nodoc:
+      attr_reader :association, :record
+
+      def initialize(record, association, options = {})
+        @record = record
+        @association = association
+        @options = options.dup.symbolize_keys.reverse_merge(force_non_association_create: false, wrap_object: false)
+      end
+
+      def build
+        model = reflection ? build_with_reflection : build_without_reflection
+        model = options[:wrap_object].call(model) if options[:wrap_object].respond_to?(:call)
+        model
+      end
+
+      protected
+
+      attr_reader :options
+
+      def model
+        record.class
+      end
+
+      def reflection
+        @reflection ||= model.try(:reflect_on_association, association)
+      end
+
+      def build_with_reflection
+        return build_with_conditions if should_use_conditions?
+
+        # Assume ActiveRecord or compatible
+        # We use a clone of the current form object to not link
+        # object together (even if unsaved)
+        dummy = record.dup
+        model = if reflection.collection?
+                  dummy.send(association).build
+                else
+                  dummy.send("build_#{association}")
+                end
+        model = model.dup if model.frozen?
+        model
+      end
+
+      def build_without_reflection
+        methods = %W[build_#{association.to_s.pluralize} build_#{association.to_s.singularize}]
+        available_methods = methods.select { |m| record.respond_to?(m) }
+        raise "Association #{association} doesn't exist on #{model}" unless available_methods.any?
+
+        record.send(available_methods.first)
+      end
+
+      def should_use_conditions?
+        reflection.class.name.starts_with?('Mongoid::') || options[:force_non_association_create]
+      end
+
+      def build_with_conditions
+        conditions = reflection.respond_to?(:conditions) ? reflection.conditions.flatten : []
+        reflection.klass.new(*conditions)
+      end
+    end
+  end
+end

data/lib/cocooned/association/renderer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Cocooned
+  module Association
+    class Renderer # :nodoc:
+      def initialize(template, form, association, object, options = {})
+        @template = template
+        @form = form
+        @association = association
+        @object = object
+        @options = options.dup.symbolize_keys
+      end
+
+      def render
+        form.public_send(form_method, association, object, form_options) do |form|
+          template.render(partial, **render_options(form))
+        end
+      end
+
+      protected
+
+      attr_reader :template, :form, :association, :object, :options
+
+      def singular_association
+        association.to_s.singularize
+      end
+
+      def form_method
+        ancestors = form.class.ancestors.map(&:to_s)
+        return :simple_fields_for if ancestors.include?('SimpleForm::FormBuilder')
+        return :semantic_fields_for if ancestors.include?('Formtastic::FormBuilder')
+
+        :fields_for
+      end
+
+      def form_options
+        options.fetch(:form_options, {}).symbolize_keys.reverse_merge(child_index: "new_#{association}")
+      end
+
+      def partial
+        options.fetch(:partial, "#{singular_association}_fields")
+      end
+
+      def render_options(form)
+        options.fetch(:locals, {}).merge(form_name => form)
+      end
+
+      def form_name
+        options.fetch(:form_name, :f).to_sym
+      end
+    end
+  end
+end

data/lib/cocooned/association.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Cocooned
+  module Association # :nodoc:
+    autoload :Builder, 'cocooned/association/builder'
+    autoload :Renderer, 'cocooned/association/renderer'
+  end
+end

data/lib/cocooned/deprecation.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'active_support/deprecation'
+
+module Cocooned
+  # Custom deprecator to use with ActiveSupport::Deprecation methods
+  class Deprecation < ActiveSupport::Deprecation
+    @deprecators = {}
+
+    def self.[](deprecation_horizon = nil)
+      @deprecators[deprecation_horizon] ||= new(deprecation_horizon)
+    end
+
+    def initialize(deprecation_horizon = nil, gem_name = 'Cocooned')
+      deprecation_horizon ||= format('%<major>d.0', major: Gem::Version.new(Cocooned::VERSION).segments.first + 1)
+      super(deprecation_horizon, gem_name)
+    end
+  end
+
+  # Deprecated methods
+  module Deprecated # :nodoc:
+    module Helpers # :nodoc:
+      module Tags # :nodoc:
+        # @deprecated: Please use {#cocooned_add_item_link} instead
+        def link_to_add_association(*args, &block)
+          cocooned_add_item_link(*args, &block)
+        end
+        deprecate link_to_add_association: 'Use :cocooned_add_link instead',
+                  deprecator: Deprecation['3.0']
+
+        # @deprecated: Please use {#cocooned_remove_item_link} instead
+        def link_to_remove_association(*args, &block)
+          cocooned_remove_item_link(*args, &block)
+        end
+        deprecate link_to_remove_association: 'Use :cocooned_remove_item_link instead',
+                  deprecator: Deprecation['3.0']
+      end
+    end
+
+    module TagsHelper # :nodoc:
+      module DefaultLabel # :nodoc:
+        protected
+
+        def i18n_namespaces
+          return super unless I18n.exists?(:cocoon)
+
+          Deprecation['3.0'].warn 'Support for the :cocoon i18n namespace will be removed in 3.0', caller_locations(3)
+          super + %w[cocoon]
+        end
+      end
+
+      module DataAttributes # :nodoc:
+        protected
+
+        # Compatibility with the old way to pass data attributes to Rails view helpers
+        # Has we use the :data key (introduced in Rails 3.1), they will not be looked up.
+        def html_data
+          return super unless data_keys.size.positive?
+
+          Deprecation['3.0'].warn 'Compatibility with options named data-* will be removed in 3.0', caller_locations(3)
+          html_data_normalize super.merge(data_options)
+        end
+
+        def data_keys
+          options.keys.select { |k| k.to_s.match?(/data[_-]/) }
+        end
+
+        def data_options
+          data_keys.each_with_object({}) do |original_key, extracted|
+            key = original_key.to_s.gsub(/^data[_-]/, '')
+            extracted[key] = options.delete(original_key)
+          end
+        end
+      end
+
+      module AssociationOptions # :nodoc:
+        protected
+
+        def association_options
+          if options.key? :insertion_traversal
+            Deprecation['3.0'].warn 'Support for the :insertion_traversal will be removed in 3.0', caller_locations(3)
+          end
+
+          super
+        end
+      end
+
+      module Renderer # :nodoc:
+        protected
+
+        def renderer_options
+          return super unless options.key?(:render_options)
+
+          Deprecation['3.0'].warn 'Support for :render_options will be removed in 3.0', caller_locations(3)
+          legacy_options = options.delete(:render_options)
+
+          super.tap do |opts|
+            opts[:locals] = legacy_options.delete(:locals) if legacy_options.key?(:locals)
+            opts[:form_options] = legacy_options
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cocooned/helpers/containers.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Cocooned
+  module Helpers
+    # Cocooned containers helpers output container or item wrappers as expected by
+    # the JavaScript companion package.
+    module Containers
+      # Wrap content with the expected markup for a Cocooned container.
+      #
+      # This is a wrapper around `ActionView::Base#content_tag` to automatically
+      # add default classes and data-attributes that define a Cocooned
+      # container.
+      #
+      # = Signatures
+      #
+      #   cocooned_container(*arguments, **options) do
+      #     # Container content
+      #   end
+      #
+      # = Parameters
+      #
+      # `cocooned_container` supports following options:
+      #
+      # - `:limit` [Integer]
+      #   Enable the limit plugin and set the accepted maximum number of items
+      # - `:reorderable` [Boolean|Hash]
+      #   Enable the reorderable plugin. When a boolean, use plugin's default.
+      #   You can also pass a Hash with explicit options (ex: `{ startAt: 1 }`).
+      #
+      # Any other argument or option supported by `ActionView::Base#content_tag`
+      # will be forwarded.
+      def cocooned_container(*args, &block)
+        options = args.extract_options!.dup
+        defaults = cocooned_wrapper_defaults(options, %w[cocooned-container], :'cocooned-container')
+        defaults[:data][:cocooned_options] = options.extract!(:limit, :reorderable).to_json
+
+        content_tag(:div, *args, **options.deep_merge(defaults), &block)
+      end
+
+      # Wrap content with the expected markup for a Cocooned item.
+      #
+      # This is a wrapper around `ActionView::Base#content_tag` to automatically
+      # add default classes and data-attributes that define a Cocooned item.
+      #
+      # = Signatures
+      #
+      #   cocooned_item(*arguments, **options) do
+      #     # Item content
+      #   end
+      #
+      # = Parameters
+      #
+      # Any argument or option supported by `ActionView::Base#content_tag` will
+      # be forwarded.
+      def cocooned_item(*args, &block)
+        options = args.extract_options!.dup
+        defaults = cocooned_wrapper_defaults(options, %w[cocooned-item nested-fields], :'cocooned-item')
+
+        content_tag(:div, *args, **options.deep_merge(defaults), &block)
+      end
+
+      protected
+
+      def cocooned_wrapper_defaults(options, additional_classes, mark)
+        # TODO: Replace with compact_blank when dropping support for Rails 6.0
+        classes = Array.wrap(options.delete(:class)).flat_map { |k| k.to_s.split }.reject(&:blank?)
+
+        { class: (classes + additional_classes), data: { mark => true } }
+      end
+    end
+  end
+end

data/lib/cocooned/helpers/tags/add.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Cocooned
+  module Helpers
+    module Tags
+      # Helpers to generate action triggers to add items in a nested form.
+      #
+      # = Signatures
+      #
+      #   {method}(label, form, association, options = {})
+      #     # Explicit name
+      #
+      #   {method}(form, association, options = {}) do
+      #     # Name as a block
+      #   end
+      #
+      #   {method}(form, association, options = {})
+      #     # Use default name
+      #
+      # = Parameters
+      #
+      # `label` is the text to be used as the link label. See the main
+      # documentation for Cocooned::Helpers::Tags for more about labelling.
+      #
+      # `form` is your form builder. Can be a SimpleForm::Builder,
+      # Formtastic::Builder or a standard Rails FormBuilder.
+      #
+      # `association` is the name of the nested association.
+      # Ex: cocooned_add_item_link "Add an item", form, :items
+      #
+      # = Options
+      #
+      # `options` can be any of the following.
+      #
+      # Association options:
+      #
+      # - **insertion_method** : the method to be used to insert new items.
+      #   Can be any of `before`, `after`, `append`, `prepend`, `replaceWith`.
+      #   Defaults to `before`
+      # - **insertion_node** : a CSS selector to match new items insertion node.
+      #   Can be any CSS selector supported by `document.querySelector`.
+      #   For compatibility with the original Cocoon:
+      #   * 'this' is supported as a special value to use the trigger itself as
+      #     insertion node.
+      #   * If no value is specified, the trigger's parent will be used.
+      # - **count**: how many item will be inserted on click.
+      #   Defaults to 1.
+      #
+      # Rendering options:
+      #
+      # - **partial**: the nested form partial.
+      #   Defaults to `{association.singular_name}_fields`.
+      # - **form_name**: name used to access the form builder in the nested form
+      #   partial. Defaults to `:f`.
+      # - **form_options**: options to be passed to the nested form builder. Can
+      #   be used to specify a wrapper for simple_form_fields if you use its
+      #   Bootstrap setup, for example. No defaults.
+      # - **locals**: a hash of local variables to forward to the partial. No
+      #   default.
+      #
+      # Building options:
+      #
+      # - **wrap_object**: anything responding to `call` to be used to wrap the
+      #   newly build item instance. Can be useful with decorators or special
+      #   initialisations. No default.
+      #   Ex:
+      #     cocooned_add_item_link "Add an item", form, :items,
+      #       wrap_object: Proc.new { |comment| CommentDecorator.new(comment) })
+      # - **force_non_association_create**: force to build instances of the
+      #   nested model without calling association build methods
+      #   (`build_{association}` or `{association}.build`). Can be usefull if,
+      #   for some specific reason, you need an object to _not_ be created on
+      #   the association, for example if you did not want `after_add` callbacks
+      #   to be triggered. Defaults to false.
+      #
+      # Compatibility options:
+      #
+      # These options are supported for backward compatibility with the original
+      # Cocoon. **Support for these options will be removed in the next major
+      # release !**.
+      #
+      # - **insertion_traversal**: a jQuery DOM traversal method name to use in
+      #   combination with **insertion_node** to find the insertion node from
+      #   the trigger. Can be any of `closest`, `parent`, `prev`, `next` or
+      #   `siblings`.
+      #   Expressed in jQuery pseudo-code, the insertion node will be determined
+      #   as the result of `$(trigger).{traversal}({insertion_node})`.
+      # - **render_options**: A nested Hash originally used to pass locals and form
+      #   builder options.
+      module Add
+        # Output a link to add an item in a nested form.
+        #
+        # = Signatures
+        #
+        #   cocooned_add_item_link(label, form, association, options = {})
+        #     # Explicit name
+        #
+        #   cocooned_add_item_link(form, association, options = {}) do
+        #     # Name as a block
+        #   end
+        #
+        #   cocooned_add_item_link(form, association, options = {})
+        #     # Use default name
+        #
+        # See Cocooned::Helpers::Tags::Add main documentation for a reference of
+        # supported parameters.
+        #
+        # See the documentation of +ActionView::Base#link_to+ for additional
+        # options.
+        def cocooned_add_item_link(*args, &block)
+          cocooned_link(Cocooned::Tags::Add, *args, &block)
+        end
+
+        # Output a button to add an item in a nested form.
+        #
+        # = Signatures
+        #
+        #   cocooned_add_item_button(label, form, association, options = {})
+        #     # Explicit name
+        #
+        #   cocooned_add_item_button(form, association, options = {}) do
+        #     # Name as a block
+        #   end
+        #
+        #   cocooned_add_item_button(form, association, options = {})
+        #     # Use default name
+        #
+        # See Cocooned::Helpers::Tags::Add main documentation for a reference of
+        # supported options.
+        def cocooned_add_item_button(*args, &block)
+          cocooned_button(Cocooned::Tags::Add, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/cocooned/helpers/tags/down.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Cocooned
+  module Helpers
+    module Tags
+      # Helpers to generate action triggers to move items down in a nested form.
+      #
+      # = Signatures
+      #
+      #   {method}(label, form, options = {})
+      #     # Explicit name
+      #
+      #   {method}(form, options = {}) do
+      #     # Name as a block
+      #   end
+      #
+      #   {method}(form, options = {})
+      #     # Use default name
+      #
+      # = Parameters
+      #
+      # `label` is the text to be used as the link label. See the main
+      # documentation for Cocooned::Helpers::Tags for more about labelling.
+      #
+      # `form` is your form builder. Can be a SimpleForm::Builder,
+      # Formtastic::Builder or a standard Rails FormBuilder.
+      module Down
+        # Output a link to move an item down.
+        #
+        # = Signatures
+        #
+        #   cocooned_move_item_down_link(label, form, options = {})
+        #     # Explicit name
+        #
+        #   cocooned_move_item_down_link(form, options = {}) do
+        #     # Name as a block
+        #   end
+        #
+        #   cocooned_move_item_down_link(form, options = {})
+        #     # Use default name
+        #
+        # See Cocooned::Helpers::Tags::Down main documentation for a reference
+        # of supported parameters.
+        #
+        # See the documentation of +ActionView::Base#link_to+ for additional
+        # options.
+        def cocooned_move_item_down_link(*args, &block)
+          cocooned_link(Cocooned::Tags::Down, *args, &block)
+        end
+
+        # Output a button to move an item down.
+        #
+        # = Signatures
+        #
+        #   cocooned_move_item_down_button(label, form, options = {})
+        #     # Explicit name
+        #
+        #   cocooned_move_item_down_button(form, options = {}) do
+        #     # Name as a block
+        #   end
+        #
+        #   cocooned_move_item_down_button(form, options = {})
+        #     # Use default name
+        #
+        # See Cocooned::Helpers::Tags::Add main documentation for a reference of
+        # supported parameters.
+        #
+        # See the documentation of +ActionView::Helpers::FormBuilder#button+ for
+        # valid options.
+        def cocooned_move_item_down_button(*args, &block)
+          cocooned_button(Cocooned::Tags::Down, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/cocooned/helpers/tags/remove.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Cocooned
+  module Helpers
+    module Tags
+      # Helpers to generate action triggers to remove items in a nested form.
+      #
+      # = Signatures
+      #
+      #   {method}(label, form, options = {})
+      #     # Explicit name
+      #
+      #   {method}(form, options = {}) do
+      #     # Name as a block
+      #   end
+      #
+      #   {method}(form, options = {})
+      #     # Use default name
+      #
+      # = Parameters
+      #
+      # `label` is the text to be used as the link label. See the main
+      # documentation for Cocooned::Helpers::Tags for more about labelling.
+      #
+      # `form` is your form builder. Can be a SimpleForm::Builder,
+      # Formtastic::Builder or a standard Rails FormBuilder.
+      module Remove
+        # Output a link to remove an item (and an hidden field to mark
+        # it as destroyed if it has already been persisted).
+        #
+        # = Signatures
+        #
+        #   cocooned_remove_item_link(label, form, options = {})
+        #     # Explicit name
+        #
+        #   cocooned_remove_item_link(form, options = {}) do
+        #     # Name as a block
+        #   end
+        #
+        #   cocooned_remove_item_link(form, options = {})
+        #     # Use default name
+        #
+        # See Cocooned::Helpers::Tags::Remove main documentation for a reference
+        # of supported parameters.
+        #
+        # See the documentation of +ActionView::Base#link_to+ for additional
+        # options.
+        def cocooned_remove_item_link(*args, &block)
+          cocooned_link(Cocooned::Tags::Remove, *args, &block)
+        end
+
+        # Output a button to remove an item (and an hidden field to mark
+        # it as destroyed if it has already been persisted).
+        #
+        # = Signatures
+        #
+        #   cocooned_remove_item_link(label, form, options = {})
+        #     # Explicit name
+        #
+        #   cocooned_remove_item_link(form, options = {}) do
+        #     # Name as a block
+        #   end
+        #
+        #   cocooned_remove_item_link(form, options = {})
+        #     # Use default name
+        #
+        # See Cocooned::Helpers::Tags::Remove main documentation for a reference
+        # of supported parameters.
+        #
+        # See the documentation of +ActionView::Base#link_to+ for additional
+        # options.
+        def cocooned_remove_item_button(*args, &block)
+          cocooned_button(Cocooned::Tags::Remove, *args, &block)
+        end
+      end
+    end
+  end
+end