Repository Public
1<!--2SP Wallet iOS3File: docs/UI_CONVENTIONS.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# SP Wallet iOS — conventions d'écran et de code89App native Swift 6 / SwiftUI (iOS 26+, iPhone et iPad). **Aucune vue web.** Cœur partagé : `../SPWalletCore` (voir son `docs/CONVENTIONS.md`).1011## Règles dures12131. **Aucune donnée inventée.** Un écran affiche ce que le serveur a dit (ou un instantané daté). Pas de valeur par défaut qui14 ressemble à une vraie valeur, pas d'état de succès déduit par l'app. Un solde illisible s'affiche « indisponible », jamais 0.152. **Seul `finalized` est un succès** pour une transaction ; un pont / un échange entre réseaux n'est terminé que lorsque sa section16 le dit (`isComplete`, `swapCompletion()`), jamais à la diffusion de la transaction source.173. **Approbation = clé d'accès liée à l'objet.** Tout parcours qui signe passe par une fonction `prepare…` du Core (qui vérifie18 défi == SHA-256(objet canonique) et objet == demande), affiche l'objet vérifié EN ENTIER (aucune troncature d'adresse, de montant,19 de limite, de contrat ; rien de replié ; rien d'animé), puis appelle `approve…` avec `model.env.passkeys`. La feuille de revue20 porte `.interactiveDismissDisabled()`. Si le Core lève `ApprovalError.unsupported` (le serveur de production ne renvoie pas encore21 l'objet), l'écran l'explique avec `ErrorNotice` et n'offre aucun contournement.224. **Rien d'automatique** : une cotation n'exécute rien ; un QR, un lien, un widget, Siri ne préparent ni n'approuvent rien.235. **Aucun paramètre de risque par défaut** : levier, budget, plafond par ordre, limite de perte, marchés, expiration sont saisis24 explicitement par le propriétaire (champ vide au départ, bouton désactivé tant qu'il manque une valeur).256. **Modes toujours visibles** : SIMULATION / PAPIER / RÉEL (et TESTNET / MAINNET) par `Pill` + texte, jamais par la couleur seule.26 Un chiffre de simulation ou de papier porte son étiquette à côté de lui.277. **Arrêter doit toujours être possible** : pause, arrêt, révocation, arrêt d'urgence ne demandent jamais plus qu'une confirmation.288. **Hors ligne** : `model.canOperate == false` désactive toute opération ; les lectures retombent sur `model.env.cache` avec29 `FreshnessBanner()` en tête d'écran. Jamais d'opération financière hors ligne.309. Les refus du serveur (limites, verrous, juridiction, signataire) sont montrés tels quels : `ErrorNotice(error:)` (code + phrase).3110. Journaux : `Logger` avec `privacy: .public` uniquement pour des codes ; jamais d'adresse, de montant, de jeton, de secret.3233**Environnement des contenus présentés (plantage sinon)** : feuilles, `fullScreenCover`, popovers, destinations de navigation34(`navigationDestination`, `NavigationLink { … }`), cellules de `Table`, menus contextuels n'héritent pas de façon fiable des objets35`@Environment`. Chaque contenu présenté se termine par **`.wallet(model)`** (définie dans `Components/Theme.swift`), ou reçoit ses36modèles en paramètres. Un objet `@Observable` propre à un écran se passe TOUJOURS en paramètre (`let flow: MonFlux`), jamais par37`@Environment`.3839## Briques à réutiliser (ne pas recréer)4041- État : `@Environment(AppModel.self) model` (`model.env` : `client`, `wallet`, `transfers`, `passkeys`, `cache`, `preferences` ;42 `model.networks/accounts/portfolio/activity/settings` : `Loaded<T>` ; `model.canOperate`, `model.currency`, `model.hideBalances`,43 `model.network(id)`, `model.account(network)`), `@Environment(Router.self) router` (`router.go(.section)`, `router.sheet`).44 Les API de domaine se construisent à la demande : `SwapAPI(model.env.client)`, etc.45- Thème : `Theme.*`, `.spCard()`, `.spPage()`, `.spEyebrow()`, polices `.spDisplay/.spTitle/.spHeadline/.spBody/.spCallout/.spFootnote/.spMono`,46 boutons `.buttonStyle(.spPrimary | .spSecondary | .spDestructive)` (un seul primaire par écran).47- Composants : `Notice`, `Pill`, `FreshnessBanner`, `SecurityIndicator`, `EmptyState`, `ErrorNotice`, `FieldRow` (mono + copiable pour48 adresses/hash), `SectionHeader`, `AssetIcon`, `NetworkIcon`, `Masked` (respecte « masquer les soldes »), `AssetRow`, `TransactionRow`,49 `NetworkPicker`, `IntentReview` (revue d'un `Intent` vérifié), `ProposalTracker` (suivi jusqu'à confirmation), `QRCodeView`,50 `QRScannerSheet`, `JSONFields` (détail serveur brut, étiqueté), `ShareSheet`, `ExportFiles`.51- Format : `Money.fiat/price/change/exact/brief/age/shortAddress`. `Money.exact` partout où un montant sera approuvé ;52 `Money.brief` et `shortAddress` uniquement dans les listes.53- Modèle d'un parcours : voir `Features/Send/SendFlow.swift` (`@Observable` modèle du parcours, clé d'idempotence stable par demande,54 étapes formulaire → revue → suivi, annulation de la clé d'accès sans erreur, réponse perdue → relire l'état au lieu de re-signer).5556## Mise en page5758iPhone d'abord (une main : action principale en bas, cibles ≥ 44 pt). iPad : mêmes blocs en grille ou `Table` quand59`horizontalSizeClass == .regular` (voir `HomeView`, `PortfolioView`) ; menus contextuels ; pas de colonne unique étroite.60Chaque section est une vue racine sans `NavigationStack` propre (elle est déjà dans celui de la coque) avec `.navigationTitle`.61Graphiques : Swift Charts, axes discrets, étiquette de source/nature sous le graphique.6263## Texte, accessibilité, tests6465- Textes d'interface en français (langue source) via `String(localized:)` / littéraux SwiftUI ; code et commentaires en anglais.66- Tout contrôle utile aux tests porte un `accessibilityIdentifier` `section.element` (ne pas le poser sur un conteneur : il écrase les enfants).67- En-tête obligatoire en tête de fichier (projet, File, Description, Author, Contact).68- Tests unitaires (Swift Testing) dans `Tests/<Feature>Tests.swift` pour la logique de parcours (validation, comparaison, états).69- Tests d'interface dans `UITests/<Feature>UITests.swift`, sur la pile jetable (`../SPWalletCore/Scripts/dev-stack.sh up-fork`, clés70 aléatoires, Base = fork local avec faux ETH, passkey logicielle) : helpers `Stack.app()`, `signIn(app)`, `go(app, "section")`, `shot("nom")`.71 **Jamais la production, jamais de fonds réels.** Un seul simulateur par agent (`SPWALLET_SIM`).72- `Scripts/build.sh generate` après tout ajout de fichier ; `debug`, `test`, `uitest`.73