abyme 0.1.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75ea02cf1745593dc62c0bd09cf27fa431f73916142bf5a51266bfe12e065e9e
-  data.tar.gz: 8bd81717590e1a37c7c4d4011f4061a5da49cc2bee542e2648f41af0442b9a0e
+  metadata.gz: c47483c64b5a49b57f83cf3e779b089aff6cfb218a6cc4cc56c35b7cf14ea44a
+  data.tar.gz: ad6152628fe3731f04a19bf3afabf45f1f9c2fc92f7af2637ce990cd8ad801e8
 SHA512:
-  metadata.gz: ab0079016a2c44ec66bdc343e85fa44332f496e815c696f7a8ae2a8de40bb8d379a0a605193d385065d40fb43a4fd7f40fae3f51572fe03c93732753a7b0e1b7
-  data.tar.gz: ec0134da02c6b2c550577a907402288d4e51e6721c7afa4a0fad8bb080941d8a6e5e91213ad2f88b2aab798f827b45ef1a44cd95ae07de946fab9d2fcb9c4495
+  metadata.gz: 1fb02ef0524a28ae5a7445c1f51d3144e1ae11b4bbe710dd5e4d87b8a767d4b0e598f512293892cc114f06e492c73074a4c409a902a2911e29b0329bdf0a1a96
+  data.tar.gz: 6bb56a17944fd6f4577580bc19cb5a004903e7dc149c65aedbc3d6e34469565c66f26318147cdb7cde107d7adc06ad3176b875557c6cb8ef8412489d3131ea09

data/.gitignore

