proscenium 0.9.1-x86_64-darwin → 0.11.0.pre.1-x86_64-darwin

data/lib/proscenium/builder.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'ffi'
+require 'oj'
+
+module Proscenium
+  class Builder
+    class CompileError < StandardError; end
+
+    class Result < FFI::Struct
+      layout :success, :bool,
+             :response, :string
+    end
+
+    module Request
+      extend FFI::Library
+      ffi_lib Pathname.new(__dir__).join('ext/proscenium').to_s
+
+      enum :environment, [:development, 1, :test, :production]
+
+      attach_function :build, [
+        :string,      # path or entry point. multiple can be given by separating with a semi-colon
+        :string,      # base URL of the Rails app. eg. https://example.com
+        :string,      # path to import map, relative to root
+        :string,      # ENV variables as a JSON string
+
+        # Config
+        :string,      # root
+        :environment, # Rails environment as a Symbol
+        :bool,        # code splitting enabled?
+        :bool         # debugging enabled?
+      ], Result.by_value
+
+      attach_function :resolve, [
+        :string,      # path or entry point
+        :string,      # path to import map, relative to root
+
+        # Config
+        :string,      # root
+        :environment  # Rails environment as a Symbol
+      ], Result.by_value
+    end
+
+    class BuildError < StandardError
+      attr_reader :error, :path
+
+      def initialize(path, error)
+        error = Oj.load(error, mode: :strict).deep_transform_keys(&:underscore)
+
+        super "Failed to build '#{path}' -- #{error['text']}"
+      end
+    end
+
+    class ResolveError < StandardError
+      attr_reader :error_msg, :path
+
+      def initialize(path, error_msg)
+        super "Failed to resolve '#{path}' -- #{error_msg}"
+      end
+    end
+
+    def self.build(path, root: nil, base_url: nil)
+      new(root: root, base_url: base_url).build(path)
+    end
+
+    def self.resolve(path, root: nil)
+      new(root: root).resolve(path)
+    end
+
+    def initialize(root: nil, base_url: nil)
+      @root = root || Rails.root
+      @base_url = base_url
+    end
+
+    def build(path)
+      ActiveSupport::Notifications.instrument('build.proscenium', identifier: path) do
+        result = Request.build(path, @base_url, import_map, env_vars.to_json,
+                               @root.to_s,
+                               Rails.env.to_sym,
+                               Proscenium.config.code_splitting,
+                               Proscenium.config.debug)
+
+        raise BuildError.new(path, result[:response]) unless result[:success]
+
+        result[:response]
+      end
+    end
+
+    def resolve(path)
+      ActiveSupport::Notifications.instrument('resolve.proscenium', identifier: path) do
+        result = Request.resolve(path, import_map, @root.to_s, Rails.env.to_sym)
+        raise ResolveError.new(path, result[:response]) unless result[:success]
+
+        result[:response]
+      end
+    end
+
+    private
+
+    # Build the ENV variables as determined by `Proscenium.config.env_vars` and
+    # `Proscenium::DEFAULT_ENV_VARS` to pass to esbuild.
+    def env_vars
+      ENV['NODE_ENV'] = ENV.fetch('RAILS_ENV', nil)
+      ENV.slice(*Proscenium.config.env_vars + Proscenium::DEFAULT_ENV_VARS)
+    end
+
+    def cache_query_string
+      q = Proscenium.config.cache_query_string
+      q ? "--cache-query-string #{q}" : nil
+    end
+
+    def import_map
+      return unless (path = Rails.root&.join('config'))
+
+      if (json = path.join('import_map.json')).exist?
+        return json.relative_path_from(@root).to_s
+      end
+
+      if (js = path.join('import_map.js')).exist?
+        return js.relative_path_from(@root).to_s
+      end
+
+      nil
+    end
+  end
+end

