proscenium 0.16.0

data/lib/proscenium/middleware/esbuild.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class Middleware
+    class Esbuild < Base
+      class CompileError < Base::CompileError
+        def initialize(args)
+          detail = args[:detail]
+          detail = ActiveSupport::HashWithIndifferentAccess.new(Oj.load(detail, mode: :strict))
+
+          args[:detail] = if detail[:location]
+                            "#{detail[:text]} in #{detail[:location][:file]}:" +
+                              detail[:location][:line].to_s
+                          else
+                            detail[:text]
+                          end
+
+          super
+        end
+      end
+
+      def attempt
+        render_response Builder.build_to_string(path_to_build, root: Rails.root.to_s,
+                                                               base_url: @request.base_url)
+      rescue Builder::CompileError => e
+        raise self.class::CompileError, { file: @request.fullpath, detail: e.message }, caller
+      end
+    end
+  end
+end

data/lib/proscenium/middleware/runtime.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class Middleware
+    class Runtime < Esbuild
+      private
+
+      def real_path
+        @real_path ||= Pathname.new(@request.path.sub(%r{^/@proscenium},
+                                                      '/lib/proscenium/libs')).to_s
+      end
+
+      def root_for_readable
+        Proscenium::Railtie.root
+      end
+    end
+  end
+end

data/lib/proscenium/middleware/url.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class Middleware
+    # Handles requests for URL encoded URL's.
+    class Url < Esbuild
+      private
+
+      # @override [Esbuild] It's a URL, so always assume it is renderable (we won't actually know
+      #   until it's downloaded).
+      def renderable?
+        true
+      end
+    end
+  end
+end

data/lib/proscenium/middleware.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class Middleware
+    extend ActiveSupport::Autoload
+
+    # Error when the build command fails.
+    class BuildError < StandardError; end
+
+    autoload :Base
+    autoload :Esbuild
+    autoload :Engines
+    autoload :Runtime
+    autoload :Url
+
+    def initialize(app)
+      @app = app
+
+      chunks_path = Rails.public_path.join('assets').to_s
+      headers = Rails.application.config.public_file_server.headers || {}
+      @chunk_handler = ::ActionDispatch::FileHandler.new(chunks_path, headers:)
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+
+      return @app.call(env) if !request.get? && !request.head?
+      return @chunk_handler.attempt(request.env) if request.path.match?(%r{^/_asset_chunks/})
+
+      attempt(request) || @app.call(env)
+    end
+
+    private
+
+    def attempt(request)
+      return unless (type = find_type(request))
+
+      # file_handler.attempt(request.env) || type.attempt(request)
+
+      type.attempt request
+    end
+
+    def find_type(request)
+      return Url if request.path.match?(%r{^/https?%3A%2F%2F})
+      return Runtime if request.path.match?(%r{^/@proscenium/})
+      return Esbuild if Pathname.new(request.path).fnmatch?(app_path_glob, File::FNM_EXTGLOB)
+
+      pathname = Pathname.new(request.path)
+      Engines if pathname.fnmatch?(ui_path_glob, File::FNM_EXTGLOB) ||
+                 pathname.fnmatch?(engines_path_glob, File::FNM_EXTGLOB)
+    end
+
+    def app_path_glob
+      "/{#{Proscenium::ALLOWED_DIRECTORIES}}/**.{#{file_extensions}}"
+    end
+
+    def engines_path_glob
+      names = Proscenium.config.engines.map(&:engine_name)
+      "/{#{names.join(',')}}/{#{Proscenium::ALLOWED_DIRECTORIES}}/**.{#{file_extensions}}"
+    end
+
+    def ui_path_glob
+      "/proscenium/ui/**.{#{file_extensions}}"
+    end
+
+    def file_extensions
+      @file_extensions ||= FILE_EXTENSIONS.join(',')
+    end
+
+    # TODO: handle precompiled assets
+    # def file_handler
+    #   ::ActionDispatch::FileHandler.new Rails.public_path.join('assets').to_s,
+    #                                     headers: { 'X-Proscenium-Middleware' => 'precompiled' }
+    # end
+  end
+end

