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.
• The default generated component doesn't fit - you need custom chrome, imperative focus, a modal/sheet trigger, extra buttons, a composite widget, or a 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 only need to restyle the default renderer, prefer globalDefaults or per-field props first. If you need a brand new field type that no builder covers, jump to field.custom() instead.

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 controller.descriptor (advanced) when you need to inspect the resolved builder descriptor - for example to read the mask pattern, the min/max of a field.number(), or the accepted MIME types of a field.file() - without re-declaring them in the renderer.

• Prefer fieldController(name) over field.custom() when you still want a built-in field type such as select, masked, phone, or otp.
• Prefer fieldController(name) over builder-level .render(fn) when the custom UI needs surrounding layout, external buttons, modal state, or imperative focus control from outside the field.
• Prefer renderPicker (on field.select / field.radio / field.date) over fieldController(name) when only the picker surface changes and the built-in field trigger is already good enough.
• Prefer globalDefaults or per-field props over fieldController when the change is purely visual - styling, spacing, label alignment - and the underlying markup is fine.