npm package: @ruc-lib/metaform
Description: The main aim of meta forms is to make forms based on JSON along with validation support, dependent fields, custom theming etc.
Latest version: 4.0.0

# ruclib-metaform

The main aim of meta forms is to make forms based on JSON along with validation support, dependent fields, custom theming etc.

## RUC Library Installation Guide

Users can easily install the RUC (Ruxptest Library) from npm. Additionally, they can also choose to install individual components based on their requirements.
Install RUC Library.

To install the entire RUC library:

`npm install @uxpractice/ruc-lib` 

### Install Individual Component

If you only need the Metaform component:

**For Angular 15:**
```bash
npm install @ruc-lib/metaform@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/metaform@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/metaform@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/metaform@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/metaform@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/metaform@4.0.0
```

> **Note:** When installing in Angular 15-19 apps, you must specify the matching `@angular/material` and `@angular/cdk` versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

### 📦 Version Compatibility

| Angular Version    | Compatible `@ruc-lib/metaform` Version     |
|--------------------|--------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/metaform@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/metaform@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/metaform@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/metaform@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/metaform@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/metaform@^4.0.0`     |

## Usage

To use the metaform component in your project, follow the integration guidelines provided in the documentation. Customize the metaform as per your requirements by adjusting the configuration options mentioned below.

## Import from RUC Library

If you want to use metaform from RUC library then import into `component.ts` like -

`import "@uxpractice/ruc-lib/metaform"`.

If you installed metaform as a individual component then import like - 

`import "@ruc-lib/metaform"`

Then add `RuclibMetaformModule` into `import` array.

Then use the metaform selector in your HTML file.

```
<uxp-ruclib-metaform [rucInputData]="formData" [customTheme]="customTheme"
(rucEvent)="passEvent($event)"></uxp-ruclib-metaform>
```

## Input and Output

Inputs:
•	rucInputData: Data to be passed to the metaform.
•	customTheme: Custom styling/theme for the metaform.

Outputs:
•	rucEvent: Event emitted from the metaform.

## rucInputData configurations options-

```
{
    formType?: 'simple' | 'stepper' // less priority    
    inputType: 'text' | 'password' | 'button' | 'checkbox' | 'email' | 'color' | 'date' | 'file' | 'hidden' | 'image' | 'radio' | 'number' | 'range'    | 'reset' | 'search' | 'submit' | 'time' | 'tel' | 'url' | 'week' | 'month' | 'number' | 'custom' | 'select' | 'rucMultiFileUpload' | 'rucMultiSelect',
    fieldType: string,
    id?: string,
    errorMsg? : boolean,
    name?: string,
    label?: string,
    value?: any,
    className?: string, // to be check    value?: string, //Specifies the default value for an input field    src?: string,
    alt?: string,
    appearance?: string,
    min?: string, //Specifies the minimum value for an input field    
    max?: string, //Specifies the maximum value for an input field    
    width?: string, // like for image    
    height?: string, // like for image    
    checked?: boolean, //Specifies that an input field should be pre-selected when the page loads (for type="checkbox" or type="radio")    
    disabled?: boolean, //Specifies that an input field should be disabled    
    maxlength?: string, //Specifies the maximum number of character for an input field    
    readonly?: boolean, //Specifies that an input field is read only (cannot be changed)    
    required?: boolean, //Specifies that an input field is required (must be filled out)    
    size?: string, //Specifies the width (in characters) of an input field    
    step?: string, //Specifies the legal number intervals for an input field   
    sameRow? : boolean, 
    sameRowColumnWidth? : string, 
    tooltip? : string,
    tooltipPosition? : string, //'after', 'before', 'above', 'below', 'left', 'right'
    pattern? : any, // The input pattern attribute specifies a regular expression that the input field's value is checked against, when the form is submitted. The pattern attribute works with the following input types: text, date, search, url, tel, email, and password.    
    placeholder?: any,
    autofocus?: any, //The input autofocus attribute specifies that an input field should automatically get focus when the page loads.   
    autocomplete?: any,
    customComponentName?: 'multifileupload' | 'multiselect' | 'none',   
    rucMultiselectInput? : {
      rucInputData? : any,
      dataSource? : any
    }, // multiselect interface   
    rucMultiFileUpload? : {rucInputData? : any}
    hasDependentFields?: boolean,
    dependentFieldParentId?: any,
    dependentFields?: MetaFormConfig[];
    selectedParentId?: any;
    toolTipDescription?: string,
    customErrorMessage?: string,
    showErrorOnPopUp?: boolean, //need to be discuss more. as a enhancement    
    groupOptions?: groupOptions[] = [{
    id: string,
    name: string,
    value?: string, // compulsary if its select option part    selected?: boolean 
    disable? : boolean
 }],
    stepperForm?: boolean;
    stepper?: Stepper[] = [{
  stepControl?: string;
  stepperlabel?: string;
  stepperFormData?: MetaFormConfig[];  
 }],
    rucMultiFileUploadInput?:{
      rucInputData? : any,
    }
}

export interface groupOptions{
    id: string,
    name: string,
    value?: string,
    disable? : boolean
 }
 export interface Stepper{
  stepControl?: string;
  stepperlabel?: string;
  stepperFormData?: MetaFormConfig[];  
 }
```

> ⚠️ **IMPORTANT: Custom Theme Usage in Angular Material**

When implementing **custom themes**, such as:

```scss
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}
```


## Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

## Acknowledgements

Thank you for choosing the Metaform Component Library. If you have any feedback or suggestions, please let us know!