stimulus_reflex 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce2617cefcb188998c2f9aca1a440bd2501839a699166cdfa32fba44741af5f5
-  data.tar.gz: a486389eef17cfa47e8fefef2256cd72a2aff25c1d6ce5713cc49d444565f787
+  metadata.gz: 8072c82ab1f16ce62c41e6d970952c3762a9e2fe5d87d2036ff2f37af7f3a4fb
+  data.tar.gz: b3549d33023d9c27e878443f48391e13b82562e4dc9d9cbfb64b9744d8fe0702
 SHA512:
-  metadata.gz: 36f7b68e56c6446b5125d984378f24207bec848fdfeb99365b99dcac3f9b725e20a99fbd093740e22abc8c8d6fae4b16bd9c470d475289adcd25bb4b177a5563
-  data.tar.gz: ed8f1e225df23c5b949f2c1f6a4f743521f7b6118f621808b19f46d6716fe812b7c6d475149972ad655737806c3612768d9001cc1f6619b41e2732543a6f6fb4
+  metadata.gz: 5ba2646379f9bbe65485d947c55467640e890d516ad571f704e064f0fb78956b977ba405d5698efdb6fd3b7e87f1075a9948d59c4b6ec2855410d3b290137a31
+  data.tar.gz: 756a22a1a4cb5f1d4ad985dd1424ed15edc3d2e4d8efcf080d3c3a9a551a170fc1a76d84543fd105acc104b97c07d7f377348a00ec329222fa6341c0e627051c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stimulus_reflex (1.1.1)
+    stimulus_reflex (2.0.0)
       cable_ready (>= 4.0.3)
       nokogiri
       rack

data/README.md

