ObservableArray, and its use by adoptedStyleSheets

[mfreed7]

Braw mornin' TAG!

I'm requesting a TAG review of ObservableArray, and its use by adoptedStyleSheets.

This is essentially one new idea, the ObservableArray IDL type, plus one use of that new type, for the adoptedStyleSheets API. While it would seem that these might constitute two separate TAG reviews, I think it makes sense to review them together, since one proves the use case for the other. Also, adoptedStyleSheets by itself is already a specified, shipped API, and we're just talking about converting it from FrozenArray to ObservableArray. LMK if you disagree.

Motivation/Summary

Various Web APIs require an array-ish class to represent a list of things. However, for various reasons (enumerated on the issue), fake arrays have always been used in these cases. Examples include NodeList and HTMLOptionsCollection. These are similar to arrays, but they cannot be used in the same ways that standard Javascript arrays are used, e.g. through .map(), .filter(), .concat(), and .push(). The FrozenArray type is used in some places, but it also has downsides, such as being immutable.

The ObservableArray WebIDL type is designed to solve the above problems. It provides a mutable array with spec hooks into the set and remove behaviors, so that mutations can be properly tracked or blocked.

The adoptedStyleSheets API previously used the FrozenArray type to represent the list of CSSStyleSheets. The spec was recently changed to represent it as an assignable ObservableArray, which should be backwards-compatible, but also expand the usability by allowing array mutations in place.

Links

• Explainer¹: The best ObservableArray explainer is provided by the introductory comment on this issue: A new approach to array-ish classes whatwg/webidl#796
• Specification URL: ObservableArray and adoptedStyleSheets
• Tests: This folder already contains tests for the existing adoptedStyleSheets and constructable stylesheets APIs. New tests of the use of ObservableArray will be added once this PR lands.
• User research: None
• Security and Privacy self-review²: None
• Primary contacts (and their relationship to the specification):
  • Mason Freed (@mfreed7), Google
  • Domenic Denicola (@domenic), Google
• Organization(s)/project(s) driving the specification: Google
• Key pieces of existing multi-stakeholder review or discussion of this specification: Mostly on the ObservableArray PR and the issue discussing using it for adoptedStyleSheets.
• External status/issue trackers for this specification (publicly visible, e.g. Chrome Status): https://chromestatus.com/feature/5638996492288000

Further details:

• I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: Chromium would like to ship this feature soon
• The group where the work on this specification is currently being done: WHATWG and WICG
• The group where standardization of this work is intended to be done: WHATWG
• Major unresolved issues with or opposition to this specification: There is opposition from WebKit specifically to making/keeping adoptedStyleSheets assignable. WebKit feels that an assignable attribute is a vector for race conditions. Most/all other participants, including other implementers and many large developers agree that race conditions can happen whenever/however await is used, and the proposed API is the least risky. This has been extensively discussed.
• This work is being funded by: Google

We'd prefer the TAG provide feedback as (please delete all but the desired option):

💬 leave review feedback as a comment in this issue and @-notify @mfreed7 @domenic

[domenic]

Thanks @mfreed7 for filing this!

I re-read whatwg/webidl#796 (ah, 2019, what an innocent time) and found that while the "Background" section holds up great, the "Solutions" section doesn't capture some of how our thinking evolved. So to provide some additional color there:

• We initially proposed the "Solving this in Web IDL" solution, at Introduce the observable array type (legacy platform object based) whatwg/webidl#836.
• However, after some evaluation of that solution in A new approach to array-ish classes whatwg/webidl#796 (comment) , we instead moved to a proxy-based solution in Introduce the observable array type (proxy-based) whatwg/webidl#840

I'll also point out that the example in https://webidl.spec.whatwg.org/#example-af5d265e is pretty explainer-ish and might be a helpful read.

[cynthia]

Discussed during our F2F. Apologies this took so long. This looks great!

One request here would be to consider exposing this to web developers as well (make it a constructable object, instead of a trait) - and possibly bring it to TC39. WDYT?

[mfreed7]

Discussed during our F2F. Apologies this took so long. This looks great!

Thanks!

One request here would be to consider exposing this to web developers as well (make it a constructable object, instead of a trait) - and possibly bring it to TC39. WDYT?

@domenic WDYT?

[domenic]

One request here would be to consider exposing this to web developers as well (make it a constructable object, instead of a trait) - and possibly bring it to TC39. WDYT?

@domenic WDYT?

I've been in favor of giving developers a nice way to create observable arrays since the beginning; see some of the discussion in whatwg/webidl#796.

The latest shape (after the course corrections mentioned in #693 (comment)) makes this a bit trickier. Part of the reason the current solution is so good is precisely because it is "just a (proxy for an) Array", i.e. it is not a constructible class. If it were a constructible class, with its own constructor, then it would have worse compatibility with Arrays!

So this means the creation of these things would need to look a bit different, perhaps Array.observable(...) or createObservableArray(), instead of new ObservableArray().

The other hard part of exposing this functionality to developers is that we'd then need to come up with a nice-to-use API that is good for all time, instead of just creating something that works for spec developers and can be tweaked any time. The spec-author facing hooks are:

• "set an indexed value"
• "delete an indexed value"
• a fully mutable "backing list"

but I'd be hesitant to say these are the best possible API, or can be expressed nicely in JS (as opposed to in spec language). As a simple example, in spec land we're representing an assignment, e.g. observableArray[5] = "foo", as a delete-then-set; maybe developers would prefer that to be represented as a single change operation.

So overall I think it would be a significant project to make these developer-creatable, which would benefit from research, maybe some cowpath-paving libraries, and so on. Probably the first step, before investing too much, is to find out if there's demand for this sort of thing.