reactionview 0.4.1 → 0.6.0

data/lib/generators/reactionview/install_generator.rb

@@ -32,20 +32,55 @@ module ReActionView
             # How to handle templates that come from gems (:fallback, :skip, or :compile), defaults to :fallback
             # config.external_template_mode = :skip
 
-            # Add custom transform visitors to process templates before compilation
-            # config.transform_visitors = [
-            #   Herb::Visitor::new
-            # ]
+            # Measure what a page does while it renders, and show it in the dev tools.
+            # Follows development unless you say otherwise, and each measurement can be turned off.
+            # config.instrumentation.enabled = Rails.env.development?
+            # config.instrumentation.sql_queries = false
+            # config.instrumentation.render_times = false
+            # config.instrumentation.translations = false
+
+            # Add visitors to the compile. Place them with `insert_before` and `insert_after`.
+            # config.engine.visitors.use(Herb::Visitor.new)
+
+            # Parser options for every compile, merged over the ones in .herb.yml
+            # config.engine.parser_options = { strict_locals: true }
           end
         RUBY
       end
 
+      def add_javascript
+        if File.exist?("config/importmap.rb")
+          say "The gem pins the reactionview client runtime in your importmap, nothing to add there.", :green
+        elsif File.exist?("package.json")
+          say "Add the client runtime to your bundle: #{javascript_install_command}", :yellow
+        end
+
+        return unless File.exist?("app/javascript/application.js")
+
+        say "Importing reactionview in app/javascript/application.js...", :green
+
+        append_to_file "app/javascript/application.js", %(import "reactionview"\n)
+      end
+
+      def javascript_install_command
+        if File.exist?("bun.lock") || File.exist?("bun.lockb")
+          "bun add reactionview"
+        elsif File.exist?("pnpm-lock.yaml")
+          "pnpm add reactionview"
+        elsif File.exist?("package-lock.json")
+          "npm install reactionview"
+        else
+          "yarn add reactionview"
+        end
+      end
+
       def show_installation_complete
         say "\nReActionView has been successfully installed! 🎉", :green
         say "\nNext steps:", :blue
         say "  1. Review config/initializers/reactionview.rb"
         say "  2. Enable `config.intercept_erb = true` to process all `*.html.erb` templates using `Herb::Engine`."
         say "  3. Create `*.html.herb` templates for explicit Herb usage."
+        say "  4. Make sure `import \"reactionview\"` runs in your JavaScript entry point, see https://reactionview.dev/javascript"
 
         say "\nLearn more:", :yellow
         say "  GitHub:  https://github.com/marcoroth/reactionview"

data/lib/reactionview/asset_manifest.rb

@@ -46,7 +46,7 @@ module ReActionView
 
     def explanation
       <<~MESSAGE
-        ReActionView's dev tools assets are missing from your precompiled assets.
+        ReActionView's JavaScript assets are missing from your precompiled assets.
         #{status}
 
         To fix this, delete the precompiled assets:

data/lib/reactionview/config.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
+require "herb"
+require "herb/visitor/stack"
+
 module ReActionView
   class Config
+    EXTERNAL_TEMPLATE_MODES = %i[fallback skip compile].freeze
+    SLOT_MODES = %i[server client].freeze
+
     attr_accessor :intercept_erb
     attr_accessor :debug_mode
-    attr_accessor :transform_visitors
 
-    EXTERNAL_TEMPLATE_MODES = %i[fallback skip compile].freeze
+    attr_reader :slots
 
+    attr_writer :dev_server
     attr_writer :dev_server_port
     attr_writer :project_path
     attr_writer :validation_mode
@@ -15,10 +21,72 @@ module ReActionView
     def initialize
       @intercept_erb = false
       @debug_mode = nil
+      @dev_server = nil
       @dev_server_port = nil
       @external_template_mode = nil
-      @transform_visitors = []
+      @engine = nil
       @project_path = nil
