diff --git a/index.bs b/index.bs index a35e7dd..8f59b83 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}} when it is associated with a new [=top-level browsing context=] + due to activation of its [=portal browsing context=].
- - 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=].