stimulus_reflex 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6798571d8f8229083855114f5f499414f308a47e03c438f1b74b5eb534acd78f
-  data.tar.gz: 62e2d714b2ae14c16bf4435665d339717d9fa99330d3eb604fa6720c15f64f80
+  metadata.gz: 253dc2246ab12a13e75ea23f907375b011d3ef16fae1836638a81c00017f5eb1
+  data.tar.gz: f1a2a7e3555a9509f9a3a1fb1bdccb0ecd36fb806511302e7cc5f1fe18d7d2c3
 SHA512:
-  metadata.gz: 2d22087e7519727c787770fb971aa510d2480a5b45e00efa78eb708adcc69d89cf085b3fad6544c9a46bb183240ea452ded9ce665495ca7f5d47bcc021c8a7e0
-  data.tar.gz: 3b0aaf7d1c98ba7281f24f2d96fb1d043e297847837c2ad38028bac114c7ed7fe80c929e0c58491b646533f8d4958921e8e1483d5bc320c4d04d3034ec2e53aa
+  metadata.gz: 93a93f0ecf009492eeb422249814d1b9bfdd4de8592cac5e4d6feb029a670ea3dd6b15b156b11da564e4b4ec6453e97bdddccecdb8bd0df5c29c8d3b45efa264
+  data.tar.gz: be64d27ccfa1a7c8cec4781c199628af9e4ad345bbf0744fbc64f4bb9b6bb9de0de8fcdb413ad2fb58e666dcd7362198b45355d64e8f25dd87f882fd9f942fef

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stimulus_reflex (1.0.2)
+    stimulus_reflex (1.1.0)
       cable_ready (>= 4.0.3)
       nokogiri
       rack
@@ -90,11 +90,11 @@ GEM
     mini_mime (1.0.2)
     mini_portile2 (2.4.0)
     minitest (5.11.3)
-    nio4r (2.4.0)
+    nio4r (2.5.1)
     nokogiri (1.10.4)
       mini_portile2 (~> 2.4.0)
     parallel (1.17.0)
-    parser (2.6.3.0)
+    parser (2.6.4.0)
       ast (~> 2.4.0)
     pry (0.12.2)
       coderay (~> 1.1.0)
@@ -149,7 +149,7 @@ GEM
       actionpack (>= 4.0)
       activesupport (>= 4.0)
       sprockets (>= 3.0.0)
-    standard (0.1.2)
+    standard (0.1.3)
       rubocop (~> 0.72.0)
       rubocop-performance (~> 1.4.0)
     standardrb (1.0.0)
@@ -162,7 +162,7 @@ GEM
     websocket-driver (0.7.1)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.4)
-    zeitwerk (2.1.9)
+    zeitwerk (2.1.10)
 
 PLATFORMS
   ruby

data/README.md

