proscenium 0.9.1-arm64-darwin → 0.10.0-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15424d2f9be8b21e02ff041ffd66b1d3941ed266473fd543026b267d740263af
-  data.tar.gz: 17a8a97411258ea8d097bddac3591145d5b9ae14dc4281cdf67080437a8e218f
+  metadata.gz: 8476631a6a76d05712794e1ccd025decfb33ec672d08e696eca527fc07d7ea00
+  data.tar.gz: 0004ad9df6750154ebd725cd1ded6fbbb1bba6156ffccefe82c2b42c8f2370ef
 SHA512:
-  metadata.gz: 792b961dcfbe60717023bbfa437e1694112731d3e82548801464ef78dc1b916f77a2bac4332e4e8e1f2629827166088d3f233df09509cc929711f85dd4db64d3
-  data.tar.gz: 7bdf1387811bf3ade70697d043581c29742d9ffdfdcc3a37a2a0d71a285ff1f28cad9a59f92ef60e0a407c1a77033f228a8018cdd6928a68a7115f09998f6818
+  metadata.gz: 2cd56577c80caa017fa198310886d1447102b0e57284072c425d3ef8c3a3f8a34674d79b5088f9f75dd94b12348e6e697401168348ef41e719ea228897a7baef
+  data.tar.gz: 6d54cbabd613ec4b2006cacd255cd8dc42284888fa9f7844fdae9a9468fb6c1b9fcefbf4066a26f2a742b2e8cee5f7f8d2768336aa13fec89715dd79e4d7c07d

data/README.md

@@ -4,28 +4,64 @@ Proscenium treats your client-side code as first class citizens of your Rails ap
 "fast by default" internet. It bundles your JS, JSX and CSS in real time, on demand, and with zero
 configuration.
 
-- Fast real-time bundling, tree-shaking and minification.
-- Real time bundling of Javascript (.js,.jsx), Typescript (.ts,.tsx) and CSS (.css).
-- NO JavaScript runtime - just the browser!
+- Fast real-time bundling, tree-shaking and minification of Javascript (.js,.jsx), Typescript (.ts,.tsx) and CSS (.css).
+- NO JavaScript runtime needed - just the browser!
 - NO build step or pre-compilation.
 - NO additional process or server - Just run Rails!
 - Deep integration with Rails.
 - Zero configuration.
 - Serve assets from anywhere within your Rails root (/app, /config, /lib, etc.).
 - Automatically side load JS/TS/CSS for your layouts and views.
-- Import from NPM, URLs, and locally.
+- ESM importing from NPM, URLs, and locally.
 - Server-side import map support.
-- CSS Modules.
-- CSS mixins.
+- CSS Modules & mixins.
 - Source maps.
