@salesforce-ui-embedding/internal-lightning-ui-embedding 2.3.0-rc.2 → 2.3.0-rc.3

package/dist/modules/lightning/uiEmbedding/uiEmbedding.js

@@ -3,6 +3,9 @@
  * For full license text, see the LICENSE.txt file in this package.
  */
 
+import { NavigationMixin } from "lightning/navigation";
+import LightningToast from "lightning/toast";
+import UiEmbeddingModal from "lightning/uiEmbeddingModal";
 import { api, LightningElement } from "lwc";
 
 import { buildBootstrapEnvelope, validateHeartbeat, validateShutdown } from "./utils/bootstrap";
@@ -11,6 +14,7 @@ import { isLightningDomainSameOriginEnabled } from "./utils/gater";
 import { HostBridge } from "./utils/host-bridge";
 import { HOST_INFO } from "./utils/host-info";
 import { createInstrumentation } from "./utils/instrumentation";
+import { StandardErrorCode } from "./utils/jsonrpc";
 import { createLogger } from "./utils/log";
 import { computeSandboxTokens } from "./utils/sandbox";
 import {
@@ -19,6 +23,7 @@ import {
     EVENTS_UNSUBSCRIBE_METHOD,
     HEARTBEAT_TYPE,
     HostLwcEvent,
+    JsonRpcHandlerError,
     RESIZE_METHOD,
     SHUTDOWN_TYPE,
     UI_STATE_CHANGED_METHOD,
@@ -51,7 +56,18 @@ function toCloneableDetail(detail) {
     return detail;
 }
 
-export default class Embedding extends LightningElement {
+/** `ui/display-modal` component spec of the built-in generic modal, the only spec the host opens. */
+const DEFAULT_MODAL_SPEC = "default";
+
+/**
+ * Modal config keys the host owns; dropped from guest `attributes` so a guest cannot set them. Documented on
+ * `ModalOptions.attributes` in the contract — keep the two in sync.
+ */
+const RESERVED_MODAL_KEYS = new Set(["size", "label", "description", "disableClose"]);
+
+// `NavigationMixin(LightningElement)` gives the host `this[NavigationMixin.Navigate](pageRef)`
+// so `ui/navigate-to` can drive real Lightning navigation.
+export default class Embedding extends NavigationMixin(LightningElement) {
     _iframe = null;
     _container = null;
     _frameShadow = null;
@@ -614,7 +630,8 @@ export default class Embedding extends LightningElement {
         // subscribe/unsubscribe registry, and the resize-hint notification; it
         // calls back into _composeUiState() for the snapshot returned on
         // subscribe, _redispatchEventFromEmbedding() for inbound
-        // `ui/events/dispatch`, and _handleResizeHint() for `ui/notifications/resize`.
+        // `ui/events/dispatch`, _handleResizeHint() for `ui/notifications/resize`, and
+        // _handleNavigateTo() / _handleDisplayModal() / _handleDisplayToast() for the view.* requests.
         this._bridge = new HostBridge(
             port,
             () => this._composeUiState(),
@@ -623,6 +640,77 @@ export default class Embedding extends LightningElement {
             (params) => this._handleSfEmbeddingError(params),
             (...args) => this._log(...args),
             this._instrumentation,
+            (params) => this._handleNavigateTo(params),
+            (params) => this._handleDisplayModal(params),
+            (params) => this._handleDisplayToast(params),
+        );
+    }
+
+    /** `ui/navigate-to` → lightning/navigation. Params are PageReference-shaped. */
+    _handleNavigateTo(opts) {
+        const navigate = this[NavigationMixin.Navigate];
+
+        navigate.call(this, {
+            type: opts.type,
+            attributes: opts.attributes ?? {},
+            ...(opts.state ? { state: opts.state } : {}),
+        });
+    }
+
+    /**
+     * `ui/display-modal` → lightning/modal. Resolves on user dismissal (indefinite class). Only the generic
+     * "default" modal is offered; any other spec is rejected with INVALID_PARAMS (§7.1).
+     */
+    async _handleDisplayModal(opts) {
+        if (opts.component !== DEFAULT_MODAL_SPEC) {
+            throw new JsonRpcHandlerError(
+                StandardErrorCode.INVALID_PARAMS,
+                `unregistered modal component: '${opts.component}'`,
+            );
+        }
+        // Guest attributes first so they cannot override the host-controlled modal config. Only
+        // defined values are passed: an explicit `undefined` would overwrite the modal's defaults
+        // (e.g. size 'medium').
+        const attributes = Object.fromEntries(
+            Object.entries(opts.attributes ?? {}).filter(([key]) => !RESERVED_MODAL_KEYS.has(key)),
+        );
+        const config = {
+            ...attributes,
+            ...(opts.size !== undefined ? { size: opts.size } : {}),
+            ...(opts.label !== undefined ? { label: opts.label, description: opts.label } : {}),
+        };
+        let closeResult;
+        try {
+            closeResult = await UiEmbeddingModal.open(config);
+        } catch (err) {
+            // The overlay container rejects with a bare `undefined` when it won't open another
+            // overlay (per-type limit reached); surface a real error instead of an empty rejection.
+            if (err instanceof Error) throw err;
+            // Keep any other rejection value as the cause so the original failure stays diagnosable.
+            throw new JsonRpcHandlerError(StandardErrorCode.INTERNAL_ERROR, "host could not open the modal", {
+                cause: err,
+            });
+        }
+        // A modal may close with an LWC proxy, which fails structured-clone; the transport
+        // swallows that send error, so the guest's indefinite request would never settle.
+        return { closeResult: toCloneableDetail(closeResult) };
+    }
+
+    /**
+     * `ui/display-toast` → lightning/toast. Fire-and-forget: response means queued/displayed, NOT dismissed
+     * (§7.1). `source` is the host element so the toast anchors to this instance.
+     */
+    _handleDisplayToast(opts) {
+        // `lightning/toast` requires `label`, and (unlike the legacy ShowToastEvent path) does not
+        // promote `message` to it, so a title-less toast would fail validation. Promote it here.
+        LightningToast.show(
+            {
+                label: opts.title ?? opts.message,
+                message: opts.title ? opts.message : undefined,
+                variant: opts.variant,
+                mode: opts.mode,
+            },
+            this,
         );
     }
 

package/dist/modules/lightning/uiEmbedding/utils/host-bridge.js

@@ -15,6 +15,8 @@ import { MessageChannelTransport, StandardErrorCode } from "./jsonrpc";
 import { createLogger } from "./log";
 import { BridgeClient, JsonRpcRouter } from "./request-router";
 import {
+    DISPLAY_MODAL_METHOD,
+    DISPLAY_TOAST_METHOD,
     EMBEDDING_INITIALIZED_METHOD,
     ERROR_METHOD,
     EVENTS_DISPATCH_METHOD,
@@ -22,10 +24,12 @@ import {
     EVENTS_UNSUBSCRIBE_METHOD,
     HOST_INITIALIZED_METHOD,
     JsonRpcHandlerError,
+    NAVIGATE_TO_METHOD,
     RESIZE_METHOD,
     UI_STATE_SUBSCRIBE_METHOD,
     UI_STATE_UNSUBSCRIBE_METHOD,
 } from "./sf-embedding-contract";
+import { isHttpUrl } from "./url";
 
 export class HostBridge extends JsonRpcRouter {
     // Active UiState wire subscription. Only one is permitted at a time; a second
@@ -48,6 +52,9 @@ export class HostBridge extends JsonRpcRouter {
         onSfEmbeddingError,
         log = createLogger("[lightning-ui-embedding:host-bridge]", () => false),
         instrumentation,
+        onNavigateTo,
+        onDisplayModal,
+        onDisplayToast,
     ) {
         // Wrap the transferred port in the shared transport; the BridgeClient
         // subscribes to it (lazily starting the port), and the router claims
@@ -131,6 +138,77 @@ export class HostBridge extends JsonRpcRouter {
             log("embedding error received:", params);
             onSfEmbeddingError(params);
         });
+
+        // view.* UI-action methods. Each is registered only when the component supplies its
+        // callback; when absent the router returns METHOD_NOT_FOUND (the host simply doesn't
+        // offer that surface). Capability gating (§6) will layer on top of this — a later story
+        // wires CAPABILITY_NOT_ALLOWED.
+
+        // Navigate request; component drives lightning/navigation. Result: void.
+        if (onNavigateTo) {
+            this.onRequest(NAVIGATE_TO_METHOD, async (params) => {
+                if (!params || typeof params.type !== "string" || params.type.length === 0) {
+                    this._instrumentation?.incrementCounter("sfembedding.view.navigate_rejected", 1, true, {
+                        reason: "invalid_params",
+                    });
+                    throw new JsonRpcHandlerError(
+                        StandardErrorCode.INVALID_PARAMS,
+                        "navigate-to requires a 'type' string",
+                    );
+                }
+                if (params.type === "standard__webPage" && !isHttpUrl(params.attributes?.url)) {
+                    this._instrumentation?.incrementCounter("sfembedding.view.navigate_rejected", 1, true, {
+                        reason: "invalid_url",
+                    });
+                    throw new JsonRpcHandlerError(
+                        StandardErrorCode.INVALID_PARAMS,
+                        "navigate-to standard__webPage requires an http(s) or relative 'url'",
+                    );
+                }
+                await onNavigateTo(params);
+                this._instrumentation?.incrementCounter("sfembedding.view.navigated", 1, false);
+            });
+        }
+
+        // Modal request; component opens lightning/modal. Indefinite class: resolves on user
+        // dismissal. Unregistered component specs are rejected with INVALID_PARAMS (§7.1) — the
+        // component throws for them.
+        if (onDisplayModal) {
+            this.onRequest(DISPLAY_MODAL_METHOD, async (params) => {
+                if (!params || typeof params.component !== "string" || params.component.length === 0) {
+                    this._instrumentation?.incrementCounter("sfembedding.view.modal_rejected", 1, true, {
+                        reason: "invalid_params",
+                    });
+                    throw new JsonRpcHandlerError(
+                        StandardErrorCode.INVALID_PARAMS,
+                        "display-modal requires a 'component' spec",
+                    );
+                }
+                this._instrumentation?.incrementCounter("sfembedding.view.modal_opened", 1, false);
+                const result = await onDisplayModal(params);
+                this._instrumentation?.incrementCounter("sfembedding.view.modal_closed", 1, false);
+                return result;
+            });
+        }
+
+        // Toast request; component shows lightning/toast. Result: void. The response means
+        // "queued/displayed", NOT "dismissed" (§7.1) — mirrors native lightning/toast's
+        // fire-and-forget contract.
+        if (onDisplayToast) {
+            this.onRequest(DISPLAY_TOAST_METHOD, async (params) => {
+                if (!params || typeof params.message !== "string" || params.message.length === 0) {
+                    this._instrumentation?.incrementCounter("sfembedding.view.toast_rejected", 1, true, {
+                        reason: "invalid_params",
+                    });
+                    throw new JsonRpcHandlerError(
+                        StandardErrorCode.INVALID_PARAMS,
+                        "display-toast requires a 'message'",
+                    );
+                }
+                await onDisplayToast(params);
+                this._instrumentation?.incrementCounter("sfembedding.view.toast_shown", 1, false);
+            });
+        }
     }
 
     /** The active UiState wire subscription id, or null when none is active. */

package/dist/modules/lightning/uiEmbedding/utils/host-info.js

@@ -3,11 +3,11 @@
  * For full license text, see the LICENSE.txt file in this package.
  */
 
-// `"2.3.0-rc.2"` is a repo-wide ambient declared in /types/globals.d.ts;
+// `"2.3.0-rc.3"` is a repo-wide ambient declared in /types/globals.d.ts;
 // build.mjs substitutes the literal at build time, jest globals supply a test value.
 
 /** Identity emitted on `ui/notifications/host-initialized`. */
 export const HOST_INFO = {
     name: "lightning-ui-embedding",
-    version: "2.3.0-rc.2",
+    version: "2.3.0-rc.3",
 };

package/dist/modules/lightning/uiEmbedding/utils/sf-embedding-contract.js

@@ -40,8 +40,8 @@ const HOST_META_DATA_PARAM = "hostMetaData";
 /** Throw from a request handler to surface a specific JSON-RPC error code. */
 class JsonRpcHandlerError extends Error {
 
-  constructor(code, message) {
-    super(message);_defineProperty(this, "code", void 0);
+  constructor(code, message, options) {
+    super(message, options);_defineProperty(this, "code", void 0);
     this.code = code;
     this.name = "JsonRpcHandlerError";
   }
@@ -55,12 +55,24 @@ const EMBEDDING_INITIALIZED_METHOD = "ui/notifications/embedding-initialized";
 /** Iframe-side error notification. Fire-and-forget, non-PII observability signal. */
 const ERROR_METHOD = "ui/notifications/error";
 
+// Host modal: embedding → host request that backs the guest's `lightning/modal` import (§7.1 / §7.2).
+/** `ui/display-modal` — backs `lightning/modal`. Capability gate: `view.displayModal`. */
+const DISPLAY_MODAL_METHOD = "ui/display-modal";
+
+// Host navigation: embedding → host request that backs the guest's `lightning/navigation` import (§7.1 / §7.2).
+/** `ui/navigate-to` — backs `lightning/navigation`. Capability gate: `view.navigateTo`. */
+const NAVIGATE_TO_METHOD = "ui/navigate-to";
+
 // Resize hint channel: embedding → host, fire-and-forget. CSS pixels.
 const RESIZE_METHOD = "ui/notifications/resize";
 
+// Host toast: embedding → host request that backs the guest's `lightning/toast` import (§7.1 / §7.2).
+/** `ui/display-toast` — backs `lightning/toast`. Capability gate: `view.displayToast`. */
+const DISPLAY_TOAST_METHOD = "ui/display-toast";
+
 // UI-state subscription axis. Snapshot in subscribe response; full-replacement change pushes.
 const UI_STATE_SUBSCRIBE_METHOD = "ui/subscribe/ui-state";
 const UI_STATE_UNSUBSCRIBE_METHOD = "ui/unsubscribe/ui-state";
 const UI_STATE_CHANGED_METHOD = "ui/notifications/ui-state-changed";
 
-export { BOOTSTRAP_ENVELOPE_TYPE, EMBEDDING_INITIALIZED_METHOD, ERROR_METHOD, EVENTS_DISPATCH_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD, HEARTBEAT_TYPE, HOST_INITIALIZED_METHOD, HOST_META_DATA_PARAM, HostLwcEvent, JsonRpcHandlerError, PROTOCOL_NAME, RESIZE_METHOD, SHUTDOWN_TYPE, UI_STATE_CHANGED_METHOD, UI_STATE_SUBSCRIBE_METHOD, UI_STATE_UNSUBSCRIBE_METHOD };
+export { BOOTSTRAP_ENVELOPE_TYPE, DISPLAY_MODAL_METHOD, DISPLAY_TOAST_METHOD, EMBEDDING_INITIALIZED_METHOD, ERROR_METHOD, EVENTS_DISPATCH_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD, HEARTBEAT_TYPE, HOST_INITIALIZED_METHOD, HOST_META_DATA_PARAM, HostLwcEvent, JsonRpcHandlerError, NAVIGATE_TO_METHOD, PROTOCOL_NAME, RESIZE_METHOD, SHUTDOWN_TYPE, UI_STATE_CHANGED_METHOD, UI_STATE_SUBSCRIBE_METHOD, UI_STATE_UNSUBSCRIBE_METHOD };

package/dist/modules/lightning/uiEmbedding/utils/url.js

@@ -28,6 +28,20 @@ export function isLightningDomain(origin) {
     );
 }
 
+/**
+ * True when `url` is a string that resolves (against the host page) to an http(s) URL. Rejects
+ * `javascript:`, `data:` and other schemes a guest could otherwise hand to host navigation.
+ */
+export function isHttpUrl(url) {
+    if (typeof url !== "string" || url.length === 0) return false;
+    try {
+        const { protocol } = new URL(url, window.location.href);
+        return protocol === "https:" || protocol === "http:";
+    } catch {
+        return false;
+    }
+}
+
 export function appendHostMetaData(src, instanceId, hostAppOrigin) {
     const url = new URL(src);
     const meta = { instanceId, hostAppOrigin };

package/dist/modules/lightning/uiEmbeddingModal/uiEmbeddingModal.html

@@ -0,0 +1,14 @@
+<!--
+  Copyright 2026 Salesforce, Inc. All rights reserved.
+  For full license text, see the LICENSE.txt file in this package.
+-->
+
+<template>
+    <lightning-modal-header label={headerLabel}></lightning-modal-header>
+    <lightning-modal-body>
+        <p class="slds-p-around_small">{content}</p>
+    </lightning-modal-body>
+    <lightning-modal-footer>
+        <lightning-button label="Close" variant="brand" onclick={handleClose}></lightning-button>
+    </lightning-modal-footer>
+</template>

package/dist/modules/lightning/uiEmbeddingModal/uiEmbeddingModal.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2026 Salesforce, Inc. All rights reserved.
+ * For full license text, see the LICENSE.txt file in this package.
+ */
+
+import LightningModal from "lightning/modal";
+import { api } from "lwc";
+
+const DEFAULT_HEADING = "Message";
+
+/**
+ * Generic modal `<lightning-ui-embedding>` registers by default, so a guest's `displayModal` works without the
+ * host registering a component. It shows guest-supplied text only (rendered as text, never as markup) and
+ * closes without a result; richer modals are registered by the host.
+ */
+export default class UiEmbeddingModal extends LightningModal {
+    @api heading = "";
+    @api content = "";
+
+    /** Header text; never empty, so the dialog always has an accessible name. */
+    get headerLabel() {
+        return this.heading || this.label || DEFAULT_HEADING;
+    }
+
+    handleClose() {
+        this.close();
+    }
+}

package/dist/modules/lightning/uiEmbeddingModal/uiEmbeddingModal.js-meta.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2026 Salesforce, Inc. All rights reserved.
+  For full license text, see the LICENSE.txt file in this package.
+-->
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <isExposed>false</isExposed>
+    <minApiVersion>62.0</minApiVersion>
+</LightningComponentBundle>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforce-ui-embedding/internal-lightning-ui-embedding",
-    "version": "2.3.0-rc.2",
+    "version": "2.3.0-rc.3",
     "private": false,
     "description": "Lightning Base Component (LWC) host for sf-embedding-protocol iframes",
     "license": "SEE LICENSE IN LICENSE.txt",
@@ -22,8 +22,8 @@
     },
     "devDependencies": {
         "@salesforce/jsonrpc": "^10.12.3",
-        "@salesforce/sf-embedding-contract": "2.3.0-rc.2",
-        "utils": "2.3.0-rc.2"
+        "@salesforce/sf-embedding-contract": "2.3.0-rc.3",
+        "utils": "2.3.0-rc.3"
     },
     "sideEffects": false,
     "publishConfig": {