@pi-spi/app 0.0.0-stage → 1.2.0

package/src/core/router.tsx

@@ -0,0 +1,497 @@
+import {
+  CommonActions,
+  createNavigationContainerRef,
+  StackActions,
+  type ParamListBase,
+} from '@react-navigation/native';
+import { createContext, useContext, useEffect, type ReactElement, type ReactNode } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+
+import { AppBar, Scaffold } from '../shared/material/scaffold';
+import type { BlocBase } from './bloc';
+import { Di } from './di';
+import { Logger } from './logger';
+import { useTheme } from './theme';
+import { ValueNotifier } from './value_notifier';
+import type { OverlayEntry, OverlayKind } from '../shared/material/overlays';
+
+/** État de la route affichée, équivalent de `GoRouterState`. */
+export type RouteState = {
+  /** Emplacement complet demandé (ex. `/transaction/cancel/ABC`). */
+  location: string;
+  /** Modèle de la route correspondante (ex. `/transaction/cancel/:id`). */
+  path: string;
+  pathParameters: Record<string, string>;
+  queryParameters: Record<string, string>;
+  /** Objet passé à la navigation (`params` des helpers d'{@link AppRouter}), comme `state.extra`. */
+  extra?: unknown;
+};
+
+/** Accès aux blocs globaux du SDK depuis un redirect (≈ `context.read<B>()`). */
+export type RedirectContext = {
+  read<B extends BlocBase<any>>(type: abstract new (...args: any[]) => B): B;
+};
+
+/**
+ * Définition d'une route, équivalent d'une `GoRoute` :
+ * - `page` : plein écran, transition horizontale (`Page` en Flutter) ;
+ * - `dialog` : par-dessus l'écran précédent, 50 px sous le haut, coins
+ *   supérieurs arrondis, fond assombri (`DialogPage` en Flutter).
+ */
+export type RouteDef = {
+  path: string;
+  kind: 'page' | 'dialog';
+  builder: (state: RouteState) => ReactElement;
+  /** Retourne une autre route vers laquelle rediriger, ou `null` pour afficher celle-ci. */
+  redirect?: (state: RouteState, context: RedirectContext) => Promise<string | null> | string | null;
+};
+
+type ScreenParams = {
+  location: string;
+  pathParameters: Record<string, string>;
+  queryParameters: Record<string, string>;
+  extraId?: string;
+  resultId?: string;
+};
+
+const NOT_FOUND = '*';
+const MAX_REDIRECTS = 5;
+
+/**
+ * Routeur d'une instance du SDK (équivalent du `GoRouter` créé par
+ * `AppRouter.routes()`) : un `navigationRef` propre, donc aucune collision
+ * si le SDK est ouvert plusieurs fois dans la vie de l'application hôte.
+ */
+export class SdkRouter {
+  static readonly logger = new Logger();
+
+  readonly navigationRef = createNavigationContainerRef<ParamListBase>();
+
+  /** Route initiale, après résolution des redirects (voir {@link resolveInitial}). */
+  initialState?: { name: string; params: ScreenParams };
+
+  /** Accès aux blocs globaux pour les redirects, fourni par `PiSpiSdkEntry`. */
+  redirectContext: RedirectContext = {
+    read: () => {
+      throw new Error('SdkRouter.redirectContext non initialisé.');
+    },
+  };
+
+  /** Feuilles du bas et dialogues ouverts (voir `shared/material/overlays.tsx`), du plus ancien au plus récent. */
+  readonly overlays = new ValueNotifier<OverlayEntry[]>([]);
+
+  private readonly extras = new Map<string, unknown>();
+  private readonly results = new Map<string, (value: unknown) => void>();
+  private sequence = 0;
+
+  constructor(
+    readonly definitions: readonly RouteDef[],
+    readonly initialLocation: string,
+  ) {}
+
+  /** Toutes les routes déclarées, plus la page « introuvable ». */
+  get screens(): readonly RouteDef[] {
+    return [...this.definitions, notFoundRoute];
+  }
+
+  definition(path: string): RouteDef {
+    return this.screens.find((d) => d.path === path) ?? notFoundRoute;
+  }
+
+  /** Trouve la route correspondant à [location] (les routes sans paramètre sont prioritaires). */
+  match(location: string, extra?: unknown): { def: RouteDef; state: RouteState } {
+    const [pathPart, queryPart] = location.split('?');
+    const queryParameters: Record<string, string> = {};
+    if (queryPart) {
+      for (const pair of queryPart.split('&')) {
+        const [k, v = ''] = pair.split('=');
+        if (k) queryParameters[decodeURIComponent(k)] = decodeURIComponent(v);
+      }
+    }
+    const segments = splitPath(pathPart);
+    let best: { def: RouteDef; params: Record<string, string>; score: number } | undefined;
+    for (const def of this.definitions) {
+      const pattern = splitPath(def.path);
+      if (pattern.length !== segments.length) continue;
+      const params: Record<string, string> = {};
+      let score = 0;
+      let ok = true;
+      for (let i = 0; i < pattern.length && ok; i++) {
+        if (pattern[i].startsWith(':')) {
+          params[pattern[i].substring(1)] = decodeURIComponent(segments[i]);
+        } else if (pattern[i] === segments[i]) {
+          score++;
+        } else {
+          ok = false;
+        }
+      }
+      if (ok && (!best || score > best.score)) best = { def, params, score };
+    }
+    const def = best?.def ?? notFoundRoute;
+    return {
+      def,
+      state: { location, path: def.path, pathParameters: best?.params ?? {}, queryParameters, extra },
+    };
+  }
+
+  /** Applique les redirects de la route demandée (et des suivantes), comme GoRouter. */
+  async resolve(location: string, extra?: unknown): Promise<{ def: RouteDef; state: RouteState }> {
+    let current = this.match(location, extra);
+    for (let i = 0; i < MAX_REDIRECTS && current.def.redirect; i++) {
+      const target = await current.def.redirect(current.state, this.redirectContext);
+      if (target == null || target === current.state.location) break;
+      SdkRouter.logger.i(`Redirection ${current.state.location} -> ${target}`);
+      current = this.match(target);
+    }
+    return current;
+  }
+
+  /** Résout la route initiale avant le premier affichage du navigateur. */
+  async resolveInitial(): Promise<void> {
+    SdkRouter.logger.i(`Route initiale ${this.initialLocation}`);
+    const resolved = await this.resolve(this.initialLocation);
+    this.initialState = { name: resolved.def.path, params: this.toParams(resolved.state) };
+  }
+
+  /** `extra` passé à la route affichée par l'écran de [params]. */
+  extraOf(params: ScreenParams | undefined): unknown {
+    return params?.extraId != null ? this.extras.get(params.extraId) : undefined;
+  }
+
+  /** Appelé au démontage d'un écran : libère son `extra` et résout un `push` encore en attente. */
+  release(params: ScreenParams | undefined): void {
+    if (params?.extraId != null) this.extras.delete(params.extraId);
+    if (params?.resultId != null) this.completeResult(params.resultId, undefined);
+  }
+
+  /** Empile [location] ; la promesse est résolue avec la valeur passée à `pop` (≈ `context.push`). */
+  async push<T>(location: string, extra?: unknown): Promise<T | undefined> {
+    const resolved = await this.resolve(location, extra);
+    const resultId = this.nextId();
+    const result = new Promise<T | undefined>((resolve) => {
+      this.results.set(resultId, resolve as (value: unknown) => void);
+    });
+    this.navigationRef.dispatch(
+      StackActions.push(resolved.def.path, { ...this.toParams(resolved.state), resultId }),
+    );
+    return result;
+  }
+
+  /** Remplace toute la pile par [location] (≈ `context.go`). */
+  async go(location: string, extra?: unknown): Promise<void> {
+    const resolved = await this.resolve(location, extra);
+    this.navigationRef.dispatch(
+      CommonActions.reset({ index: 0, routes: [{ name: resolved.def.path, params: this.toParams(resolved.state) }] }),
+    );
+  }
+
+  /** Remplace l'écran courant par [location] (≈ `context.pushReplacement`). */
+  async replace(location: string, extra?: unknown): Promise<void> {
+    const resolved = await this.resolve(location, extra);
+    this.navigationRef.dispatch(StackActions.replace(resolved.def.path, this.toParams(resolved.state)));
+  }
+
+  /** Ouvre une feuille ou un dialogue ; résolu à sa fermeture avec la valeur passée à `pop`. */
+  showOverlay<T>(
+    kind: OverlayKind,
+    builder: () => ReactNode,
+    barrierDismissible: boolean,
+    options: { themed?: boolean } = {},
+  ): Promise<T | undefined> {
+    return new Promise<T | undefined>((resolve) => {
+      const entry: OverlayEntry = {
+        id: Number(this.nextId()),
+        kind,
+        builder,
+        themed: options.themed ?? false,
+        barrierDismissible,
+        canPop: true,
+        resolve: resolve as (value: unknown) => void,
+      };
+      this.overlays.value = [...this.overlays.value, entry];
+    });
+  }
+
+  isTopOverlay(entry: OverlayEntry): boolean {
+    const list = this.overlays.value;
+    return list[list.length - 1] === entry;
+  }
+
+  /**
+   * Ferme la feuille/le dialogue le plus récent s'il y en a un, sinon
+   * l'écran courant, en transmettant [value] à celui qui l'a ouvert
+   * (≈ `context.pop`).
+   */
+  pop(value?: unknown): void {
+    const overlays = this.overlays.value;
+    if (overlays.length > 0) {
+      const top = overlays[overlays.length - 1];
+      this.overlays.value = overlays.slice(0, -1);
+      top.resolve(value);
+      return;
+    }
+    const params = this.navigationRef.getCurrentRoute()?.params as ScreenParams | undefined;
+    if (params?.resultId != null) this.completeResult(params.resultId, value);
+    if (this.navigationRef.canGoBack()) this.navigationRef.goBack();
+  }
+
+  canPop(): boolean {
+    return this.overlays.value.length > 0 || (this.navigationRef.isReady() && this.navigationRef.canGoBack());
+  }
+
+  currentRoute(): string {
+    const params = this.navigationRef.getCurrentRoute()?.params as ScreenParams | undefined;
+    return params?.location ?? this.initialLocation;
+  }
+
+  private toParams(state: RouteState): ScreenParams {
+    let extraId: string | undefined;
+    if (state.extra !== undefined) {
+      extraId = this.nextId();
+      this.extras.set(extraId, state.extra);
+    }
+    return {
+      location: state.location,
+      pathParameters: state.pathParameters,
+      queryParameters: state.queryParameters,
+      extraId,
+    };
+  }
+
+  private completeResult(resultId: string, value: unknown): void {
+    const resolve = this.results.get(resultId);
+    if (resolve) {
+      this.results.delete(resultId);
+      resolve(value);
+    }
+  }
+
+  private nextId(): string {
+    this.sequence += 1;
+    return String(this.sequence);
+  }
+}
+
+function splitPath(path: string): string[] {
+  return path.split('/').filter((s) => s.length > 0);
+}
+
+export const SdkRouterContext = createContext<SdkRouter | null>(null);
+
+/** Routeur de l'instance courante du SDK (≈ `GoRouter.of(context)`). */
+export function useAppRouter(): SdkRouter {
+  const router = useContext(SdkRouterContext);
+  if (!router) throw new Error('useAppRouter() doit être utilisé dans un écran du SDK PI-SPI.');
+  return router;
+}
+
+const RouteStateContext = createContext<RouteState | null>(null);
+
+/** État de la route de l'écran courant (≈ `GoRouterState.of(context)`). */
+export function useRouteState(): RouteState {
+  const state = useContext(RouteStateContext);
+  if (!state) throw new Error('useRouteState() doit être utilisé dans un écran du SDK PI-SPI.');
+  return state;
+}
+
+/**
+ * Écran générique du navigateur : retrouve la {@link RouteDef} de la route
+ * affichée, construit son contenu et l'habille en `Page` ou `DialogPage`.
+ */
+export function RouteScreen({ route }: { route: { name: string; params?: object } }) {
+  const router = useAppRouter();
+  const params = route.params as ScreenParams | undefined;
+  const def = router.definition(route.name);
+  const state: RouteState = {
+    location: params?.location ?? route.name,
+    path: def.path,
+    pathParameters: params?.pathParameters ?? {},
+    queryParameters: params?.queryParameters ?? {},
+    extra: router.extraOf(params),
+  };
+
+  useEffect(() => () => router.release(params), [router, params]);
+
+  const content = <RouteStateContext.Provider value={state}>{def.builder(state)}</RouteStateContext.Provider>;
+  return def.kind === 'dialog' ? <DialogFrame>{content}</DialogFrame> : content;
+}
+
+/** Habillage d'une `DialogPage` : 50 px sous le haut, coins supérieurs arrondis, fond assombri. */
+function DialogFrame({ children }: { children: ReactElement }) {
+  const theme = useTheme();
+  return (
+    <View style={styles.barrier}>
+      <View style={[styles.dialog, { backgroundColor: theme.scaffoldBackgroundColor }]}>{children}</View>
+    </View>
+  );
+}
+
+/** Page affichée si aucune page trouvée */
+export function NotFoundPage() {
+  const router = useAppRouter();
+  const theme = useTheme();
+  return (
+    <Scaffold
+      appBar={
+        <AppBar
+          onBack={() => {
+            if (router.canPop()) router.pop();
+            else void Di.config.close();
+          }}
+        />
+      }
+    >
+      <View style={styles.center}>
+        <Text style={theme.textTheme.bodyLarge}>A venir</Text>
+      </View>
+    </Scaffold>
+  );
+}
+
+const notFoundRoute: RouteDef = { path: NOT_FOUND, kind: 'page', builder: () => <NotFoundPage /> };
+
+/**
+ * Définit la logique de routage / navigation entre les différentes pages
+ * du SDK. Contrairement à l'application de référence, ce router ne
+ * possède pas de routes de connexion/sécurité (login, PIN, permissions) :
+ * l'application hôte gère l'authentification avant d'afficher le SDK.
+ */
+export class AppRouter {
+  static readonly logger = new Logger();
+
+  // Liste des routes du SDK
+  // Alias
+  static readonly alias = '/alias';
+  static readonly aliasMBNOcreate = '/alias/mbno';
+  static readonly aliasMBNOconfirm = '/alias/mbno/confirm';
+  static readonly aliasClaimDetails = '/alias/revendications/:id';
+
+  // Home
+  static readonly home = '/home';
+
+  // Première utilisation : introduction puis demande de permission contacts
+  static readonly introduction = '/introduction';
+  static readonly permissions = '/permissions';
+
+  // Sélection de compte (client à plusieurs comptes) : affichée à chaque
+  // ouverture du SDK, avant l'accueil.
+  static readonly selectAccount = '/select-account';
+
+  // Contacts
+  static readonly contactCreate = '/contact';
+  static readonly contactSelect = '/contact/select';
+
+  // Transactions
+  static readonly transactionSend = '/transaction/send_now';
+  static readonly transactionSendDetails = '/transaction/send_now/:id';
+  static readonly transactionSendDetailsCategorie = '/transaction/send_now/details/categorie';
+  static readonly transactionReceive = '/transaction/receive_now';
+  static readonly transactionReceiveDetails = '/transaction/receive_now/:id';
+  static readonly transactionFormPage = '/transaction-form-fields';
+  static readonly transactionFormVerification = '/transaction-form-verification';
+  static readonly transactionFormSchedule = '/transaction-form-schedule';
+  static readonly transactionSearch = '/transaction-search';
+  static readonly transactionSearchFilters = '/transaction-search/filters';
+  static readonly transactionCancel = '/transaction/cancel/:id';
+  static readonly transactionSplitPayment = '/transaction/split-payment';
+  static readonly transactionSplitPaymentTx = '/transaction/split-payment/transaction';
+  static readonly transactionSplitPaymentRepartition = '/transaction/split-payment/repartition';
+
+  // Subscriptions
+  static readonly subscriptionList = '/subscriptions/list';
+  static readonly subscriptionDetails = '/subscriptions/details';
+  static readonly subscriptionSchedule = '/transaction/schedule';
+  static readonly subscriptionSubscribe = '/subscriptions/create';
+
+  // QR Code
+  static readonly qrcodeScan = '/qrcode/scan';
+  static readonly qrcodeShow = '/qrcode/show';
+  static readonly qrcodeTransactionSend = '/qrcode/send';
+
+  // Categories
+  static readonly categories = '/categories';
+  static readonly categoriesSelect = '/categories/select';
+  static readonly categoriesAdd = '/categories/add';
+  static readonly categoriesEdit = '/categories/edit';
+
+  // Profile
+  static readonly profile = '/profile';
+  static readonly profileCompte = '/profile/compte';
+  static readonly profileParametre = '/profile/parametre';
+  static readonly profileContacts = '/profile/contacts';
+  static readonly profileParametreTheme = '/profile/parametre/theme';
+  static readonly profileParametreNotifications = '/profile/parametre/notifications';
+  static readonly profileParametreNotificationsSon = '/profile/parametre/notifications/son';
+  static readonly profileHelpCenter = '/profile/help-center';
+  static readonly loginCgu = '/profile/cgu';
+  static readonly loginPoc = '/profile/poc';
+
+  // Notifications
+  static readonly notifications = '/notifications';
+
+  /** Constructeur privé : la classe n'est jamais instanciée. */
+  private constructor() {}
+
+  /**
+   * Méthode qui retourne la configuration des routes. Un nouveau routeur
+   * (et un nouveau `navigationRef`) est créé à chaque appel : si le SDK est
+   * ouvert plusieurs fois dans la vie de l'application hôte, chaque
+   * instance a son propre navigateur, sans collision.
+   *
+   * [definitions] : les routes des modules (voir `routes.tsx`, séparé de
+   * ce fichier pour que le routeur n'importe aucun écran — les écrans
+   * importent le routeur, l'inverse créerait des cycles d'import).
+   */
+  static routes(initial: string, definitions: readonly RouteDef[]): SdkRouter {
+    AppRouter.logger.i(`Route initiale ${initial}`);
+    return new SdkRouter(definitions, initial);
+  }
+
+  /**
+   * Route à afficher une fois l'onboarding (introduction/permissions)
+   * terminé ou sauté : la sélection de compte si le client en a
+   * plusieurs, sinon directement l'accueil (avec `Di.activeCompte` déjà
+   * correctement initialisé par `Di.init`).
+   */
+  static postOnboardingRoute(): string {
+    return Di.config.user.comptes.length > 1 ? AppRouter.selectAccount : AppRouter.home;
+  }
+
+  /** Permet de naviguer entre les pages (empile la page, comme en Flutter). */
+  static go(router: SdkRouter, route: string, options: { params?: unknown } = {}): void {
+    void router.push(route, options.params);
+  }
+
+  /** Permet de naviguer entre les pages, en attendant la valeur de retour de la page ouverte. */
+  static push<T>(router: SdkRouter, route: string, options: { params?: unknown } = {}): Promise<T | undefined> {
+    return router.push<T>(route, options.params);
+  }
+
+  /** Permet de naviguer entre les pages, en remplaçant la page courante (l'accueil remplace toute la pile). */
+  static pushReplacement(router: SdkRouter, route: string, options: { params?: unknown } = {}): void {
+    if ([AppRouter.home].includes(route)) {
+      void router.go(route, options.params);
+    } else {
+      void router.replace(route, options.params);
+    }
+  }
+
+  /** Fermer un dialogue */
+  static pop(router: SdkRouter, options: { value?: unknown } = {}): void {
+    router.pop(options.value);
+  }
+
+  static canPop(router: SdkRouter): boolean {
+    return router.canPop();
+  }
+
+  static currentRoute(router: SdkRouter): string {
+    return router.currentRoute();
+  }
+}
+
+const styles = StyleSheet.create({
+  barrier: { flex: 1, backgroundColor: 'rgba(0,0,0,0.4)', paddingTop: 50 },
+  dialog: { flex: 1, borderTopLeftRadius: 15, borderTopRightRadius: 15, overflow: 'hidden' },
+  center: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+});