grand_central 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4bab60b41f78d368a46d6f5f50411b9ff3e4c1e1
-  data.tar.gz: 162f18b085499204b190ed07b4b12e3fec03e538
+  metadata.gz: fe5a078a6cda01d5fde96d17f7e82f48cebb98ef
+  data.tar.gz: 132beffe1126ec5c30fb33153780e70c8b1505df
 SHA512:
-  metadata.gz: 5f2abc49d9c520540967964f8c6f7badf979c80ec322dba655e69f8fcc8d9ff063d2b867cb1b47f5bdf8954c935a157ed2083f01f95b336af5452c459cb0c0f7
-  data.tar.gz: 0e9922a471ad8e7392f48b68bec976edb67b1ea13867cf6b87436baaabee01ed3ee98727a940613d1ae47b3dbc58ddf8bdcc949dbbcfc8696bdf33597ef134ec
+  metadata.gz: 6c6c671b532b64fbca5e3379819c6e25c2b3d7f529c017a0d14cafb7f953743fe683a9364e8a4ea87d808808e341c32c5ee319027ea3a7930c54f4fd3ff37353
+  data.tar.gz: 6de0e865c112c6efac22927063cfb8d7c07eadd0b1e19c97ddcd24a4af2377ce4832593abc2bd1afd54db7e280ca26d8fb9ded2e7a3d2cf70a66c496895125f3

data/.travis.yml

@@ -1,7 +1,8 @@
 language: ruby
 rvm:
-  - 2.1.10
-  - 2.2.3
-  - 2.3.1
-  - jruby
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - jruby-9.1.14.0
 before_install: gem install bundler

data/Gemfile

@@ -1,4 +1,6 @@
 source 'https://rubygems.org'
 
+gem 'pry'
+
 # Specify your gem's dependencies in grand_central.gemspec
 gemspec

data/README.md

@@ -93,6 +93,91 @@ store = GrandCentral::Store.new(todos: []) do |state, action|
 end
 ```
 
+### Dispatching actions without the store
+
+There may be parts of your app that need to dispatch actions but you don't want them to know about the store itself. In a [Clearwater](https://github.com/clearwater-rb/clearwater) app, for example, your components may need to fire off actions, but you don't want them to know how to get things from the store.
+
+Subclasses of `GrandCentral::Action` have a `store` attribute where you can set the default store to dispatch to:
+
+```ruby
+store = GrandCentral::Store.new(todos: []) do |state, action|
+  # ...
+end
+
+MyAction = GrandCentral::Action.with_attributes(:a, :b, :c)
+MyAction.store = store
+```
+
+To use this default store, you can send the `call` message to the action class itself:
+
+```ruby
+MyAction.call(1, 2, 3) # these arguments correspond to the a, b, and c attributes above
+```
+
+#### Action Currying
+
+You can [curry](https://en.wikipedia.org/wiki/Currying) an action with the `[]` operator instead of `call`. There is a minor difference between action currying and traditional function currying, though: function currying automatically invokes the function once all of the arguments are received, whereas currying a `GrandCentral::Action` will curry until you explicitly invoke it with `call`:
+
+```ruby
+SetAttribute = Action.with_attributes(:attr, :value)
+
+# Returns an action type based on `SetAttribute` with `attr` hard-
+# coded to `:name`. When you invoke this new action type, you only
+# need to provide the value.
+SetName = SetAttribute[:name]
+
+# This action is a further specialization where we know both the
+# attribute *and* the value. You don't need to provide any values.
+ClearName = SetName[nil]
+```
+
+These are all equivalent action invocations:
+
+```ruby
+SetAttribute.call :name, nil
+SetAttribute[:name].call nil
+SetAttribute[:name, nil].call
+SetName.call nil
+ClearName.call
+```
+
+#### Using with Clearwater
+
+Because of action currying, we can set action types as event handlers in Clearwater components. GrandCentral even knows how to handle `Bowser::Event` objects whose targets are instances of `Bowser::Element` (Clearwater uses Bowser as its DOM abstraction). So if you set an action to handle toggling a checkbox, the last argument will contain the input's `checked` property; if you use it for a text box, the last argument will be the `value` property. It'll even prevent `form` submission for you:
+
+```ruby
+AddTodo = Action.with_attributes(:description)
+SetNewTodoDescription = Action.with_attributes(:description)
+ToggleTodo = Action.with_attributes(:todo, :complete)
+DeleteTodo = Action.with_attributes(:todo)
+
+class TodoList
+  include Clearwater::Component
+  
+  def initialize(todos, new_description)
+    @todos = todos
+    @new_description = new_description
+  end
+  
+  def render
+    div([
+      # All arguments are provided to the AddTodo action, but we still delay its invocation
+      form({ onsubmit: AddTodo[@new_description] }, [
+        # We omit the description from SetNewTodoDescription - it's inferred from the input event
+        input(oninput: SetNewTodoDescription, value: @new_description),
+        button('Add'),
+      ]),
+      ul(todos.map { |todo|
+        li([
+          input(type: :checkbox, onchange: ToggleTodo[todo]),
+          todo.description,
+          button({ onclick: DeleteTodo[todo] }, '✖️'),
+        ])
+      }),
+    ])
+  end
+```
+
 ### Performing actions on dispatch
 
 You may want your application to do something in response to a dispatch. For example, in a Clearwater app, you might want to re-render the application when the store's state has changed:
@@ -104,12 +189,37 @@ end
 
 app = Clearwater::Application.new(component: Layout.new)
 
-store.on_dispatch do |old_state, new_state|
-  app.render unless old_state.equal?(new_state)
+# on_dispatch yields the state before and after the dispatch as well as the action
+store.on_dispatch do |before, after, action|
+  app.render unless before.equal?(after)
 end
 ```
 
-Notice the `unless old_state.equal?(new_state)` clause. This is one of the reasons we recommend you update state by returning a new value instead of mutating it in-place. It allows you to do cache invalidation in O(1) time.
+Notice the `unless before.equal?(after)` clause. This is one of the reasons we recommend you update state by returning a new value instead of mutating it in-place. It allows you to do cache invalidation in O(1) time.
+
+Using `on_dispatch` also useful if you want to consolidate all of your side effects:
+
+```ruby
+FetchUsers = Action.create do
+  def request
+    Bowser::HTTP.fetch('/api/users')
+  end
+end
+LoadUsers = Action.with_attributes(:json) do
+  def users
+    json[:users].map { |attrs| User.new(attrs) }
+  end
+end
+
+store.on_dispatch do |before, after, action|
+  case action
+  when FetchUsers
+    action.request
+      .then(&:json)
+      .then(&LoadUsers)
+  end
+end
+```
 
 ## Models
 

data/bin/console

@@ -10,5 +10,5 @@ require "grand_central"
 # require "pry"
 # Pry.start
 
-require "irb"
-IRB.start
+require "pry"
+Pry.start

data/lib/grand_central/action.rb

@@ -72,7 +72,7 @@ module GrandCentral
 
       def call *args
         if store.nil?
-          raise ArgumentError, "No store set for #{action_class}"
+          raise ArgumentError, "No store set for #@action_class"
         end
 
         store.dispatch @action_class.new(*handle_bowser_event(@args + args))

data/lib/grand_central/version.rb

@@ -1,3 +1,3 @@
 module GrandCentral
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grand_central
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Jamie Gaskins
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-11-05 00:00:00.000000000 Z
+date: 2017-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -95,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
 summary: State and action management for Opal apps