Reference Target: How to handle events fired on the reference target by related elements?

[alice]

This was raised by @jakearchibald in whatwg/html#10707 (comment):

An interesting case here:

<button popovertarget="component-a">…</button>
<component-a id="component-a">
  <template shadowrootmode="closed" shadowrootreferencetarget="inner-thing">
    <div id="inner-thing" popover>…</div>
  </template>
</component-a>

As the owner of the button, is it weird that I don't get a toggle event on component-a, despite the popover being successfully opened?

and whatwg/html#11148 (comment):

Because the problem is referenceTarget specific, a solution tailored to referenceTarget seems ok. As in, the command event (and other related events like popover toggle) can flow through retargeted boundaries.

<component-a>
  <template shadowrootmode="closed">
    <button command="--foo" commandFor="component-b">…</button>
    <component-b id="component-b">
      <template shadowrootmode="closed" shadowrootreferencetarget="inner-thing">
        <div id="inner-thing"></div>
      </template>
    </component-b>
  </template>
</component-a>

In the example above, the command would be seen within component-b's shadow root, since that's where the ultimate target is, but it would also be seen in component-a's shadow root, since it was retargeted from there.

We'd need to consider cases where retargeting was between multiple shadow roots.

[We should] work on the referenceTarget-specific issues as part of that feature work. I don't think we should solve this just for command, nor should we end up having to default to composed events everywhere due to referenceTarget.

---

My proposal (see also #1098 (comment)):

• Certain events get a source, which already exists on CommandEvent. We would also need to add it to:
  • SubmitEvent, which already has submitter for the same thing, so submitter could be used as an alias
  • ToggleEvent
  • The definition of the event concept, so that it can be used in algorithms, analogous to how relatedTarget is.
• Set source to the element which causes an event to fire on another element before firing the event; some locations for where this needs to happen are listed below.
• Modify shadow root's get the parent algorithm to:
  1. let target be event’s path’s first struct’s invocation target;
  2. if event’s composed flag is set, return shadow root’s host;
  3. if shadow root is not the root of target, and event does not have a source or shadow root is not the root of event's source, return shadow root's host;
  4. if event has a source, and event's source's root is a shadow-including ancestor of shadow root, return the result of retargeting target against event's triggering element;
  5. otherwise, return null.

Some places we'd need to modify event initialisation:

• form submission with submitter as the source
• show popover when invoker is not null, with invoker as the source
• dialog invoker command steps leads to two potential algorithms which would both need to be updated to include the source:
  • show a modal dialog
  • close the dialog
  • These each fire a beforetoggle event and queue a dialog toggle event task
• custom command on <button> should already work as-is with the new "get the parent" logic for shadow roots.

---

Draft PRs:
whatwg/dom#1377
whatwg/html#11349

[alice]

I think one "solution" worth exploring might be whether popoverTarget is worth scoping out of reference target behaviour. I think you could potentially make a reasonable case that authors would expect it to apply to the shadow host even when the shadow host has a reference target: if I have some kind of <fancy-thing> which includes <thing> with a bunch of extra elements for presentation/information/etc, I probably wouldn't expect only <thing> to show up as the popover.

I'm even less sure about commandFor, but I think a similar argument might apply?

I agree with Jake that if they are scoped in, we should try to avoid requiring authors to do extra work to make these events work reasonably.

I think either way, it might be worth considering what plausible scenarios there are for how popoverTarget and commandFor might end up referring to a shadow host with a reference target; I'm having trouble imagining how that might eventuate, which makes it difficult to reason about what a good solution might be.

[alice]

Also, are there attributes other than popoverTarget and commandFor which cause events to be fired on the target element like this, that should be considered as part of this discussion?

[jakearchibald]

There's <label for="…">, but I don't think that's a concern because there are already custom element features that redirect focus, and focus is a composed event.

<input form="…"> is interesting here, in relation to the submit event.

<input list="…"> is interesting in terms of this feature, but not to do with events.

There are other bits of linking, such as SVG <use>.

That's all I could find from a quick skim of the HTML spec.

[Westbrook]

We SHOULD NOT scope these things out.

This is 100% where refereneTargetMap would come in and allow people to decide what things to map through or not. I might even go so far as to say that were these attributes of high interest in not mapping, that they would point to the referenceTargetExcludes or similar idea that a couple of people brought up through the course.

Would it be bonkers to add a "referenced" event that rather than composing through the whole DOM tree created an event path that only included the host and the target elements, and as such listing only those two in its composedPath()?

[alice]

@Westbrook can you envisage a scenario where popover or commandfor might be used to refer to an element with a reference target set?

I'm not committed one way or another to arguing we should scope them out, I just want to have all options on the table. Scoping them out would certainly be a pain on the spec side, for one thing, so if anything I'd probably err on the side of leaving them in for purely selfish reasons. But I think unless we can come up with a plausible scenario to reason about, it's going to be difficult to figure out what sensible defaults might be here.

[alice]

Here's an example using form (thanks @jakearchibald) that might be helpful:

<x-form id="x-form">
  <template shadowRootMode="open" referenceTarget="form">
    <form id="form"></form>
  </template>
</x-form>
<label>Name: <input form="x-form"></label>
<input type="submit" form="x-form">

If a user clicks the Submit button, it definitely seems like the page should get a chance to cancel the submission by listening for the submit event on <x-form>.

Do we think that is equally true if the form was submitted some other way? For example:

<x-form id="x-form">
  <template shadowRootMode="open" referenceTarget="form">
    <form id="form">
        <slot></slot>
        <input type="submit">
    </form>
  </template>
  <label>Name: <input form="x-form"></label>
</x-form>

If I hit that submit button, should the submit event be fired on the <x-form>?

[Westbrook]

Off the top of my head, I would not be surprised to see this pattern:

<button popovertarget="popover">Toggle</button>
<x-popover id="popover">
  <template shadowRootMode="open" referenceTarget="container">
    <style>
      #container {
        /* completely encapsulated styles for the popover */
      }
    </style>
    <div id="container" popover>
     Popover content.
    </div>
  </template>
