@epistola.app/valtimo-plugin 0.9.4 → 0.11.0

package/lib/components/check-job-status-configuration/check-job-status-configuration.component.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { FunctionConfigurationComponent } from '@valtimo/plugin';
+import { FunctionConfigurationComponent, FunctionConfigurationData } from '@valtimo/plugin';
 import { FormOutput } from '@valtimo/components';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { CheckJobStatusConfig } from '../../models';
@@ -10,7 +10,7 @@ export declare class CheckJobStatusConfigurationComponent implements FunctionCon
     pluginId: string;
     prefillConfiguration$: Observable<CheckJobStatusConfig>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<CheckJobStatusConfig>;
+    configuration: EventEmitter<FunctionConfigurationData>;
     private saveSubscription;
     private readonly formValue$;
     private readonly valid$;

package/lib/components/download-document-configuration/download-document-config.util.d.ts

@@ -0,0 +1,15 @@
+import { DownloadDocumentConfig } from '../../models';
+/**
+ * Pure helpers for the download-document configurator, extracted so they can be unit-tested
+ * without the Angular component (mirrors the process-link-selector util pattern). See
+ * `docs/adr/0001-download-document-content-storage.md`.
+ */
+export type StorageTarget = 'TEMPORARY_RESOURCE' | 'PROCESS_VARIABLE';
+export declare const DEFAULT_STORAGE_TARGET: StorageTarget;
+/** Normalize a (possibly undefined) storageTarget to a concrete target, applying the default. */
+export declare function resolveStorageTarget(target?: string): StorageTarget;
+/**
+ * A config is valid when the input variable and the output variable that matches the chosen
+ * storage target are both set.
+ */
+export declare function isDownloadDocumentConfigValid(config: Partial<DownloadDocumentConfig> | null | undefined): boolean;

package/lib/components/download-document-configuration/download-document-configuration.component.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { FunctionConfigurationComponent } from '@valtimo/plugin';
-import { FormOutput } from '@valtimo/components';
+import { FunctionConfigurationComponent, FunctionConfigurationData } from '@valtimo/plugin';
+import { FormOutput, SelectItem } from '@valtimo/components';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { DownloadDocumentConfig } from '../../models';
 import * as i0 from "@angular/core";
@@ -10,7 +10,7 @@ export declare class DownloadDocumentConfigurationComponent implements FunctionC
     pluginId: string;
     prefillConfiguration$: Observable<DownloadDocumentConfig>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<DownloadDocumentConfig>;
+    configuration: EventEmitter<FunctionConfigurationData>;
     private saveSubscription;
     private readonly formValue$;
     private readonly valid$;
@@ -22,6 +22,15 @@ export declare class DownloadDocumentConfigurationComponent implements FunctionC
     resolvedPrefill: Partial<DownloadDocumentConfig>;
     readonly prefillResolved$: BehaviorSubject<boolean>;
     safeDisabled$: Observable<boolean>;
+    /**
+     * Static option set for the storage target. Values match the backend
+     * {@code DocumentStorageTarget} enum constants; labels are explained further via the
+     * translated field title/tooltip.
+     */
+    readonly storageTargetOptions: SelectItem[];
+    readonly defaultStorageTarget: import("./download-document-config.util").StorageTarget;
+    /** Drives which output-variable field is shown (resource id vs inline content). */
+    readonly selectedTarget$: BehaviorSubject<string>;
     ngOnInit(): void;
     ngOnDestroy(): void;
     formValueChange(formOutput: FormOutput): void;

package/lib/components/epistola-admin-page/epistola-admin-page.component.d.ts

@@ -1,7 +1,7 @@
 import { OnInit } from '@angular/core';
 import { ActivatedRoute, Router } from '@angular/router';
 import { EpistolaAdminService } from '../../services/epistola-admin.service';
