VGSTextField

@MainActor
public class VGSTextField : UIView
extension VGSTextField: UITextFieldDelegate
extension VGSTextField: @preconcurrency MaskedTextFieldDelegate

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:

Show on GitHub

UI Attributes

  • Placeholder text displayed when there is no user input.

    • Update before field becomes first responder to avoid layout flicker.

    Declaration

    Swift

    @MainActor
public var placeholder: String? { get set }
    Show on GitHub

  • Autocapitalization behavior for textual input.

    • Default: .sentences.
    • Usually left as default for names; set .none for numeric / code inputs.

    Declaration

    Swift

    @MainActor
public var autocapitalizationType: UITextAutocapitalizationType { get set }
    Show on GitHub

  • Spell checking behavior.

    • Default: .default.
    • Set .no for numeric or strictly formatted fields (card, CVC, SSN).

    Declaration

    Swift

    @MainActor
public var spellCheckingType: UITextSpellCheckingType { get set }
    Show on GitHub

  • Attributed placeholder allowing styled placeholder text.

    • Loses effect if placeholder later reassigned; prefer one approach.

    Declaration

    Swift

    @MainActor
public var attributedPlaceholder: NSAttributedString? { get set }
    Show on GitHub

  • Natural intrinsic size including content insets (padding).

    Declaration

    Swift

    @MainActor
public override var intrinsicContentSize: CGSize { get }
    Show on GitHub

  • Content inset for text & placeholder inside the field.

    • Adjust to increase touch target or visual spacing.

    Declaration

    Swift

    @MainActor
public var padding: UIEdgeInsets { get set }
    Show on GitHub

  • Horizontal text alignment.

    • Defaults to .natural; adjust for RTL/LTR explicit layout needs.

    Declaration

    Swift

    @MainActor
public var textAlignment: NSTextAlignment { get set }
    Show on GitHub

  • Clear button display mode.

    • Default: .never.
    • Avoid enabling for sensitive fields unless UX mandates quick clearing.

    Declaration

    Swift

    @MainActor
public var clearButtonMode: UITextField.ViewMode { get set }
    Show on GitHub

  • Secure text entry toggle.

    • Masks visible characters when true; use for CVC or other sensitive short values.
    • Avoid enabling for card number masking (handled by format pattern & state exposure of last4 instead).

    Declaration

    Swift

    @MainActor
public var isSecureTextEntry: Bool { get set }
    Show on GitHub

  • Dynamic Type scaling flag.

    • Enable if adopting system-wide accessibility text size adjustments.

    Declaration

    Swift

    @MainActor
public var adjustsFontForContentSizeCategory: Bool { get set }
    Show on GitHub

  • Custom accessory view displayed above the keyboard (e.g. toolbar with Done button).

    Declaration

    Swift

    @MainActor
public var keyboardAccessoryView: UIView? { get set }
    Show on GitHub

  • Autocorrection behavior.

    • Default .default; disable (.no) for formats like card number, CVC, SSN, dates.

    Declaration

    Swift

    @MainActor
public var autocorrectionType: UITextAutocorrectionType { get set }
    Show on GitHub

Accessibility Attributes

  • Accessibility label describing the field’s purpose (without sensitive content).

    Declaration

    Swift

    @MainActor
public var textFieldAccessibilityLabel: String? { get set }
    Show on GitHub

  • Accessibility hint describing the result of interaction (avoid exposing actual values).

    Declaration

    Swift

    @MainActor
public var textFieldAccessibilityHint: String? { get set }
    Show on GitHub

  • Determines if the underlying text control is an accessibility element.

    • Set false only when grouping with a custom container element.

    Declaration

    Swift

    @MainActor
public var textFieldIsAccessibilityElement: Bool { get set }
    Show on GitHub

Functional Attributes

  • Configuration establishing semantic type, formatting, validation rules, and collector registration.

    Behavior:

    • On assignment: registers with the provided VGSCollect instance; applies format & validation defaults.
    • Re-assignment replaces previous configuration (not recommended mid-edit).
    • Nil assignment logs a warning and leaves field unregistered.

    Usage:

    let cfg = VGSConfiguration(collector: collector, fieldName: "card_cvc")
cfg.type = .cvc
cvcField.configuration = cfg

    Notes:

    • Set before user interaction; avoid mutation while first responder.

    Declaration

    Swift

    @MainActor
public var configuration: VGSConfiguration? { get set }
    Show on GitHub

  • Delegate receiving editing lifecycle callbacks (begin, change, end, return).

    Declaration

    Swift

    @MainActor
public weak var delegate: VGSTextFieldDelegate?
    Show on GitHub

Manage input

  • Sets a default (prefilled) value WITHOUT marking field as dirty.

    • Use for restoring a non-sensitive placeholder-like value or formatting demonstration.
    • Does not trigger isDirty so initial unchanged state logic remains intact.
    • If maxInputLength is specified, value is trimmed accordingly.

    Declaration

    Swift

    @MainActor
public func setDefaultText(_ text: String?)
    Show on GitHub

  • Removes all input content.

    • Resets formatting state while retaining configuration.

    Declaration

    Swift

    @MainActor
public func cleanText()
    Show on GitHub

Compare Input

  • Compares raw (unformatted) content equality with another VGSTextField.

    • Ignores masking characters and dividers.
    • Useful for confirm-input patterns (e.g. email repeat) when using masking.

    Declaration

    Swift

    @MainActor
public func isContentEqual(_ textField: VGSTextField) -> Bool
    Show on GitHub

Text Attribute

  • VGSTextField text font

    Declaration

    Swift

    @MainActor
var font: UIFont? { get set }
    Show on GitHub

  • VGSTextField text color

    Declaration

    Swift

    @IBInspectable
@MainActor
var textColor: UIColor? { get set }
    Show on GitHub

UI Layer Attribute

UIResponder methods