hotwired · seanpdoyle · Jan 20, 2021 · Mar 27, 2021 · Apr 8, 2021 · Apr 8, 2021
diff --git a/docs/reference/lifecycle_callbacks.md b/docs/reference/lifecycle_callbacks.md
@@ -27,7 +27,9 @@ Method       | Invoked by Stimulus…
 ------------ | --------------------
 initialize() | Once, when the controller is first instantiated
 connect()    | Anytime the controller is connected to the DOM
+[name]TargetConnected(target: Element) | Anytime a target is connected to the DOM
 disconnect() | Anytime the controller is disconnected from the DOM
+[name]TargetDisconnected(target: Element) | Anytime a target is disconnected from the DOM
 
 ## Connection
 
@@ -38,6 +40,15 @@ A controller is _connected_ to the document when both of the following condition
 
 When a controller becomes connected, Stimulus calls its `connect()` method.
 
+### Targets
+
+A target is _connected_ to the document when both of the following conditions are true:
+
+* its element is present in the document as a descendant of its corresponding controller's element
+* its identifier is present in the element's `data-{identifier}-target` attribute
+
+When a target becomes connected, Stimulus calls its controller's `[name]TargetConnected()` method, passing the target element as a parameter.
+
 ## Disconnection
 
 A connected controller will later become _disconnected_ when either of the preceding conditions becomes false, such as under any of the following scenarios:
@@ -50,12 +61,26 @@ A connected controller will later become _disconnected_ when either of the prece
 
 When a controller becomes disconnected, Stimulus calls its `disconnect()` method.
 
+### Targets
+
+A connected target will later become _disconnected_ when either of the preceding conditions becomes false, such as under any of the following scenarios:
+
+* the element is explicitly removed from the document with `Node#removeChild()` or `ChildNode#remove()`
+* one of the element's parent elements is removed from the document
+* one of the element's parent elements has its contents replaced by `Element#innerHTML=`
+* the element's `data-{identifier}-target` attribute is removed or modified
+* the document installs a new `<body>` element, such as during a Turbo page change
+
+When a target becomes disconnected, Stimulus calls its controller's `[name]TargetDisconnected()` method, passing the target element as a parameter.
+
 ## Reconnection
 
 A disconnected controller may become connected again at a later time.
 
 When this happens, such as after removing the controller's element from the document and then re-attaching it, Stimulus will reuse the element's previous controller instance, calling its `connect()` method multiple times.
 
+Similarly, a disconnected target may be connected again at a later time. Stimulus will invoke its controller's `[name]TargetConnected()` method multiple times.
+
 ## Order and Timing
 
 Stimulus watches the page for changes asynchronously using the [DOM `MutationObserver` API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).

