ngx-mat-form-errors 0.0.3 → 0.0.4

package/README.md

@@ -1,24 +1,186 @@
-# NgxFormErrors
+# ngx-mat-form-errors
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 18.2.0.
+A lightweight Angular library that automatically displays validation errors for Angular Material forms. Stop writing repetitive error message logic!
 
-## Code scaffolding
+[![npm version](https://img.shields.io/npm/v/ngx-mat-form-errors.svg)](https://www.npmjs.com/package/ngx-mat-form-errors)
+[![npm downloads](https://img.shields.io/npm/dm/ngx-mat-form-errors.svg)](https://www.npmjs.com/package/ngx-mat-form-errors)
 
-Run `ng generate component component-name --project ngx-form-errors` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ngx-form-errors`.
-> Note: Don't forget to add `--project ngx-form-errors` or else it will be added to the default project in your `angular.json` file. 
+## Installation
 
-## Build
+```bash
+npm install ngx-mat-form-errors
+```
 
-Run `ng build ngx-form-errors` to build the project. The build artifacts will be stored in the `dist/` directory.
+## Quick Usage
 
-## Publishing
+### 1. Import the module
 
-After building your library with `ng build ngx-form-errors`, go to the dist folder `cd dist/ngx-form-errors` and run `npm publish`.
+**For standalone components:**
+```typescript
+import { NgxFormErrorsModule } from 'ngx-mat-form-errors';
 
-## Running unit tests
+@Component({
+  // ...
+  imports: [
+    // ... other imports
+    NgxFormErrorsModule,
+    ReactiveFormsModule,
+    MatFormFieldModule,
+    MatInputModule
+  ]
+})
+export class YourComponent {}
+```
 
-Run `ng test ngx-form-errors` to execute the unit tests via [Karma](https://karma-runner.github.io).
+**For NgModules:**
+```typescript
+import { NgxFormErrorsModule } from 'ngx-mat-form-errors';
+
+@NgModule({
+  imports: [
+    // ... other imports
+    NgxFormErrorsModule,
+    ReactiveFormsModule,
+    MatFormFieldModule,
+    MatInputModule
+  ]
+})
+export class AppModule {}
+```
+
+### 2. Create a form
+
+```typescript
+import { FormBuilder, FormGroup, Validators } from '@angular/forms';
+
+export class YourComponent {
+  form: FormGroup;
+
+  constructor(private fb: FormBuilder) {
+    this.form = this.fb.group({
+      email: ['', [Validators.required, Validators.email]],
+      password: ['', [Validators.required, Validators.minLength(8)]]
+    });
+  }
+}
+```
+
+### 3. Add to template
+
+```html
+<form [formGroup]="form">
+  <!-- Email field -->
+  <mat-form-field>
+    <mat-label>Email</mat-label>
+    <input matInput formControlName="email">
+  </mat-form-field>
+  <ngx-error field="email" label="Email"></ngx-error>
+
+  <!-- Password field -->
+  <mat-form-field>
+    <mat-label>Password</mat-label>
+    <input matInput type="password" formControlName="password">
+  </mat-form-field>
+  <ngx-error field="password" label="Password"></ngx-error>
+</form>
+```
+
+That's it! Errors will automatically show when fields are invalid and touched.
+
+## Examples
+
+### Basic Form
+
+```html
+<mat-form-field>
+  <mat-label>Username</mat-label>
+  <input matInput formControlName="username">
+</mat-form-field>
+<ngx-error field="username" label="Username"></ngx-error>
+```
+
+### Custom Label
+
+```html
+<ngx-error field="email" label="Email address"></ngx-error>
+<!-- Displays: "Email address is required" instead of "Email is required" -->
+```
+
+### Nested Form Groups
+
+```html
+<div formGroupName="address">
+  <mat-form-field>
+    <mat-label>Street</mat-label>
+    <input matInput formControlName="street">
+  </mat-form-field>
+  <ngx-error field="address.street" label="Street"></ngx-error>
+</div>
+```
+
+## Default Error Messages
+
+| Error | Message |
+|-------|---------|
+| required | `{label} is required` |
+| email | `Invalid email format` |
+| minlength | `{label} must be at least {requiredLength} characters` |
+| maxlength | `{label} cannot exceed {requiredLength} characters` |
+| pattern | `Invalid {label} format` |
+| default | `Invalid {label}` |
+
+## Custom Error Messages
+
+Create a custom service:
+
+```typescript
+import { Injectable } from '@angular/core';
+import { ErrorService } from 'ngx-mat-form-errors';
+
+@Injectable({ providedIn: 'root' })
+export class CustomErrorService extends ErrorService {
+  override getErrorMessage(errors: any, label: string): string {
+    if (errors['required']) return `Please enter your ${label}`;
+    if (errors['email']) return 'Enter a valid email address';
+    if (errors['minlength']) return `Minimum ${errors['minlength'].requiredLength} characters required`;
+    return super.getErrorMessage(errors, label);
+  }
+}
+```
+
+Add to providers:
+
+```typescript
+providers: [
+  { provide: ErrorService, useClass: CustomErrorService }
+]
+```
+
+## API
+
+### `<ngx-error>` Component
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `field` | string | Yes | Form control name (supports nested like "address.street") |
+| `label` | string | No | Display name (defaults to field name) |
+
+## Styling
+
+The component uses the `.ngx-error` class:
+
+```css
+.ngx-error {
+  color: #f44336;
+  font-size: 12px;
+  margin-top: 4px;
+}
+```
+
+## Requirements
+
+- Angular 14+
+- @angular/forms
+- @angular/material (optional)
 
-## Further help
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-mat-form-errors",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": false,
   "peerDependencies": {
     "@angular/common": "^18.2.0",