cocooned 2.5.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f2af10b0b746c5011676ba112458b540d192803ca0b1ddf527464b748003ed5
-  data.tar.gz: 0246debfd5bf517de6b2ae2ef10bc2caa117c732c855943ee998513ba4dd5ead
+  metadata.gz: 4452a44114a2a49166816f4966764b27cccf5de838568acb29fc68544fb96878
+  data.tar.gz: 7d28fe11d1d06bb28433be2587411471ce79db0983347de07acf40a2e62bc3d7
 SHA512:
-  metadata.gz: e6636bfb5b815f29ce6285bd504bc0c9a43196f70d0b0b21e771bee1e67338eec2ff64251012e8f5d67d2d54606c8538c2eb27a57f99ef70242d81bc6d5672e2
-  data.tar.gz: f8ba105ad6016c0ee6d846344543d7afda37cd7e52a07baa1ab80cc7392bbe0abf8ba32ec59e8201d5c0daa9ab19583973061d174909e27a1be958d157d6d58c
+  metadata.gz: 8af0b42463b95aac1f4bf2c1f290a75735a1ebb304fe333f79124da55bb2f0d694c05e23292b3328accb0b70c596205b918a6912757f2e8dbddcd5101f6df4bc
+  data.tar.gz: e95c020441e9c26e4941d49ec7e202dc22af173b02af6bf2023a46260004dceee1e0ca9f352bed232a80b085c819a35f26d9994013a21a76ed65f669d2f4f471

data/CHANGELOG.md

