proscenium 0.10.0-aarch64-linux → 0.11.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8bdf57d7adeffd9f5e9870b1eee740e13635eb0d8f7e086cf4f27c5995351dc
-  data.tar.gz: 63e17d99ae30ef464865f59b32b6ca202319483f8e5d6022fb36e5c1241ee933
+  metadata.gz: 2c9e2910c66b7815caac52459933e495e418d806dcc59ee468a1503516f3412b
+  data.tar.gz: 3362ffddc7b059ac0a9ed0d13ad072bd6e4bb5058e979cfb7bedb376a2db805d
 SHA512:
-  metadata.gz: 9ccbafedf5dc6decec21d7d9a3ecb75fc90c235be31d1b2abb8f125c74047d79c2526c8336e5165fb5d919131fc441e6fa93b289e1b84968385f3c3ebdf6d272
-  data.tar.gz: a1555df493558a94b4ea1188894b09b3c44cf103ff71ea8b01e1ff95e801fd51530613689d4ccc66356ff95be1bf73d3a15f36db0c225c0a5ccf7abd79360956
+  metadata.gz: 60d02529097f5f539d0403b42f8f95d1f7349490a73cfc0b7c52792f05993dad85eea679ea40fb064946b2b803c9c1fc6b7a02893b7f01bb73ddebc2c40f3121
+  data.tar.gz: 16bcd2a02ab09654207ddb58d02728e08492a3e2973e1bdd5cb26a071639b128ecf07990bd50dfede00e1f56bfa3df22ea796ee5d717baeb45bb2b4f83184160

data/README.md

@@ -1,18 +1,16 @@
 # Proscenium - Modern client-side development 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.
+Proscenium treats your client-side code as first class citizens of your Rails app, and assumes a "fast by default" internet. It bundles your JavaScript and CSS in real time, on demand, and with zero configuration.
 
-- Fast real-time bundling, tree-shaking and minification of Javascript (.js,.jsx), Typescript (.ts,.tsx) and CSS (.css).
+**The highlights:**
+
+- Fast real-time bundling, tree-shaking, code-splitting 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.
-- ESM importing from NPM, URLs, and locally.
+- Automatically side-load your layouts, views, and partials.
+- Import from NPM, URL's, and locally.
 - Server-side import map support.
 - CSS Modules & mixins.
 - Source maps.
@@ -54,7 +52,7 @@ configuration.
 
 ## 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 obviously depends on whether you are adding Proscenium to an existing Rails app, or creating a new one. So 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
@@ -91,7 +89,7 @@ Using the examples above...
 
 ## Side Loading
 
-> 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.
+> 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`, `.tsx`, and `.module.css`. Also partials were not side loaded prior to 0.10.0.
 
 Proscenium is best experienced when you side load your assets.
 
@@ -101,7 +99,7 @@ With Rails you would typically declaratively load your JavaScript and CSS assets
 
 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:
+You would manually and declaratively include those two files in your application layout, something like this:
 
 ```erb
 <%# /app/views/layouts/application.html.erb %>
@@ -119,7 +117,7 @@ You would include those two files in your application layout, something like thi
 </html>
 ```
 
-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:
+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 (or layout), something like this:
 
 ```erb
 <%# /app/views/users/index.html.erb %>
@@ -163,25 +161,25 @@ Your application layout is at `/app/views/layouts/application.hml.erb`, and the
 - `/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:
+Now, in your layout and view, replace the `javascript_include_tag` and `stylesheet_link_tag` helpers with the `include_stylesheets` and `include_javascripts` helpers from Proscenium. Something like this:
 
 ```erb
 <!DOCTYPE html>
 <html>
   <head>
     <title>Hello World</title>
-    <%= side_load_stylesheets %>
+    <%= include_stylesheets %>
   </head>
   <body>
     <%= yield %>
-    <%= side_load_javascripts type: 'module', defer: true %>
+    <%= include_javascripts type: 'module', defer: true %>
   </body>
 </html>
 ```
 
 > 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.
+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 `include_stylesheets` and `include_javascripts` helpers.
 
 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.
 
@@ -229,6 +227,16 @@ import utils from '/lib/utils'
 import constants from './constants'
 ```
 
