solder 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: caab8b73cfc913261226022ae6e2e0d67fd6643164fa5d2b9058d7a8eb298cb1
-  data.tar.gz: a03a6323c422e4ee59cc89ccbc3b6431b3b82f755378ca7057d5868fde4e181a
+  metadata.gz: 00c285939bae079a1349a896571e8b315752b813715081d4d29d043a25d0c27a
+  data.tar.gz: '092845396d182c4082c4915a12fd9a9087666557c95cca1cae4a6be1e9078420'
 SHA512:
-  metadata.gz: 1dc4b63179b081c60def903eae5ee336209a8c90eebe8136c43f2f5f3dd1f932a9b1b2745c672cf3c80f421243433f1228f6db36acc29bd838f0fba11b63c62e
-  data.tar.gz: 2d02e8e58009e38c21568c5d8aaa3dc97bfa6f42682865b4d2c13dba549dc76c4913670460dcf4a4ea0ac1c1cedb14138baf97133fcc13d349405a229671f5ee
+  metadata.gz: adb71a8e89b6c6730250dd0ba23b5ad0390822ba6d35afd130fd655a37ab6cecbcd45f1c443ece71d8e199a8fce984d6070d8dd0dcab4e6444041f0089e402bf
+  data.tar.gz: ea5f579f47725c9d5f148ca0f1e9dca34e2f98a81b6575595442266b36c3e264577ef96fcff94487dbc3fef0390d7c1c891c8f00b9196023ff796d02cde216dc

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,17 @@
 module Solder
   class UiStateController < ApplicationController
+    include ActionView::Helpers::SanitizeHelper
+
     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 +23,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]).deep_transform_values { sanitize(_1) }
     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/lib/generators/solder/initializer/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Copies the Solder configuration template to config/initializers
+
+Example:
+    bin/rails generate solder:initializer
+
+    This will create:
+        config/initializers/solder.rb

data/lib/generators/solder/initializer/USAGE~

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    bin/rails generate initializer Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/solder/initializer/initializer_generator.rb

@@ -0,0 +1,7 @@
+class Solder::InitializerGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  def copy_controller_template
+    template "solder.rb", Rails.root.join("config/initializers/solder.rb")
+  end
+end

data/lib/generators/solder/initializer/initializer_generator.rb~

@@ -0,0 +1,3 @@
+class Solder::InitializerGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+end

data/lib/generators/solder/initializer/templates/solder.rb

@@ -0,0 +1,10 @@
+Solder.configure do |config|
+  # Specify a global around action for Solder's UIStateController
+  # This is useful for any assumptions your app makes, e.g. instance
+  # variables being present, headers being checked, or multitenancy
+  # (see example below)
+  #
+  # config[:around_action] = ->(_controller, action) do
+  #   ActsAsTenant.without_tenant { action.call }
+  # end
+end

data/lib/generators/solder/stimulus/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Copies the solder stimulus controller to app/javascript/controllers
+
+Example:
+    bin/rails generate solder:stimulus
+
+    This will create:
+        app/javascript/controllers/solder_controller.js

data/lib/generators/solder/stimulus/USAGE~

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    bin/rails generate stimulus Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/solder/stimulus/stimulus_generator.rb

@@ -0,0 +1,7 @@
+class Solder::StimulusGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  def copy_controller_template
+    template "solder_controller.js.tt", Rails.root.join("app/javascript/controllers/solder_controller.js")
+  end
+end

data/lib/generators/solder/stimulus/stimulus_generator.rb~

@@ -0,0 +1,3 @@
+class Solder::StimulusGenerator < Rails::Generators::NamedBase
+  source_root File.expand_path("templates", __dir__)
+end

data/lib/generators/solder/stimulus/templates/solder_controller.js.tt

