Listes et parcours métier mobiles
Ce lot expérimental ajoute un parcours liste → détail → création/modification et suppression dans @sia-ui/react-native. La démo Contacts utilise les routes Expo Router et un stockage local persistant. Aucun serveur métier n'est fourni.
Déclarer la ressource
import { CrudPage, defineResource } from '@sia-ui/react-native';
import type { ResourceDataSource } from '@sia-ui/headless';
type Contact = { id: string; name: string; email: string };
const resource = defineResource<Contact>({
name: 'contacts',
label: { singular: 'Contact', plural: 'Contacts', create: 'Nouveau contact' },
permissions: { view: 'contacts.read', create: 'contacts.create',
edit: 'contacts.edit', delete: 'contacts.delete' },
fields: {
id: { readOnly: true, inList: false },
name: { label: 'Nom', required: true, card: 'title', sortable: true },
email: { label: 'E-mail', type: 'email', required: true, card: 'subtitle' },
},
});
// Définir hors du rendu, ou mémoriser selon le compte/tenant courant.
const source: ResourceDataSource<Contact> = {
list: (query, { signal }) => api.listContacts(query, { signal }),
get: (id, { signal }) => api.getContact(id, { signal }),
create: (values, { signal }) => api.createContact(values, { signal }),
update: (id, values, { signal }) => api.updateContact(id, values, { signal }),
remove: (id, { signal }) => api.deleteContact(id, { signal }),
};
// `api` est votre client : adapter les signatures à votre serveur.
export function ContactsPage() {
return <CrudPage resource={resource} source={source} can={access.can} />;
}api et access sont injectés par l'application. list reçoit la page (à partir de 1), perPage, search, sort et filters. Il doit retourner { items, total }, où total est le nombre de résultats après filtrage, avant pagination. get retourne une ligne ou null pour une fiche introuvable. L'identifiant doit être stable : champ id par défaut ou fonction key déclarée. Les méthodes d'écriture sont facultatives ; leur absence masque l'action concernée.
Les métadonnées et conventions de permissions sont communes dans le paquet headless. Les champs, rendus et contrôles restent propres à chaque plateforme : une définition contenant des éléments DOM ne se réutilise pas telle quelle en natif. Le web conserve ses exports resourcePermissions et createPermissionConvention.
Formulaire et données
Les champs déclarés génèrent le formulaire et les valeurs initiales. inForm, inList, inDetail, group, renderControl et render ajustent chaque surface. Les champs serveur, calculés ou en lecture seule sont exclus du formulaire sauf inclusion explicite. Les mots de passe/OTP sont masqués dans les fiches et exclus des listes par défaut. Un mot de passe n'est pas prérempli en édition.
defaults, toValues, toCreate et toUpdate permettent de séparer entité, valeurs de formulaire et DTO. En cas de validation serveur, lever new ResourceValidationError({ email: 'Cette adresse existe déjà.' }) depuis l'adaptateur. Les erreurs sont rattachées aux champs ; un échec global laisse la saisie en place et permet de réessayer. Les détails techniques d'une exception ne sont pas affichés à l'utilisateur.
Le formulaire réutilise le défilement et les commandes du clavier natif. Une annulation avec saisie non enregistrée demande confirmation. Pour les gestes retour, liens et navigation Expo, fournir renderFormGuard avec SiaExpoUnsavedChangesGuard ; voir apps/native-demo/demo/contacts.tsx. Le simple bouton Annuler dispose également d'une confirmation sans Expo Router.
Liste et variantes
ResourceListutiliseFlatList, sans imbriquer une liste dans un ScrollView.variant="cards" | "rows",density="comfortable" | "compact",paginationVariant="compact" | "pages",pageSizes,renderItemetheaderpersonnalisent le rendu. Les valeurs par défaut du provider passent parresourceListdans les defaults natifs.FiltersBarréunit recherche et filtres simples en feuille, avec validation, annulation et résumé des valeurs actives. Recherche temporisée de 250 ms par défaut ; Entrée et Actualiser déclenchent immédiatement la requête.- Recherche, filtres, taille de page et tri reviennent à la première page.
useTableQueryexposesetSort; un contrôleur personnalisé ancien sans ce setter reste accepté mais n'affiche pas le sélecteur de tri de la liste native. showRefreshetpullToRefreshcontrôlent les deux modes d'actualisation. Un échec d'actualisation conserve les lignes déjà chargées et offre un réessai.- La dernière page est corrigée si le total diminue. Une recherche ou un changement de fiche masque les anciennes données ; les réponses périmées sont ignorées et leur signal est annulé. L'adaptateur doit transmettre ce signal au transport.
PageHeader, Descriptions (vertical ou en ligne), Pagination (compacte ou pages), AsyncState et PermissionGate sont exportés séparément. CrudPage accepte aussi une route contrôlée (route, onRouteChange), un contrôleur de requête et une requête de liste partagés pour garder l'état entre écrans. initialScrollOffset et onScroll permettent de restaurer le défilement.
Droits et états
can évalue les règles de la ressource. Une règle déclarée sans évaluateur est refusée. Sans règle déclarée, l'opération reste autorisée par défaut. La lecture refusée ne lance pas les requêtes ; création, modification et suppression revérifient le droit avant l'appel. L'API doit appliquer sa propre autorisation : masquer un bouton ne protège pas un serveur.
Chargement, vide, accès refusé, fiche introuvable, erreur et réessai ont chacun un rendu adapté. Une suppression exige confirmation. Après enregistrement, la fiche est rechargée et le formulaire cesse d'être considéré comme modifié avant de naviguer. Une écriture déjà reçue par le serveur n'est pas annulée rétroactivement par un AbortSignal ; l'idempotence reste une responsabilité de l'API.
Tester Contacts
- Lancer
pnpm native, ouvrir la démo et choisir Administrateur. - Ouvrir Contacts : 30 exemples au premier lancement, 10 par page.
- Rechercher, filtrer le statut, trier, changer la page, puis ouvrir une fiche. Revenir à la liste : critères et page sont conservés pendant la navigation.
- Créer un contact, vérifier les champs obligatoires et un e-mail déjà utilisé. Tester l'échec d'enregistrement puis réessayer sans perdre la saisie.
- Modifier la fiche, tester l'annulation et la protection contre la perte de saisie.
- Annuler une suppression, puis la confirmer ; vérifier le total de la liste.
- Dans Options de démonstration, comparer cartes/lignes, densités et pagination, puis simuler attente, liste vide, lecture seule et erreurs liste/fiche.
- Recharger l'application pour vérifier la persistance, puis se reconnecter en Membre : consultation seule. Le bouton de réinitialisation restaure les exemples.
Les données de cette démo sont communes aux comptes locaux sur l'appareil. Les critères et le défilement ne sont pas persistés après un rechargement complet. Les tests automatisés et les exports Expo ne remplacent pas les essais physiques Android/iOS du clavier, des gestes, du lecteur d'écran et des grandes polices.
Prévu
Les menus et actions groupées de page sont désormais disponibles dans le lot actions et sélection. Le tableau multicolonnes sur tablette, la pagination par curseur/le défilement infini, le cache temps réel, les mutations optimistes et l'envoi effectif de fichiers ne font pas partie de ce lot. Les briques métier complémentaires de la matrice restent à traiter séparément.