@wavemaker-ai/react-runtime 1.0.0-rc.309

package/components/data/form/base-form/props.d.ts

@@ -0,0 +1,297 @@
+import { BaseProps } from "@wavemaker-ai/react-runtime/higherOrder/withBaseWrapper";
+import { UseFormReset } from "react-hook-form";
+/**
+ * Defines the different scenarios for form nesting and their configurations.
+ * This provides a single source of truth for understanding form behavior
+ * based on its relationship to parent forms.
+ *
+ * Scenarios:
+ * - STANDALONE: No parent form (root form)
+ * - DIRECT_CHILD: Form -> Form (direct nesting with parentForm prop)
+ * - LIST_CHILD: Form -> List -> Form (form inside a list widget)
+ * - PREFAB_CHILD: Form -> Prefab -> Form (form inside a prefab, context-based)
+ * - LIST_PREFAB_CHILD: Form -> List -> Prefab -> Form (prefab inside list)
+ */
+export declare enum FormType {
+    /** Root form with no parent */
+    STANDALONE = "standalone",
+    /** Form -> Form: Direct child form with parentForm prop */
+    DIRECT_CHILD = "direct_child",
+    /** Form -> List -> Form: Child form inside a list widget */
+    LIST_CHILD = "list_child",
+    /** Form -> Prefab -> Form: Form inside a prefab (context-based relationship) */
+    PREFAB_CHILD = "prefab_child",
+    /** Form -> List -> Prefab -> Form: Form inside a prefab that's inside a list */
+    LIST_PREFAB_CHILD = "list_prefab_child"
+}
+/**
+ * Configuration for each form type.
+ * Determines how the form handles field registration, data reset, and data sourcing.
+ */
+export interface FormTypeConfig {
+    type: FormType;
+    /**
+     * Field Registration Strategy
+     * - 'prefixed': Fields registered as "formName.fieldName" (direct/list child forms)
+     * - 'direct': Fields registered as "fieldName" (standalone and prefab forms)
+     */
+    fieldRegistration: "prefixed" | "direct";
+    /**
+     * Data Reset Strategy
+     * - 'wrapped': reset({ [formName]: data }) - matches prefixed field registration
+     * - 'flat': reset(data) - matches direct field registration
+     */
+    dataResetStrategy: "wrapped" | "flat";
+    /**
+     * Data Source Priority
+     * Determines where to get form data, in order of preference
+     */
+    dataSourcePriority: ("childFormData" | "prefabContextData" | "propsData")[];
+    /**
+     * Whether this form type should emit data changes to parent
+     */
+    emitsToParent: boolean;
+}
+/**
+ * Configuration map for all form types.
+ * Single source of truth for form behavior based on type.
+ */
+export declare const FORM_TYPE_CONFIGS: Record<FormType, FormTypeConfig>;
+/**
+ * Get the configuration for a form type.
+ */
+export declare function getFormTypeConfig(formType: FormType): FormTypeConfig;
+/** Check if form is any type of child form (not standalone) */
+export declare function isChildFormType(formType: FormType): boolean;
+/** Check if form uses prefixed field registration (direct/list child) */
+export declare function usesPrefixedFields(formType: FormType): boolean;
+/**
+ * Detect form type based on props and context values.
+ * This is the main detection logic used by useParentFormRelationship.
+ */
+export declare function detectFormType(params: {
+    hasParentFormProp: boolean;
+    hasChildDatasetNode: boolean;
+    hasPrefabContext: boolean;
+    isInList: boolean;
+}): FormType;
+interface BaseFormProps extends BaseProps {
+    listener?: ListenerContext;
+    captionwidth: string;
+    captionposition: "left" | "right" | "top" | "bottom";
+    captionalign: "left" | "center" | "right";
+    autocomplete: "on" | "off";
+    method: "post" | "put" | "delete";
+    messagelayout: "Inline" | "Toaster";
+    postmessage: string;
+    errormessage: string;
+    tabindex: number;
+    validationtype: string;
+    collapsible: boolean;
+    expanded: boolean;
+    isInsideWizard?: boolean;
+    itemsperrow?: number;
+    formdata?: Record<string, unknown>;
+    onReset: () => void;
+    action: (event: React.FormEvent<HTMLFormElement>, widget: any) => void;
+    onSubmit: (event: React.FormEvent<HTMLFormElement>, widget: any, data: any) => void;
+    onError: (event: React.FormEvent<HTMLFormElement>, widget: any, error: any) => void;
+    onSuccess: (event: React.FormEvent<HTMLFormElement>, widget?: any, data?: any) => void;
+    formSubmit: (event: React.FormEvent<HTMLFormElement>, widget: any, data: any, operation?: any) => void;
+    onChange: (event: React.FormEvent<HTMLFormElement>, widget: any, data: any) => void;
+    onBeforeSubmit: (event: React.FormEvent<HTMLFormElement>, widget: any, data: any) => boolean | string | object | Promise<boolean | string | object>;
+    cancel: () => void;
+    parentForm?: string;
+    isParentList?: boolean | string;
+    parentListName?: string;
+    childdatasetnode?: string;
+    formArrayIndex?: number;
+    datasource?: any;
+    widgettype?: string;
+    onResult?: (event: React.FormEvent<HTMLFormElement>, widget: any, data: any) => void;
+    onDataSourceChange?: (fields: any[]) => void;
+    destroy?: (formName?: string) => void;
+    insertmessage?: string;
+    updatemessage?: string;
+    deletemessage?: string;
+    Livefilter?: (data: any, clear: boolean, formFields: Record<string, any>) => void;
+    autoupdate?: boolean | string;
+    target?: string;
+    encType?: string;
+    "form-type"?: string;
+    standalone?: boolean;
+}
+export declare const defaultProps: Partial<BaseFormProps>;
+export type ValidationMessage = {
+    field: string;
+    value: any;
+    errorType: string[];
+    message: string;
+    getElement: () => HTMLElement | null;
+    formName: string;
+    fullyQualifiedFormName: string;
+};
+export interface FormFieldWidget {
+    formKey?: string;
+    fieldName?: string;
+    dataKey?: string;
+    [key: string]: any;
+}
+export interface FormElementWithMethods extends HTMLFormElement {
+    getFormData?: () => {
+        values: any;
+        isValid: boolean;
+    };
+    validateForm?: () => boolean | Promise<boolean>;
+    clearErrors?: () => void;
+    getProps?: () => BaseFormProps;
+    formWidgets?: Record<string, any>;
+    getValidationMessages?: () => ValidationMessage[];
+    validationMessages?: ValidationMessage[];
+}
+/**
+ * Widget data stored in the listener.Widgets proxy for each form
+ */
+export interface FormWidgetData {
+    formdata?: Record<string, any>;
+    formfields?: Record<string, FormFieldWidget>;
+    formWidgets?: Record<string, any>;
+    validationMessages?: ValidationMessage[];
+}
+/**
+ * Listener context passed to widgets via props
+ * Contains global widget registry and app-level utilities
+ */
+export interface ListenerContext {
+    Widgets?: Record<string, FormWidgetData>;
+    Actions?: Record<string, any>;
+    App?: {
+        notifyApp?: (message: string, type?: string, showInToaster?: boolean) => void;
+    };
+    onChange?: (widgetName: string, data: any) => void;
+}
+export interface UseFormDataSyncOptions {
+    reset: UseFormReset<any>;
+    /** The detected form type - determines sync behavior */
+    formType: FormType;
+    formName?: string;
+}
+export interface UseFormDataSyncReturn {
+    currentFormData: any;
+    syncFormData: (data: any) => void;
+    resetFormData: (data: any) => void;
+    clearFormData: (cleanedData?: Record<string, any>) => void;
+    markCurrentData: (data: any) => void;
+    isUpdating: () => boolean;
+}
+export interface UseParentFormRelationshipOptions {
+    name: string;
+    parentForm?: any;
+    isParentList?: boolean | string;
+    parentListName?: string;
+    childdatasetnode?: string;
+    formArrayIndex?: number;
+}
+export interface UseParentFormRelationshipReturn {
+    /** The detected form type (STANDALONE, DIRECT_CHILD, LIST_CHILD, PREFAB_CHILD, LIST_PREFAB_CHILD) */
+    formType: FormType;
+    /** Configuration for the detected form type */
+    formTypeConfig: FormTypeConfig;
+    /** Parent form reference (from props or PrefabContext) */
+    parentForm: any;
+    /** Whether form is inside a list widget */
+    isParentList: boolean;
+    /** Index in parent list array (-1 if not in list) */
+    formArrayIndex: number;
+    /** The data key to extract child data from parent */
+    effectiveChildDatasetNode: string | undefined;
+    /** Full data path for nested forms (e.g., "employeeInfos[0].emergencyContact") */
+    fullDataPath: string | undefined;
+    /** Whether form has explicit props-based parent relationship */
+    hasDirectChildRelationship: boolean;
+    /** The root parent form name (for deeply nested forms) */
+    rootParentForm: string | undefined;
+    /** Parent form's data (instance-specific) */
+    parentFormData: any;
+    /** Parent form data context */
+    parentFormDataContext: any;
+}
+export interface UseFormValidationOptions {
+    formRef: React.RefObject<HTMLFormElement | null>;
+    formfields: Record<string, any>;
+    formReff: React.RefObject<any>;
+    control: any;
+    trigger: () => Promise<boolean>;
+    errors: any;
+    formName: string;
+    listener?: any;
+}
+export interface UseFormValidationReturn {
+    validationMessagesRef: React.MutableRefObject<ValidationMessage[]>;
+    validateFieldsOnSubmit: () => Promise<boolean>;
+    buildValidationMessages: () => ValidationMessage[];
+    exposeValidationMessages: (messages: ValidationMessage[]) => void;
+}
+export interface UseFormOperationsOptions {
+    formName: string;
+    formfields: Record<string, any>;
+    formRef: React.RefObject<HTMLFormElement | null>;
+    formReff: React.RefObject<any>;
+    /** The detected form type */
+    formType: FormType;
+    fullDataPath?: string;
+    parentFormDataContext?: any;
+    clearFormData: (data?: Record<string, any>) => void;
+    resetFormData: (data: any) => void;
+    trigger: () => Promise<boolean>;
+    submit: () => Promise<boolean | undefined>;
+    listener?: any;
+    /** Widget form type (e.g., 'live-filter') */
+    widgetFormType?: string;
+    autoupdate?: string;
+    debouncedFilter?: () => void;
+}
+export interface UseFormOperationsReturn {
+    formreset: () => Promise<void>;
+    create: () => void;
+    edit: (data: any) => void;
+    setFormData: (data: any) => void;
+    saveAndNew: () => void;
+    saveAndView: () => void;
+    showViewMode: boolean;
+    setShowViewMode: React.Dispatch<React.SetStateAction<boolean>>;
+}
+export interface UseFormSubmissionOptions {
+    formName: string;
+    formfields: Record<string, any>;
+    formDataref: React.MutableRefObject<any>;
+    getValues: () => any;
+    /** The detected form type */
+    formType: FormType;
+    validateFieldsOnSubmit: () => Promise<boolean>;
+    resetFormData: (data: any) => void;
+    toggleMessage: (state: boolean, msg?: string, type?: string) => void;
+    setShowViewMode: React.Dispatch<React.SetStateAction<boolean>>;
+    listener?: any;
+    datasource?: any;
+    formSubmit: Function;
+    widgettype?: string;
+    onBeforeSubmit?: Function;
+    onSubmit?: Function;
+    onResult?: Function;
+    onSuccess?: Function;
+    onError?: Function;
+    insertmessage?: string;
+    updatemessage?: string;
+    deletemessage?: string;
+    postmessage?: string;
+    errormessage?: string;
+    messagelayout?: string;
+    standalone?: boolean;
+}
+export interface UseFormSubmissionReturn {
+    submit: (e?: any) => Promise<boolean | undefined>;
+    deleteEntry: (e?: any) => Promise<void>;
+    handleFormSubmit: (data: any, e?: any, operationType?: string) => Promise<void>;
+}
+export default BaseFormProps;

