@salesforce/sdk-view 1.133.1 → 1.134.0

package/README.md

@@ -1,38 +1,256 @@
 # @salesforce/sdk-view
 
-The View SDK provides a unified interface for visual interactions and user feedback across different Salesforce application surfaces. It handles notifications, alerts, and modal dialogs, automatically adapting to the hosting environment.
+View SDK for displaying notifications, modals, and managing visual state across Salesforce application surfaces. Provides a unified API for alerts, toasts, modal dialogs, theming, and viewport resizing — automatically adapting to the host environment.
 
-## Purpose
+## Installation
 
-The View SDK manages interactions that affect the visual shell or user feedback, independent of business data. It abstracts away the complexity of different hosting environments, allowing applications to deliver consistent user experiences whether running in a UI Bundle, embedded iframe, or conversational interface.
+```sh
+npm install @salesforce/sdk-view
+```
 
-## Key Capabilities
+## Quick Start
 
-- **Notifications**: Display alerts, toasts, and confirmations appropriate to the hosting environment
-- **Modals**: Request the host to overlay modal dialogs, even within iframe constraints
-- **Surface Adaptation**: Automatically detects and adapts to the runtime environment
+```ts
+import { createViewSDK } from "@salesforce/sdk-view";
 
-## Supported Surfaces
+const sdk = await createViewSDK();
 
-The View SDK supports the following application surfaces:
+// Show a success toast
+await sdk.displayToast?.({ message: "Record saved", level: "success" });
 
-- **UI Bundles**: Standard Salesforce UI Bundles with native browser capabilities
-- **Micro Frontends**: Embedded iframe applications that communicate through the host bridge
-- **OpenAI ChatGPT Apps**: Conversational interfaces integrated with ChatGPT
+// Check the host theme
+const theme = sdk.getTheme?.();
+if (theme?.mode === "dark") {
+  document.body.classList.add("dark");
+}
+```
 
-## Architecture
+## Initialization
+
+### Factory (Async)
+
+`createViewSDK` detects the runtime surface and returns the appropriate implementation. Each call creates a new instance.
+
+```ts
+const sdk = await createViewSDK();
+```
+
+### Singleton (Recommended)
+
+`getViewSDK` caches the instance so all callers share one SDK. The Promise itself is cached, preventing race conditions from concurrent callers.
+
+```ts
+import { getViewSDK } from "@salesforce/sdk-view";
+
+const sdk = await getViewSDK();
+```
+
+### Synchronous Access
+
+After `getViewSDK()` has resolved, you can access the instance synchronously. Returns `null` if not yet initialized.
+
+```ts
+import { getViewSDKSync } from "@salesforce/sdk-view";
+
+const sdk = getViewSDKSync(); // ViewSDK | null
+```
+
+### Options
+
+```ts
+import { Surface } from "@salesforce/sdk-core";
+
+const sdk = await createViewSDK({
+  // Force a specific surface (skip auto-detection)
+  surface: Surface.MCPApps,
+  // MCP Apps session options
+  mcpApps: {
+    appIdentity: { name: "my-app" },
+    handshakeTimeout: 5000,
+  },
+});
+```
+
+### Reset (Testing)
+
+```ts
+import { resetViewSDK } from "@salesforce/sdk-view";
+
+resetViewSDK(); // Clears cached singleton; next getViewSDK() creates fresh instance
+```
+
+## API Reference
+
+All `ViewSDK` methods are optional — availability depends on the runtime surface. Always use optional chaining (`?.`) when calling them.
+
+### displayAlert
+
+Display a modal notification that requires user acknowledgment.
+
+```ts
+await sdk.displayAlert?.({
+  message: "Please save your work before continuing",
+  level: "warning",
+});
+```
+
+| Param     | Type           | Default  | Description                                                   |
+| --------- | -------------- | -------- | ------------------------------------------------------------- |
+| `message` | `string`       | —        | Message text to display                                       |
+| `level`   | `MessageLevel` | `"info"` | Severity: `"info"` \| `"success"` \| `"warning"` \| `"error"` |
+
+### displayToast
+
+Display a non-blocking notification that auto-dismisses.
+
+```ts
+await sdk.displayToast?.({
+  message: "File uploaded successfully",
+  level: "success",
+});
+```
+
+Same parameters as `displayAlert`.
+
+### displayModal
+
+Display a custom HTML dialog. OpenAI surface only (MCP Apps not yet implemented).
+
+```ts
+await sdk.displayModal?.({
+  componentReference: "ui://widget/settings.html",
+  params: { userId: "123", mode: "edit" },
+});
+```
+
+| Param                | Type                      | Description                                            |
+| -------------------- | ------------------------- | ------------------------------------------------------ |
+| `componentReference` | `string`                  | URI of the HTML template (`"ui://widget/[name].html"`) |
+| `params`             | `Record<string, unknown>` | Optional parameters passed to the modal                |
+
+On OpenAI, params are accessible in the modal via `window.openai.view.params`.
 
