ember-css-modules 2.1.1 → 3.0.0

package/README.md

@@ -0,0 +1,311 @@
+# ember-css-modules
+
+> [!IMPORTANT]
+> This package has been the core means of using CSS Modules in Ember projects for a long time, and it will continue to be maintained, but v3 is likely the final major version and this probably isn't what you want to use in new projects. See [the main README in this repository](https://github.com/salsify/ember-css-modules) for more details on the current state of CSS Modules in Ember.
+>
+> Ready to migrate? See the migration guides for [apps](../../docs/MIGRATING-V1-APP.md) and [addons](../../docs/MIGRATING-V1-ADDON.md).
+
+<details>
+<summary>Full documentation</summary>
+
+Ember-flavored support for [CSS Modules](https://github.com/css-modules/css-modules). For an overview of some of the motivations for the CSS Modules concept, see [this blog post](http://blog.salsify.com/engineering/good-fences-with-css-modules).
+
+- [What and Why?](#what-and-why)
+- [Usage](#usage)
+  - [Simple Example](#simple-example)
+  - [Component Colocation Example](#component-colocation-example)
+  - [Styling Reuse](#styling-reuse)
+  - [Programmatic Styles Access](#programmatic-styles-access)
+  - [Global Classes](#global-classes)
+  - [Values](#values)
+  - [Glint usage](#glint-usage)
+- [Usage in Addons](#usage-in-addons)
+- [Advanced Configuration](#advanced-configuration)
+  - [Where to Specify Options](#where-to-specify-options)
+  - [Extensions in Module Paths](#extensions-in-module-paths)
+  - [Scoped Name Generation](#scoped-name-generation)
+  - [Source Maps](#source-maps)
+    - [Notes](#notes)
+- [Ember Support](#ember-support)
+
+## What and Why?
+
+When you build a component, you drop a `.js` file and a `.hbs` file in your app directory, and your tooling takes care of the rest. Babel takes your fancy ES6 module and restructures it into nice browser-friendly code, while still giving you isolation and modularity guarantees. Meanwhile, the rest of the Ember CLI build pipeline picks up these new files and automatically incorporates them into your final JS artifact. And when it's time to come back and tweak your component, you (just like the Ember resolver) know exactly where those files live based just on the name of the component.
+
+**With ember-css-modules, your styling is a first-class citizen alongside your templates and JavaScript**. You have one `.css` file per component (or route controller), in the same structure you're already using in the rest of your app. Every class you write is local to that file by default, with explicit mechanisms for opting into sharing, just like your JavaScript modules. And just like all your JS modules are automatically included in `<app-name>.js`, your CSS modules will automatically be included in `<app-name>.css`.
+
+## Usage
+
+### Simple Example
+
+With ember-css-modules, you define styles on a per-component (or -controller) basis. You define these styles using the same file layout you use for templates; for example, in pod structure you'd put `styles.css` alongside `template.hbs` in the component's pod. The classes in that stylesheet are then automatically namespaced to the corresponding component or controller. In order to reference them, you use the `local-class` attribute rather than the standard `class`.
+
+```hbs
+{{! app/components/my-component/template.hbs }}
+<div local-class='hello-class'>Hello, world!</div>
+```
+
+```css
+/* app/components/my-component/styles.css */
+.hello-class {
+  font-weight: bold;
+}
+```
+
+Similarly, if you were styling e.g. your application controller, you would place your styles alongside `controller.js` in `<podModulePrefix>/application/styles.css`.
+
+### Component Colocation Example
+
+In Octane apps, where component templates can be colocated with their backing class, your styles module for a component takes the same name as the backing class and template files:
+
+```hbs
+{{! app/components/my-component.hbs }}
+<div local-class='hello-class'>Hello, world!</div>
+```
+
+```css
+/* app/components/my-component.css */
+.hello-class {
+  font-weight: bold;
+}
+```
+
+### Styling Reuse
+
+In the example above, `hello-class` is rewritten internally to something like `_hello-class_1dr4n4` to ensure it doesn't conflict with a `hello-class` defined in some other module.
+
+For cases where class reuse is desired, there's [the `composes` property](https://github.com/css-modules/css-modules#composition). Suppose you have a title in your component that you'd like to inherit your app-wide "secondary header" styling, which itself uses generic styling shared by all headers:
+
+```css
+/* app/styles/headers.css */
+.header {
+  font-weight: bold;
+  text-decoration: underline;
+}
+
+.secondary-header {
+  composes: header;
+  color: #339;
+}
+```
+
+```css
+/* app/components/my-component/styles.css */
+.component-title {
+  composes: secondary-header from 'my-app-name/styles/headers';
+  background-color: #eee;
+}
+```
+
+In the template for `my-component`, an element with `local-class="component-title"` will end up with an actual class string like `_component-title_1dr4n4 _secondary-header_1658xu _header_1658xu`, incorporating styles from all of the composing classes.
+
+Note that you may also use relative paths to specify the source modules for composition.
+
+Finally, you can compose local classes from global un-namespaced ones that are provided e.g. by a CSS framework by specifying `global` as the source of the class:
+
+```css
+/* vendor/some-lib.css */
+.super-important {
+  color: orange;
+}
+```
+
+```css
+/* app/components/my-component/styles.css */
+.special-button {
+  composes: super-important from global;
+}
+```
+
+### Programmatic Styles Access
+
+Currently the `local-class` attribute is honored on HTML elements and component invocations, e.g. `<div local-class="foo {{bar}}">` and `{{input local-class="baz"}}`. It is not (currently) supported in subexpressions like the `(component)` helper.
+
+If you need to access a local class in a template in other scenarios (such as passing in a class name as a property or reusing a class from another module), there is also a `local-class` helper you can use. For example, the "secondary-header" example above can be written as:
+
+```hbs
+{{! app/components/my-component/template.hbs }}
+<div
+  class='{{local-class "secondary-header" from='my-app-name/styles/headers'}}'
+>Hello, world!</div>
+```
+
+Note that the `from` parameter is optional; by default classes will come from the current module, as with the `local-class` attribute.
+
+In a JavaScript context, the class mappings can also be imported directly from whatever path the corresponding CSS module occupies, e.g.
+
+```js
+import styles from 'my-app-name/components/my-component/styles';
+console.log(styles['hello-class']);
+// => "_hello-class_1dr4n4"
+```
+
+**Note**: by default, the import path for a styles module does _not_ include the `.css` (or equivalent) extension. However, if you set `includeExtensionInModulePath: true`, then you'd instead write:
+
+```js
+import styles from 'my-app-name/components/my-component/styles.css';
+```
+
+Note that the extension is **always** included for styles modules that are part of an Octane "colocated" component, to avoid a conflict with the import path for the component itself.
+
+### Global Classes
+
+Some libraries provide explicit class names as part of their public interface in order to allow customization of their look and feel. If, for example, you're wrapping such a library in a component, you need to be able to reference those unscoped class names in the context of your component styles. The `:global` pseudoselector allows for this:
+
+```css
+.my-component :global(.some-library-class) {
+  color: orange;
+}
+```
+
+For more details on `:local` and `:global` exceptions, see [the CSS Modules documentation](https://github.com/css-modules/css-modules#exceptions).
+
+### Values
+
+For exposing data other than class names across module boundaries, you can use `@value`.
+
+```css
+/* app/styles/colors.css */
+@value primary-color: #8af;
+@value secondary-color: #fc0;
+```
+
+```css
+/* app/some-route-pod/styles.css */
+@value primary-color, secondary-color from 'my-app-name/styles/colors';
+
+.blurb {
+  color: primary-color;
+  background-color: secondary-color;
+}
+```
+
+Note that values are also exposed on the `styles` object for a given module, so they are also accessible from JavaScript if you need to coordinate between the two. As a contrived example:
+
+```js
+// app/some-route-pod/controller.js
+import styles from 'app/some-route-pod/styles';
+
+export default Ember.Controller.extend({
+  logColor() {
+    console.log('primary color is', styles['primary-color']);
+  },
+});
+```
+
+### Glint usage
+
+Helper `{{local-class}}` has proper [Glint](https://github.com/typed-ember/glint) types,
+which allow you when using TypeScript to get strict type checking in your templates.
+
+Unless you are using [strict mode](http://emberjs.github.io/rfcs/0496-handlebars-strict-mode.html) templates
+(via [first class component templates](http://emberjs.github.io/rfcs/0779-first-class-component-templates.html)),
+you need to import the addon's Glint template registry and extend your app's registry declaration
+as described in the [Using Addons](https://typed-ember.gitbook.io/glint/using-glint/ember/using-addons#using-glint-enabled-addons) documentation:
+
+```ts
+import '@glint/environment-ember-loose';
+import type EmberCssModulesRegistry from 'ember-css-modules/template-registry';
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry
+    extends EmberCssModulesRegistry /* other addon registries */ {
+    // local entries
+  }
+}
+```
+
+## Usage in Addons
+
+You can also use ember-css-modules in addons that expose components to their consuming application. To do this you'll need to move `ember-css-modules` out of `devDependencies` and into `dependencies` in your addon's `package.json` ([see issue #8](https://github.com/salsify/ember-css-modules/issues/8)).
+
+Note also that **your addon must have an `addon/styles` directory** in order to trigger CSS processing in Ember CLI. In order for the directory to be preserved when you publish your addon, you can create an empty `.placeholder` file (`.gitkeep` won't work; by default, the `.npmignore` for your addon will prevent files with that name from being published).
+
+## Advanced Configuration
+
+Details about specific advanced configuration options are broken out into smaller mini-guides that each focus on a single topic:
+
+- [Using CSS Modules with Tailwind CSS](./docs/TAILWINDCSS.md)
+- [Using CSS Modules with other preprocessors like Sass or Less](./docs/PREPROCESSORS.md)
+- [Working with PostCSS plugins](./docs/POSTCSS.md)
+- [Module ordering](./docs/ORDERING.md)
+- [Defining values at build time with virtual modules](./docs/VIRTUAL_MODULES.md)
+
+### Where to Specify Options
+
+For applications, custom configuration for ember-css-modules may be specified in `ember-cli-build.js`:
+
+```js
+new EmberApp(defaults, {
+  // ...
+  cssModules: {
+    // config
+  },
+});
+```
+
+For addons, configuration may be specified in your addon's `index.js` instead:
+
+```js
+module.exports = {
+  // ...
+  options: {
+    cssModules: {
+      // config
+    },
+  },
+};
+```
+
+### Extensions in Module Paths
+
+When importing a CSS module's values from JS, or referencing it via `@value` or `composes:`, by default you do not include the `.css` extension in the import path. The exception to this rule is for modules that are part of an Octane-style colocated component, as the extension is the only thing to differentiate the styles module from the component module itself.
+
+If you wish to enable this behavior for _all_ modules, you can set the `includeExtensionInModulePath` flag in your configuration:
+
+```js
+new EmberApp(defaults, {
+  cssModules: {
+    includeExtensionInModulePath: true,
+  },
+});
+```
+
+### Scoped Name Generation
+
+By default, ember-css-modules produces a unique scoped name for each class in a module by combining the original class name with a hash of the path of the containing module. You can override this behavior by passing a `generateScopedName` function in the configuration.
+
+```js
+new EmberApp(defaults, {
+  cssModules: {
+    generateScopedName(className, modulePath) {
+      // Your logic here
+    },
+  },
+});
+```
+
+Note that addons may specify their own `generateScopedName` function, but otherwise they will fall back to using the one (if any) specified by the host application.
+
+### Source Maps
+
+Ember CLI allows you to [specify source map settings](https://ember-cli.com/user-guide/#source-maps) for your entire build process, and ember-css-modules will honor that configuration. For instance, to enable source maps in all environments for both JS and CSS files, you could put the following in your `ember-cli-build.js`:
+
+```
+sourcemaps: {
+  enabled: true,
+  extensions: ['js', 'css']
+}
+```
+
+#### Notes
+
+- You should specify the `css` extension in your source map configuration even if you're using a different extension for your modules themselves, since the final output file will be a `.css` file.
+- Currently CSS source maps (for _any_ Ember CLI preprocessor) only work for applications, not for addons. Watch [ember-cli/broccoli-concat#58](https://github.com/ember-cli/broccoli-concat/issues/58) for progress on that front.
+- Enabling source maps for CSS can cause Ember CLI to output an invalid comment at the end of your `vendor.css` file. This is harmless in many situations, but can cause issues with tools that postprocess your css, like ember-cli-autoprefixer. [ember-cli/broccoli-concat#58](https://github.com/ember-cli/broccoli-concat/issues/58) is the root cause of this issue as well.
+
+## Ember Support
+
+This addon supports Ember 3.28 and later, and is primarily for use in classic-build applications and v1 addons. See [the main README in this repository](https://github.com/salsify/ember-css-modules) for more details on more effective ways of using CSS Modules with Embroider and in v2 addons.
+
+</details>

package/addon/-runtime.js

@@ -0,0 +1 @@
+export * from 'glimmer-local-class-transform/-runtime';

package/docs/ORDERING.MD

@@ -0,0 +1,51 @@
+# Module Ordering
+
+All `.css` files in your `app`/`addon` directories are automatically concatenated into a single output file. Since [the ordering of rules in CSS is what breaks specificity ties](https://developer.mozilla.org/en/docs/Web/CSS/Specificity), the details of this concatenation can be important.
+
+## Implicit Ordering
+
+Where possible, ember-css-modules takes advantage of information it has about the dependencies between your CSS modules when making decisions about ordering. Any time, for instance, a class in one module `a` composes a class in module `b`, the contents of module `b` will be included earlier in the file output than the contents of `a`. This means you can override properties from composed classes without worrying about specificity hacks:
+
+```css
+/* app/styles/b.css */
+.b {
+  color: green;
+  font-weight: bold;
+}
+```
+
+```css
+/* app/styles/a.css */
+.a {
+  composes: b from './b';
+  color: orange;
+}
+```
+
+## Explicit Ordering
+
+You may also have cases where you explicitly want certain modules to be included early or late in the concatenated CSS. This may be common if, for example, you have a set of global base classes in your application.
+
+To meet this goal, you can declare `headerModules` and `footerModules` in your ember-css-modules configuration.
+
+```js
+cssModules: {
+  headerModules: [
+    'my-app/styles/simple-elements',
+    'my-app/styles/typography'
+  ]
+}
+```
+
+You use the same paths when configuring `headerModules` and `footerModules` as you would with `@value` and `composes`.
+
+#### Final Output
+
+Given the rules above, the final ordering for the modules included in an app or addon build will look something like this:
+
+```
+<modules configured in headerModules>
+<modules connected via composes: or @value imports>
+<modules with no connections and no explicit ordering>
+<modules configured in footerModules>
+```

package/docs/POSTCSS.md

@@ -0,0 +1,89 @@
+# PostCSS Plugins
+
+Since the CSS module loader is built on [PostCSS](https://github.com/postcss/postcss), your modules have access to the [full range of plugins](http://postcss.parts/) that exist.
+
+## Simple Usage
+
+For example, to automatically manage vendor prefixes with [Autoprefixer](https://github.com/postcss/autoprefixer):
+
+```js
+var autoprefixer = require('autoprefixer');
+// ...
+new EmberApp(defaults, {
+  cssModules: {
+    plugins: [
+      autoprefixer('last 2 versions')
+    ]
+  }
+});
+```
+
+## Plugin Configuration
+
+If you're unfamiliar with PostCSS, it may not be obvious how you pass configuration to a plugin. PostCSS plugins are themselves actually functions that you call with the configuration you want to pass to them. In the Autoprefixer example above, note that we call the `autoprefixer` function with the config we want to use with it (in this case a simple string, but with many plugins this would be an object literal with any number of option keys provided).
+
+Note: if you're coming from `ember-cli-postcss`, its nonstandard `[plugin, config]` tuple format is _not_ supported.
+
+## Before/After PostCSS Plugins
+
+By default, any PostCSS plugins you specify will be applied after the module transformation. To apply a set of plugins beforehand instead, you can pass a hash with `before` and `after` keys. For instance, if you wanted to use [postcss-nested](https://github.com/postcss/postcss-nested) so that you could define a set of global classes as a single block:
+
+```js
+new EmberApp(defaults, {
+  cssModules: {
+    plugins: {
+      before: [
+        nested
+      ],
+      after: [
+        autoprefixer('last 2 versions')
+      ]
+    }
+  }
+});
+```
+
+## Post-Process Plugins
+
+You can also provide a set of `postprocess` plugins that will run on the file after it has been concatenated.  This is useful for plugins like `postcss-sprites` that behave better when run against a single file. The `postprocess` array will be passed through to the `plugins` option in [`broccoli-postcss`](https://github.com/jeffjewiss/broccoli-postcss#broccolipostcsstree-options); see that package for details.
+
+```javascript
+new EmberApp(defaults, {
+  cssModules: {
+    plugins: {
+      postprocess: [
+        require('postcss-sprites')({ /* options */ })
+      ]
+    }
+  }
+});
+```
+
+## Importing Third Party Files
+
+Out of the box, ember-css-modules doesn't provide a way to to include CSS from outside the app or addon in development. Where possible, including these styles by `app.import`ing them from Bower or using a tool like [ember-cli-node-assets](https://github.com/dfreeman/ember-cli-node-assets) is a good practice, since the build pipeline will have to do less work during development, and your users will benefit from better caching in `vendor.css`.
+
+Some styling tools, however, allow for customization as part of a build process. As a specific example, [Basscss](http://www.basscss.com/) allows you to define specific [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) to customize its default styling. To accomplish this with ember-css-modules, you can use [postcss-import](https://github.com/postcss/postcss-import) and [postcss-css-variables](https://github.com/MadLittleMods/postcss-css-variables).
+
+```js
+new EmberApp(defaults, {
+  cssModules: {
+    plugins: [
+      require('postcss-import'),
+      require('postcss-css-variables')
+    ]
+  }
+});
+```
+
+```css
+/* app/styles/third-party.css */
+@import 'some-other-library';
+@import 'basscss';
+
+:root {
+  --h1: 4rem;
+}
+```
+
+Note that any plugins that run _after_ postcss-import will be applied to the imported files, which is why setting the `--h1` variable above affects the Basscss output.

package/docs/PREPROCESSORS.md

@@ -0,0 +1,61 @@
+# Using ember-css-modules with other preprocessors
+
+The one-step solution for using ember-css-modules in concert with another preprocessor like Sass or Less is to use a plugin like [ember-css-modules-sass](https://npmjs.com/package/ember-css-modules-sass). However, if you want to tweak the default behavior or are looking to implement your own integration with another preprocessor, the settings here will help you in that direction.
+
+## Two Approaches
+
+High level, there are two approaches to using ECM alongside another preprocessor.
+
+### Modules and preprocessor syntax in isolation
+
+The first is to have your modules be completely separate from e.g. your Sass, only combining the two at the very end of the build into a single stylesheet. In this scenario, you use vanilla CSS (possibly with some PostCSS plugins) in all your `.css` module files, and ember-css-modules doesn't touch any of your `.scss`/`.less`/etc files, leaving them to behave globally exactly as they did before.
+
+The advantage to this approach is that it provides a clear migration path: as you convert global classes into local modularized styling, the file extension and syntax you use also changes with it, making the divide clear.
+
+For example, with Sass you could install ember-cli-sass and then configure ember-css-modules to emit a `_modules` partial:
+
+```js
+cssModules: {
+  intermediateOutputPath: 'app/styles/_modules.scss'
+}
+```
+
+And then in your `app.scss`, simply import it:
+
+```scss
+// other Sass code and imports
+@import 'modules';
+```
+
+Note: when specifying `intermediateOutputPath`, for an app you must include `app/styles/_modules.scss` at the front, but addon styles output is already implicitly scoped, so you would just set `intermediateOutputPath` to `_modules.scss`.
+
+#### Custom syntax directly in modules
+
+The second approach is viable for preprocessors for which there is a PostCSS syntax extension, such as [Sass](https://github.com/postcss/postcss-scss) and (at least partially) [Less](https://github.com/gilt/postcss-less). It allows for using custom preprocessor syntax directly in CSS modules, handing off the concatenated final output directly to the preprocessor. This is the approach taken by plugins like `ember-css-modules-sass`.
+
+Again using Sass as an example, you would specify `app.scss` as your intermediate output file so that ember-cli-sass would pick it up directly, and then tell ember-css-modules to look for `.scss` files and pass through custom PostCSS syntax configuration.
+
+```js
+cssModules: {
+  // Emit a combined SCSS file for ember-cli-sass to compile
+  intermediateOutputPath: 'app/styles/app.scss',
+
+  // Use .scss as the extension for CSS modules instead of the default .css
+  extension: 'scss',
+
+  // Pass a custom parser/stringifyer through to PostCSS for processing modules
+  postcssOptions: {
+    syntax: require('postcss-scss')
+  }
+}
+```
+
+### Passing Through Other Files
+
+When you configure an `intermediateOutputPath`, ember-css-modules will automatically pass through all files with stylesheet-like extensions for subsequent processors to be able to include. If you're relying on being able to reference data from other files in a downstream processing step, you may configure the extensions of files that should be passed on.
+
+```js
+cssModules: {
+  passthroughFileExtensions: ['json']
+}
+```

package/docs/TAILWINDCSS.md

@@ -0,0 +1,77 @@
+# Using ember-css-modules with tailwindcss
+
+Adapted from https://github.com/chrism/emberjs-tailwind-purgecss
+NOTE: if you're coming from this installation be aware that you'll need to uninstall ember-cli-postcss
+
+## Installation
+
+```bash
+ember install ember-css-modules
+yarn add tailwindcss postcss-import @fullhuman/postcss-purgecss -D
+```
+
+## Setup tailwindcss
+```bash
+mkdir app/tailwind
+npx tailwind init app/tailwind/config.js --full
+```
+
+## Create new CSS files and import Tailwind
+
+Create app/styles/components.css and app/styles/utilities.css then update app.css
+
+```css
+@import "tailwindcss/base";
+
+@import "tailwindcss/components";
+@import "components.css";
+
+@import "tailwindcss/utilities";
+@import "utilities.css";
+```
+
+## Update build pipeline to include plugins
+
+```js
+// ember-cli-build.js
+'use strict';
+
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
+const isProduction = EmberApp.env() === 'production';
+
+const purgecssOptions = {
+  content: [
+    // add extra paths here for components/controllers which include tailwind classes
+    './app/index.html',
+    './app/templates/**/*.hbs',
+    './app/components/**/*.hbs'
+  ],
+  defaultExtractor: content => {
+    return content.match(/[A-Za-z0-9-_:/]+/g) || []
+  },
+  // Leave css definitions starting with an underscore untouched.
+  // This prevents css definitions generated by ember-css-modules
+  // from being purged.
+  safelist: [/^_/]
+};
+
+let cssModulesPlugins = [
+  require('postcss-import')({ path: ['node_modules'] }),
+  require('tailwindcss')('./app/tailwind/config.js'),
+];
+
+if (isProduction) {
+  const purgecss = require('@fullhuman/postcss-purgecss')(purgecssOptions);
+  cssModulesPlugins.push(purgecss);
+}
+
+module.exports = function(defaults) {
+  let app = new EmberApp(defaults, {
+    cssModules: {
+      plugins: cssModulesPlugins
+    }
+  });
+
+  return app.toTree();
+};
+```

package/docs/VIRTUAL_MODULES.md

@@ -0,0 +1,41 @@
+# Virtual Modules
+
+There are many scenarios where it can be useful to programmatically define constants at build time rather than hard coding them in your source. You can accomplish this in ember-css-modules by passing a `virtualModules` hash in your config.
+
+For example, given this configuration:
+
+```js
+cssModules: {
+  virtualModules: {
+    'color-palette': {
+      'grass-green': '#4dbd33'
+    }
+  }
+}
+```
+
+The following import would retrieve the value `#4dbd33`:
+
+```css
+@value grass-green from 'color-palette';
+```
+
+Virtual modules may be particularly useful for addon authors, as they provide a way to make your addon styling configurable by consumers of your addon at build time. For instance, in your `index.js` you might have something like:
+
+```js
+included() {
+  // ...
+  this.options = Object.assign({}, this.options, {
+    cssModules: {
+      virtualModules: {
+        'my-addon-config': {
+          'header-color': config.headerColor || 'green',
+          'header-background': config.headerBackground || 'gray'
+        }
+      }
+    }
+  });
+  this._super.included.apply(this, arguments);
+  // ...
+}
+```