solder 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: caab8b73cfc913261226022ae6e2e0d67fd6643164fa5d2b9058d7a8eb298cb1
-  data.tar.gz: a03a6323c422e4ee59cc89ccbc3b6431b3b82f755378ca7057d5868fde4e181a
+  metadata.gz: 9d86c83657628b64222a9656e535f19ca6d66a4e675c3e80e7b86d4c2a0f3835
+  data.tar.gz: 42f8a93bca5208c7c0bab9e1d5cf764f8dfa70564dd2c43952d580df8fee8f77
 SHA512:
-  metadata.gz: 1dc4b63179b081c60def903eae5ee336209a8c90eebe8136c43f2f5f3dd1f932a9b1b2745c672cf3c80f421243433f1228f6db36acc29bd838f0fba11b63c62e
-  data.tar.gz: 2d02e8e58009e38c21568c5d8aaa3dc97bfa6f42682865b4d2c13dba549dc76c4913670460dcf4a4ea0ac1c1cedb14138baf97133fcc13d349405a229671f5ee
+  metadata.gz: cf18a4e8990db861c48cb81585afff0e6d14d3baa98fe2769947c383af10f9aeefe5c73d0787dbf27f994920eef3aeac4910a07bf7386813bc3dde0ae1a857d9
+  data.tar.gz: 0b08006eda6254c442df937076b51980a01b47becff672f3bca401ba73d73af641f6e1d684a325cff4396c3c58c068bbbeb491e5b109efa5335866ab83040423

data/README.md

@@ -1,12 +1,30 @@
 # 🧑‍🏭 Solder
-Short description and motivation.
+Persist and restore ephemeral attributes of HTML elements using the Rails cache store and StimulusJS
 
