@openfin/core 33.76.27 → 33.76.36

package/src/api/platform/Instance.d.ts

@@ -8,8 +8,8 @@ type LayoutModule = OpenFin.Fin['Platform']['Layout'];
  *
  * Enables taking snapshots of itself and applyi
  * ng them to restore a previous configuration
- * as well as listen to <a href="tutorial-Platform.EventEmitter.html">platform events</a>.
- * @namespace
+ * as well as listen to {@link OpenFin.PlatformEvents platform events}.
+ *
  */
 export declare class Platform extends EmitterBase<OpenFin.PlatformEvent> {
     #private;
@@ -17,52 +17,293 @@ export declare class Platform extends EmitterBase<OpenFin.PlatformEvent> {
     private _channel;
     Application: OpenFin.Application;
     identity: OpenFin.ApplicationIdentity;
+    /**
+     * @internal
+     */
     constructor(identity: OpenFin.ApplicationIdentity, channel: Channel);
     getClient: (identity?: OpenFin.ApplicationIdentity) => Promise<ChannelClient>;
     /**
      * Creates a new view and attaches it to a specified target window.
-     * @param { View~options } viewOptions View creation options
-     * @param { Identity } [target] The window to which the new view is to be attached. If no target, create a view in a new window.
-     * @param { Identity } [targetView] If provided, the new view will be added to the same tabstrip as targetView.
-     * @return { Promise<View> }
-     * @tutorial Platform.createView
+     * @param viewOptions View creation options
+     * @param target The window to which the new view is to be attached. If no target, create a view in a new window.
+     * @param targetView If provided, the new view will be added to the same tabstrip as targetView.
+     *
+     * @remarks If the view already exists, will reparent the view to the new target. You do not need to set a name for a View.
+     * Views that are not passed a name get a randomly generated one.
+     *
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const platform = fin.Platform.getCurrentSync();
+     *
+     * platform.createView({
+     *     name: 'test_view',
+     *     url: 'https://developers.openfin.co/docs/platform-api'
+     * }, windowIdentity).then(console.log);
+     * ```
+     *
+     * Reparenting a view:
+     * ```js
+     * let windowIdentity;
+     * if (fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * let platform = fin.Platform.getCurrentSync();
+     * let viewOptions = {
+     *     name: 'example_view',
+     *     url: 'https://example.com'
+     * };
+     * // a new view will now show in the current window
+     * await platform.createView(viewOptions, windowIdentity);
+     *
+     * const view = fin.View.wrapSync({ uuid: windowIdentity.uuid, name: 'yahoo_view' });
+     * // reparent `example_view` when a view in the new window is shown
+     * view.on('shown', async () => {
+     *     let viewIdentity = { uuid: windowIdentity.uuid, name: 'example_view'};
+     *     let target = {uuid: windowIdentity.uuid, name: 'test_win'};
+     *     platform.createView(viewOptions, target);
+     * });
+     *
+     * // create a new window
+     * await platform.createWindow({
+     *     name: "test_win",
+     *     layout: {
+     *         content: [
+     *             {
+     *                 type: 'stack',
+     *                 content: [
+     *                     {
+     *                         type: 'component',
+     *                         componentName: 'view',
+     *                         componentState: {
+     *                             name: 'yahoo_view',
+     *                             url: 'https://yahoo.com'
+     *                         }
+     *                     }
+     *                 ]
+     *             }
+     *         ]
+     *     }
+     * }).then(console.log);
+     * ```
      */
     createView(viewOptions: OpenFin.PlatformViewCreationOptions, target?: OpenFin.CreateViewTarget, targetView?: OpenFin.Identity): Promise<View>;
     /**
      * Creates a new Window.
-     * @param { Window~options } options Window creation options
-     * @return { Promise<_Window> }
-     * @tutorial Platform.createWindow
+     * @param options Window creation options
+     *
+     * @remarks There are two Window types at your disposal while using OpenFin Platforms - Default Window and Custom Window.
+     *
+     * The Default Window uses the standard OpenFin Window UI. It contains the standard close, maximize and minimize buttons,
+     * and will automatically render the Window's layout if one is specified.
+     *
+     * For deeper customization, you can bring your own Window code into a Platform. This is called a Custom Window.
+     *
+     * @example
+     *
+     *
+     * The example below will create a Default Window which uses OpenFin default Window UI.<br>
+     * The Window contains two Views in a stack Layout:
+     *
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     * platform.createWindow({
+     *     layout: {
+     *         content: [
+     *             {
+     *                 type: 'stack',
+     *                 content: [
+     *                     {
+     *                         type: 'component',
+     *                         componentName: 'view',
+     *                         componentState: {
+     *                             name: 'test_view_1',
+     *                             url: 'https://cdn.openfin.co/docs/javascript/canary/Platform.html'
+     *                         }
+     *                     },
+     *                     {
+     *                         type: 'component',
+     *                         componentName: 'view',
+     *                         componentState: {
+     *                             name: 'test_view_2',
+     *                             url: 'https://cdn.openfin.co/docs/javascript/canary/Platform.html'
+     *                         }
+     *                     }
+     *                 ]
+     *             }
+     *         ]
+     *     }
+     * }).then(console.log);
+     * ```
+     * The Default Window's design can be customized by specifying the `stylesheetUrl` property in the manifest:
+     *
+     * ```json
+     * {
+     *     platform: {
+     *         defaultWindowOptions: {
+     *             stylesheetUrl: 'some-url.css',
+     *             ...
+     *         }
+     *     }
+     * }
+     * ```
+     * For a list of common Layout CSS classes you can override in your custom stylesheet, see <a href="tutorial-layoutStyles.html">Useful Layout CSS Classes</a>
+     **
+     * To specify a Platform Custom Window, provide a `url` property when creating a Window.
+     * If you intend to render a Layout in your Custom Window, you must also specify an `HTMLElement` that the Layout will inject into and set its `id` property to `"layout-container"`.
+     *
+     * The example below will create a Platform Custom Window:
+     *
+     * ```js
+     *     // in an OpenFin app:
+     *     const platform = fin.Platform.getCurrentSync();
+     *     const windowConfig =
+     *         {
+     *             url: "https://www.my-domain.com/my-custom-window.html", // here we point to where the Custom Frame is hosted.
+     *             layout: {
+     *                 content: [
+     *                     {
+     *                         type: "stack",
+     *                         content: [
+     *                             {
+     *                                 type: "component",
+     *                                 componentName: "view",
+     *                                 componentState: {
+     *                                     name: "app #1",
+     *                                     url: "https://cdn.openfin.co/docs/javascript/canary/Platform.html"
+     *                                 }
+     *                             },
+     *                             {
+     *                                 type: "component",
+     *                                 componentName: "view",
+     *                                 componentState: {
+     *                                     name: "app #2",
+     *                                     url: "https://cdn.openfin.co/docs/javascript/canary/Platform.html"
+     *                                 }
+     *                             }
+     *                         ]
+     *                     }
+     *                 ]
+     *             }
+     *         };
+     *     platform.createWindow(windowConfig);
+     * ```
+     *
+     * Here's an example of a minimalist Custom Platform Window implementation:
+     * ```html
+     * <html>
+     *     <head>
+     *         <meta charset="utf-8">
+     *         <meta name="viewport" content="width=device-width, initial-scale=1">
+     *         <link rel="stylesheet" type="text/css" href="./styles.css">
+     *     </head>
+     *     <body>
+     *         <div id="of-frame-main">
+     *             <div id="title-bar">
+     *                 <div class="title-bar-draggable">
+     *                     <div id="title"> This is a custom frame! </div>
+     *                 </div>
+     *                 <div id="buttons-wrapper">
+     *                     <div class="button" id="minimize-button"></div>
+     *                     <div class="button" id="expand-button"></div>
+     *                     <div class="button" id="close-button"></div>
+     *                 </div>
+     *             </div>
+     *             <div id="layout-container"></div> <!-- OpenFin layout would be injected here -->
+     *             <script src="./custom-frame.js"></script>
+     *         </div>
+     *     </body>
+     * </html>
+     * ```
+     * Your Custom Window can use in-domain resources for further customization (such as CSS, scripts, etc.).<br>
+     * For a list of common Layout CSS classes you can override in your stylesheet, see <a href="tutorial-layoutStyles.html">Useful Layout CSS Classes</a>
+     *
+     * The example above will require the `body` element to have `height: 100%;` set in order to render the layout correctly.
      */
     createWindow(options: OpenFin.PlatformWindowCreationOptions): Promise<OpenFin.Window & OpenFin.Identity>;
     /**
      * Closes current platform, all its windows, and their views.
-     * @return { Promise<void> }
-     * @tutorial Platform.quit
+     *
+     * @example
+     * ```js
+     * const platform = await fin.Platform.getCurrent();
+     * platform.quit();
+     * // All windows/views in current layout platform will close and platform will shut down
+     * ```
      */
     quit(): Promise<void>;
     /**
      * Closes a specified view in a target window.
-     * @param { Identity } viewIdentity View identity
-     * @return { Promise<void> }
-     * @tutorial Platform.closeView
+     * @param viewIdentity View identity
+     *
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const viewOptions = {
+     *     name: 'test_view',
+     *     url: 'https://example.com'
+     * };
+     *
+     * function sleep(ms) {
+     *     return new Promise(resolve => setTimeout(resolve, ms));
+     * }
+     *
+     * const platform = await fin.Platform.getCurrent();
+     *
+     * await platform.createView(viewOptions, windowIdentity);
+     * // a new view will now show in the current window
+     *
+     * await sleep(5000);
+     *
+     * const viewIdentity = { uuid: windowIdentity.uuid, name: 'test_view'};
+     * platform.closeView(viewIdentity);
+     * // the view will now close
+     * ```
      */
     closeView(viewIdentity: OpenFin.Identity): Promise<void>;
     /**
      * ***DEPRECATED - please use Platform.createView.***
      * Reparents a specified view in a new target window.
-     * @param { Identity } viewIdentity View identity
-     * @param { Identity } target new owner window identity
-     * @return { Promise<View> }
+     * @param viewIdentity View identity
+     * @param target new owner window identity
+     *
      * @tutorial Platform.createView
      */
     reparentView(viewIdentity: OpenFin.Identity, target: OpenFin.Identity): Promise<View>;
     /**
-     * Returns a snapshot of the platform in its current state.
+     * Returns a snapshot of the platform in its current state. You can pass the returning object to
+     * [Platform.applySnapshot]{@link Platform#applySnapshot} to launch it.
+     *
+     * @remarks The snapshot will include details such as an [ISO format](https://en.wikipedia.org/wiki/ISO_8601)
+     * timestamp of when the snapshot was taken, OpenFin runtime version the platform is running on, monitor information
+     * and the list of currently running windows.
      *
-     * Can be used to restore an application to a previous state.
-     * @return { Promise<Snapshot> }
-     * @tutorial Platform.getSnapshot
+     * @example
+     * ```js
+     * const platform = await fin.Platform.getCurrent();
+     * const snapshot = await platform.getSnapshot();
+     * ```
      */
     getSnapshot(): Promise<OpenFin.Snapshot>;
     /**
@@ -72,11 +313,25 @@ export declare class Platform extends EmitterBase<OpenFin.PlatformEvent> {
      *
      * Can be used to restore a view to a previous state.
      *
-     * @param { Identity } viewIdentity View identity
-     * @returns { Promise<ViewState> }
+     * @param viewIdentity View identity
+     *
      * @internal
      * @experimental
-     * @tutorial Platform.getViewSnapshot
+     * @remarks This slice of snapshot state is equivalent to what is stored as `componentState` for views
+     * when capturing platform state using [Platform.getSnapshot]{@link Platform#getSnapshot}.
+     *
+     * @example
+     * ```js
+     * const platform = await fin.Platform.getCurrent();
+     * const url = 'https://google.com';
+     * const view = await fin.View.create({ name: 'my-view', target: fin.me.identity, url });
+     *
+     * await view.navigate(url);
+     *
+     * const viewState = await platform.getViewSnapshot(view.identity);
+     *
+     * console.log(viewState);
+     * ```
      */
     getViewSnapshot(viewIdentity: OpenFin.Identity): Promise<OpenFin.ViewState>;
     /**
@@ -87,60 +342,308 @@ export declare class Platform extends EmitterBase<OpenFin.PlatformEvent> {
      *
      * The function accepts either a snapshot taken using {@link Platform#getSnapshot getSnapshot},
      * or a url or filepath to a snapshot JSON object.
-     * @param { Snapshot | string } requestedSnapshot Snapshot to apply, or a url or filepath.
-     * @param { ApplySnapshotOptions } [options] Optional parameters to specify whether existing windows should be closed.
-     * @return { Promise<Platform> }
-     * @tutorial Platform.applySnapshot
+     * @param requestedSnapshot Snapshot to apply, or a url or filepath.
+     * @param options Optional parameters to specify whether existing windows should be closed.
+     *
+     * @remarks Will create any windows and views that are not running but are passed in the snapshot object. Any View
+     * specified in the snapshot is assigned a randomly generated name to avoid collisions.
+     *
+     * @example
+     * ```js
+     * // Get a wrapped layout platform instance
+     * const platform = await fin.Platform.getCurrent();
+     *
+     * const snapshot = {
+     *     windows: [
+     *         {
+     *             layout: {
+     *                 content: [
+     *                     {
+     *                         type: 'stack',
+     *                         content: [
+     *                             {
+     *                                 type: 'component',
+     *                                 componentName: 'view',
+     *                                 componentState: {
+     *                                     name: 'component_X',
+     *                                     url: 'https://www.openfin.co'
+     *                                 }
+     *                             },
+     *                             {
+     *                                 type: 'component',
+     *                                 componentName: 'view',
+     *                                 componentState: {
+     *                                     name: 'component_Y',
+     *                                     url: 'https://cdn.openfin.co/embed-web/chart.html'
+     *                                 }
+     *                             }
+     *                         ]
+     *                     }
+     *                 ]
+     *             }
+     *         }
+     *     ]
+     * }
+     *
+     * platform.applySnapshot(snapshot);
+     * ```
+     *
+     * In place of a snapshot object, `applySnapshot` can take a url or filepath and to retrieve a JSON snapshot.
+     *
+     * ```js
+     * const platform = await fin.Platform.getCurrent();
+     * platform.applySnapshot('https://api.jsonbin.io/b/5e6f903ef4331e681fc1231d/1');
+     * ```
+     *
+     * Optionally, `applySnapshot` can close existing windows and restore a Platform to a previously saved state.
+     * This is accomplished by providing `{ closeExistingWindows: true }` as an option.
+     *
+     * ```js
+     * // Get a wrapped layout platform instance
+     * const platform = await fin.Platform.getCurrent();
+     *
+     * async function addViewToWindow(winId) {
+     *     return await platform.createView({
+     *         name: 'test_view_3',
+     *         url: 'https://openfin.co'
+     *     }, winId);
+     * }
+     *
+     * async function createWindowWithTwoViews() {
+     *     const platform = await fin.Platform.getCurrent();
+     *
+     *     return platform.createWindow({
+     *         layout: {
+     *             content: [
+     *                 {
+     *                     type: 'stack',
+     *                     content: [
+     *                         {
+     *                             type: 'component',
+     *                             componentName: 'view',
+     *                             componentState: {
+     *                                 name: 'test_view_1',
+     *                                 url: 'https://example.com'
+     *                             }
+     *                         },
+     *                         {
+     *                             type: 'component',
+     *                             componentName: 'view',
+     *                             componentState: {
+     *                                 name: 'test_view_2',
+     *                                 url: 'https://yahoo.com'
+     *                             }
+     *                         }
+     *                     ]
+     *                 }
+     *             ]
+     *         }
+     *     });
+     * }
+     *
+     * const win = await createWindowWithTwoViews();
+     * // ... you will now see a new window with two views in it
+     *
+     * // we take a snapshot of the current state of the app, before changing it
+     * const snapshotOfInitialAppState = await platform.getSnapshot();
+     *
+     * // now let's change the state of the app:
+     * await addViewToWindow(win.identity);
+     * // ... the window now has three views in it
+     *
+     * await platform.applySnapshot(snapshotOfInitialAppState, { closeExistingWindows: true });
+     * // ... the window will revert to previous state, with just two views
+     *
+     * ```
      */
     applySnapshot(requestedSnapshot: OpenFin.Snapshot | string, options?: OpenFin.ApplySnapshotOptions): Promise<Platform>;
     /**
      * Fetches a JSON manifest using the browser process and returns a Javascript object.
-     * Can be overwritten using {@link Platform#init Platform.init}.
-     * @param { string } manifestUrl The URL of the manifest to fetch.
-     * @return { Promise<any> }
-     * @tutorial Platform.fetchManifest
+     * Can be overwritten using {@link Platform.PlatformModule.init Platform.init}.
+     * @param manifestUrl The URL of the manifest to fetch.
+     *
+     * @remarks Can be overwritten using {@link Platform#init Platform.init}.
+     *
+     * @example
+     *
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     * const manifest = await platform.fetchManifest('https://www.path-to-manifest.com/app.json');
+     * console.log(manifest);
+     * ```
      */
     fetchManifest(manifestUrl: string): Promise<any>;
+    /**
+     * @deprecated (renamed)
+     * @ignore
+     */
     launchLegacyManifest: (manifestUrl: string) => Promise<Platform>;
     /**
      * Retrieves a manifest by url and launches a legacy application manifest or snapshot into the platform.  Returns a promise that
      * resolves to the wrapped Platform.
-     * @param {string} manifestUrl - The URL of the manifest that will be launched into the platform.  If this app manifest
+     * @param manifestUrl - The URL of the manifest that will be launched into the platform.  If this app manifest
      * contains a snapshot, that will be launched into the platform.  If not, the application described in startup_app options
-     * will be launched into the platform. The applicable startup_app options will become {@link View~options View Options}.
-     * @return {Promise<Platform>}
-     * @tutorial Platform.launchContentManifest
+     * will be launched into the platform. The applicable startup_app options will become {@link OpenFin.ViewCreationOptions View Options}.
+     *
+     * @remarks If the app manifest contains a snapshot, that will be launched into the platform.  If not, the
+     * application described in startup_app options will be launched into the platform as a window with a single view.
+     * The applicable startup_app options will become View Options.
+     *
+     * @example
+     * ```js
+     * try {
+     *     const platform = fin.Platform.getCurrentSync();
+     *     await platform.launchContentManifest('http://localhost:5555/app.json');
+     *     console.log(`content launched successfully into platform`);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * // For a local manifest file:
+     * try {
+     *     const platform = fin.Platform.getCurrentSync();
+     *     platform.launchContentManifest('file:///C:/somefolder/app.json');
+     *     console.log(`content launched successfully into platform`);
+     * } catch(e) {
+     *     console.error(e);
+     * }
+     * ```
      * @experimental
      */
     launchContentManifest(manifestUrl: string): Promise<Platform>;
     /**
      * Set the context of a host window. The context will be available to the window itself, and to its child Views. It will be saved in any platform snapshots.
      * It can be retrieved using {@link Platform#getWindowContext getWindowContext}.
-     * @param {any} context - A field where serializable context data can be stored to be saved in platform snapshots.
-     * @param {Identity} [target] - A target window or view may optionally be provided. If no target is provided, the update will be applied
+     * @param context - A field where serializable context data can be stored to be saved in platform snapshots.
+     * @param target - A target window or view may optionally be provided. If no target is provided, the update will be applied
      * to the current window (if called from a Window) or the current host window (if called from a View).
-     * @return {Promise<void>}
-     * @tutorial Platform.setWindowContext
+     *
+     * @remarks The context data must be serializable.  This can only be called from a window or view that has been launched into a
+     * platform.
+     * This method can be called from the window itself, or from any child view. Context data is shared by all
+     * entities within a window.
+     *
+     * @example
+     * Setting own context:
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     * const contextData = {
+     *     security: 'STOCK',
+     *     currentView: 'detailed'
+     * }
+     *
+     * await platform.setWindowContext(contextData);
+     * // Context of current window is now set to `contextData`
+     * ```
+     *
+     * Setting the context of another window or view:
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     * const contextData = {
+     *     security: 'STOCK',
+     *     currentView: 'detailed'
+     * }
+     *
+     * const windowOrViewIdentity = { uuid: fin.me.uuid, name: 'nameOfWindowOrView' };
+     * await platform.setWindowContext(contextData, windowOrViewIdentity);
+     * // Context of the target window or view is now set to `contextData`
+     * ```
+     *
+     * A view can listen to changes to its host window's context by listening to the `host-context-changed` event.
+     * This event will fire when a host window's context is updated or when the view is reparented to a new window:
+     *
+     * ```js
+     * // From a view
+     * const contextChangeHandler = ({ context }) => {
+     *     console.log('Host window\'s context has changed. New context data:', context);
+     *     // react to new context data here
+     * }
+     * await fin.me.on('host-context-changed', contextChangeHandler);
+     *
+     * const platform = await fin.Platform.getCurrentSync();
+     * const contextData = {
+     *     security: 'STOCK',
+     *     currentView: 'detailed'
+     * }
+     * platform.setWindowContext(contextData) // contextChangeHandler will log the new context
+     * ```
+     *
+     * To listen to a window's context updates, use the `context-changed` event:
+     * ```js
+     * // From a window
+     * const contextChangeHandler = ({ context }) => {
+     *     console.log('This window\'s context has changed. New context data:', context);
+     *     // react to new context data here
+     * }
+     * await fin.me.on('context-changed', contextChangeHandler);
+     *
+     * const platform = await fin.Platform.getCurrentSync();
+     * const contextData = {
+     *     security: 'STOCK',
+     *     currentView: 'detailed'
+     * }
+     * platform.setWindowContext(contextData) // contextChangeHandler will log the new context
+     * ```
      * @experimental
      */
     setWindowContext(context?: any, target?: OpenFin.Identity): Promise<void>;
     /**
      * Get the context context of a host window that was previously set using {@link Platform#setWindowContext setWindowContext}.
      * The context will be saved in any platform snapshots.  Returns a promise that resolves to the context.
-     * @param {Identity} [target] - A target window or view may optionally be provided. If no target is provided, target will be
+     * @param target - A target window or view may optionally be provided. If no target is provided, target will be
      * the current window (if called from a Window) or the current host window (if called from a View).
-     * @return {Promise<any>}
-     * @tutorial Platform.getWindowContext
+     *
+     * @remarks This method can be called from the window itself, or from any child view. Context data is shared
+     * by all entities within a window.
+     *
+     * @example
+     *
+     * Retrieving context from current window:
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     * const customContext = { answer: 42 };
+     * await platform.setWindowContext(customContext);
+     *
+     * const myContext = await platform.getWindowContext();
+     * console.log(myContext); // { answer: 42 }
+     * ```
+     *
+     * Retrieving the context of another window or view:
+     * ```js
+     * const platform = fin.Platform.getCurrentSync();
+     *
+     * const windowOrViewIdentity = { uuid: fin.me.uuid, name: 'nameOfWindowOrView' };
+     *
+     * const targetWindowContext = await platform.getWindowContext(windowOrViewIdentity);
+     * console.log(targetWindowContext); // context of target window
+     * ```
      * @experimental
      */
     getWindowContext(target?: OpenFin.Identity): Promise<any>;
     /**
      * Closes a window. If enableBeforeUnload is enabled in the Platform options, any beforeunload handler set on Views will fire
      * This behavior can be disabled by setting skipBeforeUnload to false in the options parameter.
-     * @param {Identity} winId
-     * @param {closeWindowoptions} [options]
-     * @returns {Promise<void>}
-     * @tutorial Platform.closeWindow
+     * @param winId
+     * @param options
+     *
+     * @remarks This method works by setting a `close-requested` handler on the Platform Window. If you have your own `close-requested` handler set on the Platform Window as well,
+     * it is recommended to move that logic over to the [PlatformProvider.closeWindow]{@link PlatformProvider#closeWindow} override to ensure it runs when the Window closes.
+     *
+     * @example
+     *
+     * ```js
+     * // Close the current Window inside a Window context
+     * const platform = await fin.Platform.getCurrent();
+     * platform.closeWindow(fin.me.identity);
+     *
+     * // Close the Window from inside a View context
+     * const platform = await fin.Platform.getCurrent();
+     * const parentWindow = await fin.me.getCurrentWindow();
+     * platform.closeWindow(parentWindow.identity);
+     *
+     * // Close the Window and do not fire the before unload handler on Views
+     * const platform = await fin.Platform.getCurrent();
+     * platform.closeWindow(fin.me.identity, { skipBeforeUnload: true });
+     * ```
      * @experimental
      */
     closeWindow(windowId: OpenFin.Identity, options?: {