data/lib/proscenium/css_module/path.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module CssModule::Path
+    # Returns the path to the CSS module file for this class, where the file is located alongside
+    # the class file, and has the same name as the class file, but with a `.module.css` extension.
+    #
+    # If the CSS module file does not exist, it's ancestry is checked, returning the first that
+    # exists. Then finally `nil` is returned if never found.
+    #
+    # @return [Pathname]
+    def css_module_path
+      return @css_module_path if instance_variable_defined?(:@css_module_path)
+
+      path = source_path.sub_ext('.module.css')
+      @css_module_path = path.exist? ? path : nil
+
+      unless @css_module_path
+        klass = superclass
+
+        while klass.respond_to?(:css_module_path) && !klass.abstract_class
+          break if (@css_module_path = klass.css_module_path)
+
+          klass = klass.superclass
+        end
+      end
+
+      @css_module_path
+    end
+  end
+end

data/lib/proscenium/css_module/transformer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class CssModule::Transformer
+    FILE_EXT = '.module.css'
+
+    def self.class_names(path, *names)
+      new(path).class_names(*names)
+    end
+
+    def initialize(source_path)
+      @source_path = source_path
+      @source_path = Pathname.new(@source_path) unless @source_path.is_a?(Pathname)
+      @source_path = @source_path.sub_ext(FILE_EXT) unless @source_path.to_s.end_with?(FILE_EXT)
+    end
+
+    # Transform each of the given class `names` to their respective CSS module name, which consist
+    # of the name, and suffixed with the digest of the resolved source path.
+    #
+    # Any name beginning with '@' will be transformed to a CSS module name. If `require_prefix` is
+    # false, then all names will be transformed to a CSS module name regardless of whether or not
+    # they begin with '@'.
+    #
+    #   class_names :@my_module_name, :my_class_name
+    #
+    # Note that the generated digest is based on the resolved (URL) path, not the original path.
+    #
+    # You can also provide a path specifier and class name. The path will be the URL path to a
+    # stylesheet. The class name will be the name of the class to transform.
+    #
+    #   class_names "/lib/button@default"
+    #   class_names "mypackage/button@large"
+    #   class_names "@scoped/package/button@small"
+    #
+    # @param names [String,Symbol,Array<String,Symbol>]
+    # @param require_prefix: [Boolean] whether or not to require the `@` prefix.
+    # @return [Array<String>] the transformed CSS module names.
+    def class_names(*names, require_prefix: true)
+      names.map do |name|
+        name = name.to_s if name.is_a?(Symbol)
+
+        if name.include?('/')
+          if name.start_with?('@')
+            # Scoped bare specifier (eg. "@scoped/package/lib/button@default").
+            _, path, name = name.split('@')
+            path = "@#{path}"
+          elsif name.start_with?('/')
+            # Local path with leading slash.
+            path, name = name[1..].split('@')
+          else
+            # Bare specifier (eg. "mypackage/lib/button@default").
+            path, name = name.split('@')
+          end
+
+          class_name! name, path: "#{path}#{FILE_EXT}"
+        elsif name.start_with?('@')
+          class_name! name[1..]
+        else
+          require_prefix ? name : class_name!(name)
+        end
+      end
+    end
+
+    def class_name!(name, path: @source_path)
+      resolved_path = Resolver.resolve(path.to_s)
+      digest = Importer.import(resolved_path)
+
+      sname = name.to_s
+      if sname.start_with?('_')
+        "_#{sname[1..]}-#{digest}"
+      else
+        "#{sname}-#{digest}"
+      end
+    end
+  end
+end

data/lib/proscenium/css_module.rb

@@ -3,41 +3,19 @@
 module Proscenium::CssModule
   extend ActiveSupport::Autoload
 
-  class StylesheetNotFound < StandardError
-    def initialize(pathname)
-      @pathname = pathname
-      super
-    end
-
-    def message
-      "Stylesheet is required, but does not exist: #{@pathname}"
-    end
-  end
-
-  autoload :ClassNamesResolver
-  autoload :Resolver # deprecated
-
-  # Like `css_modules`, but will raise if the stylesheet cannot be found.
-  #
-  # @param name [Array, String]
-  def css_module!(names)
-    cssm.class_names!(names).join ' '
-  end
+  autoload :Path
+  autoload :Transformer
 
   # Accepts one or more CSS class names, and transforms them into CSS module names.
   #
-  # @param name [Array, String]
-  def css_module(names)
-    cssm.class_names(names).join ' '
+  # @param name [String,Symbol,Array<String,Symbol>]
+  def css_module(*names)
+    cssm.class_names(*names, require_prefix: false).join ' '
   end
 
   private
 
