proscenium 0.1.0.alpha2-x86_64-darwin → 0.1.0.alpha3-x86_64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d33e162bf11cfad365e816b4dbb6b414af4e27554a9a241a68f0e511d3304120
-  data.tar.gz: a308f22364895470325ec64ef039ce57d635228c0c38af2b05f26905c23f5b10
+  metadata.gz: 1ead562a986b1202c37134ed480888b71eb54704383c611f676c11fef0bbc2b5
+  data.tar.gz: '081ebe2a6cbc7bef601d1b698a00e01e371c9fd3fd35f2b2a8dad3da3284b6f3'
 SHA512:
-  metadata.gz: c602130d2ceb6a3fb19f3eff6c90c433903f7727aca48d0f474c6ee0b8863a3f7ba355572a4f06fa2005b3f00d708a9c374f061c6314991630558ba177c6ec3d
-  data.tar.gz: 77205b53c2bbbf504724c82dc44f745f8268469f68b2f955d3a6a85bf9c45402cf1559054a4e23bae419d7b57340a07be5fa6db81b904d7b7bb133b282639b4c
+  metadata.gz: 6e38c959ead1d73f71f12f9aee51535e8753941288b82f736e36e378dd44874ee16bb20bb3f02540b8a72a2d36204b6df64e1f026f76bdf109a7003508106360
+  data.tar.gz: 2b338f1f1eec4abce62b2d9369502f9c3feb32c4b6adba48214cd146ea2d3737955a0afa6e7973e92a44266a9900e37107f7d2d765fffcba0d2aa15889330db8

data/README.md

@@ -1,65 +1,195 @@
 # 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
+- Serve assets from anywhere within your Rails root.
+- Automatically side load JS/CSS for your layouts and views.
+- Import JS and CSS from node_modules, URL, local (relative, absolute)
 - Real-time bundling of JS, JSX and CSS.
-- Import CSS and other static assets (images, fonts, etc.)
-
-## WANT
-
-- Nested CSS
-- Import CSS Modules
+- Import Map
+- CSS Modules
+- Minification
 
 ## 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`
+
+## 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
 
-### Side Loading
+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.
 
-Proscenium has built in support for automatically side loading JS and CSS with your views and layouts.
+```js
+import doStuff from 'stuff?bundle'
+doStuff()
+```
 
-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:
+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
+
+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 `<%= 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.
 
-### Importing in JS with `import`
+Side loading is enabled by default, but you can disable it by setting `config.proscenium.side_load`
+to `false`.
 
-Imports that do not begin with a `./` or `/` are bare imports, and will import a package using your local Node resolution algorithm.
+## CSS Modules
 
-`import 'react'`
-`import React as * from 'react'`
-`import { useState } from 'react'`
+Direct access to CSS files are parsed through @parcel/css.
 
-Absolute and relative import paths are supported (`/*`, `./*`), and will behave as you would expect.
+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.
 
-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.
+## Auto Reload
 
-### CSS
+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:
 
-Direct access to CSS files are parsed through @parcel/css.
+```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.
 
-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.
+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.
 
 ## How It Works
 
@@ -77,7 +207,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/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,145 @@
+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 {
+            white-space: pre-wrap;
+          }
+          .lineCursor {
+            white-space: pre;
+            color: blueviolet;
+          }
+        </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_plugin.js

@@ -0,0 +1,76 @@
+import { crypto } from 'std/crypto/mod.ts'
+import { join, resolve, dirname, fromFileUrl } from 'std/path/mod.ts'
+
+import setup from './setup_plugin.js'
+
+export default setup('css', async build => {
+  const cwd = build.initialOptions.absWorkingDir
+  const parcelBin = resolve(dirname(fromFileUrl(import.meta.url)), '../../../../bin/parcel_css')
+
+  let customMedia
+  try {
+    customMedia = await Deno.readTextFile(join(cwd, 'config', 'custom_media_queries.css'))
+  } catch {
+    // do nothing, as we don't require custom media.
+  }
+
+  return [
+    {
+      type: 'onLoad',
+      filter: /\.css$/,
+      namespace: 'file',
+      async callback(args) {
+        let path = args.path
+        const isCssModule = args.path.endsWith('.module.css')
+        let cmd = [parcelBin, '--nesting', '--targets', '>= 0.25%']
+
+        if (customMedia) {
+          cmd.push('--custom-media')
+
+          path = await Deno.makeTempFile()
+          await Deno.writeTextFile(path, (await Deno.readTextFile(args.path)) + customMedia)
+        }
+
+        if (isCssModule) {
+          const hash = await digest(args.path.slice(cwd.length))
+          cmd = cmd.concat(['--css-modules', '--css-modules-pattern', `[local]${hash}`])
+        }
+
+        const p = Deno.run({
+          cmd: [...cmd, path],
+          stdout: 'piped',
+          stderr: 'piped'
+        })
+
+        const { code } = await p.status()
+        const rawOutput = await p.output()
+        const rawError = await p.stderrOutput()
+
+        // Even though Deno docs say that reading the outputs (above) closes their pipes, warnings
+        // are raised during tests that the child process have not been closed. So we manually close
+        // here.
+        p.close()
+
+        if (code === 0) {
+          const contents = new TextDecoder().decode(rawOutput)
+          return { loader: 'css', contents: isCssModule ? JSON.parse(contents).code : contents }
+        } else {
+          const errorString = new TextDecoder().decode(rawError)
+          throw errorString
+        }
+      }
+    }
+  ]
+})
+
+async function digest(value) {
+  value = new TextEncoder().encode(value)
+  const view = new DataView(await crypto.subtle.digest('SHA-1', value))
+
+  let hexCodes = ''
+  for (let index = 0; index < view.byteLength; index += 4) {
+    hexCodes += view.getUint32(index).toString(16).padStart(8, '0')
+  }
+
+  return hexCodes.slice(0, 8)
+}

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

@@ -1,15 +1,17 @@
 import setup from './setup_plugin.js'
 
 export default setup('env', () => {
-  return {
-    onResolve: {
+  return [
+    {
+      type: 'onResolve',
       filter: /^env$/,
       callback({ path }) {
         return { path, namespace: 'env' }
       }
     },
 
-    onLoad: {
+    {
+      type: 'onLoad',
       filter: /.*/,
       namespace: 'env',
       callback() {
@@ -17,5 +19,5 @@ export default setup('env', () => {
         return { loader: 'json', contents: JSON.stringify(env) }
       }
     }
-  }
+  ]
 })

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

