Intent to Implement and Ship: Make Document constructible

[Davaajav]

Contact emails

dava...@google.com

Spec

https://dom.spec.whatwg.org/#dom-document-document

Summary

Make Document constructible with new Document(). Chrome currently supports document creation via DOMImplementation interface, but not via direct invoking of its constructor. See Issue 238234.

Is this feature supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

Yes

Compatibility Risk

Small - Firefox and Safari already implement this constructor.

The specs have merged the Document and HTMLDocument interfaces and left window.HTMLDocument as an alias of Document. Blink hasn't implemented this yet, so new Document() returns a HTMLDocument instance. See Issue 238368.

Limitations

None

OWP launch tracking bug?

This is one constructor, so we think this is a bug and doesn't need OWP launch tracking. We're sending this intent as a "heads up"/PSA.

Link to entry on the feature dashboard

None. This is part of the DOM Document interface that Blink has supported since forever.

[TAMURA, Kent]

On Fri, Sep 16, 2016 at 10:24 AM, 'Davaajav' via blink-dev <blin...@chromium.org> wrote:

Contact emails

dava...@google.com

Spec

https://dom.spec.whatwg.org/#dom-document-document

Summary

Make Document constructible with new Document(). Chrome currently supports document creation via DOMImplementation interface, but not via direct invoking of its constructor. See Issue 238234.

Is this feature supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

Yes

Compatibility Risk

Small - Firefox and Safari already implement this constructor.

The specs have merged the Document and HTMLDocument interfaces and left window.HTMLDocument as an alias of Document. Blink hasn't implemented this yet, so new Document() returns a HTMLDocument instance. See Issue 238368.

Did Firefox and WebKit merge Document and HTMLDocument? If not, do they return an HTMLDocument by |new Document()|?

 

Limitations

None

OWP launch tracking bug?

This is one constructor, so we think this is a bug and doesn't need OWP launch tracking. We're sending this intent as a "heads up"/PSA.

Link to entry on the feature dashboard

None. This is part of the DOM Document interface that Blink has supported since forever.

--

TAMURA Kent
Software Engineer, Google

[Boris Zbarsky]

On 9/15/16 9:52 PM, TAMURA, Kent wrote:
> Did Firefox and WebKit merge Document and HTMLDocument?

Firefox has not.

> If not, do they return an HTMLDocument by |new Document()|?

No, we return a Document.

-Boris

[Elliott Sprehn]

This appears to also be true of Safari:

new Document() instanceof HTMLDocument is false, open() etc. are all missing on the instance.

I'd prefer if we didn't implement new Document() returning an HTMLDocument and diverge from Safari and Firefox. :)

 

-Boris

[Dominic Cooney]

Bit of background on this proposed change: we have encountered some tests which coincidentally rely on new Document(), which is why we want to implement it now.

This is my fault--I misread the spec. There's a note that "Unlike createDocument(), this constructor does not return an XMLDocument object, but a document (Document object)"; I took this to mean returning a HTMLDocument would be safe, since HTMLDocument is just an alias for Document in the spec world, but in fact the Document has content type application/xml, etc.

We don't plan to diverge from Safari and Firefox. We should just return Document here.

 

-Boris

[Philip Jägenstedt]

Some context in addition to issue 238368:

https://github.com/whatwg/dom/issues/221

https://github.com/whatwg/dom/issues/278

https://github.com/whatwg/dom/issues/308

We need to bring this document interface saga to a conclusion, and  as I commented on #221, figuring out what to do with the Document constructor is the key.

My main concern is that the constructor will be the only way to create an instance of Document that isn't either an HTMLDocument or an XMLDocument, and that this will be a funny corner case in need of extra testing everywhere. Unfortunately, making HTMLDocument or XMLDocument an alias of Document does not look promising.

FWIW, the idea of having new Document() return either an HTMLDocument or an XMLDocument looks weird, but it is possible to implement. For a while, new TextTrackCue() returned a VTTCue instance.