package/components/data/form/base-form/props.js

@@ -0,0 +1,180 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.defaultProps = exports.FormType = exports.FORM_TYPE_CONFIGS = void 0;
+exports.detectFormType = detectFormType;
+exports.getFormTypeConfig = getFormTypeConfig;
+exports.isChildFormType = isChildFormType;
+exports.usesPrefixedFields = usesPrefixedFields;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+// ============================================================================
+// Form Type System
+// ============================================================================
+/**
+ * Defines the different scenarios for form nesting and their configurations.
+ * This provides a single source of truth for understanding form behavior
+ * based on its relationship to parent forms.
+ *
+ * Scenarios:
+ * - STANDALONE: No parent form (root form)
+ * - DIRECT_CHILD: Form -> Form (direct nesting with parentForm prop)
+ * - LIST_CHILD: Form -> List -> Form (form inside a list widget)
+ * - PREFAB_CHILD: Form -> Prefab -> Form (form inside a prefab, context-based)
+ * - LIST_PREFAB_CHILD: Form -> List -> Prefab -> Form (prefab inside list)
+ */
+var FormType = exports.FormType = /*#__PURE__*/function (FormType) {
+  /** Root form with no parent */
+  FormType["STANDALONE"] = "standalone";
+  /** Form -> Form: Direct child form with parentForm prop */
+  FormType["DIRECT_CHILD"] = "direct_child";
+  /** Form -> List -> Form: Child form inside a list widget */
+  FormType["LIST_CHILD"] = "list_child";
+  /** Form -> Prefab -> Form: Form inside a prefab (context-based relationship) */
+  FormType["PREFAB_CHILD"] = "prefab_child";
+  /** Form -> List -> Prefab -> Form: Form inside a prefab that's inside a list */
+  FormType["LIST_PREFAB_CHILD"] = "list_prefab_child";
+  return FormType;
+}({});
+/**
+ * Configuration for each form type.
+ * Determines how the form handles field registration, data reset, and data sourcing.
+ */
+/**
+ * Configuration map for all form types.
+ * Single source of truth for form behavior based on type.
+ */
+var FORM_TYPE_CONFIGS = exports.FORM_TYPE_CONFIGS = (0, _defineProperty2["default"])((0, _defineProperty2["default"])((0, _defineProperty2["default"])((0, _defineProperty2["default"])((0, _defineProperty2["default"])({}, FormType.STANDALONE, {
+  type: FormType.STANDALONE,
+  fieldRegistration: "direct",
+  dataResetStrategy: "flat",
+  dataSourcePriority: ["propsData"],
+  emitsToParent: false
+}), FormType.DIRECT_CHILD, {
+  type: FormType.DIRECT_CHILD,
+  fieldRegistration: "prefixed",
+  dataResetStrategy: "wrapped",
+  dataSourcePriority: ["childFormData"],
+  emitsToParent: true
+}), FormType.LIST_CHILD, {
+  type: FormType.LIST_CHILD,
+  fieldRegistration: "prefixed",
+  dataResetStrategy: "wrapped",
+  dataSourcePriority: ["childFormData"],
+  emitsToParent: true
+}), FormType.PREFAB_CHILD, {
+  type: FormType.PREFAB_CHILD,
+  fieldRegistration: "direct",
+  dataResetStrategy: "flat",
+  dataSourcePriority: ["prefabContextData"],
+  emitsToParent: true
+}), FormType.LIST_PREFAB_CHILD, {
+  type: FormType.LIST_PREFAB_CHILD,
+  fieldRegistration: "direct",
+  dataResetStrategy: "flat",
+  dataSourcePriority: ["prefabContextData"],
+  emitsToParent: true
+});
+
+/**
+ * Get the configuration for a form type.
+ */
+function getFormTypeConfig(formType) {
+  return FORM_TYPE_CONFIGS[formType];
+}
+
+// ============================================================================
+// Form Type Helper Functions
+// ============================================================================
+
+/** Check if form is any type of child form (not standalone) */
+function isChildFormType(formType) {
+  return formType !== FormType.STANDALONE;
+}
+
+/** Check if form uses prefixed field registration (direct/list child) */
+function usesPrefixedFields(formType) {
+  return FORM_TYPE_CONFIGS[formType].fieldRegistration === "prefixed";
+}
+
+/**
+ * Detect form type based on props and context values.
+ * This is the main detection logic used by useParentFormRelationship.
+ */
+function detectFormType(params) {
+  var hasParentFormProp = params.hasParentFormProp,
+    hasChildDatasetNode = params.hasChildDatasetNode,
+    hasPrefabContext = params.hasPrefabContext,
+    isInList = params.isInList;
+  var hasDirectParentRelation = hasParentFormProp || hasChildDatasetNode;
+  if (hasDirectParentRelation) {
+    return isInList ? FormType.LIST_CHILD : FormType.DIRECT_CHILD;
+  }
+  if (hasPrefabContext) {
+    return isInList ? FormType.LIST_PREFAB_CHILD : FormType.PREFAB_CHILD;
+  }
+  return FormType.STANDALONE;
+}
+
+// ============================================================================
+// Base Form Props
+// ============================================================================
+
+var defaultProps = exports.defaultProps = {
+  captionwidth: "xs-12 sm-3 md-3 lg-3",
+  captionposition: "left",
+  captionalign: "left",
+  autocomplete: "off",
+  method: "post",
+  messagelayout: "Inline",
+  postmessage: "Data posted successfully",
+  errormessage: "An error occurred. Please try again!",
+  tabindex: 0,
+  validationtype: "default",
+  collapsible: false,
+  expanded: true,
+  onReset: function onReset() {},
+  onSubmit: function onSubmit(event, widget, data) {},
+  onError: function onError(event, widget, error) {},
+  onSuccess: function onSuccess(event, widget, data) {},
+  formSubmit: function formSubmit(event, widget, data) {},
+  onChange: function onChange(event, widget, data) {},
+  onBeforeSubmit: function onBeforeSubmit(event, widget, data) {
+    return true;
+  }
+};
+
+// ============================================================================
+// Widget and Form Field Interfaces
+// ============================================================================
+
+/**
+ * Widget data stored in the listener.Widgets proxy for each form
+ */
+
+/**
+ * Listener context passed to widgets via props
+ * Contains global widget registry and app-level utilities
+ */
+
+// ============================================================================
+// useFormDataSync Hook Interfaces
+// ============================================================================
+
+// ============================================================================
+// useParentFormRelationship Hook Interfaces
+// ============================================================================
+
+// ============================================================================
+// useFormValidation Hook Interfaces
+// ============================================================================
+
+// ============================================================================
+// useFormOperations Hook Interfaces
+// ============================================================================
+
+// ============================================================================
+// useFormSubmission Hook Interfaces
+// ============================================================================

