proscenium 0.6.0-x86_64-linux → 0.8.2-x86_64-linux

data/lib/proscenium/phlex/react_component.rb

@@ -1,10 +1,32 @@
 # frozen_string_literal: true
 
 #
-# Renders a div for use with component-manager.
+# Renders a div for use with @proscenium/component-manager.
 #
-class Proscenium::Phlex::ReactComponent < Proscenium::Phlex::Component
-  attr_accessor :props, :lazy
+# You can pass props to the component in the `:props` keyword argument.
+#
+# By default, the component is lazy loaded when intersecting using IntersectionObserver. Pass in
+# :lazy as false to disable this and render the component immediately.
+#
+# React components are not side loaded at all.
+#
+class Proscenium::Phlex::ReactComponent < Phlex::HTML
+  class << self
+    attr_accessor :path, :abstract_class
+
+    def inherited(child)
+      position = caller_locations(1, 1).first.label == 'inherited' ? 2 : 1
+      child.path = Pathname.new caller_locations(position, 1).first.path.sub(/\.rb$/, '')
+
+      super
+    end
+  end
+
+  self.abstract_class = true
+
+  include Proscenium::Phlex::ComponentConcerns::CssModules
+
+  attr_writer :props, :lazy
 
   # @param props: [Hash]
   # @param lazy: [Boolean] Lazy load the component using IntersectionObserver. Default: true.
@@ -16,10 +38,32 @@ class Proscenium::Phlex::ReactComponent < Proscenium::Phlex::Component
   # @yield the given block to a `div` within the top level component div. If not given,
   #   `<div>loading...</div>` will be rendered. Use this to display a loading UI while the component
   #   is loading and rendered.
-  def template(&block)
-    div class: ['componentManagedByProscenium', '@component'],
-        data: { component: { path: virtual_path, props: props, lazy: lazy }.to_json } do
-      block ? div(&block) : div { 'loading...' }
-    end
+  def template(**attributes, &block)
+    component_root(:div, **attributes, &block)
+  end
+
+  private
+
+  def component_root(element, **attributes, &block)
+    send element, data: { proscenium_component: component_data }, **attributes, &block
+  end
+
+  def props
+    @props ||= {}
+  end
+
+  def lazy
+    instance_variable_defined?(:@lazy) ? @lazy : (@lazy = false)
+  end
+
+  def component_data
+    {
+      path: virtual_path, lazy: lazy,
+      props: props.deep_transform_keys { |k| k.to_s.camelize :lower }
+    }.to_json
+  end
+
+  def virtual_path
+    path.to_s.delete_prefix(Rails.root.to_s)
   end
 end

data/lib/proscenium/phlex/resolve_css_modules.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module Phlex::ResolveCssModules
+    extend ActiveSupport::Concern
+
+    class_methods do
+      attr_accessor :side_load_cache
+    end
+
+    def before_template
+      self.class.side_load_cache ||= Set.new
+      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 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 template
+    #       div class: '/lib/users@name' do
+    #         'Joel Moss'
+    #       end
+    #     end
+    #   end
+    #
+    # The given class name should be underscored, and the resulting CSS module name will be
+    # `camelCased` with a lower case first character.
+    #
+    # @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?('@')
+        resolver = CssModule::ClassNamesResolver.new(attributes[:class], path)
+        self.class.side_load_cache.merge resolver.stylesheets
+        attributes[:class] = resolver.class_names
+      end
+
+      attributes
+    end
+
+    def after_template
+      super
+      self.class.side_load_cache&.each { |path| SideLoad.append! path, :css }
+    end
+  end
+end

data/lib/proscenium/phlex.rb

@@ -1,60 +1,61 @@
 # frozen_string_literal: true
 
-require 'phlex'
+require 'phlex-rails'
 
 module Proscenium
-  class Phlex < ::Phlex::View
+  class Phlex < ::Phlex::HTML
     extend ActiveSupport::Autoload
+    include Proscenium::CssModule
 
-    autoload :Component
+    autoload :Page
     autoload :ReactComponent
+    autoload :ResolveCssModules
+    autoload :ComponentConcerns
 
-    module Helpers
-      def side_load_javascripts(...)
-        return unless (output = @_view_context.side_load_javascripts(...))
+    extend ::Phlex::Rails::HelperMacros
+    include ::Phlex::Rails::Helpers::JavaScriptIncludeTag
+    include ::Phlex::Rails::Helpers::StyleSheetLinkTag
 
