Document PopStateEvent() and PopStateEvent.state (#25702)

Co-authored-by: dawei-wang <dawei-wang@users.noreply.github.com>

files/en-us/web/api/history/forward/index.md

@@ -11,8 +11,7 @@ The **`History.forward()`** method causes the browser to move
 forward one page in the session history. It has the same effect as calling
 {{domxref("History.go", "history.go(1)")}}.
 
-This method is {{glossary("asynchronous")}}. Add a listener for the
-{{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed.
+This method is {{glossary("asynchronous")}}. Add a listener for the {{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed.
 
 ## Syntax
 
@@ -43,7 +42,7 @@ history.
 
 ```js
 document.getElementById("go-forward").addEventListener("click", (e) => {
-  window.history.forward();
+  history.forward();
 });
 ```
 
@@ -58,4 +57,5 @@ document.getElementById("go-forward").addEventListener("click", (e) => {
 ## See also
 
 - {{domxref("History")}}
+- {{domxref("Window/popstate_event", "popstate")}}
 - [Working with the History API](/en-US/docs/Web/API/History_API/Working_with_the_History_API)

files/en-us/web/api/history/index.md

@@ -9,6 +9,10 @@ browser-compat: api.History
 
 The **`History`** interface allows manipulation of the browser _session history_, that is the pages visited in the tab or frame that the current page is loaded in.
 
+There is only one instance of `history` (It is a _singleton_.) accessible via the global object {{domxref("Window.history", "history")}}.
+
+> **Note:** This interface is only available on the main thread ({{domxref("Window")}}). It cannot be accessed in {{domxref("Worker")}} or {{domxref("Worklet")}} contexts.
+
 ## Instance properties
 
 _The `History` interface doesn't inherit any property._
@@ -53,4 +57,4 @@ _The `History`_ _interface doesn't inherit any methods._
 
 ## See also
 
-- The {{domxref("Window.history")}} property returning the history of the current session.
+- {{domxref("Window.history", "history")}} global object

files/en-us/web/api/history/pushstate/index.md

@@ -11,6 +11,8 @@ In an [HTML](/en-US/docs/Web/HTML) document, the
 **`history.pushState()`** method adds an entry to the browser's
 session history stack.
 
+This method is {{glossary("asynchronous")}}. Add a listener for the {{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed. The `state` parameter will be available in it.
+
 ## Syntax
 
 ```js-nolint
@@ -89,9 +91,9 @@ history.pushState(state, "", url);
 ### Change a query parameter
 
 ```js
-const url = new URL(window.location);
+const url = new URL(location);
 url.searchParams.set("foo", "bar");
-window.history.pushState({}, "", url);
+history.pushState({}, "", url);
 ```
 
 ## Specifications

files/en-us/web/api/history/replacestate/index.md

@@ -13,18 +13,20 @@ URL passed in the method parameters. This method is particularly useful
 when you want to update the state object or URL of the current history entry in response
 to some user action.
 
+This method is {{glossary("asynchronous")}}. Add a listener for the {{domxref("Window/popstate_event", "popstate")}} event in order to determine when the navigation has completed. The `state` parameter will be available in it.
+
 ## Syntax
 
 ```js-nolint
-replaceState(stateObj, unused)
-replaceState(stateObj, unused, url)
+replaceState(state, unused)
+replaceState(state, unused, url)
 ```
 
 ### Parameters
 
-- `stateObj`
-  - : The state object is a JavaScript object which is associated with the history entry
-    passed to the `replaceState` method. The state object can be
+- `state`
+  - : An object which is associated with the history entry
+    passed to the `replaceState()` method. The state object can be
     `null`.
 - `unused`
   - : This parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional, and safe against future changes to the method.

files/en-us/web/api/history/state/index.md

@@ -48,3 +48,4 @@ console.log("History.state after pushState: ", history.state);
 - [Working with the History API](/en-US/docs/Web/API/History_API/Working_with_the_History_API)
 - [`History.pushState()`](/en-US/docs/Web/API/History/pushState)
 - [`History.replaceState()`](/en-US/docs/Web/API/History/replaceState)
+- [`PopStateEvent.state`](/en-US/docs/Web/API/PopStateEvent/state)

files/en-us/web/api/history_api/example/index.md

@@ -1,10 +1,10 @@
 ---
-title: Ajax navigation example
+title: History navigation example
 slug: Web/API/History_API/Example
 page-type: guide
 ---
 
-This is an example of an AJAX website composed only of three pages (_first_page.php_, _second_page.php_ and _third_page.php_). To see how it works, please create the following files (or git clone [https://github.com/giabao/mdn-ajax-nav-example.git](https://github.com/giabao/mdn-ajax-nav-example) ):
+This is an example of a website composed only of three pages (_first_page.php_, _second_page.php_ and _third_page.php_). To see how it works, please create the following files (or git clone [https://github.com/giabao/mdn-ajax-nav-example.git](https://github.com/giabao/mdn-ajax-nav-example) ):
 
 > **Note:** For fully integrating the {{HTMLElement("form")}} elements within this _mechanism_, please take a look at the paragraph [Submitting forms and uploading files](/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest#submitting_forms_and_uploading_files).
 
@@ -422,5 +422,5 @@ For more information, please see: [Working with the History API](/en-US/docs/Web
 
 ## See also
 
-- {{ domxref("window.history") }}
+- {{domxref("window.history", "history")}} global object
 - {{domxref("Window/popstate_event", "popstate")}} event

files/en-us/web/api/history_api/index.md

@@ -7,7 +7,9 @@ browser-compat: api.History
 
 {{DefaultAPISidebar("History API")}}
 
-The DOM {{DOMxRef("Window")}} object provides access to the browser's session history (not to be confused for [WebExtensions history](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history)) through the {{DOMxRef("Window.history","history")}} object. It exposes useful methods and properties that let you navigate back and forth through the user's history, and manipulate the contents of the history stack.
+The **History API** provides access to the browser's session history (not to be confused with [WebExtensions history](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history)) through the {{DOMxRef("Window.history","history")}} global object. It exposes useful methods and properties that let you navigate back and forth through the user's history, and manipulate the contents of the history stack.
+
+> **Note:** This API is only available on the main thread ({{domxref("Window")}}). It cannot be accessed in {{domxref("Worker")}} or {{domxref("Worklet")}} contexts.
 
 ## Concepts and usage
 
@@ -18,15 +20,15 @@ Moving backward and forward through the user's history is done using the {{DOMxR
 To move backward through history:
 
 ```js
-window.history.back();
+history.back();
 ```
 
 This acts exactly as if the user clicked on the <kbd><strong>Back</strong></kbd> button in their browser toolbar.
 
 Similarly, you can move forward (as if the user clicked the <kbd><strong>Forward</strong></kbd> button), like this:
 
 ```js
-window.history.forward();
+history.forward();
 ```
 
 ### Moving to a specific point in history
@@ -36,13 +38,13 @@ You can use the {{DOMxRef("History.go","go()")}} method to load a specific page
 To move back one page (the equivalent of calling {{DOMxRef("History.back","back()")}}):
 
 ```js
-window.history.go(-1);
+history.go(-1);
 ```
 
 To move forward a page, just like calling {{DOMxRef("History.forward","forward()")}}:
 
 ```js
-window.history.go(1);
+history.go(1);
 ```
 
 Similarly, you can move forward 2 pages by passing `2`, and so forth.
@@ -53,27 +55,29 @@ Another use for the `go()` method is to refresh the current page by either passi
 // The following statements
 // both have the effect of
 // refreshing the page
-window.history.go(0);
-window.history.go();
+history.go(0);
+history.go();
 ```
 
 You can determine the number of pages in the history stack by looking at the value of the `length` property:
 
 ```js
-let numberOfEntries = window.history.length;
+const numberOfEntries = history.length;
 ```
 
 ## Interfaces
 
 - {{domxref("History")}}
   - : Allows manipulation of the browser _session history_ (that is, the pages visited in the tab or frame that the current page is loaded in).
+- {{domxref("PopStateEvent")}}
+  - : The interface of the {{domxref("Window.popstate_event", "popstate")}} event.
 
 ## Examples
 
-The following example assigns a listener to the `onpopstate` property. And then illustrates some of the methods of the history object to add, replace, and move within the browser history for the current tab.
+The following example assigns a listener for the {{domxref("Window.popstate_event", "popstate")}} event. It then illustrates some of the methods of the history object to add, replace, and move within the browser history for the current tab.
 
 ```js
-window.onpopstate = (event) => {
+window.addEventListener("popstate", (event) => {
   alert(
     `location: ${document.location}, state: ${JSON.stringify(event.state)}`
   );
@@ -97,11 +101,5 @@ history.go(2); // alerts "location: http://example.com/example.html?page=3, stat
 
 ## See also
 
-### References
-
-- {{ domxref("window.history") }}
+- {{domxref("window.history", "history")}} global object
 - {{domxref("Window/popstate_event", "popstate")}} event
-
-### Guides
-
-- [Working with the History API](/en-US/docs/Web/API/History_API/Working_with_the_History_API)

files/en-us/web/api/history_api/working_with_the_history_api/index.md

@@ -5,6 +5,7 @@ page-type: guide
 ---
 
 {{DefaultAPISidebar("History API")}}
+
 The {{DOMxRef("History.pushState","pushState()")}} and {{DOMxRef("History.replaceState","replaceState()")}} methods add and modify history entries, respectively. These methods work in conjunction with the {{domxref("Window/popstate_event", "popstate")}} event.
 
 ## Adding and modifying history entries
@@ -16,7 +17,7 @@ Using {{DOMxRef("History.pushState","pushState()")}} changes the referrer that g
 Suppose `https://mozilla.org/foo.html` executes the following JavaScript:
 
 ```js
-let stateObj = {
+const stateObj = {
   foo: "bar",
 };
 
@@ -67,7 +68,9 @@ In other documents, it creates an element with a `null` namespace URI.
 Suppose `https://mozilla.org/foo.html` executes the following JavaScript:
 
 ```js
-let stateObj = { foo: "bar" };
+const stateObj = {
+  foo: "bar",
+};
 history.pushState(stateObj, "page 2", "bar.html");
 ```
 
@@ -96,11 +99,11 @@ When your page loads, it might have a non-null state object. This can happen, fo
 You can read the state of the current history entry without waiting for a `popstate` event using the {{DOMxRef("History.state","history.state")}} property like this:
 
 ```js
-let currentState = history.state;
+const currentState = history.state;
 ```
 
 ## See also
 
 - [History API](/en-US/docs/Web/API/History_API)
-- [Ajax navigation example](/en-US/docs/Web/API/History_API/Example)
-- {{ domxref("window.history") }}
+- [History navigation example](/en-US/docs/Web/API/History_API/Example)
+- {{domxref("window.history", "history")}} global object

files/en-us/web/api/popstateevent/index.md

@@ -5,7 +5,7 @@ page-type: web-api-interface
 browser-compat: api.PopStateEvent
 ---
 
-{{APIRef("HTML DOM")}}
+{{APIRef("History API")}}
 
 **`PopStateEvent`** is an interface for the [`popstate`](/en-US/docs/Web/API/Window/popstate_event) event.
 

files/en-us/web/api/popstateevent/popstateevent/index.md

@@ -0,0 +1,46 @@
+---
+title: PopStateEvent()
+slug: Web/API/PopStateEvent/PopStateEvent
+page-type: web-api-constructor
+browser-compat: api.PopStateEvent.PopStateEvent
+---
+
+{{APIRef("History API")}}
+
+The **`PopStateEvent()`** constructor creates a new {{domxref("PopStateEvent")}} object.
+
+> **Note:** A web developer doesn't typically need to call this constructor, as the browser creates these objects itself when firing {{domxref("Window/popstate_event", "popstate")}} events.
+
+## Syntax
+
+```js-nolint
+new PopStateEvent(type, options)
+```
+
+### Parameters
+
+- `type`
+  - : A string with the name of the event.
+    It is case-sensitive and browsers set it to `popstate`.
+- `options` {{optional_inline}}
+  - : An object that, _in addition to the properties defined in {{domxref("Event/Event", "Event()")}}_, has the following property:
+    - `state` {{optional_inline}}
+      - : An object representing the state. Practically it is a value provided by the call to {{domxref("history.pushState()")}} or {{domxref("history.replaceState()")}}. If not set, it defaults to `null`.
+
+### Return value
+
+A new {{domxref("PopStateEvent")}} object.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("history.pushState()")}}
+- {{domxref("history.replaceState()")}}
+- {{domxref("Window/popstate_event", "popstate")}} event

files/en-us/web/api/popstateevent/state/index.md

@@ -0,0 +1,56 @@
+---
+title: PopStateEvent.state
+slug: Web/API/PopStateEvent/state
+page-type: web-api-instance-property
+browser-compat: api.PopStateEvent.state
+---
+
+{{ APIRef("History API") }}
+
+The **`state`** read-only property of the {{domxref("PopStateEvent")}} interface represents the state stored when the event was created.
+
+Practically it is a value provided by the call to {{domxref("history.pushState()")}} or {{domxref("history.replaceState()")}}
+
+## Value
+
+An object, or `null`.
+
+## Examples
+
+The code below logs the value of `state` when using the
+{{domxref("History.pushState","pushState()")}} method to push a value to the history.
+
+```js
+// Log the state of
+addEventListener("popstate", (event) => {
+  console.log("State received: ", event.state);
+});
+
+// Now push something on the stack
+history.pushState({ name: "Example" }, "pushState example", "page1.html");
+history.pushState(
+  { name: "Another example" },
+  "pushState example",
+  "page1.html"
+);
+```
+
+This will log:
+
+```plain
+State received: { name: "Example" }
+State received: { name: "Another example" }
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("PopStateEvent()")}} constructor
+- {{domxref("History.state")}}

files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md

@@ -79,7 +79,6 @@ Browsers must serialize the properties `name` and `message`, and are expected to
 - [HTML Specification: Safe passing of structured data](https://html.spec.whatwg.org/multipage/infrastructure.html#safe-passing-of-structured-data)
 - [Transferable objects](/en-US/docs/Web/API/Web_Workers_API/Transferable_objects)
 - {{domxref("structuredClone()")}}
-- {{domxref("window.history")}}
 - {{domxref("window.postMessage()")}}
 - [Web Workers](/en-US/docs/Web/API/Web_Workers_API)
 - [IndexedDB](/en-US/docs/Web/API/IndexedDB_API)

files/en-us/web/api/window/forward/index.md

@@ -11,7 +11,7 @@ status:
 
 Moves the window one document forward in history. This was a Firefox-specific method and was removed in Firefox 31.
 
-> **Note:** Use the standard {{domxref("History.forward", "window.history.forward()")}} method instead.
+> **Note:** Use the standard {{domxref("History.forward", "history.forward()")}} method instead.
 
 ## Syntax
 

files/en-us/web/api/window/index.md

@@ -270,11 +270,11 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface a
 ### Deprecated methods
 
 - {{domxref("Window.back()")}} {{Non-standard_Inline}} {{Deprecated_Inline}}
-  - : Moves back one in the window history. This method is deprecated; you should instead use {{domxref("History.back", "window.history.back()")}}.
+  - : Moves back one in the window history. This method is deprecated; you should instead use {{domxref("History.back", "history.back()")}}.
 - {{domxref("Window.captureEvents()")}} {{Deprecated_Inline}}
   - : Registers the window to capture all events of the specified type.
 - {{domxref("Window.forward()")}} {{Non-standard_Inline}} {{Deprecated_Inline}}
-  - : Moves the window one document forward in the history. This method is deprecated; you should instead use {{domxref("History.forward", "window.history.forward()")}}.
+  - : Moves the window one document forward in the history. This method is deprecated; you should instead use {{domxref("History.forward", "history.forward()")}}.
 - {{domxref("Window.releaseEvents()")}} {{Deprecated_Inline}}
   - : Releases the window from trapping events of a specific type.
 - {{domxref("Window.showModalDialog()")}} {{Non-standard_Inline}} {{Deprecated_Inline}}