@@ -1,5 +1,7 @@
-[![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/)
+[![Lines of Code](http://img.shields.io/badge/lines_of_code-218-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)
+![Prettier](https://github.com/hopsoft/stimulus_reflex/workflows/Prettier%20Check%20Action/badge.svg)
+![StandardRB](https://github.com/hopsoft/stimulus_reflex/workflows/StandardRB%20Check%20Action/badge.svg)
 
 # StimulusReflex
 
@@ -25,14 +27,19 @@ _Inspired by [Phoenix LiveView](https://youtu.be/Z2DU0qLfPIY?t=670)._ 🙌
 - [How it Works](#how-it-works)
 - [Setup](#setup)
   * [JavaScript](#javascript)
+    + [app/javascript/controllers/index.js](#appjavascriptcontrollersindexjs)
   * [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)
+- [Usage](#usage)
+  * [Implicit Declarative Reflexes](#implicit-declarative-reflexes)
+    + [app/views/pages/example.html.erb](#appviewspagesexamplehtmlerb)
+    + [app/reflexes/example_reflex.rb](#appreflexesexample_reflexrb)
+  * [Explicitly Defined Reflexes](#explicitly-defined-reflexes)
+    + [app/views/pages/example.html.erb](#appviewspagesexamplehtmlerb-1)
+    + [app/javascript/controllers/example.js](#appjavascriptcontrollersexamplejs)
+    + [app/reflexes/example_reflex.rb](#appreflexesexample_reflexrb-1)
+- [What Just Happened](#what-just-happened)
 - [Advanced Usage](#advanced-usage)
-  * [Reflex Methods](#reflex-methods)
-    + [The `options` Keyword Argument](#the-options-keyword-argument)
+  * [The Reflex `element` property](#the-reflex-element-property)
   * [ActionCable](#actioncable)
     + [Performance](#performance)
     + [ActionCable Rooms](#actioncable-rooms)
@@ -77,6 +84,21 @@ There are no hidden gotchas.
 ```
 yarn add stimulus_reflex
 ```
+#### app/javascript/controllers/index.js
+
+This is the file where Stimulus is initialized in your application.
+_Note that your file location may be different._
+
+```javascript
+import { Application } from 'stimulus';
+import { definitionsFromContext } from 'stimulus/webpack-helpers';
+import StimulusReflex from 'stimulus_reflex';
+
+const application = Application.start();
+const context = require.context('controllers', true, /_controller\.js$/);
+application.load(definitionsFromContext(context));
+StimulusReflex.initialize(application);
+```
 
 ### Gemfile
 
@@ -84,9 +106,47 @@ yarn add stimulus_reflex
 gem "stimulus_reflex"
 ```
 
-## Basic Usage
+## Usage
+
+### Implicit Declarative Reflexes
+
+This example shows how to create a reactive feature without the need to write any JavaScript
+other than initializing StimulusReflex itself _([see the setup instructions](#javascript))_. Everything else is managed entirely by HTML and Ruby.
 
-### app/views/pages/example.html.erb
+#### app/views/pages/example.html.erb
+
+```erb
+<head></head>
+  <body>
+    <a href="#" data-reflex="click->ExampleReflex#increment" data-step="1" data-count="<%= @count.to_i %>">
+      Increment <%= @count.to_i %>
+    </a>
+  </body>
+</html>
+```
+
+#### app/reflexes/example_reflex.rb
+
+```ruby
+class ExampleReflex < StimulusReflex::Reflex
+  def increment
+    @count = element.dataset[:count].to_i + element.dataset[:step].to_i
+  end
+end
+```
+
+The code above will automatically update the relevant DOM nodes with the updated count whenever the anchor is clicked.
+
+__Note that all concerns from managing state to rendering views are handled server side.__
+This technique works regardless of how complex the UI may become.
+For example, we could render multiple instances of `@count` in unrelated sections of the page and they will all update.
+
+### Explicitly Defined Reflexes
+
+This example shows how to create a reactive feature by defining an explicit client side
+Stimulus controller to handle the DOM event and trigger the server side reflex.
+
+#### app/views/pages/example.html.erb
 
 ```erb
 <head></head>
@@ -98,7 +158,7 @@ gem "stimulus_reflex"
 </html>
 ```
 
-### app/javascript/controllers/example.js
+#### app/javascript/controllers/example.js
 
 ```javascript
 import { Controller } from "stimulus"
@@ -116,7 +176,7 @@ export default class extends Controller {
 }
 ```
 
-### app/reflexes/example_reflex.rb
+#### app/reflexes/example_reflex.rb
 
 ```ruby
 class ExampleReflex < StimulusReflex::Reflex
@@ -126,65 +186,57 @@ class ExampleReflex < StimulusReflex::Reflex
 end
 ```
 
-The following happens after the `StimulusReflex::Reflex` method call finishes.
+## What Just Happened
+
+The following happens when a `StimulusReflex::Reflex` is invoked.
 
 1. The page that triggered the reflex is re-rerendered. _Instance variables created in the reflex are available to both the controller and view templates._
 2. The re-rendered HTML is sent to the client over the ActionCable socket.
-3. The page is updated via fast DOM diffing courtesy of morphdom. _While future versions of StimulusReflex might support more granular updates, today the entire body is re-rendered and sent over the socket._
-
-## Advanced Usage
-
-### Reflex Methods
+3. The page is updated via fast DOM diffing courtesy of morphdom.
 
-#### The `options` Keyword Argument
+   _NOTE: While future versions of StimulusReflex may support more granular updates, today the entire body is re-rendered and sent over the socket._
 
-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
+## Advanced Usage
 
-  def other_work(value, options: {})
-    # ...
-  end
-end
-```
+### The Reflex `element` property
 
-The `options` value contains all of the Stimulus controller's
+All reflex methods expose an `element` property.
+This property holds a Hash like data structure that represents the HTML element that triggered the refelx.
+It 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" />
+<checkbox id="example"
+          label="Example"
+          data-controller="checkbox"
+          data-value="123"
+          checked />
 ```
 
-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"
+  def work()
+    element[:id]    # => the HTML element's id attribute value
+    element.dataset # => a Hash that represents the HTML element's dataset
+
+    element[:id]                 # => "example"
+    element[:checked]            # => true
+    element[:label]              # => "Example"
+    element["data-controller"]   # => "checkbox"
+    element["data-value"]        # => "123"
+    element.dataset[:controller] # => "checkbox"
+    element.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
+- `element[:checked]` holds a boolean
+- `element[:selected]` holds a boolean
+- `element[:value]` holds the [DOM element's value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#value)
+- `select` elements assign `element[:value]` to their selected option's value
+- `select` elements with _multiselect_ enabled assign `element[:values]` to their selected options values
+- All other values exposed in `element` are extracted from the DOM element's attributes
 
 ### ActionCable
 
@@ -249,11 +301,5 @@ Please run `./bin/standardize` prior submitting pull requests.
 1. Run `rake build`
 1. Run `rake release`
 1. Change directories `cd ./javascript`
-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
-    ```
+1. Run `yarn publish --tag GIT_TAG_CREATED_BY_RUBYGEMS`
+1. Assign same version number to the JavaScript package _Might not be required?_

data/lib/stimulus_reflex.rb

@@ -10,7 +10,7 @@ require "nokogiri"
 require "cable_ready"
 require "stimulus_reflex/version"
 require "stimulus_reflex/reflex"
-require "stimulus_reflex/dom_element"
+require "stimulus_reflex/element"
 require "stimulus_reflex/channel"
 
 module StimulusReflex

data/lib/stimulus_reflex/channel.rb

@@ -22,11 +22,11 @@ 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"])
+    element = StimulusReflex::Element.new(data["attrs"])
 
     begin
-      reflex = reflex_name.constantize.new(self, url: url)
-      delegate_call_to_reflex reflex, method_name, arguments, options
+      reflex = reflex_name.constantize.new(self, url: url, element: element)
+      delegate_call_to_reflex reflex, method_name, arguments
     rescue => invoke_error
       logger.error "\e[31mStimulusReflex::Channel Failed to invoke #{target}! #{url} #{invoke_error}\e[0m"
     end
@@ -40,24 +40,15 @@ class StimulusReflex::Channel < ActionCable::Channel::Base
 
   private
 
-  def delegate_call_to_reflex(reflex, method_name, arguments = [], options = {})
+  def delegate_call_to_reflex(reflex, method_name, arguments = [])
     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
+      reflex.public_send method_name
     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
+      reflex.public_send method_name, *arguments
     else
       raise ArgumentError.new("wrong number of arguments (given #{arguments.inspect}, expected #{required_params.inspect}, optional #{optional_params.inspect})")
     end

data/lib/stimulus_reflex/{dom_element.rb → element.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class StimulusReflex::DomElement
+class StimulusReflex::Element
   attr_reader :attributes
 
   delegate :[], to: :"@attributes"

data/lib/stimulus_reflex/reflex.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
 class StimulusReflex::Reflex
-  attr_reader :channel, :url
+  attr_reader :channel, :url, :element
 
   delegate :connection, to: :channel
   delegate :session, to: :request
 
-  def initialize(channel, url: nil)
+  def initialize(channel, url: nil, element: nil)
     @channel = channel
     @url = url
+    @element = element
   end
 
   def request

data/lib/stimulus_reflex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StimulusReflex
-  VERSION = "1.1.1"
+  VERSION = "2.0.0"
 end

metadata

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