Docs

Author: martijn00

lib/src/form_field_validator_extensions.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import '../form_builder_validators.dart';
 
+/// Extension methods for [FormFieldValidator].
 extension FormFieldValidatorExtensions<T> on FormFieldValidator<T> {
   /// Combines the current validator with another validator using logical AND.
   FormFieldValidator<T> and(FormFieldValidator<T> other) {

lib/src/string/alphabetical_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template alphabetical_validator_template}
+/// [AlphabeticalValidator] extends [BaseValidator] to validate if a string contains only alphabetical characters.
+///
+/// This validator checks if the value matches the specified regex pattern that allows only letters (both uppercase and lowercase).
+///
+/// ## Parameters:
+///
+/// - [regex] The regular expression used to validate the alphabetical format. Defaults to a regex that matches only alphabetical characters.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class AlphabeticalValidator extends BaseValidator<String> {
+  /// Constructor for the alphabetical validator.
   AlphabeticalValidator({
     /// {@macro alphabetical_template}
     RegExp? regex,
@@ -13,6 +26,7 @@ class AlphabeticalValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   }) : regex = regex ?? _alphabetical;
 
+  /// The regular expression used to validate the alphabetical format.
   final RegExp regex;
 
   /// {@template alphabetical_template}

lib/src/string/contains_validator.dart

@@ -1,7 +1,21 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template contains_validator_template}
+/// [ContainsValidator] extends [BaseValidator] to validate if a string contains a specified substring.
+///
+/// This validator checks if the value contains the specified substring, with an option for case sensitivity.
+///
+/// ## Parameters:
+///
+/// - [substring] The substring that the value must contain.
+/// - [caseSensitive] Whether the search should be case-sensitive. Defaults to true.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class ContainsValidator extends BaseValidator<String> {
+  /// Constructor for the contains validator.
   const ContainsValidator(
     this.substring, {
     this.caseSensitive = true,
@@ -13,8 +27,10 @@ class ContainsValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The substring that the value must contain.
   final String substring;
 
+  /// Whether the search should be case-sensitive.
   final bool caseSensitive;
 
   @override

lib/src/string/ends_with_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template ends_with_validator_template}
+/// [EndsWithValidator] extends [BaseValidator] to validate if a string ends with a specified suffix.
+///
+/// This validator checks if the value ends with the specified suffix.
+///
+/// ## Parameters:
+///
+/// - [suffix] The suffix that the value must end with.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class EndsWithValidator extends BaseValidator<String> {
+  /// Constructor for the ends with validator.
   const EndsWithValidator(
     this.suffix, {
     /// {@macro base_validator_error_text}
@@ -11,6 +24,7 @@ class EndsWithValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The suffix that the value must end with.
   final String suffix;
 
   @override

lib/src/string/lowercase_validator.dart

@@ -1,7 +1,19 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template lowercase_validator_template}
+/// [LowercaseValidator] extends [BaseValidator] to validate if a string is entirely lowercase.
+///
+/// This validator checks if the value is the same as its lowercase version.
+///
+/// ## Parameters:
+///
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class LowercaseValidator extends BaseValidator<String> {
+  /// Constructor for the lowercase validator.
   const LowercaseValidator({
     /// {@macro base_validator_error_text}
     super.errorText,

lib/src/string/match_not_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template match_not_validator_template}
+/// [MatchNotValidator] extends [BaseValidator] to validate if a string does not match a specified regular expression pattern.
+///
+/// This validator checks if the value does not match the provided regex pattern.
+///
+/// ## Parameters:
+///
+/// - [regex] The regular expression pattern that the value must not match.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MatchNotValidator extends BaseValidator<String> {
+  /// Constructor for the match not validator.
   const MatchNotValidator(
     this.regex, {
     /// {@macro base_validator_error_text}
@@ -11,6 +24,7 @@ class MatchNotValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The regular expression pattern that the value must not match.
   final RegExp regex;
 
   @override

lib/src/string/match_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template match_validator_template}
+/// [MatchValidator] extends [BaseValidator] to validate if a string matches a specified regular expression pattern.
+///
+/// This validator checks if the value matches the provided regex pattern.
+///
+/// ## Parameters:
+///
+/// - [regex] The regular expression pattern that the value must match.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MatchValidator extends BaseValidator<String> {
+  /// Constructor for the match validator.
   const MatchValidator(
     this.regex, {
     /// {@macro base_validator_error_text}
@@ -11,6 +24,7 @@ class MatchValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The regular expression pattern that the value must match.
   final RegExp regex;
 
   @override

lib/src/string/max_words_count_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template max_words_count_validator_template}
+/// [MaxWordsCountValidator] extends [BaseValidator] to validate if a string contains no more than a specified number of words.
+///
+/// This validator checks if the number of words in the value does not exceed the specified maximum word count.
+///
+/// ## Parameters:
+///
+/// - [maxWordsCount] The maximum allowable number of words.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MaxWordsCountValidator extends BaseValidator<String> {
+  /// Constructor for the maximum words count validator.
   const MaxWordsCountValidator(
     this.maxWordsCount, {
     /// {@macro base_validator_error_text}
@@ -11,6 +24,7 @@ class MaxWordsCountValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The maximum allowable number of words.
   final int maxWordsCount;
 
   @override
@@ -19,7 +33,7 @@ class MaxWordsCountValidator extends BaseValidator<String> {
 
   @override
   String? validateValue(String valueCandidate) {
-    final int wordsCount = valueCandidate.trim().split(' ').length;
+    final int wordsCount = valueCandidate.trim().split(RegExp(r'\s+')).length;
 
     return wordsCount > maxWordsCount ? errorText : null;
   }

lib/src/string/min_words_count_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template min_words_count_validator_template}
+/// [MinWordsCountValidator] extends [BaseValidator] to validate if a string contains at least a specified number of words.
+///
+/// This validator checks if the number of words in the value is at least the specified minimum word count.
+///
+/// ## Parameters:
+///
+/// - [minWordsCount] The minimum required number of words.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MinWordsCountValidator extends BaseValidator<String> {
+  /// Constructor for the minimum words count validator.
   const MinWordsCountValidator(
     this.minWordsCount, {
     /// {@macro base_validator_error_text}
@@ -11,6 +24,7 @@ class MinWordsCountValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The minimum required number of words.
   final int minWordsCount;
 
   @override
@@ -19,7 +33,7 @@ class MinWordsCountValidator extends BaseValidator<String> {
 
   @override
   String? validateValue(String valueCandidate) {
-    final int wordsCount = valueCandidate.trim().split(' ').length;
+    final int wordsCount = valueCandidate.trim().split(RegExp(r'\s+')).length;
 
     return wordsCount < minWordsCount ? errorText : null;
   }

lib/src/string/single_line_validator.dart

@@ -1,7 +1,19 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template single_line_validator_template}
+/// [SingleLineValidator] extends [BaseValidator] to validate if a string contains only a single line.
+///
+/// This validator checks if the value does not contain any newline characters.
+///
+/// ## Parameters:
+///
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class SingleLineValidator extends BaseValidator<String> {
+  /// Constructor for the single line validator.
   const SingleLineValidator({
     /// {@macro base_validator_error_text}
     super.errorText,