@@ -0,0 +1,41 @@
+import { Controller } from '@hotwired/stimulus'
+import { get, patch } from '@rails/request.js'
+
+export default class extends Controller {
+  static values = {
+    key: String
+  }
+
+  async connect () {
+    this.mutationObserver = new MutationObserver(this.mutateState.bind(this))
+
+    this.mutationObserver.observe(this.element, { attributes: true })
+  }
+
+  disconnect () {
+    this.mutationObserver?.disconnect()
+  }
+
+  mutateState (mutationList, observer) {
+    mutationList
+      .filter(mutation => mutation.attributeName !== 'data-solder-touch')
+      .forEach(async mutation => {
+        const body = new FormData()
+
+        const attributes = {}
+        this.element
+          .getAttributeNames()
+          .filter(name => name !== 'data-controller')
+          .map(name => {
+            attributes[name] = this.element.getAttribute(name)
+          })
+
+        body.append('key', this.keyValue)
+        body.append('attributes', JSON.stringify(attributes))
+
+        await patch('/solder/ui_state/update', {
+          body
+        })
+      })
+  }
+}

data/lib/install/install.rb

@@ -0,0 +1,36 @@
+# install @rails/request.js
+if Rails.root.join("config/importmap.rb").exist?
+  say "Pin @rails/request.js"
+  append_to_file "config/importmap.rb", %(pin "@rails/request.js", preload: true\n)
+else
+  say "Install @rails/request.js"
+  run "yarn add @rails/request.js"
+end
+
+gemfile = Rails.root.join("Gemfile").read
+
+# install stimulus-rails, if not already present
+if !gemfile.include? "stimulus-rails"
+  gem "stimulus-rails"
+  rails_command "stimulus:install"
+  say "✅ stimulus-rails has been installed"
+else
+  say "⏩ stimulus-rails is already installed. Skipping."
+end
+
+# copy stimulus controller template
+generate "solder:stimulus"
+
+# turn on development caching
+if Rails.root.join("tmp", "caching-dev.txt").exist?
+  say "⏩ Already caching in development. Skipping."
+else
+  system "rails dev:cache"
+  say "✅ Enabled caching in development"
+end
+
+# mount engine
+route 'mount Solder::Engine, at: "/solder"'
+
+# copy initializer template
+generate "solder:initializer" if yes?("Do you want to install the solder initializer template?")

data/lib/install/install.rb~

@@ -0,0 +1,17 @@
+if Rails.root.join("config/importmap.rb").exist?
+  say "Pin @rails/request.js"
+  append_to_file "config/importmap.rb", %(pin "@rails/request.js", preload: true\n)
+else
+  say "Install @rails/request.js"
+  run "yarn add @rails/request.js"
+end
+
+# if stimulus isn't present
+# bundle add stimulus-rails
+# bin/rails stimulus:install
+gemfile = Rails.root.join("Gemfile").read
+binding.irb
+
+say "Installing Stimulus"
+gem "stimulus-rails"
+rails_command "stimulus:install"

data/lib/install/templates/solder_controller.js.tt

@@ -0,0 +1,41 @@
+import { Controller } from '@hotwired/stimulus'
+import { get, patch } from '@rails/request.js'
+
+export default class extends Controller {
+  static values = {
+    key: String
+  }
+
+  async connect () {
+    this.mutationObserver = new MutationObserver(this.mutateState.bind(this))
+
+    this.mutationObserver.observe(this.element, { attributes: true })
+  }
+
+  disconnect () {
+    this.mutationObserver?.disconnect()
+  }
+
+  mutateState (mutationList, observer) {
+    mutationList
+      .filter(mutation => mutation.attributeName !== 'data-solder-touch')
+      .forEach(async mutation => {
+        const body = new FormData()
+
+        const attributes = {}
+        this.element
+          .getAttributeNames()
+          .filter(name => name !== 'data-controller')
+          .map(name => {
+            attributes[name] = this.element.getAttribute(name)
+          })
+
+        body.append('key', this.keyValue)
+        body.append('attributes', JSON.stringify(attributes))
+
+        await patch('/solder/ui_state/update', {
+          body
+        })
+      })
+  }
+}

data/lib/solder/engine.rb

@@ -1,8 +1,24 @@
 module Solder
+  class << self
+    def config
+      Rails.application.config.solder
+    end
+
+    def configure
+      yield config
+    end
+  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|
+      next if called_by_installer?
+      next if called_by_generator?
+
       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.
