fieldController()

Use fieldController(name) when all of the following are true:

• The field should stay typed as one of the built-in builder types (text, email, select, radio, masked, phone, otp, date, file, number, …) so you inherit its validation, normalization, and conditional semantics.
• You need to bind the field runtime to an input, modal/sheet trigger, composite widget, or shared design-system wrapper.
• You still want the renderer to be driven by reactive state (value, error, touched, validating, visible) so conditional rules, persistence, and analytics keep working.

If you need a brand new value type that no builder covers, use field.custom() and render its controller the same way.

Complete fieldController(name) surface:

Every property is type-narrowed against the schema: value is typed as the exact value type of the field (for example string for field.text, boolean for field.checkbox, SelectOption['value'] for field.select), and options / otpLength only appear on the field types that actually expose them.

controller.focus() and controller.blur() do nothing by default - you have to tell FormBridge *how* to focus your custom element. That is what registerFocusable(target) is for.

• Web - pass a DOM node via a ref callback: ref={(node) => controller.registerFocusable(node)}. FormBridge will call node.focus() / node.blur().
• Native - pass a React Native TextInput ref the same way. FormBridge uses its imperative focus() / blur() methods.
• Custom widgets - pass any object of shape { focus?: () => void; blur?: () => void }. This is how you wire modals, bottom sheets, rich editors, or third-party components. Call registerFocusable(null) on unmount to detach.

Once registered, FormBridge can drive focus from anywhere - auto-focus on mount, focus the first invalid field after a failed submit, jump to a field when a server-side error lands, or chain focus through a wizard step.

• Always call onBlur() after the user finishes interacting with a custom trigger (closing a modal, leaving a popover). Without it, touched stays false and validateOn: 'onBlur' / 'onTouched' never fires.
• Respect visible - when a conditional rule hides the field, either render nothing or render it disabled. Hidden fields still hold a value but should not be editable.
• Respect disabled - the runtime sets it from the schema and from conditional rules; forwarding it keeps the form consistent with other fields.
• Prefer onChange over setValue for user-driven edits: onChange fires the full update pipeline (change handlers, validation, analytics), while setValue is meant for imperative updates (presets, paste handlers, resets).
• Don't read state.values[name] directly for rendering - read controller.value. The controller subscribes the component to that field only, avoiding re-renders on unrelated updates.
• Use the type-specific controller metadata documented by each builder instead of relying on private descriptor fields.

• Use fieldController(name) for built-in field types such as select, masked, phone, or otp.
• Use field.custom() when the schema needs a value model not covered by a built-in builder.
• Keep purely visual decisions in the component or design-system adapter that consumes the controller.