@contrail/extensions-sdk 1.0.27 → 1.0.28

package/lib/apps/plan.d.ts

@@ -7,7 +7,8 @@ export declare enum PlanCommand {
     ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items",
     GET_PLACEHOLDERS = "plan:get_placeholders",
     GET_VIEW_STATE = "plan:get_view_state",
-    ASSIGN_ITEMS = "plan:assign_items"
+    ASSIGN_ITEMS = "plan:assign_items",
+    SCROLL_TO_PLACEHOLDER = "plan:scroll_to_placeholder"
 }
 /**
  * A row on a plan. Beyond the item linkage below, properties are the org-configured
@@ -42,6 +43,30 @@ export interface PlaceholderItemAssignment {
     /** The item to assign — an item family or an item option. */
     itemId: string;
 }
+export interface ScrollToPlaceholderOptions {
+    /**
+     * Also bring this column into view horizontally.
+     *
+     * Omit to scroll vertically only, which is usually what you want after writing to a row —
+     * it leaves the user's horizontal position alone.
+     */
+    propertySlug?: string;
+}
+/** Why a row could not be brought into view. */
+export declare type ScrollToPlaceholderFailure = 'not-on-plan' | 'not-displayed' | 'no-grid';
+export interface ScrollToPlaceholderResult {
+    /** Whether the row was brought into view. Already-visible rows report `true`. */
+    revealed: boolean;
+    /**
+     * Set only when `revealed` is false.
+     *
+     * - `not-on-plan` - no row on this plan has that id.
+     * - `not-displayed` - the row exists but the user's filter or sort excludes it, so there is
+     *   no position to scroll to. Reading {@link PlanApp.getViewState} will say why.
+     * - `no-grid` - the plan is not currently showing the grid, so there is nothing to scroll.
+     */
+    reason?: ScrollToPlaceholderFailure;
+}
 export interface GetPlaceholdersOptions {
     /** Defaults to `all`. */
     scope?: PlanPlaceholderScope;
@@ -130,6 +155,27 @@ export declare class PlanApp {
      * Requires the plan to be editable.
      */
     static assignItems(assignments: Array<PlaceholderItemAssignment>): Promise<void>;
+    /**
+     * Scrolls the plan's grid so a row is in view.
+     *
+     * Use this after writing to the plan - assigning items or adding rows - so the user can see
+     * what changed instead of having to hunt for it. A row that is already on screen is left
+     * alone rather than re-centred.
+     *
+     * This is a view-only operation: it does not select the row, change the filter, or edit
+     * anything, and it does not require the plan to be editable.
+     *
+     * Check the result rather than assuming success - a row outside the user's current filter has
+     * no position in the grid to scroll to:
+     *
+     * ```ts
+     * const result = await PlanApp.scrollToPlaceholder(rowId);
+     * if (!result.revealed && result.reason === 'not-displayed') {
+     *   // The row was written, but the user's filter hides it.
+     * }
+     * ```
+     */
+    static scrollToPlaceholder(placeholderId: string, options?: ScrollToPlaceholderOptions): Promise<ScrollToPlaceholderResult>;
     /**
      * Creates new rows on the plan from property data, and returns them.
      *

package/lib/apps/plan.js

@@ -22,6 +22,7 @@ var PlanCommand;
     PlanCommand["GET_PLACEHOLDERS"] = "plan:get_placeholders";
     PlanCommand["GET_VIEW_STATE"] = "plan:get_view_state";
     PlanCommand["ASSIGN_ITEMS"] = "plan:assign_items";
+    PlanCommand["SCROLL_TO_PLACEHOLDER"] = "plan:scroll_to_placeholder";
 })(PlanCommand = exports.PlanCommand || (exports.PlanCommand = {}));
 class PlanApp {
     static getCurrentPlan() {
@@ -171,6 +172,39 @@ class PlanApp {
             PlanApp.validateAndReturnResults(results);
         });
     }
+    /**
+     * Scrolls the plan's grid so a row is in view.
+     *
+     * Use this after writing to the plan - assigning items or adding rows - so the user can see
+     * what changed instead of having to hunt for it. A row that is already on screen is left
+     * alone rather than re-centred.
+     *
+     * This is a view-only operation: it does not select the row, change the filter, or edit
+     * anything, and it does not require the plan to be editable.
+     *
+     * Check the result rather than assuming success - a row outside the user's current filter has
+     * no position in the grid to scroll to:
+     *
+     * ```ts
+     * const result = await PlanApp.scrollToPlaceholder(rowId);
+     * if (!result.revealed && result.reason === 'not-displayed') {
+     *   // The row was written, but the user's filter hides it.
+     * }
+     * ```
+     */
+    static scrollToPlaceholder(placeholderId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            if (!placeholderId) {
+                return { revealed: false, reason: 'not-on-plan' };
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.SCROLL_TO_PLACEHOLDER,
+                data: { placeholderId, options },
+            });
+            return PlanApp.validateAndReturnResults(results);
+        });
+    }
     /**
      * Creates new rows on the plan from property data, and returns them.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/extensions-sdk",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "Client library for interfacing with VibeIQ's services and apps from an extension.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",