@gooddata/sdk-ui-pluggable-application 11.55.0-alpha.3 → 11.55.0-alpha.4

package/esm/hostNavigation.d.ts

@@ -0,0 +1,54 @@
+import { type IHostNavigationRequest } from "@gooddata/sdk-pluggable-application-model";
+/**
+ * Mutable slot an application's router fills with its navigate function once it exists.
+ *
+ * @remarks
+ * The path handed to `navigate` is relative to the application's base path (starts with "/").
+ * The implementation must navigate with history REPLACE semantics: the takeover lets the host
+ * push first (see {@link createHostNavigationTakeover}), so the replace lands on the entry that
+ * push created and history gains exactly one entry, with the source entry preserved.
+ *
+ * An application whose navigation guard can cancel this navigation (an unsaved-changes blocker)
+ * is responsible for restoring the URL when the user cancels — the host push has already
+ * happened by then. gdc-reports' editor does this on its Stay choice.
+ *
+ * @alpha
+ */
+export interface IPluggableAppNavigateRef {
+    current: ((path: string) => void) | null;
+}
+/**
+ * The in-app route a host navigation target stands for, or undefined when the target leaves
+ * the application.
+ *
+ * @remarks
+ * Query and hash ride along with the path.
+ *
+ * @alpha
+ */
+export declare function inAppPath(url: string, basePath: string): string | undefined;
+/**
+ * Builds an {@link @gooddata/sdk-pluggable-application-model#IPluggableApplicationMountHandle.onHostNavigationRequested}
+ * handler that takes over host navigations landing inside the application.
+ *
+ * @remarks
+ * The host chrome navigates through its own router, which the application's router does not
+ * observe — an unhandled chrome push targeting the application would change the URL and render
+ * nothing. The returned handler drives targets inside the base path through the application's
+ * own navigation (which also keeps its navigation guards in force) and leaves anything else to
+ * the host.
+ *
+ * The takeover still calls `proceed` before navigating: the host push keeps the host chrome's
+ * own location state (menu highlight, targets derived from the current path) in sync and
+ * preserves the source history entry; the application then renders by REPLACING that entry
+ * with the same URL, so history gains exactly one entry. Push-first is a deliberate trade-off:
+ * ordering the push after the application navigation would either destroy the source entry
+ * (replace) or duplicate the target (push), and gating it on the navigation committing loses
+ * the push when a navigation guard confirms later. The cost is that a guard cancelling the
+ * follow-up navigation leaves the pushed URL behind — which is why the guard owner restores
+ * the URL on cancel (see {@link IPluggableAppNavigateRef}).
+ *
+ * @alpha
+ */
+export declare function createHostNavigationTakeover(basePath: string, navigateRef: IPluggableAppNavigateRef): (request: IHostNavigationRequest) => boolean;
+//# sourceMappingURL=hostNavigation.d.ts.map

package/esm/hostNavigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostNavigation.d.ts","sourceRoot":"","sources":["../src/hostNavigation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAExF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5C;AAUD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsB3E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4BAA4B,CACxC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,wBAAwB,GACtC,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAW9C"}

package/esm/hostNavigation.js

@@ -0,0 +1,75 @@
+// (C) 2026 GoodData Corporation
+const RELATIVE_ORIGIN = "https://pluggable.invalid";
+// The real origin when running in a browser, so same-origin absolute targets resolve as in-app;
+// outside one the sentinel makes every absolute URL foreign, which is the only safe reading.
+function resolutionOrigin() {
+    return typeof location === "object" && location?.origin ? location.origin : RELATIVE_ORIGIN;
+}
+/**
+ * The in-app route a host navigation target stands for, or undefined when the target leaves
+ * the application.
+ *
+ * @remarks
+ * Query and hash ride along with the path.
+ *
+ * @alpha
+ */
+export function inAppPath(url, basePath) {
+    const base = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+    const origin = resolutionOrigin();
+    // URL resolution collapses dot segments ("..", "%2e%2e"), which a raw prefix check would let
+    // slip past the base and take over a navigation that actually leaves the application.
+    let target;
+    try {
+        target = new URL(url, origin);
+    }
+    catch {
+        // A target that does not parse is not in-app; the host decides what to do with it.
+        return undefined;
+    }
+    // A cross-origin target is never in-app, whatever its pathname looks like — a navigation to
+    // another origin must stay the host's to perform.
+    if (target.origin !== origin) {
+        return undefined;
+    }
+    const { pathname } = target;
+    if (pathname !== base && !pathname.startsWith(`${base}/`)) {
+        return undefined;
+    }
+    return `${pathname.slice(base.length) || "/"}${target.search}${target.hash}`;
+}
+/**
+ * Builds an {@link @gooddata/sdk-pluggable-application-model#IPluggableApplicationMountHandle.onHostNavigationRequested}
+ * handler that takes over host navigations landing inside the application.
+ *
+ * @remarks
+ * The host chrome navigates through its own router, which the application's router does not
+ * observe — an unhandled chrome push targeting the application would change the URL and render
+ * nothing. The returned handler drives targets inside the base path through the application's
+ * own navigation (which also keeps its navigation guards in force) and leaves anything else to
+ * the host.
+ *
+ * The takeover still calls `proceed` before navigating: the host push keeps the host chrome's
+ * own location state (menu highlight, targets derived from the current path) in sync and
+ * preserves the source history entry; the application then renders by REPLACING that entry
+ * with the same URL, so history gains exactly one entry. Push-first is a deliberate trade-off:
+ * ordering the push after the application navigation would either destroy the source entry
+ * (replace) or duplicate the target (push), and gating it on the navigation committing loses
+ * the push when a navigation guard confirms later. The cost is that a guard cancelling the
+ * follow-up navigation leaves the pushed URL behind — which is why the guard owner restores
+ * the URL on cancel (see {@link IPluggableAppNavigateRef}).
+ *
+ * @alpha
+ */
+export function createHostNavigationTakeover(basePath, navigateRef) {
+    return ({ url, proceed }) => {
+        const target = inAppPath(url, basePath);
+        const navigate = navigateRef.current;
+        if (target === undefined || navigate === null) {
+            return false;
+        }
+        proceed();
+        navigate(target);
+        return true;
+    };
+}

