optimism 0.2.10

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "optimism"
+
+# 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 "pry"
+
+Pry.start

data/bin/loc

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+cloc --exclude-dir=node_modules,test --include-ext=rb,js .

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/bin/standardize

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+bundle exec standardrb --fix
+cd ./javascript && yarn run prettier-standard --lint javascript/*.js test/*.js

data/lib/optimism.rb

@@ -0,0 +1,108 @@
+require "cable_ready"
+require "optimism/version"
+require "optimism/railtie" if defined?(Rails)
+
+module Optimism
+  include CableReady::Broadcaster
+  class << self
+    mattr_accessor :channel, :form_class, :error_class, :disable_submit, :suffix, :emit_events, :add_css, :inject_inline, :container_selector, :error_selector, :form_selector, :submit_selector
+    self.channel = "OptimismChannel"
+    self.form_class = "invalid"
+    self.error_class = "error"
+    self.disable_submit = false
+    self.suffix = ""
+    self.emit_events = false
+    self.add_css = true
+    self.inject_inline = true
+    self.container_selector = "#RESOURCE_ATTRIBUTE_container"
+    self.error_selector = "#RESOURCE_ATTRIBUTE_error"
+    self.form_selector = "#RESOURCE_form"
+    self.submit_selector = "#RESOURCE_submit"
+  end
+
+  def self.configure(&block)
+    yield self
+  end
+
+  def broadcast_errors(model, attributes)
+    return unless model&.errors&.messages
+    resource = model.class.to_s.downcase
+    form_selector, submit_selector = Optimism.form_selector.sub("RESOURCE", resource), Optimism.submit_selector.sub("RESOURCE", resource)
+    attributes = case attributes
+    when ActionController::Parameters, Hash, ActiveSupport::HashWithIndifferentAccess
+      attributes.to_h.keys
+    when String, Symbol
+      [attributes.to_s]
+    when Array
+      attributes.flatten.map &:to_s
+    else
+      raise Exception.new "attributes must be a Hash (Parameters, Indifferent or standard), Array, Symbol or String"
+    end
+    process_resource(model, attributes, [resource])
+    if model.errors.any?
+      cable_ready[Optimism.channel].dispatch_event(name: "optimism:form:invalid", detail: {resource: resource}) if Optimism.emit_events
+      cable_ready[Optimism.channel].add_css_class(selector: form_selector, name: Optimism.form_class) if Optimism.form_class.present?
+      cable_ready[Optimism.channel].set_attribute(selector: submit_selector, name: "disabled") if Optimism.disable_submit
+    else
+      cable_ready[Optimism.channel].dispatch_event(name: "optimism:form:valid", detail: {resource: resource}) if Optimism.emit_events
+      cable_ready[Optimism.channel].remove_css_class(selector: form_selector, name: Optimism.form_class) if Optimism.form_class.present?
+      cable_ready[Optimism.channel].remove_attribute(selector: submit_selector, name: "disabled") if Optimism.disable_submit
+    end
+    cable_ready.broadcast
+    head :ok
+  end
+
+  def process_resource(model, attributes, ancestry)
+    attributes.each do |attribute|
+      if attribute.ends_with?("_attributes")
+        resource = attribute[0..-12]
+        nested_models = model.send(resource.to_sym)
+        nested_models.each_with_index do |nested, index|
+          process_resource(nested, attributes[attribute][index.to_s], ancestry + [resource, index]) if attributes[attribute].key?(index.to_s)
+        end
+      else
+        process_attribute(model, attribute, ancestry.dup)
+      end
+    end
+  end
+
+  def process_attribute(model, attribute, ancestry)
+    resource = ancestry.shift
+    resource += "_#{ancestry.shift}_attributes_#{ancestry.shift}" until ancestry.empty?
+    container_selector, error_selector = Optimism.container_selector.sub("RESOURCE", resource).sub("ATTRIBUTE", attribute), Optimism.error_selector.sub("RESOURCE", resource).sub("ATTRIBUTE", attribute)
+    if model.errors.messages.map(&:first).include?(attribute.to_sym)
+      message = "#{attribute.humanize} #{model.errors.messages[attribute.to_sym].first}#{Optimism.suffix}"
+      cable_ready[Optimism.channel].dispatch_event(name: "optimism:attribute:invalid", detail: {resource: resource, attribute: attribute, text: message}) if Optimism.emit_events
+      cable_ready[Optimism.channel].add_css_class(selector: container_selector, name: Optimism.error_class) if Optimism.add_css
+      cable_ready[Optimism.channel].text_content(selector: error_selector, text: message) if Optimism.inject_inline
+    else
+      cable_ready[Optimism.channel].dispatch_event(name: "optimism:attribute:valid", detail: {resource: resource, attribute: attribute}) if Optimism.emit_events
+      cable_ready[Optimism.channel].remove_css_class(selector: container_selector, name: Optimism.error_class) if Optimism.add_css
+      cable_ready[Optimism.channel].text_content(selector: error_selector, text: "") if Optimism.inject_inline
+    end
+  end
+end
+
+module ActionView::Helpers
+  class FormBuilder
+    def container_for(attribute, **options, &block)
+      @template.tag.div @template.capture(&block), options.merge!(id: container_id_for(attribute)) if block_given?
+    end
+
+    def container_id_for(attribute)
+      Optimism.container_selector.sub("RESOURCE", object_name.delete("]").tr("[", "_")).sub("ATTRIBUTE", attribute.to_s)[1..-1]
+    end
+
+    def error_for(attribute, **options)
+      @template.tag.span options.merge! id: error_id_for(attribute)
+    end
+
+    def error_id_for(attribute)
+      Optimism.error_selector.sub("RESOURCE", object_name.delete("]").tr("[", "_")).sub("ATTRIBUTE", attribute.to_s)[1..-1]
+    end
+  end
+end
+
+class ActionController::Base
+  include Optimism
+end

data/lib/optimism/railtie.rb

@@ -0,0 +1,11 @@
+require "pathname"
+
+module Optimism
+  class Railtie < Rails::Railtie
+    railtie_name :optimism
+
+    rake_tasks do
+      load Pathname.new(__dir__).join("rake.rb")
+    end
+  end
+end

data/lib/optimism/rake.rb

@@ -0,0 +1,18 @@
+require "fileutils"
+
+desc "Inject some optimism into this application"
+task :"optimism:install" do
+  CHANNELS = [
+    {app_path: "app/javascript/channels/optimism_channel.js", template_path: "../templates/optimism_channel.js" },
+    {app_path: "app/channels/optimism_channel.rb", template_path: "../templates/optimism_channel.rb" },
+  ]
+
+  CHANNELS.each do |channel|
+    if File.exist?("./#{channel[:app_path]}")
+      $stderr.puts "=> [ skipping ] #{channel[:app_path]} already exists"
+    else
+      FileUtils.cp(File.expand_path(channel[:template_path], __dir__), "./#{channel[:app_path]}")
+      $stderr.puts "=> #{channel[:app_path]} created"
+    end
+  end
+end

data/lib/optimism/version.rb

@@ -0,0 +1,3 @@
+module Optimism
+  VERSION = "0.2.10"
+end

data/lib/templates/optimism_channel.js

@@ -0,0 +1,11 @@
+import consumer from './consumer'
+import CableReady from 'cable_ready'
+
+consumer.subscriptions.create('OptimismChannel', {
+  received (data) {
+    if (data.cableReady)
+      CableReady.perform(data.operations, {
+        emitMissingElementWarnings: false
+      })
+  }
+})

data/lib/templates/optimism_channel.rb

@@ -0,0 +1,5 @@
+class OptimismChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from "OptimismChannel"
+  end
+end

data/optimism.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "optimism/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "optimism"
+  spec.version = Optimism::VERSION
+  spec.authors = ["leastbad"]
+  spec.email = ["hello@leastbad.com"]
+
+  spec.summary = "Drop-in Rails form validations"
+  spec.description = "Realtime remote form input validations delivered via websockets"
+  spec.homepage = "https://github.com/leastbad/optimism"
+  spec.license = "MIT"
+
+  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 "pry"
+  spec.add_development_dependency "pry-nav"
+  spec.add_development_dependency "standardrb"
+  spec.add_dependency "rack"
+  spec.add_dependency "rails", ">= 5.2"
+  spec.add_dependency "cable_ready", "~> 4.0.9"
+end

data/quick-start.md

@@ -0,0 +1,123 @@
+# Quick Start
+
+Let's start with the simplest scenario possible: you have a form with multiple input elements, and when the user clicks on the Submit button you want to display any validation error messages beside the elements that have issues. When the user resolves these issues and clicks the Submit button, the form is processed normal and the page navigates to whatever comes next.
+
+## Model
+
+Validations are covered in-depth by the [official documentation](https://guides.rubyonrails.org/active_record_validations.html#validation-helpers). Optimism doesn't require anything special.
+
+{% hint style="info" %}
+Optimism is designed for ActiveRecord models that have validations defined, although it should work with any Ruby class that implements [Active Model](https://guides.rubyonrails.org/active_model_basics.html) and has an `errors` accessor.
+{% endhint %}
+
+## View
+
+Here's sample form partial for a Post model. It has two attributes - **name** and **body** and was generated with a Rails scaffold command.
+
+{% code title="app/views/posts/\_form.html.erb BEFORE Optimism" %}
+```rust
+<%= form_with(model: post, local: true) do |form| %>
+  <% if post.errors.any? %>
+    <div id="error_explanation">
+      <h2><%= pluralize(post.errors.count, "error") %> prohibited this post from being saved:</h2>
+
+      <ul>
+        <% post.errors.full_messages.each do |message| %>
+          <li><%= message %></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="field">
+    <%= form.label :name %>
+    <%= form.text_field :name %>
+  </div>
+
+  <div class="field">
+    <%= form.label :body %>
+    <%= form.text_area :body %>
+  </div>
+
+  <div class="actions">
+    <%= form.submit %>
+  </div>
+<% end %>
+```
+{% endcode %}
+
+And here is that same form partial, configured to work with Optimism:
+
+{% code title="app/views/posts/\_form.html.erb AFTER Optimism" %}
+```rust
+<%= form_with(model: post) do |form| %>
+  <div class="field">
+    <%= form.label :name %>
+    <%= form.text_field :name %>
+    <%= form.error_for :name %>
+  </div>
+
+  <div class="field">
+    <%= form.label :body %>
+    <%= form.text_area :body %>
+    <%= form.error_for :body %>
+  </div>
+
+  <div class="actions">
+    <%= form.submit %>
+  </div>
+<% end %>
+```
+{% endcode %}
+
+Eagle-eyed readers will see that setting up a bare-bones Optimism integration requires removing two things and adding one thing to each attribute:
+
+1. Remove `local: true` from the `form_with` on the first line
+2. Remove the error messages block from lines 2-12 entirely
+3. Add an `error_for` helper for each attribute
+
+The `error_for` helper creates an empty `span` tag with an id such as _posts\_body\_error_, and this is where the error messages for the body attribute will appear.
+
+{% hint style="success" %}
+Even though `form_with` is remote-by-default, many developers were confused and frustrated by the lack of opinionated validation handling out of the box for remote forms. Since scaffolds are for new users to get comfortable, remote forms are disabled. This is the primary reason that Optimism was created: we want our tasty remote forms without any heartburn.
+{% endhint %}
+
+## Controller
+
+The last step is to slightly modify the **create** and **update** actions in our PostsController. The other actions have been removed for brevity:
+
+{% code title="app/controllers/posts\_controller.rb" %}
+```rust
+  def create
+    @post = Post.new(post_params)
+    respond_to do |format|
+      if @post.save
+        format.html { redirect_to @post, notice: 'Post was successfully created.' }
+        format.json { render :show, status: :created, location: @post }
+      else
+        format.html { broadcast_errors @post, post_params }
+        format.json { render json: @post.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  def update
+    respond_to do |format|
+      if @post.update(post_params)
+        format.html { redirect_to @post, notice: 'Post was successfully updated.' }
+        format.json { render :show, status: :ok, location: @post }
+      else
+        format.html { broadcast_errors @post, post_params }
+        format.json { render json: @post.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+```
+{% endcode %}
+
+The only meaningful change required \(as seen on lines 8 and 20 in this example\) is to replace `render :new` and `render :edit` with a call to `broadcast_errors` which has two mandatory parameters: the model instance and the list of attributes to validate. Usually this is the whitelisted params hash, but you can pass a subset as small as one attribute to be validated.
+
+That's all there is to it. You now have live - if _unstyled_ - form validations being delivered over websockets.
+
+![](.gitbook/assets/high_five.svg)
+

data/reference.md

@@ -0,0 +1,165 @@
+# Reference
+
+## ActionController Mixins
+
+### **broadcast\_errors**\(model, attributes\)
+
+**model**: an instance of an Active Record model, or a class inheriting from Active Model  
+**attributes**: one or many attributes in the form of a ActionController::Parameters, Hash, HashWithIndifferentAccess, Symbol, String or Array \(of Strings or Symbols\)
+
+Call this method in a resource controller's `create` or `update` actions when a model validation fails. A list of instructions for the client browser will be prepared and dispatched via a persistent websocket connection.
+
+The two most common use cases are form-based \(Parameters\) or in-line editing of a single attribute \(Symbol or String\).
+
+#### Example
+
+```ruby
+if @post.update(post_params)
+  # Eat. Pray. Love.
+else
+  broadcast_errors @post, post_params
+end
+```
+
+
+
+## Form Builder Helpers
+
+### container\_for\(attribute, \*\*options, &block\)
+
+**attribute**: Symbol identifying the the model attribute to use  
+**options**: an implicit Hash allowing you to pass in class names, data attributes and other HTML attributes  
+**block**: all ERB content passed to this helper inside the do..end will be rendered as content
+
+Call this helper to create a `div` that will wrap your input element along with any labels and error messages. It will have an id attribute that will allow Optimism to route any validation errors to the correct place. When a validation failure occurs, this `div` will have an _error_ class added to it, allowing a style cascade to change the visual appearance of the input element and the error message.
+
+#### Example
+
+```rust
+  <%= form.container_for :name, class: "field" do %>
+    <%= form.text_field :name %>
+  <% end %>
+```
+
+
+
+### container\_id\_for\(attribute\)
+
+**attribute**: Symbol identifying the the model attribute to use
+
+Returns the id required for a container to wrap your input elements and receive CSS updates. Use it if you are forced to create your own container markup from scratch; generally it is easiest to make use of **container\_for** if possible.
+
+#### Example
+
+```rust
+<blockquote id="<%= form.container_id_for :name %>"></blockquote>
+```
+
+
+
+### error\_for\(attribute, \*\*options\)
+
+**attribute**: Symbol identifying the the model attribute to use  
+**options**: an implicit Hash allowing you to pass in class names, data attributes and other HTML attributes
+
+Call this helper to create a `span` that you place adjacent to your your input elements. It will have an id attribute that will allow Optimism to route any validation errors to the correct place. When a validation failure occurs, this `span` will have the error message injected into it. It is typically hidden unless there is a message present.
+
+#### Example
+
+```rust
+<%= form.error_for :name, class: "d-none text-danger small form-group" %>
+```
+
+
+
+### error\_id\_for\(attribute\)
+
+**attribute**: Symbol identifying the the model attribute to use
+
+Returns the id required for a container to receive validation error text. Use it if you are forced to create your own error message markup from scratch; generally it is easiest to make use of **error\_for** if possible.
+
+```rust
+<blockquote id="<%= form.error_id_for :name %>"></blockquote>
+```
+
+
+
+![](.gitbook/assets/master_plan.svg)
+
+## Initializer
+
+Optimism is configurable via an optional initializer file. As with all initializers, changes only take effect after your Rails server has been restarted. Here is a sample initializer file that contains all of the default values for the configuration of the library. All changes apply globally to all instances of Optimism.
+
+{% code title="config/initializers/optimism.rb" %}
+```ruby
+Optimism.configure do |config|
+  config.channel = "OptimismChannel"
+  config.form_class = "invalid"
+  config.error_class = "error"
+  config.disable_submit = false
+  config.suffix = ""
+  config.emit_events = false
+  config.add_css = true
+  config.inject_inline = true
+  config.container_selector = "#RESOURCE_ATTRIBUTE_container"
+  config.error_selector = "#RESOURCE_ATTRIBUTE_error"
+  config.form_selector = "#RESOURCE_form"
+  config.submit_selector = "#RESOURCE_submit"
+end
+```
+{% endcode %}
+
+**channel**: The ActionCable channel created by the `rake optimism:install` setup task. In most cases, you don't need to change this value. In fact, the only good reason to change this value is if you already have an OptimismChannel. If this describes you, congratulations on your optimism.
+
+**form\_class**: The CSS class that will be applied to the form if the id has been properly set eg. `posts_form` \(following the simple pattern **resources\_form**\). If form\_class is set to false or nil, no CSS class will be applied.
+
+**error\_class**: The CSS class the will be applied to a container when a validation fails. Use this class to cascade to the input elements and change their appearance.
+
+**disable\_submit**: If set to true and your Submit button is named properly eg. `posts_submit` \(following the simple pattern **resources\_submit**\), your Submit button will be disabled if there are validation errors. It will also be re-enabled if the validation errors are corrected. Only use this if you are working with in-line validations or else your users will lose the ability to Submit your form more than once.
+
+**suffix**: Likely the most important setting of all, this string will be appended to all validation error messages. While most validation errors on the web today do not have a trailing period, this is a matter of developer preference and when you're working on Rails, we care about your trails.
+
+**emit\_events**: Optimism is so flexible that you can opt to have it fire DOM events in addition to \(or instead of\) text content and CSS updates. Scroll down for more information on the events that will be sent.
+
+**add\_css**: Flag to control whether containers will receive CSS updates when a form is invalid.
+
+**inject\_inline**: Flag to control whether validation error messages will be displayed inside _error\_for_ spans.
+
+**container\_selector**: This is the pattern from which container id CSS selectors will be constructed. You probably shouldn't change this.
+
+**error\_selector**: This is the pattern from which error\_for span id CSS selectors will be constructed. You probably shouldn't change this.
+
+**form\_selector**: This is the pattern from which form id CSS selectors will be constructed. You probably shouldn't change this.
+
+**submit\_selector**: This is the pattern from which Submit button id CSS selectors will be constructed. You probably shouldn't change this.
+
+
+
+## Events
+
+If you set the `emit_events` property to true in your initializer, Optimism will emit DOM events in response to validation errors. This can happen in addition to or instead of CSS and text updates. This is a great alternative for complicated integrations where you have legacy components which need to be notified of error conditions on the backend.
+
+In practical terms, DOM events give you tooling options and creative flexibility that are difficult to achieve with textual error messages and CSS error classes. It's simply a fact that no library can anticipate every design pattern or UI innovation. Today you might connect DOM events to a [toast notification library](https://www.jqueryscript.net/blog/Best-Toast-Notification-jQuery-Plugins.html#vanilla), but tomorrow there could be a mass proliferation of embedded ocular computers with sub-vocalization control interfaces, and we aren't going to tell you how those devices should punish users for bad input.
+
+### Form-level events
+
+Event: **optimism:form:invalid**  
+Detail: resource
+
+Event: **optimism:form:valid**  
+Detail: resource
+
+One of these events will fire, depending on whether the model is valid. Resource is the pluralized class name of the Active Record model, eg. `posts`
+
+### Attribute-level events
+
+Event: **optimism:attribute:invalid**  
+Detail: resource, attribute, text
+
+Event: **optimism:attribute:valid**  
+Detail: resource, attribute
+
+One of these events will fire **for each attribute**, depending on whether that attribute is valid. Resource is the pluralized class name of the Active Record model, eg. `posts`. Attribute is hopefully self-explanatory. Text is the text content of the validation error message.
+
+![](.gitbook/assets/alien_science.svg)
+