@i2analyze/notebook-sdk 1.9.0-dev.1 → 1.9.0-dev.2

package/lib/gen/notebook-sdk-public.d.ts

@@ -2295,6 +2295,47 @@ export declare namespace commands {
          * @i2since 1.0
          */
         surfaceCommands(...commandsOrCommandIds: (ICommand | CommandId)[]): void;
+        /**
+         * Adds a dynamic group whose commands are determined at runtime based on the current application state.
+         *
+         * @remarks
+         * Dynamic groups allow commands to be created and surfaced at runtime, when the group is displayed
+         * from a menu or ribbon popup. The group's `onSurface` callback is invoked when the group needs to
+         * be rendered, and receives the current context along with a scoped {@link commands.IDynamicActionArea}
+         * for creating and positioning commands.
+         *
+         * Commands created within a dynamic group are transient - they exist only while the group is visible
+         * and are automatically cleaned up when the group is removed from the surface.
+         *
+         * @example
+         * ```typescript
+         * // Add a dynamic group to the chart item popup menu
+         * api.commands.chartItemPopupMenu.addDynamicGroup({
+         *   id: 'context-actions',
+         *   label: 'Context Actions',
+         *   type: 'records',
+         *   onSurface: (commandArea, context, signal) => {
+         *     // Create commands based on current selection
+         *     const entityCount = context.entityRecords.count;
+         *     if (entityCount > 0) {
+         *       const cmd = commandArea.createCommand({
+         *         id: 'process-selected',
+         *         name: `Process ${entityCount} selected items`,
+         *         type: 'records',
+         *         onExecute: (payload) => { /* ... *\/ }
+         *       });
+         *       commandArea.surfaceCommands(cmd);
+         *     }
+         *   }
+         * });
+         * ```
+         *
+         * @typeParam TCommandType - The type of commands in this group, which determines the context passed to `onSurface`.
+         * @param config - The configuration for the dynamic group.
+         * @throws `Error` if the configuration is invalid or a group with the same identifier already exists.
+         * @i2since 1.9
+         */
+        addDynamicGroup<TCommandType extends CommandType = CommandType>(config: IDynamicGroupConfig<TCommandType>): void;
         /**
          * Gets the system groups for the action area, which you can use to specify relative locations for your actions and groups.
          * @i2since 1.0
@@ -2419,6 +2460,128 @@ export declare namespace commands {
      */
     export interface IMenuGroup extends IGroupBase {
     }
+    /**
+     * Configuration for a dynamic group whose contents is determined at runtime.
+     *
+     * @typeParam TCommandType - The type of commands in this group, which determines the context passed to `onSurface`.
+     * @i2since 1.9
+     */
+    export interface IDynamicGroupConfig<TCommandType extends CommandType = CommandType> {
+        /**
+         * Gets the identifier of the group, which should be a GUID.
+         * @i2since 1.9
+         */
+        readonly id: GroupId;
+        /**
+         * Gets the label of the group, which is displayed to users.
+         *
+         * @remarks
+         * The label appears in popup menus and submenus, and also as the label for ribbon buttons
+         * that open a pop-out menu.
+         *
+         * @i2since 1.9
+         */
+        readonly label: string;
+        /**
+         * Gets the icon of the group, which is displayed in the user interface.
+         * @i2since 1.9
+         */
+        readonly icon?: IIcon;
+        /**
+         * Gets the type of context that is passed to the `onSurface` callback.
+         *
+         * @remarks
+         * The value `'unscoped'` means no context (the context parameter is `undefined`).
+         * The value `'records'` provides a chart selection records context ({@link commands.IRecordsContext}).
+         * The value `'application'` provides the full application contents context ({@link app.IApplicationContents}).
+         *
+         * @i2since 1.9
+         */
+        readonly type: TCommandType;
+        /**
+         * Invokes a callback when the group needs to be rendered in the user interface.
+         *
+         * @remarks
+         * Receives a scoped {@link commands.IDynamicActionArea} for creating and surfacing commands.
+         * Commands created in this callback are transient and exist only while the group is visible.
+         * They are automatically unregistered when the group is removed from the surface.
+         *
+         * The `signal` parameter fires when the group is being removed, allowing you to cancel pending
+         * async operations or clean up resources.
+         *
+         * @param commandArea - A scoped action area for creating and positioning commands within this group.
+         * @param context - The context based on the group type, determined by {@link commands.CommandPayloadMap}.
+         * @param signal - An `AbortSignal` that fires when the group is removed from the surface.
+         * @returns An optional cleanup function that is called when the group is removed.
+         * @i2since 1.9
+         */
+        onSurface(commandArea: IDynamicActionArea, context: CommandPayloadMap[TCommandType], signal: AbortSignal): void | (() => void);
+    }
+    /**
+     * A scoped action area for creating and positioning commands within a dynamic group.
+     *
+     * @remarks
+     * This interface is provided to the `onSurface` callback of {@link commands.IDynamicGroupConfig}.
+     * It allows you to create commands and organize them within the dynamic group using positioning
+     * methods like `before`, `after`, and `getGroup`.
+     *
+     * Commands created through this area are automatically cleaned up when the dynamic group is removed
+     * from the surface.
+     *
+     * @i2since 1.9
+     */
+    export interface IDynamicActionArea extends Pick<ICommandApi, 'createCommand'> {
+        /**
+         * Locates the area of the user interface that appears immediately before a particular action or group of actions.
+         *
+         * @param idOrCommand - The identifier of the action or group to use as a reference, or a command object.
+         * @returns An object that you can use to add actions or a group to the located area.
+         * @i2since 1.9
+         */
+        before(idOrCommand: CommandId | GroupId | ICommand): IDynamicActionArea;
+        /**
+         * Locates the area of the user interface that appears immediately after a particular action or group of actions.
+         *
+         * @param idOrCommand - The identifier of the action or group to use as a reference, or a command object.
+         * @returns An object that you can use to add actions or a group to the located area.
+         * @i2since 1.9
+         */
+        after(idOrCommand: CommandId | GroupId | ICommand): IDynamicActionArea;
+        /**
+         * Locates the area of the user interface that is occupied by a particular group of actions.
+         *
+         * @param id - The identifier of the group to use as a reference.
+         * @returns An action area representing the specified group.
+         * @i2since 1.9
+         */
+        getGroup(id: GroupId): IDynamicActionArea;
+        /**
+         * Adds the specified group of actions to the user interface.
+         *
+         * @param group - The group to add.
+         * @returns An object that you can use to add actions or a further group to the new group.
+         * @i2since 1.9
+         */
+        addGroup(group: IGroup): IDynamicActionArea;
+        /**
+         * Adds the specified group of actions to the user interface, or gets an existing group with the same identifier.
+         *
+         * @param group - The group to add or get.
+         * @returns An object that you can use to add actions or a further group to the new or existing group.
+         * @i2since 1.9
+         */
+        addOrGetGroup(group: IGroup): IDynamicActionArea;
+        /**
+         * Adds actions for the specified registered commands to the user interface.
+         *
+         * @remarks
+         * When you surface multiple commands, the actions are added to the user interface in the same order as you specify them.
+         *
+         * @param commandsOrCommandIds - The registered commands, or the identifiers of the commands, to surface.
+         * @i2since 1.9
+         */
+        surfaceCommands(...commandsOrCommandIds: (ICommand | CommandId)[]): void;
+    }
     /**
      * A representation of a command in the user interface. An action is created when a command is surfaced.
      * @i2since 1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i2analyze/notebook-sdk",
-  "version": "1.9.0-dev.1",
+  "version": "1.9.0-dev.2",
   "description": "i2 Notebook SDK",
   "license": "MIT",
   "publishConfig": {