view_component_reflex 1.1.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 163bc65c20bb1ac85bb9e15ee2ce4fbf7039a9d90cbe7c4cb1591d03699edc71
-  data.tar.gz: fb80faac53511b705e0170da3cfae4c7c82c1a59c6bf773e8b86eea30463b9f5
+  metadata.gz: 0d42e80a31d1a4a27c828f02fc584e9c5eb6660a6d5697e0db3a9631be358dec
+  data.tar.gz: 96450604f1d0965c104171a8b1d667f6d4dc38019e0c6434fd974ff80a3d9f26
 SHA512:
-  metadata.gz: 9936a4885f9b8e625eca11ac78af316f475764688a5fd2aca9f098aabd802c5e578bdca12266b7176c52c3ff6302dcf7c703e1dd902194bc2dd8c20a1071ab14
-  data.tar.gz: e5fca59e3e33091ee7b53df0d0cf40007b476835f141cd3f717d7b86e14fde3cec8ffce960a4f23b7ffe5f12a48d10a6917843a9e33c67d911b76485187796c7
+  metadata.gz: deaf8859ae5816796b965ba5c7e1022032253f44fc1e6c94bcdda8dd481d20afb1319a63c99acc98e184908c5c0b299384e1b77cecef4cd5099263bc4f0d4606
+  data.tar.gz: 6da8e3668c5cf6f2dd64c770eada3b381669dd2dac2cf11dc65b2f9e7a94d4e7d450a563506459057642d0f97629d582d1935a9eef7bbf61acfc084402b2e1cd

data/README.md

@@ -30,7 +30,7 @@ end
 # counter_component.html.erb
 <%= component_controller do %>
     <p><%= @count %></p>
-    <button type="button" data-reflex="click->CounterComponentReflex#increment" data-key="<%= key %>">Click</button>
+    <%= reflex_tag :increment, :button, "Click" %>
 <% end %>
 ```
 
@@ -39,7 +39,7 @@ end
 In order to reconcile state to components in collections, you can specify a `collection_key` method that returns some
 value unique to that component.
 
-```
+```ruby
 class TodoComponent < ViewComponentReflex::Component
   def initialize(todo:)
     @todo = todo
@@ -53,6 +53,134 @@ end
 <%= render(TodoComponent.with_collection(Todo.all)) %>
 ```
 
+## API
+
+### permit_parameter?(initial_param, new_params)
+If a new parameter is passed to the component during rendering, it is used instead of what's in state.
+If you're storing instances in state, you can use this to properly compare them.
+
+```ruby
+def permit_parameter?(initial_param, new_param)
+  if new_param.instance_of? MyModel 
+    new_param.id == @my_model.id
+  else
+    super
+  end
+end
+```
+
+### omitted_from_state
+Return an array of instance variables you want to omit from state. Useful if you have an object 
+that isn't serializable as an instance variable, like a form.
+
+```ruby
+def omitted_from_state
+  [:@form]
+end
+```
+
+### reflex_tag(reflex, name, content_or_options_with_block = nil, options = nil, escape = true, &block)
+This shares the same definition as `content_tag`, except it accepts a reflex as the first parameter.
+
+```erb
+<%= reflex_tag :increment, :button, "Click me!" %>
+```
+
+Would add a click handler to the `increment` method on your component.
+
+To use a non-click event, specific that with `->` notiation
+
+```erb
+<%= reflex_tag "mouseenter->increment", :button, "Click me!" %>
+```
+
+### collection_key
+If you're rendering a component as a collection with `MyComponent.with_collection(SomeCollection)`, you must define this method to return some unique value for the component.
+This is used to reconcile state in the background.
+
+```ruby
+def initialize
+  @my_model = MyModel.new
+end
+
+def collection_key
+ @my_model.id
+end
+```
+
+### prevent_refresh!
+By default, VCR will re-render your component after it executes your method. `revent_refresh!` prevents this from happening.
+
+```ruby
+def my_method
+  prevent_refresh!
+  @foo = Lbar
+end # the rendered page will not reflect this change
+```
+
+### refresh_all!
+Refresh the entire body of the page
+
+```ruby
+def do_some_global_action
+  prevent_refresh!
+  session[:model] = MyModel.new
+  refresh_all!
+end
+```
+
+### key
+This is a key unique to a particular component. It's used to reconcile state between renders, and should be passed as a data attribute whenever a reflex is called
+
+```erb
+<button type="button" data-reflex="click->MyComponent#do_something" data-key="<%= key %>">Click me!</button>
+```
+
+### component_controller(options = {}, &blk)
+This is a view helper to properly connect VCR to the component. It outputs `<div data-controller="my-controller" key=<%= key %></div>`
+You *must* wrap your component in this for everything to work properly.
+
+```erb
+<%= component_controller do %>
+  <p><%= @count %></p
+<% end %>
+```
+
+## Common patterns
+A lot of the time, you only need to update specific components when changing instance variables. For example, changing `@loading` might only need
+to display a spinner somewhere on the page. You can define setters to implicitly render the appropriate pieces of dom whenever that variable is set
+
+```ruby
+def initialize
+  @loading = false
+end
+
+def loading=(new_value)
+  @loading = new_value
+  refresh! '#loader'
+end
+
+def do_expensive_action
+  prevent_refresh! 
+
+  self.loading = true
+  execute_it
+  self.loading = false
+end
+```
+
+```erb
+<%= component_controller do %>
+  <div id="loader"> 
+    <% if @loading %>
+      <p>Loading...</p>
+    <% end %>
+  </div>
+
+  <button type="button" data-reflex="click->MyComponent#do_expensive_action" data-key="<%= key %>">Click me!</button>
+<% end
+```
+
 ## Custom State Adapters
 
 ViewComponentReflex uses session for its state by default. To change this, add
