SPB Git

Repository Public

UI_CONVENTIONS.md 6.3 KB

# SP Wallet iOS — conventions d'écran et de code

App native Swift 6 / SwiftUI (iOS 26+, iPhone et iPad). Aucune vue web. Cœur partagé : ../SPWalletCore (voir son docs/CONVENTIONS.md).

# Règles dures

  1. Aucune donnée inventée. Un écran affiche ce que le serveur a dit (ou un instantané daté). Pas de valeur par défaut qui ressemble à une vraie valeur, pas d'état de succès déduit par l'app. Un solde illisible s'affiche « indisponible », jamais 0.
  2. Seul finalized est un succès pour une transaction ; un pont / un échange entre réseaux n'est terminé que lorsque sa section le dit (isComplete, swapCompletion()), jamais à la diffusion de la transaction source.
  3. Approbation = clé d'accès liée à l'objet. Tout parcours qui signe passe par une fonction prepare… du Core (qui vérifie défi == SHA-256(objet canonique) et objet == demande), affiche l'objet vérifié EN ENTIER (aucune troncature d'adresse, de montant, de limite, de contrat ; rien de replié ; rien d'animé), puis appelle approve… avec model.env.passkeys. La feuille de revue porte .interactiveDismissDisabled(). Si le Core lève ApprovalError.unsupported (le serveur de production ne renvoie pas encore l'objet), l'écran l'explique avec ErrorNotice et n'offre aucun contournement.
  4. Rien d'automatique : une cotation n'exécute rien ; un QR, un lien, un widget, Siri ne préparent ni n'approuvent rien.
  5. Aucun paramètre de risque par défaut : levier, budget, plafond par ordre, limite de perte, marchés, expiration sont saisis explicitement par le propriétaire (champ vide au départ, bouton désactivé tant qu'il manque une valeur).
  6. Modes toujours visibles : SIMULATION / PAPIER / RÉEL (et TESTNET / MAINNET) par Pill + texte, jamais par la couleur seule. Un chiffre de simulation ou de papier porte son étiquette à côté de lui.
  7. Arrêter doit toujours être possible : pause, arrêt, révocation, arrêt d'urgence ne demandent jamais plus qu'une confirmation.
  8. Hors ligne : model.canOperate == false désactive toute opération ; les lectures retombent sur model.env.cache avec FreshnessBanner() en tête d'écran. Jamais d'opération financière hors ligne.
  9. Les refus du serveur (limites, verrous, juridiction, signataire) sont montrés tels quels : ErrorNotice(error:) (code + phrase).
  10. Journaux : Logger avec privacy: .public uniquement pour des codes ; jamais d'adresse, de montant, de jeton, de secret.

Environnement des contenus présentés (plantage sinon) : feuilles, fullScreenCover, popovers, destinations de navigation (navigationDestination, NavigationLink { … }), cellules de Table, menus contextuels n'héritent pas de façon fiable des objets @Environment. Chaque contenu présenté se termine par .wallet(model) (définie dans Components/Theme.swift), ou reçoit ses modèles en paramètres. Un objet @Observable propre à un écran se passe TOUJOURS en paramètre (let flow: MonFlux), jamais par @Environment.

# Briques à réutiliser (ne pas recréer)

  • État : @Environment(AppModel.self) model (model.env : client, wallet, transfers, passkeys, cache, preferences ; model.networks/accounts/portfolio/activity/settings : Loaded<T> ; model.canOperate, model.currency, model.hideBalances, model.network(id), model.account(network)), @Environment(Router.self) router (router.go(.section), router.sheet). Les API de domaine se construisent à la demande : SwapAPI(model.env.client), etc.
  • Thème : Theme.*, .spCard(), .spPage(), .spEyebrow(), polices .spDisplay/.spTitle/.spHeadline/.spBody/.spCallout/.spFootnote/.spMono, boutons .buttonStyle(.spPrimary | .spSecondary | .spDestructive) (un seul primaire par écran).
  • Composants : Notice, Pill, FreshnessBanner, SecurityIndicator, EmptyState, ErrorNotice, FieldRow (mono + copiable pour adresses/hash), SectionHeader, AssetIcon, NetworkIcon, Masked (respecte « masquer les soldes »), AssetRow, TransactionRow, NetworkPicker, IntentReview (revue d'un Intent vérifié), ProposalTracker (suivi jusqu'à confirmation), QRCodeView, QRScannerSheet, JSONFields (détail serveur brut, étiqueté), ShareSheet, ExportFiles.
  • Format : Money.fiat/price/change/exact/brief/age/shortAddress. Money.exact partout où un montant sera approuvé ; Money.brief et shortAddress uniquement dans les listes.
  • Modèle d'un parcours : voir Features/Send/SendFlow.swift (@Observable modèle du parcours, clé d'idempotence stable par demande, étapes formulaire → revue → suivi, annulation de la clé d'accès sans erreur, réponse perdue → relire l'état au lieu de re-signer).

# Mise en page

iPhone d'abord (une main : action principale en bas, cibles ≥ 44 pt). iPad : mêmes blocs en grille ou Table quand horizontalSizeClass == .regular (voir HomeView, PortfolioView) ; menus contextuels ; pas de colonne unique étroite. Chaque section est une vue racine sans NavigationStack propre (elle est déjà dans celui de la coque) avec .navigationTitle. Graphiques : Swift Charts, axes discrets, étiquette de source/nature sous le graphique.

# Texte, accessibilité, tests

  • Textes d'interface en français (langue source) via String(localized:) / littéraux SwiftUI ; code et commentaires en anglais.
  • Tout contrôle utile aux tests porte un accessibilityIdentifier section.element (ne pas le poser sur un conteneur : il écrase les enfants).
  • En-tête obligatoire en tête de fichier (projet, File, Description, Author, Contact).
  • Tests unitaires (Swift Testing) dans Tests/<Feature>Tests.swift pour la logique de parcours (validation, comparaison, états).
  • Tests d'interface dans UITests/<Feature>UITests.swift, sur la pile jetable (../SPWalletCore/Scripts/dev-stack.sh up-fork, clés aléatoires, Base = fork local avec faux ETH, passkey logicielle) : helpers Stack.app(), signIn(app), go(app, "section"), shot("nom"). Jamais la production, jamais de fonds réels. Un seul simulateur par agent (SPWALLET_SIM).
  • Scripts/build.sh generate après tout ajout de fichier ; debug, test, uitest.
Files main
Menu

Theme