data/lib/proscenium/monkey.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Proscenium
+  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  module Monkey
+    module TemplateRenderer
+      private
+
+      def render_template(view, template, layout_name, locals) # rubocop:disable Metrics/*
+        result = super
+        return result if !view.controller || !Proscenium.config.side_load
+
+        renderable = template.instance_variable_get(:@renderable)
+
+        to_sideload = if Object.const_defined?(:ViewComponent) &&
+                         template.is_a?(ActionView::Template::Renderable) &&
+                         renderable.class < ::ViewComponent::Base &&
+                         renderable.class.format == :html
+                        renderable
+                      elsif template.respond_to?(:virtual_path) &&
+                            template.respond_to?(:type) && template.type == :html
+                        template
+                      end
+        if to_sideload
+          options = view.controller.sideload_assets_options
+          layout = find_layout(layout_name, locals.keys, [formats.first])
+          sideload_template_assets layout, view.controller, options if layout
+          sideload_template_assets to_sideload, view.controller, options
+        end
+
+        result
+      end
+
+      def sideload_template_assets(tpl, controller, options)
+        options = {} if options.nil?
+        options = { js: options, css: options } unless options.is_a?(Hash)
+
+        if tpl.instance_variable_defined?(:@sideload_assets_options)
+          tpl_options = tpl.instance_variable_get(:@sideload_assets_options)
+          options = case tpl_options
+                    when Hash then options.deep_merge(tpl_options)
+                    else
+                      { js: tpl_options, css: tpl_options }
+                    end
+        end
+
+        %i[css js].each do |k|
+          options[k] = controller.instance_eval(&options[k]) if options[k].is_a?(Proc)
+        end
+
+        Importer.sideload "app/views/#{tpl.virtual_path}", **options
+      end
+    end
+
+    module PartialRenderer
+      private
+
+      def render_partial_template(view, locals, template, layout, block)
+        result = super
+
+        return result if !view.controller || !Proscenium.config.side_load
+
+        if template.respond_to?(:virtual_path) &&
+           template.respond_to?(:type) && template.type == :html
+          options = view.controller.sideload_assets_options
+          sideload_template_assets layout, options if layout
+          sideload_template_assets template, options
+        end
+
+        result
+      end
+
+      def sideload_template_assets(tpl, options)
+        options = {} if options.nil?
+        options = { js: options, css: options } unless options.is_a?(Hash)
+
+        if tpl.instance_variable_defined?(:@sideload_assets_options)
+          tpl_options = tpl.instance_variable_get(:@sideload_assets_options)
+          options = if tpl_options.is_a?(Hash)
+                      options.deep_merge tpl_options
+                    else
+                      { js: tpl_options, css: tpl_options }
+                    end
+        end
+
+        %i[css js].each do |k|
+          options[k] = controller.instance_eval(&options[k]) if options[k].is_a?(Proc)
+        end
+
+        Importer.sideload "app/views/#{tpl.virtual_path}", **options
+      end
+    end
+  end
+  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+end

data/lib/proscenium/phlex/asset_inclusions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Proscenium::Phlex::AssetInclusions
+  def include_stylesheets
+    comment { '[PROSCENIUM_STYLESHEETS]' }
+  end
+
+  def include_javascripts
+    comment { '[PROSCENIUM_LAZY_SCRIPTS]' }
+    comment { '[PROSCENIUM_JAVASCRIPTS]' }
+  end
+
+  def include_assets
+    include_stylesheets
+    include_javascripts
+  end
+end