-  def path
-    self.class.path
-  end
-
   def cssm
-    @cssm ||= Resolver.new(path)
+    @cssm ||= Transformer.new(self.class.css_module_path)
   end
 end

data/lib/proscenium/ensure_loaded.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Proscenium
+  NotIncludedError = Class.new(StandardError)
+
+  module EnsureLoaded
+    def self.included(child)
+      child.class_eval do
+        append_after_action do
+          if request.format.html? && Importer.imported?
+            if Importer.js_imported?
+              raise NotIncludedError, 'There are javascripts to be included, but they have ' \
+                                      'not been included in the page. Did you forget to add the ' \
+                                      '`#include_javascripts` helper in your views?'
+            end
+
+            if Importer.css_imported?
+              raise NotIncludedError, 'There are stylesheets to be included, but they have ' \
+                                      'not been included in the page. Did you forget to add the ' \
+                                      '`#include_stylesheets` helper in your views?'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/proscenium/ext/proscenium.h

@@ -85,23 +85,30 @@ extern "C" {
 
 // Build the given `path` in the `root`.
 //
-//   - path - The path to build relative to `root`.
-//   - root - The working directory.
-//   - baseUrl - base URL of the Rails app. eg. https://example.com
-//   - env - The environment (1 = development, 2 = test, 3 = production)
-//   - importMap - Path to the import map relative to `root`.
-//   - debug
+//	BuildOptions
+//	- path - The path to build relative to `root`. Multiple paths can be given by separating them
+//	  with a semi-colon.
+//	- baseUrl - base URL of the Rails app. eg. https://example.com
+//	- importMap - Path to the import map relative to `root`.
+//	- envVars - JSON string of environment variables.
+//	Config:
+//	- root - The working directory.
+//	- env - The environment (1 = development, 2 = test, 3 = production)
+//	- codeSpitting?
+//	- debug?
 //
-extern struct Result build(char* filepath, char* root, char* baseUrl, unsigned int env, char* importMap, GoUint8 debug);
+extern struct Result build(char* filepath, char* baseUrl, char* importMap, char* envVars, char* root, unsigned int env, GoUint8 codeSplitting, GoUint8 debug);
 
 // Resolve the given `path` relative to the `root`.
 //
-//   - path - The path to build relative to `root`.
-//   - root - The working directory.
-//   - env - The environment (1 = development, 2 = test, 3 = production)
-//   - importMap - Path to the import map relative to `root`.
+//	ResolveOptions
+//	- path - The path to build relative to `root`.
+//	- importMap - Path to the import map relative to `root`.
+//	Config
+//	- root - The working directory.
+//	- env - The environment (1 = development, 2 = test, 3 = production)
 //
-extern struct Result resolve(char* path, char* root, unsigned int env, char* importMap);
+extern struct Result resolve(char* path, char* importMap, char* root, unsigned int env);
 
 #ifdef __cplusplus
 }

data/lib/proscenium/helper.rb

@@ -15,5 +15,67 @@ module Proscenium
 
       super
     end
