Add resize feature to Component

[marchant]

When a component's element is resized as part of a layout / size changes around it, like when a window is resized, a mobile screen is rotated, or through being in an in-app Split View control, it may need to execute JavaScript code to relayout itself internally.

This is can be true for a slider that needs to reposition its thumbs/knobs, or a segmented control to position the highlight of the current selected segment.

We're going to do this by having the event manager host a single ResizeObserver for all components'element in a mod. This will be the single integration with the ResizeObserver API, and we'll dispatch from there as tested and validated performance-wise here (https://groups.google.com/a/chromium.org/g/blink-dev/c/z6ienONUb5A , the last entry from Aleks Totic)

The most natural way to dispatch is to embrace events, and we're going to use the "change" event: ChangeEvent in core/event/change-event.js

That has started to be used in the data layer, starting in DataTrigger, however it's not using the EventManager there for dispatch, but we need to. ChangeEvent is not actually a subclass of Event or MutableEvent which is what we typically use, because it needs to work in the worker on top of node.js where DOM events don't exists. But as long as it behaves like an Event, it shouldn't matter to the EventManager.

There are 2 possible ways to go at this: hack the ResizeObserverEntry we're receiving via the ResizeObserver()'s callback to make it looks like and behave like a ChangeEvent, or create an actual ChangeEvent and move properties/values from the ResizeObserverEntry to it.

Those ResizeObserverEntry's properties are:

• target, which is the same property name and value on an event.
• borderBoxSize - https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/borderBoxSize
• contentBoxSize - https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/contentBoxSize
• devicePixelContentBoxSize - https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/devicePixelContentBoxSize
• contentRect - https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/contentRect

We need to find a home for those on the change event where the key property will be set to "size", We could just set the whole ResizeObserverEntry to the "keyValue" property of the change event:

var changeEvent = new ChangeEvent;
  changeEvent.target = aResizeObserverEntry.target;
  changeEvent.key = "size";
  changeEvent.keyValue = aResizeObserverEntry;
  this.handleEvent(changeEvent); // this here his the event manager, calling his own handleEvent() method from within the ResizeObserver's callback 

When a component want size changes events, it should use the options argument of addEventListener ( https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener ) to provide the fact that it needs to listen to changes on the "size" property, and also provide what the ResizeObserver: observe() method offers in term of options. An options object allowing you to set options for the observation, see more at https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/observe#options

Currently this only has one possible option that can be set, "box", with possible values being: content-box, border-box, device-pixel-content-box, so with a component it would look like this:

this.element.addEventListener(“change”, this, { 
    "size": {
        box: "device-pixel-content-box"
    }
});

per implementation in target.js, mod's addEventListener() ends up calling:
defaultEventManager.registerTargetEventListener(this, type, listener, optionsOrUseCapture);

So in EventManager's registerTargetEventListener(target, eventType, listener, optionsOrUseCapture) method, we need to add a new handling for a type "change" on a target that is an instance of Element or SVGElement, where we'll create on-demand EventManager's this._resizeObserver = new ResizeObserver(dispatchCallback) if it wasn't before, and use this._resizeObserver.observe(target, {box: optionsOrUseCapture.size.box}) to kickstart the observing.

dispatchCallback is the function where we get the changes and we'll have to turn it into an event and distribute them.

@tejaede @maxwell-jordan please take a look and comment as you see fit

[tejaede]

@marchant I think Event or MutableEvent with type "resize" is better than ChangeEvent with key "size" for a few reasons.

• "resize" event is already established and widely understood. The API can be what people are already used to: window.addEventListener("resize", this) and component.addEventListener("resize", this)
• A component resize is explicitly DOM-related so there's no concern about it running in a worker.
• A component does not have a "size" property. A ChangeEvent on a DataObject says "one of the properties changed". For that to apply to a component, it would be more like adding a ChangeEvent for height or width.

---

A few other thoughts.

1. We need to add to the spec that removing the listener will trigger unobserve. I imagine this is what you had in mind, but let's make it explicit.
2. Related to point 1, what happens when the observed element leaves the DOM? Is it computationally free to keep it in the observer? If it's not, do we need to remove it and re-add it if/when it's added back to the DOM? Or is that moot and we rely on the listener to add/remove itself in enterDocument/exitDocument.
3. Does the component add the event listener to itself? e.g.

class Slider extends Control {
  
   enterDocument (firstTime) {
        this.addEventListener("change", this, {
               size: {
                     box: "border-box"
              }
        });
        //OR
       this.addEventListener("resize", this);
   }
    
}

[marchant]

The listening is on the DOM element, it's not on the component. The component here is the listener, the target being listened to is the component's element:

class Slider extends Control {
  
   enterDocument (firstTime) {
        this.element.addEventListener("change", this, {
               size: {
                     box: "border-box"
              }
        });
        //OR
       this.element.addEventListener("resize", this);
   }
    
}

My concern with using a resize event, is that the data to be used off the event that is being dispatched is entirely different than those from the OG window level resize event, so that's weird as well.

What's missing here would be to create an DOM elements new "size" property that would have the same structure/properties as what's shared by the resize observer:

borderBoxSize, contentBoxSize, devicePixelContentBoxSize and contentRect.

So one would be able to do something like this.element.size.borderBoxSize and those individual properties of the size object would use DOM api to return the same result as in the resizeObserver entry:
{
blockSize: 335
inlineSize: 651
}

The 3 size properties have this same shape

[tejaede]

@marchant

The listening is on the DOM element, it's not on the component.

Got it. That makes sense.

My concern with using a resize event, is that the data to be used off the event that is being dispatched is entirely different than those from the OG window level resize event, so that's weird as well.

What's missing here would be to create an DOM elements new "size" property that would have the same structure/properties as what's shared by the resize observer:

Adding a size property to the element effectively addresses my concern. I considered that as a possible path forward as well.

For the sake of academic argument, the fact the original "resize" doesn't include the same payload isn't a deal breaker, IMO. It would be perfectly reasonable for the original resize event to include the new size. It doesn't, but that doesn't mean an iteration on the resize event can't or shouldn't. But as I said, the addition of "size" to element is enough for me to be on board.

[tejaede]

Then making a separate comment on "unobserve" to make sure it gets addressed in the spec. @marchant Can you comment on the "maybe" in particular?

Definitely: Call unobserve when someone calls element.removeEventListener("change", this, {size: {box: "border-box"}});

Maybe?: Automatically when the element leaves the DOM (or do we leave this to the implementer? I think it depends, as I said before, on how expensive it is to have an element outside the DOM being observed).

[marchant]

Sorry forgot that part: 100% on the definitely: Call unobserve when someone calls element.removeEventListener("change", this, {size: {box: "border-box"}});

Unfortunately on the maybe, it's already true of any other event we listen to on DOM elements. I can only assume that the internal browser code has some handling of that as it's not a rare scenario, but I haven't research that.

[marchant]

One reason I prefer the change event on a property "size" is that it's nor an invention of an "event name" "for the sake of it". That feels intellectually sloppy now that I have realized this. By definition a "resize" is a size change... Why invent a new name every time instead of following that pattern. rename? relastName?!

Actually, to be consistent with data operations naming underneath maybe "update" would be a better name than "change"?