</x-popover>

I'm not sure if I'd call it contrived or convention.

This style of usage is built directly into patterns like https://opensource.adobe.com/spectrum-web-components/components/overlay/ via JS mapping due to how it benefitted polyfilling browsers that did not support Popover, and likely will persist to polyfilling browsers that do not have Anchor Position just the same.

[alice]

Thanks for the example @Westbrook, that helps a lot.

I think your idea:

add a "referenced" event that rather than composing through the whole DOM tree created an event path that only included the host and the target elements, and as such listing only those two in its composedPath()

seems like a pretty good starting point.

I think for my question above, I would say that in the second case the event shouldn't be "referenced" - i.e. that because the submit action doesn't come from outside the shadow root, the event should stay within.

Likewise, for your example, if we changed it to something like:

<x-popover id="popover">
  <template shadowRootMode="open" referenceTarget="container">
    <style>
      #container {
        /* completely encapsulated styles for the popover */
      }
    </style>
    <button popovertarget="popover">Toggle</button>
    <div id="container" popover>
     Popover content.
    </div>
  </template>
</x-popover>

Where there is still a referenceTarget pointing at the popover, but the button inside of the shadow root is actually what is used to toggle it, then the event should stay within the shadow root.

old version

To that end, I think we might want something like:

• Add a "trigger element" alongside target
• Set the "trigger element" for events which are specifically triggered via attribute-associated elements (see below)
• Modify shadow root's get the parent algorithm to something like:
  1. let target be event’s path’s first struct’s invocation target;
  2. if event’s composed flag is set, or shadow root is not the root of target, return return shadow root’s host;
  3. otherwise, if event has a triggering element, and event's triggering element's root is a shadow-including ancestor of shadow root, return the result of retargeting target against event's triggering element;
  4. otherwise, return null.

That's a pretty quick and dirty sketch, but I think something like that would work? The idea of step 3 is to retarget target only if the triggering element is associated via reference target, i.e. if the triggering element uses something like popoverTargetElement from the same or deeper shadow root, it should return null.

After working through a bunch of examples, here's a refined version of the logic:

• Certain events get a source, which already exists on CommandEvent. We would also need to add it to:
  • SubmitEvent, which already has submitter for the same thing, so submitter could be used as an alias
  • ToggleEvent
  • The definition of the event concept, so that it can be used in algorithms, analogous to how relatedTarget is.
• Set source to the element which causes an event to fire on another element before firing the event; some locations for where this needs to happen are listed below.
• Modify shadow root's get the parent algorithm to:
  1. let target be event’s path’s first struct’s invocation target;
  2. if event’s composed flag is set, return shadow root’s host;
  3. if shadow root is not the root of target, and event does not have a source or shadow root is not the root of event's source, return shadow root's host;
  4. if event has a source, and event's source's root is a shadow-including ancestor of shadow root, return the result of retargeting target against event's triggering element;
  5. otherwise, return null.

