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

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

@@ -1662,6 +1662,145 @@ export declare namespace chart {
          */
         getRecordsOfType(itemType: schema.ChartItemTypeSpecifier): data.IReadOnlyCollection<records.IChartRecord>;
     }
+    /**
+     * Detailed information about the specific properties, notes, and source references that changed within a record.
+     *
+     * @remarks
+     * This interface provides granular change tracking at the property level.
+     * Empty sets indicate no changes occurred in that category.
+     *
+     * **Known Limitations:**
+     * - Only includes changes for properties that have been fetched. Changes to unfetched properties are not reported here.
+     * - Security dimension changes are not included in this interface.
+     * - If a record is reported as having changed but `recordChanges` shows empty sets for all categories, this may indicate unfetched property changes or security-only edits.
+     *
+     * @example
+     * ```typescript
+     * // Plugin code consuming recordChanges
+     * chartChangeListener((change) => {
+     *   if (change.type === 'minor' && change.recordChanges) {
+     *     change.recordChanges.forEach((recordId, changes) => {
+     *       // Check for property changes
+     *       if (changes.properties?.changed.size > 0) {
+     *         console.log('Properties changed:', changes.properties.changed);
+     *       }
+     *
+     *       // Check for note additions
+     *       if (changes.notes?.added.size > 0) {
+     *         console.log('Notes added:', changes.notes.added);
+     *       }
+     *
+     *       // Check for source reference edits
+     *       if (changes.sourceReferences?.edited.size > 0) {
+     *         console.log('Source references edited:', changes.sourceReferences.edited);
+     *       }
+     *
+     *       // Check for source reference removals
+     *       if (changes.sourceReferences?.removed.size > 0) {
+     *         console.log('Source references removed:', changes.sourceReferences.removed);
+     *       }
+     *     });
+     *   }
+     * });
+     * ```
+     *
+     * @i2since 1.9
+     */
+    export interface IRecordChanges {
+        /**
+         * Gets the property changes for this record.
+         *
+         * @remarks
+         * The property changes are categorized as follows:
+         * - Added: New properties that were set (property type IDs that were not previously set)
+         * - Removed: Properties that were removed (set to `null` or deleted)
+         * - Changed: Existing properties whose values were modified
+         *
+         * **Note:** If a property value oscillates within the same mutation (for example, A→B→A),
+         * it is still reported as "changed" since this tracks mutations, not just final state.
+         *
+         * Empty sets indicate no changes in that category.
+         *
+         * @i2since 1.9
+         */
+        readonly properties?: {
+            /**
+             * Gets the property type IDs for properties that were added to the record.
+             * @i2since 1.9
+             */
+            readonly added: data.IReadOnlyCollection<schema.PropertyTypeIdentifier>;
+            /**
+             * Gets the property type IDs for properties that were removed from the record.
+             * @i2since 1.9
+             */
+            readonly removed: data.IReadOnlyCollection<schema.PropertyTypeIdentifier>;
+            /**
+             * Gets the property type IDs for properties whose values were changed.
+             * @i2since 1.9
+             */
+            readonly changed: data.IReadOnlyCollection<schema.PropertyTypeIdentifier>;
+        };
+        /**
+         * Gets the note changes for this record.
+         *
+         * @remarks
+         * The note changes are categorized as follows:
+         * - Added: New notes that were created
+         * - Edited: Existing notes whose content was modified
+         * - Removed: Notes that were deleted
+         *
+         * Empty sets indicate no changes in that category.
+         *
+         * @i2since 1.9
+         */
+        readonly notes?: {
+            /**
+             * Gets the note IDs for notes that were added to the record.
+             * @i2since 1.9
+             */
+            readonly added: data.IReadOnlyCollection<data.NoteId>;
+            /**
+             * Gets the note IDs for notes whose content was edited.
+             * @i2since 1.9
+             */
+            readonly edited: data.IReadOnlyCollection<data.NoteId>;
+            /**
+             * Gets the note IDs for notes that were removed from the record.
+             * @i2since 1.9
+             */
+            readonly removed: data.IReadOnlyCollection<data.NoteId>;
+        };
+        /**
+         * Gets the source reference changes for this record.
+         *
+         * @remarks
+         * The source reference changes are categorized as follows:
+         * - Added: New source references that were added
+         * - Edited: Existing source references whose content was modified
+         * - Removed: Source references that were deleted
+         *
+         * Empty sets indicate no changes in that category.
+         *
+         * @i2since 1.9
+         */
+        readonly sourceReferences?: {
+            /**
+             * Gets the source reference IDs for source references that were added to the record.
+             * @i2since 1.9
+             */
+            readonly added: data.IReadOnlyCollection<data.SourceReferenceId>;
+            /**
+             * Gets the source reference IDs for source references whose content was edited.
+             * @i2since 1.9
+             */
+            readonly edited: data.IReadOnlyCollection<data.SourceReferenceId>;
+            /**
+             * Gets the source reference IDs for source references that were removed from the record.
+             * @i2since 1.9
+             */
+            readonly removed: data.IReadOnlyCollection<data.SourceReferenceId>;
+        };
+    }
     /**
      * A change that has occurred to the data in a chart.
      * @i2since 1.0
@@ -1671,14 +1810,18 @@ export declare namespace chart {
          * Gets the type of change (minor or major) made to the chart.
          *
          * @remarks
-         * When a "minor" change takes place, the change reports the detail of the affected elements and records.
-         * When a "major" change takes place, the expectation is that client code reloads the whole chart.
+         * The `type` field is always "minor" in current versions. The distinction between major and minor changes has been removed.
+         * This field will be removed in the next major release.
+         *
+         * @deprecated This field will be removed in the next major release. All changes now report detailed affected elements and records.
          * @i2since 1.0
+         *
          */
         readonly type: 'minor' | 'major';
     }
     /**
      * A major change that has occurred to the data on a chart.
+     * @deprecated Use {@link chart.IChartChange} instead. The `type` field is always "minor" and the distinction between major and minor changes has been removed. This interface will be removed in the next major release.
      * @i2since 1.0
      */
     export interface IChartChangeMajor extends IChartChangeBase {
@@ -1784,9 +1927,44 @@ export declare namespace chart {
              */
             readonly removed: data.IReadOnlyCollection<visual.ElementId>;
         };
+        /**
+         * Gets granular change details for records that changed in this chart update.
+         *
+         * @remarks
+         * This optional field provides property-level change tracking for records.
+         * When populated, it contains an entry for each record that changed, with detailed information about:
+         * - Which properties were added, removed, or changed
+         * - Which notes were added, edited, or removed
+         * - Which source references were added or removed
+         *     *
+         * **Usage Pattern:**
+         * ```typescript
+         * // New opt-in granularity
+         * change.recordChanges?.forEach((recordId, changes) => {
+         *   if (changes.properties?.changed.size > 0) {
+         *     console.log('Properties changed for', recordId);
+         *   }
+         * });
+         * ```
+         *
+         * **Known Limitations:**
+         *   Changes to unfetched properties are not reported here.
+         * - Security dimension changes are not included.
+         * - If a record appears in `records.changed` but has no corresponding entry in `recordChanges`,
+         *   or if the entry shows empty sets for all categories, this may indicate unfetched property changes
+         *   or security-only edits.
+         *
+         * @i2since 1.9
+         */
+        readonly recordChanges?: data.IKeyedReadOnlyCollection<records.AnalyzeRecordId, IRecordChanges>;
     }
     /**
      * A change to the data in a chart in i2 Notebook.
+     *
+     * @remarks
+     * Use this type for all chart change handling. The distinction between major and minor changes has been removed,
+     * and all changes now report detailed information about affected elements and records.
+     *
      * @i2since 1.0
      */
     export type IChartChange = IChartChangeMajor | IChartChangeMinor;
@@ -2295,6 +2473,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 +2638,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.3",
   "description": "i2 Notebook SDK",
   "license": "MIT",
   "publishConfig": {