Skip to content

Commit

Permalink
Add navigation hooks for WebDriver BiDi history traversal
Browse files Browse the repository at this point in the history 
WebDriver BiDi wants to invoke the 'traverse the history by a delta`
algorithm, and get a callback whenever the algoritihm has run to
completion, either by failing or by the navigation or state
restoration completing.

w3c/webdriver-bidi#109 is the WebDriver BiDi
side of this change.
  • Loading branch information
@jgraham
jgraham committed Jul 30, 2021
1 parent 1b5099f commit 5f17205
Showing 1 changed file with 118 additions and 42 deletions.
160 changes: 118 additions & 42 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4132,6 +4132,8 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-fragment-navigated">WebDriver BiDi fragment navigated</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-dom-content-loaded">WebDriver BiDi DOM content loaded</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-load-complete">WebDriver BiDi load complete</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-page-show">WebDriver BiDi page show</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-pop-state">WebDriver BiDi pop state</dfn></li>
</ul>
</dd>

Expand Down Expand Up @@ -84700,16 +84702,23 @@ interface <dfn interface>History</dfn> {

<hr>

<p>To <dfn>traverse the history by a delta</dfn> given <var>delta</var> and <span>browsing
context</span> <var>source browsing context</var>, the user agent must append a <span
data-x="concept-task">task</span> to this <span>top-level browsing context</span>'s <span>session
history traversal queue</span>, the <span data-x="concept-task">task</span> consisting of running
the following steps:</p>
<p>To <dfn>traverse the history by a delta</dfn> given <var>delta</var>, <span>browsing
context</span> <var>source browsing context</var>, and an optional <span
data-x="navigation-id">navigation id</span> <var>navigationId</var> (default null),
the user agent must append a <span data-x="concept-task">task</span> to this <span>top-level
browsing context</span>'s <span>session history traversal queue</span>, the <span
data-x="concept-task">task</span> consisting of running the following steps:</p>

<ol>
<li><p>If the index of the <span>current entry of the joint session history</span> plus
<var>delta</var> is less than zero or greater than or equal to the number of items in the
<span>joint session history</span>, then return.</p>
<span>joint session history</span>, invoke <span>WebDriver BiDi navigation failed</span>
with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
data-x="concept-request-url">url</span>, then return.</p></li>

<li><p>Let <var>specified entry</var> be the entry in the <span>joint session
history</span> whose index is the sum of <var>delta</var> and the index of the
Expand All @@ -84719,17 +84728,32 @@ interface <dfn interface>History</dfn> {
the <var>specified entry</var>.</p></li>

<li><p>If <var>source browsing context</var> is not <span>allowed to navigate</span>
<var>specified browsing context</var>, then return.</p></li>
<var>specified browsing context</var>, then invoke <span>WebDriver BiDi navigation failed</span> with
with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
data-x="concept-request-url">url</span>, then return.</p></li>

<li><p>If the <var>specified browsing context</var>'s <span>active document</span>'s <span>unload
counter</span> is greater than 0, then return.</p></li>
counter</span> is greater than 0, then invoke <span>WebDriver BiDi navigation failed</span> with
with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
data-x="concept-request-url">url</span>, then return.</p></li>

<li>
<p><span>Queue a global task</span> on the <span>history traversal task source</span> given
<var>specified browsing context</var>'s <span>active window</span> to perform the following
steps:</p>

<ol>
<li><p>If <var>navigationId</var> is null, let <var>navigation id</var> be the result of
<span>generating a random UUID</span>. <ref spec=UUID></p></li>

<li><p>If there is an ongoing attempt to navigate <var>specified browsing context</var>
that has not yet <span data-x="concept-navigate-mature">matured</span> (i.e. it has not passed the
point of making its <code>Document</code> the <span>active document</span>), then cancel that
Expand All @@ -84743,7 +84767,13 @@ interface <dfn interface>History</dfn> {
<ol>
<li><p><span>Prompt to unload</span> the <span>active document</span> of the <var>specified
browsing context</var>. If the user <span>refused to allow the document to be
unloaded</span>, then return.</p></li>
unloaded</span>, , then invoke <span>WebDriver BiDi navigation failed</span> with
with <var>source browsing context</var>, and a <span>WebDriver BiDi navigation status</span>
whose <span data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-canceled">canceled</code>", and <span
data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
data-x="concept-request-url">url</span>, then return.</p></li>

<li><p><span data-x="unload a document">Unload</span> the <span>active document</span> of the
<var>specified browsing context</var>.</p></li>
Expand All @@ -84752,7 +84782,8 @@ interface <dfn interface>History</dfn> {

<li><p><span>Traverse the history</span> of the <var>specified browsing context</var> to
the <var>specified entry</var> with <var><span>explicitHistoryNavigation</span></var> set to
true.</p>
true, and <span data-x="traverse-history-navigationid">navigation id</span> set to
<var>navigationId</var>.</p>
</ol>
</li>
</ol>
Expand Down Expand Up @@ -86246,8 +86277,6 @@ interface <dfn interface>Location</dfn> { // but see also <a href="#the-location
context</span>'s <span>active window</span> has <span>transient activation</span>; otherwise
false.</p></li>

<li><p>Let <var>navigationStatus</var> be </li>

<li><p>Invoke <span>WebDriver BiDi navigation started</span> with <var>browsingContext</var>, and
a new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
Expand Down Expand Up @@ -87363,7 +87392,8 @@ new PaymentRequest(&hellip;); // Allowed to use
<li><p><span>Traverse the history</span> to <var>sessionHistory</var>'s <span>current
entry</span> with <var data-x="traverse-history-hh">historyHandling</var> set to
<var>navigationParams</var>'s <span data-x="navigation-params-hh">history
handling</span>.</p></li>
handling</span>, and <span data-x="traverse-history-navigationid">navigation id</span>
set to <var>navigationId</var>.</p></li>
</ol>
</dd>

Expand Down Expand Up @@ -87393,7 +87423,9 @@ new PaymentRequest(&hellip;); // Allowed to use

<li><p><span>Traverse the history</span> to <var>newEntry</var> with
<var data-x="traverse-history-hh">historyHandling</var> set to "<code
data-x="hh-replace">replace</code>".</p></li>
data-x="hh-replace">replace</code>", and <span
data-x="traverse-history-navigationid">navigation id</span> set to <var>navigationId</var>.
</p></li>
</ol>
</dd>

Expand Down Expand Up @@ -87422,7 +87454,9 @@ new PaymentRequest(&hellip;); // Allowed to use
<li><p><span data-x="list append">Append</span> <var>newEntry</var> to
<var>sessionHistory</var>.</p></li>

<li><p><span>Traverse the history</span> to <var>newEntry</var>.</p></li>
<li><p><span>Traverse the history</span> to <var>newEntry</var> with <span
data-x="traverse-history-navigationid">navigation id</span> set to <var>navigationId</var>.
</p></li>
</ol>
</dd>
</dl>
Expand Down Expand Up @@ -87816,18 +87850,11 @@ new PaymentRequest(&hellip;); // Allowed to use
mode</span>.</p></li>

<li><p><span>Traverse the history</span> to the new entry, with <var
data-x="traverse-history-hh">historyHandling</var> set to <var>historyHandling</var> and with
<var><span>nonBlockingEvents</span></var> set to true. This will <span>scroll to the
fragment</span> given in what is now the document's <span
data-x="traverse-history-hh">historyHandling</var> set to <var>historyHandling</var>,
<var><span>nonBlockingEvents</span></var> set to true, and <span
data-x="traverse-history-navigationid">navigation id</span> set to <var>navigationId</var>.
This will <span>scroll to the fragment</span> given in what is now the document's <span
data-x="concept-document-url">URL</span>.</p></li>

<li><p><p>Invoke <span>WebDriver BiDi fragment navigated</span> with <var>browsingContext</var>,
and a new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-url">url</span> is <var>resource</var>'s <span
data-x="concept-request-url">url</span>, and <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-complete">complete</code>".</p></li>
</ol>

<p class="note">If the scrolling fails because the relevant <span data-x="concept-id">ID</span> has
Expand Down Expand Up @@ -87956,8 +87983,9 @@ new PaymentRequest(&hellip;); // Allowed to use
with an optional <span>history handling behavior</span> <dfn
data-x="traverse-history-hh"><var>historyHandling</var></dfn> (default "<code
data-x="hh-default">default</code>"), an optional boolean <dfn><var>nonBlockingEvents</var></dfn>
(default false), and an optional boolean <dfn><var>explicitHistoryNavigation</var></dfn> (default
false):</p>
(default false), an optional boolean <dfn><var>explicitHistoryNavigation</var></dfn> (default
false), optional <span data-x="navigation-id">navigation id</span>
<dfn data-x="traverse-history-navigationid"><var>navigationId</var></dfn> (default null):</p>

<p class="note">This algorithm is not just invoked when <span data-x="traverse the history by a
delta">explicitly going back or forwards in the session history</span> &mdash; it is also invoked
Expand All @@ -87983,11 +88011,12 @@ new PaymentRequest(&hellip;); // Allowed to use
<li>
<p><span>Navigate</span><!--DONAV history traversal after eviction--> the <span>browsing
context</span> to <var>request</var> with <var data-x="navigation-hh">historyHandling</var>
set to "<code data-x="hh-entry-update">entry update</code>" and with <var
set to "<code data-x="hh-entry-update">entry update</code>", with <var
data-x="navigation-historypolicycontainer">historyPolicyContainer</var> set to
<var>entry</var>'s <span data-x="she-policy-container">policy container</span>. The navigation
must be done using the same <span>source browsing context</span> as was used the first time
<var>entry</var> was created.</p>
<var>entry</var>'s <span data-x="she-policy-container">policy container</span>, and with
<span data-x="navigation-navigationid">navigation id</span> set to <var>navigationId</var>.
The navigation must be done using the same <span>source browsing context</span> as was
used the first time <var>entry</var> was created.</p>

<p class="note">The "<span>navigate</span>" algorithm reinvokes this "traverse" algorithm to
complete the traversal, at which point <var>entry</var>'s <span
Expand All @@ -88009,6 +88038,20 @@ new PaymentRequest(&hellip;); // Allowed to use
<li><p>Let <var>newDocument</var> be <var>entry</var>'s <span
data-x="she-document">document</span>.</p></li>

<li><p>If <var>navigationId</var> is null:</p>
<!-- In practice I think the only case that we use the navigation id in subsequent steps is
when we have a page loaded from the bfcache, in which case document's navigation id is always null.
We could just use null as the navigation id in that case, but it would mean a difference between
a WebDriver-initiated history traversal from the bfcache and a UA initated history traversal. -->
<ol>
<li><p>If <var>newDocument</var>'s <span data-x="concept-document-navigation-id">navigation
id</span> is not null, let <var>navigationId</var> be <var>newDocument</var>'s <span
data-x="concept-document-navigation-id">navigation id</span>. Otherwise let
<var>navigationId</var> be the result of <span>generating a random UUID</span>.
<ref spec=UUID></p></li>
</ol>
</li>

<li><p>If <var>newDocument</var> is different than the <span>current entry</span>'s <span
data-x="she-document">document</span>, or <var>historyHandling</var> is "<code
data-x="hh-entry-update">entry update</code>" or "<code data-x="hh-reload">reload</code>",
Expand Down Expand Up @@ -88098,6 +88141,14 @@ new PaymentRequest(&hellip;); // Allowed to use
<li><p><span>Fire a page transition event</span> named <code
data-x="event-pageshow">pageshow</code> at <var>newDocument</var>'s <span>relevant global
object</span> with true.</p></li>

<li><p>Invoke <span>WebDriver BiDi page show</span> with <var>newDocument</var>'s
<span data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver BiDi
navigation status</span> whose <span data-x="navigation-status-id">id</span> is the
<var>navigationId</var>, <span data-x="navigation-status-status">status</span> is
"<code data-x="navigation-status-complete">complete</code>", and <span
data-x="navigation-status-url">url</span> is the <var>newDocument</var>'s <span
data-x="concept-document-url">URL</span>.</p></li>
</ol>

<!-- an interesting thing to test would be to traverse back during onload, before the first
Expand Down Expand Up @@ -88170,19 +88221,44 @@ new PaymentRequest(&hellip;); // Allowed to use
object</span> to run the following steps instead.</p>

<ol>
<li><p>If <var>stateChanged</var> is true, then <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-popstate">popstate</code> at <var>newDocument</var>'s
<span>relevant global object</span>, using <code>PopStateEvent</code>, with the <code
data-x="dom-PopStateEvent-state">state</code> attribute initialized to <var>state</var>.</p></li>
<li><p>If <var>stateChanged</var> is true:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-popstate">popstate</code> at <var>newDocument</var>'s
<span>relevant global object</span>, using <code>PopStateEvent</code>, with the <code
data-x="dom-PopStateEvent-state">state</code> attribute initialized to <var>state</var>.
</p></li>

<li><p>Invoke <span>WebDriver BiDi pop state</span> with with <var>newDocument</var>'s
<span data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver
BiDi navigation status</span> whose <span data-x="navigation-status-id">id</span> is
<var>navigationId</var>, <span data-x="navigation-status-url">url</span> is
<var>resource</var>'s <span data-x="concept-request-url">url</span>, and <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-complete">complete</code>".</p></li>
</ol>
</li>

<li><p><span>Restore persisted state</span> from <var>entry</var>.</p></li>

<li><p>If <var>hashChanged</var> is true, then <span data-x="concept-event-fire">fire an
event</span> named <code data-x="event-hashchange">hashchange</code> at the <span>browsing
context</span>'s <span>active window</span>, using <code>HashChangeEvent</code>, with the <code
data-x="dom-HashChangeEvent-oldURL">oldURL</code> attribute initialized to <var>oldURL</var>
and the <code data-x="dom-HashChangeEvent-newURL">newURL</code> attribute initialized to
<var>newURL</var>.</p></li>
<li><p>If <var>hashChanged</var> is true:</p>
<ol>
<li><p><span data-x="concept-event-fire">Fire an event</span> named
<code data-x="event-hashchange">hashchange</code> at the <span>browsing context</span>'s
<span>active window</span>, using <code>HashChangeEvent</code>, with the <code
data-x="dom-HashChangeEvent-oldURL">oldURL</code> attribute initialized to <var>oldURL</var>
and the <code data-x="dom-HashChangeEvent-newURL">newURL</code> attribute initialized to
<var>newURL</var>.</p></li>

<li><p>Invoke <span>WebDriver BiDi fragment navigated</span> with <var>newDocument</var>'s
<span data-x="concept-document-bc">browsing context</span>, and a new <span>WebDriver
BiDi navigation status</span> whose <span data-x="navigation-status-id">id</span> is
<var>navigationId</var>, <span data-x="navigation-status-url">url</span> is
<var>resource</var>'s <span data-x="concept-request-url">url</span>, and <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-complete">complete</code>".</p></li>
</ol>
</li>
</ol>
</li>
</ol>
Expand Down

0 comments on commit 5f17205

Please sign in to comment.