docs(loading): nits and fixes

docs/loading.md

@@ -2,70 +2,74 @@
 
 Playwright logically splits the process of showing a new document in the page into **navigation** and **loading**.
 
-**Navigation** starts with an intent, for example:
-- loading a url with [`page.goto('http://example.com')`](api.md#pagegotourl-options);
-- clicking a link with [`page.click('text="Continue"')`](api.md#pageclickselector-options);
-- reloading with [`page.reload()`](api.md#pagereloadoptions);
-- assiging to [location](https://developer.mozilla.org/en-US/docs/Web/API/Location) in the script like `location.href = 'http://example.com'`;
-- using [history api](https://developer.mozilla.org/en-US/docs/Web/API/History) in the script like `history.pushState({}, 'title', '#deep-link')`.
-
-This navigation intent may result in a navigation or get canceled, for example transformed into a download. When navigation succeeds, page starts **loading** the document.
-
-**Loading** usually takes time, retrieving the response over the network, parsing, executing scripts and firing events. The typical loading scenario is:
-- [`page.url()`](api.md#pageurl) is set to the loading url;
-- document content is loaded over network and parsed;
-- [`domcontentloaded`](api.md#event-domcontentloaded) event is fired;
-- page executes some scripts and loads resources like stylesheets and images;
-- `networkidle2` is triggered (no more than two network connections for at least `500` ms),
-- [`load`](api.md#event-load) event is fired;
-- page executes some more scripts;
-- `networkidle0` is triggered (no network connections for at least `500` ms).
+### Navigation
 
-### Common scenarios
+Page navigation can be either initiated by the Playwright call:
+
+```js
+// Load a page
+await page.goto('https://example.com')
+
+// Reload a page
+await page.reload()
+
+// Click a link
+await page.click('text="Continue"')
+```
+
+or by the page itself:
+
+```js
+// Programmatic navigation
+window.location.href = 'https://example.com'
+
+// Single page app navigation
+history.pushState({}, 'title', '#deep-link')
+```
+
+Navigation intent may result in being canceled, for example transformed into a download or hitting an unresolved DNS address. Only when the navigation succeeds, page starts **loading** the document.
 
-Playwright tries its best to handle **navigations** seamlessly, so that script does not have to worry about it:
-- `page.goto()` waits for the navigation to happen;
-- `page.click('a')` waits for synchronously triggered navigation to happen;
-- history api calls are treated as navigations to make automating single-page applications easy.
+### Loading
 
-Playwright reasonably handles **loading** by default - it waits for the `load` event in explicit navigations like `page.goto()`; and for the `domcontentloaded` event in the implicit navigations triggered by clicks, evaluations and popups.
+Page load takes time retrieving the response body over the network, parsing, executing the scripts and firing the events. Typical load scenario goes through the following load states:
+- [`page.url()`](api.md#pageurl) is set to the new url
+- document content is loaded over network and parsed
+- [`domcontentloaded`](api.md#event-domcontentloaded) event is fired
+- page executes some scripts and loads resources like stylesheets and images
+- [`load`](api.md#event-load) event is fired
+- page executes dynamically loaded scripts
+- `networkidle0` is fired - no new network requests made for at least `500` ms
 
-In the typical scenario where navigation is followed by performing some action, the action will wait for the target element to appear. There is no need to explicitly wait for loading to finish.
+### Common scenarios
 
-Consider the following scenario, where everything is handled by Playwright behind the scenes:
+By default, Playwright handles navigations seamlessly so that you did not need to think about them. Consider the following scenario, where everything is handled by Playwright behind the scenes:
 
 ```js
-// The page does a client-side redirect to 'http://example.com/login'.
-// Playwright automatically waits for the login page to load.
 await page.goto('http://example.com');
+// If the page does a client-side redirect to 'http://example.com/login'.
+// Playwright will automatically wait for the login page to load.
 
 // Playwright waits for the lazy loaded #username and #password inputs
 // to appear before filling the values.
 await page.fill('#username', 'John Doe');
 await page.fill('#password', '********');
 
 // Playwright waits for the login button to become enabled and clicks it.
+await page.click('text=Login');
 // Clicking the button navigates to the logged-in page and Playwright
 // automatically waits for that.
-await page.click('text=Login');
 ```
 
-However, depending on the page, an explicit loading handling may be required.
-
-### Lazy loading, for example client side hydration
-
-When the page loads essential content lazily (e.g. from the `onload`), loading stages like `networkidle0` or `networkidle2` can help.
-```js
-await page.goto('http://example.com', { waitUntil: 'networkidle0' });
-// Hydration is done, all the lazy resources have been loaded, ready to take a screenshot.
-await page.screenshot();
-```
+Explicit loading handling may be required for more complicated scenarios though.
 
 ### Loading a popup
 
-When popup is opened, explicitly calling [`page.waitForLoadState()`](#pagewaitforloadstatestate-options) ensures that popup is ready for evaluation.
+When popup is opened, explicitly calling [`page.waitForLoadState()`](#pagewaitforloadstatestate-options) ensures that popup is loaded to the desired state.
 ```js
-const {popup} = await page.click('a[target="_blank"]');  // Opens a popup.
+const { popup } = await Promise.all([
+  page.waitForEvent('popup'),
+  page.click('a[target="_blank"]')  // <-- opens popup
+]);
 await popup.waitForLoadState('load');
 await popup.evaluate(() => window.globalVariableInitializedByOnLoadHandler);
 ```
@@ -75,22 +79,24 @@ await popup.evaluate(() => window.globalVariableInitializedByOnLoadHandler);
 Usually, the client-side redirect happens before the `load` event, and `page.goto()` method automatically waits for the redirect. However, when redirecting from a link click or after the `load` event, it would be easier to explicitly [`waitForNavigation()`](#pagewaitfornavigationoptions) to a specific url.
 ```js
 await Promise.all([
-  page.click('a'), // Triggers a navigation with a script redirect.
   page.waitForNavigation({ url: '**/login' }),
+  page.click('a'), // Triggers a navigation with a script redirect.
 ]);
 ```
-Note the `Promise.all` to click and wait for navigation at the same time. Awaiting these methods one after the other is racy, because navigation could happen too fast.
+
+Notice the `Promise.all` to click and wait for navigation. Awaiting these methods one after the other is racy, because navigation could happen too fast.
 
 ### Click triggers navigation after a timeout
 
 When `onclick` handler triggers a navigation from a `setTimeout`, use an explicit [`waitForNavigation()`](#pagewaitfornavigationoptions) call as a last resort.
 ```js
 await Promise.all([
-  page.click('a'), // Triggers a navigation after a timeout.
   page.waitForNavigation(), // Waits for the next navigation.
+  page.click('a'), // Triggers a navigation after a timeout.
 ]);
 ```
-Note the `Promise.all` to click and wait for navigation at the same time. Awaiting these methods one after the other is racy, because navigation could happen too fast.
+
+Notice the `Promise.all` to click and wait for navigation. Awaiting these methods one after the other is racy, because navigation could happen too fast.
 
 ### Unpredictable patterns
 
@@ -105,7 +111,11 @@ await page.screenshot();
 When clicking on a button triggers some asynchronous processing, issues a couple GET requests and pushes a new history state multiple times, explicit [`waitForNavigation()`](#pagewaitfornavigationoptions) to a specific url is the most reliable option.
 ```js
 await Promise.all([
-  page.click('text=Process the invoice'), // Triggers some complex handling.
   page.waitForNavigation({ url: '**/invoice#processed' }),
+  page.click('text=Process the invoice'), // Triggers some complex handling.
 ]);
 ```
+
+### Lazy loading, hydration
+
+TBD