@@ -1,8 +1,10 @@
-[![Lines of Code](http://img.shields.io/badge/lines_of_code-159-brightgreen.svg?style=flat)](http://blog.codinghorror.com/the-best-code-is-no-code-at-all/)
+[![Lines of Code](http://img.shields.io/badge/lines_of_code-203-brightgreen.svg?style=flat)](http://blog.codinghorror.com/the-best-code-is-no-code-at-all/)
 [![Maintainability](https://api.codeclimate.com/v1/badges/2b24fdbd1ae37a24bedb/maintainability)](https://codeclimate.com/github/hopsoft/stimulus_reflex/maintainability)
 
 # StimulusReflex
 
+_reflex_ - an action that is performed as a response to a stimulus
+
 ### Build reactive [Single Page Applications (SPAs)](https://en.wikipedia.org/wiki/Single-page_application) with [Rails](https://rubyonrails.org) and [Stimulus](https://stimulusjs.org)
 
 This project supports building [reactive applications](https://en.wikipedia.org/wiki/Reactive_programming)
@@ -11,19 +13,51 @@ It's designed to work perfectly with [server rendered HTML](https://guides.rubyo
 [Russian doll caching](https://edgeguides.rubyonrails.org/caching_with_rails.html#russian-doll-caching),
 [Stimulus](https://stimulusjs.org), [Turbolinks](https://www.youtube.com/watch?v=SWEts0rlezA), etc...
 
-
 __No need for a complex front-end framework. No need to grow your team or duplicate your efforts.__
 
----
-
-> The lifecycle of a "modern" SPA app is so convoluted, it requires a team to build and support.
-> The wire size and computation demands of these heavy client sites frequently run slower than the server-rendered pages that they replaced.
-> With Stimulus Reflex, a Rails developer can build Single Page Applications without the need for client rendering or heavy JS frameworks.
-
----
-
 _Inspired by [Phoenix LiveView](https://youtu.be/Z2DU0qLfPIY?t=670)._ 🙌
 
+## Table of Contents
+
+<!-- toc -->
+
+- [Before you Begin](#before-you-begin)
+- [How it Works](#how-it-works)
+- [Setup](#setup)
+  * [JavaScript](#javascript)
+  * [Gemfile](#gemfile)
+- [Basic Usage](#basic-usage)
+  * [app/views/pages/example.html.erb](#appviewspagesexamplehtmlerb)
+  * [app/javascript/controllers/example.js](#appjavascriptcontrollersexamplejs)
+  * [app/reflexes/example_reflex.rb](#appreflexesexample_reflexrb)
+- [Advanced Usage](#advanced-usage)
+  * [Reflex Methods](#reflex-methods)
+    + [The `options` Keyword Argument](#the-options-keyword-argument)
+  * [ActionCable](#actioncable)
+    + [Performance](#performance)
+    + [ActionCable Rooms](#actioncable-rooms)
+  * [Render Delay](#render-delay)
+- [Demo Applications](#demo-applications)
+- [Contributing](#contributing)
+  * [Coding Standards](#coding-standards)
+  * [Releasing](#releasing)
+
+<!-- tocstop -->
+
+## Before you Begin
+
+StimulusReflex provides functionality similar to what can already be achieved with Rails by combining
+[UJS remote elements](https://guides.rubyonrails.org/working_with_javascript_in_rails.html#remote-elements)
+, [Stimulus](https://stimulusjs.org), and [Turbolinks](https://github.com/turbolinks/turbolinks).
+_Consider building with standard Rails tooling before introducing StimulusReflex._
+_Check out the [Stimulus TodoMVC](https://github.com/hopsoft/stimulus_todomvc) example if you are unsure how to accomplish this._
+
+StimulusReflex offers 3 primary benefits over the traditional Rails HTTP request/response cycle.
+
+1. __Communication happens on the ActionCable web socket__ _- saves time by avoiding the overhead of establishishing traditional HTTP connections_
+1. __The controller action is invoked directly__ _- skips framework overhead such as the middleware chain, etc..._
+1. __DOM diffing is used to update the page__ _- provides faster rendering and less jitter_
+
 ## How it Works
 
 1. Render a standard Rails view template
@@ -100,12 +134,64 @@ The following happens after the `StimulusReflex::Reflex` method call finishes.
 
 ## Advanced Usage
 
+### Reflex Methods
+
+#### The `options` Keyword Argument
+
+Reflex methods support an _optional_ `options` keyword argument.
+
+- This is the only supported keyword argument.
+- It must appear after ordinal arguments.
+
+```ruby
+class ExampleReflex < StimulusReflex::Reflex
+  def work(options: {})
+    # ...
+  end
+
+  def other_work(value, options: {})
+    # ...
+  end
+end
+```
+
+The `options` value contains all of the Stimulus controller's
+[DOM element attributes](https://developer.mozilla.org/en-US/docs/Web/API/Element/attributes) as well as other properties like `checked` and `value`.
+_Most of the values will be strings._
+Here's an example:
+
+```html
+<checkbox checked label="Example" data-controller="checkbox" data-value="123" />
+```
+
+The markup above produces the following behavior in a reflex method.
+
+```ruby
+class ExampleReflex < StimulusReflex::Reflex
+  def work(options: {})
+    options[:checked]            # => true
+    options[:label]              # => "Example"
+    options["data-controller"]   # => "checkbox"
+    options["data-value"]        # => "123"
+    options.dataset[:controller] # => "checkbox"
+    options.dataset[:value]      # => "123"
+  end
+end
+```
+
+- `options[:checked]` holds a boolean
+- `options[:selected]` holds a boolean
+- `options[:value]` holds the [DOM element's value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#value)
+- `select` elements assign `options[:value]` to their selected option's value
+- `select` elements with _multiselect_ enabled assign `options[:values]` to their selected options values
+- All other values stored in `options` are extracted from the DOM element's attributes
+
 ### ActionCable
 
 StimulusReflex will use the ActionCable defaults of `window.App` and `App.cable` if they exist.
 If these defaults do not exist, StimulusReflex will establish a new socket connection.
 
-### Performance
+#### Performance
 
 ActionCable emits verbose log messages. Disabling ActionCable logs may improve performance.
 
@@ -115,7 +201,7 @@ ActionCable emits verbose log messages. Disabling ActionCable logs may improve p
 ActionCable.server.config.logger = Logger.new(nil)
 ```
 
-### ActionCable Rooms
+#### ActionCable Rooms
 
 You may find the need to restrict notifications to a specific room.
 This can be accomplished by setting the `data-room` attribute on the StimulusController element.
@@ -151,6 +237,22 @@ Building apps with StimulusReflex should evoke your memories of the original [Ra
 
 ## Contributing
 
+### Coding Standards
+
 This project uses [Standard](https://github.com/testdouble/standard)
 and [Prettier](https://github.com/prettier/prettier) to minimize bike shedding related to code formatting.
 Please run `./bin/standardize` prior submitting pull requests.
+
+### Releasing
+
+1. Bump version number at `lib/stimulus_reflex/version.rb`
+1. Push changes to GitHub
+1. Run `rake release`
+1. Run `yarn publish`
+1. Assign same version number to the JavaScript package
+1. Push changes to GitHub
+1. Push tags to GitHub
+
+    ```
+    git push --tags
+    ```

data/Rakefile

@@ -1,2 +1,4 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 task default: :spec

data/bin/standardize

@@ -1,4 +1,4 @@
 #!/bin/bash
 
 bundle exec standardrb --fix
-prettier --write javascript/stimulus_reflex.js
+cd ./javascript && yarn run prettier --write stimulus_reflex.js

data/lib/stimulus_reflex/channel.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class StimulusReflex::Channel < ActionCable::Channel::Base
   include CableReady::Broadcaster
 
@@ -20,28 +22,44 @@ class StimulusReflex::Channel < ActionCable::Channel::Base
     reflex_name, method_name = target.split("#")
     reflex_name = reflex_name.classify
     arguments = data["args"] || []
+    options = StimulusReflex::DomElement.new(data["attrs"])
 
     begin
       reflex = reflex_name.constantize.new(self, url: url)
-      delegate_call_to_reflex reflex, method_name, arguments
+      delegate_call_to_reflex reflex, method_name, arguments, options
     rescue => invoke_error
-      logger.error "StimulusReflex::Channel Failed to invoke #{target}! #{url} #{invoke_error}"
+      logger.error "\e[31mStimulusReflex::Channel Failed to invoke #{target}! #{url} #{invoke_error}\e[0m"
     end
 
     begin
       render_page_and_broadcast_morph url, reflex
     rescue => render_error
-      logger.error "StimulusReflex::Channel Failed to rerender #{url} #{render_error}"
+      logger.error "\e[31mStimulusReflex::Channel Failed to rerender #{url} #{render_error}\e[0m"
     end
   end
 
   private
 
-  def delegate_call_to_reflex(reflex, method_name, arguments = [])
-    if reflex.method(method_name).arity != 0
-      reflex.send method_name, *arguments
+  def delegate_call_to_reflex(reflex, method_name, arguments = [], options = {})
+    method = reflex.method(method_name)
+    required_params = method.parameters.select { |(kind, _)| kind == :req }
+    optional_params = method.parameters.select { |(kind, _)| kind == :opt }
+    accepts_options_kwarg = method.parameters.select { |(kind, name)| name == :options && kind.to_s.start_with?("key") }.size > 0
+
+    if arguments.size == 0 && required_params.size == 0
+      if accepts_options_kwarg
+        reflex.public_send method_name, {options: options}
+      else
+        reflex.public_send method_name
+      end
+    elsif arguments.size >= required_params.size && arguments.size <= required_params.size + optional_params.size
+      if accepts_options_kwarg
+        reflex.public_send method_name, *arguments, {options: options}
+      else
+        reflex.public_send method_name, *arguments
+      end
     else
-      reflex.send method_name
+      raise ArgumentError.new("wrong number of arguments (given #{arguments.inspect}, expected #{required_params.inspect}, optional #{optional_params.inspect})")
     end
   end
 

data/lib/stimulus_reflex/dom_element.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class StimulusReflex::DomElement
+  attr_reader :attributes
+
+  delegate :[], to: :"@attributes"
+
+  def initialize(attrs = {})
+    @attributes = HashWithIndifferentAccess.new(attrs || {}).freeze
+  end
+
+  def dataset
+    @dataset ||= attributes.each_with_object(HashWithIndifferentAccess.new) { |(key, value), memo|
+      next unless key.start_with?("data-")
+      memo[key.delete_prefix("data-")] = value
+    }.freeze
+  end
+end

data/lib/stimulus_reflex/reflex.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class StimulusReflex::Reflex
   attr_reader :channel, :url
 

data/lib/stimulus_reflex/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StimulusReflex
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

data/lib/stimulus_reflex.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "uri"
 require "rack"
 require "rails/engine"
@@ -8,6 +10,7 @@ require "nokogiri"
 require "cable_ready"
 require "stimulus_reflex/version"
 require "stimulus_reflex/reflex"
+require "stimulus_reflex/dom_element"
 require "stimulus_reflex/channel"
 
 module StimulusReflex

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_reflex
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Nathan Hopkins
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-17 00:00:00.000000000 Z
+date: 2019-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -156,6 +156,7 @@ files:
 - bin/standardize
 - lib/stimulus_reflex.rb
 - lib/stimulus_reflex/channel.rb
+- lib/stimulus_reflex/dom_element.rb
 - lib/stimulus_reflex/reflex.rb
 - lib/stimulus_reflex/version.rb
 homepage: https://github.com/hopsoft/stimulus_reflex