Formulaires déclaratifs mobiles
Le paquet natif exporte désormais Form, FormField (alias Field), les champs spécialisés et ConfirmDialog. Le conteneur manuel FormContainer reste disponible. La démo distingue assemblage manuel, formulaire déclaratif, sélections et variantes.
Choisir le propriétaire des valeurs
import { Form } from '@sia-ui/react-native';
<Form
defaultValues={{ name: '', email: '' }}
fields={[
{ name: 'name', label: 'Nom', required: true },
{ name: 'email', label: 'Courriel', type: 'email', required: true },
]}
onSubmit={async (values) => { await save(values); }}
/>Le mode local installe la validation de configuration et accepte une règle globale validate supplémentaire. Pour un adaptateur externe, passer form={form} : ses valeurs, règles et erreurs restent la source de vérité. Utiliser createNativeFormValidator(fields, messages) avec useLocalForm, ou des règles équivalentes de l’application. Le validateur de configuration est synchrone ; l’adaptateur peut gérer sa propre validation asynchrone. Après un enregistrement, appeler form.reset(values) si ces valeurs doivent devenir la référence non modifiée.
Les entrées peuvent être des champs ou des groupes { group, description, fields }. visible(values) masque un champ ; les noms doivent être uniques. render permet un contrôle personnalisé. Les types disponibles sont text, email, password, textarea, number, currency, phone, otp, select, multiselect, autocomplete, checkbox, switch, radio, custom, date, dateRange, dateTime, time, file et image. Les options de ce nouveau lot sont détaillées dans le guide dates et fichiers. Les autres éditeurs web restent à porter.
Variantes et saisies
Les champs texte et de sélection ont trois apparences : outline, filled, underline, et trois tailles sm, md, lg (hauteurs minimales 48/52/56). Les props du champ prennent priorité sur l’apparence du formulaire. Input expose startAdornment, endAdornment et clearable pour une valeur contrôlée. Les erreurs et le focus d’un champ invalide restent rouges. readOnly conserve la lecture sans modification ; disabled bloque l’interaction. Le formulaire en lecture seule masque l’action d’enregistrement.
| Champ | Comportement livré et utilité |
|---|---|
| InputNumber | Valeur number/null, brouillon décimal intermédiaire, bornes au blur, pas, précision optionnelle et boutons masquables. |
| CurrencyInput | Nombre avec précision et suffixe monétaire ; ne prétend pas formater tous les séparateurs locaux. |
| PhoneInput | Normalisation au blur via le registre partagé de pays, défaut CM ; une saisie invalide est conservée pour correction. Aucun sélecteur de pays intégré. |
| OtpInput | Champ unique, nettoyage du collage, longueur 1–12, suggestion système et onComplete dédoublonné. Pas de cases séparées. |
| Textarea | Saisie multiligne avec retour à la ligne ; pas d’envoi sur Entrée par défaut. |
| SearchInput | Effacement et callback de recherche sur validation ; le debounce réseau appartient au chargeur de suggestions. |
Les règles required, email, nombre fini/borné, téléphone configuré et longueur OTP sont proposées par le validateur. Chaque champ peut ajouter validate. Les contraintes d’interface ne remplacent pas la validation côté serveur.
Sélection et recherche
Select, MultiSelect et Autocomplete partagent une feuille et une liste virtualisée. La recherche locale ignore casse et accents. fetcher(query, signal) active une recherche distante différée par debounce ; changer la recherche ou fermer annule la requête et les réponses obsolètes sont ignorées. Les libellés sélectionnés restent conservés entre recherches. Une erreur propose un réessai.
MultiSelect garde la feuille ouverte et propose une confirmation ; Autocomplete peut accepter une valeur libre avec allowCustomValue. Les options désactivées, l’effacement, la lecture seule et le rendu de valeur sont configurables. Le chargement distant ne réalise pas de pagination automatique. Fournir les options initiales nécessaires pour afficher les libellés de valeurs préexistantes.
Clavier et envoi
Form conserve les références des contrôles sans les remonter à chaque frappe. Après validation, le premier contrôle invalide reçoit le focus. La chaîne de saisie saute les contrôles sans clavier, masqués ou verrouillés. Les touches Suivant/Terminé et la barre Précédent/Suivant/Confirmer suivent cette chaîne. Le premier invalide est focalisé après la levée du verrou d’envoi. L’aperçu web ne ferme pas le clavier lors du défilement programmatique : cela préserve le focus lors du déplacement jusqu’à un champ. La barre apparaît avec le clavier sur Android/iOS ; keyboardToolbar={false} la retire et keyboardAccessory permet un remplacement.
AppShell mesure son en-tête pour calculer le décalage. Modal possède déjà la compensation : un formulaire imbriqué ne la double pas. Dans une page déjà défilante, le conteneur manuel peut utiliser scrollable={false} et une compensation explicite adaptée. Le défilement accepte les appuis sur les actions pendant la saisie ; l’envoi est verrouillé et une exception reste présentée comme une erreur utilisateur. Un envoi réussi sans erreur ferme le clavier.
Les feuilles ont expandOnKeyboard={true} par défaut : elles occupent la hauteur disponible à l’ouverture du clavier puis reviennent à leur position configurée. La poignée reste propriétaire de son geste et ferme le clavier au début du glissement. Le déplacement sur tout le contenu reste prévu.
Confirmation et navigation Expo
ConfirmDialog propose action asynchrone, verrou, erreur réessayable, ton danger et confirmation par texte exact. Les messages techniques ne sont pas exposés.
L’entrée optionnelle @sia-ui/react-native/expo-router exporte SiaExpoUnsavedChangesGuard et useSiaExpoNavigation. Le garde utilise le mécanisme officiel de prévention de retrait d’écran d’Expo Router pour Retour/pop/replace et coordonne les liens du shell. Utiliser le hook pour les push/navigate personnalisés ; un appel direct au routeur extérieur à ce circuit ne garantit pas cette protection. Passer when={form.state.isDirty} et onDiscard pour réinitialiser les valeurs. La session et l’autorisation serveur restent des responsabilités distinctes.
Démonstration et validation
/forms/basic: assemblage manuel avec adaptateur./forms/declarative: groupes, validation, envoi, protection de sortie et formulaire en feuille./forms/choices: recherche distante simulée, erreur en saisissant « erreur », choix multiples et valeur libre ; apparences, tailles et états./forms/variants: apparences, tailles, erreurs, lecture seule, désactivation, champs spécialisés et confirmation textuelle avec échec simulé.
Les tests couvrent les contrats de validation, annulation réseau, double envoi, références stables, chaîne clavier et garde de navigation. Les exports vérifient la compilation sur les trois plateformes. À valider sur appareil : clavier physique/IME, défilement jusqu’au champ, redimensionnement des feuilles, Retour, VoiceOver/TalkBack et grandes polices. L’aperçu web ne prouve pas ces comportements.
Positionnement du champ pendant la saisie
La visibilité ne repose plus sur le ScrollResponder et ses métriques internes. Input signale son focus à son hôte FormContainer ou KeyboardScrollView. Celui-ci mesure le champ et son viewport après le focus et après les changements de taille (clavier, barre d’actions, contenu, orientation). Le défilement conserve une marge pour le libellé et le bas du champ, dans les limites du contenu. Les callbacks de mesure devenus obsolètes après un changement de champ sont ignorés. Un champ plus haut que l’espace disponible est aligné par son début ; son contenu reste défilable.
Les actions Précédent/Suivant utilisent désormais deux chevrons dans des cibles tactiles de 48 unités, avec leurs libellés accessibles conservés. Confirmer reste à droite. Le retour au champ précédent annule aussi un blur différé du champ quitté.
Pour une page de saisie sans adaptateur ni bouton d’envoi :
import { Input, KeyboardScrollView } from '@sia-ui/react-native';
<KeyboardScrollView contentContainerStyle={{ padding: 20, gap: 24 }}>
<Input label="Nom" value={name} onChangeText={setName} />
<Input label="Description" multiline value={description} onChangeText={setDescription} />
</KeyboardScrollView>KeyboardScrollView accepte les props ScrollView, une ref, keyboardAvoiding et keyboardVerticalOffset. Il reprend le décalage du shell et reconnaît la compensation d’une modale. Utiliser une seule zone défilante propriétaire : un FormContainer avec scrollable={false} dans une ScrollView extérieure ne peut pas piloter le défilement de cette dernière. Préférer le défilement propre du conteneur. La démo utilise ce défilement pour l’assemblage manuel et KeyboardScrollView pour les catalogues de champs. Les essais clavier/IME sur téléphone restent nécessaires.