@@ -0,0 +1,21 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+yarn-error.log
+/node_modules
+
+# rspec failure tracking
+.rspec_status
+node_modules
+
+# Dummy app
+spec/dummy/db/*.sqlite3
+spec/dummy/db/*.sqlite3-journal
+spec/dummy/db/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache

data/.rspec

@@ -0,0 +1 @@
+--require rails_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 2.0.2

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in abyme.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,96 @@
+PATH
+  remote: .
+  specs:
+    abyme (0.2.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (6.0.3.4)
+      actionview (= 6.0.3.4)
+      activesupport (= 6.0.3.4)
+      rack (~> 2.0, >= 2.0.8)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (6.0.3.4)
+      activesupport (= 6.0.3.4)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activesupport (6.0.3.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    builder (3.2.4)
+    concurrent-ruby (1.1.7)
+    crass (1.0.6)
+    diff-lcs (1.4.4)
+    erubi (1.9.0)
+    i18n (1.8.5)
+      concurrent-ruby (~> 1.0)
+    loofah (2.7.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (1.0.0)
+    mini_portile2 (2.4.0)
+    minitest (5.14.2)
+    nokogiri (1.10.10)
+      mini_portile2 (~> 2.4.0)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-dummy (0.1.0)
+      railties
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.0.3.4)
+      actionpack (= 6.0.3.4)
+      activesupport (= 6.0.3.4)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.20.3, < 2.0)
+    rake (13.0.1)
+    rspec-core (3.9.3)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-rails (4.0.1)
+      actionpack (>= 4.2)
+      activesupport (>= 4.2)
+      railties (>= 4.2)
+      rspec-core (~> 3.9)
+      rspec-expectations (~> 3.9)
+      rspec-mocks (~> 3.9)
+      rspec-support (~> 3.9)
+    rspec-support (3.9.3)
+    sqlite3 (1.4.2)
+    thor (1.0.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    zeitwerk (2.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  abyme!
+  bundler (~> 2.0)
+  rails-dummy
+  rake (~> 13.0)
+  rspec-rails
+  sqlite3
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Louis Sommer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,341 @@
+# Abyme 🕳
+
+abyme is a modern take on handling dynamic nested forms in Rails 6+ using StimulusJS.
+
+## Disclaimer
+This project is still a work in progress and subject to change. We encourage not to use it in production code just yet.
+
+Any enhancement proposition or bug report welcome !
+
+General remarks : 
+* A demo app will soon be online.
+* For now, the gem is tested through our demo app. Specific autonomous tests will be transfered/written in the following days.
+* Help is very much wanted on the Events part of the gem (see bottom of this documentation)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'abyme'
+```
+
+And then execute:
+
+    $ bundle
+    $ yarn add abyme
+
+
+Assuming you [already installed Stimulus](https://stimulusjs.org/handbook/introduction), add this in `app/javascript/controllers/index.js` :
+```javascript
+// app/javascript/controllers/index.js
+import { Application } from "stimulus"
+import { definitionsFromContext } from "stimulus/webpack-helpers"
+// Add this line below
+import { AbymeController } from 'abyme'
+
+const application = Application.start()
+const context = require.context("controllers", true, /_controller\.js$/)
+application.load(definitionsFromContext(context))
+// And this one
+application.register('abyme', AbymeController)
+```
+
+## What are nested forms and why a new gem ?
+
+Nested forms (or more accurately *nested fields* or *nested attributes*) are forms that deal with associated models. Let's picture a `Project` model that `has_many :tasks`. A nested form will allow you to create a project along with one or several tasks **within a single form**. If `Tasks` were to have associations on their own, like `:comments`, you could also, still in the same form, instantiate comments along with their parent models.
+
+Rails provides [its own helper](https://api.rubyonrails.org/v6.0.1/classes/ActionView/Helpers/FormHelper.html#method-i-fields_for) to handle nested attributes. **abyme** is basically a smart wrapper around it, offering easier syntax along with some fancy additions. To work properly, some configuration will be required in both models and controllers (see below).
+
+What Rails doesn't provide natively is the possibility to **dynamically add new associations on the fly**, which requires Javascript implementation. What this means it that you would normally have to know in advance how many fields you'd like to display (1, 2 or any number of `:tasks`), which isn't very usable in this day and age. This is what the [cocoon gem](https://github.com/nathanvda/cocoon) has been helping with for the past 7 years. This gem still being implemented in JQuery (which [Rails dropped as a dependency](https://github.com/rails/rails/issues/25208)), we wanted to propose a more plug'n'play approach, using Basecamp's [Stimulus](https://stimulusjs.org/) instead.
+
+## Basic Configuration
+
+### Models
+Let's consider a to-do application with Projects having many Taks, themselves having many Comments.
+```ruby
+# models/project.rb
+class Project < ApplicationRecord
+  has_many :tasks
+  validates :title, :description, presence: true
+end
+
+# models/task.rb
+class Task < ApplicationRecord
+  belongs_to :project
+  has_many :comments
+  validates :title, :description, presence: true
+end
+
+# models/comment.rb
+class Comment < ApplicationRecord
+  belongs_to :task
+  validates :content, presence: true
+end
+```
+The end-goal here is to be able to create a project along with different tasks, and immediately add comments to some of these tasks ; all within a single form.
+What we'll have is a 2-level nested form. Thus, we'll need to configure our `Project` and `Task` models like so :
+```ruby
+# models/project.rb
+class Project < ApplicationRecord
+  include Abyme::Model
+  has_many :tasks, inverse_of: :project
+  # ...
+  abyme_for :tasks
+end
+
+# models/task.rb
+class Task < ApplicationRecord
+  include Abyme::Model
+  has_many :comments, inverse_of: :task
+  # ...
+  abyme_for :comments
+end
+```
+Note the use of the `inverse_of` option. It is needed for Rails to effectively associate children to their yet unsaved parent. Have a peek to the bottom of [this page](https://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html#method-i-accepts_nested_attributes_for) for more info.
+
+### Controller
+Since we're dealing with one form, we're only concerned with one controller : the one the form routes to. In our example, this would be the `ProjectsController`.
+The only configuration needed here will concern our strong params. Nested attributes require a very specific syntax to white-list the permitted attributes. It looks like this :
+
+```ruby
+def project_params
+  params.require(:project).permit(
+    :title, :description, tasks_attributes: [
+      :id, :title, :description, :_destroy, comments_attributes: [
+        :id, :content, :_destroy
+      ]
+    ]
+  )
+end
+```
+A few explanations here. 
+
+* To permit a nested model attributes in your params, you'll need to pass the `association_attributes: [...]` hash at the end of your resource attributes. Key will always be `association_name` followed by `_attributes`, while the value will be an array of symbolized attributes, just like usual.
+
+> **Note**: if your association is a singular one (`has_one` or `belongs_to`) the association will be singular ; if a Project `has_one :owner`, you would then need to pass `owner_attributes: [...]`)
+
+* You may have remarked the presence of `id` and `_destroy` among those params. These are necessary for edit actions : if you want to allow your users to destroy or update existing records, these are **mandatory**.  Otherwise, Rails won't be able to recognize these records as existing ones, and will just create new ones. More info [here](https://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html).
+
+## Basic Usage
+
+Dealing with nested attributes means you'll generally have to handle a few things inside your form:
+* Display fields for the **persisted records** (here, already existing `:tasks`)
+* Display fields for the **new records** (future `:tasks` not yet persisted)
+* A button to **trigger the addition** of fields for a new resource (an `Add a new task` button)
+* A button to **remove fields** for a given resource (`Remove task`)
+
+abyme provides helper methods for all these. Here's how our form for `Project` looks like when using default values:
+
+```ruby
+# views/projects/_form.html.erb
+<%= simple_form_for @project do |f| %>
+  <%= f.input :title %>
+  <%= f.input :description %>
+  <%= f.submit 'Save' %>
+
+  <%= abymize(:tasks, f) do |abyme| %>
+    <%= abyme.records %>
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+<% end %>
+```
+
+`abyme.records` will contain the persisted associations fields, while `abyme.new_records` will contain fields for the new associations. `add_association` will by default generate a button with a text of type "Add `resource_name`". To work properly, this method **has** to be called **inside the block** passed to the `abymize` method.
+
+Now where's the code for these fields ? abyme will assume a **partial** to be present in the directory `/views/abyme` with a *name respecting this naming convention* (just like with [cocoon](https://github.com/nathanvda/cocoon#basic-usage)): `_singular_association_name_fields.html.erb`. 
+
+This partial might look like this:
+```ruby
+# views/abyme/_task_fields.html.erb
+<%= f.input :title %>
+<%= f.input :description %>
+<%= f.hidden_field :_destroy %>
+
+<%= remove_association(tag: :div) do %>
+  <i class="fas fa-trash"></i>
+<% end %>
+```
+
+Note the presence of the `remove_association` button. Here, we pass it an option to make it a `<div>`, as well as a block to customize its content. Don't forget the `_destroy` attribute, needed to mark items for destruction.
+
+### What about the controller ?
+
+What about it ? Well, not much. That's the actual magical thing about `nested_attributes`: once your model is aware of its acceptance of those for a given association, and your strong params are correctly configured, there's nothing else to do.
+`@project.create(project_params)` is all you'll need to save a project along with its descendants 👨‍👧‍👧
+
+### Auto mode
+
+Let's now take care of our comments fields. We'll add these using our neat *automatic mode*: just stick this line at the end of the partial:
+```ruby
+# views/abyme/_task_fields.html.erb
+# ... rest of the partial above
+<%= abymize(:comments, f) %>
+```
+Where's the rest of the code ? Well, if the default configuration you saw above in the `_form.html.erb` suits you, and the order in which the different resources appear feels right (persisted first, new fields second, and the 'Add' button last), then you can just spare the block, and it will be taken care of for you. We'll just write our `_comment_fields.html.erb` partial in the `views/abyme` directory and we'll be all set.
+
+## Advanced usage
+### Models
+In models, the `abyme_for :association` acts as an alias for this command :
+
+```ruby
+  accepts_nested_attributes_for :association, reject_if: :all_blank, :allow_destroy: true
+```
+
+Which is the way you would configure `nested_attributes` 90% of the time. Should you want to pass [any available options](https://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html#method-i-accepts_nested_attributes_for) to this method or change those, you may just pass them as with the original method :
+```ruby
+  abyme_for :association, limit: 3, allow_destroy: false
+```
+
+### Views
+
+#### #records
+A few options can be passed to `abyme.records`:
+* `collection:` : allows you to pass a collection of your choice to only display specific objects.
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    <%= abyme.records(collection: @project.tasks.where(done: false)) %>
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+```
+* `order:` : allows you to pass an ActiveRecord `order` method to sort your instances the way you want.
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    <%= abyme.records(order: { created_at: :asc }) %>
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+```
+* `partial:` : allows you to indicate a custom partial, if one has not already been passed to `abymize`.
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    <%= abyme.records %>
+    <%= abyme.new_records(partial: 'projects/task_fields') %>
+    <%= add_association %>
+  <% end %>
+```
+* `fields_html:` : gives you the possibility to add any HTML attribute you may want to each set of fields. By default, an `abyme--fields` and an `singular_association-fields` class are already present.
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    <%= abyme.records(fields_html: { class: "some-class" }) %>
+    # Every set of persisted fields will have these 3 classes : 'abyme--fields', 'task-fields', and 'some-class'
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+```
+* `wrapper_html:` : gives you the possibility to add any HTML attribute you may want to the wrapper containing all fields.
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    <%= abyme.records(wrapper_html: { class: "persisted-records" }) %>
+    # The wrapper containing all persisted task fields will have an id "abyme-tasks-wrapper" and a class "persisted-records"
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+```
+#### #new_records
+Here are the options that can be passed to `abyme.new_records`:
+* `position:` : allows you to specify whether new fields added dynamically should go at the top or at the bottom. `:end` is the default value.
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    <%= abyme.records %>
+    <%= abyme.new_records(position: :start) %>
+    <%= add_association %>
+  <% end %>
+```
+* `partial:` : same as `#records`
+* `fields_html:` : same as `#records`
+* `wrapper_html:` : same as `#records`
+
+#### #add_association, #remove_association
+These 2 methods behave the same. Here are their options :
+* `tag:` : allows you to specify a tag of your choosing, like `:a`, or `:div`. Default is `:button`.
+* `content:` : the text to display inside the element. Default is `Add association_name`
+* `html:` : gives you the possibility to add any HTML attribute you may want to the element.
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    # ...
+    <%= add_association(tag: :a, content: "Add a super task", html: {id: "add-super-task"}) %>
+  <% end %>
+```
+
+As you may have seen above, you can also pass a block to the method to give it whatever HTML content you want :
+```ruby
+  <%= abymize(:tasks, f) do |abyme| %>
+    # ...
+    <%= add_association(tag: :div, html: {id: "add-super-task", class: "flex"}) do %>
+      <i class="fas fa-plus"></i>
+      <h2>Add a super task</h2>
+    <% end %>
+  <% end %>
+```
+
+
+#### #abymize(:association, form_object)
+This is the container for all your nested fields. It takes two parameters (the symbolized association and the `form_builder`), and some optional ones. Please note an id is automatically added to this element, which value is : `abyme--association`. 
+* `partial:` : allows you to indicate a custom partial path for both `records` and `new_records`
+```ruby
+  <%= abymize(:tasks, f, partial: 'projects/task_fields') do |abyme| %>
+    <%= abyme.records %>
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+```
+* `limit:` : allows you to limit the number of new fields that can be created through JS. If you need to limit the number of associations in database, you will need to add validations. You can also pass an option [in your model as well](https://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html#method-i-accepts_nested_attributes_for).
+```ruby
+  <%= abymize(:tasks, f, limit: 5) do |abyme| %>
+    # Beyond 5 tasks, the add button won't add any more fields. See events section below to see how to handle the 'abyme:limit-reached' event
+    <%= abyme.records %>
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+```
+* `min_count` : by default, there won't be any blank fields added on page load. By passing a `min_count` option, you can set how many empty fields should appear in the form.
+```ruby
+  <%= abymize(:tasks, f, min_count: 1) do |abyme| %>
+    # 1 blank task will automatically be added to the form.
+    <%= abyme.records %>
+    <%= abyme.new_records %>
+    <%= add_association %>
+  <% end %>
+```
+
+*When in auto mode*, the abymize method can take a few options:
+* `button_text:` : this will set the `add_association` button text to the string of your choice.
+* All options that should be passed to either `records` or `new_records` can be passed here and will be passed down.
+
+## Events
+This part is still a work in progress and subject to change. We're providing some basic self-explanatory events to attach to. These are emitted by the main container (created by the `abymize` method).
+
+We're currently thinking about a way to attach to these via Stimulus. Coming soon !
+
+### Lifecycle events
+* `abyme:before-add`
+* `abyme:after-add`
+* `abyme:before-remove`
+* `abyme:after-remove`
+```javascript
+document.getElementById('abyme--tasks').addEventListener('abyme:before-add', yourCallback)
+```
+
+### Other events
+* `abyme:limit-reached`
+```javascript
+const tasksContainer = document.getElementById('abyme--tasks');
+tasksContainer.addEventListener('abyme:limit-reached', () => { 
+  alert('You reached the max number of tasks !')
+});
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bear-in-mind/abyme.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,28 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'rails/dummy/tasks'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+load 'rails/tasks/statistics.rake'
+
+Bundler::GemHelper.install_tasks
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Abyme'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/abyme.gemspec

@@ -0,0 +1,34 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "abyme/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "abyme"
+  spec.version       = Abyme::VERSION::STRING
+  spec.authors       = ["Romain Sanson", "Louis Sommer"]
+  spec.email         = ["louis.sommer@hey.com"]
+
+  spec.summary       = "abyme is the modern way to handle dynamic nested forms in Rails 6+."
+  # spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = "https://github.com/bear-in-mind/abyme"
+  spec.license       = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/bear-in-mind/abyme"
+  spec.metadata["changelog_uri"] = "https://github.com/bear-in-mind/abyme"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "rails-dummy"
+  spec.add_development_dependency "sqlite3"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "abyme"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rails

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" with Rails 4 gems installed from the root of your application.
+
+ENGINE_ROOT = File.expand_path('..', __dir__)
+ENGINE_PATH = File.expand_path('../lib/abyme/engine', __dir__)
+
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+
+require 'rails/all'
+require 'rails/engine/commands'

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/javascript/abyme_controller.js

@@ -0,0 +1,121 @@
+import { Controller } from 'stimulus';
+
+export default class extends Controller {
+  static targets = ['template', 'associations', 'fields', 'newFields'];
+
+  connect() {
+    if (this.count) {
+      this.addDefaultAssociations();
+    }
+  }
+
+  get count() {
+    return this.element.dataset.minCount || 0;
+  }
+  
+  get position() {
+    return this.associationsTarget.dataset.abymePosition === 'end' ? 'beforeend' : 'afterbegin';
+  }
+
+  add_association(event) {
+    if (event) {
+      event.preventDefault();
+    }
+    // check for limit reached
+    if (this.element.dataset.limit && this.limit_check()) {
+      this.create_event('limit-reached')
+      return false
+    }
+
+    const html = this.build_html();
+    this.create_event('before-add');
+    this.associationsTarget.insertAdjacentHTML(this.position, html);
+    this.create_event('after-add');
+  }
+
+  remove_association(event) {
+    event.preventDefault();
+    this.create_event('before-remove');
+    this.mark_for_destroy(event);
+    this.create_event('after-remove');
+  }
+
+  // LIFECYCLE EVENTS RELATED
+
+  create_event(stage, html = null) {
+    const event = new CustomEvent(`abyme:${stage}`, { detail: {controller: this, content: html} });
+    this.element.dispatchEvent(event);
+    // WIP
+    this.dispatch(event, stage);
+  }
+
+  // WIP : Trying to integrate event handling through controller inheritance
+  dispatch(event, stage) {
+    if (stage === 'before-add' && this.abymeBeforeAdd) this.abymeBeforeAdd(event);
+    if (stage === 'after-add' && this.abymeAfterAdd) this.abymeAfterAdd(event);
+    if (stage === 'before-remove' && this.abymeBeforeRemove) this.abymeBeforeAdd(event);
+    if (stage === 'after-remove' && this.abymeAfterRemove) this.abymeAfterRemove(event);
+  }
+
+  abymeBeforeAdd(event) {
+  }
+
+  abymeAfterAdd(event) {
+  }
+
+  abymeBeforeRemove(event) {
+  }
+
+  abymeAfterRemove(event) {
+  }
+
+  // UTILITIES
+
+  // build html
+  build_html() {
+    let html = this.templateTarget.innerHTML.replace(
+      /NEW_RECORD/g,
+      new Date().getTime()
+    );
+      
+    if (html.match(/<template[\s\S]+<\/template>/)) {
+      const template = html
+      .match(/<template[\s\S]+<\/template>/)[0]
+      .replace(/(\[\d{12,}\])(\[[^\[\]]+\]"){1}/g, `[NEW_RECORD]$2`);
+      
+      html = html.replace(/<template[\s\S]+<\/template>/g, template);
+    }
+
+    return html;
+  }
+    
+  // mark association for destroy
+  mark_for_destroy(event) {
+    let item = event.target.closest('.abyme--fields');
+    item.querySelector("input[name*='_destroy']").value = 1;
+    item.style.display = 'none';
+    item.classList.add('abyme--marked-for-destroy')
+  }
+
+  // check if associations limit is reached
+  limit_check() {
+    return (this.newFieldsTargets
+                .filter(item => !item.classList.contains('abyme--marked-for-destroy'))).length 
+                >= parseInt(this.element.dataset.limit)
+  }
+
+  // Add default blank associations at page load
+  async addDefaultAssociations() {
+    let i = 0
+    while (i < this.count) {
+      this.add_association()
+      i++
+      // Sleep function to ensure uniqueness of timestamp
+      await this.sleep(1);
+    }
+  }
+
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

data/javascript/index.js

@@ -0,0 +1,2 @@
+import AbymeController from './abyme_controller';
+export { AbymeController };

data/lib/abyme.rb

@@ -0,0 +1,8 @@
+require "abyme/version"
+require 'abyme/view_helpers'
+require 'abyme/engine'
+
+module Abyme
+  class Error < StandardError; end
+  autoload :Model, 'abyme/model'
+end

data/lib/abyme/abyme_builder.rb

@@ -0,0 +1,32 @@
+module Abyme
+  class AbymeBuilder < ActionView::Base
+    include ActionView
+
+    def initialize(association:, form:, lookup_context:, partial:, &block)
+      @association = association
+      @form = form
+      @lookup_context = lookup_context
+      @partial = partial
+      yield(self) if block_given?
+    end
+  
+    def records(options = {})
+      persisted_records_for(@association, @form, options) do |fields_for_association|
+        render_association_partial(fields_for_association, options)
+      end
+    end
+    
+    def new_records(options = {}, &block)
+      new_records_for(@association, @form, options) do |fields_for_association|
+        render_association_partial(fields_for_association, options)
+      end
+    end
+  
+    private
+
+    def render_association_partial(fields, options)
+      partial = @partial || options[:partial] || "abyme/#{@association.to_s.singularize}_fields"
+      ActionController::Base.render(partial: partial, locals: { f: fields })
+    end
+  end
+end

data/lib/abyme/engine.rb

@@ -0,0 +1,12 @@
+module Abyme
+  class Engine < ::Rails::Engine
+    isolate_namespace Abyme
+    
+    config.after_initialize do
+      ActiveSupport.on_load :action_view do
+        # ActionView::Base.send :include, Abyme::ViewHelpers
+        include Abyme::ViewHelpers
+      end
+    end
+  end
+end

data/lib/abyme/model.rb

@@ -0,0 +1,12 @@
+module Abyme
+  module Model
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def abyme_for(association, options = {})
+        default_options = {reject_if: :all_blank, allow_destroy: true}
+        accepts_nested_attributes_for association, default_options.merge(options)
+      end
+    end
+  end
+end

data/lib/abyme/version.rb

@@ -0,0 +1,9 @@
+module Abyme
+  module VERSION
+    MAJOR = 0
+    MINOR = 2
+    PATCH = 3
+
+    STRING = [MAJOR, MINOR, PATCH].join(".")
+  end
+end

data/lib/abyme/view_helpers.rb

@@ -0,0 +1,117 @@
+require_relative "abyme_builder"
+
+module Abyme
+  module ViewHelpers
+
+    def abymize(association, form, options = {}, &block)
+      content_tag(:div, data: { controller: 'abyme', limit: options[:limit], min_count: options[:min_count] }, id: "abyme--#{association}") do
+        if block_given?
+          yield(Abyme::AbymeBuilder.new(
+            association: association, form: form, lookup_context: self.lookup_context, partial: options[:partial]
+            )
+          )
+        else
+          model = association.to_s.singularize.classify.constantize
+          concat(persisted_records_for(association, form, options))
+          concat(new_records_for(association, form, options)) 
+          concat(add_association(content: options[:button_text] || "Add #{model}"))
+        end
+      end
+    end
+
+    def new_records_for(association, form, options = {}, &block)
+      options[:wrapper_html] ||= {}
+
+      wrapper_default = { 
+        data: { 
+          target: 'abyme.associations', 
+          association: association, 
+          abyme_position: options[:position] || :end 
+        } 
+      }
+
+      fields_default = { data: { target: 'abyme.fields abyme.newFields' } }
+
+      content_tag(:div, build_attributes(wrapper_default, options[:wrapper_html])) do
+        content_tag(:template, class: "abyme--#{association.to_s.singularize}_template", data: { target: 'abyme.template' }) do
+          form.fields_for association, association.to_s.classify.constantize.new, child_index: 'NEW_RECORD' do |f|
+            content_tag(:div, build_attributes(fields_default, basic_fields_markup(options[:fields_html], association))) do
+              # Here, if a block is passed, we're passing the association fields to it, rather than the form itself
+              block_given? ? yield(f) : render(options[:partial] || "abyme/#{association.to_s.singularize}_fields", f: f)
+            end
+          end
+        end
+      end
+    end
+  
+    def persisted_records_for(association, form, options = {})
+      records = options[:collection] || form.object.send(association)
+      options[:wrapper_html] ||= {}
+      fields_default = { data: { target: 'abyme.fields' } }
+      
+      if options[:order].present?
+        records = records.order(options[:order])
+        # Get invalid records
+        invalids = form.object.send(association).reject(&:persisted?)
+        records = records.to_a.concat(invalids) if invalids.any?
+      end 
+      
+      content_tag(:div, options[:wrapper_html]) do
+        form.fields_for(association, records) do |f|
+          content_tag(:div, build_attributes(fields_default, basic_fields_markup(options[:fields_html], association))) do
+            block_given? ? yield(f) : render(options[:partial] || "abyme/#{association.to_s.singularize}_fields", f: f)
+          end
+        end
+      end
+    end
+  
+    def add_association(options = {}, &block)
+      action = 'click->abyme#add_association'
+      create_button(action, options, &block)
+    end
+  
+    def remove_association(options = {}, &block)
+      action = 'click->abyme#remove_association'
+      create_button(action, options, &block)
+    end
+
+    private
+  
+    def create_button(action, options, &block)
+      options[:html] ||= {}
+      options[:tag] ||= :button
+      options[:content] ||= 'Add Association'
+  
+      if block_given?
+        content_tag(options[:tag], { data: { action: action } }.merge(options[:html])) do
+          capture(&block)
+        end
+      else
+        content_tag(options[:tag], options[:content], { data: { action: action } }.merge(options[:html]))
+      end
+    end
+
+    def basic_fields_markup(html, association = nil)
+      if html && html[:class]
+        html[:class] = "abyme--fields #{association.to_s.singularize}-fields #{html[:class]}" 
+      else
+        html ||= {}
+        html[:class] = "abyme--fields #{association.to_s.singularize}-fields"
+      end
+      html
+    end
+
+    def build_attributes(default, attr)
+      # ADD NEW DATA ATTRIBUTES VALUES TO THE DEFAULT ONES (ONLY VALUES)
+      if attr[:data]
+        default[:data].each do |key, value|
+          default[:data][key] = "#{value} #{attr[:data][key]}".strip
+        end
+      # ADD NEW DATA ATTRIBUTES (KEYS & VALUES)
+        default[:data] = default[:data].merge(attr[:data].reject { |key, _| default[:data][key] })
+      end
+      # MERGE THE DATA ATTRIBUTES TO THE HASH OF HTML ATTRIBUTES
+      default.merge(attr.reject { |key, _| key == :data })
+    end
+  end
+end

data/lib/generators/abyme/install_generator.rb

@@ -0,0 +1,25 @@
+# require 'rails/generators'
+# require 'json'
+
+# module Abyme
+#   module Generators
+#     class InstallGenerator < Rails::Generators::Base
+#     	source_root File.expand_path("templates", __dir__)
+
+#       def setup
+#       	# Creating stimulus abyme_controller.js file
+#       	# ==========================================
+#         template "abyme_controller.js", "app/javascript/controllers/abyme_controller.js"
+#         add_stimulus
+#       end
+
+#       def add_stimulus
+#       	# Checking if stimulus is present in package.json => yarn add if it's not
+#       	# =======================================================================
+#       	package = JSON.parse(File.open('package.json').read)
+#       	exec('yarn add stimulus') if !package['dependencies'].keys.include?('stimulus')
+#       end
+
+#     end
+#   end
+# end

data/lib/generators/abyme/templates/abyme_controller.js

@@ -0,0 +1,17 @@
+import { Controller } from 'stimulus';
+
+export default class extends Controller {
+	connect() {
+		console.log('Abyme Controller Connected');
+	}
+
+	add_association(event) {
+		event.preventDefault();
+		console.log('Add Association');
+	}
+
+	remove_association(event) {
+		event.preventDefault();
+		console.log('Remove Association');
+	}
+}

data/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "abyme",
+  "version": "0.1.2",
+  "description": "JS companion to abyme gem",
+  "main": "javascript/index.js",
+  "files": [
+    "package.json",
+    "javascript/**/*"
+  ],
+  "directories": {
+    "lib": "javascript"
+  },
+  "repository": {
+    "url": "https://github.com/bear-in-mind/abyme",
+    "type": "git"
+  },
+  "author": "Romain Sanson <romain.sanson@hey.com> & Louis Sommer <louis.sommer@hey.com>",
+  "license": "MIT",
+  "private": false,
+  "homepage": "https://github.com/bear-in-mind/abyme",
+  "bugs": "https://github.com/bear-in-mind/abyme/issues",
+  "dependencies": {
+    "stimulus": "^1.1.1"
+  }
+}