-        @_target << output
-      end
+    define_output_helper :side_load_stylesheets
+    define_output_helper :side_load_javascripts
+
+    # Side loads the class, and its super classes that respond to `.path`. Assign the
+    # `abstract_class` class variable to any abstract class, and it will not be side loaded.
+    # Additionally, if the class responds to `side_load`, then that method is called.
+    module Sideload
+      def before_template
+        klass = self.class
 
-      %i[side_load_stylesheets proscenium_dev].each do |name|
-        define_method name do
-          if (output = @_view_context.send(name))
-            @_target << output
-          end
+        if !klass.abstract_class && respond_to?(:side_load, true)
+          side_load
+          klass = klass.superclass
         end
-      end
-    end
 
-    module Sideload
-      def template(...)
-        Proscenium::SideLoad.append self.class.path if Rails.application.config.proscenium.side_load
+        while !klass.abstract_class && klass.respond_to?(:path) && klass.path
+          Proscenium::SideLoad.append klass.path
+          klass = klass.superclass
+        end
 
         super
       end
     end
 
     class << self
-      attr_accessor :path
+      attr_accessor :path, :abstract_class
 
       def inherited(child)
-        path = caller_locations(1, 1)[0].path
-        child.path = path.delete_prefix(::Rails.root.to_s).delete_suffix('.rb')[1..]
+        unless child.path
+          child.path = if caller_locations(1, 1).first.label == 'inherited'
+                         Pathname.new caller_locations(2, 1).first.path
+                       else
+                         Pathname.new caller_locations(1, 1).first.path
+                       end
+        end
 
-        child.prepend Sideload
-        child.include Helpers
+        child.prepend Sideload if Rails.application.config.proscenium.side_load
 
         super
       end
     end
-
-    def css_module(name)
-      cssm.class_names!(name).join ' '
-    end
-
-    private
-
-    def cssm
-      @cssm ||= Proscenium::CssModule.new(self.class.path)
-    end
   end
 end

data/lib/proscenium/railtie.rb

@@ -1,23 +1,20 @@
 # frozen_string_literal: true
 
 require 'rails'
-require 'action_cable/engine'
-require 'listen'
+require 'proscenium/log_subscriber'
 
 ENV['RAILS_ENV'] = Rails.env
 
 module Proscenium