@@ -6,8 +6,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## Version 3.0.0 (2026-01-27)
+
+## Breaking changes
+
+* Respect browser accessibility settings on reduced motion to determinate the default value of the `animate` option (#120)  
+  `animate` will be set to false by default if the `(prefers-reduced-motion: reduce)` media query matches.
+* Proper instances cleanup through [explicit resource management](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Resource_management) (#115)  
+  Introduce a `dispose` method on Cocooned instances to clean up what was done in the `start` method: remove event listeners and delete references to the disposed instance, so it can be cleanly garbage collected.
+  This may require you to install a polyfill for `DisposableStack` and `[Symbol.dispose]()` to support older browsers.
+
+To not introduce too many breaking changes in a single release, removal of long-time deprecated features have been postponed to Cocooned 4.0 (#122)
+
+## Added
+
+* Optional Stimulus integration (#119)
+  Introduce two ways to integrate Cocooned with Stimulus: `registerCocoonedContainer` and `useCocooned`. See documentation for details.
+
 ### Changed
 
+* Add Ruby 4.0 to the test matrix (#112)
+
 ## Version 2.5.0 (2025-10-23)
 
 * Upgrade to use `eslint ~> 9` (#103)

data/app/assets/javascripts/cocoon.js

@@ -1,3 +1,3 @@
 //= require 'cocooned'
 
-/* TODO: Remove in 3.0 */
+/* TODO: Remove in 4.0 */

data/app/assets/javascripts/cocooned.js

@@ -36,6 +36,153 @@
     }
   }
 
+  class Traverser {
+    constructor (origin, traversal) {
+      this.#origin = origin;
+      this.#traversal = traversal;
+    }
+
+    resolve (selector) {
+      if (this.#traversal in this.#origin && typeof this.#origin[this.#traversal] === 'function') {
+        return this._tryMethod(this.#traversal, selector)
+      }
+
+      if (this.#traversal in this.#origin) {
+        return this._tryProperty(this.#traversal)
+      }
+
+      const method = `_${this.#traversal}`;
+      if (method in this) {
+        return this[method](selector)
+      }
+
+      return null
+    }
+
+    /* Protected and private attributes and methods */
+    #origin
+    #traversal
+
+    _tryMethod (method, selector) {
+      try {
+        const resolved = this.#origin[method](selector);
+        if (resolved instanceof HTMLElement) {
+          return resolved
+        }
+      } catch (e) {}
+
+      return null
+    }
+
+    _tryProperty (property) {
+      const resolved = this.#origin[property];
+      if (resolved instanceof HTMLElement) {
+        return resolved
+      }
+
+      return null
+    }
+
+    _parent (selector) {
+      if (this.#origin.parentElement.matches(selector)) {
+        return this.#origin.parentElement
+      }
+      return null
+    }
+
+    _prev (selector) {
+      if (this.#origin.previousElementSibling.matches(selector)) {
+        return this.#origin.previousElementSibling
+      }
+      return null
+    }
+
+    _next (selector) {
+      if (this.#origin.nextElementSibling.matches(selector)) {
+        return this.#origin.nextElementSibling
+      }
+      return null
+    }
+
+    _siblings (selector) {
+      return this.#origin.parentElement.querySelector(selector)
+    }
+  }
+
+  class Deprecator {
+    logger
+    package
+    version
+
+    constructor (version, packageName, logger) {
+      this.version = version;
+      this.package = packageName;
+      this.logger = logger;
+    }
+
+    warn (message, replacement = null) {
+      if (message in this.#emitted) {
+        return
+      }
+
+      const warning = `${message}. It will be removed from ${this.package} ${this.version}`;
+      const alternative = (replacement !== null ? `, use ${replacement} instead` : '');
+      this.logger.warn(`DEPRECATION WARNING: ${warning}${alternative}.`);
+
+      this.#emitted[message] = true;
+    }
+
+    /* Protected and private attributes and methods */
+    #emitted = Object.create(null)
+  }
+
+  const deprecators = Object.create(null);
+
+  function deprecator (version, packageName = 'Cocooned', logger = console) {
+    const hash = [version, packageName].join('#');
+    if (!(hash in deprecators)) {
+      deprecators[hash] = new Deprecator(version, packageName, logger);
+    }
+
+    return deprecators[hash]
+  }
+
+  class Listener {
+    constructor (eventTarget, type, listener) {
+      this.#eventTarget = eventTarget;
+      this.#type = type;
+      this.#listener = listener;
+
+      this.#eventTarget.addEventListener(this.#type, this.#listener);
+    }
+
+    dispose () {
+      this.#eventTarget.removeEventListener(this.#type, this.#listener);
+    }
+
+    /* Protected and private attributes and methods */
+    #eventTarget
+    #type
+    #listener
+  }
+
+  disposable(Listener);
+
+  if (typeof Symbol.dispose !== "symbol") {
+    console.warn(`
+    Cocooned use Disposable objects but they are not supported by your browser.
+    See Cocooned documentation for polyfill options.
+  `);
+  }
+
+  function disposable(klass) {
+    if (typeof Symbol.dispose !== "symbol") {
+      return
+    }
+
+    klass.prototype[Symbol.dispose] = klass.prototype.dispose;
+  }
+
   // Borrowed from <https://stackoverflow.com/a/2117523>
   function uuidv4 () {
     return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, c =>
@@ -69,13 +216,22 @@
     ]
   }
 
+  const canAnimate = (
+    'animate' in document.createElement('div') &&
+    typeof document.createElement('div').animate === 'function'
+  );
+
+  const shouldAnimate = (
+    'matchMedia' in window &&
+    !window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+
   const instances = Object.create(null);
 
   class Base {
     static get defaultOptions () {
-      const element = document.createElement('div');
       return {
-        animate: ('animate' in element && typeof element.animate === 'function'),
+        animate: canAnimate && shouldAnimate,
         animator: defaultAnimator,
         duration: 450
       }
@@ -98,7 +254,7 @@
 
     constructor (container, options) {
       this._container = container;
-      this._uuid = uuidv4();
+      this.__uuid = uuidv4();
       this._options = this.constructor._normalizeOptions({
         ...this.constructor.defaultOptions,
         ...('cocoonedOptions' in container.dataset ? JSON.parse(container.dataset.cocoonedOptions) : {}),
@@ -115,16 +271,31 @@
     }
 
     start () {
-      this.container.dataset.cocoonedContainer = true;
-      this.container.dataset.cocoonedUuid = this._uuid;
-      instances[this._uuid] = this;
+      if (!('cocoonedContainer' in this.container.dataset)) {
+        deprecator('4.0').warn(
+          'CSS classes based detection is deprecated',
+          'cocooned_container Rails helper to declare containers'
+        );
+        this.container.dataset.cocoonedContainer = true;
+      }
+
+      this.container.dataset.cocoonedUuid = this.__uuid;
+      this._onDispose(() => delete this.container.dataset.cocoonedUuid);
+
+      instances[this.__uuid] = this;
+      this._onDispose(() => delete instances[this.__uuid]);
 
       const hideDestroyed = () => { hideMarkedForDestruction(this, this.items); };
 
       hideDestroyed();
-      this.container.ownerDocument.addEventListener('page:load', hideDestroyed);
-      this.container.ownerDocument.addEventListener('turbo:load', hideDestroyed);
-      this.container.ownerDocument.addEventListener('turbolinks:load', hideDestroyed);
+      this._addEventListener(this.container.ownerDocument, 'page:load', hideDestroyed);
+      this._addEventListener(this.container.ownerDocument, 'turbo:load', hideDestroyed);
+      this._addEventListener(this.container.ownerDocument, 'turbolinks:load', hideDestroyed);
+    }
+
+    dispose () {
+      this._disposer.dispose();
+      this._container = null;
     }
 
     notify (node, eventType, eventData) {
@@ -180,8 +351,21 @@
 
     _container
     _options
-    __uuid
+    __disposer
     __emitter
+    __uuid
+
+    _addEventListener (target, type, listener) {
+      this._disposer.use(new Listener(target, type, listener));
+    }
+
+    get _disposer () {
+      if (typeof this.__disposer === 'undefined') {
+        this.__disposer = new DisposableStack();
+      }
+
+      return this.__disposer
+    }
 
     get _emitter () {
       if (typeof this.__emitter === 'undefined') {
@@ -191,6 +375,10 @@
       return this.__emitter
     }
 
+    _onDispose (callback) {
+      this._disposer.defer(callback);
+    }
+
     _selectors (name) {
       return this.constructor.selectors[name]
     }
@@ -205,6 +393,8 @@
     }
   }
 
+  disposable(Base);
+
   class Trigger {
     constructor (trigger, cocooned) {
       this._trigger = trigger;
@@ -277,117 +467,6 @@
     }
   }
 
-  class Traverser {
-    constructor (origin, traversal) {
-      this.#origin = origin;
-      this.#traversal = traversal;
-    }
-
-    resolve (selector) {
-      if (this.#traversal in this.#origin && typeof this.#origin[this.#traversal] === 'function') {
-        return this._tryMethod(this.#traversal, selector)
-      }
-
-      if (this.#traversal in this.#origin) {
-        return this._tryProperty(this.#traversal)
-      }
-
-      const method = `_${this.#traversal}`;
-      if (method in this) {
-        return this[method](selector)
-      }
-
-      return null
-    }
-
-    /* Protected and private attributes and methods */
-    #origin
-    #traversal
-
-    _tryMethod (method, selector) {
-      try {
-        const resolved = this.#origin[method](selector);
-        if (resolved instanceof HTMLElement) {
-          return resolved
-        }
-      } catch (e) {}
-
-      return null
-    }
-
-    _tryProperty (property) {
-      const resolved = this.#origin[property];
-      if (resolved instanceof HTMLElement) {
-        return resolved
-      }
-
-      return null
-    }
-
-    _parent (selector) {
-      if (this.#origin.parentElement.matches(selector)) {
-        return this.#origin.parentElement
-      }
-      return null
-    }
-
-    _prev (selector) {
-      if (this.#origin.previousElementSibling.matches(selector)) {
-        return this.#origin.previousElementSibling
-      }
-      return null
-    }
-
-    _next (selector) {
-      if (this.#origin.nextElementSibling.matches(selector)) {
-        return this.#origin.nextElementSibling
-      }
-      return null
-    }
-
-    _siblings (selector) {
-      return this.#origin.parentElement.querySelector(selector)
-    }
-  }
-
-  class Deprecator {
-    logger
-    package
-    version
-
-    constructor (version, packageName, logger) {
-      this.version = version;
-      this.package = packageName;
-      this.logger = logger;
-    }
-
-    warn (message, replacement = null) {
-      if (message in this.#emitted) {
-        return
-      }
-
-      const warning = `${message}. It will be removed from ${this.package} ${this.version}`;
-      const alternative = (replacement !== null ? `, use ${replacement} instead` : '');
-      this.logger.warn(`DEPRECATION WARNING: ${warning}${alternative}.`);
-
-      this.#emitted[message] = true;
-    }
-
-    /* Protected and private attributes and methods */
-    #emitted = Object.create(null)
-  }
-
-  const deprecators = Object.create(null);
-
-  function deprecator (version, packageName = 'Cocooned', logger = console) {
-    const hash = [version, packageName].join('#');
-    if (!(hash in deprecators)) {
-      deprecators[hash] = new Deprecator(version, packageName, logger);
-    }
-
-    return deprecators[hash]
-  }
-
   class Extractor {
     constructor (trigger, cocooned) {
       this.#trigger = trigger;
@@ -466,7 +545,7 @@
         return this.#trigger.ownerDocument.querySelector(node)
       }
 
-      deprecator('3.0').warn('associationInsertionTraversal is deprecated');
+      deprecator('4.0').warn('associationInsertionTraversal is deprecated');
       const traverser = new Traverser(this.#trigger, this.#dataset.associationInsertionTraversal);
 
       return traverser.resolve(node)
@@ -736,12 +815,12 @@
         .map(element => Add.create(element, this))
         .filter(trigger => this.toContainer(trigger.insertionNode) === this.container);
 
-      this.addTriggers.forEach(add => add.trigger.addEventListener(
-        'click',
-        clickHandler$1((e) => add.handle(e))
-      ));
+      this.addTriggers.forEach(add => {
+        this._addEventListener(add.trigger, 'click', clickHandler$1((e) => add.handle(e)));
+      });
 
-      this.container.addEventListener(
+      this._addEventListener(
+        this.container,
         'click',
         itemDelegatedClickHandler(this, this._selector('triggers.remove'), (e) => {
           const trigger = new Remove(e.target, this);
@@ -795,7 +874,7 @@
         return
       }
 
-      this.container.addEventListener('cocooned:before-insert', e => {
+      this._addEventListener(this.container, 'cocooned:before-insert', e => {
         if (this.items.length < this.options.limit) {
           return
         }
@@ -943,16 +1022,16 @@
         return
       }
 
-      this.container.addEventListener('cocooned:after-insert', e => this._reindexer.reindex(e));
-      this.container.addEventListener('cocooned:after-remove', e => this._reindexer.reindex(e));
-      this.container.addEventListener('cocooned:after-move', e => this._reindexer.reindex(e));
+      this._addEventListener(this.container, 'cocooned:after-insert', e => this._reindexer.reindex(e));
+      this._addEventListener(this.container, 'cocooned:after-remove', e => this._reindexer.reindex(e));
+      this._addEventListener(this.container, 'cocooned:after-move', e => this._reindexer.reindex(e));
       const form = this.container.closest('form');
       if (form !== null) {
-        form.addEventListener('submit', e => this._reindexer.reindex(e));
+        this._addEventListener(form, 'submit', e => this._reindexer.reindex(e));
       }
 
-      this.container.addEventListener('click', clickHandler(this, this._selector('triggers.up'), Up));
-      this.container.addEventListener('click', clickHandler(this, this._selector('triggers.down'), Down));
+      this._addEventListener(this.container, 'click', clickHandler(this, this._selector('triggers.up'), Up));
+      this._addEventListener(this.container, 'click', clickHandler(this, this._selector('triggers.down'), Down));
     }
 
     /* Protected and private attributes and methods */
@@ -1051,7 +1130,7 @@
 
   $(() => cocoonAutoStart($));
 
-  deprecator('3.0').warn(
+  deprecator('4.0').warn(
     'Loading @notus.sh/cocooned/cocooned is deprecated',
     '@notus.sh/cocooned/jquery, @notus.sh/cocooned or `@notus.sh/cocooned/src/cocooned/cocooned`'
   );

data/app/assets/stylesheets/cocoon.css

@@ -2,4 +2,4 @@
  *= require cocooned
  */
 
-/* TODO: Remove in 3.0 */
+/* TODO: Remove in 4.0 */

data/app/assets/stylesheets/cocooned.css

@@ -1 +1 @@
-/* TODO: Remove in 3.0 */
+/* TODO: Remove in 4.0 */

data/cocooned.gemspec

@@ -13,8 +13,8 @@ Gem::Specification.new do |spec|
 
   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.
+    Rails nested form made easy, with standard Rails form builder, Formtastic or SimpleForm.
+    Unobtrusive and zero-dependencies JavaScript included, with optional integration with jQuery and Stimulus.
   DESC
   spec.homepage = 'https://github.com/notus-sh/cocooned'
 
@@ -42,7 +42,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'rails', '>= 7.2', '< 8.2'
 
-  spec.add_development_dependency 'bundler', '~> 2.1'
+  spec.add_development_dependency 'bundler', '>= 2.1'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.11'
 end

data/lib/cocooned/deprecation.rb

@@ -26,14 +26,14 @@ module Cocooned
           cocooned_add_item_link(...)
         end
         deprecate link_to_add_association: 'Use :cocooned_add_link instead',
-                  deprecator: Deprecation['3.0']
+                  deprecator: Deprecation['4.0']
 
         # @deprecated: Please use {#cocooned_remove_item_link} instead
         def link_to_remove_association(...)
           cocooned_remove_item_link(...)
         end
         deprecate link_to_remove_association: 'Use :cocooned_remove_item_link instead',
-                  deprecator: Deprecation['3.0']
+                  deprecator: Deprecation['4.0']
       end
     end
 
@@ -44,7 +44,7 @@ module Cocooned
         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)
+          Deprecation['4.0'].warn 'Support for the :cocoon i18n namespace will be removed in 4.0', caller_locations(3)
           super + %w[cocoon]
         end
       end
@@ -57,7 +57,7 @@ module Cocooned
         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)
+          Deprecation['4.0'].warn 'Compatibility with options named data-* will be removed in 4.0', caller_locations(3)
           html_data_normalize super.merge(data_options)
         end
 
@@ -78,7 +78,7 @@ module Cocooned
 
         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)
+            Deprecation['4.0'].warn 'Support for the :insertion_traversal will be removed in 4.0', caller_locations(3)
           end
 
           super
@@ -91,7 +91,7 @@ module Cocooned
         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)
+          Deprecation['4.0'].warn 'Support for :render_options will be removed in 4.0', caller_locations(3)
           legacy_options = options.delete(:render_options)
 
           super.tap do |opts|

data/lib/cocooned/helpers/containers.rb

@@ -32,10 +32,8 @@ module Cocooned
       def cocooned_container(*args, &)
         options = args.extract_options!.dup
         name = args.shift || :div
-        defaults = cocooned_wrapper_defaults(options, %w[cocooned-container], :'cocooned-container')
-        defaults[:data][:cocooned_options] = options.extract!(:limit, :reorderable).to_json
 
-        content_tag(name, *args, **options.deep_merge(defaults), &)
+        content_tag(name, *args, **cocooned_container_options(options), &)
       end
 
       # Wrap content with the expected markup for a Cocooned item.
@@ -56,17 +54,30 @@ module Cocooned
       def cocooned_item(*args, &)
         options = args.extract_options!.dup
         name = args.shift || :div
-        defaults = cocooned_wrapper_defaults(options, %w[cocooned-item nested-fields], :'cocooned-item')
 
-        content_tag(name, *args, **options.deep_merge(defaults), &)
+        content_tag(name, *args, **cocooned_item_options(options), &)
       end
 
       protected
 
-      def cocooned_wrapper_defaults(options, additional_classes, mark)
-        classes = Array.wrap(options.delete(:class)).flat_map { |k| k.to_s.split }.compact_blank
+      def cocooned_container_options(options)
+        options.deep_merge(
+          class: token_list(options.delete(:class), %w[cocooned-container]),
+          data: {
+            controller: [options.dig(:data, :controller), :cocooned].compact_blank.map(&:to_s).join(' '),
+            cocooned_container: true,
+            cocooned_options: options.extract!(:limit, :reorderable).to_json
+          }
+        )
+      end
 
-        { class: (classes + additional_classes), data: { mark => true } }
+      def cocooned_item_options(options)
+        options.deep_merge(
+          class: token_list(options.delete(:class), %w[cocooned-item nested-fields]),
+          data: {
+            cocooned_item: true
+          }
+        )
       end
     end
   end

data/lib/cocooned/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cocooned
-  VERSION = '2.5.0'
+  VERSION = '3.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cocooned
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Gaël-Ian Havard
@@ -34,14 +34,14 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.1'
 - !ruby/object:Gem::Dependency
@@ -72,9 +72,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.11'
-description: " 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. "
+description: " Rails nested form made easy, with standard Rails form builder, Formtastic
+  or SimpleForm. Unobtrusive and zero-dependencies JavaScript included, with optional
+  integration with jQuery and Stimulus. "
 email:
 - gael-ian@notus.sh
 - nathan@dixis.com
@@ -136,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Form builder agnostic handling of Rails nested forms
 test_files: []