feat: improved embed navigation APIs

docs/docs/developers/embed/postmessage.md

@@ -116,6 +116,8 @@ iframe.contentWindow.postMessage({
 
 `success` is `false` when `failOnError` is `true` and validation produced errors, in which case the state is not applied and `appliedState` is omitted. `appliedState` is the canonicalized query string that was actually applied to the dashboard. `errors` contains a message for each invalid parameter.
 
+Applying a state also discards the state the dashboard was last viewed with in this embed session, so the dashboard renders exactly the state that was applied. In particular, `setValidState({ state: "" })` resets the dashboard to its default view rather than restoring the previously viewed filters.
+
 
 ### `getState()`
 
@@ -307,6 +309,114 @@ iframe.contentWindow.postMessage({
 
 **Note:** The AI pane is only available for dashboards when the chat feature is enabled. If the AI pane is not available, calling this method will not cause an error, but the pane will not be shown.
 
+
+### `navigateToDashboard({ name, state, failOnError })`
+
+Navigates the iframe to another dashboard in the same project.
+
+```js
+iframe.contentWindow.postMessage({
+  id: 9,
+  method: "navigateToDashboard",
+  params: { name: "bids_explore", state: "view=pivot&tr=PT24H&grain=hour" },
+}, "*");
+```
+
+**Parameters:**
+- `name` (string): The name of the explore or canvas dashboard to navigate to, as defined in the project's YAML files.
+- `state` (string, optional): A URL query string to apply to the dashboard being navigated to. When omitted, the dashboard opens in its default state, even if it was previously visited with filters applied in this embed session. The state of the dashboard being navigated away from is never carried over.
+- `failOnError` (boolean, optional): Behaves the same as in `setValidState`. When `false` (the default), the cleaned state is applied even when some parameters were invalid; when `true`, the navigation is skipped entirely if validation produced errors.
+
+**Response:**
+
+```json
+{ "id": 9, "result": { "success": true, "appliedState": "view=pivot&tr=PT24H&grain=hour", "errors": [] } }
+```
+
+The response has the same shape as `setValidState`: `state` is validated against the target dashboard's metrics view and explore specs, and `appliedState` is the canonicalized query string that was actually applied. As with `setValidState`, validation is currently supported for explore dashboards; for other dashboard types the state is applied as-is.
+
+**Error Response (if the dashboard does not exist):**
+
+```json
+{
+  "id": 9,
+  "error": {
+    "code": -32603,
+    "message": "Dashboard \"bids_explore\" not found"
+  }
+}
+```
+
+The same error is returned when `name` refers to a resource that is not an explore or canvas dashboard, or to a dashboard the embed's access token does not grant access to.
+
+Each call adds an entry to the browser's session history, so it can be undone with `navigateBack` as long as the host page has not navigated in the meantime.
+
+**Note:** All three navigation methods require navigation to be enabled in the embed configuration. When the embed is configured with `navigation=false`, they return an error instead of navigating:
+
+```json
+{
+  "id": 9,
+  "error": {
+    "code": -32603,
+    "message": "Navigation is disabled for this embed"
+  }
+}
+```
+
+
+### `navigateBack()`
+
+Navigates back to the previous entry in the browser's session history, equivalent to the browser's back button.
+
+```js
+iframe.contentWindow.postMessage({
+  id: 10,
+  method: "navigateBack",
+}, "*");
+```
+
+**Parameters:** None.
+
+**Response:**
+
+```json
+{ "id": 10, "result": true }
+```
+
+The browser's session history belongs to the whole tab, not to the iframe: it interleaves the host page's entries with the embed's in the order they were created, and [`history.back()`](https://html.spec.whatwg.org/multipage/nav-history-apis.html#dom-history-back) traverses that shared history. So `navigateBack` steps back one entry in the tab, whichever document created it:
+
+- When the embed created the most recent entry, the embed navigates back. This is the case whenever the host page stays put while the embed is open.
+- When the host page navigated more recently than the embed did, that host navigation is undone instead and the embed stays where it is.
+- When there is no earlier entry at all, for example on the first dashboard the embed loaded with a host page that has not navigated, the call succeeds without navigating. If the host page does have earlier entries, the tab goes back to one of them and the embed is unloaded along with the page.
+
+If your host page navigates while an embed is open, and you need back and forward to move only the embed, keep track of the dashboards and states you have applied and replay them with `navigateToDashboard` or `setValidState` instead of using `navigateBack` and `navigateForward`.
+
+**Note:** This method returns the `Navigation is disabled for this embed` error when the embed is configured with `navigation=false`.
+
+
+### `navigateForward()`
+
+Navigates forward to the next entry in the browser's session history, equivalent to the browser's forward button.
+
+```js
+iframe.contentWindow.postMessage({
+  id: 11,
+  method: "navigateForward",
+}, "*");
+```
+
+**Parameters:** None.
+
+**Response:**
+
+```json
+{ "id": 11, "result": true }
+```
+
+As with `navigateBack`, this traverses the tab's shared session history, so it can redo a host page navigation rather than an embed one. It succeeds without navigating when there is no next entry, which is the case unless the tab was taken back first, since any new navigation discards the forward entries.
+
+**Note:** As with `navigateBack`, this method returns an error when the embed is configured with `navigation=false`.
+
 ## Notifications
 
 Notifications are sent **from the iframe** to the parent window. These do not include an `id`.
@@ -329,7 +439,7 @@ Fired whenever the internal state of the iframe changes.
 
 ### `navigation({ from: string, to: string })`
 
-Fired whenever a user navigates between dashboards. This event is only emitted when navigation is enabled in the embed configuration.
+Fired whenever navigation between dashboards happens, either through a user interaction or through a `navigateToDashboard` call. This event is only emitted when navigation is enabled in the embed configuration.
 
 - `from`: The name of the dashboard the user navigated from, or `"dashboardListing"` if navigating from the dashboard listing page
 - `to`: The name of the dashboard the user navigated to, or `"dashboardListing"` if navigating to the dashboard listing page
@@ -451,6 +561,9 @@ window.addEventListener("message", async (event) => {
     const aiPaneState = await sendRequest("getAiPane");
     console.log("AI pane open:", aiPaneState.open);
     await sendRequest("setAiPane", true);
+
+    await sendRequest("navigateToDashboard", { name: "bids_canvas" });
+    await sendRequest("navigateBack");
   }
 
   if (event.data?.method === "stateChanged") {