@masterteam/forms 0.0.35 → 0.0.36

package/types/masterteam-forms-client-form.d.ts

@@ -0,0 +1,337 @@
+import * as _angular_core from '@angular/core';
+import { OnDestroy } from '@angular/core';
+import { FormControl } from '@angular/forms';
+import { DynamicFormConfig } from '@masterteam/components';
+import * as _masterteam_forms_client_form from '@masterteam/forms/client-form';
+import { Observable } from 'rxjs';
+
+interface Response<T> {
+    endpoint: string;
+    status: number;
+    code: number;
+    locale: string;
+    message?: string | null;
+    errors?: any | null;
+    data: T;
+    cacheSession?: string;
+}
+type ProcessFormMode = 'Approval' | 'Direct';
+type ProcessFormSubmitStatus = 'PendingApproval' | 'Executed';
+type OperationType = 'FormOperation' | 'ActionOperation';
+type ProcessFormSource = 'Step' | 'ModuleFallback' | 'LevelFallback' | 'None';
+interface ProcessFormLoadRequest {
+    moduleKey: string;
+    operationKey: string;
+    moduleId?: number;
+    levelId?: number;
+    levelDataId?: number;
+    moduleDataId?: number;
+    requestSchemaId?: number;
+    draftProcessId?: number;
+    preview?: boolean;
+}
+interface ProcessFormLoadResponse {
+    mode: ProcessFormMode;
+    formSource: ProcessFormSource;
+    requiresForm: boolean;
+    requestSchemaId: number | null;
+    requestId: number | null;
+    stepId: number | null;
+    stepSchemaId: number | null;
+    stepName: string | null;
+    formConfiguration: ClientFormConfiguration | null;
+    values: ProcessFormValue[];
+    context: ProcessFormContext;
+}
+interface ProcessFormSubmitRequest {
+    moduleKey: string;
+    operationKey: string;
+    moduleId?: number;
+    levelId?: number;
+    levelDataId?: number;
+    moduleDataId?: number;
+    requestSchemaId?: number;
+    draftProcessId?: number;
+    returnUrl?: string;
+    values: ProcessFormSubmitValue[];
+}
+interface ProcessFormSubmitValue {
+    requestPropertyId?: number;
+    propertyKey: string;
+    value: any;
+}
+interface ProcessFormSubmitResponse {
+    status: ProcessFormSubmitStatus;
+    requestSchemaId: number | null;
+    requestId: number | null;
+    createdEntityId: number | null;
+    message: string | null;
+}
+interface ProcessFormValue {
+    propertyKey: string;
+    value: any;
+    metadata?: ProcessFormValueMetadata;
+}
+interface ProcessFormValueMetadata {
+    propertyId: number;
+    key: string;
+    viewType: string;
+    source: string;
+}
+interface ProcessFormContext {
+    moduleKey: string;
+    operationKey: string;
+    moduleId: number | null;
+    levelId: number | null;
+    levelDataId: number | null;
+    moduleDataId: number | null;
+    requestSchemaId: number | null;
+    requestId: number | null;
+    stepId: number | null;
+    stepSchemaId: number | null;
+    preview: boolean;
+}
+type ClientFieldWidth = '25' | '50' | '100';
+interface ClientFormConfiguration {
+    isActive: boolean;
+    sections: ClientFormSection[];
+    validations?: ClientValidationRule[];
+}
+interface ClientFormSection {
+    id: string;
+    name: {
+        en: string;
+        ar: string;
+    };
+    order: number;
+    fields: ClientFormField[];
+}
+interface ClientFormField {
+    id: string;
+    sectionId: string;
+    propertyKey: string;
+    property?: ClientPropertyItem;
+    width: ClientFieldWidth;
+    order: number;
+    hiddenInCreation?: boolean;
+    hiddenInEditForm?: boolean;
+    isRequired?: boolean;
+    isRead?: boolean;
+    isWrite?: boolean;
+    showConditionalDisplayFormula?: boolean;
+    conditionalDisplayFormula?: string;
+}
+interface ClientPropertyItem {
+    key: string;
+    propertyId?: number;
+    name: string | Record<string, string>;
+    viewType?: string;
+    configuration?: Record<string, unknown>;
+    [key: string]: any;
+}
+interface ClientValidationRule {
+    id: string | number;
+    formulaTokens: string;
+    formulaText: string;
+    message: {
+        en: string;
+        ar: string;
+    };
+    severity: 'error' | 'warning';
+    enabled: boolean;
+}
+interface FormRequiredInterception {
+    requestSchemaId: number;
+    operationType: OperationType;
+    status: 'FormRequired';
+    message: string;
+    levelId: number;
+    levelDataId: number;
+    moduleDataId: number;
+}
+/**
+ * Type guard to detect a FormRequired interception response from legacy commands.
+ * Use in HTTP interceptors to redirect to process-forms flow.
+ */
+declare function isFormRequiredInterception(response: any): response is FormRequiredInterception;
+
+/**
+ * Per-instance signal-based state for ClientForm.
+ *
+ * NOT providedIn root — each ClientForm component provides its own instance
+ * via `providers: [ClientFormStateService]`, enabling multiple independent
+ * forms on the same page.
+ */
+declare class ClientFormStateService {
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly submitting: _angular_core.WritableSignal<boolean>;
+    readonly error: _angular_core.WritableSignal<string | null>;
+    readonly submitError: _angular_core.WritableSignal<string | null>;
+    readonly loadResponse: _angular_core.WritableSignal<ProcessFormLoadResponse | null>;
+    readonly submitResponse: _angular_core.WritableSignal<ProcessFormSubmitResponse | null>;
+    readonly isLoaded: _angular_core.Signal<boolean>;
+    readonly mode: _angular_core.Signal<ProcessFormMode | null>;
+    readonly isApproval: _angular_core.Signal<boolean>;
+    readonly isDirect: _angular_core.Signal<boolean>;
+    readonly formSource: _angular_core.Signal<ProcessFormSource | null>;
+    readonly isFallbackForm: _angular_core.Signal<boolean>;
+    readonly requiresForm: _angular_core.Signal<boolean>;
+    readonly formConfiguration: _angular_core.Signal<ClientFormConfiguration | null>;
+    readonly values: _angular_core.Signal<ProcessFormValue[]>;
+    readonly context: _angular_core.Signal<ProcessFormContext | null>;
+    readonly stepName: _angular_core.Signal<string | null>;
+    readonly requestSchemaId: _angular_core.Signal<number | null>;
+    readonly requestId: _angular_core.Signal<number | null>;
+    readonly stepId: _angular_core.Signal<number | null>;
+    readonly stepSchemaId: _angular_core.Signal<number | null>;
+    /** Process virtual fields (Request_Date, Step_Name, etc.) — read-only display */
+    readonly virtualFields: _angular_core.Signal<ProcessFormValue[]>;
+    /** Editable form values (non-virtual) */
+    readonly formValues: _angular_core.Signal<ProcessFormValue[]>;
+    readonly isSubmitted: _angular_core.Signal<boolean>;
+    readonly submitStatus: _angular_core.Signal<_masterteam_forms_client_form.ProcessFormSubmitStatus | null>;
+    readonly isPendingApproval: _angular_core.Signal<boolean>;
+    readonly isExecuted: _angular_core.Signal<boolean>;
+    readonly createdEntityId: _angular_core.Signal<number | null>;
+    setLoadResponse(response: ProcessFormLoadResponse): void;
+    setSubmitResponse(response: ProcessFormSubmitResponse): void;
+    setError(message: string): void;
+    setSubmitError(message: string): void;
+    reset(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClientFormStateService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ClientFormStateService>;
+}
+
+/**
+ * Client Form — Runtime process form component.
+ *
+ * Self-contained, signal-based (no NGXS). Each instance manages its own state
+ * via a component-scoped `ClientFormStateService`.
+ *
+ * **No action buttons in template.** Parent controls all actions via `viewChild()`:
+ *
+ * ```html
+ * <mt-client-form #processForm [moduleKey]="'Risk'" [operationKey]="'CloseRisk'" />
+ * <button (click)="processForm.load()">Load</button>
+ * <button (click)="processForm.submit()">Submit</button>
+ * ```
+ *
+ * Or programmatically:
+ * ```typescript
+ * readonly processForm = viewChild.required(ClientForm);
+ * this.processForm().load();
+ * this.processForm().submit();
+ * ```
+ */
+declare class ClientForm implements OnDestroy {
+    private readonly api;
+    protected readonly state: ClientFormStateService;
+    private loadSub?;
+    private submitSub?;
+    readonly moduleKey: _angular_core.InputSignal<string>;
+    readonly operationKey: _angular_core.InputSignal<string>;
+    readonly moduleId: _angular_core.InputSignal<number | undefined>;
+    readonly levelId: _angular_core.InputSignal<number | undefined>;
+    readonly levelDataId: _angular_core.InputSignal<number | undefined>;
+    readonly moduleDataId: _angular_core.InputSignal<number | undefined>;
+    readonly requestSchemaId: _angular_core.InputSignal<number | undefined>;
+    readonly draftProcessId: _angular_core.InputSignal<number | undefined>;
+    readonly preview: _angular_core.InputSignal<boolean>;
+    readonly returnUrl: _angular_core.InputSignal<string | undefined>;
+    readonly readonly: _angular_core.InputSignal<boolean>;
+    readonly autoLoad: _angular_core.InputSignal<boolean>;
+    readonly formMode: _angular_core.InputSignal<"create" | "edit">;
+    readonly lang: _angular_core.InputSignal<"en" | "ar">;
+    readonly loaded: _angular_core.OutputEmitterRef<ProcessFormLoadResponse>;
+    readonly submitted: _angular_core.OutputEmitterRef<ProcessFormSubmitResponse>;
+    readonly errored: _angular_core.OutputEmitterRef<string>;
+    readonly modeDetected: _angular_core.OutputEmitterRef<ProcessFormMode>;
+    readonly formSourceDetected: _angular_core.OutputEmitterRef<ProcessFormSource>;
+    readonly formControl: FormControl<Record<string, any> | null>;
+    readonly formConfig: _angular_core.Signal<DynamicFormConfig | null>;
+    readonly initialValues: _angular_core.Signal<Record<string, any>>;
+    readonly virtualFields: _angular_core.Signal<ProcessFormValue[]>;
+    readonly hasVirtualFields: _angular_core.Signal<boolean>;
+    private readonly autoLoadEffect;
+    private readonly patchValuesEffect;
+    /**
+     * Load form configuration from the API.
+     * Builds request from current input values.
+     */
+    load(): void;
+    /**
+     * Submit the current form values.
+     * Builds submit request from form value + load context.
+     */
+    submit(): void;
+    /**
+     * Get the current form value as a flat key-value object.
+     */
+    getFormValue(): Record<string, any>;
+    /**
+     * Get the current form value mapped to submit payload format.
+     */
+    getSubmitValues(): ProcessFormSubmitValue[];
+    /**
+     * Check whether the current form state is valid.
+     */
+    isValid(): boolean;
+    /**
+     * Reset the component to its initial state.
+     */
+    reset(): void;
+    ngOnDestroy(): void;
+    private buildLoadRequest;
+    private buildSubmitRequest;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClientForm, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ClientForm, "mt-client-form", never, { "moduleKey": { "alias": "moduleKey"; "required": true; "isSignal": true; }; "operationKey": { "alias": "operationKey"; "required": true; "isSignal": true; }; "moduleId": { "alias": "moduleId"; "required": false; "isSignal": true; }; "levelId": { "alias": "levelId"; "required": false; "isSignal": true; }; "levelDataId": { "alias": "levelDataId"; "required": false; "isSignal": true; }; "moduleDataId": { "alias": "moduleDataId"; "required": false; "isSignal": true; }; "requestSchemaId": { "alias": "requestSchemaId"; "required": false; "isSignal": true; }; "draftProcessId": { "alias": "draftProcessId"; "required": false; "isSignal": true; }; "preview": { "alias": "preview"; "required": false; "isSignal": true; }; "returnUrl": { "alias": "returnUrl"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "autoLoad": { "alias": "autoLoad"; "required": false; "isSignal": true; }; "formMode": { "alias": "formMode"; "required": false; "isSignal": true; }; "lang": { "alias": "lang"; "required": false; "isSignal": true; }; }, { "loaded": "loaded"; "submitted": "submitted"; "errored": "errored"; "modeDetected": "modeDetected"; "formSourceDetected": "formSourceDetected"; }, never, never, true, never>;
+}
+
+/**
+ * Stateless HTTP service for process-forms runtime APIs.
+ * Root-provided — safe to share across multiple ClientForm instances.
+ */
+declare class ClientFormApiService {
+    private readonly http;
+    private readonly baseUrl;
+    /**
+     * Load form configuration and values for a given operation context.
+     * Backend determines mode (Approval vs Direct) based on published schema.
+     */
+    load(request: ProcessFormLoadRequest): Observable<Response<ProcessFormLoadResponse>>;
+    /**
+     * Submit form values. Result depends on mode:
+     * - Approval → status: 'PendingApproval'
+     * - Direct   → status: 'Executed'
+     */
+    submit(request: ProcessFormSubmitRequest): Observable<Response<ProcessFormSubmitResponse>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClientFormApiService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ClientFormApiService>;
+}
+
+/**
+ * Convert a runtime FormConfiguration into a DynamicFormConfig
+ * that can be passed directly to `<mt-dynamic-form>`.
+ *
+ * @param config  The form configuration from the load API
+ * @param lang    Current UI language ('en' | 'ar')
+ * @param mode    'create' or 'edit' — filters hidden fields accordingly
+ */
+declare function mapToDynamicFormConfig(config: ClientFormConfiguration, lang?: 'en' | 'ar', mode?: 'create' | 'edit'): DynamicFormConfig;
+/**
+ * Convert API property values into a flat key-value object
+ * suitable for `formControl.patchValue()`.
+ *
+ * Only includes non-virtual (editable) values.
+ */
+declare function mapValuesToFormValue(values: ProcessFormValue[]): Record<string, any>;
+/**
+ * Convert the current form value back into the submit payload format.
+ *
+ * Maps `requestPropertyId` from the load response metadata where available,
+ * so backend can match to schema request properties.
+ */
+declare function mapFormValueToSubmitValues(formValue: Record<string, any>, loadResponse: ProcessFormLoadResponse): ProcessFormSubmitValue[];
+
+export { ClientForm, ClientFormApiService, ClientFormStateService, isFormRequiredInterception, mapFormValueToSubmitValues, mapToDynamicFormConfig, mapValuesToFormValue };
+export type { ClientFieldWidth, ClientFormConfiguration, ClientFormField, ClientFormSection, ClientPropertyItem, ClientValidationRule, FormRequiredInterception, OperationType, ProcessFormContext, ProcessFormLoadRequest, ProcessFormLoadResponse, ProcessFormMode, ProcessFormSource, ProcessFormSubmitRequest, ProcessFormSubmitResponse, ProcessFormSubmitStatus, ProcessFormSubmitValue, ProcessFormValue, ProcessFormValueMetadata, Response };