data/lib/proscenium/phlex/css_modules.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module Phlex::CssModules
+    include Proscenium::CssModule
+
+    def self.included(base)
+      base.extend CssModule::Path
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Set of CSS module paths that have been resolved after being transformed from 'class' HTML
+      # attributes. See #process_attributes. This is here because Phlex caches attributes. Which
+      # means while the CSS class names will be transformed, any resolved paths will be lost in
+      # subsequent requests.
+      attr_accessor :resolved_css_module_paths
+    end
+
+    def before_template
+      self.class.resolved_css_module_paths ||= Concurrent::Set.new
+      super
+    end
+
+    def after_template
+      self.class.resolved_css_module_paths.each do |path|
+        Proscenium::Importer.import path
+      end
+
+      super
+    end
+
+    # Resolve and side load any CSS modules in the "class" attributes, where a CSS module is a class
+    # name beginning with a `@`. The class name is resolved to a CSS module name based on the file
+    # system path of the Phlex class, and any CSS file is side loaded.
+    #
+    # For example, the following will side load the CSS module file at
+    # app/components/user/component.module.css, and add the CSS Module name `user_name` to the
+    # <div>.
+    #
+    #   # app/components/user/component.rb
+    #   class User::Component < Proscenium::Phlex
+    #     def view_template
+    #       div class: :@user_name do
+    #         'Joel Moss'
+    #       end
+    #     end
+    #   end
+    #
+    # Additionally, any class name containing a `/` is resolved as a CSS module path. Allowing you
+    # to use the same syntax as a CSS module, but without the need to manually import the CSS file.
+    #
+    # For example, the following will side load the CSS module file at /lib/users.module.css, and
+    # add the CSS Module name `name` to the <div>.
+    #
+    #   class User::Component < Proscenium::Phlex
+    #     def view_template
+    #       div class: '/lib/users@name' do
+    #         'Joel Moss'
+    #       end
+    #     end
+    #   end
+    #
+    # @raise [Proscenium::CssModule::Resolver::NotFound] If a CSS module file is not found for the
+    #   Phlex class file path.
+    def process_attributes(**attributes)
+      if attributes.key?(:class) && (attributes[:class] = tokens(attributes[:class])).include?('@')
+        names = attributes[:class].is_a?(Array) ? attributes[:class] : attributes[:class].split
+
+        attributes[:class] = cssm.class_names(*names).map do |name, path|
+          self.class.resolved_css_module_paths << path if path
+          name
+        end
+      end
+
+      attributes
+    end
+  end
+end

data/lib/proscenium/phlex/react_component.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Proscenium
+  # Renders a <div> for use with React components, with data attributes specifying the component
+  # path and props.
+  #
+  # If a block is given, it will be yielded within the div, allowing for a custom "loading" UI. If
+  # no block is given, then a "loading..." text will be rendered. It is intended that the component
+  # is mounted to this div, and the loading UI will then be replaced with the component's rendered
+  # output.
+  #
+  # You can pass props to the component in the `:props` keyword argument.
+  class Phlex::ReactComponent < Phlex
+    self.abstract_class = true
+
+    include ReactComponentable
+
+    # Override this to provide your own loading UI.
+    #
+    # @example
+    #   def view_template(**attributes, &block)
+    #     super do
+    #       'Look at me! I am loading now...'
+    #     end
+    #   end
+    #
+    # @yield the given block to a `div` within the top level component div.
+    def view_template(**attributes, &)
+      send(root_tag, **{ data: data_attributes }.deep_merge(attributes), &)
+    end
+  end
+end

data/lib/proscenium/phlex.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'phlex-rails'
+
+module Proscenium
+  class Phlex < ::Phlex::HTML
+    extend ActiveSupport::Autoload
+
+    autoload :CssModules
+    autoload :ReactComponent
+    autoload :AssetInclusions
+
+    include Proscenium::SourcePath
+    include CssModules
+    include AssetInclusions
+
+    module Sideload
+      def before_template
+        Proscenium::SideLoad.sideload_inheritance_chain self,
+                                                        helpers.controller.sideload_assets_options
+
+        super
+      end
+    end
+
+    class_attribute :sideload_assets_options
+
+    class << self
+      attr_accessor :abstract_class
+
+      def inherited(child)
+        child.prepend Sideload
+
+        super
+      end
+
+      def sideload_assets(value)
+        self.sideload_assets_options = value
+      end
+    end
+  end
+end