+      @slots = false
+      @instrumentation = nil
+    end
+
+    def engine
+      @engine ||= EngineOptions.new
+    end
+
+    def transform_visitors
+      ReActionView.deprecator.warn("`config.transform_visitors` is deprecated. Read the visitors from `config.engine.visitors` instead.")
+
+      engine.visitors
+    end
+
+    def transform_visitors=(visitors)
+      ReActionView.deprecator.warn(
+        "`config.transform_visitors=` is deprecated. Add visitors with `config.engine.visitors.use(visitor)` instead, " \
+        "and place them with `insert_before` and `insert_after`."
+      )
+
+      engine.visitors.replace(Array(visitors))
+    end
+
+    class EngineOptions
+      attr_reader :visitors
+      attr_reader :parser_options
+
+      def initialize
+        @visitors = ::Herb::Visitor::Stack.new
+        @parser_options = {}
+      end
+
+      def parser_options=(options)
+        raise ArgumentError, "parser_options must be a Hash of parser options, got #{options.inspect}" unless options.is_a?(Hash)
+
+        @parser_options = options.transform_keys(&:to_sym)
+      end
+    end
+
+    def dev_server_enabled?
+      return @dev_server unless @dev_server.nil?
+
+      true
+    end
+
+    def slots=(value)
+      unless [nil, true, false].include?(value) || SLOT_MODES.include?(value)
+        raise ArgumentError, "slots must be true, false, or one of #{SLOT_MODES.inspect}, got #{value.inspect}"
+      end
+
+      @slots = value
+    end
+
+    def slot_mode_for(source)
+      ::Herb::Engine::Slots::Visitor.directive_mode(source) || default_slot_mode
+    end
+
+    def default_slot_mode
+      return nil unless slots
+
+      slots == true ? :server : slots
     end
 
     def external_template_mode
@@ -61,11 +129,38 @@ module ReActionView
       development?
     end
 
+    def instrumentation
+      @instrumentation ||= InstrumentationOptions.new(enabled: development?)
+    end
+
+    class InstrumentationOptions < ::ActiveSupport::OrderedOptions
+      BUILT_INS = [:sql_queries, :render_times, :translations].freeze
+      KEYS = ([:enabled] + BUILT_INS).freeze
+
+      def initialize(enabled:)
+        super()
+
+        merge!(enabled: enabled, **BUILT_INS.to_h { |key| [key, true] })
+      end
+
+      def []=(key, value)
+        raise ArgumentError, "unknown instrumentation option #{key.inspect}, expected one of #{KEYS.inspect}" unless KEYS.include?(key.to_sym)
+
+        super
+      end
+
+      def measuring?(built_in)
+        !!self[:enabled] && !!self[built_in]
+      end
+    end
+
     def dev_server_port
       return @dev_server_port if @dev_server_port
       return nil unless development?
 
-      ::Herb.dev_server_port(Rails.root.to_s)
+      require "herb/dev/server_entry"
+
+      ::Herb::Dev::ServerEntry.port_for(Rails.root.to_s)
     end
   end
 

data/lib/reactionview/importmap.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+pin "reactionview", to: "reactionview.esm.js", preload: true

