@uipath/maestro-builder-sdk 6.34.0 → 6.35.0

package/dist/check.js

@@ -10,7 +10,7 @@ import { FlowNode } from './core/node-classes.js';
 import { planContributionBindings } from './core/contribution-bindings.js';
 import { definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
 import { actionVersion, bundledActionNodeType, bundledContainerDefinition, bundledDefinition, perCallDefinition, resolveContributionDefinition } from './serialize.js';
-import { FORM_FIELD_TYPES, formFieldOptionsProblem, formFieldOptionsWhy, formFieldTypeHint, formFieldTypeWhy, validFormFieldTypesText } from './core/form-field-type.js';
+import { FORM_FIELD_TYPES, formFieldOptionsProblem, formFieldOptionsWhy, formFieldSettingProblems, formFieldTypeHint, formFieldTypeWhy, validFormFieldTypesText, } from './core/form-field-type.js';
 import { AGENTIC_PROCESS_FORMS } from './core/agentic-process-forms.js';
 import { checkEventResolution, checkEventSubscription, eventParamsFor, } from './core/event-checks.js';
 import { checkCookedEscapes } from './flow-expr-check.js';
@@ -3573,7 +3573,7 @@ function checkInlineAgent(step, inputs, diags, opts = {}, ledger = newResourceId
                         + `${JSON.stringify(f?.type)}, ${formFieldTypeWhy(f?.type, `which the form does not recognize — it would `
                             + `be published as a plain string`)}. Valid: ${validFormFieldTypesText()}.`, formFieldTypeHint(f?.type));
                 }
-                const optionsProblem = formFieldOptionsProblem(f?.type, f?.options);
+                const optionsProblem = formFieldOptionsProblem(f);
                 if (optionsProblem !== undefined) {
                     const message = `Inline agent step "${step}"'s quick-form escalation field "${String(f?.id ?? '?')}" `
                         + `${formFieldOptionsWhy(optionsProblem, f?.type)}.`;
@@ -3583,6 +3583,10 @@ function checkInlineAgent(step, inputs, diags, opts = {}, ledger = newResourceId
                         at('INLINE_AGENT_ESCALATION_FIELD_OPTIONS', message, `options: [{ id: 'opt-1', value: 'high', label: 'High' }, { id: 'opt-2', value: 'low', label: 'Low' }]`);
                     }
                 }
+                for (const problem of formFieldSettingProblems(f)) {
+                    at('INLINE_AGENT_ESCALATION_FIELD_SETTING_INVALID', `Inline agent step "${step}"'s quick-form escalation gives the field "${String(f?.id ?? '?')}" `
+                        + `${problem}. The platform refuses the form.`);
+                }
             }
             continue;
         }

package/dist/core/actions.d.ts

@@ -102,19 +102,114 @@ export interface FormFieldOption {
     /** What the reviewer sees, e.g. `'High'`. */
     label: string;
 }