@@ -76,13 +204,13 @@ class YourAdapter
   end
 
   ##
-  # set_state is used to modify the state. It accepts a reflex, which gives you
-  # access to the request, as well as the controller and other useful objects. 
+  # set_state is used to modify the state.
   #
-  # reflex - The reflex instance that's trying to set the state
+  # request - a rails request object
+  # controller - the current controller
   # key - a unique string that identifies the component
   # new_state - the new state to set
-  def self.set_state(reflex, key, new_state)
+  def self.set_state(request, controller, key, new_state)
     # update the state
   end
 

data/app/components/view_component_reflex/component.rb

@@ -43,7 +43,11 @@ module ViewComponentReflex
               component.instance_variable_set(k, v)
             end
             name.to_proc.call(component, *args)
-            refresh!
+            refresh! unless @prevent_refresh
+          end
+
+          def prevent_refresh!
+            @prevent_refresh = true
           end
 
           define_method :component_class do
@@ -62,7 +66,7 @@ module ViewComponentReflex
             return @component if @component
             @component = component_class.allocate
             reflex = self
-            exposed_methods = [:params, :request, :element, :refresh!, :refresh_all!, :stimulus_controller]
+            exposed_methods = [:params, :request, :element, :refresh!, :refresh_all!, :stimulus_controller, :session, :prevent_refresh!]
             exposed_methods.each do |meth|
               @component.define_singleton_method(meth) do |*a|
                 reflex.send(meth, *a)
@@ -72,7 +76,7 @@ module ViewComponentReflex
           end
 
           def set_state(new_state = {})
-            ViewComponentReflex::Engine.state_adapter.set_state(self, element.dataset[:key], new_state)
+            ViewComponentReflex::Engine.state_adapter.set_state(request, controller, element.dataset[:key], new_state)
           end
 
           def state
@@ -98,15 +102,23 @@ module ViewComponentReflex
       helpers.controller.instance_variable_get(:@stimulus_reflex)
     end
 
-    def component_controller(opts = {}, &blk)
+    def component_controller(opts_or_tag = :div, opts = {}, &blk)
       self.class.init_stimulus_reflex
       init_key
-      opts[:data] = {
+
+      tag = :div
+      if opts_or_tag.is_a? Hash
+        options = opts_or_tag
+      else
+        tag = opts_or_tag
+        options = opts
+      end
+      options[:data] = {
         controller: self.class.stimulus_controller,
         key: key,
-        **(opts[:data] || {})
+        **(options[:data] || {})
       }
-      content_tag :div, capture(&blk), opts
+      content_tag tag, capture(&blk), options
     end
 
     # key is required if you're using state
@@ -121,10 +133,36 @@ module ViewComponentReflex
       @key = key
     end
 
+    def reflex_tag(reflex, name, content_or_options_with_block = nil, options = nil, escape = true, &block)
+      action, method = reflex.to_s.split("->")
+      if method.nil?
+        method = action
+        action = "click"
+      end
+      data_attributes = {
+        reflex: "#{action}->#{self.class.name}##{method}",
+        key: key
+      }
+      if content_or_options_with_block.is_a?(Hash)
+        merge_data_attributes(content_or_options_with_block, data_attributes)
+      else
+        merge_data_attributes(options, data_attributes)
+      end
+      content_tag(name, content_or_options_with_block, options, escape, &block)
+    end
+
     def collection_key
       nil
     end
 
+    def permit_parameter?(initial_param, new_param)
+      initial_param != new_param
+    end
+
+    def omitted_from_state
+      []
+    end
+
     def key
       # initialize session state
       if !stimulus_reflex? || session[@key].nil?
@@ -137,15 +175,30 @@ module ViewComponentReflex
           :@helpers, :@controller, :@request, :@content
         ]
         instance_variables.reject { |k| blacklist.include?(k) }.each do |k|
-          new_state[k] = instance_variable_get(k)
+          new_state[k] = instance_variable_get(k) unless omitted_from_state.include?(k)
         end
         ViewComponentReflex::Engine.state_adapter.store_state(request, @key, new_state)
+        ViewComponentReflex::Engine.state_adapter.store_state(request, "#{@key}_initial", new_state)
       else
+        initial_state = ViewComponentReflex::Engine.state_adapter.state(request, "#{@key}_initial")
         ViewComponentReflex::Engine.state_adapter.state(request, @key).each do |k, v|
-          instance_variable_set(k, v)
+          unless permit_parameter?(initial_state[k], instance_variable_get(k))
+            instance_variable_set(k, v)
+          end
         end
       end
       @key
     end
+
+    private
+
+    def merge_data_attributes(options, attributes)
+      data = options[:data]
+      if data.nil?
+        options[:data] = attributes
+      else
+        options[:data].merge! attributes
+      end
+    end
   end
 end

data/lib/view_component_reflex/state_adapter/session.rb

@@ -5,12 +5,12 @@ module ViewComponentReflex
         request.session[key] ||= {}
       end
 
-      def self.set_state(reflex, key, new_state)
+      def self.set_state(request, controller, key, new_state)
         new_state.each do |k, v|
-          state(reflex.request, key)[k] = v
+          state(request, key)[k] = v
         end
-        store = reflex.request.session.instance_variable_get("@by")
-        store.commit_session reflex.request, reflex.controller.response
+        store = request.session.instance_variable_get("@by")
+        store.commit_session request, controller.response
       end
 
       def self.store_state(request, key, new_state = {})

data/lib/view_component_reflex/version.rb

@@ -1,3 +1,3 @@
 module ViewComponentReflex
-  VERSION = '1.1.1'
+  VERSION = '1.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component_reflex
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Joshua LeBlanc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-20 00:00:00.000000000 Z
+date: 2020-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails