@fagon/ngx-intellitoolx 16.0.1

package/README.md

@@ -0,0 +1,959 @@
+# IntelliToolxHelper
+
+Utility helpers for working with Angular Reactive Forms, deep comparisons, change detection, and common data transformations.
+Designed to simplify form state management, prevent accidental navigation, and normalize user input.
+
+### Installation
+
+npm install intellitoolx-helper
+
+## Import
+
+import { IntelliToolxHelper } from 'intellitoolx-helper';
+
+Methods
+
+## captureInitialValue(form)
+
+Captures and clones the initial value of a form and marks it as pristine.
+
+static captureInitialValue(form: AbstractControl): any
+
+Features
+Uses getRawValue() when available
+Marks form as pristine
+Returns a deep clone of the initial value
+
+Example
+const initial = IntelliToolxHelper.captureInitialValue(this.form);
+
+## trimFormGroup(control)
+
+Recursively trims whitespace from all string values in a form.
+
+static trimFormGroup(control: AbstractControl): void
+
+Supports
+FormGroup
+FormArray
+FormControl
+
+Example
+IntelliToolxHelper.trimFormGroup(this.form);
+
+## deepEqual(obj1, obj2)
+
+Performs a deep comparison between two values.
+
+static deepEqual(obj1: any, obj2: any): boolean
+
+Special behavior
+Treats null, undefined, and "" as equal
+Normalizes numeric comparisons
+Compares File objects by metadata
+Supports nested objects & arrays
+
+Example
+IntelliToolxHelper.deepEqual(a, b);
+
+## isEmpty(value)
+
+Checks if a value is empty.
+
+static isEmpty(value: any): boolean
+
+Returns true for:
+null
+undefined
+empty string
+whitespace-only string
+
+## clone(value)
+
+Creates a deep clone.
+
+static clone(value: any): any
+
+Uses structuredClone (Angular 14+ compatible).
+
+## formHasChanges(initialValue, form)
+
+Determines whether a form value has changed.
+
+static formHasChanges(initialValue: any, form: AbstractControl): boolean
+
+Example
+if (IntelliToolxHelper.formHasChanges(initial, this.form)) {
+// prompt user
+}
+
+## confirmIfChanged(hasChanges, confirmHandler?)
+
+Shows confirmation if changes exist.
+
+static confirmIfChanged(
+hasChanges: boolean,
+confirmHandler?: ConfirmHandler
+): Promise<boolean>
+
+Behavior
+Returns true if no changes
+Uses provided handler if available
+Falls back to browser confirm()
+
+Example
+const canLeave = await IntelliToolxHelper.confirmIfChanged(
+hasChanges,
+() => dialog.confirm()
+);
+
+## registerBeforeUnload(shouldBlock, message?)
+
+Prevents accidental page exit when changes exist.
+
+static registerBeforeUnload(
+shouldBlock: () => boolean,
+message?: string
+): () => void
+
+Returns
+Cleanup function to remove the listener.
+
+Example
+const cleanup = IntelliToolxHelper.registerBeforeUnload(() =>
+this.form.dirty
+);
+
+// later
+cleanup();
+
+## getFormControl(form, path)
+
+Retrieves a nested FormControl using dot notation.
+
+static getFormControl<T>(
+form: AbstractControl,
+path: string
+): FormControl<T> | null
+
+Supports
+Nested FormGroups
+FormArrays using numeric indexes
+
+Example
+const control = IntelliToolxHelper.getFormControl(this.form, 'address.street');
+const item = IntelliToolxHelper.getFormControl(this.form, 'items.0.name');
+
+## convertImageToBase64(file)
+
+Converts an image file to a Base64 string.
+
+static convertImageToBase64(file: File): Promise<string>
+
+Example
+const base64 = await IntelliToolxHelper.convertImageToBase64(file);
+
+## replaceCharacter(text, replaceChar, replaceWithChar)
+
+Replaces all occurrences of a character in a string.
+
+static replaceCharacter(
+text: any,
+replaceChar: string,
+replaceWithChar: string
+): string
+
+Example
+IntelliToolxHelper.replaceCharacter('1-2-3', '-', ':');
+// 1:2:3
+
+## convertJsonStringToJson(value)
+
+Safely converts a JSON string into an object.
+
+static convertJsonStringToJson<T>(
+value: T | string | null | undefined
+): T | null
+
+Behavior
+Returns parsed object if valid JSON string
+Returns original object if already parsed
+Returns null if parsing fails
+
+Example
+const data = IntelliToolxHelper.convertJsonStringToJson<MyType>(jsonString);
+
+### Usage Pattern (Recommended)
+
+initialValue = IntelliToolxHelper.captureInitialValue(this.form);
+
+save() {
+IntelliToolxHelper.trimFormGroup(this.form);
+
+if (!IntelliToolxHelper.formHasChanges(this.initialValue, this.form)) {
+return;
+}
+
+// proceed with save
+}
+
+# IntellitoolxRegExps
+
+A collection of commonly used regular expressions for validation in Angular and TypeScript applications.
+
+Designed for:
+Reactive Forms validation
+Input sanitization
+Reusable validation patterns
+Consistent form behavior across projects
+
+Import
+import { IntellitoolxRegExps } from 'intellitoolx-helper';
+
+Available Regular Expressions
+
+## EMAIL_REGEX
+
+EMAIL*REGEX: /^(?=.{1,50}$)[a-zA-Z0-9.*%+-]+@[a-zA-Z0-9.-]+\.[A-Za-z]{2,}$/
+
+Validates an email address with:
+Maximum length of 50 characters
+Standard email format
+Requires valid domain suffix (min 2 characters)
+
+Valid Examples
+test@example.com
+user.name@mail-domain.org
+info123@test.co
+
+Invalid Examples
+invalid-email
+user@
+@test.com
+
+Usage (Angular Validator)
+
+this.form = new FormGroup({
+email: new FormControl('', [
+Validators.pattern(IntellitoolxRegExps.EMAIL_REGEX),
+]),
+});
+
+## NUMBER_REGEX
+
+NUMBER_REGEX: /^\d+$/
+
+Validates:
+Whole numbers only
+No decimals
+No negative values
+No spaces or characters
+
+Valid Examples
+1, 25, 99999
+
+Invalid Examples
+1.5, -10, abc
+
+## AMOUNT_REGEX
+
+AMOUNT_REGEX: /^\d+(\.\d{1,2})?$/
+
+Validates monetary amounts:
+Whole numbers
+Optional decimal
+Maximum 2 decimal places
+
+Valid Examples
+10, 10.5, 10.50, 9999.99
+
+Invalid Examples
+10., 10.999, abc
+
+## DOMAIN_REGEX
+
+DOMAIN_REGEX:
+/^(?=.{1,255}$)(https?|ftp):\/\/([\w.-]+)\.([a-z\.]{2,6})(:[0-9]{1,5})?(\/\S*)?$/
+
+Validates full URLs with:
+http, https, or ftp protocol
+
+Valid domain
+Optional port
+Optional path
+Maximum length of 255 characters
+
+Valid Examples
+https://example.com, http://sub.domain.org, https://example.com:8080/path, ftp://files.server.net
+
+Invalid Examples
+example.com, http:/example.com, htp://domain.com
+
+### Usage in Angular Reactive Forms
+
+this.form = new FormGroup({
+email: new FormControl('', [
+Validators.pattern(IntellitoolxRegExps.EMAIL_REGEX),
+]),
+amount: new FormControl('', [
+Validators.pattern(IntellitoolxRegExps.AMOUNT_REGEX),
+]),
+website: new FormControl('', [
+Validators.pattern(IntellitoolxRegExps.DOMAIN_REGEX),
+]),
+});
+
+# IntellitoolxFormUpdateMessage
+
+A lightweight Angular standalone component that displays a configurable warning message when a form has no changes to save.
+
+Designed to improve user experience by clearly informing users why an action (such as saving) cannot proceed.
+
+## Import
+
+import { IntellitoolxFormUpdateMessage } from 'intellitoolx-helper';
+Because it is standalone, import it directly:
+
+@Component({
+standalone: true,
+imports: [IntellitoolxFormUpdateMessage],
+})
+
+## Basic Usage
+
+<itx-form-update-message></itx-form-update-message>
+
+### Default message:
+
+There are no changes to save. Please modify a field to continue.
+With Configuration
+
+Customize text and styling using itxFormUpdateMessageConfig.
+
+<itx-form-update-message
+[itxFormUpdateMessageConfig]="updateMessageConfig"
+
+> </itx-form-update-message>
+> updateMessageConfig = {
+>   message: 'Nothing changed yet.',
+>   textColor: '#0c5460',
+>   backgroundColor: '#d1ecf1',
+>   borderColor: '#bee5eb',
+> };
+
+## Configuration Interface
+
+export interface IntellitoolxFormUpdateMessageConfig {
+message?: string;
+textColor?: string;
+backgroundColor?: string;
+borderColor?: string;
+padding?: string;
+iconAndMessageGap?: string;
+borderRadius?: string;
+fontWeight?: number | string;
+iconSize?: string;
+}
+
+All properties are optional.
+
+## Default Styling Behavior
+
+If no configuration is provided, the component uses accessible warning styles.
+
+Property Default
+text color #963C00
+background #fff3cd
+border #f3cd5a
+padding 1rem
+border radius 0.5rem
+gap 0.5rem
+font weight 400
+icon size 1rem
+Accessibility
+
+Uses role="alert" to notify assistive technologies
+Icon is hidden from screen readers with aria-hidden="true"
+Provides clear visual contrast for warning context
+
+Example: Show When No Changes Exist
+<itx-form-update-message
+\*ngIf="!formHasChanges"
+
+> </itx-form-update-message>
+> formHasChanges = false;
+> Example: Integrating With IntelliToolxHelper
+> hasChanges = IntelliToolxHelper.formHasChanges(this.initialValue, this.form);
+> <itx-form-update-message
+>   *ngIf="!hasChanges"
+> </itx-form-update-message>
+
+## Theming Examples
+
+Success Style
+updateMessageConfig = {
+message: 'No updates were made.',
+textColor: '#155724',
+backgroundColor: '#d4edda',
+borderColor: '#c3e6cb',
+};
+
+Minimal Style
+updateMessageConfig = {
+backgroundColor: 'transparent',
+borderColor: '#ddd',
+textColor: '#555',
+};
+
+## When to Use
+
+Use this component when:
+A save/update action is triggered without changes
+Preventing redundant submissions
+Improving form UX clarity
+Displaying inline form state feedback
+
+# IntellitoolxFormErrors
+
+A lightweight Angular standalone component for displaying reactive form validation errors with customizable and extensible error messages.
+
+Built to:
+standardize validation messages
+support component-level overrides
+allow global extension of error messages
+simplify template error handling
+
+Import
+import { IntellitoolxFormErrors } from 'intellitoolx-helper';
+
+You can import it directly into any component.
+
+## Basic Usage
+
+<input [formControl]="emailControl" />
+<itx-form-errors [control]="emailControl"></itx-form-errors>
+
+Errors will display automatically when:
+control is touched
+control is invalid
+
+Default Supported Errors
+The component includes built-in messages for common validators:
+
+Error Key Message
+required This field is required
+email The email entered is invalid
+minlength You must enter at least X characters
+maxlength You must not enter more than X characters
+pattern Your entry must match the required pattern
+passwordMismatch Password and confirm password do not match
+futureDate Future date is not allowed
+duplicateEmail Each email must be unique
+maxWords Exceeded maximum number of words
+maxMonthYear Date is later than allowed
+minMonthYear Date is earlier than allowed
+exceededAllowedDateDifference Date difference can only be one month
+exceededLeastDateAllowed Start date cannot be greater than end date
+
+## Adding Control Labels (User-Friendly Messages)
+
+<itx-form-errors
+[control]="amountControl"
+controlLabel="Amount"
+
+> </itx-form-errors>
+
+Example output:
+Amount cannot be greater than 100
+
+Component-Level Custom Messages
+Override messages for a specific field.
+
+componentValidation = {
+required: { message: 'Email is mandatory' },
+minlength: { message: 'Too short' },
+};
+
+<itx-form-errors
+[control]="emailControl"
+[componentValidation]="componentValidation"
+
+> </itx-form-errors>
+
+### Using Custom Validators with Messages
+
+If your validator returns an object:
+return { customMinValue: { message: 'Value is too small' } };
+
+The component will display:
+Value is too small
+
+## Extending Error Messages (Recommended)
+
+Consumers can extend the component to add global or shared messages.
+
+### Option 1 — Extend the Component
+
+Create your own reusable error component:
+
+import { Component } from '@angular/core';
+import { IntellitoolxFormErrors } from 'intellitoolx-helper';
+
+@Component({
+selector: 'app-form-errors',
+standalone: true,
+imports: [IntellitoolxFormErrors],
+template: `     <itx-form-errors
+      [control]="control"
+      [componentValidation]="componentValidation"
+      [controlLabel]="controlLabel"
+    />
+  `,
+})
+export class AppFormErrors extends IntellitoolxFormErrors {
+override errorMessages = {
+...this.errorMessages,
+required: 'This field cannot be empty',
+phone: 'Phone number is invalid',
+usernameTaken: 'This username is already taken',
+};
+}
+
+Now use:
+<app-form-errors [control]="control"></app-form-errors>
+
+### Option 2 — Extend via Custom Validator Keys
+
+Return new error keys from validators:
+
+return { usernameTaken: true };
+
+Then provide the message:
+
+componentValidation = {
+usernameTaken: { message: 'Username already exists' },
+};
+
+### Option 3 — Global Shared Messages Service (Advanced)
+
+Create a shared constant:
+
+export const APP_ERROR_MESSAGES = {
+required: 'Required field',
+email: 'Invalid email address',
+};
+
+Then extend:
+override errorMessages = {
+...APP_ERROR_MESSAGES,
+};
+
+## Supported Error Value Types
+
+The component intelligently handles different validator outputs:
+
+Boolean
+{ required: true }
+→ uses default or custom message
+
+String
+{ customError: 'Invalid value provided' }
+→ displays string directly
+
+Object
+{ minlength: { requiredLength: 5 } }
+→ dynamic message rendering
+
+Built-in Smart Messages
+Pattern Errors
+
+## Displays:
+
+Please provide a valid {controlLabel}
+Min / Max Validators
+Age cannot be less than 18
+Price cannot be greater than 100
+Ngb Date Errors
+Invalid date format provided
+
+### Best Practices
+
+✔ Always provide controlLabel for better UX
+✔ Use componentValidation for field-specific overrides
+✔ Extend the component for app-wide consistency
+✔ Return structured error objects from custom validators
+✔ Keep error keys consistent across the application
+
+Example (Full Integration)
+<input formControlName="email" />
+
+<app-form-errors
+[control]="form.controls.email"
+controlLabel="Email Address"
+
+> </app-form-errors>
+
+# RequiredMarkerDirective
+
+An Angular standalone directive that automatically adds a visual required marker to form labels when the associated form control has a required validator.
+This ensures consistent UX and eliminates manual asterisk management.
+
+## Import
+
+import { RequiredMarkerDirective } from 'intellitoolx-helper';
+
+Because it is standalone, import it directly:
+
+@Component({
+standalone: true,
+imports: [RequiredMarkerDirective],
+})
+
+## Basic Usage
+
+Add the directive to a <label> element.
+
+<label for="email" itxRequired>Email</label>
+<input id="email" formControlName="email" />
+
+If the control has Validators.required, the output becomes:
+Email \*
+
+## How It Works
+
+Reads the label’s for attribute.
+Finds the matching control inside the parent FormGroup.
+Checks for Validators.required.
+Adds or removes the required marker dynamically.
+Updates when value or status changes.
+
+## Dynamic Updates
+
+If required validation is added or removed at runtime:
+control.setValidators([Validators.required]);
+control.updateValueAndValidity();
+The label updates automatically.
+
+## Default Marker Behavior
+
+Property Default
+marker sign \*
+color red
+spacing 0.25rem
+position after label text
+Global Configuration
+
+## You can configure marker appearance globally using the provided injection token.
+
+Step 1 — Provide Configuration
+import { REQUIRED_MARKER_GLOBAL_CONFIG } from 'intellitoolx-helper';
+
+providers: [
+{
+provide: REQUIRED_MARKER_GLOBAL_CONFIG,
+useValue: {
+sign: '*',
+color: '#d9534f',
+spacing: '4px',
+position: 'after', // 'before' | 'after'
+},
+},
+];
+
+Configuration Options
+export interface ResolvedRequiredMarkerConfig {
+sign: string;
+color: string;
+spacing: string;
+position: 'before' | 'after';
+}
+
+Positioning the Marker
+After (default)
+Email \*
+Before
+position: 'before'
+
+- Email
+
+Preserves Additional Label Text
+The directive preserves text in parentheses or suffix content.
+<label for="dob" itxRequired>Date of Birth (optional)</label>
+
+Output when required:
+Date of Birth \* (optional)
+Works With Nested Form Groups
+Ensure the for attribute matches the control name.
+<label for="address.street" itxRequired>Street</label>
+<input formControlName="street" />
+
+## Requirements
+
+Must be used inside a form with FormGroupDirective
+Label for attribute must match control name
+
+## Common Mistakes
+
+Missing for attribute
+Label not associated with control
+Control name mismatch
+
+Example (Complete)
+
+<form [formGroup]="form">
+  <label for="email" itxRequired>Email</label>
+  <input id="email" formControlName="email" />
+</form>
+email: new FormControl('', Validators.required);
+
+# JsonParsePipe
+
+An Angular standalone pipe that safely parses JSON strings into JavaScript objects.
+
+Built on top of IntelliToolxHelper.convertJsonStringToJson, this pipe prevents template errors when dealing with dynamic or stringified JSON data.
+
+## Import
+
+import { JsonParsePipe } from 'intellitoolx-helper';
+
+Because it is standalone, import it directly:
+
+@Component({
+standalone: true,
+imports: [JsonParsePipe],
+})
+
+## Usage
+
+Basic Example
+{{ jsonString | jsonParse | json }}
+
+Input
+jsonString = '{"name":"John","age":30}';
+
+Output
+{
+"name": "John",
+"age": 30
+}
+
+## When to Use
+
+Use jsonParse when:
+API responses contain stringified JSON
+Form values store serialized objects
+LocalStorage data needs parsing
+Preventing template crashes from invalid JSON
+
+## Behavior
+
+The pipe safely handles multiple input types:
+
+Input Result
+Valid JSON string Parsed object
+Invalid JSON string null
+Object Returned unchanged
+null / undefined null
+
+Examples
+Parse API Data
+
+<div *ngIf="user.data | jsonParse as parsed">
+  {{ parsed.name }}
+</div>
+
+Parse Stored JSON
+{{ localStorageValue | jsonParse | json }}
+
+Safe Access with Optional Chaining
+{{ (settings | jsonParse)?.theme }}
+
+Equivalent TypeScript Logic
+
+The pipe internally performs:
+IntelliToolxHelper.convertJsonStringToJson(value);
+
+Error Safety
+Unlike JSON.parse() directly in templates, this pipe:
+prevents runtime template errors
+avoids breaking change detection
+returns null on parsing failure
+
+For large datasets or repeated bindings:
+Prefer parsing in the component
+parsedData = IntelliToolxHelper.convertJsonStringToJson(data);
+
+# IntelliToolx Validators
+
+A set of reusable Angular Reactive Form validators designed for common business rules such as amount limits, password matching, word limits, and duplicate detection.
+
+These validators integrate seamlessly with Angular forms and work perfectly with IntellitoolxFormErrors for displaying user-friendly messages.
+
+Import
+import {
+customMaxAmountValidator,
+customMinAmountValidator,
+MaxWordsValidator,
+PasswordMismatchValidator,
+uniqueEmailsValidator
+} from 'intellitoolx-helper';
+
+## Validators Overview
+
+Validator Purpose
+customMaxAmountValidator Enforces maximum numeric value
+customMinAmountValidator Enforces minimum numeric value
+MaxWordsValidator Limits number of words
+PasswordMismatchValidator Ensures password fields match
+uniqueEmailsValidator Prevents duplicate emails in FormArray
+
+## customMaxAmountValidator(maxValue)
+
+Ensures a numeric value does not exceed a specified maximum.
+customMaxAmountValidator(maxValue: number): ValidatorFn
+
+Example
+amount = new FormControl('', [
+customMaxAmountValidator(1000)
+]);
+
+Error Output
+{
+customMaxValue: {
+requiredMin: 1000,
+actual: 1200,
+message: "The value must not exceed 1000.00"
+}
+}
+
+Notes
+Accepts numeric values only
+Returns a formatted error message
+Works with IntellitoolxFormErrors automatically
+
+## customMinAmountValidator(minValue)
+
+Ensures a numeric value is at least the specified minimum.
+customMinAmountValidator(minValue: number): ValidatorFn
+
+Example
+amount = new FormControl('', [
+customMinAmountValidator(10)
+]);
+Error Output
+{
+customMinValue: {
+requiredMin: 10,
+actual: 5,
+message: "The value must be at least 10.00"
+}
+}
+
+## MaxWordsValidator(maxWords)
+
+Limits the number of words in a text input.
+MaxWordsValidator(maxWords: number): ValidatorFn
+
+Example
+description = new FormControl('', [
+MaxWordsValidator(20)
+]);
+
+### Behavior
+
+Ignores extra whitespace
+Counts words separated by spaces
+
+Error Output
+{
+maxWords: {
+actual: 25,
+max: 20
+}
+}
+
+## PasswordMismatchValidator(controlName, matchingControlName)
+
+Validates that two form fields match (commonly used for password confirmation).
+PasswordMismatchValidator(
+controlName: string,
+matchingControlName: string
+)
+
+Example
+this.form = new FormGroup(
+{
+password: new FormControl(''),
+confirmPassword: new FormControl('')
+},
+{
+validators: PasswordMismatchValidator('password', 'confirmPassword')
+}
+);
+
+Error Output
+{ passwordMismatch: true }
+
+Notes
+Error is applied to the matching control
+Ideal for password confirmation fields
+
+## uniqueEmailsValidator()
+
+Ensures all email addresses inside a FormArray are unique.
+uniqueEmailsValidator(): ValidatorFn
+
+Example
+this.form = new FormGroup({
+contacts: new FormArray([
+new FormGroup({
+email: new FormControl('')
+})
+])
+});
+
+this.contacts.setValidators(uniqueEmailsValidator());
+
+### Behavior
+
+Ignores case and whitespace
+Flags duplicates automatically
+Updates errors dynamically
+
+Error Output (control level)
+{ duplicateEmail: true }
+Error Output (form array level)
+{ duplicateEmails: true }
+
+### Integration with IntellitoolxFormErrors
+
+These validators return error keys compatible with the error component:
+Validator Error Key
+customMaxAmountValidator customMaxValue
+customMinAmountValidator customMinValue
+MaxWordsValidator maxWords
+PasswordMismatchValidator passwordMismatch
+uniqueEmailsValidator duplicateEmail
+
+### Best Practices
+
+✔ Use with Reactive Forms only
+✔ Combine with required validators when necessary
+✔ Provide control labels for better error messages
+✔ Normalize numeric inputs before validation
+✔ Use FormArray validators for dynamic lists
+
+### Complete Example
+
+this.form = new FormGroup({
+amount: new FormControl('', [
+customMinAmountValidator(10),
+customMaxAmountValidator(1000),
+]),
+description: new FormControl('', [
+MaxWordsValidator(20)
+]),
+});
+
+License
+MIT