proscenium 0.1.0.alpha2-arm64-darwin → 0.1.0.alpha4-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8247c82996a679f10da36d65c389e07ae4bad1b1399168338ffd937401b1cc6
-  data.tar.gz: 113eeee3890bc5e35ed8c114d209f365fea71f6f3c6b87e1dffbef359208973d
+  metadata.gz: 3ac83bfca343680535bf4f188a9e74db2848752cda2708f323a175215d508a1c
+  data.tar.gz: ba7d653af25382437e4aa3870f5be2f02731da51828080c01eddcdb370f58de9
 SHA512:
-  metadata.gz: faa3d8d5a0986b1b58b4bc0452dfd4e4144cf1517651fa416c487e7c155dbd67eea7d7a5fc0d583ad93226edfc5de4271cfd2bdfb6fa7bd1f3eb3071c816bfb9
-  data.tar.gz: 522e92bbe7193632ed084eb69344408e1085319ff99a76c1c7994414038c6512324c3cc0e2e4dcc3d3ba91fab042fc8be9cf325fcda0264e734e631d58a205ca
+  metadata.gz: f1ee7d5ca80dd3ada1436934df8302cbb091e0eca24f9be66417b529a47a574edd46bae4e3b00a643f0eeab0af80a72d2fdebd174b2403aab56de59df4ccb02b
+  data.tar.gz: 686685bd60968269a7e286a965f7aeab153e5202136d881f875586f8c64eade642e51f405b4d1a92a88be04dea85e7ba3d07b94900ce582cd8d3372bbea16c65

data/README.md

@@ -1,65 +1,250 @@
-# Proscenium
-
-- Serve assets from anywhere within the Rails root. (eg. `/app/views/layouts/application.css`, `/lib/utils/time.js`)
-- Side loaded JS/CSS for your layouts and views.
-- JS imports
-- Dynamic imports
-- Real-time bundling of JS, JSX and CSS.
-- Import CSS and other static assets (images, fonts, etc.)
-
-## WANT
-
-- Nested CSS
-- Import CSS Modules
+# Proscenium - Modern Client-Side Tooling for Rails
+
+Proscenium treats your client-side code as first class citizens of your Rails app, and assumes a
+"fast by default" internet. It compiles your JS, JSX and CSS in real time, and on demand, with no
+configuration at all!
+
+- Zero configuration.
+- NO JavaScript rumtime needed - just the browser!
+- Real-time compilation.
+- No additional process or server - Just run Rails!
+- Serve assets from anywhere within your Rails root (/app, /config, /lib).
+- Automatically side load JS/CSS for your layouts and views.
+- Import JS(X) and CSS from node_modules, URL, local (relative, absolute).
+- Optional bundling of JS(X) and CSS.
+- Import Map support for JS and CSS.
+- CSS Modules.
+- CSS Custom Media Queries.
+- CSS mixins.
+- Minification.
+- Auto reload after changes (development only).
+
+## !! EXPERIMENTAL SOFTWARE !!
+
+While my goal is to use Proscenium in production, I strongly recommended that you **DO NOT** use
+this in production apps! Right now, this is a play thing, and should only be used for
+development/testing.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application's Gemfile, and you're good to go:
 
 ```ruby
 gem 'proscenium'
 ```
 
