# ngx-t-forms

Enterprise-ready Angular form builder and runtime. Build dynamic, multi-step forms from JSON schemas with calculated fields, API-driven options, file uploads, signatures, and rich text editing.

## Why ngx-t-forms

- JSON-driven form schema with sections, columns, and rich inputs
- Standalone Angular components for fast integration
- Built-in form builder UI and form listing UI
- Calculated fields, dependent logic, and custom validation rules
- API and Mongo pipeline-driven options/value fetching
- Specialized inputs: signature pad, QR code, geo-location, file upload, rich text editor

## Requirements

- Angular `^19.2.6`
- RxJS `~7.8`
- Angular CDK + Material (theme required)
- `ngx-t-forms-types` (type definitions for schemas)

Many specialized inputs are enabled by peer dependencies (EditorJS tools, `signature_pad`, `html5-qrcode`, `qrcode`, `mathjs`, `joi`). Install them if you use those inputs.

## Installation

```bash
npm i ngx-t-forms ngx-t-forms-types
```

Install peer dependencies used by your inputs:

```bash
npm i @angular/material @angular/cdk @angular/animations
npm i @editorjs/editorjs @editorjs/header @editorjs/list @editorjs/paragraph @editorjs/table @editorjs/quote @editorjs/marker @editorjs/image @editorjs/embed @editorjs/code @editorjs/raw @editorjs/delimiter @editorjs/text-variant-tune
npm i signature_pad html5-qrcode qrcode mathjs joi ngx-ui-tour-md-menu db-aggregation-pipeline-builder uuid
```

Add an Angular Material theme (required for all UI components):

```json
// styles (angular.json)
"styles": [
  "node_modules/@angular/material/prebuilt-themes/indigo-pink.css",
  "src/styles.scss"
]
```

## Quick start

### 1) Provide library configuration

`ngx-t-forms` uses a single environment config to wire UI actions and data access.

```ts
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideNgxTForms } from 'ngx-t-forms';
import { NgxTFormsConfig } from 'ngx-t-forms-types';
import { of } from 'rxjs';

const ngxTFormsConfig: NgxTFormsConfig = {
  formBuilder: {
    addNewForm: () => {},
    editForm: (formId: string) => {},
    getForm: (formId: string) => of(null),
    saveFormData: (formId: string | undefined, data: Record<string, any>) => {},
    formSubmittedSuccessfully: (formId?: string) => {},
    toastSuccess: (message: string) => {},
    toastError: (message: string) => {},
    httpGetDataFunction: (url: string, options?: any) => of(null),
    httpPostDataFunction: (url: string, data: any, options?: any) => of(null),
    runMongoDbPipeLine: (payload: any) => of([]),
    fileUpload: (file: string, fileName: string, fileType: string) => of({ url: '' }),
    getUserSignature: () => of(null),
    saveUserSignature: (data: any) => of(null),
    getScoaTree: () => of(null),
    getSCOAAccount: (account: string) => of(null),
    getWorkflowCols: (workflowId: string) => of([]),
    getSelectedDocument: (docId: string) => of(null),
    getWorkflowData: (params: { workflowId: string }) => []  // Required for document picker with documentSourceType 'default'
  }
};

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideNgxTForms(ngxTFormsConfig)
  ]
};
```

### 2) Render a complete form

`UserFormStepperComponent` renders a full, multi-step form from a stored schema.

```ts
import { Component } from '@angular/core';
import { UserFormStepperComponent } from 'ngx-t-forms';

@Component({
  selector: 'app-form-runner',
  standalone: true,
  imports: [UserFormStepperComponent],
  template: `
    <lib-user-form-stepper
      [formId]="formId"
      [initialValues]="initialValues"
      [passParamsOnSubmit]="submitContext">
    </lib-user-form-stepper>
  `
})
export class FormRunnerComponent {
  formId = 'your-form-id';
  initialValues = {};
  submitContext = { submittedBy: 'user-id' };
}
```

## Core components

- `FormBuilderComponent`: UI to build and edit forms
- `FormsComponent`: list and manage saved forms
- `UserFormStepperComponent`: runtime stepper UI to complete a form
- `TFormInputComponent`: render a single input definition
- `TDynamicDataEditComponent` / `TDynamicDataViewComponent`: schema editors and read-only views

All components are standalone; import them directly in your `imports` array.

## Form schema (overview)

Form schemas are typed in `ngx-t-forms-types`. The core pattern is:

```ts
import { ElementTypes, InputDataTypes, InputTypes } from 'ngx-t-forms-types';

const form = {
  slides: [
    {
      sectionId: 'section-1',
      label: 'Customer Details',
      columns: [
        {
          element: ElementTypes.Input,
          dataType: InputDataTypes.String,
          type: InputTypes.Text,
          label: 'Full name',
          formControlName: 'fullName',
          id: 'fullName',
          colSize: 6,
          required: true
        }
      ]
    }
  ]
};
```

### Calculated fields

Use `calculatedFieldRules` to compute values based on other inputs:

```ts
{
  element: ElementTypes.Input,
  isCalculatedField: true,
  formControlName: 'total',
  calculatedFieldRules: {
    variables: [
      { variable: 'a', inputId: 'price', formControlName: 'price' },
      { variable: 'b', inputId: 'qty', formControlName: 'qty' }
    ],
    formula: 'a * b'
  }
}
```

## Scripts (library development)

- Build: `ng build ngx-t-forms --configuration production`
- Test: `ng test ngx-t-forms`
- Publish: `ng build ngx-t-forms` then `npm publish` from `dist/ngx-t-forms`

## Repository

- Repo: `https://github.com/petoriT/01ANGULAR-WORKSPACE`

## License

Private — all rights reserved. Permission to use, copy, or redistribute must be obtained from the founder and creator, Mashego Terrence.