@@ -0,0 +1,53 @@
+import setup from './setup_plugin.js'
+
+export default setup('httpBundle', () => {
+  return [
+    {
+      type: 'onResolve',
+      filter: /^https?:\/\//,
+      callback(args) {
+        let queryParams, suffix
+        if (args.path.includes('?')) {
+          const [path, query] = args.path.split('?')
+          queryParams = new URLSearchParams(query)
+          suffix = `?${query}`
+          args.path = path
+        }
+
+        if (queryParams?.has('bundle')) {
+          return { path: args.path, namespace: 'httpBundle', suffix }
+        } else {
+          return { external: true }
+        }
+      }
+    },
+
+    // Intercept all import paths inside downloaded files and resolve them against the original URL.
+    {
+      type: 'onResolve',
+      filter: /.*/,
+      namespace: 'httpBundle',
+      callback(args) {
+        return {
+          path: new URL(args.path, args.importer).toString(),
+          namespace: 'httpBundle'
+        }
+      }
+    },
+
+    // Download and return the content.
+    //
+    // TODO: cache this!
+    {
+      type: 'onLoad',
+      filter: /.*/,
+      namespace: 'httpBundle',
+      async callback(args) {
+        const textResponse = await fetch(args.path)
+        const contents = await textResponse.text()
+
+        return { contents }
+      }
+    }
+  ]
+})

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

@@ -0,0 +1,59 @@
+import { join } from 'std/path/mod.ts'
+import { parseFromString } from 'import-maps/resolve'
+
+const baseURL = new URL('file://')
+
+class ImportMapError extends Error {
+  constructor(fileName, ...params) {
+    super(...params)
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ImportMapError)
+    }
+
+    this.name = 'ImportMapError'
+    this.file = fileName
+  }
+}
+
+export function readImportMap(fileName, rootDir) {
+  let importMap
+
+  if (fileName) {
+    importMap = readFile(fileName, rootDir, true)
+  } else {
+    fileName = ['config/import_map.json', 'config/import_map.js'].find(f => {
+      const result = readFile(f, rootDir)
+      if (result) {
+        importMap = result
+        return true
+      }
+    })
+  }
+
+  return importMap
+}
+
+function readFile(file, rootDir, required = false) {
+  let contents = null
+
+  try {
+    contents = Deno.readTextFileSync(join(rootDir, file))
+  } catch (error) {
+    if (required) {
+      throw new ImportMapError(file, error.message, { cause: error })
+    }
+  }
+
+  if (contents === null) return null
+
+  try {
+    if (file.endsWith('.js')) {
+      contents = JSON.stringify(eval(contents)(Deno.env.get('RAILS_ENV')))
+    }
+
+    return parseFromString(contents, baseURL)
+  } catch (error) {
+    throw new ImportMapError(file, error.message, { cause: error })
+  }
+}