-import { BpmnValidationViolation, ChangelogRelease, ClasspathCatalog, PendingJob, PluginUsageEntry } from '../../models';
+import { BpmnValidationReport, BpmnValidationViolation, ChangelogRelease, ClasspathCatalog, FormCarrierIssue, LegacyOverrideForm, PendingJob, PluginUsageEntry } from '../../models';
 import * as i0 from "@angular/core";
 /**
  * Combined view model for a single plugin configuration card.
@@ -26,12 +26,12 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     cards: ConfigurationCard[];
     selectedCard: ConfigurationCard | null;
     activeTab: 'actions' | 'pending' | 'catalogs';
-    overviewTab: 'configurations' | 'validations' | 'changelog';
+    overviewTab: 'configurations' | 'validations' | 'changelog' | 'forms';
     loading: boolean;
     pluginVersion: string | null;
     changelog: ChangelogRelease[] | null;
     changelogLoading: boolean;
-    validationViolations: BpmnValidationViolation[];
+    validationReport: BpmnValidationReport | null;
     reconcilingExecutionIds: Set<string>;
     reconcileFeedback: {
         executionId: string;
@@ -46,6 +46,17 @@ export declare class EpistolaAdminPageComponent implements OnInit {
         type: 'success' | 'error';
         message: string;
     } | null;
+    formIssues: FormCarrierIssue[] | null;
+    formIssuesLoading: boolean;
+    repairingFormIds: Set<string>;
+    repairingAll: boolean;
+    formFeedback: {
+        formId: string;
+        type: 'success' | 'error';
+        message: string;
+    } | null;
+    legacyOverrideForms: LegacyOverrideForm[] | null;
+    legacyOverrideLoading: boolean;
     private connectionStatuses;
     private usageEntries;
     private pendingJobs;
@@ -54,11 +65,24 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     private pendingLoaded;
     private deepLinkConfigId;
     constructor(adminService: EpistolaAdminService, route: ActivatedRoute, router: Router);
+    /** Violations from the latest report (empty when healthy or not yet loaded). */
+    get validationViolations(): BpmnValidationViolation[];
+    /** Scan cadence in whole minutes, for the "refreshes every N min" note. */
+    get refreshIntervalMinutes(): number;
+    /** Combined "forms needing attention" count for the tab badge (carrier + legacy override). */
+    get formsAttentionCount(): number;
+    /** Whether the forms tab has loaded at least one of its two scans. */
+    get formsScanLoaded(): boolean;
     ngOnInit(): void;
     selectConfiguration(card: ConfigurationCard): void;
     backToOverview(): void;
     setActiveTab(tab: 'actions' | 'pending' | 'catalogs'): void;
-    setOverviewTab(tab: 'configurations' | 'validations' | 'changelog'): void;
+    setOverviewTab(tab: 'configurations' | 'validations' | 'changelog' | 'forms'): void;
+    private loadLegacyOverrideForms;
+    private loadFormIssues;
+    isRepairingForm(issue: FormCarrierIssue): boolean;
+    repairForm(issue: FormCarrierIssue): void;
+    repairAllForms(): void;
     private loadChangelog;
     refresh(): void;
     exportProcessLink(entry: PluginUsageEntry): void;

package/lib/components/epistola-configuration/epistola-configuration.component.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { PluginConfigurationComponent } from '@valtimo/plugin';
+import { PluginConfigurationComponent, PluginConfigurationData } from '@valtimo/plugin';
 import { FormOutput } from '@valtimo/components';
 import { Observable } from 'rxjs';
 import { EpistolaPluginConfig } from '../../models';
@@ -10,7 +10,7 @@ export declare class EpistolaConfigurationComponent implements PluginConfigurati
     pluginId: string;
     prefillConfiguration$: Observable<EpistolaPluginConfig>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<EpistolaPluginConfig>;
+    configuration: EventEmitter<PluginConfigurationData>;
     /** Epistola slug pattern: lowercase alphanumeric with hyphens, no leading/trailing hyphens. */
     private static readonly SLUG_PATTERN;
     private saveSubscription;

package/lib/components/epistola-document/epistola-document.component.d.ts

@@ -1,7 +1,7 @@
-import { ChangeDetectorRef, EventEmitter, OnDestroy, OnInit } from '@angular/core';
+import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
 import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
+import { EpistolaPluginService } from '../../services';
 import * as i0 from "@angular/core";
 export type EpistolaDocumentDisplay = 'inline' | 'button' | 'both';
 /**
@@ -20,11 +20,10 @@ export type EpistolaDocumentDisplay = 'inline' | 'button' | 'both';
  * <p>For the dry-run / what-would-be-generated UX use
  * {@code epistola-document-preview} instead.
  */