-## Usage
+## Frontend Code Anywhere!
+
+Proscenium believes that your frontend code is just as important as your backend code, and is not an
+afterthought - they should be first class citizens of your Rails app. So instead of throwing all
+your JS and CSS into a "app/assets" directory, put them wherever you want!
+
+For example, if you have JS that is used by your `UsersController#index`, then put it in
+`app/views/users/index.js`. Or if you have some CSS that is used by your entire application, put it
+in `app/views/layouts/application.css`. Maybe you have a few JS utility functions, so put them in
+`lib/utils.js`.
+
+Simply create your JS(X) and CSS anywhere you want, and they will be served by your Rails app.
+
+Using the examples above...
+
+- `app/views/users/index.js` => `https://yourapp.com/app/views/users/index.js`
+- `app/views/layouts/application.css` => `https://yourapp.com/app/views/layouts/application.css`
+- `lib/utils.js` => `https://yourapp.com/lib/utils.js`
+- `config/properties.css` => `https://yourapp.com/config/properties.css`
+
+## Importing
+
+Proscenium supports importing JS and CSS from `node_modules`, URL, and local (relative, absolute).
+
+Imports are assumed to be JS files, so there is no need to specify the file extesnion in such cases.
+But you can if you like. All other file types must be specified using their full file name and
+extension.
+
+### URL Imports
+
+Any import beginning with `http://` or `https://` will be fetched from the URL provided:
+
+```js
+import React from 'https://esm.sh/react`
+```
+
+```css
+@import 'https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css';
+```
+
+### Import from NPM (`node_modules`)
+
+Bare imports (imports not beginning with `./`, `/`, `https://`, `http://`) are fully supported, and
+will use your package manager of choice (eg, NPM, Yarn, pnpm):
+
+```js
+import React from 'react`
+```
+
+### Local Imports
+
+And of course you can import your own code, using relative or absolute paths (file extension is
+optional):
+
+```js /app/views/layouts/application.js
+import utils from '/lib/utils'
+```
+
+```js /lib/utils.js
+import constants from './constants'
+```
+
+## Bundling
+
+Proscenium does not do any bundling, as we believe that **the web is now fast by default**. So we
+let you decide if and when to bundle your code using query parameters in your JS and CSS imports.
+
+```js
+import doStuff from 'stuff?bundle'
+doStuff()
+```
+
+Bundling a URL import is not supported, as the URL itself may also support query parameters,
+resulting in conflicts. For example, esm.sh also supports a `?bundle` param, bundling a module's
+dependencies into a single file. Instead, you should install the module locally using your favourite
+package manager.
+
+## Import Map
+
+Import map for both JS and CSS is supported out of the box, and works with no regard to the browser
+version being used. Just create `config/import_map.json`:
+
+```json
+{
+  "imports": {
+    "react": "https://esm.sh/react@18.2.0",
+    "start": "/lib/start.js",
+    "common": "/lib/common.css",
+    "@radix-ui/colors/": "https://esm.sh/@radix-ui/colors@0.1.8/",
+  }
+}
+```
+
+Using the above import map, we can do...
+
+```js
+import { useCallback } from 'react'
+import startHere from 'start'
+import styles from 'common'
+```
+
+and for CSS...
+
+```css
+@import 'common';
+@import '@radix-ui/colors/blue.css';
+```
+
+You can instead 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 => ({
+  imports: {
+    react: env === 'development' ? 'https://esm.sh/react@18.2.0?dev' : 'https://esm.sh/react@18.2.0'
+  }
+})
+```
 
-### Side Loading
+## Side Loading
 
-Proscenium has built in support for automatically side loading JS and CSS with your views and layouts.
+Proscenium has built in support for automatically side loading JS and CSS with your views and
+layouts.
 
-Just create a JS and/or CSS file with the same name as any view or layout, and make sure your layouts include `<%= yield :side_loaded_js %>` and `<%= yield :side_loaded_css %>`. Something like this:
+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:
 
 ```html
 <!DOCTYPE html>
 <html>
   <head>
     <title>Hello World</title>
-    <%= yield :side_loaded_css %>
+    <%= side_load_stylesheets %>
   </head>
   <body>
-    <%= yield %> <%= yield :side_loaded_js %>
+    <%= yield %>
+    <%= side_load_javascripts defer: true, type: 'module' %>
   </body>
 </html>
 ```
 
-On each page request, Proscenium will check if your layout and view has a JS/CSS file of the same name, and include them into your layout HTML.
+On each page request, Proscenium will check if your layout and view has a JS/CSS file of the same
+name, and include them into your layout HTML. Partials are not side loaded.
+
+Side loading is enabled by default, but you can disable it by setting `config.proscenium.side_load`
+to `false`.
 
-### Importing in JS with `import`
+## CSS Modules
 
-Imports that do not begin with a `./` or `/` are bare imports, and will import a package using your local Node resolution algorithm.
+Give any CSS file a `.module.css` extension, and Proscenium will load it as a CSS Module...
 
-`import 'react'`
-`import React as * from 'react'`
-`import { useState } from 'react'`
+```css
+.header {
+  background-color: #00f;
+}
+```
+
+The above produces:
 
-Absolute and relative import paths are supported (`/*`, `./*`), and will behave as you would expect.
+```css
+.header5564cdbb {
+  background-color: #00f;
+}
+```
 
-Imports are assumed to be JS files, so there is no need to specify the file extesnion in such cases. But you can if you like. All other file types must be specified using their fill file name and extension.
+Importing a CSS file from JS will automatically append the stylesheet to the document's head. The
+results of the import will be an object of CSS modules.
 
-### CSS
+```js
+import styles from './styles.module.css'
+```
 
-Direct access to CSS files are parsed through @parcel/css.
+## Auto Reload
 
