@contrail/extensions-sdk 1.0.33 → 1.0.34

package/lib/apps/plan.d.ts

@@ -8,7 +8,8 @@ export declare enum PlanCommand {
     GET_PLACEHOLDERS = "plan:get_placeholders",
     GET_VIEW_STATE = "plan:get_view_state",
     ASSIGN_ITEMS = "plan:assign_items",
-    SCROLL_TO_PLACEHOLDER = "plan:scroll_to_placeholder"
+    SCROLL_TO_PLACEHOLDER = "plan:scroll_to_placeholder",
+    UPDATE_PLACEHOLDERS = "plan:update_placeholders"
 }
 /**
  * A row on a plan. Beyond the item linkage below, properties are the org-configured
@@ -43,6 +44,45 @@ export interface PlaceholderItemAssignment {
     /** The item to assign — an item family or an item option. */
     itemId: string;
 }
+/**
+ * Edits to one existing row, keyed by property slug.
+ *
+ * Only two kinds of property can be written this way:
+ *
+ * - `isDropped` — `true` drops the row, `false` restores it.
+ * - Assortment-item properties (`forecast`, `targetVolume`, ...) — plan-placeholder properties
+ *   that also exist on the `assortment-item` type and on neither `item` nor `project-item`.
+ *
+ * Item and project-item properties are refused: edit those entities directly and the plan picks the
+ * change up through propagation.
+ *
+ * Values take the shape {@link PlanApp.getPlaceholders} returns. An object-reference or user-list
+ * property takes the referenced object (with its `id`) or `null`.
+ */
+export interface PlaceholderChange {
+    /** The row to edit. */
+    id: string;
+    changes: {
+        [propertySlug: string]: any;
+    };
+}
+export interface UpdatePlaceholdersOptions {
+    /** Skip the undo/redo entry. Intended for bulk programmatic writes. */
+    skipRecordingUndoRedo?: boolean;
+}
+/** One property edit the plan declined, and why. The row's other edits are still applied. */
+export interface RejectedPlaceholderChange {
+    placeholderId: string;
+    propertySlug: string;
+    /** Human-readable, e.g. `This value is calculated with a formula.` */
+    reason: string;
+}
+export interface UpdatePlaceholdersResult {
+    /** The edited rows as they are after the write, formulas re-evaluated. */
+    placeholders: Array<PlanPlaceholder>;
+    /** Edits refused by the row's own rules — permissions, rule sets, value validation, drop checks. */
+    rejectedChanges: Array<RejectedPlaceholderChange>;
+}
 export interface ScrollToPlaceholderOptions {
     /**
      * Also bring this column into view horizontally.
@@ -155,6 +195,32 @@ export declare class PlanApp {
      * Requires the plan to be editable.
      */
     static assignItems(assignments: Array<PlaceholderItemAssignment>): Promise<void>;
+    /**
+     * Edits existing rows: drops or restores them, and sets assortment-item properties such as
+     * forecasts. See {@link PlaceholderChange} for what can be written.
+     *
+     * Runs the same write path as a grid edit, so formulas re-evaluate, the change is undoable, it is
+     * persisted, and it is broadcast to other users. Resolves once the write has been applied, with
+     * the updated rows.
+     *
+     * Two kinds of failure are reported differently:
+     *
+     * - **Throws, and writes nothing,** when the request is wrong: a row id not on this plan, or a
+     *   property that cannot be written through this method. These are bugs in the caller.
+     * - **Rejects individual edits,** listed in `rejectedChanges`, when a row's own rules refuse them:
+     *   the property is read-only, a formula, or locked by a rule set; the value fails validation; or
+     *   the row cannot be dropped. Every other edit is applied, as a paste into the grid would be.
+     *
+     * ```ts
+     * const { rejectedChanges } = await PlanApp.updatePlaceholders([
+     *   { id: rowA, changes: { isDropped: true } },
+     *   { id: rowB, changes: { forecast: 1200 } },
+     * ]);
+     * ```
+     *
+     * Requires the plan to be editable.
+     */
+    static updatePlaceholders(placeholderChanges: Array<PlaceholderChange>, options?: UpdatePlaceholdersOptions): Promise<UpdatePlaceholdersResult>;
     /**
      * Scrolls the plan's grid so a row is in view.
      *

package/lib/apps/plan.js

@@ -23,6 +23,7 @@ var PlanCommand;
     PlanCommand["GET_VIEW_STATE"] = "plan:get_view_state";
     PlanCommand["ASSIGN_ITEMS"] = "plan:assign_items";
     PlanCommand["SCROLL_TO_PLACEHOLDER"] = "plan:scroll_to_placeholder";
+    PlanCommand["UPDATE_PLACEHOLDERS"] = "plan:update_placeholders";
 })(PlanCommand = exports.PlanCommand || (exports.PlanCommand = {}));
 class PlanApp {
     static getCurrentPlan() {
@@ -172,6 +173,44 @@ class PlanApp {
             PlanApp.validateAndReturnResults(results);
         });
     }
+    /**
+     * Edits existing rows: drops or restores them, and sets assortment-item properties such as
+     * forecasts. See {@link PlaceholderChange} for what can be written.
+     *
+     * Runs the same write path as a grid edit, so formulas re-evaluate, the change is undoable, it is
+     * persisted, and it is broadcast to other users. Resolves once the write has been applied, with
+     * the updated rows.
+     *
+     * Two kinds of failure are reported differently:
+     *
+     * - **Throws, and writes nothing,** when the request is wrong: a row id not on this plan, or a
+     *   property that cannot be written through this method. These are bugs in the caller.
+     * - **Rejects individual edits,** listed in `rejectedChanges`, when a row's own rules refuse them:
+     *   the property is read-only, a formula, or locked by a rule set; the value fails validation; or
+     *   the row cannot be dropped. Every other edit is applied, as a paste into the grid would be.
+     *
+     * ```ts
+     * const { rejectedChanges } = await PlanApp.updatePlaceholders([
+     *   { id: rowA, changes: { isDropped: true } },
+     *   { id: rowB, changes: { forecast: 1200 } },
+     * ]);
+     * ```
+     *
+     * Requires the plan to be editable.
+     */
+    static updatePlaceholders(placeholderChanges, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            if (!(placeholderChanges === null || placeholderChanges === void 0 ? void 0 : placeholderChanges.length)) {
+                return { placeholders: [], rejectedChanges: [] };
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.UPDATE_PLACEHOLDERS,
+                data: { placeholderChanges, options },
+            });
+            return PlanApp.validateAndReturnResults(results);
+        });
+    }
     /**
      * Scrolls the plan's grid so a row is in view.
      *

package/package.json

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