Merge pull request #241 from salsify/deprecate-classic-component-apis

Author: dfreeman

CHANGELOG.md

@@ -1,4 +1,50 @@
-## 1.4.0 (May 17, 2021) 
+## Unreleased
+### Deprecated
+- ECM's support for binding local class names on the root element of a classic `Ember.Compnent` (the `localClassNames` and `localClassNameBindings` properties and the `@localClassName` and `@localClassNames` decorators) has been deprecated and will be removed in the next major release. These APIs rely on reopening `Ember.Component` (which is itself [now deprecated](https://github.com/emberjs/rfcs/pull/671)) and can be replaced by several alternative patterns. See the Upgrade Notes section below for migration suggestions.
+
+### Upgrade Notes
+For classic `@ember/component` subclasses, `ember-css-modules` has had support for binding static and dynamic local class names to the component's root element using either `.extend()` or decorator syntax:
+
+```js
+export default Component.extend({
+  localClassNames: ['always-present'],
+  localClassNameBindings: ['flipACoin'],
+
+  flipACoin: computed(function() {
+    return Math.random() > 0.5 ? 'yes-class' : 'no-class';
+  }),
+});
+```
+
+```js
+@localClassNames('always-present')
+export default class MyComponent extends Component {
+  @localClassName flipACoin = Math.random() > 0.5 ? 'yes-class' : 'no-class';
+}
+```
+
+Both versions of these APIs are now deprecated, as:
+  1. they rely on monkey-patching `Ember.Component`, which is itself [now deprecated](https://github.com/emberjs/rfcs/pull/671)
+  1. they're parallels of the `classNames` and `classNameBindings` APIs that are no longer relevant in modern Ember applications
+
+Depending on your appetite for refactoring and modernizing, you might take one of three approaches to migrating off of these APIs:
+  1. Convert your components to use the modern `@glimmer/component` base class instead of `@ember/component`. Since Glimmer component templates have "outer HTML" semantics, there's no implicit root element for these APIs to apply to. See the [Octane vs Classic cheat sheet](https://ember-learn.github.io/ember-octane-vs-classic-cheat-sheet/) for further details on the differences between classic and Glimmer components.
+  1. Use `tagName: ''` to remove the implicit root element from your classic component, then add a corresponding explicit root element to your template, where you can use `local-class` as you would for any other element.
+  1. Import the class name mapping from your styles module and use that with the classic `classNames` and `classNameBindings` APIs:
+     ```js
+     import styles from './styles';
+
+     export default Component.extend({
+       classNames: [styles['always-present']],
+       classNameBindings: ['flipACoin'],
+
+       flipACoin: computed(function() {
+         return Math.random() > 0.5 ? styles['yes-class'] : styles['no-class'];
+       }),
+     });
+     ```
+
+## 1.4.0 (May 17, 2021)
 ### Added
 - We now support a wider range of dependencies that includes PostCSS 8 out of the box. Depending on your package manager, you'll likely see this upgrade take effect automatically when you update ECM, and you may see deprecation warnings for any older PostCSS plugins you're using.
 

packages/ember-css-modules/addon/mixins/component-mixin.js

@@ -4,7 +4,7 @@ import { computed, defineProperty } from '@ember/object';
 import Mixin from '@ember/object/mixin';
 import { dasherize } from '@ember/string';
 import { getOwner } from '@ember/application';
-import { assert } from '@ember/debug';
+import { assert, deprecate } from '@ember/debug';
 
 export default Mixin.create({
   localClassNames: null,
@@ -42,6 +42,22 @@ export default Mixin.create({
       layout
     );
 
+    deprecate(
+      'Support for `localClassNames`, `localClassNameBindings` and the `@localClassName` and `@localClassNames` ' +
+      'decorators will be removed in the next major release of ember-css-modules. The `' + name + '` component ' +
+      'uses one or more of these APIs. See the ECM 1.5.0 release notes for further details and migration options: ' +
+      'https://github.com/salsify/ember-css-modules/releases/tag/v1.5.0',
+      false,
+      {
+        id: 'ember-css-modules.classic-component-apis',
+        for: 'ember-css-modules',
+        until: '2.0.0',
+        since: {
+          enabled: '1.5.0'
+        }
+      }
+    );
+
     // Since https://github.com/emberjs/ember.js/pull/18096
     if (typeof layout === 'function') layout = layout(getOwner(this));
 

yarn.lock

@@ -6621,7 +6621,7 @@ ember-compatibility-helpers@^1.0.2, ember-compatibility-helpers@^1.1.1, ember-co
     semver "^5.4.1"
 
 "ember-css-modules@link:packages/ember-css-modules":
-  version "1.3.4"
+  version "1.4.0"
   dependencies:
     broccoli-bridge "^1.0.0"
     broccoli-concat "^3.2.2"
@@ -6860,9 +6860,9 @@ ember-resolver@^8.0.2:
     resolve "^1.17.0"
 
 ember-rfc176-data@^0.3.12, ember-rfc176-data@^0.3.15, ember-rfc176-data@^0.3.16, ember-rfc176-data@^0.3.5:
-  version "0.3.16"
-  resolved "https://registry.yarnpkg.com/ember-rfc176-data/-/ember-rfc176-data-0.3.16.tgz#2ace0ac9cf9016d493a74a1d931643a308679803"
-  integrity sha512-IYAzffS90r2ybAcx8c2qprYfkxa70G+/UPkxMN1hw55DU5S2aLOX6v3umKDZItoRhrvZMCnzwsdfKSrKdC9Wbg==
+  version "0.3.17"
+  resolved "https://registry.yarnpkg.com/ember-rfc176-data/-/ember-rfc176-data-0.3.17.tgz#d4fc6c33abd6ef7b3440c107a28e04417b49860a"
+  integrity sha512-EVzTTKqxv9FZbEh6Ktw56YyWRAA0MijKvl7H8C06wVF+8f/cRRz3dXxa4nkwjzyVwx4rzKGuIGq77hxJAQhWWw==
 
 ember-router-generator@^1.2.3:
   version "1.2.3"