-export declare class EpistolaDocumentComponent implements FormioCustomComponent<unknown>, OnInit, OnDestroy {
+export declare class EpistolaDocumentComponent implements FormioCustomComponent<unknown>, OnChanges, OnDestroy {
     private readonly epistolaPluginService;
     private readonly sanitizer;
     private readonly formIoStateService;
-    private readonly taskContext;
     private readonly cdr;
     value: unknown;
     valueChange: EventEmitter<unknown>;
@@ -45,6 +44,11 @@ export declare class EpistolaDocumentComponent implements FormioCustomComponent<
     tenantIdVariable: string;
     /** Filename used for the download disposition. */
     filename: string;
+    /**
+     * Task id forwarded by the Formio wrapper from the server-prefilled form
+     * ({@code epistola:taskId} value resolver), populated in every Valtimo task-open flow.
+     */
+    taskInstanceId?: string | null;
     loading: boolean;
     downloading: boolean;
     error: string | null;
@@ -52,8 +56,8 @@ export declare class EpistolaDocumentComponent implements FormioCustomComponent<
     private currentBlobUrl;
     private subscription?;
     get designMode(): boolean;
-    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, taskContext: EpistolaTaskContextService, cdr: ChangeDetectorRef);
-    ngOnInit(): void;
+    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef);
+    ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     refresh(): void;
     download(): void;
@@ -61,5 +65,5 @@ export declare class EpistolaDocumentComponent implements FormioCustomComponent<
     private buildRequest;
     private revokeBlobUrl;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaDocumentComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentComponent, "epistola-document-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "display": { "alias": "display"; "required": false; }; "documentVariable": { "alias": "documentVariable"; "required": false; }; "tenantIdVariable": { "alias": "tenantIdVariable"; "required": false; }; "filename": { "alias": "filename"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentComponent, "epistola-document-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "display": { "alias": "display"; "required": false; }; "documentVariable": { "alias": "documentVariable"; "required": false; }; "tenantIdVariable": { "alias": "tenantIdVariable"; "required": false; }; "filename": { "alias": "filename"; "required": false; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

package/lib/components/epistola-document-preview/epistola-document-preview.component.d.ts

@@ -1,21 +1,55 @@
 import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
 import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
+import { EpistolaPluginService } from '../../services';
 import * as i0 from "@angular/core";
 export declare class EpistolaDocumentPreviewComponent implements FormioCustomComponent<Record<string, any> | null>, OnChanges, OnDestroy {
     private readonly epistolaPluginService;
     private readonly sanitizer;
     private readonly formIoStateService;
     private readonly cdr;
-    private readonly taskContext;
     value: Record<string, any> | null;
     valueChange: EventEmitter<Record<string, any>>;
     disabled: boolean;
     label: string;
     processDefinitionKey?: string;
     sourceActivityId?: string;
-    overrideMapping?: Record<string, any>;
+    /**
+     * The override mapping: a JSONata expression string over `$form`, or — for
+     * not-yet-re-saved forms — the legacy `form:`-ref object.
+     */
+    overrideMapping?: string | Record<string, any>;
+    /**
+     * Task id forwarded by the Formio wrapper from the server-prefilled form
+     * ({@code epistola:taskId} value resolver), populated in every Valtimo task-open flow.
+     */
+    taskInstanceId?: string | null;
+    /**
+     * The computed input overrides (`{ doc, pv }`) the preview renders with, pushed
+     * by the Formio wrapper. Kept separate from the Formio `value`: Valtimo's custom
+     * component bridge only mirrors `value` to the DOM (never to Formio's data
+     * model), so Formio resets it to `emptyValue` on every redraw — which would
+     * cancel the preview. This dedicated input is never touched by Formio.
+     */
+    inputOverrides?: Record<string, any> | null;
+    /**
+     * Forces the Formio wrapper to recompute the input overrides from the live form
+     * data. Set by the wrapper for override-driven previews; lets the Refresh button
+     * work before the first change (e.g. on initial load with pre-filled fields).
+     */
+    requestOverrides?: () => void;
+    /**
+     * Current auto-refresh state, forwarded by the wrapper (seeded from the builder's
+     * `autoRefresh` option, default on). Seeds the header toggle's initial state.
+     */
+    autoRefresh?: boolean;
+    /**
+     * Tells the wrapper to enable/disable auto-refresh (recompute on change/blur).
+     * Set by the wrapper for override-driven previews; called by the header toggle.
+     */
+    setAutoRefresh?: (enabled: boolean) => void;
+    /** Runtime state of the header auto-refresh toggle. */
+    autoRefreshEnabled: boolean;
     loading: boolean;
     error: string | null;
     previewUrl: SafeResourceUrl | null;
@@ -23,21 +57,31 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     private initialized;
     private currentBlobUrl;
     private previewSubscription?;
-    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef, taskContext: EpistolaTaskContextService);
+    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef);
     /**
-     * Resolve the active task id from {@link EpistolaTaskContextService}, populated
-     * by {@code EpistolaTaskContextInterceptor} on the canonical Valtimo task-open
-     * call. Returns null when used outside a task context (e.g. Formio builder).
+     * The active task id, forwarded by the Formio wrapper from the server-prefilled
+     * form ({@code epistola:taskId} value resolver). Null outside a task context
+     * (e.g. Formio builder), in which case the component fails closed.
      */
     private get currentTaskId();
