solid_objects 0.4.3 → 0.5.0

data/lib/solid_objects/actor_view.rb

@@ -37,10 +37,20 @@ module SolidObjects
       )
     end
 
-    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?) -> untyped
-    def component(name, observes: nil, partial: nil)
+    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol) -> untyped
+    def component(
+      name,
+      observes: nil,
+      partial: nil,
+      key: nil,
+      locals: {},
+      refresh: :replace
+    )
       component_name = normalized_component_name(name)
-      return static_component(component_name, partial:) unless observes
+      unless observes
+        validate_static_options!(key:, locals:, refresh:)
+        return static_component(component_name, partial:)
+      end
       if partial
         raise ArgumentError,
           "reactive components resolve partials by actor and component name"
@@ -48,19 +58,21 @@ module SolidObjects
 
       dependencies = normalized_dependencies(observes)
       validate_dependencies!(dependencies)
-      ensure_unique_component!(component_name)
       refresh_path = component_path_resolver.call(view_context:)
       registration = ComponentRegistration.issue(
         reference:,
         component_name:,
+        component_key: key,
         dependencies:,
+        locals:,
+        refresh_method: refresh,
         snapshot:,
         refresh_path:
       )
+      ensure_unique_component!(registration)
       rendered = ComponentRenderer.new(
         snapshot:,
-        component_name:,
-        dependencies:,
+        registration:,
         view_context:,
         authorization_context:
       ).call
@@ -68,9 +80,10 @@ module SolidObjects
       view_context.content_tag(
         :"turbo-frame",
         rendered,
-        id: DomIdentity.component(reference, component_name),
+        id: registration.dom_id,
         data: {
-          solid_objects_revision: "#{snapshot.instance_id}:#{snapshot.revision}"
+          solid_objects_revision: "#{snapshot.instance_id}:#{snapshot.revision}",
+          solid_objects_refresh: registration.refresh_method
         }
       )
     end
@@ -85,6 +98,11 @@ module SolidObjects
       observable_names.dup
     end
 
+    # @rbs () -> bool
+    def morph_components?
+      component_registrations.any?(&:morph?)
+    end
+
     # @rbs () -> State
     def state
       snapshot.actor.state
@@ -183,14 +201,23 @@ module SolidObjects
         "unknown observable dependency #{unknown.inspect} for #{reference.actor_type}"
     end
 
-    # @rbs (String) -> void
-    def ensure_unique_component!(component_name)
-      return unless component_registrations.any? do |registration|
-        registration.component_name == component_name
+    # @rbs (ComponentRegistration) -> void
+    def ensure_unique_component!(registration)
+      return unless component_registrations.any? do |existing_registration|
+        existing_registration.dom_id == registration.dom_id
       end
 
       raise ArgumentError,
-        "component #{component_name.inspect} is already rendered in this solid_object scope"
+        "component #{registration.component_name.inspect} with key " \
+          "#{registration.component_key.inspect} is already rendered in this solid_object scope"
+    end
+
+    # @rbs (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol) -> void
+    def validate_static_options!(key:, locals:, refresh:)
+      return if key.nil? && locals.empty? && refresh.to_s == "replace"
+
+      raise ArgumentError,
+        "key, locals, and refresh require an observable component"
     end
 
     # @rbs () -> Proc | ComponentPathResolver

data/lib/solid_objects/component_registration.rb

@@ -6,7 +6,10 @@ module SolidObjects
   class ComponentRegistration
     # @rbs @reference: Reference
     # @rbs @component_name: String
+    # @rbs @component_key: String | Integer?
     # @rbs @dependencies: Array[String]
+    # @rbs @locals: Hash[String, untyped]
+    # @rbs @refresh_method: String
     # @rbs @instance_id: Integer
     # @rbs @revision: Integer
     # @rbs @refresh_path: String
@@ -14,17 +17,23 @@ module SolidObjects
 
     attr_reader :reference,
       :component_name,