I think that the fastest path to interop here would actually be to bring HTMLDocument and XMLDocument back into existence in the specs, and to remove the Document constructor, but someone on the Blink side needs to own this whole set of problems and come to an agreement with the other vendors. Anyone?

[Boris Zbarsky]

On 9/16/16 5:26 AM, Philip Jägenstedt wrote:
> I think that the fastest path to interop here would actually be to bring
> HTMLDocument and XMLDocument back into existence in the specs, and to
> remove the Document constructor

I don't expect it to be possible to remove the Document constructor
without breakage in Gecko. We've been shipping it for quite a long
while and people are using it.

-Boris

[Philip Jägenstedt]

Chris Dumez said the same thing for WebKit so I guess I should stop entertaining that possibility.

Boris, Chris,what do you see as the end state for document interfaces in Gecko and WebKit? Do you it's OK that new Document is the only way to create a Document instance that's neither a HTMLDocument or XMLDocument, and is that even true for Gecko and WebKit? If the new Document({ type: 'text/html' }) idea too crazy to entertain?

[Boris Zbarsky]

On 9/16/16 9:58 AM, Philip Jägenstedt wrote:
> Boris, Chris,what do you see as the end state for document interfaces in
> Gecko and WebKit?

I don't know, honestly. The document interfaces are one of the more
screwed-up parts of the web platform, full of methods and properties
that only make sense in some situations but are shoehorned into always
being there...

In practice, I'm on board with moving things from HTMLDocument to
Document when it makes sense to do so. It's not clear to me whether it
makes sense for very HTML-specific things like
body/head/images/embeds/plugins/links/forms/scripts. It's also not
clear that it makes sense for open/close/write/writeln (which can never
work on non-HTML documents anyway, and don't even work on all
HTMLDocument instances). Not sure about the *Color attributes either.

As a separate concern, even if we moved everything I'm not sure what the
right thing to do with HTMLDocument is (i.e. whether it can just become
an alias for Document or not). It's hard to say whether that's even
web-compatible until someone actually tries shipping it...

> Do you it's OK that new Document is the only way to
> create a Document instance that's neither a HTMLDocument or XMLDocument

I don't think it's really a problem, no. In practical terms, it's just
like XMLDocument but without a load() (in Gecko; in other engines it's
really the same).

> and is that even true for Gecko and WebKit?

It's true in Gecko.

> If the new Document({ type: 'text/html' }) idea too crazy to entertain?

This could be done, I guess, but we could also just make HTMLDocument
constructible (and have it not be an alias of Document). If we did it
that way, it would still need a type, defaulting to "text/html", so you
could create application/xhtml+xml HTMLDocument instances...

If we do alias HTMLDocument to Document, then having a type arg to the
Document constructor makes sense to me; that would be the sane way of
producing an HTML document (flagged so internally, that is) in that world.

Hope that helps,
Boris

[Boris Zbarsky]

On 9/16/16 10:21 AM, Boris Zbarsky wrote:
>> Do you it's OK that new Document is the only way to
>> create a Document instance that's neither a HTMLDocument or XMLDocument
>
> I don't think it's really a problem, no. In practical terms, it's just
> like XMLDocument but without a load() (in Gecko; in other engines it's
> really the same).

And to be clear, it's the same exact object in Gecko, with just a
boolean flag that controls whether it gets XMLDocument.prototype or
Document.prototype as its prototype.

Also, I was only half right. You can in fact produce a Document that's
neither HTMLDocument or XMLDocument in Gecko by doing cloneNode() on an
existing such Document. The only way to get one initially, though, is
via the constructor.

-Boris

[Domenic Denicola]

For what it's worth, I think that although this is a somewhat complex issue in spec land, the immediate path forward is actually pretty clear, and this intent shouldn't be blocked on deciding what to do.

That is, given that Gecko and WebKit are going to continue to follow the spec and return Document (an XML document) from the Document constructor, we should do the same.

Everything after that, in terms of longer-term planning, is up for debate. I have outlined my thoughts on what should happen there at https://github.com/whatwg/dom/issues/308#issuecomment-247627229, but I think it's off-topic for this blink-dev thread and should not impact the implement/ship decision.