@@ -15,8 +31,23 @@ 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
+
+    private
+
+    def called_by_installer?
+      Rake.application.top_level_tasks.include? "app:template"
+    rescue
+      false
+    end
+
+    def called_by_generator?
+      ARGV.any? { _1.include? "solder:" }
     end
   end
 end

data/lib/solder/engine.rb~

@@ -1,15 +1,31 @@
 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
+
+    initializer "solder.helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include Solder::ApplicationHelper
+        helper Solder::Engine.helpers
       end
     end
   end

data/lib/solder/version.rb

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

data/lib/solder/version.rb~

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

data/lib/tasks/solder_tasks.rake

@@ -1,4 +1,6 @@
-# desc "Explaining what the task does"
-# task :solder do
-#   # Task goes here
-# end
+namespace :solder do
+  desc "Install Solder into the app"
+  task :install do
+    system "#{RbConfig.ruby} ./bin/rails app:template LOCATION=#{File.expand_path("../install/install.rb", __dir__)}"
+  end
+end

metadata

@@ -1,57 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: solder
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Julian Rubisch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-12 00:00:00.000000000 Z
+date: 2023-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.4
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.4
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: stimulus-rails
+  name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: 7.0.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: 7.0.4
 - !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
@@ -107,19 +107,31 @@ files:
 - app/assets/stylesheets/solder/application.css
 - app/controllers/solder/application_controller.rb
 - app/controllers/solder/ui_state_controller.rb
-- app/controllers/solder/ui_state_controller.rb~
 - app/helpers/solder/application_helper.rb
-- app/helpers/solder/application_helper.rb~
 - app/jobs/solder/application_job.rb
 - app/mailers/solder/application_mailer.rb
 - app/models/solder/application_record.rb
 - app/views/layouts/solder/application.html.erb
 - config/routes.rb
-- config/routes.rb~
+- lib/generators/solder/initializer/USAGE
+- lib/generators/solder/initializer/USAGE~
+- lib/generators/solder/initializer/initializer_generator.rb
+- lib/generators/solder/initializer/initializer_generator.rb~
+- lib/generators/solder/initializer/templates/solder.rb
+- lib/generators/solder/initializer/templates/solder.rb~
+- lib/generators/solder/stimulus/USAGE
+- lib/generators/solder/stimulus/USAGE~
+- lib/generators/solder/stimulus/stimulus_generator.rb
+- lib/generators/solder/stimulus/stimulus_generator.rb~
+- lib/generators/solder/stimulus/templates/solder_controller.js.tt
+- lib/install/install.rb
+- lib/install/install.rb~
+- lib/install/templates/solder_controller.js.tt
 - lib/solder.rb
 - 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: []
@@ -141,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.3.22
 signing_key:
 specification_version: 4
 summary: Simplistic UI State Management for Rails Apps using Hotwire and Caching

data/app/controllers/solder/ui_state_controller.rb~

@@ -1,25 +0,0 @@
-module Solder
-  class UiStateController < ApplicationController
-    before_action :set_ui_state
-
-    def show
-      render json: @ui_state.value
-    end
-
-    def update
-      @ui_state.value = JSON.parse(params[:attributes])
-
-      head :ok
-    end
-
-    private
-
-    def ui_state_params
-      params.permit(:attributes, :key)
-    end
-
-    def set_ui_state
-      @ui_state = Kredis.json params[:key]
-    end
-  end
-end

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

@@ -1,14 +0,0 @@
-module Solder
-  module ApplicationHelper
-    def solder_key(name)
-      key = cache_fragment_name(name, skip_digest: true)
-        .flatten
-        .compact
-        .map(&:cache_key)
-        .join(":")
-      key += ":#{caller(1..1).first}"
-
-      ActiveSupport::Digest.hexdigest(key)
-    end
-  end
-end

data/config/routes.rb~

@@ -1,4 +0,0 @@
-Solder::Engine.routes.draw do
-  get 'ui_state/update'
-  get 'ui_state/show'
-end