import { ValidatorFn } from '@angular/forms';
/**
 * Special characters allowed in usernames.
 * **IMPORTANT**: If these characters are modified, verify that the escaping logic in
 * {@link getUsernamePattern} handles them correctly.
 */
export declare const usernameCharacters: string;
/**
 * Minimum required length for usernames.
 * Use with `Validators.minLength(minUsernameLength)`.
 */
export declare const minUsernameLength: number;
/**
 * Maximum allowed length for usernames.
 * Use with `Validators.maxLength(maxUsernameLength)`.
 */
export declare const maxUsernameLength: number;
/**
 * RegExp pattern for validating that username starts with a lowercase letter.
 * Useful for apps that want to validate the first character separately.
 *
 * @example
 * ```typescript
 * import { usernameFirstCharPattern } from '@marcura/dadesk-ui-form';
 *
 * if (!usernameFirstCharPattern.test(username)) {
 *   return 'Username must start with a lowercase letter';
 * }
 * ```
 */
export declare const usernameFirstCharPattern: RegExp;
/**
 * Formatted username special characters for display in UI hints/messages.
 * Each character from {@link usernameCharacters} is separated by a non-breaking space for better readability.
 *
 * @example
 * ```typescript
 * import { formattedUsernameCharacters } from '@marcura/dadesk-ui-form';
 *
 * const hint = `Allowed characters: ${formattedUsernameCharacters}`;
 * // Result: "Allowed characters: @ ^ $ . ! ` - # + ' ~ _"
 * ```
 */
export declare const formattedUsernameCharacters: string;
/**
 * Creates a RegExp pattern for validating username characters.
 * Uses the {@link usernameCharacters} constant for allowed special characters.
 *
 * **IMPORTANT**: The escaping logic must be kept in sync with {@link usernameCharacters}
 * to include all characters that require escaping in the regex pattern.
 *
 * @param includeFirstLetterCheck - If true, pattern requires username to start with a lowercase letter.
 *                                   If false, pattern only validates that all characters are allowed.
 *                                   Default: true
 * @returns RegExp pattern for username validation
 *
 * @example
 * ```typescript
 * // With first letter check (default behavior)
 * const patternWithStart = getUsernamePattern();
 * patternWithStart.test('john_doe'); // true
 * patternWithStart.test('John_doe'); // false (uppercase not allowed)
 * patternWithStart.test('_john');    // false (must start with letter)
 *
 * // Without first letter check (for apps that validate first character separately)
 * const patternCharsOnly = getUsernamePattern(false);
 * patternCharsOnly.test('john_doe'); // true
 * patternCharsOnly.test('_john');    // true (first char check not enforced)
 * patternCharsOnly.test('John');     // false (uppercase still not allowed)
 * ```
 */
export declare function getUsernamePattern(includeFirstLetterCheck?: boolean): RegExp;
/**
 * Validates that username starts with a lowercase letter.
 *
 * This validator only checks the first character. It's designed to be used together with
 * {@link usernameFormatValidator} (with `includeFirstLetterCheck = false`) when you need
 * separate error messages for different validation rules.
 *
 * @param validationErrorName - The key name for the validation error in the control's errors object
 * @returns A validator function that returns validation errors or null if valid
 *
 * @example
 * ```typescript
 * import {
 *   usernameFirstCharValidator,
 *   usernameFormatValidator,
 *   minUsernameLength,
 *   maxUsernameLength
 * } from '@marcura/dadesk-ui-form';
 * import { Validators } from '@angular/forms';
 *
 * // Separate validators for specific error messages
 * public readonly username: FormControl<string> = this.createControl(
 *   'username',
 *   '',
 *   [
 *     Validators.required,
 *     Validators.minLength(minUsernameLength),
 *     Validators.maxLength(maxUsernameLength),
 *     usernameFirstCharValidator('usernameStartChar'),      // Check first character
 *     usernameFormatValidator('usernameInvalidChars', false)  // Check all characters
 *   ]
 * );
 *
 * // Now you can show specific error messages:
 * // - errors.usernameStartChar: "Username must start with a lowercase letter"
 * // - errors.usernameInvalidChars: "Username contains invalid characters"
 * ```
 */
export declare function usernameFirstCharValidator(validationErrorName: string): ValidatorFn;
/**
 * Validates username format for new user creation.
 *
 * This validator checks if the username contains valid characters. By default, it also validates
 * that the username starts with a lowercase letter. Length validation should be performed
 * separately using `Validators.minLength()` and `Validators.maxLength()`.
 *
 * Requirements (with default includeFirstLetterCheck = true):
 * - Must start with a lowercase letter (a-z)
 * - Can contain: lowercase letters (a-z), numbers (0-9), and special characters defined in {@link usernameCharacters}
 * - Special characters allowed: {@link usernameCharacters}
 * - Recommended length: {@link minUsernameLength} to {@link maxUsernameLength} characters (validated separately)
 *
 * @param validationErrorName - The key name for the validation error in the control's errors object
 * @param includeFirstLetterCheck - If true, validates that username starts with a lowercase letter.
 *                                   If false, only validates character set (useful when validating first char separately).
 *                                   Default: true
 * @returns A validator function that returns validation errors or null if valid
 *
 * @example
 * Basic usage with all-in-one validation:
 * ```typescript
 * import {
 *   usernameFormatValidator,
 *   minUsernameLength,
 *   maxUsernameLength,
 *   formattedUsernameCharacters
 * } from '@marcura/dadesk-ui-form';
 * import { Validators } from '@angular/forms';
 *
 * // In your form class
 * public readonly username: FormControl<string> = this.createControl(
 *   'username',
 *   '',
 *   [
 *     Validators.required,
 *     Validators.minLength(minUsernameLength),
 *     Validators.maxLength(maxUsernameLength),
 *     usernameFormatValidator('usernameInvalidCharacters')
 *   ]
 * );
 *
 * // In your component for displaying hints
 * public readonly usernameHint: string =
 *   `Username must be ${minUsernameLength}-${maxUsernameLength} characters, ` +
 *   `start with a letter, and may contain: a-z, 0-9, ${formattedUsernameCharacters}`;
 * ```
 *
 * @example
 * Using separate validators for refined error messages:
 * ```typescript
 * import {
 *   usernameFirstCharValidator,
 *   usernameFormatValidator,
 *   minUsernameLength,
 *   maxUsernameLength
 * } from '@marcura/dadesk-ui-form';
 * import { Validators } from '@angular/forms';
 *
 * // In your form class - validate first char separately for specific error message
 * public readonly username: FormControl<string> = this.createControl(
 *   'username',
 *   '',
 *   [
 *     Validators.required,
 *     Validators.minLength(minUsernameLength),
 *     Validators.maxLength(maxUsernameLength),
 *     usernameFirstCharValidator('usernameStartChar'),         // Separate first char check
 *     usernameFormatValidator('usernameInvalidChars', false)   // Character set check only
 *   ]
 * );
 * ```
 */
export declare function usernameFormatValidator(validationErrorName: string, includeFirstLetterCheck?: boolean): ValidatorFn;