impact-nova 2.3.0 → 2.4.0

package/dist/form-react/types/fields.types.d.ts

@@ -0,0 +1,402 @@
+import { Option } from '../../components/forms/select';
+import { HTMLInputTypeAttribute } from 'react';
+import { FieldOutputValue } from './fieldsOutput.types';
+export type ValidationRule = {
+    /** Regex pattern string to test against */
+    regex?: string;
+    /** Zod method name, e.g. "email", "url", "min", "max", "uuid", "regex" */
+    zod?: string;
+    /** Arguments to pass to the Zod method, e.g. [5] for z.string().min(5) */
+    zodArgs?: unknown[];
+    /** Error message returned when validation fails */
+    message?: string;
+    /** Named sync validator → formContext.validators[name] */
+    validatorName?: string;
+};
+/**
+ * Copy for built-in `date_range` checks (supplied via remote field config — FE substitutes `{minDate}` / `{offset}` at validate time).
+ */
+export type DateRangeValidationMessages = {
+    requiredBoth?: string;
+    partialPair?: string;
+    invalidDate?: string;
+    exitMustBeAfterStart?: string;
+    /** Template: `{minDate}` = YYYY-MM-DD, `{offset}` = minStartOffsetDays */
+    startBeforeMinimum?: string;
+};
+/**
+ * Single-date field (one calendar control). Values are stored as `YYYY-MM-DD` strings in form state.
+ * Messages come from `dateValidationMessages` on the field config.
+ */
+export type DateInputValidationMessages = {
+    required?: string;
+    invalidDate?: string;
+    /** Template: `{minDate}`, `{offset}` when `minOffsetDaysFromToday` or `pastDateNotAllowed` applies */
+    beforeMinimum?: string;
+    /** When `dateAfterFieldId` is set: value must be after the referenced field's date (strict or inclusive based on `dateAfterFieldIdInclusive`) */
+    mustBeAfterOther?: string;
+    /** When `dateBeforeFieldId` is set: value must be before the referenced field's date (strict or inclusive based on `dateBeforeFieldIdInclusive`) */
+    mustBeBeforeOther?: string;
+};
+export type BaseField = {
+    order?: number;
+    id: string;
+    label?: string;
+    isDisabled?: boolean;
+    colSpan?: number;
+    clearable?: boolean;
+    placeholder?: string;
+    isRequired?: boolean;
+    helpText?: string;
+    className?: string;
+    labelOrientation?: "top" | "left";
+    isFieldReadonly?: boolean;
+    validation?: Array<ValidationRule>;
+    /** Group key used by `buildFieldGroups` / `fieldGroupTitles` for multi-section layout. */
+    fieldGroup?: string;
+    visibilityDependency?: Array<{
+        fieldId: string;
+        value: FieldOutputValue[] | FieldOutputValue;
+    }>;
+    disableDependency?: Array<{
+        fieldId: string;
+        value: FieldOutputValue[] | FieldOutputValue;
+    }>;
+    /** When "every", field is disabled only if ALL conditions match (AND). Default is "some" (OR). */
+    disableDependencyMode?: "some" | "every";
+    cascadingDependency?: Array<{
+        fieldId: string;
+        value: FieldOutputValue[] | FieldOutputValue;
+    }>;
+    doNotIncludeInSubmit?: boolean;
+    /** When true, this field is auxiliary/decorative and should not alone enable form submission (e.g. period selectors, dividers, labels). */
+    isNonValueField?: boolean;
+    /** When true, shows a "Set To Empty" action link that lets users explicitly null-out the field value. */
+    allowSetToEmpty?: boolean;
+    /**
+     * Name of formContext.functions[name].
+     * Runs on value change for any field; specialized fields (backend / paste / file)
+     * also use it for their validate/upload action. Omit = usual flow.
+     */
+    handlerName?: string;
+};
+export type LabelField = BaseField & {
+    fieldType: "label";
+    className?: string;
+};
+export type FileUploadField = BaseField & {
+    fieldType: "file_upload";
+    supportedFileTypes: Array<{
+        fileType: string;
+        templateUrl: string;
+        typeOverride: boolean;
+    }>;
+    numberOfFiles: number;
+    maxFileSize: number;
+    apiConfig?: {
+        apiEndpoint: string;
+        method: "GET" | "POST";
+    };
+};
+export type ButtonsGroupField = BaseField & {
+    fieldType: "button_group";
+    options: Array<Option>;
+    defaultSelectedValue?: string;
+};
+export type SelectField = BaseField & {
+    fieldType: "select";
+    options?: Array<Option>;
+    isMultiSelect?: boolean;
+    maxSelectLimit?: number;
+    disableClearAll?: boolean;
+    disableOptionSearch?: boolean;
+    disableSelectAll?: boolean;
+    /**
+     * Name of formContext.getSelectOptions[name].
+     * When set, that resolver is used instead of apiConfig fetch.
+     */
+    getSelectOptionsName?: string;
+    apiConfig?: {
+        apiEndpoint: string;
+        method: "GET" | "POST";
+        /** When true, cascaded POSTs send `filters: []` (no parent field values). Use for independent selects (e.g. optional attributes). */
+        doNotIncludeSectionFormStateInApiRequest?: boolean;
+        includeOnlyMandatoryFieldsInPayload?: boolean;
+        /** When true, enables cascade behaviour even when `formConfig.isCascading` is false. */
+        isCascading?: boolean;
+        /**
+         * Explicit list of field IDs whose values should be sent as cascade filters.
+         * When set, overrides the default positional behaviour (`getEarlierFieldsIds`) entirely —
+         * only these specific IDs are included, regardless of their array position.
+         * Use when you need precise control over which parent fields cascade into this field's options.
+         * Example: `["division_name", "l0_name"]` — only send Division and Department as filters.
+         */
+        cascadeFromFields?: string[];
+    };
+};
+export type DateInputField = BaseField & {
+    fieldType: "date";
+    /** Display format with moment-style tokens, e.g. "MM/DD/YYYY", "YYYY-MM-DD". Defaults to "YYYY-MM-DD". */
+    dateFormat?: string;
+    minDate?: string;
+    maxDate?: string;
+    /** Earliest selectable day is start-of-day of today + this many days. */
+    minOffsetDaysFromToday?: number;
+    /**
+     * When set (e.g. exit date), the picked date must be strictly after the referenced field’s date.
+     * The calendar `minDate` is the day after that field’s value when it is set.
+     */
+    dateAfterFieldId?: string | string[];
+    dateAfterFieldIdInclusive?: boolean;
+    /**
+     * When set (e.g. start date vs exit), the picked date must be strictly before the referenced field’s date.
+     * The calendar `maxDate` is the day before that field’s value when it is set.
+     */
+    dateBeforeFieldId?: string | string[];
+    dateBeforeFieldIdInclusive?: boolean;
+    pastDateNotAllowed?: boolean;
+    dateValidationMessages?: DateInputValidationMessages;
+    showFooter?: boolean;
+};
+export type DateRangeField = BaseField & {
+    fieldType: "date_range";
+    /** Display format with moment-style tokens, e.g. "MM/DD/YYYY", "YYYY-MM-DD". Defaults to "YYYY-MM-DD". */
+    dateFormat?: string;
+    /** ISO date string (YYYY-MM-DD) — calendar minimum for the range picker */
+    minDate?: string;
+    /** ISO date string (YYYY-MM-DD) — calendar maximum for the range picker */
+    maxDate?: string;
+    /**
+     * Earliest selectable **start** date is start-of-day of today + this many days.
+     * Example: `60` blocks choosing a start date before the calendar day that is 60 days from today.
+     */
+    minStartOffsetDays?: number;
+    defaultRange?: {
+        start: string;
+        end: string;
+    };
+    dateRangeValidationMessages?: DateRangeValidationMessages;
+    startPlaceholder?: string;
+    endPlaceholder?: string;
+    /** ISO date string — first month shown in picker navigation */
+    startMonth?: string;
+    /** ISO date string — last month shown in picker navigation */
+    endMonth?: string;
+};
+export type WeekRangeField = BaseField & {
+    fieldType: "week_range";
+    minDate?: string;
+    maxDate?: string;
+    /** Minimum selectable start date = today + N days (0 = today, blocks past dates). */
+    minStartOffsetDays?: number;
+    /** When true, past weeks/dates cannot be selected (equivalent to minStartOffsetDays: 0). */
+    disablePastWeeks?: boolean;
+    /** First month shown in the picker navigation (ISO date string). */
+    startMonth?: string;
+    /** Last month shown in the picker navigation (ISO date string). */
+    endMonth?: string;
+    defaultRange?: {
+        start: string;
+        end: string;
+    };
+    calendarType?: "fiscal" | "calendar";
+    fiscalMode?: "basic" | "advanced" | "custom";
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    selectionMode?: "week" | "fiscalMonth";
+    fiscalMonthPattern?: number[];
+    fiscalYearStartMonth?: number;
+    showFooter?: boolean;
+    format?: string;
+    /** Number of weeks before the current week to set as the minimum selectable date */
+    minWeeksOffset?: number;
+    /** Number of weeks after the current week to set as the maximum selectable date */
+    maxWeeksOffset?: number;
+    dateFormat?: string;
+};
+export type MultiWeekRangeField = BaseField & {
+    fieldType: "multi_week_picker";
+    minDate?: string;
+    maxDate?: string;
+    calendarType?: "fiscal" | "calendar";
+    fiscalMode?: "basic" | "advanced" | "custom";
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    selectionMode?: "week" | "fiscalMonth";
+    fiscalMonthPattern?: number[];
+};
+export type MonthRangeField = BaseField & {
+    fieldType: "month_range";
+    displayFormat?: "MM/YYYY" | "YYYY/MM";
+    defaultRange?: {
+        start: string;
+        end: string;
+    };
+    minDate?: string;
+    maxDate?: string;
+    startMonth?: string;
+    endMonth?: string;
+    showYearSelect?: boolean;
+    disablePastMonths?: boolean;
+    /** Number of months before the current month to set as the minimum selectable month */
+    minMonthsOffset?: number;
+    /** Number of months after the current month to set as the maximum selectable month */
+    maxMonthsOffset?: number;
+    customYears?: Array<{
+        label: string;
+        value: string;
+    }>;
+    isOutsideRange?: (month: Date) => boolean;
+};
+export type MultiMonthPickerField = BaseField & {
+    fieldType: "multi_month_picker";
+    minDate?: string;
+    maxDate?: string;
+    startMonth?: string;
+    endMonth?: string;
+};
+export type TextAreaField = BaseField & {
+    fieldType: "text_area";
+    maxRows?: number;
+    characterLimit?: number;
+    maxLength?: number;
+    defaultValue?: string;
+};
+export type RadioField = BaseField & {
+    fieldType: "radio";
+    orientation?: "row" | "column";
+    options: Array<Option>;
+    defaultSelectedValue?: string;
+};
+export type TextField = BaseField & {
+    fieldType: "text";
+    type: HTMLInputTypeAttribute;
+    defaultValue?: string | number;
+    nonNegative?: boolean;
+    allowDecimal?: boolean;
+    /**
+     * Reactively override `nonNegative` based on a flag on the currently
+     * selected option of another (select) field. Only meaningful when
+     * `nonNegative: true`. Reads `option.metadata[optionFlag]` from the
+     * selected option. Has no effect when `nonNegative` is falsy.
+     */
+    allowNegativeDependency?: {
+        fieldId: string;
+        /** Key inside the selected option's `metadata` object, e.g. `"allow_negative"`. */
+        optionFlag: string;
+    };
+};
+/**
+ * Numeric combobox: wraps Impact Nova `Combobox` with `isNumeric` plus
+ * `min` / `max` / `step` so callers can render a stepper-style dropdown
+ * (e.g. 0..95 in steps of 5). Value is stored as a number in form state.
+ */
+export type NumericComboboxField = BaseField & {
+    fieldType: "numeric_combobox";
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultValue?: number;
+};
+export type CopyPasteField = BaseField & {
+    fieldType: "fill_form_by_paste";
+    selectFieldConfig: {
+        selectFieldLabel?: string;
+        selectFieldPlaceholder?: string;
+        selectFieldOptions: Array<Option>;
+        labelOrientation?: "top" | "left";
+    };
+    textAreaConfig?: {
+        textAreaLabel?: string;
+        textAreaPlaceholder?: string;
+    };
+    /** Legacy built-in path — optional when field.handlerName is set */
+    validationConfig?: {
+        apiEndpoint: string;
+    };
+};
+export type FillFormByFileUploadField = BaseField & {
+    fieldType: "fill_form_by_file_upload";
+    supportedFileTypes: Array<{
+        fileType: string;
+        templateUrl: string;
+        typeOverride: boolean;
+    }>;
+    maxFileSize: number;
+    /** Legacy built-in path — optional when field.handlerName is set */
+    validationConfig?: {
+        apiEndpoint: string;
+    };
+};
+export type SwitchField = BaseField & {
+    fieldType: "switch";
+    leftLabel?: string;
+    rightLabel?: string;
+    defaultSelectedValue?: boolean;
+};
+export type CheckboxField = BaseField & {
+    fieldType: "checkbox";
+    defaultSelectedValue?: boolean;
+};
+export type TextFieldWithBackendValidation = BaseField & {
+    fieldType: "text_with_backend_validation";
+    /** Legacy built-in path — optional when field.handlerName is set */
+    validationConfig?: {
+        method?: "GET" | "POST";
+        apiEndpoint: string;
+        fieldValuesToIncludeInApiRequest?: Array<string>;
+        debounceTime?: number;
+        validateOnBlur?: boolean;
+        omitValidation?: Array<string>;
+    };
+};
+export type ChipsField = BaseField & {
+    fieldType: "chips";
+    options: Array<Option>;
+    chipsType?: "single" | "multi";
+    /** When true in single mode, re-clicking the active chip clears the selection. */
+    allowDeselect?: boolean;
+};
+export type DividerField = BaseField & {
+    fieldType: "divider";
+    className?: string;
+};
+export type DividerWithLabelField = BaseField & {
+    fieldType: "divider_with_label";
+    label: string;
+    labelAlignment?: "left" | "center" | "right";
+    labelClassName?: string;
+    dividerClassName?: string;
+};
+export type ObjectFieldConfig = BaseField & {
+    fieldType: "object";
+    /** Child fields rendered inside this object group */
+    fields: IField[];
+    /** Grid columns for the nested field group (defaults to parent formConfig.columns) */
+    columns?: number;
+    /** Whether to render a visual border/card around the group */
+    bordered?: boolean;
+    /** Collapsible section — user can expand/collapse */
+    collapsible?: boolean;
+    defaultCollapsed?: boolean;
+};
+export type ArrayFieldConfig = BaseField & {
+    fieldType: "array";
+    /** Template fields cloned for each array item */
+    itemFields: IField[];
+    /** Grid columns for each item's field group */
+    itemColumns?: number;
+    /** Minimum number of items (pre-populated on mount) */
+    minItems?: number;
+    /** Maximum number of items (disables "Add" when reached) */
+    maxItems?: number;
+    /** Label for the add-item button */
+    addButtonLabel?: string;
+    /** Label for each item's remove button */
+    removeButtonLabel?: string;
+    /** Whether items can be reordered via move-up / move-down */
+    orderable?: boolean;
+    /** Default values for a new item (keys match itemFields[].id) */
+    defaultItemValue?: Record<string, unknown>;
+};
+export type IField = FileUploadField | ButtonsGroupField | SelectField | DateInputField | DateRangeField | WeekRangeField | MonthRangeField | MultiMonthPickerField | TextAreaField | RadioField | TextField | NumericComboboxField | CopyPasteField | FillFormByFileUploadField | TextFieldWithBackendValidation | ChipsField | DividerField | DividerWithLabelField | LabelField | SwitchField | CheckboxField | MultiWeekRangeField | ObjectFieldConfig | ArrayFieldConfig;
+/** Discriminant string union for every built-in field type */
+export type FieldType = IField["fieldType"];

