@interopio/workspaces-api 4.6.0 → 5.0.0

package/workspaces.d.ts

@@ -20,7 +20,10 @@ export namespace IOConnectWorkspaces {
 
     /** An object describing a workspace layout. */
     export interface WorkspaceLayout {
-        /** An unique string name and identifier of the layout */
+        /** A unique string identifier of the layout */
+        id?: string;
+
+        /** name of the layout */
         name: string;
 
         /** The type of the workspace element. */
@@ -185,6 +188,10 @@ export namespace IOConnectWorkspaces {
         allowSystemHibernation?: boolean;
     }
 
+    export interface RestoreWorkspaceByIdConfig extends RestoreWorkspaceConfig {
+        layoutId: string;
+    }
+
     /**
      * Settings for showing a previously hidden Workspaces Frame instance.
      */
@@ -480,6 +487,69 @@ export namespace IOConnectWorkspaces {
          * @default true
          */
         allowSystemHibernation?: boolean;
+
+        /**
+         * Restrictions for dropping apps in the Workspace and allowing apps to appear in the "Add Apps" popup menu of the Workspace.
+         * @since io.Connect Desktop 10.5
+         * @since io.Connect Browser 4.6
+         * @since @interopio/workspaces-api 5.0.0
+         */
+        appRestrictions?: AppRestrictions | undefined;
+    }
+
+    /**
+     * Describes the default restrictions for dropping apps in a Workspace and allowing apps to appear in the "Add Apps" popup menu of a Workspace.
+     * @since io.Connect Desktop 10.5
+     * @since io.Connect Browser 4.6
+     * @since @interopio/workspaces-api 5.0.0
+     */
+    export interface AppRestrictionRule {
+
+        /**
+         * If `true`, will allow an app to appear in the "Add Apps" popup menu of a Workspace.
+         */
+        allowInApplicationPopup?: boolean;
+
+        /**
+         * If `true`, will allow an app to be dropped in a Workspace.
+         * *Available only in **io.Connect Desktop**.*
+         */
+        allowDrop?: boolean;
+    }
+
+    /**
+     * Describes the restrictions for dropping a specific app in a Workspace and allowing it to appear in the "Add Apps" popup menu of a Workspace.
+     * @since io.Connect Desktop 10.5
+     * @since io.Connect Browser 4.6
+     * @since @interopio/workspaces-api 5.0.0
+     */
+    export interface AppRestrictionEntry extends AppRestrictionRule {
+
+        /**
+         * Name of the app, as defined within the io.Connect framework, for which to apply the specified restrictions.
+         */
+        appName: string;
+    }
+
+    /**
+     * Describes the restrictions for dropping apps in a Workspace and allowing apps to appear in the "Add Apps" popup menu of a Workspace.
+     * @since io.Connect Desktop 10.5
+     * @since io.Connect Browser 4.6
+     * @since @interopio/workspaces-api 5.0.0
+     */
+    export interface AppRestrictions {
+
+        /**
+         * Array of objects describing the restrictions related to specific apps.
+         * The restrictions specified here will override the default restrictions specified via the `default` property.
+         */
+        apps?: AppRestrictionEntry[];
+
+        /**
+         * Default restrictions that will be applied to all apps.
+         * The restrictions specified here can be overridden per app via the `apps` array.
+         */
+        default?: AppRestrictionRule;
     }
 
     /** A config object which provides fine grain control when locking a workspace */
@@ -775,6 +845,18 @@ export namespace IOConnectWorkspaces {
         frame?: FrameTargetingOptions;
     }
 
+    export interface RestoreWorkspaceByIdDefinition {
+        /**
+        * The id of a saved workspace layout, which will be restored.
+        */
+        id: string;
+
+        /**
+        * An optional object containing various workspace restore options.
+        */
+        restoreOptions?: RestoreWorkspaceConfig;
+    }
+
     /** An object describing the possible options when restoring a workspace */
     export interface RestoreWorkspaceDefinition {
         /**
@@ -843,6 +925,8 @@ export namespace IOConnectWorkspaces {
 
     /** An object describing a workspace layout without the underlying structure */
     export interface WorkspaceLayoutSummary {
+        id?: string;
+
         /** An unique string name and identifier of the layout */
         name: string;
 
@@ -880,7 +964,7 @@ export namespace IOConnectWorkspaces {
         /**
          * Array of workspace definitions with which the frame should be opened
          */
-        workspaces: Array<IOConnectWorkspaces.WorkspaceDefinition | RestoreWorkspaceDefinition>;
+        workspaces: Array<IOConnectWorkspaces.WorkspaceDefinition | RestoreWorkspaceDefinition | RestoreWorkspaceByIdDefinition>;
     }
 
     export interface FrameInitializationContext {
@@ -980,11 +1064,11 @@ export namespace IOConnectWorkspaces {
     }
 
     /**
-     * Options for setting the on-top state of a Workspaces Frame.
+     * Settings for placing a Workspaces App instance on top of the z-order.
      */
     export interface FrameSetOnTopOptions {
         /**
-         * If `true`, the Frame will be set on top of other windows.
+         * If `true`, the Workspaces App instance will be set on top of the z-order.
          */
         onTop: boolean;
     }
@@ -1287,9 +1371,11 @@ export namespace IOConnectWorkspaces {
         showDialog<T>(options: FrameDialogOptions): Promise<T>;
 
         /**
-         * Sets the on-top state of the Frame.
+         * Sets a Workspaces App instance on top of the z-order.
          * *Available only in **io.Connect Desktop**.*
-         * @param options Options for setting the on-top state.
+         * @param options Settings for placing the Workspaces App instance on top of the z-order.
+         * @since io.Connect Desktop 10.3
+         * @since @interopio/workspaces-api 4.5
          */
         setOnTop(options: FrameSetOnTopOptions): Promise<void>;
 
@@ -1397,6 +1483,9 @@ export namespace IOConnectWorkspaces {
         /** The name of the originating layout of the current workspace if any */
         layoutName: string | undefined;
 
+        /** The id of the originating layout of the current workspace if any. Can be undefined if using with an older version of **io.Connect Desktop** or **io.Connect Browser**. */
+        layoutId?: string;
+
         /** Indicates if the workspace is hibernated */
         isHibernated?: boolean;
 
@@ -1480,6 +1569,14 @@ export namespace IOConnectWorkspaces {
          * This setting doesn't apply to programmatic hibernation via the `hibernate()` method of a `Workspace` instance.
          */
         allowSystemHibernation?: boolean;
+
+        /**
+         * Restrictions for dropping apps in the Workspace and allowing apps to appear in the "Add Apps" popup menu of the Workspace.
+         * @since io.Connect Desktop 10.5
+         * @since io.Connect Browser 4.6
+         * @since @interopio/workspaces-api 5.0.0
+         */
+        appRestrictions?: AppRestrictions;
     }
 
     export type SaveLayoutConfig = Omit<Omit<IOConnectWorkspaces.WorkspaceLayoutSaveConfig, "name">, "workspaceId">;
@@ -1553,7 +1650,7 @@ export namespace IOConnectWorkspaces {
          * Returns the first box in this workspace, which satisfies the provided predicate.
          * @param predicate A filtering function (predicate) called for each box present in this workspace.
          */
-        getBox(predicate: (box: WorkspaceBox) => boolean): WorkspaceBox;
+        getBox(predicate: (box: WorkspaceBox) => boolean): WorkspaceBox | undefined;
 
         /**
          * Returns all boxes in this workspace, which satisfy the provided predicate. If no predicate was provided, will return all boxes.
@@ -1565,7 +1662,7 @@ export namespace IOConnectWorkspaces {
          * Returns the first row in this workspace, which satisfies the provided predicate.
          * @param predicate A filtering function (predicate) called for each row present in this workspace.
          */
-        getRow(predicate: (row: Row) => boolean): Row;
+        getRow(predicate: (row: Row) => boolean): Row | undefined;
 
         /**
          * Returns all rows in this workspace, which satisfy the provided predicate. If no predicate was provided, will return all rows.
@@ -1577,7 +1674,7 @@ export namespace IOConnectWorkspaces {
          * Returns the first column in this workspace, which satisfies the provided predicate.
          * @param predicate A filtering function (predicate) called for each column present in this workspace.
          */
-        getColumn(predicate: (column: Column) => boolean): Column;
+        getColumn(predicate: (column: Column) => boolean): Column | undefined;
 
         /**
          * Returns all columns in this workspace, which satisfy the provided predicate. If no predicate was provided, will return all column.
@@ -1589,7 +1686,7 @@ export namespace IOConnectWorkspaces {
          * Returns the first group in this workspace, which satisfies the provided predicate.
          * @param predicate A filtering function (predicate) called for each group present in this workspace.
          */
-        getGroup(predicate: (group: Group) => boolean): Group;
+        getGroup(predicate: (group: Group) => boolean): Group | undefined;
 
         /**
          * Returns all groups in this workspace, which satisfy the provided predicate. If no predicate was provided, will return all groups.
@@ -1601,7 +1698,7 @@ export namespace IOConnectWorkspaces {
          * Returns the first window in this workspace, which satisfies the provided predicate.
          * @param predicate A filtering function (predicate) called for each window present in this workspace.
          */
-        getWindow(predicate: (window: WorkspaceWindow) => boolean): WorkspaceWindow;
+        getWindow(predicate: (window: WorkspaceWindow) => boolean): WorkspaceWindow | undefined;
 
         /**
          * Returns all windows in this workspace, which satisfy the provided predicate. If no predicate was provided, will return all windows.
@@ -1714,19 +1811,21 @@ export namespace IOConnectWorkspaces {
          */
         onResumed(callback: () => void): Promise<IOConnectWorkspaces.Unsubscribe>;
 
-       /**
-        * Notifies when the Workspace tab has been reordered. Returns an unsubscribe function.
-        * @param callback Callback function for handling the event.
-        * *Available only in **io.Connect Browser**.*
-        * @since io.Connect Browser 4.4
-        */
+        /**
+         * Notifies when the Workspace tab has been reordered. Returns an unsubscribe function.
+         * @param callback Callback function for handling the event.
+         * @since io.Connect Desktop 10.3
+         * @since io.Connect Browser 4.4
+         * @since @interopio/workspaces-api 4.4
+         */
         onTabReordered(callback: () => void): Promise<IOConnectWorkspaces.Unsubscribe>;
 
         /**
          * Notifies when the tab of a window participating in the Workspace has been reordered. Returns an unsubscribe function.
          * @param callback Callback function for handling the event. Receives as an argument the `WorkspaceWindow` object describing the window whose tab has been reordered.
-         * *Available only in **io.Connect Browser**.*
+         * @since io.Connect Desktop 10.3
          * @since io.Connect Browser 4.4
+         * @since @interopio/workspaces-api 4.4
          */
         onWindowTabReordered(callback: (window: WorkspaceWindow) => void): Promise<IOConnectWorkspaces.Unsubscribe>;
 
@@ -2213,8 +2312,9 @@ export namespace IOConnectWorkspaces {
         /**
          * Notifies when the tab of the Workspace window has been reordered. Returns an unsubscribe function.
          * @param callback Callback function for handling the event.
-         * *Available only in **io.Connect Browser**.*
+         * @since io.Connect Desktop 10.3
          * @since io.Connect Browser 4.4
+         * @since @interopio/workspaces-api 4.4
          */
         onTabReordered(callback: () => void): Promise<IOConnectWorkspaces.Unsubscribe>;
     }
@@ -2286,6 +2386,7 @@ export namespace IOConnectWorkspaces {
 
     /** A configuration object used to save a current workspace as a layout */
     export interface WorkspaceLayoutSaveConfig {
+        id?: string;
         /**
          * A string used as name (doubles as id) of the layout, which is later used when restoring it.
          */
@@ -2321,6 +2422,14 @@ export namespace IOConnectWorkspaces {
         saveWindowContexts?: boolean;
     }
 
+    /** A configuration object used to overwrite an existing workspace layout, identified by its id */
+    export interface WorkspaceLayoutSaveByIdConfig extends WorkspaceLayoutSaveConfig {
+        /**
+         * The id of the layout to overwrite.
+         */
+        id?: string;
+    }
+
     export interface SetMaximizationBoundaryConfig {
         /**
          * Represents the new value of the maximizationBoundary property
@@ -2397,6 +2506,12 @@ export namespace IOConnectWorkspaces {
          */
         delete(name: string): Promise<void>;
 
+        /**
+         * Deletes a previously saved layout by its id.
+         * @param layoutId The id of the layout to delete.
+         */
+        deleteById(layoutId: string): Promise<void>;
+
         /**
          * Returns all layouts which satisfy the predicate. This collection of all saved layouts includes the layouts structure. If no predicate is provided, it returns all saved layouts.
          * @param predicate A filtering function (predicate) called for each saved layout.
@@ -2415,6 +2530,13 @@ export namespace IOConnectWorkspaces {
          */
         save(config: WorkspaceLayoutSaveConfig): Promise<WorkspaceLayout>;
 
+        /**
+         * Overwrites the layout with the specified id with the structure of an existing, open workspace.
+         * Prefer this over `save()` when layout names aren't guaranteed to be unique (e.g. when layout sharing is enabled).
+         * @param config An object describing the id of the layout to overwrite, the layout name and the id of the workspace, whose structure will be saved.
+         */
+        saveById(config: WorkspaceLayoutSaveByIdConfig): Promise<WorkspaceLayout>;
+
         /**
          * Notifies when a layouts has been saved. This event is fired when a new layout has been saved and an existing layout has been updated.
          * @param callback Callback function to handle the event. Receives the saved layout as a parameter.
@@ -2453,7 +2575,7 @@ export namespace IOConnectWorkspaces {
          * Returns the first frame instance which satisfies the provided predicate or undefined, if non do.
          * @param predicate A filtering function (predicate) called for each open frame.
          */
-        getFrame(predicate: (frame: Frame) => boolean): Promise<Frame>;
+        getFrame(predicate: (frame: Frame) => boolean): Promise<Frame | undefined>;
 
         /**
          * Returns all frames which satisfy the provided predicate. If no predicate is provided, will return all frames.
@@ -2477,7 +2599,7 @@ export namespace IOConnectWorkspaces {
          * Returns the first workspace instance which satisfies the provided predicate or undefined, if non do.
          * @param predicate A filtering function (predicate) called for each open workspace.
          */
-        getWorkspace(predicate: (workspace: Workspace) => boolean): Promise<Workspace>;
+        getWorkspace(predicate: (workspace: Workspace) => boolean): Promise<Workspace | undefined>;
 
         /**
          * Returns an instance of the workspace with the passed id. The performance is better than getWorkspace when querying for a workspace by id.
@@ -2496,14 +2618,14 @@ export namespace IOConnectWorkspaces {
          * This function will search recursively in all open workspaces.
          * @param predicate A filtering function (predicate) called for each window in each open workspace.
          */
-        getWindow(predicate: (workspaceWindow: WorkspaceWindow) => boolean): Promise<WorkspaceWindow>;
+        getWindow(predicate: (workspaceWindow: WorkspaceWindow) => boolean): Promise<WorkspaceWindow | undefined>;
 
         /**
          * Returns the instance of the first box, which satisfies the provided predicate.
          * This function will search recursively in all open workspaces.
          * @param predicate A filtering function (predicate) called for each box in each open workspace.
          */
-        getBox(predicate: (box: WorkspaceBox) => boolean): Promise<WorkspaceBox>;
+        getBox(predicate: (box: WorkspaceBox) => boolean): Promise<WorkspaceBox | undefined>;
 
         /**
          * Opens a new workspace by restoring a previously saved workspace layout.
@@ -2512,6 +2634,12 @@ export namespace IOConnectWorkspaces {
          */
         restoreWorkspace(name: string, options?: RestoreWorkspaceConfig): Promise<Workspace>;
 
+        /**
+         * Opens a new workspace by restoring a previously saved workspace layout by its id.
+         * @param options An object containing the id of the layout to restore and various workspace restore options.
+         */
+        restoreWorkspaceById(options: RestoreWorkspaceByIdConfig): Promise<Workspace>;
+
         /**
          * Opens a new workspace based on the provided definition.
          * @param definition An object describing the shape and options of the workspace.
@@ -2581,8 +2709,9 @@ export namespace IOConnectWorkspaces {
         /**
          * Notifies when the tab of any Workspace in any Workspaces App has been reordered. Returns an unsubscribe function.
          * @param callback Callback function for handling the event. Receives as an argument the `Workspace` object describing the Workspace whose tab has been reordered.
-         * *Available only in **io.Connect Browser**.*
+         * @since io.Connect Desktop 10.3
          * @since io.Connect Browser 4.4
+         * @since @interopio/workspaces-api 4.4
          */
         onWorkspaceTabReordered(callback: (workspace: IOConnectWorkspaces.Workspace) => void): Promise<IOConnectWorkspaces.Unsubscribe>;
         /**
@@ -2628,8 +2757,9 @@ export namespace IOConnectWorkspaces {
         /**
          * Notifies when the tab of a Workspace window participating in any Workspace in any Workspaces App has been reordered. Returns an unsubscribe function.
          * @param callback Callback function for handling the event. Receives as an argument the `WorkspaceWindow` object describing the Workspace window whose tab has been reordered.
-         * *Available only in **io.Connect Browser**.*
+         * @since io.Connect Desktop 10.3
          * @since io.Connect Browser 4.4
+         * @since @interopio/workspaces-api 4.4
          */
         onWindowTabReordered(callback: (workspaceWindow: IOConnectWorkspaces.WorkspaceWindow) => void): Promise<IOConnectWorkspaces.Unsubscribe>;