package/esm/index.d.ts

@@ -9,4 +9,5 @@ export { AppProviders, type IAppProvidersProps } from "./AppProviders.js";
 export { type IPluggableAppEventsContextValue, type IPluggableAppEventsProviderProps, PluggableAppEventsProvider, usePluggableAppEvents, } from "./events.js";
 export { type IModuleTelemetryMetadata, type IPluggableAppTelemetryProviderProps, enrichTelemetryCallbacks, PluggableAppTelemetryProvider, usePluggableAppTelemetry, } from "./telemetry.js";
 export { subscribeAiAssistantDefault } from "./ai.js";
+export { type IPluggableAppNavigateRef, createHostNavigationTakeover, inAppPath } from "./hostNavigation.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EACH,KAAK,sBAAsB,EAC3B,uBAAuB,EACvB,KAAK,6BAA6B,EAClC,kBAAkB,EAClB,wBAAwB,GAC3B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,sBAAsB,EAAE,KAAK,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAE3F,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EACH,KAAK,+BAA+B,EACpC,KAAK,gCAAgC,EACrC,0BAA0B,EAC1B,qBAAqB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACH,KAAK,wBAAwB,EAC7B,KAAK,mCAAmC,EACxC,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,GAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EACH,KAAK,sBAAsB,EAC3B,uBAAuB,EACvB,KAAK,6BAA6B,EAClC,kBAAkB,EAClB,wBAAwB,GAC3B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,sBAAsB,EAAE,KAAK,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAE3F,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EACH,KAAK,+BAA+B,EACpC,KAAK,gCAAgC,EACrC,0BAA0B,EAC1B,qBAAqB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACH,KAAK,wBAAwB,EAC7B,KAAK,mCAAmC,EACxC,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,GAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,KAAK,wBAAwB,EAAE,4BAA4B,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC"}

package/esm/index.js

@@ -11,3 +11,4 @@ export { AppProviders } from "./AppProviders.js";
 export { PluggableAppEventsProvider, usePluggableAppEvents, } from "./events.js";
 export { enrichTelemetryCallbacks, PluggableAppTelemetryProvider, usePluggableAppTelemetry, } from "./telemetry.js";
 export { subscribeAiAssistantDefault } from "./ai.js";
+export { createHostNavigationTakeover, inAppPath } from "./hostNavigation.js";

package/esm/sdk-ui-pluggable-application.d.ts

@@ -6,6 +6,7 @@
 
 import { IAnalyticalBackend } from '@gooddata/sdk-backend-spi';
 import { IAuthCredentials } from '@gooddata/sdk-pluggable-application-model';
+import { IHostNavigationRequest } from '@gooddata/sdk-pluggable-application-model';
 import { ILocale } from '@gooddata/sdk-model';
 import { IPlatformContext } from '@gooddata/sdk-pluggable-application-model';
 import { IPluggableAppEvent } from '@gooddata/sdk-pluggable-application-model';