-    get overrideMappingScopes(): string[];
-    overrideMappingEntries(scope: string): {
-        path: string;
-        field: string;
-    }[];
+    /**
+     * The override mapping as a JSONata expression for the design-mode summary.
+     * Legacy `form:`-ref objects are converted on the fly for display.
+     */
+    get overrideExpression(): string;
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     refresh(): void;
+    /** Toggle auto-refresh for this session; flipping it on triggers an immediate refresh. */
+    onToggleAutoRefresh(event: Event): void;
+    /**
+     * Load the preview only when there is enough data for it. Override-driven
+     * previews (those with an override mapping) wait until the mapped form data
+     * has been computed; until then they show a placeholder rather than firing a
+     * request that Epistola would reject with a 400 for missing required fields.
+     */
+    private triggerPreview;
+    private showWaitingForInput;
     /**
      * Preview using the explicitly configured process link + input overrides.
      * Requires a runtime task context — the backend authorizes the request against
@@ -48,5 +92,5 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     private handlePreviewError;
     private revokeBlobUrl;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaDocumentPreviewComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentPreviewComponent, "epistola-document-preview-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "overrideMapping": { "alias": "overrideMapping"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentPreviewComponent, "epistola-document-preview-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "overrideMapping": { "alias": "overrideMapping"; "required": false; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; "inputOverrides": { "alias": "inputOverrides"; "required": false; }; "requestOverrides": { "alias": "requestOverrides"; "required": false; }; "autoRefresh": { "alias": "autoRefresh"; "required": false; }; "setAutoRefresh": { "alias": "setAutoRefresh"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

package/lib/components/epistola-document-preview/preview-utils.d.ts

@@ -1,5 +1,10 @@
-import { OverrideMapping } from '../override-builder/override-builder.component';
-export declare const FORM_REF_PREFIX = "form:";
+/** Re-exported for backward compatibility with existing imports/tests. */
+export { FORM_REF_PREFIX } from '../override-builder/legacy-override-converter';
+/**
+ * An override mapping is either the new JSONata expression **string** (over
+ * `$form`) or — for not-yet-re-saved forms — the legacy `form:`-ref **object**.
+ */
+export type OverrideMappingValue = string | Record<string, any> | null | undefined;
 /**
  * Detect if a string value is a JSONata expression (vs a plain literal).
  * Checks for characters that indicate JSONata operators: $, &, (, {, ?, [
@@ -11,8 +16,36 @@ export declare function isExpression(value: string): boolean;
  */
 export declare function expandDotNotation(flat: Record<string, any>): Record<string, any>;
 /**
- * Given an override mapping (scope -> { inputPath -> "form:<componentKey>" })
- * and form data, produce the inputOverrides object for the backend.
- * The "form:" prefix identifies form field references; the remainder is the Formio component key.
+ * A preview is "override-driven" when it has a non-empty override mapping: its
+ * input data comes from the form via the mapping, so it must wait for that data
+ * before it can render. Previews without a mapping load straight from the base
+ * doc/case data.
+ */
+export declare function isOverrideDriven(mapping?: OverrideMappingValue): boolean;
+/**
+ * Whether the computed input overrides carry any usable data yet.
+ */
+export declare function hasUsableOverrides(overrides?: Record<string, any> | null): boolean;
+/**
+ * Decide whether a preview request should fire given the configured override
+ * mapping and the currently computed overrides.
+ *
+ * - Override-driven previews only load once the mapped form data is present;
+ *   before that they show a "complete the form" placeholder and fire nothing
+ *   (avoids a doomed request that Epistola rejects with a 400 for missing
+ *   required fields).
+ * - Previews without a mapping always load (base data is the whole input).
+ */
+export declare function shouldLoadPreview(mapping?: OverrideMappingValue, overrides?: Record<string, any> | null): boolean;
+/**
+ * Given an override mapping and the live form data, produce the inputOverrides
+ * object (`{ doc, pv }`) the backend overlays onto the real document / process
+ * variables before the data mapping runs.
+ *
+ * The mapping is a JSONata expression over `$form`; legacy `form:`-ref objects
+ * are converted on the fly via {@link legacyOverrideToJsonata}. Evaluation is
+ * asynchronous because `jsonata().evaluate()` returns a Promise. Only `doc` and
+ * `pv` scopes (with at least one resolved field) are kept — matching what the
+ * backend consumes.
  */
