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: https://github.com/whatwg/webidl/issues/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