+/**
+ * How a form field renders (`@uipath/hitl-schema-types` `controlType`). It is a
+ * separate vocabulary from the data `type`: a single choice is `type: 'string'`
+ * with `controlType: 'dropdown'`. When it is absent, the form uses the data
+ * type's default control (or the one a choice spelling such as `singleSelect`
+ * implies).
+ */
+export type FormFieldControlType = 'text' | 'textarea' | 'numberInput' | 'datePicker' | 'dateAndTimePicker' | 'checkbox' | 'dropdown' | 'radioGroup' | 'multiSelect' | 'checkboxGroup' | 'fileUpload';
+/**
+ * One condition of a form-field rule (`@uipath/hitl-schema-types`
+ * `fieldConditionSchema`): `when` names the field it reads, and the other keys
+ * say what that field's value must be.
+ */
+export interface FormFieldCondition {
+    /** The id of the field the condition reads, e.g. `'priority'`. */
+    when: string;
+    /** The value must equal this. */
+    is?: unknown;
+    /** The value must not equal this. */
+    isNot?: unknown;
+    /** The value must be one of these. */
+    in?: unknown[];
+    /** The value must be none of these. */
+    notIn?: unknown[];
+    /** The value must match this regular expression. */
+    matches?: string;
+    /** A custom condition expression, kept as written. */
+    custom?: string;
+}
+/**
+ * A form-field rule (`@uipath/hitl-schema-types` `fieldRuleSchema`): when its
+ * conditions hold, its `effects` apply to the field, for example
+ * `{ visible: true }` or `{ required: true }`.
+ *
+ * @example
+ * hitl({
+ *   fields: [
+ *     { id: 'priority', type: 'singleSelect', direction: 'output', options: [{ id: 'o1', value: 'high', label: 'High' }] },
+ *     {
+ *       id: 'reason', type: 'string', direction: 'output',
+ *       // Required only when the priority is high.
+ *       rules: [{ id: 'rule-1', conditions: [{ when: 'priority', is: 'high' }], effects: { required: true } }],
+ *     },
+ *   ],
+ *   outcomes: ['Done'],
+ * })
+ */
+export interface FormFieldRule {
+    /** The rule's own stable id, e.g. `'rule-1'`. */
+    id: string;
+    /** What must hold for the effects to apply. */
+    conditions: FormFieldCondition[];
+    /** How the conditions combine. The platform's default is `'AND'`. */
+    operator?: 'AND' | 'OR';
+    /** What applies while the conditions hold, keyed by effect (`visible`, `required`, `disabled`). */
+    effects: Record<string, unknown>;
+}
+/**
+ * The form-field keys that say how a field looks and behaves, with the
+ * platform's own names and shapes (`@uipath/hitl-schema-types` `fieldSchemaFor`).
+ * Every one is optional and written to the form row as given, so a field the
+ * canvas saved keeps them through decompile, an edit and compile.
+ *
+ * @example
+ * hitl({
+ *   fields: [{
+ *     id: 'priority', label: 'Priority', type: 'string', direction: 'output', required: true,
+ *     controlType: 'dropdown',
+ *     options: [{ id: 'o1', value: 'high', label: 'High' }, { id: 'o2', value: 'low', label: 'Low' }],
+ *     defaultValue: 'high', colSpan: 6, requiredMessage: 'Pick one',
+ *     description: 'How urgent the invoice is.',
+ *   }],
+ *   outcomes: ['Done'],
+ * })
+ */
+export interface FormFieldSettings {
+    /** Conditions that show, require or disable the field. */
+    rules?: FormFieldRule[];
+    /** The message the form shows when a required field is left empty. */
+    requiredMessage?: string;
+    /** The field's width on the form's 12-column grid: an integer from 1 to 12. Absent means the full width. */
+    colSpan?: number;
+    /**
+     * How the field renders, e.g. `'dropdown'` or `'textarea'`. Absent means the
+     * data type's default control.
+     */
+    controlType?: FormFieldControlType;
+    /**
+     * The choices of a picker field — a `dropdown` / `singleSelect` / `enum`, or a
+     * `multiSelect`. Written to the form verbatim, in order.
+     */
+    options?: FormFieldOption[];
+    /**
+     * The value the form starts with: one `options` value for a single-choice
+     * field, a list of them for a multi-select, or the starting text.
+     */
+    defaultValue?: string | string[];
+    /** Guidance for an agent that pre-fills the field. */
+    description?: string;
+}
 /** A value the reviewer READS: shown on the form, filled in from the flow. */