[Philip Jägenstedt]

I think the broader issue does matter somewhat. For example, if we make XMLDocument an alias of Document again, then `new XMLDocument` will work, and I really think we should try to jump to the intended end state in one step to reduce the risk of getting stuck in half-way there.

Some good discussion is happening on #308 now, but this intent should not block indefinitely if we reach a stalemate, of course.

[Chris Dumez]

I also responded on https://github.com/whatwg/dom/issues/308.

--

 Chris Dumez

[Joe Medley]

Davaajav,

Do you at least have a ticket for tracking the work. I need to know when to add or update this on MDN.

Joe

Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com | 816-678-7195

If an API's not documented it doesn't exist.

On Thu, Sep 15, 2016 at 6:24 PM, 'Davaajav' via blink-dev <blin...@chromium.org> wrote:

Contact emails

dava...@google.com

Spec

https://dom.spec.whatwg.org/#dom-document-document

Summary

Make Document constructible with new Document(). Chrome currently supports document creation via DOMImplementation interface, but not via direct invoking of its constructor. See Issue 238234.

Is this feature supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

Yes

Compatibility Risk

Small - Firefox and Safari already implement this constructor.

The specs have merged the Document and HTMLDocument interfaces and left window.HTMLDocument as an alias of Document. Blink hasn't implemented this yet, so new Document() returns a HTMLDocument instance. See Issue 238368.

Limitations

None

OWP launch tracking bug?

This is one constructor, so we think this is a bug and doesn't need OWP launch tracking. We're sending this intent as a "heads up"/PSA.

Link to entry on the feature dashboard

None. This is part of the DOM Document interface that Blink has supported since forever.

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

[Davaajav Jargalsaikhan]

Joe, 

Sorry for the late response. This is the bug report link https://bugs.chromium.org/p/chromium/issues/detail?id=238234

Davaajav

[Joe Medley]

Thanks.

Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com | 816-678-7195

If an API's not documented it doesn't exist.

[Rick Byers]

It looks like there's a bunch of open spec issues here where we lack consensus on how best to move forward, and (if I'm understanding correctly) at least one of the outstanding choices could mean we'd regret adding a mechanism in blink for obtaining instances of 'Document':

https://github.com/whatwg/dom/issues/221

https://github.com/whatwg/dom/issues/278

https://github.com/whatwg/dom/issues/308

To what extent is there benefit to the web for pushing forward with this intent in spite of these open spec issues?  If developers aren't asking for the ability to do 'new Document()' then should we perhaps hold off until a consensus has been reached in the DOM spec community on the above issues?

[Domenic Denicola]

From: Rick Byers [mailto:rby...@chromium.org]

> It looks like there's a bunch of open spec issues here where we lack consensus on how best to move forward, and (if I'm understanding correctly) at least one of the outstanding choices could mean we'd regret adding a mechanism in blink for obtaining instances of 'Document':

My opinion is that none of the options will lead to us diverging from other browsers and disallowing instances of `Document`. That just seems unrealistic. I think it is safe to ship the same functionality all other browsers do; in the linked threads both Firefox and Safari expressed they would not want the spec to change in a way that was incompatible with their implementation.

I think these open spec issues are important, and we should work to resolve them, but as I said earlier in the thread, I don't think they would or should impact this intent to ship.

[Dominic Cooney]

Just briefly, I think a few people stated we don't create generic Document (versus HTMLDocument, XMLDocument) but that is not true. For example:

http://jsbin.com/yididicoqa/edit?html,output

So if there's a problem with doing that, then we have a problem.

[Philip Jägenstedt]

I indeed speculated that we never expose Document instances, because I failed to find any cases. http://jsbin.com/yididicoqa/edit?html,output is interesting, but is it not simply an oversight that Document::ensureTemplateDocument() fails to create the same kind of document?

I have just spent some time trying to summarize the state as it now is:

https://gist.github.com/foolip/103963a1ae8598d2baedd296f4a1bf4c

I've commented on the open spec issues, suggesting that discussion is taken to https://github.com/whatwg/dom/issues/221

