OtpField
One-time-code input built on UIKit. Visually it is a row of cells; for VoiceOver and Voice Control it is one text field (the cells, separators, placeholder, and error text are not accessibility elements). Embed view in SwiftUI with a UIViewRepresentable and keep this object alive, for example in the coordinator.
The host owns state and verification: call OtpState.withError or OtpState.cleared after a failed verification and assign the result to state. Typing, deletion, and paste arrive as onStateChange with the new state, which the component renders immediately. onComplete fires once per incomplete-to-complete transition. accessibility and doneButtonTitle must be localized by the host. With a mask other than OtpMask.None the field is a secure text field and VoiceOver gets the label and progress only, never the code.
The field uses the one-time-code content type, so the system can offer codes from messages. An autofilled code is applied as one input, so a code whose length differs from the field is rejected like a paste instead of being cut or filling only some cells. Autofill is recognized by the empty replacement of an empty range iOS sends first; typed keys (also several in one run-loop turn, from a hardware keyboard or Voice Control) are always applied one by one. Setting state to an error state announces OtpFieldAccessibility.errorMessage once without moving focus, and vibrates once when hapticFeedbackOnError is true. alignment only positions the cells and error text; characters inside the row always read left to right. No animation is used, so Reduce Motion needs no special handling.
The keyboard follows OtpState.charset, and changes when a state with another charset is assigned. For OtpCharset.NUMERIC it is the number pad; for OtpCharset.ALPHANUMERIC it is the ASCII keyboard with all-caps autocapitalization, whose Return key (labeled Done) dismisses the keyboard, and there is no input accessory. Autocorrection and spell checking are off for both; letters are shown in uppercase whatever the user types.
The number pad has no Return key, so its text field has a transparent input accessory holding a Done button (titled doneButtonTitle) that calls blur. The button is a system prominent button shaped like a number pad key and placed above the "3" key; the area around it passes touches through, so it does not cover the one-time-code suggestion. The fill is the system tint (dark mode and Increase Contrast apply), darkened as needed so the white title has at least 4.5:1 contrast (7:1 with Increase Contrast). The accessory adds the key height plus 12 pt (about 60 pt) above the keyboard that host layouts avoid: 6 pt above and below the key, like the spacing between number pad rows, and transparent so the suggestion stays tappable. On a hardware keyboard Return and Escape, and for VoiceOver users the two-finger scrub (escape) gesture, also dismiss the keyboard.
No accessibilityHint is set by default, intentionally: progress and error state are already part of the accessibility value, and a hint would be read on every focus.
Properties
Title of the Done button above the number pad (unused for OtpCharset.ALPHANUMERIC). Localized by the host; may change at runtime. Must not be blank.
Vibrates once when state enters the error state.
Called once per rejected multi-character input (paste, autofill, keyboard suggestion) whose character count differs from the field length. The state is unchanged. The counts usually mean the configured OtpLength differs from the host's backend. The code is never passed.