view_component_reflex 1.3.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30533287ce1445add7dba2ebed5013ed80e792de560fa9c930f3e13dcbd612d7
-  data.tar.gz: bf84f573e602b373855848b2fbe61245967e4f16e7a420b03c1b6414aa1c8c73
+  metadata.gz: eb949fc8de60d18d54d72195cd04947ba24ef73db4091b2ddd0c2992287df7d0
+  data.tar.gz: c474384a6b9c073ba4efbf924067113971e67c4e8bdc0fbfa6462471ecf95b6e
 SHA512:
-  metadata.gz: 47dc5ab24c0711778b07b8460207b1e532c944173d4df2cc8fe33447868b96a9043ad972b5a9672a0ea09ad323199b7cfa15327634199d3218e69e6c797f4196
-  data.tar.gz: d9dbc21f77baf9c73c20352a5163c8af52317a0138393d4128cc34bb60e903227e62e28e0f0e0ad92f4fa10d4206f79d295c74582774b93fefffd14801fe5c44
+  metadata.gz: e0f4a365d380e55ba8deb5f567f35fa81b2aa8ab108cd2aca4f6e97041139e8e53f446f30db3ddcea0ee0fcb08e62b2f98feef14b83f5810c54ce705a6564716
+  data.tar.gz: df46044a3c7bddc9ab204ddb052fce04f0cecf190428043a3aa4ff2fb5a1b86d7d4e9524fa509ecbea51991641f8b4da9b8eaed2b1f4ede565c6cdb922a07724

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
@@ -59,16 +59,132 @@ end
 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.
+Return an array of instance variables you want to omit from state. Only really useful if you're using the session state
+adapter, and you have an instance variable that can't be serialized.
 
