@canva/platform 1.0.1 → 1.1.0

package/index.d.ts

@@ -1,9 +1,191 @@
+/**
+ * @public
+ * An API for interacting with the App Process.
+ */
+export declare interface AppProcess {
+  readonly current: CurrentAppProcess;
+  /**
+   * @public
+   * Request the termination of an app process.
+   * @param target - The id of the app process to close.
+   * @param params - A parameters object passed to all callback functions registered via registerOnBeforeClose API for the provided AppProcessId.
+   * In addition to the required 'reason' field, app can choose to pass any structured data via params.
+   * {@link https://html.spec.whatwg.org/multipage/structured-data.html#safe-passing-of-structured-data | safe passing of structured data}
+   * @remarks
+   * A successful invocation indicates the platform has begun shutdown following procedure for the target AppProcessId, which:
+   * 1. Transitions process state to `CLOSING`, triggering all registered state change callbacks.
+   * 2. Invokes all registered onBeforeClose callbacks.
+   * 3. Waits for the process to close.
+   * 4. Transitions process state to `CLOSED`, triggering all registered state change callbacks.
+   * @remarks
+   * Once initiated, the closing process is irreversible and the process will NOT receive any events or messages from other processes.
+   */
+  requestClose<T extends CloseParams>(
+    target: AppProcessId,
+    params: T
+  ): Promise<void>;
+  /**
+   * @public
+   * Registers a callback to be executed when the state of the specified app process changes.
+   * @param target - The id of the app process for which to register the callback.
+   * @param callback - Callback function triggered on state change
+   * @returns a disposer function to unsubscribe the callback.
+   */
+  registerOnStateChange(
+    target: AppProcessId,
+    callback: (opts: { state: ProcessState }) => void
+  ): () => Promise<void>;
+  /**
+   * Registers a handler to receive messages sent from other app processes.
+   * @param callback - Handler function to receive incoming messages.
+   * @returns a disposer function to unsubscribe the handler.
+   */
+  registerOnMessage(
+    callback: (
+      sender: {
+        appProcessId: AppProcessId;
+        surface: AppSurface;
+      },
+      message: any
+    ) => void
+  ): () => Promise<void>;
+  /**
+   * Broadcasts a message to all other running app processes which share the caller's AppId.
+   * @param message - app-defined message to be broadcast. message needs to be structured data.
+   */
+  broadcastMessage(message: any): void;
+}
+
+/**
+ * An alias for the AppProcess interface for interacting with the App Process.
+ * @public
+ */
+export declare const appProcess: AppProcess;
+
+/**
+ * @public
+ * The unique identifier for an app process.
+ */
+export declare type AppProcessId = string & {
+  __appProcessId: never;
+};
+
+/**
+ * @public
+ * Information about an app process.
+ */
+export declare type AppProcessInfo<T> = {
+  /**
+   * The surface on which the app is running.
+   */
+  surface: AppSurface;
+  /**
+   * The unique identifier of the app process.
+   */
+  processId: AppProcessId;
+  /**
+   * The parameters provided to the app at the time of its process launch.
+   */
+  launchParams?: T;
+};
+
+/**
+ * @public
+ * The types of surfaces that can run an app process.
+ */
+export declare type AppSurface =
+  /**
+   * The object panel on the left side of the editing UI.
+   */
+  | "object_panel"
+  /**
+   * The overlay surface on top of a selected image in the design.
+   */
+  | "selected_image_overlay";
+
+/**
+ * @public
+ * The parameters specified when closing an app process.
+ * @remarks
+ * CloseParams are passed on to the callback function registered for handling the termination of an app process,
+ * and provide additional context for ending the process.
+ * For example, Apps should persist unsaved changes when the close reason is 'completed'.
+ */
+export declare type CloseParams = {
+  reason: CloseReason;
+};
+
+/**
+ * @public
+ * The reasons why an app process is closed.
+ */
+export declare type CloseReason =
+  /**
+   * Indicates the workflow is completed, for example, when user clicks a 'Save and Close' in the App.
+   * Any unsaved changes should be saved before closing.
+   */
+  | "completed"
+  /**
+   * Indicates user has aborted the workflow, for example, when user clicked the 'cancel' button in the App.
+   * App should be closed without saving any current changes.
+   */
+  | "aborted";
+
+/**
+ * @public
+ * Represents and exposes functionality specific to the currently running app process.
+ */
+export declare type CurrentAppProcess = {
+  /**
+   * @public
+   * Retrieves information about the current app process.
+   */
+  getInfo<T extends any>(): AppProcessInfo<T>;
+  /**
+   * @public
+   * Requests the current app process be closed.
+   * @param params - A parameters object passed to all callback functions registered via registerOnBeforeClose API for the current process.
+   * In addition to the required 'reason' field, app can choose to pass any structured data via params.
+   * @remarks
+   * A successful invocation indicates the platform has begun shutdown following procedure for the current process, which:
+   * 1. Transitions process state to `CLOSING`, triggering all registered state change callbacks.
+   * 2. Invokes all registered onBeforeClose callbacks.
+   * 3. Waits for the process to close.
+   * 4. Transitions process state to `CLOSED`, triggering all registered state change callbacks.
+   * @remarks
+   * Once initiated, the closing process is irreversible and the process will NOT receive any events or messages from other processes.
+   */
+  requestClose<T extends CloseParams>(params: T): Promise<void>;
+  /**
+   * @public
+   * Registers a callback to be executed when the current app process is about to close.
+   * @remarks Only allow registering one callback.
+   * Subsequential invokes of the API will override the existing callback.
+   * The process remains open until the callback resolve or a timeout occurs.
+   * @param callback -  The callback function to be invoked before closure.
+   * @returns a disposer function to unsubscribe the callback.
+   * @remarks Complete execution of the callback is not guaranteed. Certain user actions (e.g. closing tabs, top level navigation) may terminate app processes prematurely. Consider these callbacks **best effort only.**
+   */
+  setOnDispose<T extends CloseParams>(
+    callback: OnDisposeCallback<T>
+  ): () => Promise<void>;
+};
+
 /**
  * @public
  * Returns information about the platform on which the app is running.
  */
 export declare function getPlatformInfo(): PlatformInfo;
 