-Importing a CSS file from JS will append the CSS file to the document's head. The results of the import will be an object of CSS modules.
+To aid fast development, Proscenium comes with an auto reload feature that will automatically reload
+the page when any files changes. It is enabled by default in development, and requires that you
+mount the Proscenium Railtie into your `config/routes.rb` file:
+
+```ruby
+mount Proscenium::Railtie, at: '/proscenium' if Rails.env.development?
+```
+
+Changes to CSS/JS(X) files in your `app` and `lib` directories will cause the page to reload.
+
+NOTE: that this is hot module reloading (HMR) - a full page reload is triggered.
+
+You can disable auto reload by setting the `config.proscenium.auto_reload` config option to false.
+
+## CSS Custom Media Queries
+
+Proscenium supports [custom media queries](https://css-tricks.com/can-we-have-custom-media-queries-please/) as per the [spec](https://www.w3.org/TR/mediaqueries-5/#custom-mq). However, because of the way they are parsed, they cannot be imported using `@import`. So if you define your custom media queries in `/config/custom_media_queries.css`, Proscenium will automatically inject them into your CSS, so you can use them anywhere.
+
+## CSS Mixins
+
+CSS mixins are supported using the `@mixin` at-rule. Simply define your mixins in any number of files ending in `.mixin.css`, and using the `@define-mixin` at-rule...
+
+```css
+// /lib/text.mixin.css
+@define-mixin bigText {
+  font-size: 50px;
+}
+```
+
+```css
+// /app/views/layouts/application.css
+p {
+  @mixin bigText;
+  color: red;
+}
+```
 
 ## How It Works
 
@@ -77,7 +262,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 `deno compile --no-config -o bin/compilers/esbuild --import-map import_map.json -A lib/proscenium/compilers/esbuild.js`
 
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/joelmoss/proscenium. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/joelmoss/proscenium/blob/master/CODE_OF_CONDUCT.md).

data/app/components/react_component.rb

@@ -1,14 +1,21 @@
 # frozen_string_literal: true
 
 class ReactComponent < ApplicationComponent
-  attr_accessor :props
+  attr_accessor :props, :lazy
 
-  def initialize(props = {})
+  # @param props: [Hash]
+  # @param lazy: [Boolean] Lazy load the component using IntersectionObserver. Default: true.
+  def initialize(props: {}, lazy: true)
     @props = props
+    @lazy = lazy
+
     super
   end
 
   def call
-    tag.div data: { component: { path: virtual_path, props: @props } }
+    tag.div class: ['componentManagedByProscenium', css_module(:component)],
+            data: { component: { path: virtual_path, props: props, lazy: lazy } } do
+      tag.div content
+    end
   end
 end

data/config/routes.rb

@@ -1,5 +1,5 @@
 Proscenium::Railtie.routes.draw do
-  if Proscenium.config.auto_refresh
+  if Proscenium.config.auto_reload
     mount Proscenium::Railtie.websocket => Proscenium.config.cable_mount_path
   end
 end

data/lib/proscenium/compilers/esbuild/compile_error.js

