npm package: @sgng/dyn-forms
Description: **@sgng/dyn-forms** is an npm package tailored for Angular projects. It offers Angular components, an interface, and an enum to simplify the creation of forms encompassing various input types like text, number, and select. These input types seamlessly int
Author: Subhendu Ghosh
Latest version: 6.3.0

# @sgng/dyn-forms
**@sgng/dyn-forms** is an npm package tailored for Angular projects. It offers Angular components, an interface, and an enum to simplify the creation of forms encompassing various input types like text, number, and select. These input types seamlessly integrate with Angular's data-binding functionality. The package dynamically renders forms in the browser by accepting input field metadata or an array thereof.

# Table of contents
- [Version Compatibility](#version-compatibility)
- [Supported Input Fields](#supported-input-fields)
- [Properties](#properties)
	- [Common](#common)
	- [Specific for each input types](#specific-for-each-input-types)
- [Directives](#directives)
- [Installation](#installation)
- [Setup](#setup)
- [Usage/Examples](#usageexamples)
	- [Import Statement](#import-statement)
	- [Single Input Field](#single-input-field)
	- [Input Fields Array](#input-fields-array)
	- [Managing Input Field Values](#managing-input-field-values)
	- [Bootstrap Styling](#bootstrap-styling)
-  [Bug Reports or Feature Requests](#bug-reports-or-feature-requests)
- [Developers](#developers)
- [Support](#support)

# Version Compatibility
|Version|Angular Version|
|--|--|
|6.x.x (LST)|21.x.x|
|5.x.x|20.x.x|
|4.x.x|19.x.x|
|3.x.x|18.x.x|
|2.x.x|17.x.x|
|1.x.x|16.x.x|

# Supported Input Fields
|Input Type|Version|Desctiptions|
|--|--|--|
|Checkbox|1.0.0|Checkbox buttons let a user select **one or more** options of a limited number of choices.|
|Color|1.0.0|Used for input fields that should contain a **color**. Depending on browser support, a color picker can show up in the input field.|
|DataList|1.0.0|Provide a **list of pre-defined options** for an `input` element.|
|Date|1.0.0|Used for input fields that should contain a **date**. Depending on browser support, a date picker can show up in the input field.|
|Datetime|1.0.0|Specifies a **date and time** input field, with no time zone. Depending on browser support, a date and time picker can show up in the input field.|
|Email|1.0.0|Used for input fields that should contain an **e-mail address**. Depending on browser support, the e-mail address can be automatically validated when submitted. Some smartphones recognize the email type, and add ".com" to the keyboard to match email input.|
|File|1.0.0|Defines a **file-select** field and a "Browse" button for file uploads. ***Don't support two-way data-binding functionality.***|
|Month|1.0.0|Allows the user to select a **month and year**. Depending on browser support, a month picker can show up in the input field.|
|Number|1.0.0|Defines a **numeric** input field.|
|Password|1.0.0|Defines a **password** input field.|
|Radio|1.0.0|Radio buttons let a user select **only one** of a limited number of choices.|
|Range|1.0.0|Defines a control for entering a **number** whose exact value is not important (like a slider control).|
|Select|1.0.0|Define the available options in the **drop-down list**.|
|Tel|1.0.0|Used for input fields that should contain a **telephone number**.|
|Text|1.0.0|Defines a **single-line** text input field.|
|Textarea|1.0.0|Defines a **multi-line** text input control|
|Time|1.0.0|Allows the user to select a **time** (no time zone). Depending on browser support, a time picker can show up in the input field.|
|URL|1.0.0|Used for input fields that should contain a **URL address**.|
|Week|1.0.0|Allows the user to select a **week and year**. Depending on browser support, a week picker can show up in the input field.|

# Properties
**(*)** marked properties are required.

## Common
The below properties are common for all the input types.

|Name|Version|Data Type|Default Value
|-|-|-|-|
|id*|1.0.0|`string`||
|type*|1.0.0|`InputType`||
|label|1.0.0|`string`|`undefined`|

## Specific for each input types
### Checkbox
|Name|Version|Data Type|Default Value
|-|-|-|-|
|options*|1.0.0|`string[]`|`[]` (empty string array)|
|value|1.0.0|`string[]`|`undefined`|
|disabled|6.2.0|`string[]`|`undefined`|

### Color
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### DataList
|Name|Version|Data Type|Default Value
|-|-|-|-|
|options*|1.0.0|`string[]`|`[]` (empty string array)|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Date
|Name|Version|Data Type|Default Value
|-|-|-|-|
|min|6.3.0|`Date`|`undefined`|
|max|6.3.0|`Date`|`undefined`|
|value|1.0.0|`Date`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Datetime
|Name|Version|Data Type|Default Value
|-|-|-|-|
|min|6.3.0|`Date`|`undefined`|
|max|6.3.0|`Date`|`undefined`|
|value|1.0.0|`Date`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Email
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### File
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`File`|`undefined`|
|accept|6.3.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Month
|Name|Version|Data Type|Default Value
|-|-|-|-|
|min|6.3.0|`string`|`undefined`|
|min|6.3.0|`string`|`undefined`|
|value|1.0.0|`string` (Format: YYYY-MM)|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Number
|Name|Version|Data Type|Default Value
|-|-|-|-|
|min|6.3.0|`number`|`undefined`|
|max|6.3.0|`number`|`undefined`|
|step|6.3.0|`number`|`undefined`|
|value|1.0.0|`number`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Password
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Radio
|Name|Version|Data Type|Default Value
|-|-|-|-|
|options*|1.0.0|`string[]`|`[]` (empty string array)|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`string[]`|`undefined`|

### Range
|Name|Version|Data Type|Default Value
|-|-|-|-|
|min*|1.0.0|`number`||
|max*|1.0.0|`number`||
|value|1.0.0|`number`|`undefined`|
|step|1.0.0|`number`|`1`|
|disabled|6.2.0|`boolean`|`undefined`|

### Select
|Name|Version|Data Type|Default Value
|-|-|-|-|
|options*|1.0.0|`string[]`|`[]` (empty string array)|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Tel
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Text
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Textarea
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Time
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### URL
|Name|Version|Data Type|Default Value
|-|-|-|-|
|value|1.0.0|`string`|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

### Week
|Name|Version|Data Type|Default Value
|-|-|-|-|
|min|6.3.0|`string`|`undefined`|
|max|6.3.0|`string`|`undefined`|
|value|1.0.0|`string` (Format: YYYY-Www)|`undefined`|
|disabled|6.2.0|`boolean`|`undefined`|

# Directives
|Name|Version|Description|
|-|-|-|
|sgngBootstrap|6.1.0|Apply basic Bootstrap styling

# Installation
**With  [npm](https://npmjs.org/):**
```ps1
npm install @sgng/dyn-forms
```

# Setup
Import the `FormItemComponent` from the `@sgng/dyn-forms` package.

**app.ts**
```ts
...
import { FormItemComponent } from  '@sgng/dyn-forms';
...

@Component({
  selector: ...,
  imports: [FormItemComponent],
  templateUrl: ...,
  styleUrl: ...
})
export class AppComponent { }
```

# Usage/Examples
## Import Statement
Imports `FormItem` and `InputType` from the `@sgng/dyn-forms` library into the component file.

**app.ts**
```ts
import { FormItem, InputType } from  "@sgng/dyn-forms";
```

## Single Input Field
1. **Define a Property**:
   - In your component file, define a property named `inputField` with the type `FormItem<InputType.TEXT>`. This indicates it is a `FormItem` with a specific `InputType` such as `TEXT`.

2. **Initialize the Property**:
   - Initialize the `inputField` property as an object with the relevant properties. Refer to the [Properties](#properties) section for the ***common*** and ***specific*** properties for each input type:
     - Set the `type` property to match the type specified for `inputField`, e.g., `type: InputType.TEXT`.
     - Add other ***required*** and ***optional*** properties with appropriate values as detailed in the [Properties](#properties) section.

**app.ts**
```typescript
export class AppComponent {
	...
	inputField: FormItem<InputType.TEXT> = {
		type: InputType.TEXT,
		id: 'formItem'
	};
	...
}
```

3. **Use the Custom Component**:
   - In your HTML file, use the `<sgng-form-item>` custom component provided by the `@sgng/dyn-forms` library.
   - Bind the `inputField` property of your component class to the `item` input property of the `<sgng-form-item>` component using property binding.

**app.html**
```html
<sgng-form-item [item]="inputField"></sgng-form-item>
```

## Input Fields Array
1. **Define a Property**:
	- In your component file, define a property named `inputFields` with the type `FormItem<InputType>[]`. This indicates it is an array of `FormItem` objects, each with a type from the `InputType` enumeration.

2.  **Initialize the Property**:
    -   Initialize the `inputFields` property as an array containing multiple form item objects with their relevant properties:
        -   Set the `type` property of each form item object to an item from the `InputType` enumeration, e.g., `type: InputType.TEXT` or `type: InputType.NUMBER`.
        -   Add other required and optional properties with appropriate values as detailed in the [Properties](#properties) section.

**app.ts**
```typescript
export class AppComponent {
	...
	inputFields:  FormItem<InputType>[] = [
		{
			type:  InputType.TEXT,
			id:  'textInput'
		},
		{
			type:  InputType.NUMBER,
			id:  'numberInput'
		}
	];
	...
}
```
3.  **Use the Custom Component**:
    -   In your HTML file, use the `<sgng-form-item>` custom component provided by the `@sgng/dyn-forms` library.
    -   Bind the `inputFields` property of your component class to the `items` input property of the `<sgng-form-item>` component using property binding.

**app.html**
```html
<sgng-form-item [items]="inputFields"></sgng-form-item>
```
## Managing Input Field Values
Utilize the `value` property to retrieve or assign values to the input field(s).

## Bootstrap Styling
1. **Add `@ng-bootstrap` Package**
	- Ensure that the `@ng-bootstrap` package is installed and used in your project. You can refer to the documentation for more details [here](https://ng-bootstrap.github.io/#/home).

2. **Import the directive**:
	- Imports `BootstrapDirective` class from the `@sgng/dyn-forms` library into the component file.

**app.ts**
```ts
...
import {
	...,
	BootstrapDirective
} from  '@sgng/dyn-forms';
...

@Component({
  selector: ...,
  imports: [
	...,
	BootstrapDirective
  ],
  templateUrl: ...,
  styleUrl: ...
})
export class AppComponent { }
```

3. **Use the directive**:
	- Use the `sgngBootstrap` directive with the custom `<sgng-form-item>` tag.
	- The directive supports both a single input field and an array of input fields.

**app.html**
```html
<!-- Single Input Field -->
<sgng-form-item [item]="inputField" sgngBootstrap></sgng-form-item>

<!-- Input Fields Array-->
<sgng-form-item [items]="inputFields" sgngBootstrap></sgng-form-item>
```

# Bug Reports or Feature Requests
Help us provide you with better service. [Click here](https://forms.gle/kjVQJ9HwH39gxXuDA) to submit a Bug Report or Feature Request form.

# Developers
| [![Subhendu Ghosh](https://github.com/Subhendughosh030.png?size=100)](https://www.linkedin.com/in/subhendughosh030/) |
|-|
| [Subhendu Ghosh](https://www.linkedin.com/in/subhendughosh030/) |

# Support

If you find this project useful and would like to support its development, please consider making a small donation. Your contributions help maintain and improve the project for everyone.

[![Donate](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.me/subhendughosh030)

Thank you for your support!