+/**
+ * @public
+ * The type of a callback that is invoked when an app process is being closed.
+ * @returns a promise.
+ */
+export declare type OnDisposeCallback<T extends CloseParams> = (
+  opts: T
+) => Promise<void>;
+
 /**
  * @public
  * The result of opening an external URL when a user chooses to not navigate away from Canva.
@@ -72,6 +254,29 @@ export declare type PlatformInfo = {
   canAcceptPayments: boolean;
 };
 
+/**
+ * @public
+ * The states are an app process.
+ */
+export declare type ProcessState =
+  /**
+   * The app process is in the process of opening.
+   */
+  | "opening"
+  /**
+   * The app process is active and visible to the user on its designated surface.
+   */
+  | "open"
+  /**
+   * The app process is in the process of closing.
+   * At this state, the process becomes non-interactive and won't receive any events and messages from other processes.
+   */
+  | "closing"
+  /**
+   * The app process has been terminated and is no longer running.
+   */
+  | "closed";
+
 /**
  * @public
  * Opens an external URL.

package/lib/cjs/sdk/platform/index.js

@@ -1,17 +1,19 @@
+// Copyright 2023 Canva Inc. All Rights Reserved.
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./public"), exports);
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./public"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/lib/cjs/sdk/platform/public.js

@@ -1,25 +1,30 @@
+// Copyright 2023 Canva Inc. All Rights Reserved.
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPlatformInfo = exports.requestOpenExternalUrl = void 0;
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    appProcess: function() {
+        return appProcess;
+    },
+    requestOpenExternalUrl: function() {
+        return requestOpenExternalUrl;
+    },
+    getPlatformInfo: function() {
+        return getPlatformInfo;
+    }
+});
 const { canva } = window;
-/**
- * @public
- * Opens an external URL.
- *
- * @remarks
- * The URL is opened natively, such as in a new browser tab on desktop or in a browser sheet on mobile.
- *
- * In some browsers, the user must enable popup permissions before any URL can be opened.
- */
+const appProcess = canva.appProcess;
 function requestOpenExternalUrl(request) {
     return canva.platform.requestOpenExternalUrl(request);
 }
-exports.requestOpenExternalUrl = requestOpenExternalUrl;
-/**
- * @public
- * Returns information about the platform on which the app is running.
- */
 function getPlatformInfo() {
     return canva.platform.getPlatformInfo();
 }
-exports.getPlatformInfo = getPlatformInfo;

package/lib/esm/sdk/platform/index.js

@@ -1 +1,2 @@
+// Copyright 2023 Canva Inc. All Rights Reserved.
 export * from './public';

package/lib/esm/sdk/platform/public.js

@@ -1,4 +1,9 @@
+// Copyright 2023 Canva Inc. All Rights Reserved.
 const { canva } = window;
+/**
+ * An alias for the AppProcess interface for interacting with the App Process.
+ * @public
+ */ export const appProcess = canva.appProcess;
 /**
  * @public
  * Opens an external URL.
@@ -7,14 +12,12 @@ const { canva } = window;
  * The URL is opened natively, such as in a new browser tab on desktop or in a browser sheet on mobile.
  *
  * In some browsers, the user must enable popup permissions before any URL can be opened.
- */
-export function requestOpenExternalUrl(request) {
+ */ export function requestOpenExternalUrl(request) {
     return canva.platform.requestOpenExternalUrl(request);
 }
 /**
  * @public
  * Returns information about the platform on which the app is running.
- */
-export function getPlatformInfo() {
+ */ export function getPlatformInfo() {
     return canva.platform.getPlatformInfo();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canva/platform",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "The Canva Apps SDK app platform library",
   "author": "Canva Pty Ltd.",
   "license": "SEE LICENSE IN LICENSE.md FILE",