-```
+```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
+```
+
+## State
+
+By default, view_component_reflex stores component state in memory. You can optionally set the state adapter
+to use the session by changing `config.state_adapter` to `ViewComponentReflex::StateAdapter::Session`
 
 ## Custom State Adapters
 

data/app/components/view_component_reflex/component.rb

@@ -4,21 +4,53 @@ module ViewComponentReflex
       def init_stimulus_reflex
         klass = self
         @stimulus_reflex ||= Object.const_set(name + "Reflex", Class.new(StimulusReflex::Reflex) {
-          def refresh!(primary_selector = "[data-controller~=\"#{stimulus_controller}\"][data-key=\"#{element.dataset[:key]}\"]", *selectors)
+          def refresh!(*selectors)
             save_state
-            @channel.send :render_page_and_broadcast_morph, self, [primary_selector, *selectors], {
-              "dataset" => element.dataset.to_h,
-              "args" => [],
-              "attrs" => element.attributes.to_h,
-              "selectors" => ["body"],
-              "target" => "#{self.class.name}##{method_name}",
-              "url" => request.url,
-              "permanent_attribute_name" => "data-reflex-permanent"
-            }
+
+            # If the component has instance variables omitted from state,
+            # we can't render it to string from here because those instance
+            # variables will be missing. In that case, set the selectors to the
+            # default selector and manually morph the page
+            if selectors.empty? && !component.can_render_to_string?
+              selectors.push selector
+            end
+
+            # If we're just updating the component itself, we can
+            # directly render it instead of rendering the entire page again
+            if selectors.empty?
+              refresh_component!
+            else
+              @channel.send :render_page_and_broadcast_morph, self, selectors, {
+                "dataset" => element.dataset.to_h,
+                "args" => [],
+                "attrs" => element.attributes.to_h,
+                "selectors" => ["body"],
+                "target" => "#{self.class.name}##{method_name}",
+                "url" => request.url,
+                "permanent_attribute_name" => permanent_attribute_name
+              }
+            end
+          end
+
+          def refresh_component!
+            # The component can't figure out the key when we render from here
+            # Luckily we already know the key, so we can manually override it
+            component.tap do |k|
+              k.define_singleton_method(:key) do
+                element.dataset[:key]
+              end
+            end
+            html = controller.render_component_to_string(component)
+            document = Nokogiri::HTML(html)
+            morph selector, document.css("#{selector} > *").to_s
+          end
+
+          def selector
+            "[data-controller~=\"#{stimulus_controller}\"][data-key=\"#{element.dataset[:key]}\"]"
           end
 
           def refresh_all!
-            refresh!("body")
+            morph :body, render_page(self)
           end
 
           # SR's delegate_call_to_reflex in channel.rb
@@ -32,18 +64,17 @@ module ViewComponentReflex
             !!name.to_proc
           end
 
-          before_reflex do |a|
-            a.send a.method_name
-            throw :abort
-          end
-
           def method_missing(name, *args)
             super unless respond_to_missing?(name)
             state.each do |k, v|
               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 +93,7 @@ module ViewComponentReflex
             return @component if @component
             @component = component_class.allocate
             reflex = self
-            exposed_methods = [:params, :request, :element, :refresh!, :refresh_all!, :stimulus_controller, :session]
+            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)
@@ -81,7 +112,7 @@ module ViewComponentReflex
 
           def save_state
             new_state = {}
-            component.instance_variables.each do |k|
+            component.safe_instance_variables.each do |k|
               new_state[k] = component.instance_variable_get(k)
             end
             set_state(new_state)
@@ -98,15 +129,27 @@ module ViewComponentReflex
       helpers.controller.instance_variable_get(:@stimulus_reflex)
     end
 
-    def component_controller(opts = {}, &blk)
+    def can_render_to_string?
+      omitted_from_state.empty?
+    end
+
+    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,6 +164,24 @@ module ViewComponentReflex
       @key = key
     end
 
+    def reflex_tag(reflex, name, content_or_options_with_block = {}, options = {}, 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
@@ -135,18 +196,10 @@ module ViewComponentReflex
 
     def key
       # initialize session state
-      if !stimulus_reflex? || session[@key].nil?
-        new_state = {}
-
-        # this will almost certainly break
-        blacklist = [
-          :@view_context, :@lookup_context, :@view_renderer, :@view_flow,
-          :@virtual_path, :@variant, :@current_template, :@output_buffer, :@key,
-          :@helpers, :@controller, :@request, :@content
-        ]
-        instance_variables.reject { |k| blacklist.include?(k) }.each do |k|
-          new_state[k] = instance_variable_get(k) unless omitted_from_state.include?(k)
-        end
+      if !stimulus_reflex? || ViewComponentReflex::Engine.state_adapter.state(request, @key).empty?
+
+        new_state = create_safe_state
+
         ViewComponentReflex::Engine.state_adapter.store_state(request, @key, new_state)
         ViewComponentReflex::Engine.state_adapter.store_state(request, "#{@key}_initial", new_state)
       else
@@ -159,5 +212,38 @@ module ViewComponentReflex
       end
       @key
     end
+
+    def safe_instance_variables
+      instance_variables - unsafe_instance_variables
+    end
+
+    private
+
+    def unsafe_instance_variables
+      [
+        :@view_context, :@lookup_context, :@view_renderer, :@view_flow,
+        :@virtual_path, :@variant, :@current_template, :@output_buffer, :@key,
+        :@helpers, :@controller, :@request, :@content, :@tag_builder
+      ]
+    end
+
+    def create_safe_state
+      new_state = {}
+
+      # this will almost certainly break
+      safe_instance_variables.each do |k|
+        new_state[k] = instance_variable_get(k) unless omitted_from_state.include?(k)
+      end
+      new_state
+    end
+
+    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.rb

@@ -1,7 +1,8 @@
-require "view_component_reflex/state_adapter/session"
-require "view_component_reflex/engine"
-require 'stimulus_reflex'
-
-module ViewComponentReflex
-  # Your code goes here...
-end
+require "view_component_reflex/state_adapter/session"
+require "view_component_reflex/state_adapter/memory"
+require "view_component_reflex/engine"
+require 'stimulus_reflex'
+
+module ViewComponentReflex
+  # Your code goes here...
+end

data/lib/view_component_reflex/engine.rb

@@ -1,13 +1,13 @@
-module ViewComponentReflex
-  class Engine < ::Rails::Engine
-    class << self
-      mattr_accessor :state_adapter
-
-      self.state_adapter = StateAdapter::Session
-    end
-
-    def self.configure
-      yield self if block_given?
-    end
-  end
-end
+module ViewComponentReflex
+  class Engine < ::Rails::Engine
+    class << self
+      mattr_accessor :state_adapter
+
+      self.state_adapter = StateAdapter::Memory
+    end
+
+    def self.configure
+      yield self if block_given?
+    end
+  end
+end

data/lib/view_component_reflex/state_adapter/memory.rb

@@ -0,0 +1,25 @@
+VIEW_COMPONENT_REFLEX_MEMORY_STATE = {}
+module ViewComponentReflex
+  module StateAdapter
+    class Memory
+      def self.state(request, key)
+        VIEW_COMPONENT_REFLEX_MEMORY_STATE[request.session.id.to_s] ||= {}
+        VIEW_COMPONENT_REFLEX_MEMORY_STATE[request.session.id.to_s][key] ||= {}
+      end
+
+      def self.set_state(request, _, key, new_state)
+        new_state.each do |k, v|
+          state(request, key)[k] = v
+        end
+      end
+
+      def self.store_state(request, key, new_state = {})
+        VIEW_COMPONENT_REFLEX_MEMORY_STATE[request.session.id.to_s] ||= {}
+        VIEW_COMPONENT_REFLEX_MEMORY_STATE[request.session.id.to_s][key] ||= {}
+        new_state.each do |k, v|
+          VIEW_COMPONENT_REFLEX_MEMORY_STATE[request.session.id.to_s][key][k] = v
+        end
+      end
+    end
+  end
+end

data/lib/view_component_reflex/version.rb

@@ -1,3 +1,3 @@
-module ViewComponentReflex
-  VERSION = '1.3.0'
-end
+module ViewComponentReflex
+  VERSION = '1.7.0'
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component_reflex
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Joshua LeBlanc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-21 00:00:00.000000000 Z
+date: 2020-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -71,6 +71,7 @@ files:
 - app/components/view_component_reflex/component.rb
 - lib/view_component_reflex.rb
 - lib/view_component_reflex/engine.rb
+- lib/view_component_reflex/state_adapter/memory.rb
 - lib/view_component_reflex/state_adapter/session.rb
 - lib/view_component_reflex/version.rb
 homepage: https://github.com/joshleblanc/view_component_reflex