data/yarn.lock

@@ -0,0 +1,35 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+"@stimulus/core@^1.1.1":
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/@stimulus/core/-/core-1.1.1.tgz#42b0cfe5b73ca492f41de64b77a03980bae92c82"
+  integrity sha512-PVJv7IpuQx0MVPCBblXc6O2zbCmU8dlxXNH4bC9KK6LsvGaE+PCXXrXQfXUwAsse1/CmRu/iQG7Ov58himjiGg==
+  dependencies:
+    "@stimulus/mutation-observers" "^1.1.1"
+
+"@stimulus/multimap@^1.1.1":
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/@stimulus/multimap/-/multimap-1.1.1.tgz#b95e3fd607345ab36e5d5b55486ee1a12d56b331"
+  integrity sha512-26R1fI3a8uUj0WlMmta4qcfIQGlagegdP4PTz6lz852q/dXlG6r+uPS/bx+H8GtfyS+OOXVr3SkZ0Zg0iRqRfQ==
+
+"@stimulus/mutation-observers@^1.1.1":
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/@stimulus/mutation-observers/-/mutation-observers-1.1.1.tgz#0f6c6f081308427fed2a26360dda0c173b79cfc0"
+  integrity sha512-/zCnnw1KJlWO2mrx0yxYaRFZWMGnDMdOgSnI4hxDLxdWVuL2HMROU8FpHWVBLjKY3T9A+lGkcrmPGDHF3pfS9w==
+  dependencies:
+    "@stimulus/multimap" "^1.1.1"
+
+"@stimulus/webpack-helpers@^1.1.1":
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/@stimulus/webpack-helpers/-/webpack-helpers-1.1.1.tgz#eff60cd4e58b921d1a2764dc5215f5141510f2c2"
+  integrity sha512-XOkqSw53N9072FLHvpLM25PIwy+ndkSSbnTtjKuyzsv8K5yfkFB2rv68jU1pzqYa9FZLcvZWP4yazC0V38dx9A==
+
+stimulus@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/stimulus/-/stimulus-1.1.1.tgz#53c2fded6849e7b85eed3ed8dd76e33abd74bec5"
+  integrity sha512-R0mBqKp48YnRDZOxZ8hiOH4Ilph3Yj78CIFTBkCwyHs4iGCpe7xlEdQ7cjIxb+7qVCSxFKgxO+mAQbsNgt/5XQ==
+  dependencies:
+    "@stimulus/core" "^1.1.1"
+    "@stimulus/webpack-helpers" "^1.1.1"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: abyme
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Romain Sanson
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-10-12 00:00:00.000000000 Z
+date: 2020-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -40,26 +40,83 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails-dummy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0'
 description:
 email:
 - louis.sommer@hey.com
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- ".DS_Store"
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- abyme.gemspec
+- bin/console
+- bin/rails
+- bin/setup
+- javascript/abyme_controller.js
+- javascript/index.js
+- lib/.DS_Store
+- lib/abyme.rb
+- lib/abyme/abyme_builder.rb
+- lib/abyme/engine.rb
+- lib/abyme/model.rb
+- lib/abyme/version.rb
+- lib/abyme/view_helpers.rb
+- lib/generators/.DS_Store
+- lib/generators/abyme/install_generator.rb
+- lib/generators/abyme/templates/abyme_controller.js
+- node_modules/.yarn-integrity
+- package.json
+- yarn-error.log
+- yarn.lock
 homepage: https://github.com/bear-in-mind/abyme
 licenses:
 - MIT