ngx-smart-errors 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-04-03
+
+### Added
+
+- **NgxErrorComponent** — standalone component for rendering validation errors with signal-based reactivity.
+- **NgxErrorDirective** — attribute directive that auto-appends error UI next to form controls.
+- **ErrorMessageService** — centralized service for resolving, interpolating, and localizing error messages.
+- **provideSmartErrors()** — environment provider function for global configuration.
+- **useError()** — signal-based hook for programmatic error access in component classes.
+- **i18n support** — multi-language error message maps with runtime language switching.
+- **Custom templates** — `ng-template` support for fully custom error rendering.
+- **Smart triggers** — `touched`, `dirty`, and `submit` trigger strategies.
+- **Interpolation engine** — automatic replacement of `{requiredLength}`, `{min}`, `{max}`, etc.
+- **CLI setup wizard** — `npx ngx-smart-errors` interactive configuration generator.
+- **Debug mode** — optional console logging for development troubleshooting.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Burcin Eren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# ngx-smart-errors ✨
+
+**Production-ready Angular form error handling system.**  
+Stop writing repetitive boilerplates for error validation and start using smart, reactive messages.
+
+---
+
+## 🎯 The Problem
+
+Normally, to show errors in Angular, you write this for *every* input:
+
+```html
+<!-- BEFORE: ❌ Repetitive, messy, and hard to maintain -->
+@if (email.invalid && (email.touched || email.dirty)) {
+  <div class="error">
+    @if (email.errors?.['required']) {
+      <span>Email is required</span>
+    }
+    @if (email.errors?.['email']) {
+      <span>Invalid email format</span>
+    }
+  </div>
+}
+```
+
+## 🚀 The Solution
+
+With `ngx-smart-errors`, it's zero-boilerplate:
+
+```html
+<!-- AFTER: ✅ Clean, dynamic, and configurable -->
+<input [formControl]="email" ngxError />
+
+<!-- OR using the component -->
+<ngx-error [control]="email" />
+```
+
+---
+
+## ⚙️ Features
+
+- **Signals-based Reactivity**: Fully reactive with Angular 17+ Signals.
+- **Zero Configuration**: Sensible defaults for all built-in validators.
+- **Smart Triggers**: Show errors on `touched`, `dirty`, or `submit`.
+- **Global & Local Config**: Override messages globally or locally.
+- **Structural Directive**: Append error UI automatically with a simple `ngxError` attribute.
+- **i18n Ready**: Native support for multi-language message maps.
+- **Interpolation**: Automatically Replace `{requiredLength}`, `{min}`, etc. from validator results.
+- **Custom Templates**: Complete control over Error UI via `ng-template`.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install ngx-smart-errors
+```
+
+---
+
+## 🛠️ Global Configuration
+
+Provide global error messages in your `app.config.ts`:
+
+```ts
+import { provideSmartErrors } from 'ngx-smart-errors';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideSmartErrors({
+      errorMessages: {
+        required: 'This field is required',
+        email: 'Please enter a valid email address',
+        minlength: 'Minimum length is {requiredLength} characters',
+      },
+      defaultTrigger: 'touched', // or 'dirty', 'submit'
+      defaultLanguage: 'en',
+    })
+  ]
+};
+```
+
+---
+
+## 📖 Usage Examples
+
+### 1. Simple Directive Usage
+
+Automatically appends the error component under the input.
+
+```html
+<input formControlName="username" ngxError />
+```
+
+### 2. Manual Component Usage
+
+```html
+<ngx-error [control]="form.controls.password" trigger="dirty" />
+```
+
+### 3. Custom Local Messages
+
+```html
+<ngx-error 
+  [control]="email" 
+  [messages]="{ 
+    required: 'We really need your email', 
+    email: 'That does not look like an email' 
+  }" 
+/>
+```
+
+### 4. UI Customization with Templates
+
+```html
+<ngx-error [control]="email">
+  <ng-template let-error>
+    <div class="alert alert-danger">
+      <i class="icon-warning"></i> {{ error }}
+    </div>
+  </ng-template>
+</ngx-error>
+```
+
+### 5. Using Signals (Modern Reactive API)
+
+```ts
+import { useError } from 'ngx-smart-errors';
+
+@Component({ ... })
+export class MyComponent {
+  email = new FormControl('', [Validators.required]);
+  // reactive signal that updates automatically
+  emailError = useError(this.email); 
+}
+```
+
+---
+
+## 🌍 i18n support
+
+```ts
+provideSmartErrors({
+  errorMessages: {
+    required: {
+      en: 'Required',
+      tr: 'Zorunlu alan'
+    }
+  },
+  defaultLanguage: 'en'
+});
+```
+
+---
+
+## 🧪 Roadmap
+
+- [ ] Support for Material Design (Auto-integration)
+- [ ] Auto-discovery of `FormGroup` submission state
+- [ ] Custom validation hint animations
+- [ ] Support for Async Validators
+
+---
+
+## 🎁 License
+
+MIT

package/cli/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const blue = (text) => `\x1b[34m${text}\x1b[0m`;
+const green = (text) => `\x1b[32m${text}\x1b[0m`;
+const yellow = (text) => `\x1b[33m${text}\x1b[0m`;
+
+console.log(`\n✨  ${blue('ngx-smart-errors')} ${green('CLI Setup Wizard')}\n`);
+
+async function run() {
+  const language = await ask('🌍  Preferred language (en/tr)? ', 'en');
+  const trigger = await ask('🎯  Default trigger (touched/dirty/submit)? ', 'touched');
+  const theme = await ask('🎨  UI theme (default/tailwind)? ', 'default');
+
+  console.log(`\n🚀 Generating configuration...`);
+
+  const config = `
+import { provideSmartErrors } from 'ngx-smart-errors';
+
+export const smartErrorsConfig = provideSmartErrors({
+  defaultLanguage: '${language}',
+  defaultTrigger: '${trigger}',
+  errorMessages: {
+    required: '${language === 'tr' ? 'Bu alan zorunludur' : 'This field is required'}',
+    email: '${language === 'tr' ? 'Geçersiz e-posta' : 'Invalid email address'}'
+  }
+});
+`;
+
+  const targetPath = path.join(process.cwd(), 'src', 'app', 'smart-errors.config.ts');
+  
+  try {
+    if (!fs.existsSync(path.dirname(targetPath))) {
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    }
+    fs.writeFileSync(targetPath, config);
+    console.log(`\n✅ ${green('Success!')} Configuration generated at ${yellow('src/app/smart-errors.config.ts')}`);
+    console.log(`\nNext steps:`);
+    console.log(`1. Add 'smartErrorsConfig' to your app.config.ts providers.`);
+    console.log(`2. Import NgxErrorDirective/Component in your components.`);
+  } catch (err) {
+    console.error(`\n❌ Error writing file: ${err.message}`);
+  }
+
+  rl.close();
+}
+
+function ask(question, defaultValue) {
+  return new Promise((resolve) => {
+    rl.question(`${question} ${blue(`(${defaultValue})`)}: `, (answer) => {
+      resolve(answer || defaultValue);
+    });
+  });
+}
+
+run();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "ngx-smart-errors",
+  "version": "1.0.0",
+  "description": "Modern, signal-based Angular form validation error handling. Zero boilerplate, global/local config, i18n, custom templates.",
+  "keywords": [
+    "angular",
+    "forms",
+    "validation",
+    "errors",
+    "reactive-forms",
+    "signals",
+    "i18n",
+    "form-validation",
+    "ngx",
+    "angular-library"
+  ],
+  "author": "Burcin Eren",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/burcineren/ngx-smart-errors.git"
+  },
+  "homepage": "https://github.com/burcineren/ngx-smart-errors#readme",
+  "bugs": {
+    "url": "https://github.com/burcineren/ngx-smart-errors/issues"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=17.0.0",
+    "@angular/core": ">=17.0.0",
+    "@angular/forms": ">=17.0.0",
+    "rxjs": ">=7.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "bin": {
+    "ngx-smart-errors": "cli/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}