From 83e59089f0c6e62ca0e8802d6109290ef026e167 Mon Sep 17 00:00:00 2001
From: Ben Howell <48106640+behowell@users.noreply.github.com>
Date: Fri, 14 Jun 2024 10:17:25 -0700
Subject: [PATCH] Update Reference Target Explainer to add support for nesting
 inside labels (#210)

---
 reference-target-explainer.md | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/reference-target-explainer.md b/reference-target-explainer.md
index 48b121f..076e0dc 100644
--- a/reference-target-explainer.md
+++ b/reference-target-explainer.md
@@ -250,7 +250,9 @@ A [form-associated custom element](https://html.spec.whatwg.org/dev/custom-eleme
 
 #### Nesting inside `<label>`
 
-There is no special support for an element nested inside a label. The label must use the `for` attribute to work with `referenceTarget`. It is still ok to nest the custom element inside the label, but it must also use `for`.
+Reference Target allows for labels to be implicitly associated with the target element when the host is nested inside a `<label>` element. The shadow tree's reference target will be associated with the label that contains the element. If the shadow tree is using `referenceTargetMap`, this uses the `for` attribute from the map.
+
+In the following example, the label of the `<input id="real-input">` is "Fancy input".
 
 ```html
 <script>
@@ -262,24 +264,17 @@ There is no special support for an element nested inside a label. The label must
         this.shadowRoot_ = this.attachShadow({ mode: "closed" });
         this.shadowRoot_.innerHTML = `<input id="real-input" />`;
         this.shadowRoot_.referenceTarget = "real-input";
+        // Alternatively, set the referenceTargetMap with the `for` attribute:
+        // this.shadowRoot_.referenceTargetMap.htmlFor = "real-input";
       }
     }
   );
 </script>
 
-<!-- ❌ This label isn't associated with anything because it doesn't use `for`, 
-     and fancy-input is not form-associated. -->
 <label>
-  Fancy Input
+  Fancy input
   <fancy-input></fancy-input>
 </label>
-
-<!-- ✅ This label is applied to the inner `<input id="real-input" />`, which is 
-     fancy-input's referenceTarget. -->
-<label for="fancy-input">
-  Fancy Input
-  <fancy-input id="fancy-input"></fancy-input>
-</label>
 ```
 
 #### Nesting inside `<form>`