+      :component_key,
       :dependencies,
+      :locals,
+      :refresh_method,
       :instance_id,
       :revision,
       :refresh_path,
       :token
 
-    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
+    # @rbs (reference: Reference, component_name: String, component_key: String | Integer?, dependencies: Array[String], locals: Hash[String, untyped], refresh_method: String, instance_id: Integer, revision: Integer, refresh_path: String, token: String) -> void
     def initialize(
       reference:,
       component_name:,
+      component_key:,
       dependencies:,
+      locals:,
+      refresh_method:,
       instance_id:,
       revision:,
       refresh_path:,
@@ -32,7 +41,10 @@ module SolidObjects
     )
       @reference = reference
       @component_name = component_name
+      @component_key = component_key
       @dependencies = dependencies.freeze
+      @locals = Serialization.readonly_copy(locals)
+      @refresh_method = refresh_method
       @instance_id = instance_id
       @revision = revision
       @refresh_path = refresh_path
@@ -40,30 +52,43 @@ module SolidObjects
     end
 
     class << self
-      # @rbs (reference: Reference, component_name: String, dependencies: Array[String], snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
-      def issue(reference:, component_name:, dependencies:, snapshot:, refresh_path:)
+      # @rbs (reference: Reference, component_name: String, component_key: untyped, dependencies: Array[String], locals: Hash[untyped, untyped], refresh_method: String | Symbol, snapshot: ActorSnapshot, refresh_path: String) -> ComponentRegistration
+      def issue(
+        reference:,
+        component_name:,
+        component_key:,
+        dependencies:,
+        locals:,
+        refresh_method:,
+        snapshot:,
+        refresh_path:
+      )
         token = ComponentToken.generate(
           reference:,
           component_name:,
+          component_key:,
           dependencies:,
+          locals:,
+          refresh_method:,
           instance_id: snapshot.instance_id,
           revision: snapshot.revision,
           refresh_path:
         )
-        new(
-          reference:,
-          component_name:,
-          dependencies:,
-          instance_id: snapshot.instance_id,
-          revision: snapshot.revision,
-          refresh_path:,
-          token:
-        )
+        build(ComponentToken.verify(token), token:)
       end
 
       # @rbs (String) -> ComponentRegistration
       def from_token(token)
         payload = ComponentToken.verify(token)