-export interface ShownField {
+export interface ShownField extends FormFieldSettings {
     /** Field id — the key the answer object uses. Must be unique on the form. */
     id: string;
     /** Label the reviewer sees. Defaults to `id`. */
     label?: string;
     type: FormFieldType;
     direction: 'input';
-    /**
-     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
-     * `multiSelect`. Written to the form verbatim, in order.
-     */
-    options?: FormFieldOption[];
     /**
      * What to show — a reference, e.g. `input('amount')` or
      * `out('fetchInvoice', 'body.total')`. Required: a shown field with nothing
@@ -124,18 +219,13 @@ export interface ShownField {
     value: Expr;
 }
 /** A value the reviewer FILLS IN: read downstream with `out('<step>', '<id>')`. */
-export interface AskedField {
+export interface AskedField extends FormFieldSettings {
     /** Field id — the key the answer object uses. Must be unique on the form. */
     id: string;
     /** Label the reviewer sees. Defaults to `id`. */
     label?: string;
     type: FormFieldType;
     direction: 'output';
-    /**
-     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
-     * `multiSelect`. Written to the form verbatim, in order.
-     */
-    options?: FormFieldOption[];
     /** Reviewer must fill it in before the task can be completed. */
     required?: boolean;
 }
@@ -145,18 +235,13 @@ export interface AskedField {
  * answer. Read it downstream with `out('<step>', '<id>')` — the write target is
  * the field's own id, deliberately decoupled from where the pre-fill came from.
  */
-export interface InOutField {
+export interface InOutField extends FormFieldSettings {
     /** Field id — the key the answer object uses. Must be unique on the form. */
     id: string;
     /** Label the reviewer sees. Defaults to `id`. */
     label?: string;
     type: FormFieldType;
     direction: 'inOut';
-    /**
-     * The choices of a picker field — a `singleSelect` / `enum` dropdown or a
-     * `multiSelect`. Written to the form verbatim, in order.
-     */
-    options?: FormFieldOption[];
     /** What to pre-fill — a reference, e.g. `out('fetchInvoice', 'body.total')`. */
     value: Expr;
     /** Reviewer must confirm/fill it before the task can be completed. */

package/dist/core/form-field-type.d.ts

@@ -26,7 +26,7 @@
  * agent quick-form escalations), decompile, and the serializers' output
  * schemas.
  */
-import type { CanonicalFormFieldType, ControlFormFieldType, FormFieldOption } from './actions.js';
+import type { CanonicalFormFieldType, ControlFormFieldType, FormFieldControlType, FormFieldSettings } from './actions.js';
 /** The product's 11 canonical quick-form field types, in its own order. */
 export declare const CANONICAL_FORM_FIELD_TYPES: CanonicalFormFieldType[];
 /** The SDK's legacy spellings (`text`, `date-time`), for diagnostics that list them. */
@@ -117,48 +117,50 @@ export declare function formFieldJsonSchema(type: unknown): {
     format?: string;
 } | undefined;
 /**
- * A picker field's choices as the form row carries them (`options`, each
- * `{ id, value, label }` — the product's `optionShape`), copied so the wire
- * never aliases the author's array. `undefined` when the field has none.
- * Both serializers (human task, quick-form escalation) write through this.
+ * Every key of a quick-form field row, in the platform's own order
+ * (`@uipath/hitl-schema-types` 1.2.0 `fieldSchemaFor`). The contract test
+ * compares this list with the real package, so a key added upstream fails
+ * there until the SDK decides how to carry it.
  */
-export declare function formFieldOptionsWire(options: readonly FormFieldOption[] | undefined): FormFieldOption[] | undefined;
+export declare const FORM_FIELD_ROW_KEYS: readonly ["id", "type", "label", "direction", "required", "variable", "binding", "value", "rules", "requiredMessage", "colSpan", "controlType", "options", "defaultValue", "description"];
+/** The platform's controls (`controlType`), in its own order. */
+export declare const FORM_FIELD_CONTROL_TYPES: readonly FormFieldControlType[];
 /**
- * A form row's `options` read back for source: the well-formed choices
- * (string `id`, `value`, `label` — all three the product requires), or
- * `undefined` when the row has no `options` array. A malformed entry is left
- * out, not coerced: `{ id: 'o1', value: 1 }` is not rewritten to
- * `value: '1', label: ''`. Decompile (human task and quick-form escalation)
- * reads through this, so a canvas dropdown's choices survive an edit.
+ * Each settings key a field sets to a value the platform's schema refuses, as
+ * `key: value (what it must be)`. Empty when every setting is valid. `check`
+ * reports these: a form with one fails the platform's validation.
  *
  * @example
- * liftFormFieldOptions([{ id: 'o1', value: 'a', label: 'A' }, { id: 'o2', value: 2 }])
- * // [{ id: 'o1', value: 'a', label: 'A' }]
+ * formFieldSettingProblems({ colSpan: 13 }) // ['colSpan: 13 (must be an integer from 1 to 12 …)']
  */
-export declare function liftFormFieldOptions(raw: unknown): FormFieldOption[] | undefined;
+export declare function formFieldSettingProblems(f: unknown): string[];
+/** The `FormFieldSettings` keys, in the platform's row order. */
+export declare const FORM_FIELD_SETTINGS_KEYS: (keyof FormFieldSettings)[];
 /**
- * What is wrong with a form field's `options`, or `undefined` when nothing is.
- * `check` reports each (human task and quick-form escalation):
+ * What is wrong with a form field's choices, or `undefined` when nothing is.
+ * `check` reports each (human task and quick-form escalation). A field is a
+ * picker when its type is a choice-control spelling (`singleSelect`,
+ * `multiSelect`, `enum`) or its `controlType` is a picker control (`dropdown`,
+ * `radioGroup`, `multiSelect`, `checkboxGroup`).
  *
- * - `'malformed'`: `options` is there but is not an array of `{ id, value,
- *   label }` strings. Serialize would throw or write rows the platform refuses.
- * - `'missing'`: a choice-control type (`singleSelect`, `multiSelect`, `enum`)
- *   with no choices. The form publishes an empty picker.
- * - `'ignored'`: choices on a type that is not a choice control. The form
- *   renders a plain input and never shows them.
+ * - `'missing'`: a picker with no choices. The form publishes an empty picker.
+ * - `'ignored'`: choices on a field that is not a picker. The form renders a
+ *   plain input and never shows them.
+ *
+ * `options` that do not have the platform's shape are reported by
+ * `formFieldSettingProblems` instead, so they get no second diagnostic here.
  *
  * @example
- * formFieldOptionsProblem('singleSelect', undefined)                         // 'missing'
- * formFieldOptionsProblem('singleSelect', {})                                // 'malformed'
- * formFieldOptionsProblem('string', [{ id: 'o1', value: 'a', label: 'A' }]) // 'ignored'
- * formFieldOptionsProblem('enum', [{ id: 'o1', value: 'a', label: 'A' }])   // undefined
+ * formFieldOptionsProblem({ type: 'singleSelect' })                                         // 'missing'
+ * formFieldOptionsProblem({ type: 'string', options: [{ id: 'o1', value: 'a', label: 'A' }] }) // 'ignored'
+ * formFieldOptionsProblem({ type: 'string', controlType: 'dropdown', options: [{ id: 'o1', value: 'a', label: 'A' }] }) // undefined
  */
-export declare function formFieldOptionsProblem(type: unknown, options: unknown): 'malformed' | 'missing' | 'ignored' | undefined;
+export declare function formFieldOptionsProblem(f: unknown): 'missing' | 'ignored' | undefined;
 /**
  * The reason text for a `formFieldOptionsProblem`, worded for a diagnostic
  * that starts "… the field "<id>" …".
  */
-export declare function formFieldOptionsWhy(problem: 'malformed' | 'missing' | 'ignored', type: unknown): string;
+export declare function formFieldOptionsWhy(problem: 'missing' | 'ignored', type: unknown): string;
 /**
  * The spelling a form field's type is written in on the wire: the product's
  * canonical one for the SDK's legacy spellings (`text` is written `string`,
@@ -173,3 +175,49 @@ export declare function formFieldOptionsWhy(problem: 'malformed' | 'missing' | '
  * wireFormFieldType('number')    // 'number'
  */
 export declare function wireFormFieldType(type: unknown): unknown;
+/**
+ * A field's settings as the form row carries them: each key the author set,
+ * in the platform's row order, copied so the wire never aliases the author's
+ * objects. Both serializers (human task, quick-form escalation) append this
+ * after the row's own keys.
+ *
+ * @example
+ * formFieldSettingsWire({ colSpan: 6, controlType: 'dropdown' }) // { colSpan: 6, controlType: 'dropdown' }
+ */
+export declare function formFieldSettingsWire(f: FormFieldSettings): Record<string, unknown>;
+/**
+ * A form row's settings read back for source: each settings key whose value
+ * has the platform's shape, copied, without any key the platform's schema does
+ * not define. A key with any other value is left out here; both cases are
+ * reported by `formFieldRowLoss`.
+ */
+export declare function liftFormFieldSettings(row: Record<string, unknown>): FormFieldSettings;
+/**
+ * A field's settings as source options, in the platform's row order, for the
+ * decompilers' printers. `value` prints one data value (`'high'`, `6`,
+ * `[{ id: 'o1', … }]`).
+ */
+export declare function formFieldSettingsSource(settings: FormFieldSettings, value: (v: unknown) => string): Array<[string, string | undefined]>;
+/**
+ * Where a form row lives, which decides which of its binding keys the SDK
+ * derives: a human task writes `binding` for a shown or pre-filled field and
+ * `variable: 'vars.<id>'` for an asked one; a quick-form escalation writes
+ * neither (the agent fills the form).
+ */
+export type FormRowSite = 'human task' | 'escalation';
+/**
+ * The keys of a form row the SDK cannot carry into source, each with why.
+ * Empty when decompile → compile writes the row back as it was. The lifts
+ * report a non-empty list as a warning (an error under `--strict`), so no key
+ * is dropped silently.
+ *
+ * @example
+ * formFieldRowLoss({ id: 'a', label: 'A', type: 'string', direction: 'output', colSpan: 13 }, 'human task')
+ * // ['colSpan: 13 (not the platform\'s shape for it)']
+ */
+export declare function formFieldRowLoss(row: Record<string, unknown>, site: FormRowSite): string[];
+/**
+ * The warning (or `--strict` error) for a row `formFieldRowLoss` reported.
+ * `where` names the form, e.g. `human task "review"`.
+ */
+export declare function formFieldRowLossMessage(where: string, fieldId: string, loss: readonly string[]): string;