diff --git a/docs/reference/targets.md b/docs/reference/targets.md
@@ -88,6 +88,29 @@ if (this.hasResultsTarget) {
 }
 ```
 
+## Addition and Removal Callbacks
+
+Target _element callbacks_ let you respond whenever a target element is added or
+removed within the controller's element.
+
+Define a method `[name]TargetConnected` or `[name]TargetDisconnected` in the controller, where `[name]` is the name of the target you want to observe for additions or removals. The method receives the element as the first argument.
+
+Stimulus invokes each element callback any time its target elements are added or removed after `connect()` and before `disconnect()` lifecycle hooks.
+
+```js
+export default class extends Controller {
+  static targets = [ "input" ]
+
+  inputTargetConnected(element) {
+    element.classList.add("added-animation")
+  }
+
+  inputTargetDisconnected(element) {
+    element.classList.add("removed-animation")
+  }
+}
+```
+
 ## Naming Conventions
 
 Always use camelCase to specify target names, since they map directly to properties on your controller.
diff --git a/packages/@stimulus/core/src/context.ts b/packages/@stimulus/core/src/context.ts
@@ -7,20 +7,23 @@ import { Module } from "./module"
 import { Schema } from "./schema"
 import { Scope } from "./scope"
 import { ValueObserver } from "./value_observer"
+import { TargetObserver, TargetObserverDelegate } from "./target_observer"
 
-export class Context implements ErrorHandler {
+export class Context implements ErrorHandler, TargetObserverDelegate {
   readonly module: Module
   readonly scope: Scope
   readonly controller: Controller
   private bindingObserver: BindingObserver
   private valueObserver: ValueObserver
+  private targetObserver: TargetObserver
 
   constructor(module: Module, scope: Scope) {
     this.module = module
     this.scope = scope
     this.controller = new module.controllerConstructor(this)
     this.bindingObserver = new BindingObserver(this, this.dispatcher)
     this.valueObserver = new ValueObserver(this, this.controller)
+    this.targetObserver = new TargetObserver(this, this)
 
     try {
       this.controller.initialize()
@@ -32,6 +35,7 @@ export class Context implements ErrorHandler {
   connect() {
     this.bindingObserver.start()
     this.valueObserver.start()
+    this.targetObserver.start()
 
     try {
       this.controller.connect()
@@ -47,6 +51,7 @@ export class Context implements ErrorHandler {
       this.handleError(error, "disconnecting controller")
     }
 
+    this.targetObserver.stop()
     this.valueObserver.stop()
     this.bindingObserver.stop()
   }
@@ -82,4 +87,23 @@ export class Context implements ErrorHandler {
     detail = Object.assign({ identifier, controller, element }, detail)
     this.application.handleError(error, `Error ${message}`, detail)
   }
+
+  // Target observer delegate
+
+  targetConnected(element: Element, name: string) {
+    this.invokeControllerMethod(`${name}TargetConnected`, element)
+  }
+
+  targetDisconnected(element: Element, name: string) {
+    this.invokeControllerMethod(`${name}TargetDisconnected`, element)
+  }
+
+  // Private
+
+  invokeControllerMethod(methodName: string, ...args: any[]) {
+    const controller: any = this.controller
+    if (typeof controller[methodName] == "function") {
+      controller[methodName](...args)
+    }
+  }
 }
diff --git a/packages/@stimulus/core/src/target_observer.ts b/packages/@stimulus/core/src/target_observer.ts
@@ -0,0 +1,86 @@
+import { Multimap } from "@stimulus/multimap"
+import { Token, TokenListObserver, TokenListObserverDelegate } from "@stimulus/mutation-observers"
+import { Context } from "./context"
+
+export interface TargetObserverDelegate {
+  targetConnected(element: Element, name: string): void
+  targetDisconnected(element: Element, name: string): void
+}
+
+export class TargetObserver implements TokenListObserverDelegate {
+  readonly context: Context
+  readonly delegate: TargetObserverDelegate
+  readonly targetsByName: Multimap<string, Element>
+  private tokenListObserver?: TokenListObserver
+
+  constructor(context: Context, delegate: TargetObserverDelegate) {
+    this.context = context
+    this.delegate = delegate
+    this.targetsByName = new Multimap
+  }
+
+  start() {
+    if (!this.tokenListObserver) {
+      this.tokenListObserver = new TokenListObserver(this.element, this.attributeName, this)
+      this.tokenListObserver.start()
+    }
+  }
+
+  stop() {
+    if (this.tokenListObserver) {
+      this.disconnectAllTargets()
+      this.tokenListObserver.stop()
+      delete this.tokenListObserver
+    }
+  }
+
+  // Token list observer delegate
+
+  tokenMatched({ element, content: name }: Token) {
+    if (this.scope.containsElement(element)) {
+      this.connectTarget(element, name)
+    }
+  }
+
+  tokenUnmatched({ element, content: name }: Token) {
+    this.disconnectTarget(element, name)
+  }
+
+  // Target management
+
+  connectTarget(element: Element, name: string) {
+    if (!this.targetsByName.has(name, element)) {
+      this.targetsByName.add(name, element)
+      this.delegate.targetConnected(element, name)
+    }
+  }
+
+  disconnectTarget(element: Element, name: string) {
+    if (this.targetsByName.has(name, element)) {
+      this.targetsByName.delete(name, element)
+      this.delegate.targetDisconnected(element, name)
+    }
+  }
+
+  disconnectAllTargets() {
+    for (const name of this.targetsByName.keys) {
+      for (const element of this.targetsByName.getValuesForKey(name)) {
+        this.disconnectTarget(element, name)
+      }
+    }
+  }
+
+  // Private
+
+  private get attributeName() {
+    return `data-${this.context.identifier}-target`
+  }
+
+  private get element() {
+    return this.context.element
+  }
+
+  private get scope() {
+    return this.context.scope
+  }
+}
diff --git a/packages/@stimulus/core/src/target_properties.ts b/packages/@stimulus/core/src/target_properties.ts
@@ -33,6 +33,6 @@ function propertiesForTargetDefinition(name: string) {
       get(this: Controller) {
         return this.targets.has(name)
       }
-    }
+    },
   }
 }
diff --git a/packages/@stimulus/core/src/tests/controllers/target_controller.ts b/packages/@stimulus/core/src/tests/controllers/target_controller.ts
@@ -9,7 +9,9 @@ class BaseTargetController extends Controller {
 }
 
 export class TargetController extends BaseTargetController {
+  static classes = [ "connected", "disconnected" ]
   static targets = [ "beta", "input" ]
+  static values = { inputTargetConnectedCallCount: Number, inputTargetDisconnectedCallCount: Number }
 
   betaTarget!: Element | null
   betaTargets!: Element[]
@@ -18,4 +20,22 @@ export class TargetController extends BaseTargetController {
   inputTarget!: Element | null
   inputTargets!: Element[]
   hasInputTarget!: boolean
+
+  hasConnectedClass!: boolean
+  hasDisconnectedClass!: boolean
+  connectedClass!: string
+  disconnectedClass!: string
+
+  inputTargetConnectedCallCountValue = 0
+  inputTargetDisconnectedCallCountValue = 0
+
+  inputTargetConnected(element: Element) {
+    if (this.hasConnectedClass) element.classList.add(this.connectedClass)
+    this.inputTargetConnectedCallCountValue++
+  }
+
+  inputTargetDisconnected(element: Element) {
+    if (this.hasDisconnectedClass) element.classList.add(this.disconnectedClass)
+    this.inputTargetDisconnectedCallCountValue++
+  }
 }