-## Usage
-How to use my plugin.
+In short, this plugin will persist UI state changes a user makes on a per-element basis.
+
+This is useful for
+- storing the open/closed state of a sidebar, accordion, etc.
+- storing the state of tree views (e.g. storefront categories),
+- custom dashboard layouts
+- etc.
+
+![A Cyborg Hand Soldering, Steampunk Style](https://user-images.githubusercontent.com/4352208/208506264-db5abac6-7d33-4504-9c0d-2d5f8c26994b.png)
+
+_Image: [openjourney](https://replicate.com/prompthero/openjourney), prompt: mdjrny-v4 style cyborg soldering a piece of code onto a web application user interface, 8k, steampunk_
 
-### Persistence
+## Rationale
 
-Uses the active Rails cache store, possibly more adapters to come
+Modern server-side rendering techniques like Turbo Frames/Streams, StimulusReflex and others require to persist state on the server to facilitate rerendering without UI discrepancies.
+
+Typically, you have a few options to achieve this:
+- ActiveRecord,
+- the `session`,
+- [Kredis](https://github.com/rails/kredis)
+are the most frequent ones. It requires you to invent keys to access the state of UI elements, e.g. `session[:collapsed_categories]` etc.
+Experience shows that the management of those keys tends to increase complexity.
+
+Hence, the part that this gem takes care of is the automatic generation and management of those keys.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -25,6 +43,25 @@ Or install it yourself as:
 $ gem install solder
 ```
 
+## Usage
+
+In your view, use the `solder_onto` helper to create a unique key for the element whose attributes you want to track. For example, imagine we have an online store with multiple category-specific landing pages. There's a tree view on it for further filtering items:
+
+```erb
+<%= solder_onto([current_user, @category] do %>
+  <details>
+    <summary>Outdoor Equipment</summary>
+    
+    <details> ... </details>
+  </details>
+<% end %>
+```
+
+**IMPORTANT**: 
+1. The helper only takes care of the attributes of the **first child** within it. This is because of how [`capture`](https://api.rubyonrails.org/classes/ActionView/Helpers/CaptureHelper.html#method-i-capture) works.
+2. Think of the first argument to `solder_onto` as something akin to a cache key. You want it to be unique with regard to (almost always) the logged in user, and any other record it is scoped to. In fact, it adheres to the same interface as [`cache`](https://api.rubyonrails.org/classes/ActionView/Helpers/CacheHelper.html#method-i-cache)
+
+
 ## Dependencies
 
 ### Ruby
@@ -34,7 +71,10 @@ $ gem install solder
 
 - Stimulus
 - @rails/request.js
-- Turbo
+
+## Persistence
+
+Uses the active Rails cache store, possibly more adapters to come.
 
 ## Contributing
 Contribution directions go here.

data/Rakefile

@@ -6,3 +6,13 @@ load "rails/tasks/engine.rake"
 load "rails/tasks/statistics.rake"
 
 require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/solder/ui_state_controller.rb

@@ -1,13 +1,15 @@
 module Solder
   class UiStateController < ApplicationController
     before_action :set_ui_state, only: :show
+    around_action Solder.config[:around_action]
 
     def show
       render json: @ui_state.to_json
     end
 
     def update
-      Rails.cache.write "solder/#{params[:key]}", JSON.parse(params[:attributes])
+      Rails.cache.write "solder/#{ui_state_params[:key]}", parsed_attributes
+      records_to_touch.map(&:touch)
 
       head :ok
     end
@@ -19,7 +21,15 @@ module Solder
     end
 
     def set_ui_state
-      @ui_state = Rails.cache.read "solder/#{params[:key]}"
+      @ui_state = Rails.cache.read "solder/#{ui_state_params[:key]}"
+    end
+
+    def records_to_touch
+      GlobalID::Locator.locate_many_signed parsed_attributes["data-solder-touch"]&.split(":") || []
+    end
+
+    def parsed_attributes
+      JSON.parse(ui_state_params[:attributes])
     end
   end
 end

data/app/helpers/solder/application_helper.rb

@@ -1,5 +1,27 @@
 module Solder
   module ApplicationHelper
+    def solder_onto(name, touch: [], attribute_safelist: ["class"], &block)
+      soldered_html = capture(&block).to_s.strip
+      fragment = Nokogiri::HTML.fragment(soldered_html)
+
+      first_fragment_child = fragment.first_element_child
+
+      # rehydrate
+      ui_state = Rails.cache.read "solder/#{solder_key(name)}"
+
+      ui_state&.select { attribute_safelist.include?(_1) }&.each do |attribute_name, value|
+        first_fragment_child[attribute_name] = sanitize(value, tags: [])
+      end
+
+      # add stimulus controller and create unique key
+      first_fragment_child["data-controller"] = "#{first_fragment_child["data-controller"]} solder".strip
+      first_fragment_child["data-solder-key-value"] = solder_key(name)
+
+      first_fragment_child["data-solder-touch"] ||= Array(touch).map(&:to_sgid).map(&:to_s).join(":")
+
+      first_fragment_child.to_html.html_safe
+    end
+
     def solder_key(name)
       key = cache_fragment_name(name, skip_digest: true)
         .flatten
@@ -7,7 +29,7 @@ module Solder
         .map(&:cache_key)
         .join(":")
 
-      key += ":#{caller(1..1).first}"
+      key += ":#{caller.find { _1 =~ /html/ }}"
 
       ActiveSupport::Digest.hexdigest(key)
     end

data/app/helpers/solder/application_helper.rb~

@@ -1,12 +1,35 @@
 module Solder
   module ApplicationHelper
+    def solder_onto(name, touch: [], attribute_safelist: ["class"], &block)
+      soldered_html = capture(&block).to_s.strip
+      fragment = Nokogiri::HTML.fragment(soldered_html)
+
+      first_fragment_child = fragment.first_element_child
+
+      # rehydrate
+      ui_state = Rails.cache.read "solder/#{solder_key(name)}"
+
+      ui_state&.select { attribute_safelist.include?(_1) }&.each do |attribute_name, value|
+        first_fragment_child[attribute_name] = sanitize value
+      end
+
+      # add stimulus controller and create unique key
+      first_fragment_child["data-controller"] = "#{first_fragment_child["data-controller"]} solder".strip
+      first_fragment_child["data-solder-key-value"] = solder_key(name)
+
+      first_fragment_child["data-solder-touch"] ||= Array(touch).map(&:to_sgid).map(&:to_s).join(":")
+
+      first_fragment_child.to_html.html_safe
+    end
+
     def solder_key(name)
       key = cache_fragment_name(name, skip_digest: true)
         .flatten
         .compact
         .map(&:cache_key)
         .join(":")
-      key += ":#{caller(1..1).first}"
+
+      key += ":#{caller.find { _1 =~ /html/ }}"
 
       ActiveSupport::Digest.hexdigest(key)
     end

data/lib/solder/engine.rb

@@ -1,7 +1,14 @@
 module Solder
+  def self.config
+    Rails.application.config.solder
+  end
+
   class Engine < ::Rails::Engine
     isolate_namespace Solder
 
+    config.solder = ActiveSupport::OrderedOptions.new
+    config.solder[:around_action] = ->(_controller, action) { action.call }
+
     initializer "solder.check_caching" do |app|
       unless app.config.action_controller.perform_caching && app.config.cache_store != :null_store
         puts <<~WARN
@@ -15,8 +22,11 @@ module Solder
       end
     end
 
-    config.after_initialize do
-      ::ApplicationHelper.include helpers
+    initializer "solder.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include Solder::ApplicationHelper
+        helper Solder::Engine.helpers
+      end
     end
   end
 end

data/lib/solder/engine.rb~

@@ -1,16 +1,29 @@
 module Solder
+  def self.config
+    Rails.application.config.solder
+  end
+
   class Engine < ::Rails::Engine
     isolate_namespace Solder
 
-    initializer "solder.check_caching" do
-      unless Rails.application.config.action_controller.perform_caching && Rails.application.config.cache_store != :null_store
+    config.solder = ActiveSupport::OrderedOptions.new
+    config.solder[:around_action] = ->(_controller, action) { action.call }
+
+    initializer "solder.check_caching" do |app|
+      unless app.config.action_controller.perform_caching && app.config.cache_store != :null_store
         puts <<~WARN
-            Solder uses the Rails cache store to provide UI state persistence. Therefore, please make sure caching is enabled in your environment.Engine
+          🧑‍🏭 Solder uses the Rails cache store to provide UI state persistence. Therefore, please make sure caching is enabled in your environment.
 
           To enable caching in development, run:
             rails dev:cache
         WARN
+
+        exit false
       end
     end
+
+    config.after_initialize do
+      ::ApplicationHelper.include helpers
+    end
   end
 end

data/lib/solder/version.rb

@@ -1,3 +1,3 @@
 module Solder
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/solder/version.rb~

@@ -0,0 +1,3 @@
+module Solder
+  VERSION = "0.1.0"
+end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: solder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Julian Rubisch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-12 00:00:00.000000000 Z
+date: 2023-01-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -39,19 +53,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.1'
 - !ruby/object:Gem::Dependency
-  name: turbo-rails
+  name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
-  type: :runtime
+        version: '0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: solargraph-rails
   requirement: !ruby/object:Gem::Requirement
@@ -120,6 +134,7 @@ files:
 - lib/solder/engine.rb
 - lib/solder/engine.rb~
 - lib/solder/version.rb
+- lib/solder/version.rb~
 - lib/tasks/solder_tasks.rake
 homepage: https://github.com/julianrubisch/solder
 licenses: []