package/dist/form-react/types/fieldsOutput.types.d.ts

@@ -0,0 +1,73 @@
+import { Option } from '../../components/forms/select';
+import { MonthSelection, WeekSelection } from '../../components/data-display/calendar';
+/** Shared range shape for date_range / week_range / month_range */
+export type RangeFieldOutput = {
+    start: string | null;
+    end: string | null;
+} | null;
+export type FileUploadFieldOutput = File[] | null | undefined;
+export type ButtonsGroupFieldOutput = string | null | undefined;
+export type SelectFieldOutput = Array<Option> | null | undefined;
+export type DateRangeFieldOutput = RangeFieldOutput;
+export type WeekRangeFieldOutput = RangeFieldOutput;
+export type MonthRangeFieldOutput = RangeFieldOutput;
+export type DateInputFieldOutput = string | null | undefined;
+export type TextAreaFieldOutput = string | null | undefined;
+export type RadioFieldOutput = string | null | undefined;
+export type TextFieldOutput = string | null | undefined;
+export type TextFieldWithBackendValidationOutput = string | null | undefined;
+export type CopyPasteFieldOutput = Array<Option> | null | undefined;
+export type FillFormByFileUploadFieldOutput = Array<Option> | null | undefined;
+export type MultiWeekPickerFieldOutput = WeekSelection[] | null | undefined;
+export type MultiMonthPickerFieldOutput = MonthSelection[] | null | undefined;
+/** Empty string is the unset default from getFieldDefaultValue */
+export type NumericComboboxFieldOutput = number | "" | null | undefined;
+export type ChipsFieldOutput = string | string[] | null | undefined;
+export type SwitchFieldOutput = boolean | null | undefined;
+export type CheckboxFieldOutput = boolean | null | undefined;
+/** Presentational fields do not store a value */
+export type PresentationalFieldOutput = null | undefined;
+/**
+ * Union of all field output values (recursive for object / array nesting).
+ * Defined independently of FieldTypeToOutputMap to avoid circular map lookups.
+ */
+export type FieldOutputValue = FileUploadFieldOutput | ButtonsGroupFieldOutput | SelectFieldOutput | DateInputFieldOutput | DateRangeFieldOutput | WeekRangeFieldOutput | MultiWeekPickerFieldOutput | MonthRangeFieldOutput | MultiMonthPickerFieldOutput | TextAreaFieldOutput | RadioFieldOutput | TextFieldOutput | NumericComboboxFieldOutput | CopyPasteFieldOutput | FillFormByFileUploadFieldOutput | TextFieldWithBackendValidationOutput | ChipsFieldOutput | SwitchFieldOutput | CheckboxFieldOutput | PresentationalFieldOutput | {
+    [key: string]: FieldOutputValue;
+} | Array<{
+    [key: string]: FieldOutputValue;
+}>;
+/**
+ * Exhaustive map from every IField fieldType → form-state value shape.
+ */
+export type FieldTypeToOutputMap = {
+    file_upload: FileUploadFieldOutput;
+    button_group: ButtonsGroupFieldOutput;
+    select: SelectFieldOutput;
+    date: DateInputFieldOutput;
+    date_range: DateRangeFieldOutput;
+    week_range: WeekRangeFieldOutput;
+    multi_week_picker: MultiWeekPickerFieldOutput;
+    month_range: MonthRangeFieldOutput;
+    multi_month_picker: MultiMonthPickerFieldOutput;
+    text_area: TextAreaFieldOutput;
+    radio: RadioFieldOutput;
+    text: TextFieldOutput;
+    numeric_combobox: NumericComboboxFieldOutput;
+    fill_form_by_paste: CopyPasteFieldOutput;
+    fill_form_by_file_upload: FillFormByFileUploadFieldOutput;
+    text_with_backend_validation: TextFieldWithBackendValidationOutput;
+    chips: ChipsFieldOutput;
+    switch: SwitchFieldOutput;
+    checkbox: CheckboxFieldOutput;
+    object: {
+        [key: string]: FieldOutputValue;
+    } | null | undefined;
+    array: Array<{
+        [key: string]: FieldOutputValue;
+    }> | null | undefined;
+    label: PresentationalFieldOutput;
+    divider: PresentationalFieldOutput;
+    divider_with_label: PresentationalFieldOutput;
+};
+/** @deprecated Prefer FieldOutputValue — kept for BaseField / filter-era imports */
+export type IFilterFieldOutputValue = FieldOutputValue;