data/lib/proscenium/railtie.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'rails'
+require 'proscenium/log_subscriber'
+
+ENV['RAILS_ENV'] = Rails.env
+
+module Proscenium
+  class Railtie < ::Rails::Engine
+    isolate_namespace Proscenium
+
+    config.proscenium = ActiveSupport::OrderedOptions.new
+    config.proscenium.debug = false
+    config.proscenium.side_load = true
+    config.proscenium.code_splitting = true
+
+    # Cache asset paths when building to path. Enabled by default in production.
+    # @see Proscenium::Builder#build_to_path
+    config.proscenium.cache = ActiveSupport::Cache::MemoryStore.new if Rails.env.production?
+
+    # TODO: implement!
+    config.proscenium.cache_query_string = Rails.env.production? && ENV.fetch('REVISION', nil)
+    config.proscenium.cache_max_age = 2_592_000 # 30 days
+
+    # List of environment variable names that should be passed to the builder, which will then be
+    # passed to esbuild's `Define` option. Being explicit about which environment variables are
+    # defined means a faster build, as esbuild will have less to do.
+    config.proscenium.env_vars = Set.new
+
+    # Rails engines to expose and allow Proscenium to serve their assets.
+    #
+    # A Rails engine that has assets, can add Proscenium as a gem dependency, and then add itself
+    # to this list. Proscenium will then serve the engine's assets at the URL path beginning with
+    # the engine name.
+    #
+    # Example:
+    #   class Gem1::Engine < ::Rails::Engine
+    #     config.proscenium.engines << self
+    #   end
+    config.proscenium.engines = Set.new
+
+    config.action_dispatch.rescue_templates = {
+      'Proscenium::Builder::BuildError' => 'build_error'
+    }
+
+    config.after_initialize do |_app|
+      ActiveSupport.on_load(:action_view) do
+        include Proscenium::Helper
+      end
+    end
+
+    initializer 'proscenium.ui' do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym 'UI'
+      end
+    end
+
+    initializer 'proscenium.debugging' do
+      if Rails.gem_version >= Gem::Version.new('7.1.0')
+        tpl_path = root.join('lib', 'proscenium', 'templates').to_s
+        ActionDispatch::DebugView::RESCUES_TEMPLATE_PATHS << tpl_path
+      end
+    end
+
+    initializer 'proscenium.middleware' do |app|
+      app.middleware.insert_after ActionDispatch::Static, Middleware
+      app.middleware.insert_after ActionDispatch::Static, Rack::ETag, 'no-cache'
+      app.middleware.insert_after ActionDispatch::Static, Rack::ConditionalGet
+    end
+
+    initializer 'proscenium.sideloading' do
+      ActiveSupport.on_load(:action_controller) do
+        ActionController::Base.include EnsureLoaded
+        ActionController::Base.include SideLoad::Controller
+      end
+    end
+
+    initializer 'proscenium.monkey_patches' do
+      ActiveSupport.on_load(:action_view) do
+        ActionView::TemplateRenderer.prepend Monkey::TemplateRenderer
+        ActionView::PartialRenderer.prepend Monkey::PartialRenderer
+      end
+    end
+
+    initializer 'proscenium.public_path' do |app|
+      if app.config.public_file_server.enabled
+        headers = app.config.public_file_server.headers || {}
+        index = app.config.public_file_server.index_name || 'index'
+
+        app.middleware.insert_after(ActionDispatch::Static, ActionDispatch::Static,
+                                    root.join('public').to_s, index:, headers:)
+      end
+    end
+  end
+end
+
+if Rails.gem_version < Gem::Version.new('7.1.0')
+  class ActionDispatch::DebugView
+    def initialize(assigns)
+      tpl_path = Proscenium::Railtie.root.join('lib', 'proscenium', 'templates').to_s
+      paths = [RESCUES_TEMPLATE_PATH, tpl_path]
+      lookup_context = ActionView::LookupContext.new(paths)
+      super(lookup_context, assigns, nil)
+    end
+  end
+end