+
+    # Accepts one or more CSS class names, and transforms them into CSS module names.
+    #
+    # @see CssModule::Transformer#class_names
+    # @param name [String,Symbol,Array<String,Symbol>]
+    def css_module(*names)
+      path = Pathname.new(@lookup_context.find(@virtual_path).identifier).sub_ext('')
+      CssModule::Transformer.new(path).class_names(*names, require_prefix: false).join ' '
+    end
+
+    def include_stylesheets(**options)
+      out = []
+      Importer.each_stylesheet(delete: true) do |path, _path_options|
+        out << stylesheet_link_tag(path, extname: false, **options)
+      end
+      out.join("\n").html_safe
+    end
+    alias side_load_stylesheets include_stylesheets
+    deprecate side_load_stylesheets: 'Use `include_stylesheets` instead', deprecator: Deprecator.new
+
+    def include_javascripts(**options) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      out = []
+
+      if Rails.application.config.proscenium.code_splitting && Importer.multiple_js_imported?
+        imports = Importer.imported.dup
+
+        paths_to_build = []
+        Importer.each_javascript(delete: true) do |x, _|
+          paths_to_build << x.delete_prefix('/')
+        end
+
+        result = Builder.build(paths_to_build.join(';'), base_url: request.base_url)
+
+        # Remove the react components from the results, so they are not side loaded. Instead they
+        # are lazy loaded by the component manager.
+
+        scripts = {}
+        result.split(';').each do |x|
+          inpath, outpath = x.split('::')
+          inpath.prepend '/'
+          outpath.delete_prefix! 'public'
+
+          next unless imports.key?(inpath)
+
+          if (import = imports[inpath]).delete(:lazy)
+            scripts[inpath] = import.merge(outpath: outpath)
+          else
+            out << javascript_include_tag(outpath, extname: false, **options)
+          end
+        end
+
+        out << javascript_tag("window.prosceniumLazyScripts = #{scripts.to_json}")
+      else
+        Importer.each_javascript(delete: true) do |path, _path_options|
+          out << javascript_include_tag(path, extname: false, **options)
+        end
+      end
+
+      out.join("\n").html_safe
+    end
+    alias side_load_javascripts include_javascripts
+    deprecate side_load_javascripts: 'Use `include_javascripts` instead', deprecator: Deprecator.new
   end
 end

data/lib/proscenium/importer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+
+module Proscenium
+  class Importer < ActiveSupport::CurrentAttributes
+    JS_EXTENSIONS = %w[.tsx .ts .jsx .js].freeze
+    CSS_EXTENSIONS = %w[.module.css .css].freeze
+
+    # Holds the JS and CSS files to include in the current request.
+    #
+    # Example:
+    #   {
+    #     '/path/to/input/file.js': {
+    #       output: '/path/to/compiled/file.js',
+    #       **options
+    #     }
+    #   }
+    attribute :imported
+
+    class << self
+      # Import the given `filepath`. This is idempotent - it will never include duplicates.
+      #
+      # @param filepath [String] Absolute path (relative to Rails root) of the file to import.
+      #   Should be the actual asset file, eg. app.css, some/component.js.
+      # @param resolve [String] description of the file to resolve and import.
+      # @return [String] the digest of the imported file path if a css module (*.module.css).
+      def import(filepath = nil, resolve: nil, **options)
+        self.imported ||= {}
+
+        filepath = Resolver.resolve(resolve) if !filepath && resolve
+        css_module = filepath.end_with?('.module.css')
+
+        unless self.imported.key?(filepath)
+          # ActiveSupport::Notifications.instrument('sideload.proscenium', identifier: value)
+
+          self.imported[filepath] = { **options }
+          self.imported[filepath][:digest] = Utils.digest(filepath) if css_module
+        end
+
+        css_module ? self.imported[filepath][:digest] : nil
+      end
+
+      # Sideloads JS and CSS assets for the given Ruby filepath.
+      #
+      # Any files with the same base name and matching a supported extension will be sideloaded.
+      # Only one JS and one CSS file will be sideloaded, with the first match used in the following
+      # order:
+      #  - JS extensions: .tsx, .ts, .jsx, and .js.
+      #  - CSS extensions: .css.module, and .css.
+      #
+      # Example:
+      #  - `app/views/layouts/application.rb`
+      #  - `app/views/layouts/application.css`
+      #  - `app/views/layouts/application.js`
+      #  - `app/views/layouts/application.tsx`
+      #
+      # A request to sideload `app/views/layouts/application.rb` will result in `application.css`
+      # and `application.tsx` being sideloaded. `application.js` will not be sideloaded because the
+      # `.tsx` extension is matched first.
+      #
+      # @param filepath [Pathname] Absolute file system path of the Ruby file to sideload.
+      def sideload(filepath, **options)
+        return unless Proscenium.config.side_load
+
+        filepath = Rails.root.join(filepath) unless filepath.is_a?(Pathname)
+        filepath = filepath.sub_ext('')
+
+        import_if_exists = lambda do |x|
+          if (fp = filepath.sub_ext(x)).exist?
+            import(Resolver.resolve(fp.to_s), sideloaded: true, **options)
+          end
+        end
+
+        JS_EXTENSIONS.find(&import_if_exists)
+        CSS_EXTENSIONS.find(&import_if_exists)
+      end
+
+      def each_stylesheet(delete: false)
+        return if imported.blank?
+
+        blk = proc { |key, options| key.end_with?(*CSS_EXTENSIONS) && yield(key, options) }
+        delete ? imported.delete_if(&blk) : imported.each(&blk)
+      end
+
+      def each_javascript(delete: false)
+        return if imported.blank?
+
+        blk = proc { |key, options| key.end_with?(*JS_EXTENSIONS) && yield(key, options) }
+        delete ? imported.delete_if(&blk) : imported.each(&blk)
+      end
+
+      def css_imported?
+        imported&.keys&.any? { |x| x.end_with?(*CSS_EXTENSIONS) }
+      end
+
+      def js_imported?
+        imported&.keys&.any? { |x| x.end_with?(*JS_EXTENSIONS) }
+      end
+
+      def multiple_js_imported?
+        imported&.keys&.many? { |x| x.end_with?(*JS_EXTENSIONS) }
+      end
+
+      def imported?(filepath = nil)
+        filepath ? imported&.key?(filepath) : !imported.blank?
+      end
+    end
+  end
+end

