VGSConfiguration

public class VGSConfiguration : VGSTextFieldConfigurationProtocol

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.
Show on GitHub

Attributes

  • Collect form (owner) associated with this configuration.

    Side Effects: None on assignment (set only in initializer). Lifetime: Weak to avoid retain cycles with VGSTextField & collector.

    Declaration

    Swift

    public private(set) weak var vgsCollector: VGSCollect? { get }
    Show on GitHub

  • Semantic field type driving built-in behavior (formatting, validation defaults, keyboard suggestions).

    Default: .none (generic text input). Update before binding to a text field for consistent behavior.

    Declaration

    Swift

    public var type: FieldType
    Show on GitHub

  • Vault JSON key that the collected value will map to upon submission.

    Invariants: Should be stable, URL-safe, and unique within a single collector; collisions cause overwriting in the outgoing body. Security: Never embed real secrets; treat as a metadata label only.

    Declaration

    Swift

    public let fieldName: String
    Show on GitHub

  • Indicates that the field must contain a non-empty value for form submission to be considered valid.

    Validation: Checked during collector validation. Empty required fields produce an error list.

    Declaration

    Swift

    public var isRequired: Bool
    Show on GitHub

  • Indicates that if the user provides any value, it must pass validation rules.

    Use Case: Optional fields like second address line or promo code that should not contain invalid data when filled.

    Declaration

    Swift

    public var isRequiredValidOnly: Bool
    Show on GitHub

  • Optional visual formatting pattern (e.g. “#### #### #### ####” for card numbers).

    Behavior: Applied purely at UI layer for readability. Raw value is still captured unformatted.

    Declaration

    Swift

    public var formatPattern: String? { get set }
    Show on GitHub

  • Replacement divider string used when serializing formatted input back to a raw value. Example: A phone pattern with spaces might be collapsed or replaced with divider value during serialization.

    Declaration

    Swift

    public var divider: String?
    Show on GitHub

  • Preferred UITextContentType override used to enhance autofill & keyboard heuristics.

    Auto-Assignment: If not explicitly set, the owning text field may assign a sensible default based on type. Tracking: isTextContentTypeSet indicates whether a custom value has been provided.

    Declaration

    Swift

    public var textContentType: UITextContentType? { get set }
    Show on GitHub

  • Keyboard layout preference; if nil, a type-specific default (e.g. numeric) might be applied by the UI component.

    Declaration

    Swift

    public var keyboardType: UIKeyboardType?
    Show on GitHub

  • Return key style suggestion; does not enforce submission logic itself.

    Declaration

    Swift

    public var returnKeyType: UIReturnKeyType?
    Show on GitHub

  • Keyboard appearance preference (e.g. dark). Default is system/host app standard when nil.

    Declaration

    Swift

    public var keyboardAppearance: UIKeyboardAppearance?
    Show on GitHub

  • A composite of validation rules executed against the raw (unformatted) value to update field validity state.

    Security: Pure evaluation; does not log or persist sensitive values.

    Declaration

    Swift

    public var validationRules: VGSValidationRuleSet?
    Show on GitHub

  • Maximum allowed raw input length (excluding formatting separators).

    Enforcement: Additional user input is rejected or ignored beyond this limit.

    Declaration

    Swift

    public var maxInputLength: Int? { get set }
    Show on GitHub

Initialization

  • Designated initializer.

    Parameters:

    • vgs: Owning VGSCollect instance that will manage submission.
    • fieldName: Vault JSON key for the eventual secure submission payload.

    Preconditions: fieldName should be non-empty (not enforced).

    Declaration

    Swift

    public init(collector vgs: VGSCollect, fieldName: String)
    Show on GitHub

  • Creates a prebuilt configuration for a card number field used in CMP create card requests.

    The configuration:

    • Uses field name "pan".
    • Sets type = .cardNumber.

    • Marks the field as required and required-valid-only.

    Declaration

    Swift

    @MainActor
static func makeCardNumberConfiguration(collector: VGSCollect) -> VGSConfiguration

    Parameters

    collector

    The VGSCollect instance that will register the field.

    Return Value

    A fully configured VGSConfiguration ready to assign to VGSCardTextField/VGSTextField.

    Show on GitHub

  • Creates a prebuilt configuration for a cardholder name field used in CMP create card requests.

    The configuration:

    • Uses field name "cardholder".

    • Sets type = .cardHolderName.

    Declaration

    Swift

    @MainActor
static func makeCardholderConfiguration(collector: VGSCollect) -> VGSConfiguration

    Parameters

    collector

    The VGSCollect instance that will register the field.

    Return Value

    A fully configured VGSConfiguration ready to assign to a VGSTextField.

    Show on GitHub

  • Creates a prebuilt configuration for an expiration date field used in CMP create card requests.

    The configuration:

    • Uses field name "exp_date".
    • Sets type = .expDate.
    • Marks the field as required and required-valid-only.

    • Adds a serializer that outputs separate month/year fields:

      • exp_month
      • exp_year

    Declaration

    Swift

    @MainActor
static func makeExpDateConfiguration(collector: VGSCollect) -> VGSExpDateConfiguration

    Parameters

    collector

    The VGSCollect instance that will register the field.

    Return Value

    A fully configured VGSExpDateConfiguration ready to assign to a VGSTextField.

    Show on GitHub

  • Creates a prebuilt configuration for a CVC field used in CMP create card requests.

    The configuration:

    • Uses field name "cvc".
    • Sets type = .cvc.

    • Marks the field as required and required-valid-only.

    Declaration

    Swift

    @MainActor
static func makeCVCConfiguration(collector: VGSCollect) -> VGSConfiguration

    Parameters

    collector

    The VGSCollect instance that will register the field.

    Return Value

    A fully configured VGSConfiguration ready to assign to a VGSTextField.

    Show on GitHub