With just a little bit of coordination, I think we could sort out this whole mess in relatively short time frame. Dominic, does that seem reasonable, and can your team drive that from Blink's side?

[Philip Jägenstedt]

Davaajav, Dominic, what is your take on all of this? It is the DOM team that will own the outcome of this, so your judgement matters a lot more than my preferences.

[Dominic Cooney]

Thank you for summarizing all that, Philip.

Can I clarify your concern about adding this constructor? I think you're concerned that if we ship Document constructor, and in future decide to make XMLDocument an alias of Document again, then code will be written which depends on 'new XMLDocument' and if we make XMLDocument a separate interface again in future then we will have to implement a constructor on it, because of that newly written code? And similarly if we were to merge, then unmerge, HTMLDocument and Document.

Is that right/all?

FWIW it looks like WebKit split Document and XMLDocument after having 'new XMLDocument' work for ~2 years, without adding an XMLDocument constructor in WK153378.

I've been trying to think through where we end up:

I agree with Domenic here that the HTMLDocument and XMLDocument alternate reality is unlikely. It might be worth noting the objections?

I think in the Document and HTMLDocument alternate reality, Chromium and Edge need to implement Document constructor, or WebKit and Gecko need to remove them, to be interoperable. From the comments in issues 221 and 308 I think Chromium and Edge would need to implement Document constructor but it might be good to be specific.

This leads me to think that Chromium should implement the Document constructor anyway, and it would return Document.

If Edge indicated they could never ever implement the Document constructor, or WebKit or Gecko had a change of heart and indicated they could remove it, then I think we should not pursue adding it.

Dominic

[Philip Jägenstedt]

My primary concern is that when (almost) all UA-created documents are HTMLDocument or XMLDocument, and scripts can already create those, introducing a Document constructor is no improvement for web developers. Is there any situation where their time would be well spent by trying to use the constructor instead of document.implementation.create(HTML)Document?

The secondary concern is that when both Document and XMLDocument are concrete, then in every context a choice must be made about which to create. Making existing XMLDocument instances Document would break stuff, so I'd argue for always using XMLDocument and having a Document::createForBindings() or similar so that things are never accidentally Document instead of XMLDocument. That would leave the primary concern, that there's no reason to use the constructor.

Other than interop, are there compelling reasons to add the constructor? In the end, if adding it is the only path to interop that's fine, but I think to ship it now increases the chances that we get stuck in that state even if Gecko's use counters show that making XMLDocument an alias of Document would be safe.

[Philip Jägenstedt]

Dominic, Domenic and I just had an extended chat about this.

Blink and Edge are currently at "HTMLDocument and XMLDocument", the least plausible end state listed in the gist. All other outcomes have a constructor. "Document, HTMLDocument and XMLDocument" is the least satisfying, but not terrible. This is where Gecko and WebKit are, and where Blink would move.

The chances for "Document and HTMLDocument" depend on use counter data from Gecko, which Boris says might be available "late March or so". When we have that information, we should decide what to do with XMLDocument, based on Gecko's willingness to change.

There is some use of the constructor in web-platform-tests, and changing those and any new ones that creep in isn't a good use of time if we expect to have the constructor next year anyway. And those failures could obscure other failures worth fixing.

I've been arguing, essentially, that having 3 engines in the same state will increase the chances that we stay there out of inertia. That may be, but it's speculative. Right now there is still appetite to simplify, and March isn't that far away in web time.

So, LGTM1!

Until the eventual outcome is more clear, it's probably best to expose only HTMLDocument or XMLDocument outside of the constructor.

[Chris Harrelson]

LGTM2

[Rick Byers]

Thanks for driving the extended discussion Philip and all getting on the same page.  LGTM3

[Joe Medley]

Davaajav,

3 LGTMs. Can you please create a status entry for this now?

https://www.chromestatus.com/features

Thanks,

Joe

Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com | 816-678-7195

If an API's not documented it doesn't exist.

[Kent Tamura]

Created a chromestatus entry:

https://www.chromestatus.com/feature/6078850731606016