@@ -68,6 +69,31 @@ export declare function AppProviders({ ctx, packageName, resolveMessages: resolv
  */
 export declare function createBackendForModule(auth: IAuthCredentials, options: ICreateBackendForModuleOptions): IAnalyticalBackend;
 
+/**
+ * Builds an {@link @gooddata/sdk-pluggable-application-model#IPluggableApplicationMountHandle.onHostNavigationRequested}
+ * handler that takes over host navigations landing inside the application.
+ *
+ * @remarks
+ * The host chrome navigates through its own router, which the application's router does not
+ * observe — an unhandled chrome push targeting the application would change the URL and render
+ * nothing. The returned handler drives targets inside the base path through the application's
+ * own navigation (which also keeps its navigation guards in force) and leaves anything else to
+ * the host.
+ *
+ * The takeover still calls `proceed` before navigating: the host push keeps the host chrome's
+ * own location state (menu highlight, targets derived from the current path) in sync and
+ * preserves the source history entry; the application then renders by REPLACING that entry
+ * with the same URL, so history gains exactly one entry. Push-first is a deliberate trade-off:
+ * ordering the push after the application navigation would either destroy the source entry
+ * (replace) or duplicate the target (push), and gating it on the navigation committing loses
+ * the push when a navigation guard confirms later. The cost is that a guard cancelling the
+ * follow-up navigation leaves the pushed URL behind — which is why the guard owner restores
+ * the URL on cancel (see {@link IPluggableAppNavigateRef}).
+ *
+ * @alpha
+ */
+export declare function createHostNavigationTakeover(basePath: string, navigateRef: IPluggableAppNavigateRef): (request: IHostNavigationRequest) => boolean;
+
 /**
  * Wraps host telemetry callbacks so every `trackEvent` / `trackPageView` / `trackTiming` call also reports
  * the module's runtime metadata.
@@ -180,6 +206,17 @@ export declare interface IModuleTelemetryMetadata {
     moduleSdkVersion?: string;
 }
 
+/**
+ * The in-app route a host navigation target stands for, or undefined when the target leaves
+ * the application.
+ *
+ * @remarks
+ * Query and hash ride along with the path.
+ *
+ * @alpha
+ */
+export declare function inAppPath(url: string, basePath: string): string | undefined;
+
 /**
  * Props for {@link PlatformContextProvider}.
  *
@@ -229,6 +266,25 @@ export declare interface IPluggableAppEventsProviderProps extends PropsWithChild
     onEvent?: (event: IPluggableAppEvent) => void;
 }
 
+/**
+ * Mutable slot an application's router fills with its navigate function once it exists.
+ *
+ * @remarks
+ * The path handed to `navigate` is relative to the application's base path (starts with "/").
+ * The implementation must navigate with history REPLACE semantics: the takeover lets the host
+ * push first (see {@link createHostNavigationTakeover}), so the replace lands on the entry that
+ * push created and history gains exactly one entry, with the source entry preserved.
+ *
+ * An application whose navigation guard can cancel this navigation (an unsaved-changes blocker)
+ * is responsible for restoring the URL when the user cancels — the host push has already
+ * happened by then. gdc-reports' editor does this on its Stay choice.
+ *
+ * @alpha
+ */
+export declare interface IPluggableAppNavigateRef {
+    current: ((path: string) => void) | null;
+}
+
 /**
  * Props for {@link PluggableAppTelemetryProvider}.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gooddata/sdk-ui-pluggable-application",
-  "version": "11.55.0-alpha.3",
+  "version": "11.55.0-alpha.4",
   "description": "GoodData SDK React helpers for pluggable applications",
   "license": "MIT",
   "author": "GoodData Corporation",
@@ -24,12 +24,12 @@
     "react-intl": "7.1.11",
     "ts-invariant": "0.10.3",
     "tslib": "2.8.1",
-    "@gooddata/sdk-backend-base": "11.55.0-alpha.3",
-    "@gooddata/sdk-backend-tiger": "11.55.0-alpha.3",
-    "@gooddata/sdk-backend-spi": "11.55.0-alpha.3",
-    "@gooddata/sdk-model": "11.55.0-alpha.3",
-    "@gooddata/sdk-pluggable-application-model": "11.55.0-alpha.3",
-    "@gooddata/sdk-ui": "11.55.0-alpha.3"
+    "@gooddata/sdk-backend-base": "11.55.0-alpha.4",
+    "@gooddata/sdk-backend-spi": "11.55.0-alpha.4",
+    "@gooddata/sdk-backend-tiger": "11.55.0-alpha.4",
+    "@gooddata/sdk-model": "11.55.0-alpha.4",
+    "@gooddata/sdk-pluggable-application-model": "11.55.0-alpha.4",
+    "@gooddata/sdk-ui": "11.55.0-alpha.4"
   },
   "devDependencies": {
     "@microsoft/api-documenter": "7.30.10",
@@ -52,15 +52,15 @@
     "eslint-plugin-sonarjs": "3.0.6",
     "happy-dom": "20.9.0",
     "npm-run-all": "4.1.5",
-    "oxfmt": "0.52.0",
+    "oxfmt": "0.58.0",
     "oxlint": "1.57.0",
     "oxlint-tsgolint": "0.15.0",
     "react": "19.1.1",
     "react-dom": "19.1.1",
     "typescript": "5.9.3",
     "vitest": "4.1.8",
-    "@gooddata/eslint-config": "11.55.0-alpha.3",
-    "@gooddata/oxlint-config": "11.55.0-alpha.3"
+    "@gooddata/eslint-config": "11.55.0-alpha.4",
+    "@gooddata/oxlint-config": "11.55.0-alpha.4"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",