Some places we'd need to modify event initialisation:

• form submission with submitter as the source
• show popover when invoker is not null, with invoker as the source
• dialog invoker command steps leads to two potential algorithms which would both need to be updated to include the source:
  • show a modal dialog
  • close the dialog
  • These each fire a beforetoggle event and queue a dialog toggle event task
• custom command on <button> should already work as-is with the new "get the parent" logic for shadow roots.

[jakearchibald]

It might be worth looking at relatedTarget if you haven't already, which is doing… something maybe related? Sorry hah I'm ill and can't parse the spec properly.

https://dom.spec.whatwg.org/#concept-event-dispatch

[alice]

I think relatedTarget is for things like focus and blur events, where there is another element which is, well, related, but isn't actually a target for this event:

https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/relatedTarget
https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/relatedTarget

(Figuring that out from the spec is a massive pain, but the MDN documentation matches what I can gather from the spec, so massive props to whichever tech writer figured that all out.)

[alice]

Working through the logic I proposed in #1098 (comment) with some examples:

button with popovertarget outside of shadow root referring to popover element via reference target

From #1098 (comment)

<button id="button" popovertarget="popover">Toggle</button>
<x-popover id="popover">
  <template shadowRootMode="open" shadowRootReferenceTarget="container">
    <style>
      #container {
        /* completely encapsulated styles for the popover */
      }
    </style>
    <div id="container" popover>
     Popover content.
    </div>
  </template>
</x-popover>

1. User clicks button.

2. The button activation behaviour algorithm falls through to Step 6:

   run the popover target attribute activation behavior given element and event's target

   element and event's target are both button, because event is the click event on button.

3. The popover target attribute activation behavior algorithm takes button as the value for both node and eventTarget.

4. Let popover be button's popover target element -> popover is now container (via the reference target).

5. Assuming the popover wasn't already showing, the algorithm falls through to step 7:

   run show popover given popover, false, and node.

   popover being container and node being button.

6. In show popover, element is container and invoker is button.

7. 🆕 In step 9, we would need to pass invoker i.e. button as the source to the fire an event algorithm - something like "with the source attribute initialized to invoker".

8. 🆕 In fire an event, the source is part of the initialization of event in step 4.

9. 🆕 In event dispatch, we now get a source as part of event.

10. In step 6.8 and step 6.9.9 of event dispatch, the algorithm calls into get the parent with event.

11. When a node's get the parent is invoked on container, it returns the shadow root as normal.

12. 🆕 When a shadow root's get the parent is invoked on the shadow root, we go to the new logic:

    1. let target be event’s path’s first struct’s invocation target;
    2. if event’s composed flag is set, return shadow root’s host;
    3. if shadow root is not the root of target, and event does not have a source or shadow root is not the root of event's source, return shadow root's host;
    4. if event has a source, and event's source's root is a shadow-including ancestor of shadow root, return the result of retargeting target against event's triggering element;
    5. otherwise, return null.

    1. target is container;
    2. composed flag is not set;
    3. shadow root is the root of target (false); event has an source, button; shadow root is not the root of button (true); false && true so we go to step 4;
    4. button's root (Document) is a shadow-including ancestor of shadow root (; so, we return the result of retargeting containeragainstbutton, yielding popover` as the parent element.

13. 🆕 Back in event dispatch where the path would previously have just been [container, shadow root], it now goes [container, shadow root, popover, [... popover's light DOM ancestor chain]] (I think).

14. Event dispatch continues as normal with the given event path

15. 🆕 If composedPath() is called on event, it now also uses the new path including popover and its light DOM ancestors.

[alice]

button with popoverTarget inside of shadow root with reference target

From #1098 (comment)

<x-popover id="popover">
  <template shadowRootMode="open" shadowRootReferenceTarget="container">
    <style>
      #container {
        /* completely encapsulated styles for the popover */
      }
    </style>
    <button id="button" popovertarget="container">Toggle</button>
    <div id="container" popover>
     Popover content.
    </div>
  </template>
</x-popover>

(Steps 1-11 are the same as above.)

12. 🆕 When a shadow root's get the parent is invoked on the shadow root, we go to the new logic:

    1. let target be event’s path’s first struct’s invocation target;
    2. if event’s composed flag is set, return shadow root’s host;
    3. if shadow root is not the root of target, and event does not have a source or shadow root is not the root of event's source, return shadow root's host;
    4. if event has a source, and event's source's root is a shadow-including ancestor of shadow root, return the result of retargeting target against event's triggering element;
    5. otherwise, return null.

    1. target is container;
    2. composed is not set;
    3. shadow root is the root of target (false); event has a source, button; shadow root is the root of button (false); false && false so we go to step 4.
    4. button's root (shadow root) is not a shadow-including ancestor of shadow root (since it's non-inclusive ancestors only); so, we return null as the parent element.