-The View SDK is part of the Salesforce Platform SDK ecosystem and works alongside other domain-specific SDKs:
+### getTheme
 
-- **@salesforce/sdk-core**: Provides runtime detection and initialization
-- **@salesforce/sdk-data**: Unified data access layer
-- **@salesforce/sdk-chat**: Conversational flow participation
+Get the current theme mode from the host.
+
+```ts
+const theme = sdk.getTheme?.();
+if (theme) {
+  console.log(theme.mode); // "light" | "dark"
+}
+```
+
+Returns `Theme | null`. The `Theme` type is `{ mode: ThemeMode }` where `ThemeMode = "light" | "dark"`.
+
+### resize
+
+Resize the widget viewport. MCP Apps only. Accepts pixel values as strings.
+
+```ts
+await sdk.resize?.("800px", "600px");
+await sdk.resize?.("1024", "768"); // unitless = pixels
+```
+
+| Param    | Type     | Description                                                    |
+| -------- | -------- | -------------------------------------------------------------- |
+| `width`  | `string` | Width in pixels (`"800px"` or `"800"`). Empty string to omit.  |
+| `height` | `string` | Height in pixels (`"600px"` or `"600"`). Empty string to omit. |
+
+Only pixel values are accepted. Percentages, `rem`, `em`, `vw/vh`, `auto`, and negative values are rejected.
+
+### navigateTo
+
+Navigate to a URL within the host environment.
+
+```ts
+await sdk.navigateTo?.("/dashboard");
+```
+
+### markDirtyState / clearDirtyState
+
+Notify the host about unsaved changes. The host may show a visual indicator or prompt before closing.
+
+```ts
+// User edited a form
+await sdk.markDirtyState?.();
+
+// After saving
+await sdk.clearDirtyState?.();
+```
+
+### dispatchEvent
+
+Send a custom event with data to the host.
+
+```ts
+await sdk.dispatchEvent?.("user-action", {
+  action: "click",
+  buttonId: "submit",
+});
+```
+
+### getUiProps
+
+Get host-provided UI properties and subscribe to changes.
+
+```ts
+const uiProps = sdk.getUiProps?.();
+
+const initialProps = await uiProps.props;
+uiProps.subscribe((newProps) => {
+  // Update UI based on new props
+});
+```
+
+## Surface Capabilities
+
+Not all methods are available on every surface. Use `getSurfaceCapabilities` from `@salesforce/sdk-core` to check at runtime, or refer to this matrix:
+
+| Method         | MCP Apps | OpenAI | Salesforce ACC |
+| -------------- | -------- | ------ | -------------- |
+| `displayAlert` | Yes      | Yes    | Yes            |
+| `displayToast` | Yes      | Yes    | Yes            |
+| `displayModal` | No       | Yes    | No             |
+| `getTheme`     | Yes      | Yes    | Yes            |
+| `resize`       | Yes      | No     | No             |
+
+WebApp and Mosaic surfaces return an empty object with no methods.
+
+```ts
+import { getSurface, getSurfaceCapabilities } from "@salesforce/sdk-core";
+
+const caps = getSurfaceCapabilities(getSurface());
+if (caps.resize) {
+  await sdk.resize?.("800px", "600px");
+}
+```
+
+## Exported Types
+
+```ts
+import type {
+  ViewSDK,
+  AlertOptions,
+  ToastOptions,
+  ModalOptions,
+  Theme,
+  ThemeMode,
+  SDKOptions,
+} from "@salesforce/sdk-view";
+
+import type { ViewSDKOptions } from "@salesforce/sdk-view";
+```
+
+## Architecture
 
-## Status
+The View SDK is part of the Salesforce Platform SDK ecosystem:
 
-**Status:** Experimental (Private Package)
+- **@salesforce/sdk-core** — Surface detection, `McpAppsSession` singleton, shared interfaces
+- **@salesforce/sdk-chat** — Conversational flow participation (messages, tools, resources)
+- **@salesforce/sdk-view** — Visual interactions (notifications, modals, theming, resize)
 
-This package is currently marked as private and intended for internal use within the Salesforce UI Bundles monorepo.
+Both `sdk-chat` and `sdk-view` share a single `McpAppsSession` transport when running on MCP Apps, so the SEP-1865 handshake only happens once regardless of initialization order.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sdk-view",
-  "version": "1.133.1",
+  "version": "1.134.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@salesforce/sdk-core": "^1.133.1"
+    "@salesforce/sdk-core": "^1.134.0"
   },
   "devDependencies": {
     "vite": "^7.3.1",