package/components/data/form/base-form/utils.d.ts

@@ -0,0 +1,75 @@
+export declare const isAndroid: () => boolean;
+export declare const getFieldLayoutConfig: (captionWidth: string, captionPosition: string, os: string) => any;
+/**
+ * Checks if an element is visible in the viewport
+ */
+export declare const isElementInViewport: (el: HTMLElement) => boolean;
+/**
+ * Focuses on the first invalid field in a form using multiple DOM-based strategies
+ */
+export declare const focusOnFirstInvalidField: (formElement: HTMLElement | null, errorFieldNames?: string[]) => void;
+/**
+ * Scrolls an element into view with smooth behavior
+ */
+export declare const scrollToElement: (el: HTMLElement) => void;
+/**
+ * Converts null values to empty strings in an object
+ */
+export declare const cleanNullValues: (data: Record<string, any>) => Record<string, any>;
+/**
+ * Filters out table column keys from form data
+ * Table columns are prefixed with 'wm_table_column_'
+ */
+export declare const filterTableColumns: (data: any) => any;
+/**
+ * Transforms flat form data to nested object structure using dataKey paths.
+ * Handles PREFAB_CHILD scenario where child form data exists both at root and nested levels.
+ */
+export declare const transformToNestedObject: (data: any, formfields: Record<string, any>, formName: string) => Record<string, any>;
+/**
+ * Checks if data contains any arrays that might need filtering
+ * Used to skip filterArraysByRenderedForms when no arrays exist
+ */
+export declare const hasArrayData: (data: any) => boolean;
+/**
+ * Filters arrays to only include items that have rendered child forms in the DOM.
+ * Also strips nested sibling arrays and dataset-only fields from array items.
+ *
+ * Optimized: Returns data unchanged if no arrays exist or no widgets provided.
+ */
+export declare const filterArraysByRenderedForms: (data: any, widgets: any) => any;
+/**
+ * Merges form data with additional data from formDataref
+ */
+export declare const mergeWithFormDataRef: (data: any, formDataref: any) => any;
+/**
+ * Transforms form data to combine min/max values for range filters
+ */
+export declare const transformRangeFilterData: (data: any) => {};
+import type { ListenerContext, FormWidgetData, FormFieldWidget } from "./props";
+/**
+ * Safely get widget data for a specific form from the listener context
+ * Does not trigger re-renders when used outside dependency arrays
+ */
+export declare const getWidgetFormData: (listener: ListenerContext | undefined, formName: string | undefined) => FormWidgetData | undefined;
+/**
+ * Safely set formdata on the widget registry
+ * Treats this as an imperative side effect - should not be in dependency arrays
+ */
+export declare const setWidgetFormData: (listener: ListenerContext | undefined, formName: string | undefined, formdata: any) => void;
+/**
+ * Get form fields from widget registry
+ */
+export declare const getWidgetFormFields: (listener: ListenerContext | undefined, formName: string | undefined) => Record<string, FormFieldWidget> | undefined;
+/**
+ * Set validation messages on the widget registry
+ */
+export declare const setWidgetValidationMessages: (listener: ListenerContext | undefined, formName: string | undefined, messages: any[]) => void;
+/**
+ * Register a child field in the parent form's widget registry
+ */
+export declare const registerChildFieldInWidget: (listener: ListenerContext | undefined, formName: string | undefined, data: {
+    formKey: string;
+    fieldName: string;
+    widget: any;
+}) => void;