data/lib/proscenium/react_componentable.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module ReactComponentable
+    extend ActiveSupport::Concern
+
+    included do
+      # @return [Hash] the props to pass to the React component.
+      attr_writer :props
+
+      # The HTML tag to use as the wrapping element for the component. You can reassign this in your
+      # component class to use a different tag:
+      #
+      #   class MyComponent < Proscenium::ViewComponent::ReactComponent
+      #     self.root_tag = :span
+      #   end
+      #
+      # @return [Symbol]
+      class_attribute :root_tag, instance_predicate: false, default: :div
+
+      # By default, the template block (content) of the component will be server rendered as normal.
+      # However, when React hydrates and takes control of the component, it's content will be
+      # replaced by React with the JavaScript rendered content. Enabling this option will forward
+      # the server rendered content as the `children` prop passed to the React component.
+      #
+      # @example
+      #
+      #   const Component = ({ children }) => {
+      #     return <div dangerouslySetInnerHTML={{ __html: children }} />
+      #   }
+      #
+      # @return [Boolean]
+      class_attribute :forward_children, default: false
+
+      # Lazy load the component using IntersectionObserver?
+      #
+      # @return [Boolean]
+      class_attribute :lazy, default: false
+
+      class_attribute :loader
+
+      # @return [String] the URL path to the component manager.
+      class_attribute :manager, default: '/@proscenium/react-manager/index.jsx'
+    end
+
+    class_methods do
+      def sideload(options)
+        Importer.import manager, **options, js: { type: 'module' }
+        Importer.sideload source_path, lazy: true, **options
+      end
+    end
+
+    # @param props: [Hash]
+    def initialize(lazy: self.class.lazy, loader: self.class.loader, props: {})
+      self.lazy = lazy
+      self.loader = loader
+      @props = props
+    end
+
+    # The absolute URL path to the javascript component.
+    def virtual_path
+      @virtual_path ||= Resolver.resolve self.class.source_path.sub_ext('.jsx').to_s
+    end
+
+    def props
+      @props ||= {}
+    end
+
+    private
+
+    def data_attributes
+      {
+        proscenium_component_path: Pathname.new(virtual_path).to_s,
+        proscenium_component_props: prepared_props,
+        proscenium_component_lazy: lazy
+      }.tap do |x|
+        x[:proscenium_component_forward_children] = true if forward_children?
+      end
+    end
+
+    def prepared_props
+      props.deep_transform_keys do |term|
+        # This ensures that the first letter after a slash is not capitalized.
+        string = term.to_s.split('/').map { |str| str.camelize :lower }.join('/')
+
+        # Reverses the effect of ActiveSupport::Inflector.camelize converting slashes into `::`.
+        string.gsub '::', '/'
+      end.to_json
+    end
+
+    def loader_component
+      render Loader::Component.new(loader, @html_class, data_attributes, tag: @html_tag)
+    end
+  end
+end

data/lib/proscenium/resolver.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+
+module Proscenium
+  class Resolver < ActiveSupport::CurrentAttributes
+    # TODO: cache this across requests in production.
+    attribute :resolved
+
+    # Resolve the given `path` to a URL path.
+    #
+    # @param path [String] Can be URL path, file system path, or bare specifier (ie. NPM package).
+    # @return [String] URL path.
+    #
+    # rubocop:disable Metrics/*
+    def self.resolve(path)
+      self.resolved ||= {}
+
+      self.resolved[path] ||= begin
+        if path.start_with?('./', '../')
+          raise ArgumentError, 'path must be an absolute file system or URL path'
+        end
+
+        if path.start_with?('@proscenium/')
+          "/#{path}"
+        elsif path.start_with?(Proscenium.ui_path.to_s)
+          path.delete_prefix Proscenium.root.join('lib').to_s
+        elsif (engine = Proscenium.config.engines.find { |e| path.start_with? "#{e.root}/" })
+          path.sub(/^#{engine.root}/, "/#{engine.engine_name}")
+        elsif path.start_with?("#{Rails.root}/")
+          path.delete_prefix Rails.root.to_s
+        else
+          Builder.resolve path
+        end
+      end
+    end
+    # rubocop:enable Metrics/*
+  end
+end