@uipath/maestro-builder-sdk 6.35.1 → 6.36.1

package/dist/flow-sdk.d.ts

@@ -641,12 +641,12 @@ export type Step = {
 };
 /** One node's designer layout: canvas position, and optionally size and collapsed state. */
 export interface NodeLayout {
-    /** Absolute canvas position. */
+    /** Canvas position; relative to the container for a node inside one. */
     position: {
         x: number;
         y: number;
     };
-    /** Node size; omit for the designer default. */
+    /** Node size; omit to keep compile's 96 × 96. */
     size?: {
         width: number;
         height: number;
@@ -654,6 +654,58 @@ export interface NodeLayout {
     /** Whether the node renders collapsed. */
     collapsed?: boolean;
 }
+/**
+ * A node's layout at a canvas position — the short form of a {@link NodeLayout}
+ * for the `nodes` map of {@link FlowBuilder.layout}.
+ *
+ * @remarks
+ * Positions are canvas pixels. A child's position inside a container is relative
+ * to that container, as the designer stores it; the body of a loop starts inside
+ * the container's padding, at `at(144, 96)`. The size, {@link dim}, is needed by
+ * a container and by an inline agent; every other node is 96 × 96.
+ *
+ * @example
+ * **Lay out a main path on one row, with a side path below it**
+ * ```ts
+ * .layout({
+ *   nodes: {
+ *     start: at(256, 144), fetch: at(448, 144), eachItem: at(640, 144, dim(576, 320)),
+ *     handle: at(144, 96), // inside eachItem, relative to it
+ *     done: at(1312, 144),
+ *     onFailure: at(448, 304),
+ *   },
+ * })
+ * ```
+ *
+ * @param x - The node's left edge on the canvas.
+ * @param y - The node's top edge on the canvas.
+ * @param size - The node's size; omit to keep compile's 96 × 96.
+ * @returns A {@link NodeLayout} to put in `.layout({ nodes })`.
+ */
+export declare function at(x: number, y: number, size?: NodeLayout['size']): NodeLayout;
+/**
+ * A node's size on the canvas, in pixels — the third argument of {@link at}.
+ *
+ * @remarks
+ * Compile writes 96 × 96 on every node and the designer draws the persisted
+ * size, so a node whose canvas shape is larger needs one: a container (a loop
+ * or a do-while body, drawn as a box around its children; `format` makes it
+ * 560 × 320) and an inline agent (`dim(288, 96)`). Every other node is 96 × 96
+ * and needs none.
+ *
+ * @example
+ * **A loop wide enough for a three-step body, then an inline agent**
+ * ```ts
+ * .layout({
+ *   nodes: { eachItem: at(640, 144, dim(768, 320)), review: at(1504, 144, dim(288, 96)) },
+ * })
+ * ```
+ *
+ * @param width - The node's width.
+ * @param height - The node's height.
+ * @returns The `size` of a {@link NodeLayout}.
+ */
+export declare function dim(width: number, height: number): NonNullable<NodeLayout['size']>;
 /** One edge's route: user-dragged bends and/or the auto-router's waypoints. */
 export interface EdgeRoute {
     /** Manually placed bends, in canvas coordinates. Win over the routed set. */
@@ -1331,6 +1383,22 @@ declare class FlowBuilder extends StepList {
      * the serializer's default arrangement. Unknown keys fail compilation rather
      * than being dropped.
      *
+     * Without a layout, compile places every node on one row in emission order,
+     * which reads badly in the designer once a flow has a branch, an error path or
+     * a loop. {@link at} writes a node's entry from two numbers, and {@link dim}
+     * a container's size from two more.
+     *
+     * @example
+     * **Main path on one row, the error handler on the row below**
+     * ```ts
+     * .layout({
+     *   nodes: {
+     *     start: at(256, 144), load: at(448, 144), save: at(640, 144), done: at(832, 144),
+     *     report: at(448, 304), end: at(640, 304),
+     *   },
+     * })
+     * ```
+     *
      * @param layout - Node layout by step name, edge routes by `"from->to"`.
      * @returns This builder, so calls chain.
      */

package/dist/flow-sdk.js

@@ -262,6 +262,62 @@ export function conversationTrigger() {
 export function voiceTrigger() {
     return builtinTriggerSpec({ kind: 'voice' });
 }
+/**
+ * A node's layout at a canvas position — the short form of a {@link NodeLayout}
+ * for the `nodes` map of {@link FlowBuilder.layout}.
+ *
+ * @remarks
+ * Positions are canvas pixels. A child's position inside a container is relative
+ * to that container, as the designer stores it; the body of a loop starts inside
+ * the container's padding, at `at(144, 96)`. The size, {@link dim}, is needed by
+ * a container and by an inline agent; every other node is 96 × 96.
+ *
+ * @example
+ * **Lay out a main path on one row, with a side path below it**
+ * ```ts
+ * .layout({
+ *   nodes: {
+ *     start: at(256, 144), fetch: at(448, 144), eachItem: at(640, 144, dim(576, 320)),
+ *     handle: at(144, 96), // inside eachItem, relative to it
+ *     done: at(1312, 144),
+ *     onFailure: at(448, 304),
+ *   },
+ * })
+ * ```
+ *
+ * @param x - The node's left edge on the canvas.
+ * @param y - The node's top edge on the canvas.
+ * @param size - The node's size; omit to keep compile's 96 × 96.
+ * @returns A {@link NodeLayout} to put in `.layout({ nodes })`.
+ */
+export function at(x, y, size) {
+    return size ? { position: { x, y }, size } : { position: { x, y } };
+}
+/**
+ * A node's size on the canvas, in pixels — the third argument of {@link at}.
+ *
+ * @remarks
+ * Compile writes 96 × 96 on every node and the designer draws the persisted
+ * size, so a node whose canvas shape is larger needs one: a container (a loop
+ * or a do-while body, drawn as a box around its children; `format` makes it
+ * 560 × 320) and an inline agent (`dim(288, 96)`). Every other node is 96 × 96
+ * and needs none.
+ *
+ * @example
+ * **A loop wide enough for a three-step body, then an inline agent**
+ * ```ts
+ * .layout({
+ *   nodes: { eachItem: at(640, 144, dim(768, 320)), review: at(1504, 144, dim(288, 96)) },
+ * })
+ * ```
+ *
+ * @param width - The node's width.
+ * @param height - The node's height.
+ * @returns The `size` of a {@link NodeLayout}.
+ */
+export function dim(width, height) {
+    return { width, height };
+}
 /**
  * The designer's sticky-note palette. Any other string is passed through — the
  * `.flow` format stores `inputs.color` unvalidated — but these five are what the
@@ -952,6 +1008,22 @@ class FlowBuilder extends StepList {
      * the serializer's default arrangement. Unknown keys fail compilation rather
      * than being dropped.
      *
+     * Without a layout, compile places every node on one row in emission order,
+     * which reads badly in the designer once a flow has a branch, an error path or
+     * a loop. {@link at} writes a node's entry from two numbers, and {@link dim}
+     * a container's size from two more.
+     *
+     * @example
+     * **Main path on one row, the error handler on the row below**
+     * ```ts
+     * .layout({
+     *   nodes: {
+     *     start: at(256, 144), load: at(448, 144), save: at(640, 144), done: at(832, 144),
+     *     report: at(448, 304), end: at(640, 304),
+     *   },
+     * })
+     * ```
+     *
      * @param layout - Node layout by step name, edge routes by `"from->to"`.
      * @returns This builder, so calls chain.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.35.1",
+  "version": "6.36.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "cd7797fa2a6443158edfc8920b2e764e34ac6e71"
+  "gitref": "ede4fb3b6b1911bfc170114e086299b28a413d71"
 }