data/lib/reactionview/instrumentation.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module ReActionView
+  # What a page did while it rendered, filed against the tags that did it.
+  #
+  # `Herb::Engine::InstrumentationVisitor` says which tag is rendering at any moment. It does not
+  # say what is worth noticing while one is, because that is not the engine's business: an
+  # application knows what it cares about, and Rails already announces most of it through
+  # `ActiveSupport::Notifications`.
+  #
+  # These are the three worth having in every application, so they are here rather than in each one:
+  # the queries a tag ran, what a render cost, and what a translation rendered. Each is a subscriber
+  # that observes, plus a measurement that says how to read what was observed. Either half can be
+  # turned off on its own.
+  #
+  #     ReActionView.configure do |config|
+  #       config.instrumentation = true
+  #       config.instrumentation.sql_queries = false
+  #     end
+  #
+  module Instrumentation
+    TRANSLATION_TAGS = [/\At\(/, /\Atranslate\(/].freeze #: Array[Regexp]
+    IGNORED_QUERIES = ["SCHEMA", "TRANSACTION"].freeze #: Array[String]
+    RENDER_EVENTS = %w[
+      render_partial.action_view
+      render_collection.action_view
+      render_template.action_view
+    ].freeze #: Array[String]
+
+    def self.available?
+      require "herb/engine/runtime/session"
+
+      ::Herb::Engine::Runtime::Session.respond_to?(:measurement)
+    rescue LoadError
+      false
+    end
+
+    def self.install!(config = ReActionView.config)
+      return unless config.instrumentation.enabled
+      return unless available?
+      return if installed?
+
+      @installed = true
+
+      install_sql_queries if config.instrumentation.measuring?(:sql_queries)
+      install_render_times if config.instrumentation.measuring?(:render_times)
+      install_translations if config.instrumentation.measuring?(:translations)
+
+      config.engine.visitors.use(visitor(config))
+
+      nil
+    end
+
+    def self.installed?
+      @installed == true
+    end
+
+    def self.reset!
+      subscriptions.each { |subscription| ::ActiveSupport::Notifications.unsubscribe(subscription) }
+      subscriptions.clear
+
+      @installed = false
+    end
+
+    def self.subscriptions
+      @subscriptions ||= []
+    end
+
+    def self.visitor(config = ReActionView.config)
+      require "herb/engine/visitors/instrumentation_visitor"
+
+      ::Herb::Engine::InstrumentationVisitor.new(capture_output: config.instrumentation.measuring?(:translations) ? TRANSLATION_TAGS : nil)
+    end
+
+    def self.install_sql_queries
+      subscriptions << ::ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+        next if payload[:cached]
+        next if IGNORED_QUERIES.include?(payload[:name])
+
+        session.observe(:queries, payload[:sql])
+      end
+
+      session.measurement(
+        :queries,
+        origin: "Herb Engine (Runtime)",
+        code: "sql-queries",
+        description: ->(queries) { "This ERB tag ran #{queries.size} SQL #{"query".pluralize(queries.size)} while the page rendered." }
+      ) { |queries| "#{queries.size} SQL #{"query".pluralize(queries.size)}" }
+    end
+
+    def self.install_render_times
+      RENDER_EVENTS.each do |event|
+        subscriptions << ::ActiveSupport::Notifications.subscribe(event) do |notification|
+          session.observe(:render, {
+            duration: notification.duration.round(2),
+            gc: notification.respond_to?(:gc_time) ? notification.gc_time.round(2) : 0.0,
+            allocations: notification.respond_to?(:allocations) ? notification.allocations : 0,
+            cached: notification.payload[:cache_hit] ? true : nil,
+          }.compact)
+        end
+      end
+
+      session.measurement(:render, origin: "Herb Engine (Runtime)", code: "render-time", description: method(:render_description)) do |renders|
+        duration = renders.sum { |render| render[:duration] }.round(1)
+
+        renders.size > 1 ? "#{duration} ms over #{renders.size} renders" : "#{duration} ms"
+      end
+    end
+
+    def self.install_translations
+      session.measurement(
+        :output,
+        origin: "Herb Engine (Runtime)",
+        code: "rendered-output",
+        kind: :value,
+        per: :position,
+        description: ->(values) { "This ERB tag rendered #{values.last.to_s.strip.inspect} when the page was last built." }
+      ) { |values| values.last.to_s }
+    end
+
+    def self.render_description(renders)
+      duration = renders.sum { |render| render[:duration] }
+      gc = renders.sum { |render| render[:gc] }
+      allocations = renders.sum { |render| render[:allocations] }
+      cached = renders.count { |render| render[:cached] }
+
+      parts = ["taking #{duration.round(1)} ms"]
+      parts << "#{gc.round(1)} ms of it in GC" if gc.positive?
+      parts << "allocating #{allocations.to_fs(:delimited)} objects" if allocations.positive?
+      parts << "#{cached} served from cache" if cached.positive?
+
+      if renders.size > 1
+        "This tag rendered #{renders.size} times, #{parts.to_sentence}. Slowest was #{renders.map { |render| render[:duration] }.max.round(1)} ms."
+      else
+        "This tag rendered once, #{parts.to_sentence}."
+      end
+    end
+
+    def self.session
+      ::Herb::Engine::Runtime::Session
+    end
+  end
+end

data/lib/reactionview/railtie.rb

@@ -10,17 +10,31 @@ module ReActionView
     # end
     #
     PRECOMPILE_ASSETS = %w[
+      reactionview.esm.js
       reactionview-dev-tools.esm.js
       reactionview-dev-tools.umd.js
     ].freeze
 
+    def self.gem_root
+      Gem::Specification.find_by_name("reactionview").gem_dir
+    end
+
     initializer "reactionview.assets", after: :load_config_initializers do |app|
-      if ReActionView.config.debug_mode_enabled? && app.config.respond_to?(:assets)
-        gem_root = Gem::Specification.find_by_name("reactionview").gem_dir
+      next unless app.config.respond_to?(:assets)
 
-        app.config.assets.paths << File.join(gem_root, "app", "assets", "javascripts")
-        app.config.assets.precompile += PRECOMPILE_ASSETS
-      end
+      app.config.assets.paths << File.join(ReActionView::Railtie.gem_root, "app", "assets", "javascripts")
+      app.config.assets.precompile += PRECOMPILE_ASSETS
+    end
+
+    initializer "reactionview.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << File.join(ReActionView::Railtie.gem_root, "lib", "reactionview", "importmap.rb")
+      app.config.importmap.cache_sweepers << File.join(ReActionView::Railtie.gem_root, "app", "assets", "javascripts")
+    end
+
+    initializer "reactionview.deprecator" do |app|
+      app.deprecators[:reactionview] = ReActionView.deprecator if app.respond_to?(:deprecators)
     end
 
     initializer "reactionview.asset_manifest_check" do |app|
@@ -31,6 +45,104 @@ module ReActionView
       app.middleware.use ReActionView::Middleware::AssetManifestCheck
     end
 
+    initializer "reactionview.diagnostics" do |app|
+      next unless ReActionView.config.debug_mode_enabled? || ReActionView.config.validation_mode == :overlay || ReActionView.config.slots
+
+      require "herb/engine/runtime/middleware"
+
+      app.middleware.use ::Herb::Engine::Runtime::Middleware
+    end
+
+    initializer "reactionview.instrumentation", after: :load_config_initializers do |_app|
+      next unless ReActionView.config.instrumentation.enabled
+
+      require_relative "instrumentation"
+
+      ReActionView::Instrumentation.install!
+    end
+
+    initializer "reactionview.error_page", after: :load_config_initializers do |app|
+      next unless ReActionView.config.development?
+
+      require "herb/engine/runtime/error_page"
+
+      app.middleware.use(
+        ::Herb::Engine::Runtime::ErrorPage,
+        dev_tools: -> { ReActionView::Railtie.dev_tools_module_path },
+        dev_server_port: -> { ReActionView.config.dev_server_port }
+      )
+    end
+
+    def self.dev_tools_module_path
+      ActionController::Base.helpers.asset_path("reactionview-dev-tools.esm.js")
+    end
+
+    initializer "reactionview.slots" do |app|
+      next unless ReActionView.config.slots
+
+      Mime::Type.register ReActionView::Slots::MIME_TYPE, ReActionView::Slots::FORMAT unless Mime[ReActionView::Slots::FORMAT]
+
+      ActiveSupport.on_load(:action_view) do
+        include ReActionView::Slots::StateOverridesHelper
+      end
+
+      ActiveSupport.on_load(:action_controller_base) do
+        include ReActionView::Slots::StateOverridesHelper
+        prepend ReActionView::Slots::Rendering
+
+        app.config.paths["app/views"].existent.each do |path|
+          prepend_view_path ReActionView::Slots::Resolver.new(path)
+        end
+      end
+    end
+
+    initializer "reactionview.slots.reloading" do |app|
+      next unless ReActionView.config.slots
+
+      views = app.config.paths["app/views"].existent
+
+      next if views.empty?
+
+      watcher = app.config.file_watcher.new([], views.index_with { %w[erb] }) do
+        ReActionView::Slots.reset_dependencies!
+      end
+
+      app.reloaders << watcher
+      app.reloader.to_run { watcher.execute_if_updated }
+    end
+
+    initializer "reactionview.slots.dev_server", after: :load_config_initializers do |app|
+      next unless ReActionView.config.slots
+      next unless ReActionView.config.development?
+      next unless ReActionView.config.dev_server_enabled?
+
+      begin
+        require "herb/dev"
+      rescue LoadError
+        next
+      end
+
+      ::Herb::Dev.compiler = ReActionView::Slots::DevCompiler.new
+
+      view_paths = app.config.paths["app/views"].existent
+
+      app.server { Railtie.boot_dev_server(view_paths: view_paths) }
+    end
+
+    def self.boot_dev_server(view_paths: nil)
+      embedded = ::Herb::Dev.boot(
+        ReActionView.config.project_path,
+        watch_paths: view_paths,
+        logger: ->(message) { Rails.logger.info("[Herb Dev Server] #{message}") }
+      )
+
+      if embedded
+        $stdout.puts "* Herb Dev Server: ws://localhost:#{embedded.server.port} (embedded)"
+      else
+        $stdout.puts "* Herb Dev Server: not started, see the log"
+      end
+    end
+
     initializer "reactionview.register_herb_handler" do
       ActiveSupport.on_load(:action_view) do
         ActionView::Template.register_template_handler :herb, ReActionView::Template::Handlers::Herb

data/lib/reactionview/slots/dev_compiler.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ReActionView
+  module Slots
+    # Compiles one template for the Herb dev server, the way the application would.
+    #
+    # The dev server's watcher calls this from its own thread whenever a template changes, so
+    # the compile runs inside the Rails executor for autoload and reloader safety. A raise is
+    # left to the caller, which turns it into diagnostics instead of crashing the thread.
+    #
+    class DevCompiler
+      def call(source, relative_path)
+        absolute = File.expand_path(relative_path, ReActionView.config.project_path)
+
+        result = Rails.application.executor.wrap do
+          ReActionView::Template::Handlers::Herb.compile_for_schema(source, absolute)
+        end
+
+        ReActionView::Slots.reset_dependencies!
+
+        result
+      end
+    end
+  end
+end

data/lib/reactionview/slots/rendering.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ReActionView
+  module Slots
+    module Rendering
+      BODY_END_TAG = "</body>"
+      BLOCK_HEADER = "Herb-Block"
+
+      def _normalize_options(options)
+        super
+
+        options[:layout] = false if slots_request?
+
+        options
+      end
+
+      def render_to_body(options = {})
+        protect_steered_response
+
+        if (block = scoped_block_index)
+          begin
+            return ::JSON.generate(render_scoped_block(block, options))
+          rescue ::StandardError => e
+            raise unless ReActionView.config.development?
+
+            return render_slots_error(e)
+          end
+        end
+
+        begin
+          rendered = super
+        rescue ::StandardError => e
+          raise unless slots_request? && ReActionView.config.development?
+
+          return render_slots_error(e)
+        end
+
+        return ::JSON.generate(merge_schema(rendered, options)) if rendered.is_a?(::Hash)
+
+        deliver_slot_dependencies(rendered, options)
+
+        rendered
+      end
+
+      private
+
+      def protect_steered_response
+        return unless slots_request?
+        return unless request.respond_to?(:headers) && respond_to?(:response) && response
+        return if request.headers[StateOverrides::HEADER].nil?
+
+        response.headers["Cache-Control"] = "no-store"
+      end
+
+      def render_slots_error(error)
+        self.status = 500
+
+        cause = error.cause || error
+        template = error.respond_to?(:template) && error.template
+
+        entry = {
+          class: cause.class.name,
+          message: cause.message,
+          template: template.respond_to?(:short_identifier) ? template.short_identifier : nil,
+          backtrace: cleaned_backtrace(cause),
+        }
+
+        ::JSON.generate({ error: entry })
+      end
+
+      def cleaned_backtrace(cause)
+        raw = cause.backtrace || []
+        cleaned = ::Rails.backtrace_cleaner.clean(raw)
+
+        (cleaned.empty? ? raw : cleaned).first(5)
+      end
+
+      def merge_schema(rendered, options)
+        return rendered unless request&.headers&.[]("Herb-Schema").present?
+
+        entry = entry_point_for(options)
+
+        return rendered unless entry
+
+        schema = ReActionView::Template::Handlers::Herb.compile_for_schema(::File.read(entry), entry)
+
+        rendered.merge(schema: {
+          mode: schema.mode,
+          version: schema.version,
+          manifest: schema.manifest,
+          static_markup: schema.static_markup,
+          statics: schema.statics,
+        })
+      rescue ::StandardError => e
+        logger = defined?(::Rails) && ::Rails.logger
+        logger&.debug { "ReActionView could not build the schema envelope: #{e.class}: #{e.message}" }
+
+        rendered
+      end
+
+      def scoped_block_index
+        return nil unless slots_request?
+
+        value = request.headers[BLOCK_HEADER]
+
+        value&.match?(/\A\d+\z/) ? Integer(value, 10) : nil
+      end
+
+      def render_scoped_block(index, options)
+        entry = entry_point_for(options)
+
+        raise ::ArgumentError, "a scoped block request found no entry template" unless entry
+
+        program = ReActionView::Slots.block_program(entry, index)
+
+        raise ::ArgumentError, "the entry template compiles no slots, so it holds no block \#{index}" unless program
+
+        view_context.instance_eval(program, entry)
+      end
+
+      def slots_request?
+        respond_to?(:request) && request&.format&.symbol == Slots::FORMAT
+      end
+
+      def deliver_slot_dependencies(body, options)
+        return if slots_request?
+        return unless body.is_a?(::String)
+        return unless body.include?(Slots::REGION_MARKER)
+
+        entry = entry_point_for(options)
+
+        return unless entry
+
+        Slots.dependencies.deliver(entry)
+      rescue ::StandardError => e
+        logger = defined?(::Rails) && ::Rails.logger
+        logger&.debug { "ReActionView could not build the slot dependency map: #{e.class}: #{e.message}" }
+
+        nil
+      end
+
+      def entry_point_for(options)
+        name = options[:template] || (respond_to?(:action_name) ? action_name : nil)
+
+        return nil unless name
+
+        template = lookup_context.find(name.to_s, options[:prefixes] || _prefixes, false)
+
+        template&.identifier
+      rescue ::ActionView::MissingTemplate
+        nil
+      end
+    end
+  end
+end