data/lib/proscenium/libs/react-manager/index.jsx

@@ -0,0 +1,88 @@
+const elements = document.querySelectorAll("[data-proscenium-component-path]");
+
+// Initialize only if there are components.
+elements.length > 0 && init();
+
+function init() {
+  /**
+   * Mounts component located at `path`, into the DOM `element`.
+   *
+   * The element at which the component is mounted must have the following data attributes:
+   *
+   * - `data-proscenium-component-path`: The URL path to the component's source file.
+   * - `data-proscenium-component-props`: JSON object of props to pass to the component.
+   * - `data-proscenium-component-lazy`: If present, will lazily load the component when in view
+   *   using IntersectionObserver.
+   * - `data-proscenium-component-forward-children`: If the element should forward its `innerHTML`
+   *   as the component's children prop.
+   */
+  function mount(element, path, { children, ...props }) {
+    // For testing and simulation of slow connections.
+    // const sim = new Promise((resolve) => setTimeout(resolve, 5000));
+
+    if (!(path in window.prosceniumLazyScripts)) {
+      throw `[proscenium/react/manager] Cannot load component ${path} (not found in prosceniumLazyScripts)`;
+    }
+
+    const react = import("@proscenium/react-manager/react");
+    const Component = import(window.prosceniumLazyScripts[path].outpath);
+
+    const forwardChildren =
+      "prosceniumComponentForwardChildren" in element.dataset &&
+      element.innerHTML !== "";
+
+    Promise.all([react, Component]).then(([r, c]) => {
+      if (proscenium.env.RAILS_ENV === "development") {
+        console.groupCollapsed(
+          `[proscenium/react/manager] 🔥 %o mounted!`,
+          path
+        );
+        console.log("props: %o", props);
+        console.groupEnd();
+      }
+
+      let component;
+      if (forwardChildren) {
+        component = r.createElement(c.default, props, element.innerHTML);
+      } else if (children) {
+        component = r.createElement(c.default, props, children);
+      } else {
+        component = r.createElement(c.default, props);
+      }
+
+      r.createRoot(element).render(component);
+    });
+  }
+
+  Array.from(elements, (element) => {
+    const path = element.dataset.prosceniumComponentPath;
+    const isLazy = "prosceniumComponentLazy" in element.dataset;
+    const props = JSON.parse(element.dataset.prosceniumComponentProps);
+
+    if (proscenium.env.RAILS_ENV === "development") {
+      console.groupCollapsed(
+        `[proscenium/react/manager] ${isLazy ? "💤" : "⚡️"} %o`,
+        path
+      );
+      console.log("element: %o", element);
+      console.log("props: %o", props);
+      console.groupEnd();
+    }
+
+    if (isLazy) {
+      const observer = new IntersectionObserver((entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            observer.unobserve(element);
+
+            mount(element, path, props);
+          }
+        });
+      });
+
+      observer.observe(element);
+    } else {
+      mount(element, path, props);
+    }
+  });
+}

data/lib/proscenium/libs/react-manager/react.js

@@ -0,0 +1,2 @@
+export { createElement } from "react";
+export { createRoot } from "react-dom/client";