@contrail/extensions-sdk 1.0.25 → 1.0.27

package/lib/apps/app-context.d.ts

@@ -37,6 +37,43 @@ export interface AppContext {
     };
     user?: User;
 }
+/** One active filter condition on the plan. */
+export interface PlanFilterCriterion {
+    /** The property being filtered, e.g. `gender`. */
+    slug: string;
+    label?: string;
+    propertyType?: string;
+    /**
+     * The condition, as a FilterConditionType value: `equals`, `not_equal_to`, `is_any_of`,
+     * `is_none_of`, `contains`, `starts_with`, `ends_with`, `less_than`, `greater_than`,
+     * `greater_than_or_equal`, `less_than_or_equal`, `is_empty`, `is_not_empty`, `is_in_list`,
+     * `are_any_empty`.
+     */
+    conditionType: string;
+    /** The value compared against. An array for the `is_any_of` / `is_none_of` conditions. */
+    value?: any;
+    /** How this condition joins the previous one. Absent on the first criterion. */
+    conjunction?: 'and' | 'or';
+    includeEmptyValues?: boolean;
+}
+export interface PlanSortCriterion {
+    slug: string;
+    label?: string;
+    /** A SortDirection value: `ASC`, `DESC`, `LIST_ORDER_ASC` or `LIST_ORDER_DESC`. */
+    direction: string;
+}
+/**
+ * What the user is currently looking at, beyond the rows themselves.
+ *
+ * Lets an extension scope itself the way the grid is scoped — e.g. a goals tool can hide goals for
+ * a gender the user has filtered out, rather than reporting them as unmet.
+ */
+export interface PlanViewState {
+    /** True when at least one filter condition is active. */
+    hasFilter: boolean;
+    filters: Array<PlanFilterCriterion>;
+    sorts: Array<PlanSortCriterion>;
+}
 export interface PlanContext {
     id: string;
     name: string;
@@ -46,7 +83,20 @@ export interface PlanContext {
     itemIds?: string[];
     planPlaceholders?: any[];
     filteredPlanPlaceholderIds?: string[];
+    /**
+     * Whether a filter is active.
+     *
+     * @deprecated Superseded by `viewState`, which also says *what* the filter is. Retained because
+     * existing extensions read it; equivalent to `viewState.hasFilter`.
+     */
     hasFilter: boolean;
+    /**
+     * The filter and sorts in effect **when this extension opened**.
+     *
+     * Absent on hosts that predate this field, so guard before reading. For current state — after
+     * the user has changed the filter — `await` {@link PlanApp.getViewState}.
+     */
+    viewState?: PlanViewState;
 }
 export interface BoardContext {
     id: string;

package/lib/apps/index.d.ts

@@ -1,4 +1,4 @@
-export { getAppContext, AppContext, BoardContext, PlanContext, ShowcaseContext, VibeIQAppType } from './app-context';
+export { getAppContext, AppContext, BoardContext, PlanContext, PlanFilterCriterion, PlanSortCriterion, PlanViewState, ShowcaseContext, VibeIQAppType, } from './app-context';
 export * from './boards';
 export * from './plan';
 export * from './showcase';

package/lib/apps/plan.d.ts

@@ -1,11 +1,13 @@
-import { PlanContext } from './app-context';
+import { PlanContext, PlanViewState } from './app-context';
 export declare enum PlanCommand {
     ADD_ROWS = "plan:add_rows",
     SHOW_MESSAGE = "plan:show_message",
     CLEAR_SELECTED_ROWS = "plan:clear_selected_rows",
     ADD_PLACEHOLDERS = "plan:add_placeholders",
     ADD_PLACEHOLDERS_WITH_ITEMS = "plan:add_placeholders_with_items",
-    GET_PLACEHOLDERS = "plan:get_placeholders"
+    GET_PLACEHOLDERS = "plan:get_placeholders",
+    GET_VIEW_STATE = "plan:get_view_state",
+    ASSIGN_ITEMS = "plan:assign_items"
 }
 /**
  * A row on a plan. Beyond the item linkage below, properties are the org-configured
@@ -33,6 +35,13 @@ 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 GetPlaceholdersOptions {
     /** Defaults to `all`. */
     scope?: PlanPlaceholderScope;
@@ -90,6 +99,37 @@ export declare class PlanApp {
      * Reading is always permitted, including on a view-only plan.
      */
     static getPlaceholders(options?: GetPlaceholdersOptions): Promise<Array<PlanPlaceholder>>;
+    /**
+     * The filter and sorts in effect **right now**.
+     *
+     * Use this to scope an extension the way the grid is scoped. If the user has filtered the plan to
+     * `gender = mens`, a goals tool can hide goals for other genders rather than reporting them as
+     * unmet, and can avoid offering to create rows that would immediately fall out of that filter.
+     *
+     * ### How this differs from the launch context
+     *
+     * `getCurrentPlan().viewState` is the state captured when the extension opened — synchronous and
+     * free, but blind to any filter change since. This method round-trips to the host for current
+     * state, and refreshes `viewState` on the cached context so the synchronous read agrees with it
+     * afterwards.
+     *
+     * 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>;
     /**
      * Creates new rows on the plan from property data, and returns them.
      *

package/lib/apps/plan.js

@@ -20,6 +20,8 @@ var PlanCommand;
     PlanCommand["ADD_PLACEHOLDERS"] = "plan:add_placeholders";
     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 = exports.PlanCommand || (exports.PlanCommand = {}));
 class PlanApp {
     static getCurrentPlan() {
@@ -107,6 +109,68 @@ class PlanApp {
             return placeholders;
         });
     }
+    /**
+     * The filter and sorts in effect **right now**.
+     *
+     * Use this to scope an extension the way the grid is scoped. If the user has filtered the plan to
+     * `gender = mens`, a goals tool can hide goals for other genders rather than reporting them as
+     * unmet, and can avoid offering to create rows that would immediately fall out of that filter.
+     *
+     * ### How this differs from the launch context
+     *
+     * `getCurrentPlan().viewState` is the state captured when the extension opened — synchronous and
+     * free, but blind to any filter change since. This method round-trips to the host for current
+     * state, and refreshes `viewState` on the cached context so the synchronous read agrees with it
+     * afterwards.
+     *
+     * Reading is always permitted, including on a view-only plan.
+     */
+    static getViewState() {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            PlanApp.validatePlanContext();
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: PlanCommand.GET_VIEW_STATE,
+            });
+            const viewState = (_a = PlanApp.validateAndReturnResults(results)) !== null && _a !== void 0 ? _a : {
+                hasFilter: false,
+                filters: [],
+                sorts: [],
+            };
+            // getAppContext() hands back the live singleton, so this updates what getCurrentPlan() sees.
+            const plan = (_b = (0, app_context_1.getAppContext)().appContext) === null || _b === void 0 ? void 0 : _b.plan;
+            if (plan) {
+                plan.viewState = viewState;
+            }
+            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);
+        });
+    }
     /**
      * 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.25",
+  "version": "1.0.27",
   "description": "Client library for interfacing with VibeIQ's services and apps from an extension.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",