From 2e2344c5c029b78e1dcf1f7f7db91839caa0a10c Mon Sep 17 00:00:00 2001
From: Sergey Astapov <SergeAstapov@gmail.com>
Date: Wed, 23 Mar 2022 17:09:15 -0400
Subject: [PATCH 1/6] Element Modifiers

---
 text/0000-element-modifiers.md | 232 +++++++++++++++++++++++++++++++++
 1 file changed, 232 insertions(+)
 create mode 100644 text/0000-element-modifiers.md

diff --git a/text/0000-element-modifiers.md b/text/0000-element-modifiers.md
new file mode 100644
index 0000000000..75d530c3e0
--- /dev/null
+++ b/text/0000-element-modifiers.md
@@ -0,0 +1,232 @@
+---
+Stage: Accepted
+Start Date: 
+Release Date: Unreleased
+Release Versions:
+  ember-source: vX.Y.Z
+  ember-data: vX.Y.Z
+Relevant Team(s): Ember CLI, Learning
+RFC PR: 
+---
+
+<!--- 
+Directions for above: 
+
+Stage: Leave as is
+Start Date: Fill in with today's date, YYYY-MM-DD
+Release Date: Leave as is
+Release Versions: Leave as is
+Relevant Team(s): Fill this in with the [team(s)](README.md#relevant-teams) to which this RFC applies
+RFC PR: Fill this in with the URL for the Proposal RFC PR
+-->
+
+# Element Modifiers
+
+## Summary
+
+This RFC introduces the concept of user defined element modifiers and proposes
+adding [ember-modifier](https://github.com/ember-modifier/ember-modifier)
+to the blueprints that back `ember new` and `ember addon`, providing an
+officially-supported path for using modifiers out of the box.
+
+This RFC supersedes the original [RFC #353 "Modifiers"][rfc-0353].
+
+## Motivation
+
+Ember Octane introduced Glimmer Components as a replacement for Classic
+Components. They are simpler, more ergonomic, and more declarative. In contrast
+with Classic Components, Glimmer Components don't have any element/DOM based
+properties or hooks giving access to DOM. This was an intentional move as
+component baking class gets disconnected from DOM manipulation.
+
+Modifiers are similar to template helpers: they are functions or classes that can be used
+in templates directly using `{{double-curlies}}` syntax. The major difference with modifiers
+is that they are applied directly to *elements*:
+
+```handlebars
+<button {{effect "fade-in"}}>Save</button>
+```
+
+This RFC builds on top of low-level primitives for defining element modifiers
+introduced in [RFC #373 "Element Modifier Manager"][rfc-0373].
+The `ember-modifier` addon was built on top of those low-level primitives and
+provides a convenient API for authoring element modifiers in Ember.
+
+Element Modifiers were introduced as part of Ember Octane edition and are first class citizens
+in Ember application, like components or helpers. However today, developers need to install
+an additional library to be able to define custom modifiers.
+
+This RFC seeks to fill this gap in Ember.js' development mental model by
+providing `ember-modifier` in the blueprint.
+
+A basic element modifier is defined with the type of `modifier`.
+For example these paths would be global element modifiers in an application:
+
+* `app/modifiers/draggable.js`
+* `app/modifiers/effect.js`
+
+Similar to helpers, modifiers can be function-based:
+
+```js
+// /app/modifiers/on.js
+import { modifier } from 'ember-modifier';
+
+export default modifier((element, [eventName, handler]) => {
+  element.addEventListener(eventName, handler);
+
+  return () => {
+    element.removeEventListener(eventName, handler);
+  }
+});
+```
+
+or class-based
+
+```ts
+// /app/modifiers/on.js
+import Modifier from 'ember-modifier';
+import { registerDestructor } from '@ember/destroyable';
+
+function cleanup(instance: OnModifier) {
+  let { element, event, handler } = instance;
+
+  if (element && event && handler) {
+    element.removeEventListener(event, handler);
+
+    instance.element = null;
+    instance.event = null;
+    instance.handler = null;
+  }
+}
+
+export default class OnModifier extends Modifier {
+  element = null;
+  event = null;
+  handler = null;
+
+  // Manage teardown
+  constructor() {
+    super(...arguments);
+    registerDestructor(this, cleanup);
+  }
+
+  // Run on installation and all changes to tracked state.
+  modify(element, [event, handler]) {
+    // Clear any previous state.
+    cleanup(this);
+
+    // Set up the new handling.
+    this.addEventListener(element, event, handler);
+  }
+
+  // methods for reuse
+  addEventListener(element, event, handler) {
+    // Store the current element, event, and handler for when we need to remove
+    // them during cleanup.
+    this.element = element;
+    this.event = event;
+    this.handler = handler;
+
+    element.addEventListener(event, handler);
+  };
+}
+```
+
+While this is slightly more complicated than the function-based version,
+that complexity comes along with much more *control*. It also allows us to hook
+into Ember's dependency injection system, for example to use services.
+
+[RFC #432: Contextual Helpers and Modifiers][rfc-0432] allows optional
+invocation and partial application of modifiers, and allows modifiers to be
+yielded, passed as arguments, etc. [RFC #779: First-Class Component
+Templates][rfc-0779] allows defining them locally or importing them directly to
+be used in a `<template>` context. This combination makes many patterns much
+easier to implement:
+
+```js
+// /app/components/slide-up-card.js
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+
+const lockBodyScroll = modifier((element, [shouldLockBodyScroll]) => {
+  document.body.classList.add('lock-scroll');
+  return () => document.body.classList.remove('lock-scroll');
+});
+
+export default class SlideUpCard extends Component {
+  @action closeCard (event) {
+    event.preventDefault();
+    this.args.close();
+  }
+
+  <template>
+    {{#if has-block}}
+      {{yield (hash lock=lockBodyScroll onClick=this.closeCard)}}
+    {{else}}
+      <div
+        class="slide-up-card"
+        ...attributes
+        {{lockBodyScroll}}
+      >
+        <p>{{@bodyContent}}</p>
+
+        <button {{on "click" this.closeCard}}>Dismiss</button>
+      </div>
+    {{/if}}
+  </template>
+}
+```
+
+## Detailed design
+
+The necessary changes to `ember-cli` are relatively small since we only need
+to add the dependency to the `app` blueprint, and the `addon` blueprint will
+inherit it automatically.
+
+This has the advantage (over including it as an implicit dependency), that
+apps and addons that don't want to use it for some reason can opt out by
+removing the dependency from their `package.json` file.
+
+## How we teach this
+
+Ember Guides already teach how to use modifiers in "Template Lifecycle, DOM, and Modifiers"
+section of the guides.
+
+However, there are a couple changes we need to make to the content of the
+guides as they stand today:
+
+1. We will remove the "install `ember-modifier`" instruction from the guides,
+   since it will already be part of the blueprint.
+2. We should include at least a minimal example of a class-based modifier. For
+   that example, we can use something like `setInterval` to show how setup,
+   updates, and teardown can be more convenient when using a class.
+   (Note that here we should *only* teach the [newly-redesigned API][v3.2.0], not
+   the deprecated previous APIs. This will simplify our teaching significantly,
+   since we can describe how it matches the `Helper` APIs.)
+
+## Drawbacks
+
+- If we merge [RFC #757 "Default Modifier Manager][rfc-0757],
+  it may seem redundant with this RFC.
+- There is the potential for confusion between the `ember-modifier` package and
+  the `@ember/modifier` package which ships as part of `ember-source`.
+
+## Alternatives
+
+- Introduce [RFC #757 "Default Modifier Manager][rfc-0757]
+  creating modifiers and ask developers to install `ember-modifier`
+  for more complex use cases.
+- Integrate `ember-modifier` into the `@ember/modifier` package directly.
+- Introduce a new `@ember/*` or `@glimmer/*` package for the contents of
+  `ember-modifier`.
+
+## Unresolved questions
+
+None.
+
+[rfc-0353]: https://github.com/emberjs/rfcs/pull/353
+[rfc-0373]: https://emberjs.github.io/rfcs/0373-Element-Modifier-Managers.html
+[rfc-0432]: https://emberjs.github.io/rfcs/0432-contextual-helpers.html
+[rfc-0757]: https://github.com/emberjs/rfcs/pull/757
+[rfc-0779]: https://github.com/emberjs/rfcs/pull/779
+[v3.2.0]: https://github.com/ember-modifier/ember-modifier/releases/tag/v3.2.0
\ No newline at end of file

From 8522fa82270c27ce51c48da0933c439fadc637fb Mon Sep 17 00:00:00 2001
From: Sergey Astapov <SergeAstapov@gmail.com>
Date: Tue, 29 Mar 2022 16:18:50 -0400
Subject: [PATCH 2/6] Update PR number

---
 text/{0000-element-modifiers.md => 0811-element-modifiers.md} | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
 rename text/{0000-element-modifiers.md => 0811-element-modifiers.md} (99%)

diff --git a/text/0000-element-modifiers.md b/text/0811-element-modifiers.md
similarity index 99%
rename from text/0000-element-modifiers.md
rename to text/0811-element-modifiers.md
index 75d530c3e0..b7796d3fd9 100644
--- a/text/0000-element-modifiers.md
+++ b/text/0811-element-modifiers.md
@@ -1,12 +1,12 @@
 ---
 Stage: Accepted
-Start Date: 
+Start Date: 2022-03-29
 Release Date: Unreleased
 Release Versions:
   ember-source: vX.Y.Z
   ember-data: vX.Y.Z
 Relevant Team(s): Ember CLI, Learning
-RFC PR: 
+RFC PR: https://github.com/emberjs/rfcs/pull/811
 ---
 
 <!--- 

From b42a021021ad93bf86d0683b2d3515fc13b049a6 Mon Sep 17 00:00:00 2001
From: Sergey Astapov <SergeAstapov@gmail.com>
Date: Fri, 29 Apr 2022 14:58:34 -0400
Subject: [PATCH 3/6] RFC 811: Add note about ember-modifer goes to
 `devDependencies`

---
 text/0811-element-modifiers.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/text/0811-element-modifiers.md b/text/0811-element-modifiers.md
index b7796d3fd9..cf2395b75c 100644
--- a/text/0811-element-modifiers.md
+++ b/text/0811-element-modifiers.md
@@ -37,7 +37,7 @@ Ember Octane introduced Glimmer Components as a replacement for Classic
 Components. They are simpler, more ergonomic, and more declarative. In contrast
 with Classic Components, Glimmer Components don't have any element/DOM based
 properties or hooks giving access to DOM. This was an intentional move as
-component baking class gets disconnected from DOM manipulation.
+component backing class gets disconnected from DOM manipulation.
 
 Modifiers are similar to template helpers: they are functions or classes that can be used
 in templates directly using `{{double-curlies}}` syntax. The major difference with modifiers
@@ -57,7 +57,8 @@ in Ember application, like components or helpers. However today, developers need
 an additional library to be able to define custom modifiers.
 
 This RFC seeks to fill this gap in Ember.js' development mental model by
-providing `ember-modifier` in the blueprint.
+providing `ember-modifier` in the blueprint. `ember-modifier` will be added
+to `devDependencies`, same as e.g. @glimmer/component.
 
 A basic element modifier is defined with the type of `modifier`.
 For example these paths would be global element modifiers in an application:

From 4e96097aed145f4a2a67f6f4bca6e53b1a639a04 Mon Sep 17 00:00:00 2001
From: Sergey Astapov <SergeAstapov@gmail.com>
Date: Fri, 29 Apr 2022 15:03:30 -0400
Subject: [PATCH 4/6] RFC 811: element-modifier RFC - add more notes

* note about future potential `@glimmer/modifier`
* note about adding community addons to blueprint
---
 text/0811-element-modifiers.md | 41 ++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/text/0811-element-modifiers.md b/text/0811-element-modifiers.md
index cf2395b75c..e2b1bce5f0 100644
--- a/text/0811-element-modifiers.md
+++ b/text/0811-element-modifiers.md
@@ -188,6 +188,47 @@ This has the advantage (over including it as an implicit dependency), that
 apps and addons that don't want to use it for some reason can opt out by
 removing the dependency from their `package.json` file.
 
+**Notes:**
+1. This is *not* the usual path for delivering features into Ember: we do not
+   generally introduce community addons directly into the blueprint. In this
+   specific case, we think it is the right move:
+
+    - The addon has intentionally been reworked to rationalize it in
+      terms of the rest of the Octane programming model, explicitly with an eye to adoption in this way.
+    - We do *not* want to introduce `@glimmer/modifier` with exactly this
+      API, at least not yet, because we believe we may want to introduce
+      a slightly updated API from that package *without* requiring
+      breaking changes in the future.
+2. We are intentionally introducing more "incoherence" to the programming
+   model with this addition. (Or rather, we are acknowledging the *existing*
+   incoherence in the ecosystem, with an eye to making progress on resolving
+   it!) In particular, as the community begins adopting strict mode templates
+   via First-Class Component Templates in the months ahead, they will often
+   end up importing from both `ember-modifier` and `@ember/modifier`:
+
+   ```js
+   import { on } from '@ember/modifier';
+   import { modifier } from 'ember-modifier';
+   const playWhen = modifier((el, [shouldPlay]) => {
+     if (shouldPlay) {
+       el.play();
+     } else {
+       el.pause();
+     }
+   });
+   <template>
+     <audio
+       src={{@src}}
+       {{on "error" @onBadLoad}}
+       {{playWhen @shouldPlay}}
+     />
+   </template>
+   ```
+
+   As noted in (1) above, we have ideas on how to resolve this, but are
+   intentionally not blocking on those in favor of unlocking this key
+   functionality for Ember users in the Octane programming model *today*.
+
 ## How we teach this
 
 Ember Guides already teach how to use modifiers in "Template Lifecycle, DOM, and Modifiers"

From 808da756585338f7badceff969490982b621f51f Mon Sep 17 00:00:00 2001
From: Sergey Astapov <SergeAstapov@gmail.com>
Date: Thu, 22 Sep 2022 10:58:14 -0400
Subject: [PATCH 5/6] RFC 811: fix frontmatter and add note about addon
 blueprint

---
 text/0811-element-modifiers.md | 43 ++++++++++++++++++++--------------
 1 file changed, 25 insertions(+), 18 deletions(-)

diff --git a/text/0811-element-modifiers.md b/text/0811-element-modifiers.md
index e2b1bce5f0..5d46f60a77 100644
--- a/text/0811-element-modifiers.md
+++ b/text/0811-element-modifiers.md
@@ -1,23 +1,27 @@
 ---
-Stage: Accepted
-Start Date: 2022-03-29
-Release Date: Unreleased
-Release Versions:
-  ember-source: vX.Y.Z
-  ember-data: vX.Y.Z
-Relevant Team(s): Ember CLI, Learning
-RFC PR: https://github.com/emberjs/rfcs/pull/811
+stage: accepted
+start-date: 2022-03-29T00:00:00.000Z
+release-date:
+release-versions:
+teams: # delete teams that aren't relevant
+  - cli
+  - learning
+prs:
+  accepted: https://github.com/emberjs/rfcs/pull/811
+project-link:
 ---
 
 <!--- 
 Directions for above: 
 
-Stage: Leave as is
-Start Date: Fill in with today's date, YYYY-MM-DD
-Release Date: Leave as is
-Release Versions: Leave as is
-Relevant Team(s): Fill this in with the [team(s)](README.md#relevant-teams) to which this RFC applies
-RFC PR: Fill this in with the URL for the Proposal RFC PR
+stage: Leave as is
+start-date: Fill in with today's date, 2032-12-01T00:00:00.000Z
+release-date: Leave as is
+release-versions: Leave as is
+teams: Include only the [team(s)](README.md#relevant-teams) for which this RFC applies
+prs:
+  accepted: Fill this in with the URL for the Proposal RFC PR
+project-link: Leave as is
 -->
 
 # Element Modifiers
@@ -26,7 +30,7 @@ RFC PR: Fill this in with the URL for the Proposal RFC PR
 
 This RFC introduces the concept of user defined element modifiers and proposes
 adding [ember-modifier](https://github.com/ember-modifier/ember-modifier)
-to the blueprints that back `ember new` and `ember addon`, providing an
+to the blueprint that back `ember new`, providing an
 officially-supported path for using modifiers out of the box.
 
 This RFC supersedes the original [RFC #353 "Modifiers"][rfc-0353].
@@ -181,11 +185,14 @@ export default class SlideUpCard extends Component {
 ## Detailed design
 
 The necessary changes to `ember-cli` are relatively small since we only need
-to add the dependency to the `app` blueprint, and the `addon` blueprint will
-inherit it automatically.
+to add the dependency to the `app` blueprint.
+
+Note that `addon` blueprint will not include `ember-modifier` due to
+unresolved question (at the time of writing this RFC) regarding how addons
+should declare dependencies like `@glimmer/component`, `@glimmer/tracking`, `ember-modifier` etc.
 
 This has the advantage (over including it as an implicit dependency), that
-apps and addons that don't want to use it for some reason can opt out by
+apps that don't want to use it for some reason can opt out by
 removing the dependency from their `package.json` file.
 
 **Notes:**

From cd4429266a184d55ef2f3cdbd8f527c5704057ed Mon Sep 17 00:00:00 2001
From: Sergey Astapov <SergeAstapov@gmail.com>
Date: Tue, 8 Nov 2022 07:26:55 -0500
Subject: [PATCH 6/6] RFC 811: update links to Modifier RFC in Modifier Manager
 RFC

---
 text/0373-Element-Modifier-Managers.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/text/0373-Element-Modifier-Managers.md b/text/0373-Element-Modifier-Managers.md
index b372be21e4..cb98a99ad5 100644
--- a/text/0373-Element-Modifier-Managers.md
+++ b/text/0373-Element-Modifier-Managers.md
@@ -16,13 +16,13 @@ project-link:
 
 ## Summary
 
-This RFC proposes a low-level primitive for defining element modifiers. It is a parent to the [Modifiers RFC](https://github.com/emberjs/rfcs/pull/353).
+This RFC proposes a low-level primitive for defining element modifiers. It is a parent to the [Element Modifiers RFC](https://github.com/emberjs/rfcs/pull/811).
 
 ## Motivation
 
 Ever since Ember 1.0 we have had the concept of element modifiers, however Ember only exposes one modifier; `{{action}}`. We also do not provide a mechanism for defining your own modifiers and managing their life cycles.
 
-As [pointed out](https://github.com/emberjs/rfcs/pull/353#issuecomment-417769349) in the [Element Modifiers RFC](https://github.com/emberjs/rfcs/pull/353) we should expose the underlying infrastructure that makes element modifiers possible. Based on our experience, we believe it would be beneficial to open up these new primitives to the wider community. The largest benefit is that it allows the community to experiment with and iterate on APIs outside of the core framework.
+As [pointed out](https://github.com/emberjs/rfcs/pull/353#issuecomment-417769349) in the original [Modifiers RFC](https://github.com/emberjs/rfcs/pull/353) we should expose the underlying infrastructure that makes element modifiers possible. Based on our experience, we believe it would be beneficial to open up these new primitives to the wider community. The largest benefit is that it allows the community to experiment with and iterate on APIs outside of the core framework.
 
 This RFC is in the same spirit as the [custom components RFC](https://github.com/emberjs/rfcs/blob/master/text/0213-custom-components.md).
 
@@ -458,7 +458,8 @@ What is proposed in this RFC is a low-level primitive. We do not expect most use
 In the long term, there is a risk of fragmentating the Ember ecosystem with many competing modifier APIs. However, given the Ember community's strong desire for conventions, this seems unlikely. We expect this to play out similar to the data-persistence story – there will be a primary way to do things (Ember Data), but there are also plenty of other alternatives catering to niche use cases that are underserved by Ember Data.
 
 ## Alternatives
-Instead of focusing on exposing enough low-level primitives we can just ship the high level API as described in [RFC#353](https://github.com/emberjs/rfcs/pull/353).
+Instead of focusing on exposing enough low-level primitives we can just ship the high level API as described in [RFC#811](https://github.com/emberjs/rfcs/pull/811).
+
 ## Unresolved questions
 
 TBD?