-  # These globs should actually be Deno supported globs, and not ruby globs. This is because when
-  # precompiling, the glob paths are passed as is to the compiler run by Deno.
-  #
-  # See https://doc.deno.land/https://deno.land/std@0.145.0/path/mod.ts/~/globToRegExp
-  DEFAULT_GLOB_TYPES = {
-    esbuild: '/{config,app,lib,node_modules}/**.{js,mjs,jsx,css}',
-    runtime: '/proscenium-runtime/**.{js,jsx}',
-    url: %r{^/url:https?%3A%2F%2F},
-    outsideRoot: '/**/*.{js,jsx,mjs,css}'
+  FILE_EXTENSIONS = ['js', 'mjs', 'jsx', 'css', 'js.map', 'mjs.map', 'jsx.map', 'css.map'].freeze
+
+  MIDDLEWARE_GLOB_TYPES = {
+    application: "/**.{#{FILE_EXTENSIONS.join(',')}}",
+    url: %r{^/https?%3A%2F%2F}
   }.freeze
 
+  APPLICATION_INCLUDE_PATHS = ['config', 'app/views', 'lib', 'node_modules'].freeze
+
   class << self
     def config
       @config ||= Railtie.config.proscenium
@@ -31,21 +28,29 @@ module Proscenium
     config.proscenium.side_load = true
     config.proscenium.cache_query_string = Rails.env.production? && ENV.fetch('REVISION', nil)
     config.proscenium.cache_max_age = 2_592_000 # 30 days
-    config.proscenium.auto_reload = Rails.env.development?
-    config.proscenium.auto_reload_paths ||= %w[lib app config]
-    config.proscenium.auto_reload_extensions ||= /\.(css|jsx?)$/
+    config.proscenium.include_paths = Set.new(APPLICATION_INCLUDE_PATHS)
+
+    # A hash of gems that can be side loaded. Assets from gems listed here can be side loaded.
+    #
+    # Because side loading uses URL paths, any gem dependencies that side load assets will fail,
+    # because the URL path will be relative to the application's root, and not the gem's root. By
+    # specifying a list of gems that can be side loaded, Proscenium will be able to resolve the URL
+    # path to the gem's root, and side load the asset.
+    #
+    # Side loading gems rely on NPM and a package.json file in the gem root. This ensures that any
+    # dependencies are resolved correctly. This is required even if your gem has no package
+    # dependencies.
+    #
+    # Example:
+    #   config.proscenium.side_load_gems['mygem'] = {
+    #     root: gem_root,
+    #     package_name: 'mygem'
+    #   }
+    config.proscenium.side_load_gems = {}
 
     initializer 'proscenium.configuration' do |app|
       options = app.config.proscenium
-
-      options.glob_types = DEFAULT_GLOB_TYPES if options.glob_types.blank?
-      options.auto_reload_paths.filter! { |path| Dir.exist? path }
-      options.cable_mount_path ||= '/proscenium-cable'
-      options.cable_logger ||= Rails.logger
-    end
-
-    initializer 'proscenium.side_load' do |_app|
-      Proscenium::Current.loaded ||= SideLoad::EXTENSIONS.to_h { |e| [e, Set[]] }
+      options.include_paths = Set.new(APPLICATION_INCLUDE_PATHS) if options.include_paths.blank?
     end
 
     initializer 'proscenium.middleware' do |app|
@@ -54,57 +59,26 @@ module Proscenium
       app.middleware.insert_after ActionDispatch::Static, Rack::ConditionalGet
     end
 
-    initializer 'proscenium.helpers' do |_app|
-      ActiveSupport.on_load(:action_view) do
-        ActionView::Base.include Proscenium::Helper
+    initializer 'proscenium.side_loading' do |app|
+      if app.config.proscenium.side_load
+        Proscenium::Current.loaded ||= SideLoad::EXTENSIONS.to_h { |e| [e, Set.new] }
+
+        ActiveSupport.on_load(:action_view) do
+          ActionView::Base.include Proscenium::SideLoad::Helper
 
-        if Rails.application.config.proscenium.side_load
           ActionView::TemplateRenderer.prepend SideLoad::Monkey::TemplateRenderer
+          ActionView::PartialRenderer.prepend SideLoad::Monkey::PartialRenderer
         end
 
-        ActionView::Helpers::UrlHelper.prepend Proscenium::LinkToHelper
-      end
-    end
-
-    config.after_initialize do
-      next unless config.proscenium.auto_reload
-
-      @listener = Listen.to(*config.proscenium.auto_reload_paths,
-                            only: config.proscenium.auto_reload_extensions) do |mod, add, rem|
-        Proscenium::Railtie.websocket&.broadcast('reload', {
-                                                   modified: mod,
-                                                   removed: rem,
-                                                   added: add
-                                                 })
+        ActiveSupport.on_load(:action_controller) do
+          ActionController::Base.include Proscenium::SideLoad::EnsureLoaded
+        end
       end
-
-      @listener.start
-    end
-
-    at_exit do
-      @listener&.stop
     end
 
-    class << self
-      def websocket
-        return @websocket unless @websocket.nil?
-        return unless config.proscenium.auto_reload
-
-        cable = ActionCable::Server::Configuration.new
-        cable.cable = { adapter: 'async' }.with_indifferent_access
-        cable.mount_path = config.proscenium.cable_mount_path
-        cable.connection_class = -> { Proscenium::Connection }
-        cable.logger = config.proscenium.cable_logger
-
-        @websocket ||= ActionCable::Server::Base.new(config: cable)
-      end
-
-      def websocket_mount_path
-        "#{mounted_path}#{config.proscenium.cable_mount_path}" if websocket
-      end
-
-      def mounted_path
-        Proscenium::Railtie.routes.find_script_name({})
+    initializer 'proscenium.helper' do
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Base.include Proscenium::Helper
       end
     end
   end

data/lib/proscenium/side_load/ensure_loaded.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Proscenium::SideLoad
+  module EnsureLoaded
+    def self.included(child)
+      child.class_eval do
+        append_after_action do
+          if Proscenium::Current.loaded
+            if Proscenium::Current.loaded[:js].present?
+              raise NotIncludedError, 'There are javascripts to be side loaded, but they have not ' \
+                                      'been included. Did you forget to add the ' \
+                                      '`#side_load_javascripts` helper in your views?'
+            end
+
+            if Proscenium::Current.loaded[:css].present?
+              raise NotIncludedError, 'There are stylesheets to be side loaded, but they have not ' \
+                                      'been included. Did you forget to add the ' \
+                                      '`#side_load_stylesheets` helper in your views?'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/proscenium/side_load/helper.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module SideLoad::Helper
+    def side_load_stylesheets
+      return unless Proscenium::Current.loaded
+
+      out = []
+      Proscenium::Current.loaded[:css].delete_if do |path|
+        out << stylesheet_link_tag(path)
+      end
+      out.join("\n").html_safe
+    end
+
+    def side_load_javascripts(**options)
+      return unless Proscenium::Current.loaded
+
+      out = []
+      Proscenium::Current.loaded[:js].delete_if do |path|
+        out << javascript_include_tag(path, options)
+      end
+      out.join("\n").html_safe
+    end
+  end
+end

data/lib/proscenium/side_load/monkey.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class Proscenium::SideLoad
+  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  module Monkey
+    module TemplateRenderer
+      private
+
+      def render_template(view, template, layout_name, locals)
+        layout = find_layout(layout_name, locals.keys, [formats.first])
+        renderable = template.instance_variable_get(:@renderable)
+
+        if Object.const_defined?(:ViewComponent) &&
+           template.is_a?(ActionView::Template::Renderable) &&
+           renderable.class < ::ViewComponent::Base && renderable.class.format == :html
+          # Side load controller rendered ViewComponent
+          Proscenium::SideLoad.append "app/views/#{layout.virtual_path}" if layout
+          Proscenium::SideLoad.append "app/views/#{renderable.virtual_path}"
+        elsif template.respond_to?(:virtual_path) &&
+              template.respond_to?(:type) && template.type == :html
+          # Side load regular view template.
+          Proscenium::SideLoad.append "app/views/#{layout.virtual_path}" if layout
+
+          # Try side loading the variant template
+          if template.respond_to?(:variant) && template.variant
+            Proscenium::SideLoad.append "app/views/#{template.virtual_path}+#{template.variant}"
+          end
+
+          # The variant template may not exist (above), so we try the regular non-variant path.
+          Proscenium::SideLoad.append "app/views/#{template.virtual_path}"
+        end
+
+        super
+      end
+    end
+
+    module PartialRenderer
+      private
+
+      def build_rendered_template(content, template)
+        path = Rails.root.join('app', 'views', template.virtual_path)
+        cssm = Proscenium::CssModule::Resolver.new(path)
+        super cssm.compile_class_names(content), template
+      end
+    end
+  end
+  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+end

data/lib/proscenium/side_load.rb

@@ -1,72 +1,78 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 module Proscenium
-  module SideLoad
-    DEFAULT_EXTENSIONS = %i[js css].freeze
-    EXTENSIONS = %i[js css].freeze
+  class SideLoad
+    extend ActiveSupport::Autoload
 
-    module_function
+    NotIncludedError = Class.new(StandardError)
 
-    # Side load the given asset `path`, by appending it to `Proscenium::Current.loaded`, which is a
-    # Set of 'js' and 'css' asset paths. This is safe to call multiple times, as it uses Set's.
-    # Meaning that side loading will never include duplicates.
-    def append(path, *extensions)
-      Proscenium::Current.loaded ||= EXTENSIONS.to_h { |e| [e, Set[]] }
+    autoload :Monkey
+    autoload :Helper
+    autoload :EnsureLoaded
 
-      unless (unknown_extensions = extensions.difference(EXTENSIONS)).empty?
-        raise ArgumentError, "unsupported extension(s): #{unknown_extensions.join(',')}"
-      end
+    EXTENSIONS = %i[js css].freeze
+    EXTENSION_MAP = { '.css' => :css, '.js' => :js }.freeze
 
-      loaded_types = []
+    attr_reader :path
 
-      (extensions.empty? ? DEFAULT_EXTENSIONS : extensions).each do |ext|
-        path_with_ext = "#{path}.#{ext}"
-        ext = ext.to_sym
+    class << self
+      # Side load the given asset `path`, by appending it to `Proscenium::Current.loaded`, which is a
+      # Set of 'js' and 'css' asset paths. This is idempotent, so side loading will never include
+      # duplicates.
+      #
+      # @return [Array] appended URL paths
+      def append(path, extension_map = EXTENSION_MAP)
+        new(path, extension_map).append
+      end
 
-        next if Proscenium::Current.loaded[ext].include?(path_with_ext)
-        next unless Rails.root.join(path_with_ext).exist?
+      # Side load the given `path` at `type`, without first resolving the path. This still respects
+      # idempotency of `Proscenium::Current.loaded`.
+      #
+      # @param path [String]
+      # @param type [Symbol] :js or :css
+      def append!(path, type)
+        return if Proscenium::Current.loaded[type].include?(path)
 
-        Proscenium::Current.loaded[ext] << path_with_ext
-        loaded_types << ext
+        Proscenium::Current.loaded[type] << log(path)
       end
 
-      !loaded_types.empty? && Rails.logger.debug do
-        "[Proscenium] Side loaded /#{path}.(#{loaded_types.join(',')})"
+      def log(value)
+        ActiveSupport::Notifications.instrument('sideload.proscenium', identifier: value)
+
+        value
       end
     end
 
-    module Monkey
-      module TemplateRenderer
-        private
-
-        def render_template(view, template, layout_name, locals)
-          layout = find_layout(layout_name, locals.keys, [formats.first])
-          renderable = template.instance_variable_get(:@renderable)
-
-          if template.is_a?(ActionView::Template::Renderable) &&
-             renderable.class < ::ViewComponent::Base && renderable.class.format == :html
-            # Side load controller rendered ViewComponent
-            Proscenium::SideLoad.append "app/views/#{layout.virtual_path}" if layout
-            Proscenium::SideLoad.append "app/views/#{renderable.virtual_path}"
-          elsif template.respond_to?(:virtual_path) &&
-                template.respond_to?(:type) && template.type == :html
-            # Side load regular view template.
-            Proscenium::SideLoad.append "app/views/#{layout.virtual_path}" if layout
-
-            # Try side loading the variant template
-            if template.respond_to?(:variant) && template.variant
-              Proscenium::SideLoad.append "app/views/#{template.virtual_path}+#{template.variant}"
-            end
-
-            # The variant template may not exist (above), so we try the regular non-variant path.
-            Proscenium::SideLoad.append "app/views/#{template.virtual_path}"
-          end
-
-          super
+    # @param path [Pathname, String] The path of the file to be side loaded.
+    # @param extension_map [Hash] File extensions to side load.
+    def initialize(path, extension_map = EXTENSION_MAP)
+      @path = (path.is_a?(Pathname) ? path : Rails.root.join(path)).sub_ext('')
+      @extension_map = extension_map
+
+      Proscenium::Current.loaded ||= EXTENSIONS.index_with { |_e| Set.new }
+    end
+
+    def append
+      @extension_map.filter_map do |ext, type|
+        next unless (resolved_path = resolve_path(path.sub_ext(ext)))
+
+        # Make sure path is not already side loaded.
+        unless Proscenium::Current.loaded[type].include?(resolved_path)
+          Proscenium::Current.loaded[type] << log(resolved_path)
         end
+
+        resolved_path
       end
     end
+
+    private
+
+    def log(...)
+      self.class.log(...)
+    end
+
+    def resolve_path(path)
+      path.exist? ? Utils.resolve_path(path.to_s) : nil
+    end
   end
 end
-# rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

data/lib/proscenium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Proscenium
-  VERSION = '0.6.0'
+  VERSION = '0.8.2'
 end

data/lib/proscenium/view_component/react_component.rb

@@ -1,10 +1,24 @@
 # frozen_string_literal: true
 
+#
+# Renders HTML markup suitable for use with @proscenium/component-manager.
+#
+# If a content block is given, that content will be rendered inside the component, allowing for a
+# "loading" UI. If no block is given, then a loading text will be rendered.
+#
+# The parent div is not decorated with any attributes, apart from the selector class required by
+# component-manager. But if your component has a side loaded CSS module stylesheet
+# (component.module.css), with a `.component` class defined, then that class will be assigned to the
+# parent div as a CSS module.
+#
 class Proscenium::ViewComponent::ReactComponent < Proscenium::ViewComponent
+  self.abstract_class = true
+
   attr_accessor :props, :lazy
 
   # @param props: [Hash]
   # @param lazy: [Boolean] Lazy load the component using IntersectionObserver. Default: true.
+  # @param [Block]
   def initialize(props: {}, lazy: true)
     @props = props
     @lazy = lazy