@contrail/extensions-sdk 1.0.27 → 1.0.29

package/lib/apps/boards.d.ts

@@ -8,7 +8,8 @@ export declare enum BoardCommand {
     RECOLOR_IMAGES = "board:recolor_images",
     ADD_CONTENT_TO_ENTITY_FROM_ELEMENTS = "board:add_content_to_entity_from_elements",
     ADD_FRAMES_FROM_TEMPLATE = "board:add_frames_from_template",
-    ADD_ITEMS_TO_CLIPBOARD = "board:add_items_to_clipboard"
+    ADD_ITEMS_TO_CLIPBOARD = "board:add_items_to_clipboard",
+    COMPOSE_CONTENT = "board:compose_content"
 }
 /** Payload for bulk-add items to clipboard (Board and Showcase). */
 export interface ClipboardItemsPayload {
@@ -17,6 +18,59 @@ export interface ClipboardItemsPayload {
         projectItemId?: string | null;
     }>;
 }
+/** One image in a composition, placed in fractions of the output box. */
+export interface ComposeContentLayer {
+    /** The content to draw. The host resolves it to an image, so no URL is needed - and none can
+     * expire between planning the layout and composing it. */
+    contentId: string;
+    /**
+     * Top-left corner as a fraction of the composition box, so `{x: 0.5, y: 0}` is the top middle.
+     *
+     * Fractions rather than pixels: the layout is then independent of whatever size the extension
+     * previewed it at, and the same plan can be reused at any output resolution.
+     */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Size as a fraction of the composition box. `{width: 1, height: 1}` fills it. */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Degrees clockwise about the layer's centre. */
+    rotation?: number;
+    /** 0-1. Defaults to fully opaque. */
+    opacity?: number;
+}
+export interface ComposeContentRequest {
+    /** Drawn back to front: the first layer is behind, the last on top. */
+    layers: Array<ComposeContentLayer>;
+    /**
+     * What the new content is filed against, e.g. `item:<id>`.
+     *
+     * Required: content cannot be created free-floating - the platform derives its access policies
+     * from the holder.
+     */
+    contentHolderReference: string;
+    /** Output size in pixels. The host derives one from the source images when omitted. */
+    outputSize?: {
+        width: number;
+        height: number;
+    };
+    /** Defaults to transparent, which is usually what a composed pack shot wants. */
+    backgroundColor?: string;
+    fileName?: string;
+}
+export interface ComposeContentResult {
+    contentId: string;
+    primaryFileId?: string;
+    primaryFileUrl?: string;
+    size: {
+        width: number;
+        height: number;
+    };
+}
 export interface BoardDocumentElement extends DocumentElement {
     [key: string]: any;
 }
@@ -59,6 +113,28 @@ export declare class BoardsApp {
     static getElements(criteria: object): Promise<Array<DocumentElement>>;
     /** Creates new content from a set of elements and assigns to an entity (item, etc) as a viewable */
     static createNewContentAndAssignToEntity(assignmentOptions: any, entity: any, elements: Array<DocumentElement>): Promise<Array<DocumentElement>>;
+    /**
+     * Composes several contents into one new image, and returns it as a new content.
+     *
+     * The extension supplies a layout - which content goes where, at what size - and the board
+     * rasterises it with the same renderer its own image export uses. Nothing is added to the
+     * board: the elements exist only for the duration of the render.
+     *
+     * This is the way to build a composed image from an extension. Reading the source images into
+     * a canvas the extension owns would taint it and make the export throw, because the image
+     * files are cross-origin.
+     *
+     * ```ts
+     * const composed = await BoardsApp.composeContent({
+     *   layers: [
+     *     { contentId: 'c1', position: { x: 0, y: 0 }, size: { width: 0.6, height: 0.6 } },
+     *     { contentId: 'c2', position: { x: 0.4, y: 0.4 }, size: { width: 0.6, height: 0.6 } },
+     *   ],
+     *   contentHolderReference: `item:${setItem.id}`,
+     * });
+     * ```
+     */
+    static composeContent(request: ComposeContentRequest): Promise<ComposeContentResult>;
     static recolorImages(imageElements: Array<DocumentElement>, hexCode: string, hexMap?: {}): Promise<Array<DocumentElement>>;
     /** Request the host to bulk-add items to the user's clipboard. */
     static addItemsToClipboard(clipboardItems: Array<{

package/lib/apps/boards.js

@@ -22,6 +22,7 @@ var BoardCommand;
     BoardCommand["ADD_CONTENT_TO_ENTITY_FROM_ELEMENTS"] = "board:add_content_to_entity_from_elements";
     BoardCommand["ADD_FRAMES_FROM_TEMPLATE"] = "board:add_frames_from_template";
     BoardCommand["ADD_ITEMS_TO_CLIPBOARD"] = "board:add_items_to_clipboard";
+    BoardCommand["COMPOSE_CONTENT"] = "board:compose_content";
 })(BoardCommand = exports.BoardCommand || (exports.BoardCommand = {}));
 class BoardsApp {
     static getCurrentBoard() {
@@ -92,6 +93,44 @@ class BoardsApp {
             return this.validateAndReturnResults(results);
         });
     }
+    /**
+     * Composes several contents into one new image, and returns it as a new content.
+     *
+     * The extension supplies a layout - which content goes where, at what size - and the board
+     * rasterises it with the same renderer its own image export uses. Nothing is added to the
+     * board: the elements exist only for the duration of the render.
+     *
+     * This is the way to build a composed image from an extension. Reading the source images into
+     * a canvas the extension owns would taint it and make the export throw, because the image
+     * files are cross-origin.
+     *
+     * ```ts
+     * const composed = await BoardsApp.composeContent({
+     *   layers: [
+     *     { contentId: 'c1', position: { x: 0, y: 0 }, size: { width: 0.6, height: 0.6 } },
+     *     { contentId: 'c2', position: { x: 0.4, y: 0.4 }, size: { width: 0.6, height: 0.6 } },
+     *   ],
+     *   contentHolderReference: `item:${setItem.id}`,
+     * });
+     * ```
+     */
+    static composeContent(request) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            BoardsApp.validateBoardContext();
+            if (!((_a = request === null || request === void 0 ? void 0 : request.layers) === null || _a === void 0 ? void 0 : _a.length)) {
+                throw new Error('composeContent requires at least one layer.');
+            }
+            if (!(request === null || request === void 0 ? void 0 : request.contentHolderReference)) {
+                throw new Error('composeContent requires a contentHolderReference, e.g. `item:<id>`.');
+            }
+            const results = yield (0, actions_1.getExtensionActions)().sendMessageToHost({
+                command: BoardCommand.COMPOSE_CONTENT,
+                data: request,
+            });
+            return this.validateAndReturnResults(results);
+        });
+    }
     static recolorImages(imageElements, hexCode, hexMap = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             BoardsApp.validateBoardContext();

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.29",
   "description": "Client library for interfacing with VibeIQ's services and apps from an extension.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",