proscenium 0.7.0-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da3515fcd067a9196ab1efa8b0317f529ad3d8d0ba01ed81fe3d6c3a00f27788
+  data.tar.gz: 3ca2bfd945a9919fb51a16b884b888e85766ad71fedbe67341043737c7fe2e58
+SHA512:
+  metadata.gz: 82021604ea289ac9f9ff3a873c355a4e800c65b3a67efcc2245a77a53c69e5f38b50205164e86efebbbb2ebeb896e6dbd3082b9b445940141f21e00b3b5fc9fc
+  data.tar.gz: 25736d64cff191fac8fb1e842f09a5bbc9707a6700ace76cf1ed13985a07be9aaa4e419bf44779dc5a880409c9f3ea840d57fd2ab1f89a3a07e48b4438344101

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at joel@developwithstyle.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Joel Moss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,336 @@
+# 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 bundles your JS, JSX and CSS in real time, on demand, and with zero
+configuration.
+
+- Zero configuration.
+- Fast real-time bundling, tree-shaking and minification.
+- NO JavaScript runtime - just the browser!
+- Deep integration with Rails.
+- No additional process or server - Just run Rails!
+- Serve assets from anywhere within your Rails root (/app, /config, /lib, etc.).
+- Automatically side load JS/CSS for your layouts and views.
+- Import JS(X), TS(X) and CSS from NPM, URL, and locally.
+- Support for JSX.
+- Server-side import map support.
+- CSS Modules.
+- CSS mixins.
+- Source maps.
+- Phlex and ViewComponent integration.
+
+## ⚠️ WORK IN PROGRESS ⚠️
+
+While my goal is to use Proscenium in production, I recommended that you **DO NOT** use Proscenium in production just yet! It has only been run for local development, and requires several improvements for optimal production use.
+
+## Installation
+
+Add this line to your Rails application's Gemfile, and you're good to go:
+
+```ruby
+gem 'proscenium'
+```
+
+Please note that Proscenium is designed solely for use with Rails, so will not work - at least out of the box - anywhere else.
+
+## Client-Side 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 having to throw all your JS and CSS into a "app/assets" directory, and then requiring a separate process to compile or bundle, just put them wherever you want within your app, and just run Rails!
+
+For example, if you have some JS that is required by your `app/views/users/index.html.erb` view, just create a JS file alongside it at `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` and load it alongside your layout. Maybe you have a few JS utility functions, so put them in `lib/utils.js`.
+
+Simply put your JS(X) and CSS anywhere you want, and they will be served by your Rails app from the location where you placed them.
+
+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`
+- `app/components/menu_component.jsx` => `https://yourapp.com/app/components/menu_component.jsx`
+- `config/properties.css` => `https://yourapp.com/config/properties.css`
+
+## Importing
+
+Proscenium supports importing JS, JSX, TS and CSS 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.
+
+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. For example:
+
+```js
+import React from 'https://esm.sh/react'
+```
+
+```css
+@import 'https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css';
+```
+
+URL imports are cached, so that each import is only fetched once per server restart.
+
+### 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) via the `package.json` file:
+
+```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'
+```
+
+## Import Map [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.
+
+Just create `config/import_map.json` and specify the imports you want to use. For example:
+
+```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 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 => ({
+  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>
+    <%= side_load_stylesheets %>
+  </head>
+  <body>
+    <%= 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. Partials are not side loaded.
+
+Side loading is enabled by default, but you can disable it by setting `config.proscenium.side_load`
+to `false`.
+
+## CSS Modules
+
+Proscenium implements a subset of [CSS Modules](https://github.com/css-modules/css-modules). It supports the `:local` and `:global` keywords, but not the `composes` property. It is recommended that you use mixins instead of `composes`, as they work everywhere.
+
+Give any CSS file a `.module.css` extension, and Proscenium will load it as a CSS Module...
+
+```css
+.header {
+  background-color: #00f;
+}
+```
+
+The above input produces:
+
+```css
+.header5564cdbb {
+  background-color: #00f;
+}
+```
+
+Importing a CSS file from JS will automatically append the stylesheet to the document's head. And the results of the import will be an object of CSS class to module names.
+
+```js
+import styles from './styles.module.css'
+// styles == { header: 'header5564cdbb' }
+```
+
+It is important to note that the exported object of CSS module names is actually a Proxy object. So destructuring the object will not work. Instead, you must access the properties directly.
+
+Also, importing a CSS module from another CSS module will result in the same digest string for all classes.
+
+## CSS Mixins
+
+Proscenium provides functionality for including or "mixing in" onr or more CSS classes into another. This is similar to the `composes` property of CSS Modules, but works everywhere, and is not limited to CSS Modules.
+
+CSS mixins are supported using the `@define-mixin` and `@mixin` at-rules.
+
+A mixin is defined using the `@define-mixin` at-rule. Pass it a name, which should adhere to class name semantics, and declare your rules:
+
+```css
+// /lib/mixins.css
+@define-mixin bigText {
+  font-size: 50px;
+}
+```
+
+Use a mixin using the `@mixin` at-rule. Pass it the name of the mixin you want to use, and the url where the mixin is declared. The url is used to resolve the mixin, and can be relative, absolute, a URL, or even from an NPM packacge.
+
+```css
+// /app/views/layouts/application.css
+p {
+  @mixin bigText from url('/lib/mixins.css');
+  color: red;
+}
+```
+
+The above produce this output:
+
+```css
+p {
+  font-size: 50px;
+  color: red;
+}
+```
+
+Mixins can be declared in any CSS file. They do not need to be declared in the same file as where they are used. however, if you declare and use a mixin in the same file, you don't need to specify the URL of where the mixin is declared.
+
+```css
+@define-mixin bigText {
+  font-size: 50px;
+}
+
+p {
+  @mixin bigText;
+  color: red;
+}
+```
+
+CSS modules and Mixins works perfectly together. You can include a mixin in a CSS module.
+
+## Importing SVG from JS(X)
+
+Importing SVG from JS(X) will bundle the SVG source code. Additionally, if importing from JSX, the SVG source code will be rendered as a JSX component.
+
+## Environment Variables
+
+Import any environment variables into your JS(X) code.
+
+```js
+import RAILS_ENV from '@proscenium/env/RAILS_ENV'
+```
+
+You can only access environment variables that are explicitly named. It will export `undefined` if the env variable does not exist.
+
+## Importing i18n
+
+Basic support is provided for importing your Rails locale files from `config/locales/*.yml`, exporting them as JSON.
+
+```js
+import translations from '@proscenium/i18n'
+// translations.en.*
+```
+
+## Phlex Support
+
+*docs needed*
+
+## ViewComponent Support
+
+*docs needed*
+
+## Cache Busting [*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.
+
+For example, if you set `REVISION=v1`, URL's will be appended with `?v1`: `/my/imported/file.js?v1`.
+
+It is assumed that the `REVISION` env var will be unique between deploys. If it isn't, then assets will continue to be cached as the same version between deploys. I recommend you assign a version number or to use the Git commit hash of the deploy. Just make sure it is unique for each deploy.
+
+You can set the `cache_query_string` config option directly to define any query string you wish:
+
+```ruby
+Rails.application.config.proscenium.cache_query_string = 'my-cache-busting-version-string'
+```
+
+The cache is set with a `max-age` of 30 days. You can customise this with the `cache_max_age` config option:
+
+```ruby
+Rails.application.config.proscenium.cache_max_age = 12.months.to_i
+```
+
+## Include Paths
+
+By default, Proscenium will serve files ending with any of these extension: `js,mjs,css,jsx`, and only from `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'
+```
+
+## rjs is back!
+
+Proscenium brings back RJS! Any path ending in .rjs will be served from your Rails app. This allows you to import server rendered javascript.
+
+## Serving from Ruby Gem
+
+*docs needed*
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Running Go benchmarks
+
+```bash
+go test ./internal/builder -bench=. -run="^$" -count=10 -benchmem
+```
+
+## 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).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Proscenium project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/joelmoss/proscenium/blob/master/CODE_OF_CONDUCT.md).

data/lib/proscenium/css_module/class_names_resolver.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class CssModule::ClassNamesResolver
+    def initialize(class_names, phlex_path)
+      @class_names = class_names.split
+      @stylesheets = {}
+      @phlex_path = phlex_path.sub_ext('.module.css')
+
+      resolve_class_names
+    end
+
+    def class_names
+      @class_names.join(' ')
+    end
+
+    def stylesheets
+      @stylesheets.map { |_, values| values[:resolved_path] }
+    end
+
+    private
+
+    def resolve_class_names
+      @class_names.map! do |class_name|
+        if class_name.include?('/')
+          if class_name.starts_with?('@')
+            # Scoped bare specifier (eg. "@scoped/package/lib/button@default").
+            _, path, name = class_name.split('@')
+            path = "@#{path}"
+          elsif class_name.starts_with?('/')
+            # Local path with leading slash.
+            path, name = class_name[1..].split('@')
+          else
+            # Bare specifier (eg. "mypackage/lib/button@default").
+            path, name = class_name.split('@')
+          end
+
+          path += '.module.css'
+
+          Utils.css_modularise_class_name name, digest: add_stylesheet(path)[:digest]
+        elsif class_name.starts_with?('@')
+          Utils.css_modularise_class_name class_name[1..],
+                                          digest: add_stylesheet(@phlex_path)[:digest]
+        else
+          class_name
+        end
+      end
+    end
+
+    def add_stylesheet(path)
+      return @stylesheets[path] if @stylesheets.key?(path)
+
+      resolved_path = Utils.resolve_path(path.to_s)
+
+      unless Rails.root.join(resolved_path[1..]).exist?
+        raise CssModule::StylesheetNotFound, resolved_path
+      end
+
+      # Note that the digest is based on the resolved (URL) path, not the original path.
+      @stylesheets[path] = {
+        resolved_path: resolved_path,
+        digest: Utils.digest(resolved_path)
+      }
+    end
+  end
+end

data/lib/proscenium/css_module/resolver.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Proscenium
+  class CssModule::Resolver
+    attr_reader :side_loaded_paths
+
+    # @param path [Pathname] Absolute file system path to the Ruby file that will be side loaded.
+    def initialize(path, side_load: true, hash: nil)
+      raise ArgumentError, "'#{path}' must be a `Pathname`" unless path.is_a?(Pathname)
+
+      @path = path
+      @hash = hash
+      @css_module_path = path.sub_ext('.module.css')
+      @side_load = side_load
+      @side_loaded_paths = nil
+    end
+
+    # Parses the given `content` for CSS modules names ('class' attributes beginning with '@'), and
+    # returns the content with said CSS Modules replaced with the compiled class names.
+    #
+    # Example:
+    #   <div class="@my_css_module_name"></div>
+    def compile_class_names(content)
+      doc = Nokogiri::HTML::DocumentFragment.parse(content)
+
+      return content if (modules = doc.css('[class*="@"]')).empty?
+
+      modules.each do |ele|
+        classes = ele.classes.map { |cls| cls.starts_with?('@') ? class_names!(cls[1..]) : cls }
+        ele['class'] = classes.join(' ')
+      end
+
+      doc.to_html.html_safe
+    end
+
+    # Resolves the given CSS class names to CSS modules. This will also side load the stylesheet if
+    # it exists.
+    #
+    # @param names [String, Array]
+    # @returns [Array] of class names generated from the given CSS module `names`.
+    def class_names(*names)
+      side_load_css_module
+      Utils.css_modularise_class_names names, digest: @hash
+    end
+
+    # Like #class_names, but requires that the stylesheet exists.
+    #
+    # @param names [String, Array]
+    # @raises Proscenium::CssModule::NotFound if stylesheet does not exists.
+    # @see #class_names
+    def class_names!(...)
+      raise CssModule::StylesheetNotFound, @css_module_path unless @css_module_path.exist?
+
+      class_names(...)
+    end
+
+    def side_loaded?
+      @side_loaded_paths.present?
+    end
+
+    private
+
+    def side_load_css_module
+      return if !@side_load || !Rails.application.config.proscenium.side_load
+
+      paths = SideLoad.append @path, { '.module.css' => :css }
+
+      @side_loaded_paths = if paths.empty?
+                             nil
+                           else
+                             @hash = Utils.digest(paths[0])
+                             paths
+                           end
+    end
+  end
+end

data/lib/proscenium/css_module.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+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
+
+  # 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 ' '
+  end
+
+  private
+
+  def path
+    self.class.path
+  end
+
+  def cssm
+    @cssm ||= Resolver.new(path)
+  end
+end

data/lib/proscenium/current.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+
+module Proscenium
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :loaded
+  end
+end