+```css /app/views/layouts/application.css
+@import '/lib/reset';
+```
+
+```css /lib/reset.css
+body {
+  /* some styles... */
+}
+```
+
 ## Import Maps
 
 > **[WIP]**
@@ -397,14 +405,6 @@ one();
 
 > 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:
@@ -438,6 +438,11 @@ If these files are side loaded, then `father.js` will be split off into a separa
 
 - 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.
 
+Code splitting is enabled by default. You can disable it by setting the `code_splitting` configuration option to `false` in your application's `/config/application.rb`:
+```ruby
+config.proscenium.code_splitting = false
+```
+
 ### 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).
@@ -464,34 +469,74 @@ export let Button = ({ text }) => {
 
 ### 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.
+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 will work everywhere, even in plain CSS files.)
 
-Give any CSS file a `.module.css` extension, and Proscenium will load it as a CSS Module...
+Give any CSS file a `.module.css` extension, and Proscenium will treat it as a CSS Module, transforming all class names with a suffix unique to the file.
 
 ```css
-.header {
-  background-color: #00f;
+.title {
+  font-size: 20em;
 }
 ```
 
 The above input produces:
 
 ```css
-.header5564cdbb {
-  background-color: #00f;
+.title-5564cdbb {
+  font-size: 20em;
 }
 ```
 
