[w3ctag/design-reviews] ObservableArray, and its use by adoptedStyleSheets (Issue #693)

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](https://www.w3.org/TR/cssom-1/#extensions-to-the-document-or-shadow-root-interface), [shipped](https://chromestatus.com/feature/5394843094220800) 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](https://github.com/whatwg/webidl/issues/796)), 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](https://webidl.spec.whatwg.org/#idl-observable-array) and [adoptedStyleSheets](https://www.w3.org/TR/cssom-1/#extensions-to-the-document-or-shadow-root-interface)
  - Tests: [This folder](https://wpt.fyi/results/css/cssom?label=master&label=experimental&aligned&q=CSSStyleSheet) already contains tests for the existing `adoptedStyleSheets` and constructable stylesheets APIs. New tests of the use of `ObservableArray` will be added once [this PR](https://github.com/web-platform-tests/wpt/pull/31737) 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](https://github.com/whatwg/webidl/issues/796) and the [issue discussing using it for `adoptedStyleSheets`](https://github.com/WICG/construct-stylesheets/issues/45).
  - External status/issue trackers for this specification (publicly visible, e.g. Chrome Status): https://chromestatus.com/feature/5638996492288000


Further details:

  - [X] I have reviewed the TAG's [Web Platform Design Principles](https://www.w3.org/TR/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](https://github.com/WICG/construct-stylesheets/issues/45#issuecomment-826036758) 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](https://github.com/WICG/construct-stylesheets/issues/45#issuecomment-825055766) 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


-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/693