UI Elements

A secure input view that masks, formats, and validates sensitive user data before submission via VGSCollect.

Summary: Acts as the primary UI component for secure data entry (card number, CVC, expiration date, SSN, generic text, etc.). Provides formatting masks, validation rule application, secure raw storage abstraction, and integration hooks for tokenization.

Responsibilities:

• Applies format pattern & divider to user keystrokes (dynamic for certain types like card number).
• Exposes state snapshots (state) through VGSCollect observation closures for validation & UI feedback.
• Holds reference to VGSConfiguration that defines semantic role, validation rules, input formatting and tokenization parameters.

Formatting & Masking:

• formatPattern (from configuration or dynamic adjustment) determines visible grouping (# placeholders).
• divider inserted between pattern groups (e.g. / for dates, - for SSN).
• Card number and CVC patterns update automatically based on detected brand when using associated field types.

Validation:

• Default validation rules determined by FieldType; can be overridden via configuration.validationRules.
• Validation runs on each editing change and contributes to field & form state.

Usage:

let cardField = VGSCardTextField() // or VGSTextField()
let cfg = VGSConfiguration(collector: collector, fieldName: "card_number")
cfg.type = .cardNumber
cfg.isRequiredValidOnly = true
cardField.configuration = cfg // registers with collector
// Observe validity via collector.observeFieldState or cardField.state (if public)

Security:

• Never read or log internal textField contents directly; rely on state metadata (last4, isValid).
• Do not persist raw user-entered values (store only aliases returned from backend responses).
• Avoid copying sensitive field values into analytics, crash logs, or third-party SDKs.

Performance:

• Avoid repeatedly reassigning configuration after user input begins.

Accessibility:

• Customize accessibility label/hint via provided properties; keep hints free of sensitive content.
• Ensure sufficient contrast and dynamic type scaling if adjustsFontForContentSizeCategory is enabled.

Invariants / Preconditions:

• A non-nil configuration is required before using the field for secure submission.
• Do not mutate configuration while field is first responder to avoid inconsistent formatting.

See also:

• VGSConfiguration for defining semantic meaning & validation.
• VGSCollect for submission & state observation.

See more

@MainActor
public class VGSTextField : UIView

extension VGSTextField: UITextFieldDelegate

extension VGSTextField: @preconcurrency MaskedTextFieldDelegate

An object that displays an editable text area. Can be use instead of a VGSTextField when need to detect and show credit card brand images.

Overview: VGSCardTextField extends VGSTextField to provide real-time card brand detection (Visa, Mastercard, etc.) and an optional brand icon. It dynamically:

• Detects card brand as the user types.
• Updates spacing/formatting pattern automatically.
• Propagates brand-specific CVC length & formatting to attached VGSCVCTextField.

Usage:

1. Create instance and assign a VGSConfiguration whose type is .cardNumber (or specialized tokenization configuration).
2. Optionally customize icon presentation via cardIconLocation, cardIconSize, or supply a closure in cardsIconSource for custom imagery.
3. Observe field state (state cast to VGSCardState) to access bin, last4, and cardBrand after valid input.

Accessibility:

• Keep cardIconViewIsAccessibilityElement = true for voiceover users; set cardIconAccessibilityHint to a localized brand description.
• Avoid adding sensitive PAN information to accessibility hints.

Performance: Brand detection runs on each input change.

Security:

• No raw PAN characters are logged or exposed via public API.

See more

@MainActor
public final class VGSCardTextField : VGSTextField

An object that displays an editable text area. Can be use instead of a VGSTextField when need to show picker view with Card Number Expiration Month and Year.

Overview: VGSExpDateTextField presents a month/year picker or keyboard for collecting card expiration date securely. It auto-validates against current month to prevent past dates and adapts its formatting based on configuration.

Features:

• Month & year picker with customizable label formats (MonthFormat, YearFormat).
• Prevents selection of expired month (auto-corrects if user navigates to past entry in current year).
• Supports keyboard input fallback when configuration sets inputSource = .keyboard.
• Integrates with VGSExpDateConfiguration for formatting & serialization, including tokenization scenarios.

Usage:

1. Create text field and assign a VGSExpDateConfiguration (or tokenization configuration) to configuration before editing begins.
2. Optionally set monthPickerFormat / yearPickerFormat for UI preferences.
3. Read state for validation errors; submit through VGSCollect.

Accessibility:

• Picker components inherit system traits; provide a meaningful placeholder so VoiceOver announces context.
• Avoid exposing actual card number or other PII in any associated labels.

Performance:

• Data source arrays are lightweight; picker updates only on relevant component changes.

See more

@MainActor
public final class VGSExpDateTextField : VGSTextField

extension VGSExpDateTextField: UIPickerViewDelegate, UIPickerViewDataSource

An object that displays an editable text area. Can be use instead of a VGSTextField when need to show picker view with a Date. It support to define a range of valid dates to select from.

See more

@MainActor
public final class VGSDateTextField : VGSTextField

extension VGSDateTextField: UIPickerViewDelegate, UIPickerViewDataSource

An object that displays an editable text area. Can be use instead of a VGSTextField when need to show CVC/CVV images for credit card brands.

Overview: VGSCVCTextField augments VGSTextField by rendering a brand-specific CVC/CVV helper icon whose size and position you can customize. When paired with a VGSCardTextField, the icon and validation rules adapt to the detected brand (e.g. 3 vs 4 digit CVC length).

Usage:

1. Assign a VGSConfiguration with type = .cvc (or tokenization config) before user input.
2. Optionally adjust cvcIconLocation, cvcIconSize, or supply a custom image provider via cvcIconSource.
3. Keep accessibility hints descriptive but free of sensitive details.

Accessibility:

• cvcIconViewIsAccessibilityElement controls VoiceOver exposure.
• Use cvcIconAccessibilityHint for localized explanation: e.g. “CVC help icon”.

Security:

• Avoid logging or embedding confidential data inside accessibility strings.

See more

@MainActor
public final class VGSCVCTextField : VGSTextField

Delegates produced by VGSTextField instance.

See more

@objc
@MainActor
public protocol VGSTextFieldDelegate

A configuration object that defines semantic meaning, formatting and validation rules for an attached VGSTextField.

Summary: Configure how a secure text field should behave (data type, keyboard, formatting, validation, and submission key) when collecting sensitive data for VGS vault submission.

Responsibilities:

• Declares the vault JSON key (fieldName) used during submission.
• Specifies field semantic type (e.g. card number, CVC) that drives built–in formatting & validation defaults.
• Holds optional custom validation rules and formatting pattern overrides.
• Provides UI hints (keyboard type, return key, content type, appearance) without directly altering UI until bound.

Security:

• fieldName is a logical alias only; never place raw secrets or PII in the name itself.
• Formatting (masking/spacing) is purely cosmetic and does NOT sanitize or truncate the raw secure value transmitted to the vault.

Usage:

1. Instantiate with a VGSCollect instance and unique fieldName.
2. Adjust optional properties (e.g. isRequired, validationRules, formatPattern).
3. Assign the configuration to a VGSTextField before user input begins.

Invariants / Preconditions:

• fieldName should be non-empty and unique per collector to avoid ambiguous payload keys. (Not currently enforced at runtime.)
• Changing properties after the field has begun editing may not retroactively re-validate already entered content.

See more

public class VGSConfiguration : VGSTextFieldConfigurationProtocol

A class responsible for configuration VGSTextField with fieldType = .expDate. Extends VGSConfiguration class.

See more

@MainActor
public final class VGSExpDateConfiguration : VGSConfiguration, VGSExpDateConfigurationProtocol, VGSFormatSerializableProtocol

Class responsible for configuration VGSDateTextField or VGSTextField with fieldType = .date. Extends VGSConfiguration

See more

@MainActor
public final class VGSDateConfiguration : VGSConfiguration, VGSDateConfigurationProtocol, VGSFormatSerializableProtocol

VGSCardHolderNameTokenizationConfiguration - textfield configuration for textfield with type .cardHolderName, required for work with tokenization api.

Usage:

1. Initialize with your VGSCollect instance and a fieldName (JSON key for outbound payload).
2. Assign to a VGSTextField before user begins editing.
3. Call tokenizeData(routeId:) or createAliases(routeId:) on the collector; the response JSON will include generated alias(es).

Notes:

• Customize tokenizationParameters.format if you need different alias semantics.
• Never include real PII inside fieldName; it is only a logical key.

See more

@MainActor
public class VGSCardHolderNameTokenizationConfiguration : VGSConfiguration, VGSTextFieldTokenizationConfigurationProtocol

VGSCardNumberTokenizationConfiguration - configuration for a text field collecting card numbers (.cardNumber). Required for tokenization API usage.

Summary: Specialized configuration enabling PAN tokenization while retaining dynamic brand-driven formatting and validation inherited from VGSConfiguration.

Behavior:

• Forces type to .cardNumber.
• Supplies tokenizationParameters consumed by tokenization / alias APIs.

Usage:

let cardCfg = VGSCardNumberTokenizationConfiguration(collector: collector, fieldName: "card_number")
cardCfg.tokenizationParameters.format = VGSVaultAliasFormat.FPE_SIX_T_FOUR.rawValue
cardField.configuration = cardCfg
// Later submit
collector.createAliases { response in /* handle */ }

Customization Notes:

• Override tokenizationParameters.format before attaching to the field to avoid mid-edit alias policy changes.
• For fully opaque tokens choose VGSVaultAliasFormat.UUID.rawValue.
• Validation rules can be replaced with a custom VGSValidationRuleSet if business logic restricts brands or lengths.

Security:

• Never log raw PAN; rely on card state (last4, brand) for limited display needs.

See more

@MainActor
public class VGSCardNumberTokenizationConfiguration : VGSConfiguration, VGSTextFieldTokenizationConfigurationProtocol

VGSCVCTokenizationConfiguration - textfield configuration for textfield with type .cvc, required for work with tokenization api.

Summary: Specialized configuration subclass for CVC fields enabling tokenization when submitting via Vault API methods (e.g. tokenizeData, createAliases).

Behavior:

• Forces type to .cvc (override ignores external setter attempts).
• Supplies tokenizationParameters used to build tokenization request body.
• Inherits formatting & validation from VGSConfiguration; defaults still apply unless overridden.

Usage:

let cvcCfg = VGSCVCTokenizationConfiguration(collector: collector, fieldName: "card_cvc")
// Optional: adjust alias format
cvcCfg.tokenizationParameters.format = VGSVaultAliasFormat.FPE_SIX_T_FOUR.rawValue
cvcField.configuration = cvcCfg

Customization Notes:

• Modify tokenizationParameters.format before assigning configuration to the field.
• Validation rules can still be overridden via validationRules if needed.
• Storage should remain volatile for CVC (do not switch to persistent unless explicit compliance requirements dictate).

Security:

• Tokenization reduces exposure of raw CVC; never log raw input even with tokenization enabled.

See more

@MainActor
public class VGSCVCTokenizationConfiguration : VGSConfiguration, VGSTextFieldTokenizationConfigurationProtocol

VGSDateTokenizationConfiguration - configuration object for a date field tokenization.

Summary: Specialized configuration for .date fields enabling Vault tokenization, optional date-picker input, and optional format serialization before submission.

Behavior:

• Forces type to .date.
• Provides tokenizationParameters consumed by tokenization/alias APIs.
• Supports optional date picker via inputSource = .datePicker and year range customization (datePickerStartDate / datePickerEndDate).
• Allows input/output date format conversion & serialization through serializers collection.

Usage:

let dateCfg = VGSDateTokenizationConfiguration(collector: collector, fieldName: "event_date")
dateCfg.inputSource = .datePicker
dateCfg.inputDateFormat = .mmddyyyy
dateCfg.outputDateFormat = .yyyymmdd
dateCfg.tokenizationParameters.format = VGSVaultAliasFormat.UUID.rawValue
dateField.configuration = dateCfg

Customization Notes:

• Set format conversion properties before assigning configuration to the field.
• Provide serializers when you need extra structured output (e.g. separate year/month fields) prior to tokenization.
• Adjust start/end picker dates via initializer optional parameters.

Security:

• Tokenization replaces raw date with an alias; never log raw date content if considered sensitive (e.g. birth dates).
• Do not persist raw input.

See more

@MainActor
public final class VGSDateTokenizationConfiguration : VGSConfiguration, VGSDateConfigurationProtocol, @preconcurrency VGSTextFieldTokenizationConfigurationProtocol, VGSFormatSerializableProtocol

extension VGSDateTokenizationConfiguration: @preconcurrency VGSTextFormatConvertable

VGSExpDateTokenizationConfiguration - textfield configuration for textfield with type .expDate, required for work with tokenization api. Assign to VGSExpDateTextField (or generic VGSTextField) before user input to enable expiration date tokenization.

Summary: Specialized configuration enabling tokenization, optional date picker input source, and raw-to-formatted expiration date conversion (short/long year) prior to submission.

Behavior:

• Forces type to .expDate.
• Provides tokenizationParameters consumed by tokenization / alias APIs.
• Supports picker-based entry via inputSource = .datePicker and format conversion using inputDateFormat / outputDateFormat.
• Allows serialization into structured components through serializers before alias creation.

Usage:

let expCfg = VGSExpDateTokenizationConfiguration(collector: collector, fieldName: "card_exp")
expCfg.inputSource = .datePicker
expCfg.inputDateFormat = .shortYear
expCfg.outputDateFormat = .longYear
expCfg.tokenizationParameters.format = VGSVaultAliasFormat.UUID.rawValue
expCfg.serializers = [ExpDateFormatSerializer.month("exp_month"), ExpDateFormatSerializer.year("exp_year")] // example serializers
expField.configuration = expCfg

Customization Notes:

• Set format conversion & serializers before assigning configuration to field for consistent initial UI.
• Use serializers only when you need extra separated alias fields (month/year) beyond the single expiration alias.
• Validation rules can be overridden with a custom VGSValidationRuleSet if business constraints differ (e.g. extended future range).

Security:

• Treat expiration dates as sensitive.

See more

@MainActor
public final class VGSExpDateTokenizationConfiguration : VGSConfiguration, VGSExpDateConfigurationProtocol, @preconcurrency VGSTextFieldTokenizationConfigurationProtocol, VGSFormatSerializableProtocol

extension VGSExpDateTokenizationConfiguration: @preconcurrency VGSTextFormatConvertable

VGSSSNTokenizationConfiguration - textfield configuration for textfield with type .ssn, required for work with tokenization api.

Summary: Specialized configuration enabling tokenization for SSN fields, ensuring alias creation while preserving standard SSN input formatting and validation.

Behavior:

• Forces type to .ssn regardless of external attempts to modify.
• Supplies tokenizationParameters consumed by tokenization / alias APIs.
• Inherits base formatting & validation from VGSConfiguration; you may override validationRules for custom compliance constraints.

Usage:

let ssnCfg = VGSSSNTokenizationConfiguration(collector: collector, fieldName: "user_ssn")
ssnCfg.tokenizationParameters.format = VGSVaultAliasFormat.UUID.rawValue
ssnField.configuration = ssnCfg

Customization Notes:

• Adjust alias format prior to assigning configuration to avoid mid-edit format shifts.
• Do not relax SSN regex to avoid collecting malformed identifiers.

Security:

• Treat SSN as highly sensitive.

See more

@MainActor
public class VGSSSNTokenizationConfiguration : VGSConfiguration, VGSTextFieldTokenizationConfigurationProtocol

VGSTokenizationConfiguration - textfield configuration for a text field with any supported FieldType, enabling tokenization when no specialized configuration exists.

Summary: Generic catch-all tokenization configuration. Use for field types like .cardHolderName, .none, or custom data keys where dedicated tokenization subclasses are not provided.

Behavior:

• Inherits all formatting, validation, and requirement handling from VGSConfiguration.
• Adds tokenizationParameters consumed by Vault tokenization / alias creation APIs (tokenizeData, createAliases).

Usage:

let nameCfg = VGSTokenizationConfiguration(collector: collector, fieldName: "card_holder")
nameCfg.type = .cardHolderName
nameCfg.tokenizationParameters.format = VGSVaultAliasFormat.UUID.rawValue
nameField.configuration = nameCfg
// Later:
collector.createAliases { response in /* handle alias mapping */ }

Customization Notes:

• Set type and any validationRules before tokenization to ensure correct evaluation.
• For highly sensitive transient values consider switching storage to .VOLATILE (alias may not be reusable long-term).
• Use a deterministic alias format only if your backend requires stable pattern characteristics.

Security:

• Never log raw input pre-tokenization.

See more

@MainActor
public class VGSTokenizationConfiguration : VGSConfiguration, VGSTextFieldTokenizationConfigurationProtocol

Define the methods and properties the date configuration must have

See more

@MainActor
public protocol VGSDateConfigurationProtocol

Attributes required to configure date format and input source for field with type .expDate.

See more

@MainActor
public protocol VGSExpDateConfigurationProtocol

Type of VGSTextField configuration.

See more

public enum FieldType : Int, CaseIterable

Format used to validate a VGS date text input

See more

@MainActor
public enum VGSDateFormat : InputConvertableFormat, OutputConvertableFormat, Sendable

Struct that represents a date including year, month and day. It doesn’t include hours, minutes or seconds.

See more

public struct VGSDate

extension VGSDate: Comparable

Type of VGSTextField input source.

See more

public enum VGSTextFieldInputSource