-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.
+You now have a unique class name that you can use pretty much anywhere.
+
+#### In your Views
+
+You can reference CSS modules from your Rails views, partials, and layouts using the `css_module` helper, which accepts one or more class names, and will return the equivilent CSS module names - the class name with the unique suffix appended.
+
+With [side-loading](#side-loading) setup, you can use the `css_module` helper as follows.
+
+```erb
+<div>
+  <h1 class="<%= css_module :hello_title %>">Hello World</h1>
+  <p class="<%= css_module :body, paragraph: %>">
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  </p>
+</div>
+```
+
+`css_module` accepts multiple class names, and will return a space-separated string of transformed CSS module names.
+
+```ruby
+css_module :my_module_name
+# => "my_module_name-ABCD1234"
+```
+
+You can even reference a class from any CSS file by passing the URL path to the file, as a prefix to the class name. Doing so will automatically [side load](#side-loading) the stylesheet.
+
+```ruby
+css_module '/app/components/button.css@big_button'
+# => "big_button"
+```
+
+It also supports NPM packages (already installed in /node_modules):
+
+```ruby
+css_module 'mypackage/button@big_button'
+# => "big_button"
+```
+
+#### In your JavaScript
+
+Importing a CSS module from JS will automatically append the stylesheet to the document's head. And the result of the import will be an object of CSS class to module names.
 
 ```js
 import styles from './styles.module.css'
-// styles == { header: 'header5564cdbb' }
+// styles == { header: 'header-5564cdbb' }
 ```
 
-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.
+It is important to note that the exported object of CSS module names is actually a JavaScript [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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.
+Also, importing a CSS module into another CSS module will result in the same digest string for all classes.
 
 ### CSS Mixins
 
@@ -589,11 +634,112 @@ console.log(version)
 
 ## Phlex Support
 
-> *docs needed*
+[Phlex](https://www.phlex.fun/) is a framework for building fast, reusable, testable views in pure Ruby. Proscenium works perfectly with Phlex, with support for side-loading, CSS modules, and more. Simply write your Phlex classes and inherit from `Proscenium::Phlex`.
+
+```ruby
+class MyView < Proscenium::Phlex
+  def template
+    h1 { 'Hello World' }
+  end
+end
+```
+
+### Side-loading
+
+Any Phlex class that inherits `Proscenium::Phlex` will automatically be [side-loaded](#side-loading).
+
+### CSS Modules
+
+[CSS Modules](#css-modules) are fully supported in Phlex classes, with access to the [`css_module` helper](#in-your-views) if you need it. However, there is a better and more seemless way to reference CSS module classes in your Phlex classes.
+
+Within your Phlex classes, any class names that begin with `@` will be treated as a CSS module class.
+
+```ruby
+# /app/views/users/show_view.rb
+class Users::ShowView < Proscenium::Phlex
+  def template
+    h1 class: :@user_name do
+      @user.name
+    end
+  end
+end
+```
+
+```css
+/* /app/views/users/show_view.module.css */
+.userName {
+  color: red;
+  font-size: 50px;
+}
+```
+
+In the above `Users::ShowView` Phlex class, the `@user_name` class will be resolved to the `userName` class in the `users/show_view.module.css` file.
+
+The view above will be rendered something like this:
+
+```html
+<h1 class="user_name-ABCD1234"></h1>
+```
+
+You can of course continue to reference regular class names in your view, and they will be passed through as is. This will allow you to mix and match CSS modules and regular CSS classes in your views.
+
+```ruby
+# /app/views/users/show_view.rb
+class Users::ShowView < Proscenium::Phlex
+  def template
+    h1 class: :[@user_name, :title] do
+      @user.name
+    end
+  end
+end
+```
+
+```html
+<h1 class="user_name-ABCD1234 title">Joel Moss</h1>
+```
 
 ## ViewComponent Support
 
-> *docs needed*
+[ViewComponent](https://viewcomponent.org/) iA framework for creating reusable, testable & encapsulated view components, built to integrate seamlessly with Ruby on Rails. Proscenium works perfectly with ViewComponent, with support for side-loading, CSS modules, and more. Simply write your ViewComponent classes and inherit from `Proscenium::ViewComponent`.
+
+```ruby
+class MyView < Proscenium::ViewComponent
+  def call
+    tag.h1 'Hello World'
+  end
+end
+```
+
+### Side-loading
+
+Any ViewComponent class that inherits `Proscenium::ViewComponent` will automatically be [side-loaded](#side-loading).
+
+### CSS Modules
+
+[CSS Modules](#css-modules) are fully supported in ViewComponent classes, with access to the [`css_module` helper](#in-your-views) if you need it.
+
+```ruby
+# /app/components/user_component.rb
+class UserComponent < Proscenium::ViewComponent
+  def template
+    div.h1 @user.name, class: css_module(:user_name)
+  end
+end
+```
+
+```css
+/* # /app/components/user_component.module.css */
+.userName {
+  color: red;
+  font-size: 50px;
+}
+```
+
+The view above will be rendered something like this:
+
+```html
+<h1 class="user_name-ABCD1234">Joel Moss</h1>
+```
 
 ## Cache Busting
 
@@ -617,24 +763,40 @@ The cache is set with a `max-age` of 30 days. You can customise this with the `c
 Rails.application.config.proscenium.cache_max_age = 12.months.to_i
 ```
 
-## rjs is back!
+## 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
+## Resolution
+
+Proscenium will serve files ending with any of these extension: `js,mjs,ts,css,jsx,tsx` from the following directories, and their sub-directories of your Rails application's root: `/app`, `/lib`, `/config`, `/node_modules`, `/vendor`.
+
+So a file at `/app/views/users/index.js` will be served from `https://yourapp.com/app/views/users/index.js`.
 
-*docs needed*
+You can continue to access any file in the `/public` directory as you normally would. Proscenium will not process files in the `/public` directory.
 
-## Included Paths
+If requesting a file that exists in a root directory and the public directory, the file in the public directory will be served. For example, if you have a file at `/lib/foo.js` and `/public/lib/foo.js`, and you request `/lib/foo.js`, the file in the public directory (`/public/lib/foo.js`) will be served.
 
-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.
+### Assets from Rails Engines
 
-However, you can customise these paths with the `include_path` config option...
+Proscenium can serve assets from Rails Engines that are installed in your Rails app.
+
+An engine that wants to expose its assets via Proscenium to the application must add Proscenium as a dependency, and add itself to the list of engines in the Proscenium config options `Proscenium.config.engines`.
+
+For example, we have a gem called `gem1` that has Proscenium as a dependency, and exposes a Rails engine. It has some assets that it wants to expose to the application. To do this, it adds itself to the list of engines in the Proscenium config `engines` option:
 
 ```ruby
-Rails.application.config.proscenium.include_paths << 'app/components'
+class Gem1::Engine < ::Rails::Engine
+  config.proscenium.engines << self
+end
 ```
 
+When this gem is installed in any Rails application, its assets will be available at the URL `/gem1/...`. For example, if the gem has a file `lib/styles.css`, it can be requested at `/gem1/lib/styles.css`.
+
+The same directories and file extensions are supported as for the application itself.
+
+It is important to note that the application takes precedence over the gem. So if the application has a file at `/public/gem1/lib/styles.css`, and the gem also has a file at `/lib/styles.css`, then the file in the application will be served. This is because both files would be accessible at the same URL: `/gem1/lib/styles.css`.
+
 ## 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.
@@ -654,7 +816,7 @@ bundle exec rake compile:local
 We have tests for both Ruby and Go. To run the Ruby tests:
 
 ```bash
-bundle exec rake test
+bundle exec sus
 ```
 
 To run the Go tests:
@@ -671,7 +833,7 @@ 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).
+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
 

data/lib/proscenium/builder.rb

@@ -25,9 +25,11 @@ module Proscenium
         :string,      # ENV variables as a JSON string
 
         # Config
-        :string,      # root
+        :string,      # Rails application root
+        :string,      # Proscenium gem root
         :environment, # Rails environment as a Symbol
         :bool,        # code splitting enabled?
+        :string,      # engine names and paths as a JSON string
         :bool         # debugging enabled?
       ], Result.by_value
 
@@ -36,18 +38,25 @@ module Proscenium
         :string,      # path to import map, relative to root
 
         # Config
-        :string,      # root
-        :environment  # Rails environment as a Symbol
+        :string,      # Rails application root
+        :string,      # Proscenium gem root
+        :environment, # Rails environment as a Symbol
+        :bool         # debugging enabled?
       ], Result.by_value
     end
 
     class BuildError < StandardError
-      attr_reader :error, :path
+      attr_reader :error
 
-      def initialize(path, error)
-        error = Oj.load(error, mode: :strict).deep_transform_keys(&:underscore)
+      def initialize(error)
+        @error = Oj.load(error, mode: :strict).deep_transform_keys(&:underscore)
 
-        super "Failed to build '#{path}' -- #{error['text']}"
+        msg = @error['text']
+        if (location = @error['location'])
+          msg << " at #{location['file']}:#{location['line']}:#{location['column']}"
+        end
+
+        super msg
       end
     end
 
@@ -72,23 +81,32 @@ module Proscenium
       @base_url = base_url
     end
 
-    def build(path)
-      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)
+    def build(path) # rubocop:disable Metrics/AbcSize
+      ActiveSupport::Notifications.instrument('build.proscenium', identifier: path) do
+        result = Request.build(path, @base_url, import_map, env_vars.to_json,
+                               @root.to_s,
+                               Pathname.new(__dir__).join('..', '..').to_s,
+                               Rails.env.to_sym,
+                               Proscenium.config.code_splitting,
+                               engines.to_json,
+                               Proscenium.config.debug)
 
-      raise BuildError.new(path, result[:response]) unless result[:success]
+        raise BuildError, result[:response] unless result[:success]
 
-      result[:response]
+        result[:response]
+      end
     end
 
     def resolve(path)
-      result = Request.resolve(path, import_map, @root.to_s, Rails.env.to_sym)
-      raise ResolveError.new(path, result[:response]) unless result[:success]
-
-      result[:response]
+      ActiveSupport::Notifications.instrument('resolve.proscenium', identifier: path) do
+        result = Request.resolve(path, import_map, @root.to_s,
+                                 Pathname.new(__dir__).join('..', '..').to_s,
+                                 Rails.env.to_sym,
+                                 Proscenium.config.debug)
+        raise ResolveError.new(path, result[:response]) unless result[:success]
+
+        result[:response]
+      end
     end
 
     private
@@ -105,6 +123,10 @@ module Proscenium
       q ? "--cache-query-string #{q}" : nil
     end
 
+    def engines
+      Proscenium.config.engines.to_h { |e| [e.engine_name, e.root.to_s] }
+    end
+
     def import_map
       return unless (path = Rails.root&.join('config'))
 

data/lib/proscenium/css_module/path.rb

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

data/lib/proscenium/css_module/transformer.rb

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