implement iban validators for the new api

Author: ArturAssisComp

README-updated.md

@@ -149,8 +149,8 @@ TextFormField(
 
 ### Finance validators
 
-- `FormBuilderValidators.bic()`: Checks if the field contains a valid BIC (Bank Identifier Code).
-- TODO [ ] `FormBuilderValidators.iban()` - requires the field's to be a valid IBAN.
+- `Validators.bic()`: Checks if the field contains a valid BIC (Bank Identifier Code).
+- `Validators.iban()` - Checks if the field contains a valid IBAN (International Bank Account Number).
 
 ### Generic Type Validators
 Validators that check a generic type user input.

doc/migration.md

@@ -660,9 +660,16 @@ Validators.creditCard(
 );
 
 ```
-TODO continue from here!!!!
 
-- `FormBuilderValidators.iban()` - requires the field's to be a valid IBAN.
+- `FormBuilderValidators.iban()`
+```dart
+// Old API:
+// OBS.: There is a bug in the regex parameter. It is not used at all.
+FormBuilderValidators.iban(errorText: 'invalid iban');
+
+// New API:
+Validators.iban(ibanMsg: (_)=>'invalid iban');
+```
 
 ### Identity validators
 

lib/src/form_builder_validators.dart

@@ -4106,6 +4106,54 @@ final class Validators {
   }) =>
       val.creditCard(regex: regex, creditCardMsg: creditCardMsg);
 
+  ///{@template validator_iban}
+  /// A validator function that checks if a string is a valid International Bank
+  /// Account Number (IBAN).
+  ///
+  /// Returns null if the input is a valid IBAN format, otherwise returns an
+  /// error message. The validator performs standard IBAN validation including
+  /// length check, character conversion, and checksum calculation according to
+  /// the ISO 13616 standard.
+  ///
+  /// ## Parameters
+  /// - `isIban` (`bool Function(String input)?`): Optional custom validation
+  ///   function that determines if the input is a valid IBAN. If provided, this
+  ///   function overrides the default validation logic.
+  /// - `ibanMsg` (`String Function(String input)?`): Optional function that
+  ///   returns a custom error message when validation fails. If not provided,
+  ///   the default localized error message is used.
+  ///
+  /// ## Returns
+  /// A `Validator<String>` function that accepts a string input and returns
+  /// null for valid IBANs or an error message string for invalid IBANs.
+  ///
+  /// ## Examples
+  /// ```dart
+  /// // Basic usage with default validation and error message
+  /// final validator = Validators.iban();
+  /// assert(validator('GB82 WEST 1234 5698 7654 32') == null); // Valid IBAN
+  /// assert(validator('invalid123') != null); // Invalid IBAN
+  ///
+  /// // Using custom validation logic
+  /// final customValidator = FormBuilderValidators.iban(
+  ///   isIban: (input) => input.startsWith('DE'),
+  ///   ibanMsg: (input) => 'Only German IBANs are accepted',
+  /// );
+  /// assert(customValidator('DE89 3704 0044 0532 0130 00') == null); // Valid German IBAN
+  /// assert(customValidator('GB82 WEST 1234 5698 7654 32') != null); // Not a German IBAN
+  /// ```
+  ///
+  /// ## Caveats
+  /// - The validator removes all spaces from the input before validation
+  /// - The validation is case-insensitive as the input is converted to uppercase
+  /// - The minimum length check for IBANs is set to 15 characters (after removing spaces)
+  /// {@endtemplate}
+  static Validator<String> iban({
+    c.bool Function(String input)? isIban,
+    String Function(String input)? ibanMsg,
+  }) =>
+      val.iban(isIban: isIban, ibanMsg: ibanMsg);
+
   ///{@template validator_bic}
   /// Creates a validator that checks if a string is a valid BIC (Bank Identifier Code).
   ///

lib/src/validators/finance_validators.dart

@@ -31,6 +31,19 @@ Validator<String> bic({
   };
 }
 
+/// {@macro validator_iban}
+Validator<String> iban({
+  bool Function(String input)? isIban,
+  String Function(String input)? ibanMsg,
+}) {
+  return (String input) {
+    return isIban?.call(input) ?? _isIBAN(input)
+        ? null
+        : (ibanMsg?.call(input) ??
+            FormBuilderLocalizations.current.ibanErrorText);
+  };
+}
+
 //******************************************************************************
 //*                              Aux functions                                 *
 //******************************************************************************
@@ -82,3 +95,32 @@ bool _isBIC(String value) {
 
   return regex.hasMatch(bic);
 }
+
+/// Check if the string is a valid IBAN.
+bool _isIBAN(String value) {
+  final String iban = value.replaceAll(' ', '').toUpperCase();
+
+  if (iban.length < 15) {
+    return false;
+  }
+
+  final String rearranged = iban.substring(4) + iban.substring(0, 4);
+  final String numericIban = rearranged.split('').map((String char) {
+    final int charCode = char.codeUnitAt(0);
+    return charCode >= 65 && charCode <= 90 ? (charCode - 55).toString() : char;
+  }).join();
+
+  int remainder = int.parse(numericIban.substring(0, 9)) % 97;
+  for (int i = 9; i < numericIban.length; i += 7) {
+    remainder = int.parse(
+          remainder.toString() +
+              numericIban.substring(
+                i,
+                i + 7 < numericIban.length ? i + 7 : numericIban.length,
+              ),
+        ) %
+        97;
+  }
+
+  return remainder == 1;
+}

test/src/validators/finance_validators/iban_validator_test.dart

@@ -0,0 +1,105 @@
+import 'package:faker_dart/faker_dart.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:form_builder_validators/localization/l10n.dart';
+import 'package:form_builder_validators/src/validators/constants.dart';
+import 'package:form_builder_validators/src/validators/finance_validators.dart';
+
+void main() {
+  final Faker faker = Faker.instance;
+  final String customErrorMessage = faker.lorem.sentence();
+
+  group('IbanValidator -', () {
+    test('should return null if the IBAN is valid', () {
+      // Arrange
+      final Validator<String> validator = iban();
+      const String validIban = 'DE89370400440532013000';
+
+      // Act
+      final String? result = validator(validIban);
+
+      // Assert
+      expect(result, isNull);
+    });
+
+    test('should return null if the IBAN is valid with spaces', () {
+      // Arrange
+      final Validator<String> validator = iban();
+      const String validIban = 'DE89 3704 0044 0532 0130 00';
+
+      // Act
+      final String? result = validator(validIban);
+
+      // Assert
+      expect(result, isNull);
+    });
+
+    test('should return the default error message if the IBAN is invalid', () {
+      // Arrange
+      final Validator<String> validator = iban();
+      const String invalidIban = 'DE89370400440532013001';
+
+      // Act
+      final String? result = validator(invalidIban);
+
+      // Assert
+      expect(result, equals(FormBuilderLocalizations.current.ibanErrorText));
+    });
+
+    test(
+        'should return the custom error message if the IBAN Validator<String> is invalid',
+        () {
+      // Arrange
+      final Validator<String> validator =
+          iban(ibanMsg: (_) => customErrorMessage);
+      const String invalidIban = 'DE89370400440532013001';
+
+      // Act
+      final String? result = validator(invalidIban);
+
+      // Assert
+      expect(result, equals(customErrorMessage));
+    });
+
+    test(
+        'should return the default error message if the value is an empty string',
+        () {
+      // Arrange
+      final Validator<String> validator = iban();
+      const String value = '';
+
+      // Act
+      final String? result = validator(value);
+
+      // Assert
+      expect(result, equals(FormBuilderLocalizations.current.ibanErrorText));
+    });
+
+    test(
+        'should return the default error message if the IBAN length is less than 15 characters',
+        () {
+      // Arrange
+      final Validator<String> validator = iban();
+      const String shortIban = 'DE8937040044';
+
+      // Act
+      final String? result = validator(shortIban);
+
+      // Assert
+      expect(result, equals(FormBuilderLocalizations.current.ibanErrorText));
+    });
+
+    test(
+        'should return null if the IBAValidator<String> N length is exactly 15 characters and valid',
+        () {
+      // Arrange
+      final Validator<String> validator = iban();
+      const String validShortIban = 'AL47212110090000000235698741';
+
+      // Act
+      final String? result = validator(validShortIban);
+
+      // Assert
+      expect(result, isNull);
+    });
+  });
+}