sdk-textbox/README.md

Simple to use (Angular) textbox for controlling input while typing.

<img src="https://www.soodohkohd.com/assets/images/logo.png" title="soo-doh-kohd" height="200"/>

## Description:
The sdk-textbox is a simple to use text field for controlling input while typing. You can prevent unwanted characters and force desired formats.

## Angular Compatibility Chart

| Version | Compatibility |
|---------|---------------|
| 16      | EOL 2025      |
| 17      | EOL 2025      |
| 18      | ✔             |
| 19      | ✔             |
| 20      | Q3 2025       |

## INSTALLATION:
Using NPM:

```bash
npm install --save sdk-textbox
```

## CONFIGURATION:
To configure the ```sdk-textbox``` for your application, add the following lines to your app.module.ts file:

```typescript
import { SDKTextboxModule } from 'sdk-textbox';

@NgModule({
    imports: [
        SDKTextboxModule
    ]
})
export class AppModule { }
```

## PROPERTIES:
- ```validCharacters (string | null)```: Specify the type of input.
    - ```alpha```: Letters (upper/lower) only.
    - ```numeric```: Numbers only.
    - ```alphanumeric```: All letters (upper/lower) and numbers.
    - ```decimal```: Numbers only with 1 decimal (.) anywhere and 1 dash (-) at the beginning only.
    - ```currency```: Numbers ONLY with 1 decimal (.) anywhere and 1 dash (-) at the beginning only.
    - ```email```: Email address with ```onblur``` (exiting field) formatting.
    - ```calendar```: Calendar with available popup (component) selector.
        - Default pattern is ```YYYY-MM-DD```.
        - Use ```nocomponent``` attribute to prevent popup.
    - ```latitude```: -90 to 90.
    - ```longitude```: -180 to 180.
    - ```custom```: "Custom" set of characters based on provided pattern.
        - See the ```validCharacters="custom"``` section for more information.
- ```value (string | null)```: Specify the current value.
- ```hint (string | null)```: Specify the placeholder.
- ```pattern (string | null)```: Specify a particular format to apply.
- ```locale (string)```: Specify the locale to use for formatting (default 'en-US').
- ```multiLine (boolean)```: Allows for multiple lines of text (default: false).
- ```border (string)```: Specify the color of the border.
- ```padding (string)```: Specify the padding inside the box.
- ```margin (string)```: Specify the margin outside the box.
- ```height (string)```: Specify the height.
- ```width (string)```: Specify the width.
- ```style (string)```: Specify a style to be applied.
- ```class (string)```: Specify a class to be applied.
- ```disableSuggestions (boolean)```: Turns text suggestions on/off (default: false).
- ```showCalendarIcon (boolean)```: Shows the calendar icon (default: true).
- ```calHeight (string)```: Specify the height of the calendar control.
- ```calWidth (string)```: Specify the width of the calendar control.
- ```calFontSize (string)```: Specify a font size for calendar control.
- ```focus (boolean)```: Sets focus on the object (default: false).
- ```blurCallBackEvent```: Specify a callback method when the text looses focus.
- ```changeCallBackEvent```: Specify a callback method when the text changes.
- ```enterCallBackEvent```: Specify a callback method when the 'ENTER' key is pressed.

## USAGE:
```html
Examples:

<div>Alpha</div>
<sdk-textbox validCharacters="alpha"></sdk-textbox>

<div>Numeric</div>
<sdk-textbox validCharacters="numeric"></sdk-textbox>

<div>AlphaNumeric</div>
<sdk-textbox validCharacters="alphanumeric"></sdk-textbox>

<div>Decimal (with commas and 5 decimal positions)</div>
<sdk-textbox validCharacters="decimal" pattern="1.0-5"></sdk-textbox>

<div>Currency (with commas and $)</div>
<sdk-textbox validCharacters="currency"></sdk-textbox>

<div>Email Address</div>
<sdk-textbox style="width: 300px;" validCharacters="email"></sdk-textbox>

<div>Calendar (without popup component)</div>
<sdk-textbox validCharacters="calendar" nocomponent></sdk-textbox>

<div>Calendar</div>
<sdk-textbox validCharacters="calendar" pattern="MM/DD/YYYY"></sdk-textbox>

<div>Latitude</div>
<sdk-textbox validCharacters="latitude"></sdk-textbox>

<div>Longitude</div>
<sdk-textbox validCharacters="longitude"></sdk-textbox>

Custom Inputs:

<div>SSN</div>
<sdk-textbox validCharacters="custom" pattern="###-##-####"></sdk-textbox>

<div>Phone # with extension</div>
<sdk-textbox validCharacters="custom" pattern="(###) ###-#### x####"></sdk-textbox>

<div>Custom ([abc123])</div>
<sdk-textbox validCharacters="custom" pattern="[abc123]"></sdk-textbox>

<div>Custom ([a-zA-Z0-9])</div>
<sdk-textbox validCharacters="custom" pattern="[a-zA-Z0-9]"></sdk-textbox>

<div>Custom ([^0-9])</div>
<sdk-textbox validCharacters="custom" pattern="[^0-9]"></sdk-textbox>
```

#### ```validCharacters="custom"```
Specific characters:
- For specific character input, you MUST wrap your pattern in brackets []. This is similar to a RegEx pattern.
    - [abc123] only allows the characters "abc123".
    - [0-9] or [\d] only allows numbers.
    - [a-zA-Z0-9] only allows alphanumeric characters.
    - [^0-9] allows any character EXCEPT numbers.

- Other RegEx patterns are handled as-is but copy/paste is disabled:
    - ^[0-9]{1,5}$

Pattern-based:
- For pattern-based input, you MUST use the # character to represent numbers (0-9).
    - Segements are created by using one of the following characters:
        - space ( )
        - dash (-)
        - underscore (_)
        - forward slash (/)
        - period (.)
    - Segment characters cannot be used consecutively.
    - Each segment must contain at least one # character.

**NOTE:** The ```sdk-textbox``` also captures and formats text that is pasted in from the clipboard.