13. 🆕 Back in event dispatch the path is still just [container, shadow root].

14. Event dispatch continues as normal with the given event path

15. 🆕 If composedPath() is called on event, it returns [container, shadow root].

[alice]

button inside shadow root with popoverTargetElement in an ancestor shadow root

<x-popover id="popover">
  <template shadowRootMode="open" shadowRootReferenceTarget="container">
    <style>
      #container {
        /* completely encapsulated styles for the popover */
      }
    </style>
    <x-button id="xButton" data-popovertarget="container">
      <template shadowRootMode="open" shadowRootReferenceTarget="button">
        <button id="button">Toggle</button>
      </template>
    </x-button>
    <div id="container" popover>
     Popover content.
    </div>
  </template>
</x-popover>

// somewhere in the custom element definition for <x-button>
button.popoverTargetElement = host.getRootNode().getElementById(dataset.popovertarget);

(Steps 1-11 are the same again.)

12. 🆕 When a shadow root's get the parent is invoked on the outer shadow root, we go to the new logic:

    1. let target be event’s path’s first struct’s invocation target;
    2. if event’s composed flag is set, return shadow root’s host;
    3. if shadow root is not the root of target, and event does not have a source or shadow root is not the root of event's source, return shadow root's host;
    4. if event has a source, and event's source's root is a shadow-including ancestor of shadow root, return the result of retargeting target against event's triggering element;
    5. otherwise, return null.

    1. target is container;
    2. composed is not set;
    3. the outer shadow root is the root of target (false); event has a source, button; the outer shadow root is not the root of button (true); false && true so we go to step 4;
    4. button's root (the inner shadow root) is not a shadow-including ancestor of shadow root; so, we return null as the parent element.

(The remaining steps are the same as above.)

[alice]

Submit button with form attribute pointing to <form> in shadow root via reference target

From #1098 (comment)

<x-form id="xForm">
  <template shadowRootMode="open" shadowRootReferenceTarget="form">
    <form id="form"></form>
  </template>
</x-form>
<label>Name: <input form="x-form"></label>
<input id="submitButton" type="submit" form="x-form">

1. User clicks submitButton.

2. The submit button activation behaviour falls through to Step 3:

   Submit the element's form owner from the element with userInvolvement set to event's user navigation involvement.

3. The submit a form algorithm gets form as form (via the form attribute and reference target) and submitButton as submitter.

4. 🆕 At step 5.6 of "submit a form", the SubmitEvent should have source (submitter) initialized to submitButton when firing the submit event at form.

   (Following steps are much the same as above, but writing them out anyway.)

5. 🆕 In fire an event, the invoker is part of the initialization of event in step 4.9.

6. 🆕 In event dispatch, we now get a source as part of event.

7. In step 6.8 and step 6.9.9 of event dispatch, the algorithm calls into get the parent with event.

8. When a node's get the parent is invoked on form, it returns the shadow root as normal.

9. 🆕 When a shadow root's get the parent is invoked on the shadow root, we go to the new logic:

   1. let target be event’s path’s first struct’s invocation target;
   2. if event’s composed flag is set, return shadow root’s host;
   3. if shadow root is not the root of target, and event does not have a source or shadow root is not the root of event's source, return shadow root's host;
   4. if event has a source, and event's source's root is a shadow-including ancestor of shadow root, return the result of retargeting target against event's triggering element;
   5. otherwise, return null.

   1. target is form;
   2. composed flag is not set;
   3. shadow root is the root of target (false); event has an source, submitButton; shadow root is not the root of submitButton (true); false && true so we go to step 4;
   4. submitButton's root (Document) is a shadow-including ancestor of shadow root; so, we return the result of retargeting form against submitButton, yielding xForm as the parent element.

10. 🆕 Back in event dispatch where the path would previously have just been [form, shadow root], it now goes [form, shadow root, xForm, [... xForm's light DOM ancestor chain]] (I think).

11. Event dispatch continues as normal with the given event path

12. 🆕 If composedPath() is called on event, it now also uses the new path including xForm and its light DOM ancestors.