@contrail/extensions-sdk 1.0.26 → 1.0.28

package/lib/apps/plan.d.ts

@@ -6,7 +6,9 @@ export declare enum PlanCommand {
     ADD_PLACEHOLDERS = "plan:add_placeholders",
     ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items",
     GET_PLACEHOLDERS = "plan:get_placeholders",
-    GET_VIEW_STATE = "plan:get_view_state"
+    GET_VIEW_STATE = "plan:get_view_state",
+    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
@@ -34,6 +36,37 @@ export interface AddPlaceholdersOptions {
  * - `selected` — only the currently selected rows
  */
 export declare type PlanPlaceholderScope = 'all' | 'filtered' | 'displayed' | 'selected';
+/** Assigns one existing item to one existing placeholder row. */
+export interface PlaceholderItemAssignment {
+    /** The row to assign onto. */
+    placeholderId: string;
+    /** 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;
@@ -108,6 +141,41 @@ export declare class PlanApp {
      * Reading is always permitted, including on a view-only plan.
      */
     static getViewState(): Promise<PlanViewState>;
+    /**
+     * Assigns existing items to existing placeholder rows.
+     *
+     * Runs the plan's own item-assignment pipeline, so the item's properties are mapped onto the
+     * row, the project item is created if needed, and carryover is applied — the same work the grid
+     * does when a user drops an item onto a row. Rows appear updated immediately and the change is
+     * broadcast to other users.
+     *
+     * Use this to fill placeholders that already carry attribution; to create new rows instead, see
+     * {@link addPlaceholders}.
+     *
+     * 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

@@ -21,6 +21,8 @@ var PlanCommand;
     PlanCommand["ADD_PLACEHOLDERS_WITH_ITEMS"] = "plan:add_placeholders_with_items";
     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() {
@@ -144,6 +146,65 @@ class PlanApp {
             return viewState;
         });
     }
+    /**
+     * Assigns existing items to existing placeholder rows.
+     *
+     * Runs the plan's own item-assignment pipeline, so the item's properties are mapped onto the
+     * row, the project item is created if needed, and carryover is applied — the same work the grid
+     * does when a user drops an item onto a row. Rows appear updated immediately and the change is
+     * broadcast to other users.
+     *
+     * Use this to fill placeholders that already carry attribution; to create new rows instead, see
+     * {@link addPlaceholders}.
+     *
+     * Requires the plan to be editable.
+     */
+    static assignItems(assignments) {
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            if (!(assignments === null || assignments === void 0 ? void 0 : assignments.length)) {
+                return;
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.ASSIGN_ITEMS,
+                data: { assignments },
+            });
+            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.26",
+  "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",