+        build(payload, token:)
+      rescue UnknownActorType, UnknownComponentDependency => error
+        raise InvalidComponentToken, error.message
+      end
+
+      private
+
+      # @rbs (Hash[String, untyped], token: String) -> ComponentRegistration
+      def build(payload, token:)
         reference = Reference.new(
           actor_type: payload.fetch("actor_type"),
           actor_id: payload.fetch("actor_id")
@@ -73,18 +98,17 @@ module SolidObjects
         new(
           reference:,
           component_name: payload.fetch("component_name"),
+          component_key: payload["component_key"],
           dependencies:,
+          locals: payload.fetch("locals"),
+          refresh_method: payload.fetch("refresh_method"),
           instance_id: payload.fetch("instance_id"),
           revision: payload.fetch("revision"),
           refresh_path: payload.fetch("refresh_path"),
           token:
         )
-      rescue UnknownActorType, UnknownComponentDependency => error
-        raise InvalidComponentToken, error.message
       end
 
-      private
-
       # @rbs (Reference, Array[String]) -> void
       def validate_dependencies!(reference, dependencies)
         actor_class = SolidObjects.registry.fetch(reference.actor_type)
@@ -104,6 +128,27 @@ module SolidObjects
       [ instance_id, revision ]
     end
 
+    # @rbs () -> String
+    def dom_id
+      DomIdentity.component(
+        reference,
+        component_name,
+        key: component_key
+      )
+    end
+
+    # @rbs () -> bool
+    def morph?
+      refresh_method == "morph"
+    end
+
+    # @rbs () -> Hash[String, untyped]
+    def authorization_arguments
+      return locals unless component_key
+
+      locals.merge("component_key" => component_key).freeze
+    end
+
     # @rbs (Integer, Integer) -> String
     def refresh_url(instance_id, revision)
       query = URI.encode_www_form(

data/lib/solid_objects/component_renderer.rb

@@ -3,46 +3,44 @@
 module SolidObjects
   class ComponentRenderer
     # @rbs @snapshot: ActorSnapshot
-    # @rbs @component_name: String
-    # @rbs @dependencies: Array[String]
+    # @rbs @registration: ComponentRegistration
     # @rbs @view_context: untyped
     # @rbs @authorization_context: untyped
 
-    # @rbs (snapshot: ActorSnapshot, component_name: String, dependencies: Array[String], view_context: untyped, authorization_context: untyped) -> void
+    # @rbs (snapshot: ActorSnapshot, registration: ComponentRegistration, view_context: untyped, authorization_context: untyped) -> void
     def initialize(
       snapshot:,
-      component_name:,
-      dependencies:,
+      registration:,
       view_context:,
       authorization_context:
     )
       @snapshot = snapshot
-      @component_name = component_name
-      @dependencies = dependencies
+      @registration = registration
       @view_context = view_context
       @authorization_context = authorization_context
     end
 
     # @rbs () -> untyped
     def call
-      [ component_name, *dependencies ].uniq.each do |authorization_name|
+      [ registration.component_name, *registration.dependencies ].uniq.each do |authorization_name|
         authorize_read!(authorization_name)
       end
       actor = ComponentView.new(
         snapshot:,
-        dependencies:,
+        dependencies: registration.dependencies,
         authorization_context:
       )
       view_context.render(
         partial: default_partial,
-        locals: {
+        locals: registration.locals.transform_keys(&:to_sym).merge(
           actor:,
-          authorization_context:
-        }
+          authorization_context:,
+          component_key: registration.component_key
+        )
       )
     rescue ActionView::MissingTemplate
       raise UnknownComponent,
-        "unknown component #{component_name.inspect} for #{snapshot.reference.actor_type}"
+        "unknown component #{registration.component_name.inspect} for #{snapshot.reference.actor_type}"
     rescue ActionView::Template::Error => error
       raise error.cause if error.cause.is_a?(SolidObjects::Error)
 
@@ -52,8 +50,7 @@ module SolidObjects
     private
 
     attr_reader :snapshot,
-      :component_name,
-      :dependencies,
+      :registration,
       :view_context,
       :authorization_context
 
@@ -63,7 +60,7 @@ module SolidObjects
         actor_type: snapshot.reference.actor_type,
         actor_id: snapshot.reference.actor_id,
         message_name: observable_name,
-        arguments: {},
+        arguments: registration.authorization_arguments,
         authorization_context:
       )
       return if authorized
@@ -76,7 +73,7 @@ module SolidObjects
       actor_name = snapshot.actor_class.name
       raise InvalidActor, "anonymous actors cannot render reactive components" unless actor_name
 
-      "actors/#{actor_name.underscore}/#{component_name}"
+      "actors/#{actor_name.underscore}/#{registration.component_name}"
     end
   end
 end

data/lib/solid_objects/component_subscriptions.rb

@@ -28,7 +28,7 @@ module SolidObjects
           validate_identity!(registration, reference)
         end
       end
-      if registrations.map(&:component_name).uniq.length != registrations.length
+      if registrations.map(&:dom_id).uniq.length != registrations.length
         raise InvalidComponentToken, "duplicate actor component registration"
       end
 
@@ -39,7 +39,7 @@ module SolidObjects
     def initialize(registrations)
       @registrations = registrations
       @revisions = registrations.to_h do |registration|
-        [ registration.component_name, registration.revision_key ]
+        [ registration.dom_id, registration.revision_key ]
       end
     end
 
@@ -51,7 +51,7 @@ module SolidObjects
       registrations.filter_map do |registration|
         next unless registration.dependencies.include?(observable_name)
         next unless newer_revision?(
-          registration.component_name,
+          registration.dom_id,
           instance_id,
           revision
         )
@@ -64,7 +64,7 @@ module SolidObjects
     def reconnect_refreshes(snapshot)
       registrations.filter_map do |registration|
         next unless newer_revision?(
-          registration.component_name,
+          registration.dom_id,
           snapshot.instance_id,
           snapshot.revision
         )
@@ -92,7 +92,7 @@ module SolidObjects
 
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def refresh(registration, instance_id, revision)
-      revisions[registration.component_name] = [ instance_id, revision ]
+      revisions[registration.dom_id] = [ instance_id, revision ]
       TurboStreamRenderer.component_refresh(
         registration,
         instance_id,
@@ -101,8 +101,8 @@ module SolidObjects
     end
 
     # @rbs (String, Integer, Integer) -> bool
-    def newer_revision?(component_name, instance_id, revision)
-      current = revisions.fetch(component_name)
+    def newer_revision?(dom_id, instance_id, revision)
+      current = revisions.fetch(dom_id)
       (current <=> [ instance_id, revision ]) == -1
     end
   end

data/lib/solid_objects/component_token.rb

@@ -7,23 +7,38 @@ module SolidObjects
     PURPOSE = "solid_objects.actor_component"
     MAXIMUM_TOKEN_BYTES = 16_384
     MAXIMUM_DEPENDENCIES = 50
+    MAXIMUM_LOCALS = 50
+    MAXIMUM_COMPONENT_KEY_BYTES = 512
+    REFRESH_METHODS = %w[replace morph].freeze
+    RESERVED_LOCALS = %w[actor authorization_context component_key].freeze
+    RUBY_KEYWORDS = %w[
+      alias and begin break case class def defined do else elsif end ensure
+      false for if in module next nil not or redo rescue retry return self
+      super then true undef unless until when while yield
+    ].freeze
 
     module_function
 
-    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String) -> String
+    # @rbs (reference: Reference, component_name: String, dependencies: Array[String], instance_id: Integer, revision: Integer, refresh_path: String, ?component_key: untyped, ?locals: Hash[untyped, untyped], ?refresh_method: String | Symbol) -> String
     def generate(
       reference:,
       component_name:,
       dependencies:,
       instance_id:,
       revision:,
-      refresh_path:
+      refresh_path:,
+      component_key: nil,
+      locals: {},
+      refresh_method: "replace"
     )
       payload = {
         "actor_type" => reference.actor_type,
         "actor_id" => reference.actor_id,
         "component_name" => component_name,
+        "component_key" => Serialization.dump(component_key),
         "dependencies" => dependencies,
+        "locals" => Serialization.dump(locals),
+        "refresh_method" => refresh_method.to_s,
         "instance_id" => instance_id,
         "revision" => revision,
         "refresh_path" => refresh_path
@@ -41,6 +56,7 @@ module SolidObjects
       end
 
       payload = verifier.verified(token, purpose: PURPOSE)
+      apply_defaults!(payload)
       validate_payload!(payload)
       payload
     rescue ActiveSupport::MessageVerifier::InvalidSignature
@@ -54,6 +70,8 @@ module SolidObjects
           payload["actor_id"].is_a?(String) &&
           payload["component_name"].is_a?(String) &&
           payload["dependencies"].is_a?(Array) &&
+          payload["locals"].is_a?(Hash) &&
+          payload["refresh_method"].is_a?(String) &&
           payload["instance_id"].is_a?(Integer) &&
           payload["revision"].is_a?(Integer) &&
           payload["refresh_path"].is_a?(String)
@@ -61,7 +79,10 @@ module SolidObjects
       end
 
       validate_component_name!(payload.fetch("component_name"))
+      validate_component_key!(payload["component_key"])
       validate_dependencies!(payload.fetch("dependencies"))
+      validate_locals!(payload.fetch("locals"))
+      validate_refresh_method!(payload.fetch("refresh_method"))
       validate_revision!(
         payload.fetch("instance_id"),
         payload.fetch("revision")
@@ -71,6 +92,16 @@ module SolidObjects
     end
     private_class_method :validate_payload!
 
+    # @rbs (Hash[String, untyped]?) -> void
+    def apply_defaults!(payload)
+      return unless payload.is_a?(Hash)
+
+      payload["component_key"] = nil unless payload.key?("component_key")
+      payload["locals"] = {} unless payload.key?("locals")
+      payload["refresh_method"] = "replace" unless payload.key?("refresh_method")
+    end
+    private_class_method :apply_defaults!
+
     # @rbs (String) -> void
     def validate_component_name!(component_name)
       return if component_name.match?(/\A[a-zA-Z0-9_]+\z/)
@@ -79,6 +110,20 @@ module SolidObjects
     end
     private_class_method :validate_component_name!
 
+    # @rbs (untyped) -> void
+    def validate_component_key!(component_key)
+      return if component_key.nil?
+      return if component_key.is_a?(Integer)
+      if component_key.is_a?(String) &&
+          component_key.bytesize.positive? &&
+          component_key.bytesize <= MAXIMUM_COMPONENT_KEY_BYTES
+        return
+      end
+
+      raise InvalidComponentToken, "invalid actor component key"
+    end
+    private_class_method :validate_component_key!
+
     # @rbs (Array[untyped]) -> void
     def validate_dependencies!(dependencies)
       valid = dependencies.any? &&
@@ -91,6 +136,29 @@ module SolidObjects
     end
     private_class_method :validate_dependencies!
 
+    # @rbs (Hash[untyped, untyped]) -> void
+    def validate_locals!(locals)
+      valid = locals.length <= MAXIMUM_LOCALS &&
+        locals.keys.all? do |name|
+          name.is_a?(String) &&
+            name.match?(/\A[a-z_][a-zA-Z0-9_]*\z/) &&
+            !RESERVED_LOCALS.include?(name) &&
+            !RUBY_KEYWORDS.include?(name)
+        end
+      return if valid
+
+      raise InvalidComponentToken, "invalid actor component locals"
+    end
+    private_class_method :validate_locals!
+
+    # @rbs (String) -> void
+    def validate_refresh_method!(refresh_method)
+      return if REFRESH_METHODS.include?(refresh_method)
+
+      raise InvalidComponentToken, "invalid actor component refresh method"
+    end
+    private_class_method :validate_refresh_method!
+
     # @rbs (Integer, Integer) -> void
     def validate_revision!(instance_id, revision)
       return unless instance_id.negative? || revision.negative?

data/lib/solid_objects/dom_identity.rb

@@ -16,9 +16,12 @@ module SolidObjects
       "#{scope(reference)}_observable_#{normalized_name(name)}"
     end
 
-    # @rbs (Reference, Symbol | String) -> String
-    def component(reference, name)
-      "#{scope(reference)}_component_#{normalized_name(name)}"
+    # @rbs (Reference, Symbol | String, ?key: String | Integer?) -> String
+    def component(reference, name, key: nil)
+      identity = "#{scope(reference)}_component_#{normalized_name(name)}"
+      return identity unless key
+
+      "#{identity}_#{component_key_digest(key)}"
     end
 
     # @rbs (Reference) -> String
@@ -34,5 +37,11 @@ module SolidObjects
       name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
     end
     private_class_method :normalized_name
+
+    # @rbs (String | Integer) -> String
+    def component_key_digest(key)
+      Digest::SHA256.hexdigest(JSON.generate(key)).first(24)
+    end
+    private_class_method :component_key_digest
   end
 end

data/lib/solid_objects/engine.rb

@@ -26,6 +26,13 @@ module SolidObjects
       end
     end
 
+    initializer "solid_objects.assets" do |application|
+      next unless application.config.respond_to?(:assets)
+      next unless application.config.assets.respond_to?(:precompile)
+
+      application.config.assets.precompile << "solid_objects/component_refresh.js"
+    end
+
     rake_tasks do
       tasks_path = File.expand_path("../tasks", __dir__)
       Dir[File.join(tasks_path, "**/*.rake")].sort.each { |task| load task }

data/lib/solid_objects/turbo_stream_renderer.rb

@@ -40,15 +40,14 @@ module SolidObjects
 
     # @rbs (ComponentRegistration, Integer, Integer) -> String
     def component_refresh(registration, instance_id, revision)
-      target = DomIdentity.component(
-        registration.reference,
-        registration.component_name
-      )
+      return morph_component_refresh(registration, instance_id, revision) if registration.morph?
+
+      target = registration.dom_id
       source = ERB::Util.html_escape(
         registration.refresh_url(instance_id, revision)
       )
       revision_value = "#{instance_id}:#{revision}"
-      %(<turbo-stream action="replace" target="#{target}"><template><turbo-frame id="#{target}" src="#{source}" data-solid-objects-revision="#{revision_value}"></turbo-frame></template></turbo-stream>)
+      %(<turbo-stream action="replace" target="#{target}"><template><turbo-frame id="#{target}" src="#{source}" data-solid-objects-revision="#{revision_value}" data-solid-objects-refresh="replace"></turbo-frame></template></turbo-stream>)
     end
 
     # @rbs (String) -> Hash[String, untyped]?
@@ -75,5 +74,15 @@ module SolidObjects
       JSON.generate(value)
     end
     private_class_method :display_value
+
+    # @rbs (ComponentRegistration, Integer, Integer) -> String
+    def morph_component_refresh(registration, instance_id, revision)
+      source = ERB::Util.html_escape(
+        registration.refresh_url(instance_id, revision)
+      )
+      scope = DomIdentity.scope(registration.reference)
+      %(<turbo-stream action="append" target="#{scope}"><template><solid-objects-refresh data-target="#{registration.dom_id}" data-source="#{source}" data-refresh-method="morph"></solid-objects-refresh></template></turbo-stream>)
+    end
+    private_class_method :morph_component_refresh
   end
 end

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

data/sig/generated/lib/solid_objects/actor_view.rbs

@@ -22,8 +22,8 @@ module SolidObjects
     # @rbs (Symbol | String) -> untyped
     def value: (Symbol | String) -> untyped
 
-    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?) -> untyped
-    def component: (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?) -> untyped
+    # @rbs (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol) -> untyped
+    def component: (Symbol | String, ?observes: Symbol | String | Array[Symbol | String]?, ?partial: String?, ?key: untyped, ?locals: Hash[untyped, untyped], ?refresh: String | Symbol) -> untyped
 
     # @rbs () -> Array[String]
     def component_tokens: () -> Array[String]
@@ -31,6 +31,9 @@ module SolidObjects
     # @rbs () -> Array[String]
     def scalar_observable_names: () -> Array[String]
 
+    # @rbs () -> bool
+    def morph_components?: () -> bool
+
     # @rbs () -> State
     def state: () -> State
 
@@ -73,8 +76,11 @@ module SolidObjects
     # @rbs (Array[String]) -> void
     def validate_dependencies!: (Array[String]) -> void
 
-    # @rbs (String) -> void
-    def ensure_unique_component!: (String) -> void
+    # @rbs (ComponentRegistration) -> void
+    def ensure_unique_component!: (ComponentRegistration) -> void
+
+    # @rbs (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol) -> void
+    def validate_static_options!: (key: untyped, locals: Hash[untyped, untyped], refresh: String | Symbol) -> void
 
     # @rbs () -> Proc | ComponentPathResolver
     def component_path_resolver: () -> Proc