@@ -0,0 +1,147 @@
+export default function () {
+  if (Deno.env.get('RAILS_ENV') === 'development') {
+    return function (detail) {
+      const template = `
+        <style>
+          :host {
+            position: fixed;
+            z-index: 99999;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            overflow-y: scroll;
+            margin: 0;
+            background: rgba(0, 0, 0, 0.66);
+            display: flex;
+            align-items: center;
+            --monospace: 'SFMono-Regular', Consolas,
+                        'Liberation Mono', Menlo, Courier, monospace;
+            --red: #ff5555;
+            --yellow: #e2aa53;
+            --purple: #cfa4ff;
+            --cyan: #2dd9da;
+            --dim: #c9c9c9;
+          }
+          
+          .window {
+            font-family: var(--monospace);
+            line-height: 1.5;
+            width: 800px;
+            color: #d8d8d8;
+            margin: 30px auto;
+            padding: 25px 40px;
+            position: relative;
+            background: #181818;
+            border-radius: 6px 6px 8px 8px;
+            box-shadow: 0 19px 38px rgba(0,0,0,0.30), 0 15px 12px rgba(0,0,0,0.22);
+            overflow: hidden;
+            border-top: 8px solid var(--red);
+          }
+          
+          pre {
+            font-family: var(--monospace);
+            font-size: 16px;
+            margin: 0 0 1em 0;
+            overflow-x: scroll;
+            scrollbar-width: none;
+          }
+
+          pre::-webkit-scrollbar {
+            display: none;
+          }
+
+          .title, .message {
+            line-height: 1.3;
+            font-weight: 600;
+            white-space: pre-wrap;
+          }
+          
+          .message-body {
+            color: var(--red);
+          }
+
+          .file {
+            color: var(--cyan);
+            margin-bottom: 0;
+            white-space: pre-wrap;
+            word-break: break-all;
+          }
+
+          .code {
+            background: black;
+            border-left: 3px solid gray;
+            padding: 10px 0 0 20px;
+          }
+          .lineText {
+            display: block;
+            white-space: pre-wrap;
+          }
+          .lineCursor {
+            white-space: pre;
+            color: blueviolet;
+            display: block;
+          }
+        </style>
+        <div class="window">
+          <pre class="title">COMPILE ERROR!</pre>
+          <pre class="message"><span class="message-body"></span> in <span class="file"></span></pre>
+          <pre class="code"><span class="lineText"></span><span class="lineCursor"></span></pre>
+        </div>
+      `
+
+      class ErrorOverlay extends HTMLElement {
+        constructor(err) {
+          super()
+
+          this.root = this.attachShadow({ mode: 'open' })
+          this.root.innerHTML = template
+          this.root.querySelector('.message-body').textContent = err.text.trim()
+          if (err.location) {
+            const location = [err.location.file]
+            err.location.line && location.push(err.location.line)
+            err.location.column && location.push(err.location.column)
+            this.root.querySelector('.file').textContent = `/${location.join(':')}`
+
+            if (err.location.lineText) {
+              this.root.querySelector('.lineText').textContent = err.location.lineText
+              this.root.querySelector('.lineCursor').textContent =
+                ''.padStart(err.location.column - 1, ' ') + '^'
+            } else {
+              this.root.querySelector('.code').remove()
+            }
+
+            console.error('%s at %O', err.text, location)
+          } else {
+            console.error(err.text)
+          }
+
+          this.root.querySelector('.window').addEventListener('click', e => {
+            e.stopPropagation()
+          })
+
+          this.addEventListener('click', () => {
+            this.close()
+          })
+        }
+
+        close() {
+          this.parentNode?.removeChild(this)
+        }
+      }
+
+      const overlayId = 'proscenium-error-overlay'
+      if (customElements && !customElements.get(overlayId)) {
+        customElements.define(overlayId, ErrorOverlay)
+      }
+
+      document.body.appendChild(new ErrorOverlay(detail))
+    }
+  } else {
+    return function (detail) {
+      const location = `/${detail.location.file}:${detail.location.line}:${detail.location.column}`
+      console.error('%s at %O', detail.text, location)
+      throw `${detail.text} at ${location}`
+    }
+  }
+}

data/lib/proscenium/compilers/esbuild/css/postcss.js

@@ -0,0 +1,67 @@
+import { expandGlob } from 'std/fs/mod.ts'
+import postcss, { CssSyntaxError } from 'postcss'
+
+export default async (root, path) => {
+  let tmpFile
+  let contents
+
+  const mixinFiles = []
+  for await (const file of expandGlob(`lib/**/*.mixin.css`, { root })) {
+    mixinFiles.push(file.path)
+  }
+
+  // Only process mixins with PostCSS if there are any 'lib/**/*.mixin.css' files.
+  if (mixinFiles.length > 0) {
+    tmpFile = await Deno.makeTempFile()
+    contents = await Deno.readTextFile(path)
+
+    const result = await postcss([mixinsPlugin({ mixinFiles })]).process(contents, { from: path })
+    contents = result.css
+  }
+
+  return [tmpFile, contents]
+}
+
+const mixinsPlugin = (opts = {}) => {
+  return {
+    postcssPlugin: 'mixins',
+
+    prepare() {
+      const mixins = {}
+
+      return {
+        async Once(_, helpers) {
+          for (const path of opts.mixinFiles) {
+            const content = await Deno.readTextFile(path)
+            const root = helpers.parse(content, { from: path })
+
+            root.walkAtRules('define-mixin', atrule => {
+              mixins[atrule.params] = atrule
+            })
+          }
+        },
+
+        AtRule: {
+          mixin: (rule, helpers) => {
+            const mixin = mixins[rule.params]
+
+            if (!mixin) {
+              throw rule.error(`Undefined mixin '${rule.params}'`)
+            }
+
+            const proxy = new helpers.Root()
+            for (let i = 0; i < mixin.nodes.length; i++) {
+              const node = mixin.nodes[i].clone()
+              delete node.raws.before
+              proxy.append(node)
+            }
+
+            rule.parent.insertBefore(rule, proxy)
+
+            if (rule.parent) rule.remove()
+          }
+        }
+      }
+    }
+  }
+}