-export declare function computeInputOverrides(mapping: OverrideMapping, formData: Record<string, any>): Record<string, any>;
+export declare function computeInputOverrides(mapping: OverrideMappingValue, formData: Record<string, any>): Promise<Record<string, any>>;

package/lib/components/epistola-retry-form/epistola-retry-form.component.d.ts

@@ -1,19 +1,22 @@
 import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
-import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
+import { FormioCustomComponent } from '@valtimo/components';
+import { EpistolaPluginService } from '../../services';
 import * as i0 from "@angular/core";
 export declare class EpistolaRetryFormComponent implements FormioCustomComponent<string>, OnChanges, OnDestroy {
     private readonly epistolaPluginService;
-    private readonly formIoStateService;
     private readonly cdr;
     private readonly sanitizer;
-    private readonly taskContext;
     value: string;
     valueChange: EventEmitter<string>;
     disabled: boolean;
     label: string;
     sourceActivityId?: string;
+    /**
+     * Task id forwarded by the Formio wrapper from the server-prefilled form
+     * ({@code epistola:taskId} value resolver), populated in every Valtimo task-open flow.
+     */
+    taskInstanceId?: string | null;
     formDefinition: any;
     submission: any;
     loading: boolean;
@@ -28,9 +31,8 @@ export declare class EpistolaRetryFormComponent implements FormioCustomComponent
     private previewSubject;
     private currentBlobUrl;
     private resolvedSourceActivityId?;
-    private processDefinitionKey?;
     formOptions: any;
-    constructor(epistolaPluginService: EpistolaPluginService, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef, sanitizer: DomSanitizer, taskContext: EpistolaTaskContextService);
+    constructor(epistolaPluginService: EpistolaPluginService, cdr: ChangeDetectorRef, sanitizer: DomSanitizer);
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     togglePreview(): void;
@@ -38,5 +40,5 @@ export declare class EpistolaRetryFormComponent implements FormioCustomComponent
     private loadPreview;
     private loadForm;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaRetryFormComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaRetryFormComponent, "epistola-retry-form-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaRetryFormComponent, "epistola-retry-form-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

package/lib/components/formio-builder-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hides a registered custom Formio component from the builder's component palette,
+ * while keeping it fully usable inside other components' `editForm`s and at runtime.
+ *
+ * Formio's `WebformBuilder` only adds a component to the palette when
+ * `component.builderInfo && component.builderInfo.schema` is truthy. Overriding the
+ * registered class's static `builderInfo` getter to `false` therefore removes it from
+ * the palette. Runtime instantiation and editForm usage don't consult `builderInfo`,
+ * so they are unaffected.
+ *
+ * Call this AFTER the component is registered (and after any `setComponent` re-registration),
+ * so it targets the final class in `Formio.Components.components[type]`.
+ */
+export declare function hideFormioComponentFromBuilder(type: string): void;

package/lib/components/generate-document-configuration/generate-document-configuration.component.d.ts

@@ -1,5 +1,5 @@
 import { ChangeDetectorRef, EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { FunctionConfigurationComponent, PluginConfigurationData } from '@valtimo/plugin';
+import { FunctionConfigurationComponent, FunctionConfigurationData, PluginConfigurationData } from '@valtimo/plugin';
 import { FormOutput, SelectedValue, SelectItem } from '@valtimo/components';
 import { CaseManagementParams, ManagementContext } from '@valtimo/shared';
 import { ProcessLinkStateService } from '@valtimo/process-link';
@@ -19,7 +19,7 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
     selectedPluginConfigurationData$?: Observable<PluginConfigurationData>;
     context$?: Observable<[ManagementContext, CaseManagementParams]>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<GenerateDocumentConfig>;
+    configuration: EventEmitter<FunctionConfigurationData>;
     catalogs$: BehaviorSubject<AsyncResource<SelectItem[]>>;
     templates$: BehaviorSubject<AsyncResource<SelectItem[]>>;
     variants$: BehaviorSubject<AsyncResource<SelectItem[]>>;
@@ -68,6 +68,8 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
     processVariables: string[];
     expressionFunctions: ExpressionFunctionInfo[];
     variableSuggestions: VariableSuggestions | null;
+    /** Context variables for the JSONata editor's autocomplete ($doc/$pv/$case). */
+    editorContextVariables: Record<string, string[]>;
     prefillDataMapping: Record<string, any>;
     validationErrors$: BehaviorSubject<JsonataFieldError[]>;
     private readonly destroy$;

package/lib/components/jsonata-editor/jsonata-editor.component.d.ts

@@ -1,11 +1,19 @@
 import { EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
-import { ExpressionFunctionInfo, VariableSuggestions } from '../../models';
+import { ExpressionFunctionInfo } from '../../models';
 import * as i0 from "@angular/core";
 export declare class JsonataEditorComponent implements OnChanges, OnDestroy {
     expression: string;
     disabled: boolean;
-    suggestions: VariableSuggestions | null;
+    /**
+     * Context variables in scope, keyed by name (without `$`), each mapping to its
+     * field/path suggestions — e.g. `{ doc: [...], pv: [...] }` for the data
+     * mapping, `{ form: [...] }` for the override builder. Drives both the
+     * `$`-variable list and `$<name>.` field completion.
+     */
+    contextVariables: Record<string, string[]>;
     functions: ExpressionFunctionInfo[];
+    /** Footer hint listing the context variables in scope. */
+    variablesHint: string;
     expressionChange: EventEmitter<string>;
     validChange: EventEmitter<boolean>;
     editorModel: {
@@ -25,5 +33,5 @@ export declare class JsonataEditorComponent implements OnChanges, OnDestroy {
     private tryRegisterLanguage;
     private validateExpression;
     static ɵfac: i0.ɵɵFactoryDeclaration<JsonataEditorComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<JsonataEditorComponent, "epistola-jsonata-editor", never, { "expression": { "alias": "expression"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "suggestions": { "alias": "suggestions"; "required": false; }; "functions": { "alias": "functions"; "required": false; }; }, { "expressionChange": "expressionChange"; "validChange": "validChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<JsonataEditorComponent, "epistola-jsonata-editor", never, { "expression": { "alias": "expression"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "contextVariables": { "alias": "contextVariables"; "required": false; }; "functions": { "alias": "functions"; "required": false; }; "variablesHint": { "alias": "variablesHint"; "required": false; }; }, { "expressionChange": "expressionChange"; "validChange": "validChange"; }, never, never, true, never>;
 }

package/lib/components/override-builder/legacy-override-converter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Prefix that marked a form-field reference in the legacy override-mapping
+ * object format (e.g. `"form:motivationField"`).
+ */
+export declare const FORM_REF_PREFIX = "form:";
+/**
+ * Whether a stored override-mapping value is in the legacy **object** format
+ * (`{ scope: { inputPath: "form:fieldKey" } }`) rather than the new JSONata
+ * **string** format.
+ */
+export declare function isLegacyOverrideMapping(value: unknown): value is Record<string, any>;
+/**
+ * TEMPORARY migration shim.
+ *
+ * Converts a legacy override-mapping object into the equivalent JSONata string
+ * over `$form`. Funnelling every legacy value through this one function keeps
+ * the rest of the codebase JSONata-only.
+ *
+ * @deprecated Remove once all deployed forms have been re-saved in the JSONata
+ *   format. The admin page's "legacy override format" warning tracks which
+ *   forms still need migrating.
+ */
+export declare function legacyOverrideToJsonata(mapping: Record<string, any>): string;

package/lib/components/override-builder/override-builder.component.d.ts

@@ -1,42 +1,74 @@
-import { ChangeDetectorRef, EventEmitter } from '@angular/core';
+import { ChangeDetectorRef, EventEmitter, OnDestroy, SimpleChanges } from '@angular/core';
 import { FormioCustomComponent } from '@valtimo/components';
+import { OverrideRow } from './override-jsonata';
+import { EpistolaPluginService } from '../../services';
+import { ReferencedPath } from '../../utils/extract-referenced-paths';
 import * as i0 from "@angular/core";
-interface OverrideRow {
-    scope: 'doc' | 'pv';
-    inputPath: string;
-    formFieldKey: string;
-}
 export interface FormFieldOption {
     key: string;
     label: string;
 }
 /**
- * Override mapping format: scope → { inputPath → "form:<componentKey>" }
- * The "form:" prefix identifies this as a reference to a Formio component.
+ * Override mapping value: a JSONata expression (over `$form`) that produces the
+ * `{ doc, pv }` overlay applied during preview. Legacy form definitions may
+ * still carry the old `{ scope: { inputPath: "form:key" } }` object; it is
+ * converted to JSONata on load (see {@link legacyOverrideToJsonata}).
  */
 export type OverrideMapping = Record<string, Record<string, string>>;
-export declare class EpistolaOverrideBuilderComponent implements FormioCustomComponent<OverrideMapping | null> {
+export declare class EpistolaOverrideBuilderComponent implements FormioCustomComponent<string | OverrideMapping | null>, OnDestroy {
     private readonly cdr;
-    value: OverrideMapping | null;
-    valueChange: EventEmitter<OverrideMapping>;
+    private readonly pluginService;
+    value: string | OverrideMapping | null;
+    valueChange: EventEmitter<string | OverrideMapping>;
     disabled: boolean;
     label: string;
     availableFields: FormFieldOption[];
+    /**
+     * Identify the selected generate-document process link, forwarded from the
+     * preview component's editForm. Used to fetch the link's data mapping and
+     * surface which `$doc`/`$pv` paths it consumes — purely informational guidance.
+     */
+    processDefinitionKey: string;
+    sourceActivityId: string;
     rows: OverrideRow[];
     advancedMode: boolean;
-    jsonText: string;
-    jsonError: string | null;
+    /** True when the current expression can't be represented by the simple table. */
+    simpleUnavailable: boolean;
+    expression: string;
+    /** `$doc`/`$pv`/`$case` paths the selected template's data mapping references. */
+    referencedPaths: ReferencedPath[];
+    readonly exampleExpression = "{ \"doc\": { \"naam\": $form.voornaam & ' ' & $form.achternaam } }";
     private initialized;
-    constructor(cdr: ChangeDetectorRef);
-    ngOnChanges(): void;
+    private readonly destroy$;
+    /** Link last fetched, so we refetch only when the selected process link changes. */
+    private lastFetchedLinkKey;
+    constructor(cdr: ChangeDetectorRef, pluginService: EpistolaPluginService);
+    get formFieldKeys(): string[];
+    get hasReferencedPaths(): boolean;
+    /** Referenced paths for a scope, excluding whole-scope refs (empty path) that aren't completions. */
+    referencedPathsForScope(scope: ReferencedPath['scope']): string[];
+    /** Autocomplete context for the advanced editor: form fields plus the mapping's referenced paths. */
+    get editorContextVariables(): Record<string, string[]>;
+    /** Render a referenced path as a `$scope.path` reference (or `$scope` for a whole-scope ref). */
+    formatReferencedPath(ref: ReferencedPath): string;
+    ngOnChanges(_changes?: SimpleChanges): void;
+    ngOnDestroy(): void;
+    /**
+     * Fetch the selected process link's data mapping and extract the `$doc`/`$pv`/`$case`
+     * paths it references, so the author sees what this template consumes. Refetches only
+     * when the selected link changes; clears when no link is selected. Best-effort and
+     * non-blocking — a failed fetch simply shows no suggestions.
+     */
+    private refreshReferencedPaths;
     toggleMode(): void;
     addRow(): void;
     removeRow(index: number): void;
+    /** Simple-table change: serialize rows back to a JSONata expression. */
     emitChange(): void;
-    onJsonChange(text: string): void;
-    private rowsToMapping;
-    private mappingToRows;
+    /** Advanced-editor change. */
+    onExpressionChange(expr: string): void;
+    private loadFromExpression;
+    private emit;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaOverrideBuilderComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaOverrideBuilderComponent, "epistola-override-builder-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "availableFields": { "alias": "availableFields"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaOverrideBuilderComponent, "epistola-override-builder-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "availableFields": { "alias": "availableFields"; "required": false; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }
-export {};