package/dist/form-react/types/reactHookForm.types.d.ts

@@ -0,0 +1,196 @@
+import { ComponentType } from 'react';
+import { FieldErrors, FormState, RegisterOptions, UseFormReturn } from 'react-hook-form';
+import { Option } from '../../components/forms/select';
+import { FieldVisibilityBase } from '../../form-engine';
+import { FieldType, IField, SelectField } from './fields.types';
+export type { FieldVisibilityBase } from '../../form-engine';
+export type IFormConfig = {
+    formId: string;
+    fields: Array<IField>;
+    title?: string;
+    columns?: number;
+    gapBetweenFields?: number;
+    isCascading?: boolean;
+    includeOnlyVisibleFieldsInSubmit?: boolean;
+    enableFieldOrdering?: boolean;
+};
+export interface FormFieldProps {
+    field: IField;
+    formHelpers: UseReactHookFormReturn;
+    validationRules: RegisterOptions;
+    isDisabled: boolean;
+    formConfig: IFormConfig;
+    supportedValues?: SupportedValuesMap;
+}
+/**
+ * Consumer-injected context passed to the form framework and all field adapters.
+ * Modeled after AG Grid's `context` prop — a typed bag of functions and overrides.
+ */
+export type FormContextFieldChangeParams = {
+    formHelpers: UseReactHookFormReturn;
+    fieldId: string;
+    newValue: unknown;
+    oldValue: unknown;
+};
+export type FormContextFunctionParams = FormContextFieldChangeParams & {
+    /** Field-specific input (File, pasted string, included field values, etc.) */
+    payload?: unknown;
+};
+export type FormContextValidator = (params: FormContextFieldChangeParams) => string | true;
+export type FormContextGetSelectOptions = (params: FormContextFieldChangeParams) => Option[] | Promise<Option[]>;
+export type FormContextFunction = (params: FormContextFunctionParams) => unknown | Promise<unknown>;
+export type FormContextOnFieldChange = (params: FormContextFieldChangeParams) => void;
+export type FetchSelectOptionsParams = {
+    fieldId: string;
+    apiConfig: NonNullable<SelectField['apiConfig']>;
+    earlierFieldsValues: Record<string, unknown>;
+    fieldSupportedValues?: Record<string, unknown>;
+};
+export type PastedValuesValidationResult = {
+    valid_values: Array<{
+        label: string;
+        value: string;
+    }>;
+    invalid_values: string[];
+    message?: string;
+};
+export type ValidatePastedValuesParams = {
+    apiEndpoint: string;
+    values: string;
+    targetFieldId: string;
+    dimensionId?: string;
+};
+export type ValidateUploadedFileParams = {
+    apiEndpoint: string;
+    file: File;
+    signal?: AbortSignal;
+    onUploadProgress?: (progress: {
+        loaded: number;
+        total?: number;
+    }) => void;
+};
+export type UploadedFileValidationResult = {
+    filtered_values: Record<string, Array<{
+        label: string;
+        value: string;
+    }>>;
+    invalid_rows_count: number;
+    signed_url: string;
+    total_count: Record<string, number>;
+    valid_rows_count: number;
+    message?: string;
+    session_id?: string;
+};
+export type ValidateTextFieldWithBackendParams = {
+    formHelpers: UseReactHookFormReturn;
+    apiEndpoint: string;
+    value: string;
+    method?: 'GET' | 'POST';
+    fieldValuesToIncludeInApiRequest: Record<string, unknown>;
+};
+export type TextFieldBackendValidationResult = {
+    is_valid: boolean;
+    message?: string;
+};
+/** Network and app-specific side effects — must be provided by the host application. */
+export interface FormTransport {
+    fetchSelectOptions?: (params: FetchSelectOptionsParams) => Promise<Option[]>;
+    validatePastedValues?: (params: ValidatePastedValuesParams) => Promise<PastedValuesValidationResult>;
+    validateUploadedFile?: (params: ValidateUploadedFileParams) => Promise<UploadedFileValidationResult>;
+    validateTextFieldWithBackend?: (params: ValidateTextFieldWithBackendParams) => Promise<TextFieldBackendValidationResult>;
+    showFormErrorToast?: (message: {
+        title: string;
+        description: string;
+    }) => void;
+}
+/** Built-in fieldType keys plus arbitrary custom string keys */
+export type CustomFieldTypesMap = Partial<Record<FieldType, ComponentType<FormFieldProps>>> & Record<string, ComponentType<FormFieldProps>>;
+export interface FormValidationMeta {
+    isSubmittable: boolean;
+}
+export interface FormContextValidateFormParams {
+    formValues: ReactHookFormState;
+    visibleFields: IField[];
+}
+export interface FormContext {
+    /** Per-instance field type overrides or custom field components */
+    customFieldTypes?: CustomFieldTypesMap;
+    /** Named sync validators — referenced via validation[].validatorName */
+    validators?: Record<string, FormContextValidator>;
+    /** Named select options resolvers — referenced via getSelectOptionsName */
+    getSelectOptions?: Record<string, FormContextGetSelectOptions>;
+    /** Named handlers — referenced via BaseField.handlerName (on change + specialized validate) */
+    functions?: Record<string, FormContextFunction>;
+    /** Called after any field value changes */
+    onFieldChange?: FormContextOnFieldChange;
+    /** Host-provided network transport (axios, fetch, etc.) — not implemented by Impact Nova */
+    transport?: FormTransport;
+    /** Optional cross-field validation (e.g. required-one-of groups) merged into submit + isSubmittable */
+    validateForm?: (params: FormContextValidateFormParams) => {
+        isValid: boolean;
+        fieldErrors?: Record<string, {
+            message: string;
+        }>;
+    };
+}
+export type ReactHookFormState = Record<string, unknown>;
+/** Map of field IDs to their supported values for API injection */
+export type SupportedValuesMap = Record<string, unknown>;
+export interface UseReactHookFormReturn {
+    formConfig: IFormConfig;
+    highlightFirstError?: boolean;
+    formId: string;
+    form: UseFormReturn<ReactHookFormState>;
+    getValues: () => ReactHookFormState;
+    setValue: (fieldName: string, value: unknown) => void;
+    resetForm: (values?: ReactHookFormState) => void;
+    handleSubmit: (onSubmit?: (data: ReactHookFormState) => void) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+    handleCancel: () => void;
+    isFieldVisible: (field: FieldVisibilityBase) => boolean;
+    isFieldDisabled: (field: FieldVisibilityBase) => boolean;
+    isFieldDisabledForSubmitValidation: (field: FieldVisibilityBase) => boolean;
+    submitValidatedForm: (onSubmit?: (data: ReactHookFormState) => void) => void;
+    getEarlierFieldsIds: (currentFieldId: string, onlyMandatory?: boolean) => string[];
+    scrollToFirstError: () => void;
+    /** Set of field IDs that the user has explicitly marked as "set to empty". */
+    setToEmptyFields: Set<string>;
+    /** Mark a field as explicitly empty (snapshots current value for undo). */
+    markFieldAsEmpty: (fieldId: string) => void;
+    /** Undo a "set to empty" action — restores the field's previous value. */
+    undoSetToEmpty: (fieldId: string) => void;
+    /** Snapshot of a field's value before the latest change (for validators / handlers). */
+    getPreviousFieldValue: (fieldId: string) => unknown;
+    /** Consumer-injected context — validators, custom field types, lifecycle hooks */
+    formContext?: FormContext;
+}
+export interface ReactHooksFormProps {
+    formId?: string;
+    formConfig: IFormConfig;
+    formInitialState?: ReactHookFormState;
+    onSubmit?: (data: ReactHookFormState) => void;
+    onCancel?: (data: ReactHookFormState) => void;
+    onReset?: (data: ReactHookFormState) => void;
+    sendFormStateToParent?: (formState: FormState<ReactHookFormState>, formValues?: ReactHookFormState, formMeta?: FormValidationMeta) => void;
+    /** Map of field IDs to values that should be injected into API calls */
+    supportedValues?: SupportedValuesMap;
+    /** Consumer-injected context — validators, custom field types, lifecycle hooks */
+    formContext?: FormContext;
+}
+export interface ReactHooksFormRef {
+    submitForm: () => Promise<boolean>;
+    hasErrors: boolean;
+    errors: FieldErrors<ReactHookFormState>;
+    isValid: boolean;
+}
+export interface UseSelectOptionsProps {
+    apiConfig?: SelectField["apiConfig"];
+    formHelpers?: UseReactHookFormReturn;
+    formConfig?: IFormConfig;
+    initialOptions?: Option[];
+    id: string;
+    isEnabled: boolean;
+    /** Name of formContext.getSelectOptions resolver */
+    getSelectOptionsName?: string;
+    /** Field-specific values to inject into API payload (e.g., viewSettings, globalFilters) */
+    fieldSupportedValues?: Record<string, unknown>;
+}

package/dist/form-react/utils/batchFormFieldUpdates.d.ts

@@ -0,0 +1,14 @@
+import { UseFormReturn, Path, PathValue } from 'react-hook-form';
+type BatchFieldUpdate<FormValues extends Record<string, unknown>> = {
+    fieldName: Path<FormValues>;
+    value: PathValue<FormValues, Path<FormValues>>;
+};
+/**
+ * Applies multiple setValue calls in one synchronous pass so React 18 can
+ * batch the resulting renders into a single commit.
+ */
+export declare function batchSetFormFieldValues<FormValues extends Record<string, unknown>>(form: UseFormReturn<FormValues>, updates: BatchFieldUpdate<FormValues>[], options?: {
+    shouldDirty?: boolean;
+    shouldValidate?: boolean;
+}): void;
+export {};