-- Phlex and ViewComponent integration.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Installation](#installation)
+- [Client-Side Code Anywhere](#client-side-code-anywhere)
+- [Side Loading](#side-loading)
+- [Importing](#importing-assets)
+  - [URL Imports](#url-imports)
+  - [Local Imports](#local-imports)
+- [Import Maps](#import-maps)
+- [Source Maps](#source-maps)
+- [SVG](#svg)
+- [Environment Variables](#environment-variables)
+- [i18n](#i18n)
+- [JavaScript](#javascript)
+  - [Tree Shaking](#tree-shaking)
+  - [Code Splitting](#code-splitting)
+  - [JavaScript Caveats](#javascript-caveats)
+- [CSS](#css)
+  - [Importing CSS from JavaScript](#importing-css-from-javascript)
+  - [CSS Modules](#css-modules)
+  - [CSS Mixins](#css-mixins)
+  - [CSS Caveats](#css-caveats)
+- [Typescript](#typescript)
+  - [Typescript Caveats](#typescript-caveats)
+- [JSX](#jsx)
+- [JSON](#json)
+- [Phlex Support](#phlex-support)
+- [ViewComponent Support](#viewcomponent-support)
+- [Cache Busting](#cache-busting)
+- [rjs is back!](#rjs-is-back)
+- [Included Paths](#included-paths)
+- [Thanks](#thanks)
+- [Development](#development)
 
 ## Getting Started
 
 Getting started obviously depends on whether you are adding Proscenium to an existing Rails app, or creating a new Rails app. So please choose the appropriate guide below:
 
 - [Getting Started with a new Rails app](https://github.com/joelmoss/proscenium/blob/master/docs/guides/new_rails_app.md)
-- Getting Started with an existing Rails app *[Coming soon]*
+- Getting Started with an existing Rails app
+  - [Migrate from Sprockets](docs/guides/migrate_from_sprockets.md)
+  - Migrate from Propshaft *[Coming soon]*
+  - Migrate from Webpacker *[Coming soon]*
+- [Render a React component with Proscenium](docs/guides/basic_react.md)
 
 ## Installation
 
@@ -53,26 +89,83 @@ Using the examples above...
 - `app/components/menu_component.jsx` => `https://yourapp.com/app/components/menu_component.jsx`
 - `config/properties.css` => `https://yourapp.com/config/properties.css`
 
-### Include Paths
+## Side Loading
 
-By default, Proscenium will serve files ending with any of these extension: `js,mjs,ts,css,jsx,tsx`, and only from `app/assets`, `config`, `app/views`, `lib` and `node_modules` directories.
+> Prior to **0.10.0**, only assets with the extension `.js`, `.ts` and `.css` were side loaded. From 0.10.0, all assets are side loaded, including `.jsx`, and `.tsx`. Also partials were not side loaded prior to 0.10.0.
 
-However, you can customise these paths with the `include_path` config option...
+Proscenium is best experienced when you side load your assets.
 
-```ruby
-Rails.application.config.proscenium.include_paths << 'app/components'
+### The Problem
+
+With Rails you would typically declaratively load your JavaScript and CSS assets using the `javascript_include_tag` and `stylesheet_link_tag` helpers.
+
+For example, you may have top-level "application" CSS located in a file at `/app/assets/application.css`. Likewise, you may have some global JavaScript located in a file at `/app/assets/application.js`.
+
+You would include those two files in your application layout, something like this:
+
+```erb
+<%# /app/views/layouts/application.html.erb %>
+
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Hello World</title>
+    <%= stylesheet_link_tag 'application' %> <!-- << Your app CSS -->
+  </head>
+  <body>
+    <%= yield %>
+    <%= javascript_include_tag 'application' %> <!-- << Your app JS -->
+  </body>
+</html>
 ```
 
-## Side Loading
+Now, you may have some CSS and JavaScript that is only required by a specific view and partial, so you would load that in your view, something like this:
+
+```erb
+<%# /app/views/users/index.html.erb %>
+
+<%= stylesheet_link_tag 'users' %>
+<%= javascript_include_tag 'users' %>
+
+<%# needed by the `users/_user.html.erb` partial %>
+<%= javascript_include_tag '_user' %>
+
+<% render @users %>
+```
+
+The main problem is that you have to keep track of all these assets, and make sure each is loaded by all the views that require them, but also avoid loading them when not needed. This can be a real pain, especially when you have a lot of views.
+
+### The Solution
 
-Proscenium has built in support for automatically side loading JS, TS and CSS with your views and
-layouts.
+When side loading your JavaScript, Typescript and CSS with Proscenium, they are automatically included alongside your views, partials, layouts, and components, and only when needed.
 
-Just create a JS and/or CSS file with the same name as any view or layout, and make sure your
-layouts include `<%= side_load_stylesheets %>` and `<%= side_load_javascripts %>`. Something like
-this:
+Side loading works by looking for a JS/TS/CSS file with the same name as your view, partial, layout or component. For example, if you have a view at `app/views/users/index.html.erb`, then Proscenium will look for a JS/TS/CSS file at `app/views/users/index.js`, `app/views/users/index.ts` or `app/views/users/index.css`. If it finds one, it will include it in the HTML for that view.
 
-```html
+JSX is also supported for JavaScript and Typescript. Simply use the `.jsx` or `.tsx` extension instead of `.js` or `.ts`.
+
+### Usage
+
+Simply create a JS and/or CSS file with the same name as any view, partial or layout.
+
+Let's continue with our problem example above, where we have the following assets
+
+- `/app/assets/application.css`
+- `/app/assets/application.js`
+- `/app/assets/users.css`
+- `/app/assets/users.js`
+- `/app/assets/user.js`
+
+Your application layout is at `/app/views/layouts/application.hml.erb`, and the view that needs the users assets is at `/app/views/users/index.html.erb`, so move your assets JS and CSS alongside them:
+
+- `/app/views/layouts/application.css`
+- `/app/views/layouts/application.js`
+- `/app/views/users/index.css`
+- `/app/views/users/index.js`
+- `/app/views/users/_user.js` (partial)
+
+Now, in your layout and view, replace the `javascript_include_tag` and `stylesheet_link_tag` helpers with the `side_load_stylesheets` and `side_load_javascripts` helpers from Proscenium. Something like this:
+
+```erb
 <!DOCTYPE html>
 <html>
   <head>
@@ -81,20 +174,22 @@ this:
   </head>
   <body>
     <%= yield %>
-    <%= side_load_javascripts defer: true, type: 'module' %>
+    <%= side_load_javascripts type: 'module', defer: true %>
   </body>
 </html>
 ```
 
-On each page request, Proscenium will check if your layout and view has a JS/TS/CSS file of the same
-name, and include them into your layout HTML. Partials are not side loaded.
+> NOTE that Proscenium is desiged to work with modern JavaAscript, and assumes [ESModules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) are used everywhere. This is why the `type` attribute is set to `module` in the example above. If you are not using ESModules, then you can omit the `type` attribute.
+
+On each page request, Proscenium will check if your views, layouts and partials have a JS/TS/CSS file of the same name, and then include them wherever your placed the `side_load_stylesheets` and `side_load_javascripts` helpers.
 
-Side loading is enabled by default, but you can disable it by setting `config.proscenium.side_load`
-to `false`.
+Now you never have to remember to include your assets again. Just create them alongside your views, partials and layouts, and Proscenium will take care of the rest.
 
-## Importing
+Side loading is enabled by default, but you can disable it by setting `config.proscenium.side_load` to `false` in your `/config/application.rb`.
 
-Proscenium supports importing JS, JSX, TS and CSS from NPM, by URL, your local app, and even from Ruby Gems.
+## Importing Assets
+
+Proscenium supports importing JS, JSX, TS, TSX, CSS and SVG from NPM, by URL, your local app, and even from Ruby Gems.
 
 Imported files are bundled together in real time. So no build step or pre-compilation is needed.
 
@@ -134,9 +229,13 @@ import utils from '/lib/utils'
 import constants from './constants'
 ```
 
-## Import Map [WIP]
+## Import Maps
+
+> **[WIP]**
 
-[Import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) for both JS and CSS is supported out of the box, and works with no regard to the browser being used. This is because the import map is parsed and resolved by Proscenium on the server. If you are not familiar with import maps, think of it as a way to define aliases.
+[Import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) for both JS and CSS is supported out of the box, and works with no regard to the browser being used. This is because the import map is parsed and resolved by Proscenium on the server, instead of by the browser. This is faster, and also allows you to use import maps in browsers that do not support them yet.
+
+If you are not familiar with import maps, think of them as a way to define aliases.
 
 Just create `config/import_map.json` and specify the imports you want to use. For example:
 
@@ -166,7 +265,7 @@ and for CSS...
 @import '@radix-ui/colors/blue.css';
 ```
 
-You can also write your import map in Javascript instead of JSON. So instead of `config/import_map.json`, create `config/import_map.js`, and define an anonymous function. This function accepts a single `environment` argument.
+You can also write your import map in JavaScript instead of JSON. So instead of `config/import_map.json`, create `config/import_map.js`, and define an anonymous function. This function accepts a single `environment` argument.
 
 ```js
 env => ({
@@ -176,21 +275,89 @@ env => ({
 })
 ```
 
-## Importing SVG from JS(X) and TS(X)
+## Source Maps
+
+Source maps can make it easier to debug your code. They encode the information necessary to translate from a line/column offset in a generated output file back to a line/column offset in the corresponding original input file. This is useful if your generated code is sufficiently different from your original code (e.g. your original code is TypeScript or you enabled minification). This is also useful if you prefer looking at individual files in your browser's developer tools instead of one big bundled file.
+
+Source map output is supported for both JavaScript and CSS. Each file is appended with the link to the source map. For example:
+
+```js
+//# sourceMappingURL=/app/views/layouts/application.js.map
+```
+
+Your browsers dev tools should pick this up and automatically load the source map when and where needed.
 
-Importing SVG from JS(X) will bundle the SVG source code. Additionally, if importing from JSX or TSX, the SVG source code will be rendered as a JSX/TSX component.
+## SVG
+
+You can import SVG from JS(X), which will bundle the SVG source code. Additionally, if importing from JSX or TSX, the SVG source code will be rendered as a JSX/TSX component.
 
 ## Environment Variables
 
-Import any environment variables into your JS(X) code.
+> Available in `>=0.10.0`
+
+You can define and access any environment variable from your JavaScript and Typescript under the `proscenium.env` namespace.
+
+For performance and security reasons you must declare the environment variable names that you wish to expose in your `config/application.rb` file.
+
+```ruby
+config.proscenium.env_vars = Set['API_KEY', 'SOME_SECRET_VARIABLE']
+config.proscenium.env_vars << 'ANOTHER_API_KEY'
+```
+
+This assumes that the environment variable of the same name has already been defined. If not, you will need to define it yourself either in your code using Ruby's `ENV` object, or in your shell.
+
+These declared environment variables will be replaced with constant expressions, allowing you to use this like this:
 
 ```js
-import RAILS_ENV from '@proscenium/env/RAILS_ENV'
+console.log(proscenium.env.RAILS_ENV) // console.log("development")
+console.log(proscenium.env.RAILS_ENV === 'development') // console.log(true)
 ```
 
-You can only access environment variables that are explicitly named. It will export `undefined` if the env variable does not exist.
+The `RAILS_ENV` and `NODE_ENV` environment variables will always automatically be declared for you.
+
+In addition to this, Proscenium also provides a `process.env.NODE_ENV` variable, which is set to the same value as `proscenium.env.RAILS_ENV`. It is provided to support the community's existing tooling, which often relies on this variable.
 
-## Importing i18n
+Environment variables are particularly powerful in aiding [tree shaking](#tree-shaking).
+
+```js
+function start() {
+  console.log("start")
+}
+function doSomethingDangerous() {
+  console.log("resetDatabase")
+}
+
+proscenium.env.RAILS_ENV === "development" && doSomethingDangerous()
+
+start()
+```
+
+In development the above code will be transformed into the following code, discarding the definition, and call to`doSomethingDangerous()`.
+
+```js
+function start() {
+  console.log("start")
+}
+start()
+```
+
+Please note that for security reasons environment variables are not replaced in URL imports.
+
+An undefined environment variable will be replaced with `undefined`.
+
+```js
+console.log(proscenium.env.UNKNOWN) // console.log((void 0).UNKNOWN)
+```
+
+This means that code that relies on this will not be tree shaken. You can work around this by using the [optional chaining operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining):
+
+```js
+if (typeof proscenium.env?.UNKNOWN !== "undefined") {
+  // do something if UNKNOWN is defined
+}
+```
+
+## i18n
 
 Basic support is provided for importing your Rails locale files from `config/locales/*.yml`, exporting them as JSON.
 
@@ -226,6 +393,51 @@ function one() {
 one();
 ```
 
+### Code Splitting
+
+> Available in `>=0.10.0`.
+
+> #### *Experimental!* 🧪
+>
+> Code splitting is currently experimentally and limited to side loaded code. It is disabled by default. You can enable code splitting by setting the `code_splitting` configuration option to `true` in your application's `/config/application.rb`:
+>
+> ```ruby
+> config.proscenium.code_splitting = true
+> ```
+
+[Side loaded](#side-loading) assets are automatically code split. This means that if you have a file that is imported and used imported several times, and by different files, it will be split off into a separate file.
+
+As an example:
+
+```js
+// /lib/son.js
+import father from "./father";
+
+father() + " and Son";
+```
+
+```js
+// /lib/daughter.js
+import father from "./father";
+
+father() + " and Daughter";
+```
+
+```js
+// /lib/father.js
+export default () => "Father";
+```
+
+Both `son.js` and `daughter.js` import `father.js`, so both son and daughter would usually include a copy of father, resulting in duplicated code and larger bundle sizes.
+
+If these files are side loaded, then `father.js` will be split off into a separate file or chunk, and only downloaded once.
+
+- Code shared between multiple entry points is split off into a separate shared file that both entry points import. That way if the user first browses to one page and then to another page, they don't have to download all of the JavaScript for the second page from scratch if the shared part has already been downloaded and cached by their browser.
+
+- Code referenced through an asynchronous `import()` expression will be split off into a separate file and only loaded when that expression is evaluated. This allows you to improve the initial download time of your app by only downloading the code you need at startup, and then lazily downloading additional code if needed later.
+
+- Without code splitting, an import() expression becomes `Promise.resolve().then(() => require())` instead. This still preserves the asynchronous semantics of the expression but it means the imported code is included in the same bundle instead of being split off into a separate file.
+
 ### JavaScript Caveats
 
 There are a few important caveats as far as JavaScript is concerned. These are [detailed on the esbuild site](https://esbuild.github.io/content-types/#javascript-caveats).
@@ -238,7 +450,7 @@ Note that by default, Proscenium's output will take advantage of all modern CSS
 
 The new CSS nesting syntax is supported, and transformed into non-nested CSS for older browsers.
 
-### Importing from JavaScript
+### Importing CSS from JavaScript
 
 You can also import CSS from JavaScript. When you do this, Proscenium will automatically append each stylesheet to the document's head as a `<link>` element.
 
@@ -377,13 +589,15 @@ console.log(version)
 
 ## Phlex Support
 
-*docs needed*
+> *docs needed*
 
 ## ViewComponent Support
 
-*docs needed*
+> *docs needed*
+
+## Cache Busting
 
-## Cache Busting [*COMING SOON*]
+> *COMING SOON*
 
 By default, all assets are not cached by the browser. But if in production, you populate the `REVISION` env variable, all CSS and JS URL's will be appended with its value as a query string, and the `Cache-Control` response header will be set to `public` and a max-age of 30 days.
 
@@ -411,9 +625,19 @@ Proscenium brings back RJS! Any path ending in .rjs will be served from your Rai
 
 *docs needed*
 
-## Thanks 🙏
+## Included Paths
+
+By default, Proscenium will serve files ending with any of these extension: `js,mjs,ts,css,jsx,tsx`, and only from `app/assets`, `config`, `app/views`, `lib` and `node_modules` directories.
+
+However, you can customise these paths with the `include_path` config option...
+
+```ruby
+Rails.application.config.proscenium.include_paths << 'app/components'
+```
+
+## Thanks
 
-HUGE thanks go to [Evan Wallace](https://github.com/evanw) and his amazing [esbuild](https://esbuild.github.io/) project. Proscenium would not be possible without it, and it is esbuild that makes this so fast and efficient.
+HUGE thanks 🙏 go to [Evan Wallace](https://github.com/evanw) and his amazing [esbuild](https://esbuild.github.io/) project. Proscenium would not be possible without it, and it is esbuild that makes this so fast and efficient.
 
 Because Proscenium uses esbuild extensively, some of these docs are taken directly from the esbuild docs, with links back to the [esbuild site](https://esbuild.github.io/) where appropriate.
 

data/lib/proscenium/{esbuild/golib.rb → builder.rb}

@@ -4,7 +4,9 @@ require 'ffi'
 require 'oj'
 
 module Proscenium
-  class Esbuild::Golib
+  class Builder
+    class CompileError < StandardError; end
+
     class Result < FFI::Struct
       layout :success, :bool,
              :response, :string
@@ -12,24 +14,30 @@ module Proscenium
 
     module Request
       extend FFI::Library
-      ffi_lib Pathname.new(__dir__).join('../ext/proscenium').to_s
+      ffi_lib Pathname.new(__dir__).join('ext/proscenium').to_s
 
       enum :environment, [:development, 1, :test, :production]
 
       attach_function :build, [
-        :string,      # path or entry point
-        :string,      # root
+        :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
-        :environment, # Rails environment as a Symbol
         :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
-        :string       # path to import map, relative to root
+        :environment  # Rails environment as a Symbol
       ], Result.by_value
     end
 
@@ -51,29 +59,33 @@ module Proscenium
       end
     end
 
-    def initialize(root: nil, base_url: nil)
-      @root = root || Rails.root
-      @base_url = base_url
+    def self.build(path, root: nil, base_url: nil)
+      new(root: root, base_url: base_url).build(path)
     end
 
-    def self.resolve(path)
-      new.resolve(path)
+    def self.resolve(path, root: nil)
+      new(root: root).resolve(path)
     end
 
-    def self.build(path)
-      new.build(path)
+    def initialize(root: nil, base_url: nil)
+      @root = root || Rails.root
+      @base_url = base_url
     end
 
     def build(path)
-      result = Request.build(path, @root.to_s, @base_url, Rails.env.to_sym, import_map,
-                             Rails.env.development?)
+      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
 
     def resolve(path)
-      result = Request.resolve(path, @root.to_s, Rails.env.to_sym, import_map)
+      result = Request.resolve(path, import_map, @root.to_s, Rails.env.to_sym)
       raise ResolveError.new(path, result[:response]) unless result[:success]
 
       result[:response]
@@ -81,12 +93,25 @@ module Proscenium
 
     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

data/lib/proscenium/componentable.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Proscenium::Componentable
+  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
+
+    # Should the template block be forwarded as children to the React component?
+    #
+    # @return [Boolean]
+    class_attribute :forward_children, default: false
+  end
+
+  # @param props: [Hash]
+  def initialize(props: {})
+    @props = props
+
+    super()
+  end
+
+  def virtual_path
+    Proscenium::Utils.resolve_path path.sub_ext('.jsx').to_s
+  end
+
+  private
+
+  def data_attributes
+    d = {
+      proscenium_component_path: virtual_path,
+      proscenium_component_props: prepared_props
+    }
+
+    d[:proscenium_component_forward_children] = true if forward_children?
+
+    d
+  end
+
+  def props
+    @props ||= {}
+  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
+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/libs/stimulus-loading.js

@@ -0,0 +1,83 @@
+const controllerAttribute = "data-controller";
+const controllerFilenameExtension = ".js";
+
+export function lazyLoadControllersFrom(
+  under,
+  application,
+  element = document
+) {
+  lazyLoadExistingControllers(under, application, element);
+  lazyLoadNewControllers(under, application, element);
+}
+
+function lazyLoadExistingControllers(under, application, element) {
+  queryControllerNamesWithin(element).forEach((controllerName) =>
+    loadController(controllerName, under, application)
+  );
+}
+
+function lazyLoadNewControllers(under, application, element) {
+  new MutationObserver((mutationsList) => {
+    for (const { attributeName, target, type } of mutationsList) {
+      switch (type) {
+        case "attributes": {
+          if (
+            attributeName == controllerAttribute &&
+            target.getAttribute(controllerAttribute)
+          ) {
+            extractControllerNamesFrom(target).forEach((controllerName) =>
+              loadController(controllerName, under, application)
+            );
+          }
+        }
+
+        case "childList": {
+          lazyLoadExistingControllers(under, application, target);
+        }
+      }
+    }
+  }).observe(element, {
+    attributeFilter: [controllerAttribute],
+    subtree: true,
+    childList: true,
+  });
+}
+
+function queryControllerNamesWithin(element) {
+  return Array.from(element.querySelectorAll(`[${controllerAttribute}]`))
+    .map(extractControllerNamesFrom)
+    .flat();
+}
+
+function extractControllerNamesFrom(element) {
+  return element
+    .getAttribute(controllerAttribute)
+    .split(/\s+/)
+    .filter((content) => content.length);
+}
+
+function loadController(name, under, application) {
+  if (canRegisterController(name, application)) {
+    import(controllerFilename(name, under))
+      .then((module) => registerController(name, module, application))
+      .catch((error) =>
+        console.error(`Failed to autoload controller: ${name}`, error)
+      );
+  }
+}
+
+function controllerFilename(name, under) {
+  return `${under}/${name
+    .replace(/--/g, "/")
+    .replace(/-/g, "_")}_controller${controllerFilenameExtension}`;
+}
+
+function registerController(name, module, application) {
+  if (canRegisterController(name, application)) {
+    application.register(name, module.default);
+  }
+}
+
+function canRegisterController(name, application) {
+  return !application.router.modulesByIdentifier.has(name);
+}

data/lib/proscenium/log_subscriber.rb

@@ -12,12 +12,11 @@ module Proscenium
 
     def build(event)
       path = event.payload[:identifier]
-      path = path.start_with?(/https?%3A%2F%2F/) ? CGI.unescape(path) : path
+      path = CGI.unescape(path) if path.start_with?(/https?%3A%2F%2F/)
 
       info do
         message = +"[Proscenium] Building #{path}"
         message << " (Duration: #{event.duration.round(1)}ms | Allocations: #{event.allocations})"
-        message << "\n" if defined?(Rails.env) && Rails.env.development?
       end
     end
   end

data/lib/proscenium/middleware/base.rb

@@ -51,7 +51,7 @@ module Proscenium
       end
 
       def file_readable?
-        return unless (path = clean_path(sourcemap? ? real_path[0...-4] : real_path))
+        return false unless (path = clean_path(sourcemap? ? real_path[0...-4] : real_path))
 
         file_stat = File.stat(Pathname(root).join(path.delete_prefix('/').b).to_s)
       rescue SystemCallError

data/lib/proscenium/middleware/esbuild.rb

@@ -21,10 +21,10 @@ module Proscenium
 
       def attempt
         ActiveSupport::Notifications.instrument('build.proscenium', identifier: path_to_build) do
-          render_response Proscenium::Esbuild.build(path_to_build, root: root,
+          render_response Proscenium::Builder.build(path_to_build, root: root,
                                                                    base_url: @request.base_url)
         end
-      rescue Proscenium::Esbuild::CompileError => e
+      rescue Proscenium::Builder::CompileError => e
         raise self.class::CompileError, { file: @request.fullpath, detail: e.message }, caller
       end
     end

data/lib/proscenium/middleware.rb

@@ -13,12 +13,17 @@ module Proscenium
 
     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: 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

data/lib/proscenium/phlex/component_concerns.rb

@@ -5,23 +5,5 @@ module Proscenium::Phlex::ComponentConcerns
     extend ActiveSupport::Concern
     include Proscenium::CssModule
     include Proscenium::Phlex::ResolveCssModules
-
-    # class_methods do
-    #   # FIXME: Still needed?
-    #   def path
-    #     pp name, super
-    #     pp Module.const_source_location(name).first
-
-    #     name && Pathname.new(Module.const_source_location(name).first)
-    #   rescue NameError
-    #     nil
-    #   end
-    # end
-
-    private
-
-    def path
-      self.class.path
-    end
   end
 end

data/lib/proscenium/phlex/page.rb

@@ -56,7 +56,7 @@ module Proscenium::Phlex::Page
     super do
       yield if block_given?
 
-      side_load_javascripts defer: true, type: :module
+      side_load_javascripts type: :module, defer: true
     end
   end
 end

data/lib/proscenium/phlex/react_component.rb

@@ -1,69 +1,33 @@
 # frozen_string_literal: true
 
 #
-# Renders a div for use with @proscenium/component-manager.
+# Renders a <div> for use with React components, with data attributes specifying the component path
+# and props.
 #
-# 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.
+# 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.
 #
-# React components are not side loaded at all.
+# You can pass props to the component in the `:props` keyword argument.
 #
-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
-
+class Proscenium::Phlex::ReactComponent < Proscenium::Phlex
   self.abstract_class = true
 
+  include Proscenium::Componentable
   include Proscenium::Phlex::ComponentConcerns::CssModules
 
-  attr_writer :props, :lazy
-
-  # @param props: [Hash]
-  # @param lazy: [Boolean] Lazy load the component using IntersectionObserver. Default: true.
-  def initialize(props: {}, lazy: true) # rubocop:disable Lint/MissingSuper
-    @props = props
-    @lazy = lazy
-  end
-
-  # @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.
+  # Override this to provide your own loading UI.
+  #
+  # @example
+  #   def 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 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)
+    send root_tag, **{ data: data_attributes }.deep_merge(attributes), &block
   end
 end

data/lib/proscenium/railtie.rb

@@ -11,6 +11,9 @@ module Proscenium
 
   APPLICATION_INCLUDE_PATHS = ['config', 'app/assets', 'app/views', 'lib', 'node_modules'].freeze
 
+  # Environment variables that should always be passed to the builder.
+  DEFAULT_ENV_VARS = Set['RAILS_ENV', 'NODE_ENV'].freeze
+
   class << self
     def config
       @config ||= Railtie.config.proscenium
@@ -21,11 +24,18 @@ module Proscenium
     isolate_namespace Proscenium
 
     config.proscenium = ActiveSupport::OrderedOptions.new
+    config.proscenium.debug = false
     config.proscenium.side_load = true
+    config.proscenium.code_splitting = false
     config.proscenium.cache_query_string = Rails.env.production? && ENV.fetch('REVISION', nil)
     config.proscenium.cache_max_age = 2_592_000 # 30 days
     config.proscenium.include_paths = Set.new(APPLICATION_INCLUDE_PATHS)
 
+    # 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
+
     # 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,

data/lib/proscenium/side_load/ensure_loaded.rb

@@ -5,16 +5,16 @@ class Proscenium::SideLoad
     def self.included(child)
       child.class_eval do
         append_after_action do
-          if Proscenium::Current.loaded
+          if request.format.html? && 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 ' \
+              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 ' \
+              raise NotIncludedError, 'There are stylesheets to be side loaded, but they have  ' \
+                                      'notbeen included. Did you forget to add the ' \
                                       '`#side_load_stylesheets` helper in your views?'
             end
           end

data/lib/proscenium/side_load/helper.rb

@@ -2,23 +2,39 @@
 
 module Proscenium
   module SideLoad::Helper
-    def side_load_stylesheets
+    def side_load_stylesheets(**options)
       return unless Proscenium::Current.loaded
 
       out = []
       Proscenium::Current.loaded[:css].delete_if do |path|
-        out << stylesheet_link_tag(path, extname: false)
+        out << stylesheet_link_tag(path, extname: false, **options)
       end
       out.join("\n").html_safe
     end
 
-    def side_load_javascripts(**options)
+    def side_load_javascripts(**options) # rubocop:disable Metrics/AbcSize
       return unless Proscenium::Current.loaded
 
       out = []
-      Proscenium::Current.loaded[:js].delete_if do |path|
-        out << javascript_include_tag(path, extname: false, **options)
+      paths = Proscenium::Current.loaded[:js]
+
+      if Rails.application.config.proscenium.code_splitting && paths.size > 1
+        public_path = Rails.public_path.to_s
+        paths_to_build = []
+        paths.delete_if { |x| paths_to_build << x.delete_prefix('/') }
+
+        result = Proscenium::Builder.build(paths_to_build.join(';'), base_url: request.base_url)
+        result.split(';').each do |x|
+          next if x.include?('public/assets/_asset_chunks/') || x.end_with?('.map')
+
+          out << javascript_include_tag(x.delete_prefix(public_path), extname: false, **options)
+        end
+      else
+        paths.delete_if do |x|
+          out << javascript_include_tag(x, extname: false, **options)
+        end
       end
+
       out.join("\n").html_safe
     end
   end

data/lib/proscenium/side_load/monkey.rb

@@ -18,7 +18,6 @@ class Proscenium::SideLoad
           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
@@ -26,7 +25,6 @@ class Proscenium::SideLoad
             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
 
@@ -37,6 +35,16 @@ class Proscenium::SideLoad
     module PartialRenderer
       private
 
+      def render_partial_template(view, locals, template, layout, block)
+        if template.respond_to?(:virtual_path) &&
+           template.respond_to?(:type) && template.type == :html
+          Proscenium::SideLoad.append "app/views/#{layout.virtual_path}" if layout
+          Proscenium::SideLoad.append "app/views/#{template.virtual_path}"
+        end
+
+        super
+      end
+
       def build_rendered_template(content, template)
         path = Rails.root.join('app', 'views', template.virtual_path)
         cssm = Proscenium::CssModule::Resolver.new(path)

data/lib/proscenium/side_load.rb

@@ -12,10 +12,11 @@ module Proscenium
 
     EXTENSIONS = %i[js css].freeze
     EXTENSION_MAP = {
+      '.module.css' => :css,
       '.css' => :css,
-      # '.tsx' => :js,
+      '.tsx' => :js,
       '.ts' => :js,
-      # '.jsx' => :js,
+      '.jsx' => :js,
       '.js' => :js
     }.freeze
 

data/lib/proscenium/version.rb

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

data/lib/proscenium/view_component/react_component.rb

@@ -1,34 +1,21 @@
 # frozen_string_literal: true
 
 #
-# Renders HTML markup suitable for use with @proscenium/component-manager.
+# Renders a <div> for use with React components, with data attributes specifying the component path
+# and props.
 #
 # 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.
+# "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.
 #
 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
-
-    super
-  end
+  include Proscenium::Componentable
 
   def call
-    tag.div class: ['componentManagedByProscenium', css_module(:component)],
-            data: { component: { path: virtual_path, props: props, lazy: lazy } } do
+    tag.send root_tag, data: data_attributes do
       tag.div content || 'loading...'
     end
   end

data/lib/proscenium/view_component.rb

@@ -10,10 +10,17 @@ class Proscenium::ViewComponent < ViewComponent::Base
   autoload :ReactComponent
 
   # 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.
+  # 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_render
       klass = self.class
+
+      if !klass.abstract_class && respond_to?(:side_load, true)
+        side_load
+        klass = klass.superclass
+      end
+
       while !klass.abstract_class && klass.respond_to?(:path) && klass.path
         Proscenium::SideLoad.append klass.path
         klass = klass.superclass

data/lib/proscenium.rb

@@ -9,10 +9,11 @@ module Proscenium
   autoload :Middleware
   autoload :SideLoad
   autoload :CssModule
+  autoload :Componentable
   autoload :ViewComponent
   autoload :Phlex
   autoload :Helper
-  autoload :Esbuild
+  autoload :Builder
 
   def self.reset_current_side_loaded
     Current.reset
@@ -59,7 +60,7 @@ module Proscenium
         relpath = path.delete_prefix(sroot)
 
         if (package_name = matched_gem[1][:package_name] || matched_gem[0])
-          return Esbuild::Golib.resolve("#{package_name}/#{relpath}")
+          return Builder.resolve("#{package_name}/#{relpath}")
         end
 
         # TODO: manually resolve the path without esbuild
@@ -68,7 +69,7 @@ module Proscenium
 
       return path.delete_prefix(Rails.root.to_s) if path.starts_with?("#{Rails.root}/")
 
-      Esbuild::Golib.resolve(path)
+      Builder.resolve(path)
     end
 
     # Resolves CSS class `names` to CSS module names. Each name will be converted to a CSS module

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: proscenium
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: arm64-darwin
 authors:
 - Joel Moss
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-11 00:00:00.000000000 Z
+date: 2023-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -72,34 +72,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-- !ruby/object:Gem::Dependency
-  name: phlex
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.8.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.8.1
-- !ruby/object:Gem::Dependency
-  name: phlex-rails
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -131,15 +103,16 @@ files:
 - LICENSE.txt
 - README.md
 - lib/proscenium.rb
+- lib/proscenium/builder.rb
+- lib/proscenium/componentable.rb
 - lib/proscenium/css_module.rb
 - lib/proscenium/css_module/class_names_resolver.rb
 - lib/proscenium/css_module/resolver.rb
 - lib/proscenium/current.rb
-- lib/proscenium/esbuild.rb
-- lib/proscenium/esbuild/golib.rb
 - lib/proscenium/ext/proscenium
 - lib/proscenium/ext/proscenium.h
 - lib/proscenium/helper.rb
+- lib/proscenium/libs/stimulus-loading.js
 - lib/proscenium/log_subscriber.rb
 - lib/proscenium/middleware.rb
 - lib/proscenium/middleware/base.rb

data/lib/proscenium/esbuild.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Proscenium
-  class Esbuild
-    class CompileError < StandardError; end
-
-    extend ActiveSupport::Autoload
-
-    autoload :Golib
-
-    def self.build(...)
-      new(...).build
-    end
-
-    def initialize(path, root:, base_url:)
-      @path = path
-      @root = root
-      @base_url = base_url
-    end
-
-    def build
-      Proscenium::Esbuild::Golib.new(root: @root, base_url: @base_url).build(@path)
-    end
-
-    private
-
-    def cache_query_string
-      q = Proscenium.config.cache_query_string
-      q ? "--cache-query-string #{q}" : nil
-    end
-  end
-end