From 66c16ecb726cb3d58d703667e08647d3a7990d97 Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Mon, 4 May 2020 17:39:24 -0400 Subject: [PATCH] Rearrange spec structure as more explicit patches This brings the spec closer to how it would look upon landing in HTML, and explicitly calls out what sections it would expect things to land in. Notable changes: * Moved window.portalHost from "Miscellaneous extensions" into a new "Portal hosts" section, which contains the definitions for both window.portalHost and the PortalHost interface. * Made the onportalactivate event handler addition match HTML's existing structure. * Moved subsections of "Security considerations" which were spec patches into a new dedicated section, "Updates to other specifications". * Noted the connection to whatwg/html#1230 in addition to RFC 7034. * Tweaks the wording in the "Fetch Metadata Request Headers" section's non-normative summary notes. --- index.bs | 200 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 128 insertions(+), 72 deletions(-) diff --git a/index.bs b/index.bs index a35e7dd..f300b5f 100644 --- a/index.bs +++ b/index.bs @@ -78,11 +78,17 @@ spec:url; type:dfn; text:scheme This specification extends [[HTML]] to define a new kind of [=top-level browsing context=], which can be embedded in another document, and a mechanism for replacing the contents of another top-level browsing context with the previously embedded context. + + It is structured as a series of patches to HTML and other specifications, with each major section + indicating where each it would be placed in the event of eventual graduation from incubation.
- Concepts {#concepts} - ==================== + Portal browsing contexts {#concepts} + ==================================== + + The following section would be added as a new sub-section of [[HTML]]'s + Browsing contexts section. Every [=browsing context=] has a portal state, which may be "`none`" (the default), "`portal`" or "`orphaned`". A [=nested browsing context=] always has the [=portal state=] "`none`". @@ -276,11 +282,11 @@ spec:url; type:dfn; text:scheme
- API {#api} - ========== - The `portal` element {#the-portal-element} - ------------------------------------------ + ========================================== + + The following section would be added as a new subsection of [[HTML]]'s + Embedded content section. A portal element allows for a [=portal browsing context=] to be embedded in an HTML document. @@ -620,17 +626,45 @@ spec:url; type:dfn; text:scheme htmlportalelement-event-handler-content-attributes.html - The `PortalHost` interface {#the-portalhost-interface} + Portal hosts {#the-portalhost-interface} ------------------------------------------------------ - The portal host object of a {{Window}} is a {{PortalHost}}. + Every {{Window}} has a portal host object, which is a {{PortalHost}}. It is exposed + through the {{Window/portalHost}} attribute getter at times when the window may be in a + [=portal browsing context=].
- The [=portal host object=] can be used to communicate with the [=host browsing context=]. - Its operations throw if used while its context is not a [=portal browsing context=] (i.e. there is no host). - It is not accessible via {{Window/portalHost|window.portalHost}} at such times. + The [=portal host object=] can be used to communicate with the [=host browsing context=]. Its + operations throw if used while its context is not a [=portal browsing context=] (i.e. there is + no host), in the event that JavaScript code has saved a reference to it. At such times, the + {{Window/portalHost|window.portalHost}} getter will return null.
+ + partial interface Window { + readonly attribute PortalHost? portalHost; + }; + + +
+ The portalHost attribute's getter *must* run the following steps: + + 1. Let |context| be [=this=]'s [=Window/browsing context=]. + + 1. If |context| is null or the [=portal state=] of |context| is not "`portal`", then return null. + + 1. Return [=this=]'s [=portal host object=]. +
+ + + portals-host-exposure.sub.html + portals-host-null.html + + +
+ + The {{PortalHost}} interface definition is as follows: + [Exposed=Window] interface PortalHost : EventTarget { @@ -808,8 +842,15 @@ spec:url; type:dfn; text:scheme portals-adopt-predecessor.html </wpt> </section> +</section> - Miscellaneous extensions {#miscellaneous-extensions} +<section> + Miscellaneous HTML updates {#miscellaneous-extensions} + ==================================================== + + <em>This section contains various small patches to miscellaneous areas of the HTML Standard.</em> + + The {{MessageEvent}} interface {#patch-messageevent} ---------------------------------------------------- The {{MessageEventSource}} union is extended to include the new interfaces @@ -819,76 +860,66 @@ spec:url; type:dfn; text:scheme typedef (WindowProxy or MessagePort or ServiceWorker or HTMLPortalElement or PortalHost) MessageEventSource; - A {{PortalHost}} is exposed at times when the window may be in a [=portal browsing context=]. + Event handlers {#patch-event-handlers} + -------------------------------------- - - partial interface Window { - readonly attribute PortalHost? portalHost; - }; + The table of [=event handlers=] which must be supported by {{Window}} objects, as [=event handler + IDL attributes=] on the {{Window}} objects themselves (i.e. the table containing `onafterprint`), + gets extended with the following row: + + <table class="data" dfn-for="Window"> + <thead> + <tr> + <th>[=Event handler=]</th> + <th>[=Event handler event type=]</th> + </tr> + </thead> + <tbody> + <tr> + <td><dfn attribute for="Window"><code>onportalactivate</code></dfn></td> + <td>{{portalactivate}}</td> + </tr> + </tbody> + </table> + The corresponding {{WindowEventHandlers}} mixin gets extended as follows: + + <xmp class="idl"> partial interface mixin WindowEventHandlers { attribute EventHandler onportalactivate; }; -
- The portalHost attribute's getter *must* run the following steps: - - 1. Let |context| be [=this=]'s [=Window/browsing context=]. - - 1. If |context| is null or the [=portal state=] of |context| is not "`portal`", then return null. - - 1. Return [=this=]'s [=portal host object=]. -
- - - portals-host-exposure.sub.html - portals-host-null.html - - - The following events are dispatched on {{Window}} objects: + The Events index is also updated with the + following additional row: - + - + + - + +
Event nameEvent InterfaceDispatched whenInteresting targetsDescription
portalactivate {{PortalActivateEvent}}The window is associated with a new [=top-level browsing context=] due to activation of its [=portal browsing context=].{{Window}}Fired at the {{Window}} of a [=portal browsing context=] when that [=portal browsing + context=] is activated.
- - Like other [=event handler IDL attributes=] in the {{WindowEventHandlers}} interface mixin, - {{WindowEventHandlers/onportalactivate}} is exposed on all <{body}> and <{frameset}> elements - as a [=event handler content attribute=].
- Security Considerations {#security-considerations} - ================================================== - -
- We should expand this section further. -
- - Overview {#security-overview} - ----------------------------- - - *This section is non-normative.* - - In general, a [=portal browsing context=] should respect policies that would apply to - a [=nested browsing context=], e.g. that would restrict whether a document can be embedded - in a document from another [=origin=]. + Updates to other specifications {#other-spec-updates} + ===================================================== - Integration with Content Security Policy {#csp} - ----------------------------------------------- + Content Security Policy {#csp} + ------------------------------ This specification integrates with [[CSP]] as follows. @@ -913,10 +944,14 @@ spec:url; type:dfn; text:scheme {{HTMLPortalElement/activate(options)}} should also respect the CSP [=navigate-to=] directive. - Integration with RFC 7034 {#rfc7034} - ------------------------------------ + RFC 7034 {#rfc7034} + ------------------- - This specification integrates with [[RFC7034]], which defines the `X-Frame-Options` HTTP header, as follows. + This specification integrates with [[RFC7034]], which defines the `X-Frame-Options` HTTP header, + as follows. Note that [[HTML]] also has an open issue, + whatwg/html#1230, to define + `X-Frame-Options` processing, and perhaps these updates would be done as part of resolving that + issue. If a browser receives content with this header field in response to a navigation request whose [=target browsing context=] is a [=portal browsing context=], then the browser must apply the rules @@ -930,11 +965,20 @@ spec:url; type:dfn; text:scheme 1. Return |topLevelBrowsingContext|. - Integration with Fetch Metadata Request Headers {#fetch-metadata} - ----------------------------------------------------------------- + Fetch Metadata Request Headers {#fetch-metadata} + ------------------------------------------------ This specification integrates with [[FETCH-METADATA]] as follows. +
+ The algorithm to [[FETCH-METADATA#abstract-opdef-set-mode|set the Sec-Fetch-Mode header]] for a request |r| + is modified as follows: + + 1. Where the algorithm checks whether |r|'s [=reserved client=]'s [=target browsing context=] is + a [=nested browsing context=], check instead whether it is a [=nested browsing context=] or + a [=portal browsing context=]. +
+
The effect of this is that the request for a document in a [=portal browsing context=] will contain the following HTTP header, as though it were in a [=nested browsing context=]. @@ -942,19 +986,31 @@ spec:url; type:dfn; text:scheme ``` Sec-Fetch-Mode: nested-navigate ``` +
- Even though no spec patches are required to do so, implementations must also send - the appropriate fetch metadata headers as it would if the load were occurring in - an <{iframe}> element. +
+ Per the existing processing model, the other fetch metadata headers will automatically have the + same values as they would would if the load were occurring in an <{iframe}> element, with no + spec updates needed.
+
-
- The algorithm to [[FETCH-METADATA#abstract-opdef-set-mode|set the Sec-Fetch-Mode header]] for a request |r| - is modified as follows: +
+ Security Considerations {#security-considerations} + ================================================== - 1. Where the algorithm checks whether |r|'s [=reserved client=]'s [=target browsing context=] is - a [=nested browsing context=], check instead whether it is a [=nested browsing context=] or - a [=portal browsing context=]. -
+
+ We should expand this section further. Much of what was formerly there is in + [[#other-spec-updates]] now. Once we have a more comprehensive view of all the security-related + spec updates, we should summarize them in a non-normative fashion here. +
+ + Overview {#security-overview} + ----------------------------- + + *This section is non-normative.* + In general, a [=portal browsing context=] should respect policies that would apply to + a [=nested browsing context=], e.g. that would restrict whether a document can be embedded + in a document from another [=origin=].