/**
 * Déclaration des tours. Chaque point s'ancre sur un attribut
 * `data-tour="<anchor>"` posé sur l'élément cible — jamais sur un sélecteur
 * CSS, qu'un refactor de style casserait en silence.
 *
 * Interdits en v1 : /content/* et /backlink/overview (écran « En construction »
 * en production), et tout élément situé dans une Dialog modale — le repo a déjà
 * rencontré des conflits entre overlays et `body { pointer-events: none }`.
 */

export const TOUR_IDS = ["reservoir", "recherche", "planning"] as const;
export type TourId = (typeof TOUR_IDS)[number];

export type TourStep = {
  /** Valeur de l'attribut data-tour de l'élément à mettre en avant. */
  anchor: string;
  /** Suffixe de clé i18n sous Tour.<tourId>.<key>. */
  key: string;
  /**
   * L'ancre est un en-tête de tableau que la bande de pilotage collante de sa
   * page (`sticky top-0 z-20`) RECOUVRE dès que le point précédent a fait
   * défiler le tableau — driver.js gare le haut du tableau sous la bande, puis
   * juge l'en-tête « déjà visible » (`top >= 0`) et ne défile plus.
   *
   * La découpe de l'overlay tombe alors au bon endroit mais ne révèle que le
   * fond de la bande : un rectangle sombre, sous une bulle qui décrit ce qui
   * est masqué. driver.css ne donne aucun ordre de peinture à l'élément mis en
   * avant, d'où le remède — le remonter AU-DESSUS de la bande le temps du
   * point (voir `TOUR_LIFT_ATTRIBUTE` dans `./plan`).
   *
   * Ce drapeau décrit une SITUATION, pas un réglage d'affichage : le mettre à
   * vrai sur une ancre qui n'est pas sous une bande est sans effet visible,
   * mais le laisser à faux sur une ancre qui l'est rend le point illisible.
   * Les ancres qui vivent DANS la bande (`keywords-import`, `keywords-sync`)
   * n'en ont pas besoin : elles restent épinglées, donc visibles.
   *
   * Il ne convient PAS à une ancre aussi large que la bande. `planning-dispatch`
   * vise une ligne de tableau pleine largeur : la remonter la rend lisible, mais
   * son fond opaque tranche alors la barre d'outils en deux sur toute sa
   * largeur — on échange un masquage contre un autre, plus laid. Vérifié en
   * navigateur le 2026-07-31 ; ce point relève du correctif par défilement,
   * resté en dette.
   */
  underStickyBand?: true;
};

export type TourDef = {
  id: TourId;
  /** Route exacte de rattachement. */
  route: string;
  steps: readonly TourStep[];
};

export const TOURS: readonly TourDef[] = [
  {
    id: "reservoir",
    route: "/keywords/reservoir",
    steps: [
      { anchor: "reservoir-table", key: "whatIsIt" },
      { anchor: "keywords-import", key: "import" },
      { anchor: "keywords-sync", key: "sync" },
      {
        anchor: "reservoir-sources",
        key: "sources",
        underStickyBand: true,
      },
    ],
  },
  {
    id: "recherche",
    route: "/keywords/recherche",
    steps: [
      { anchor: "research-table", key: "whatIsIt" },
      {
        anchor: "research-gsc-columns",
        key: "gscColumns",
        underStickyBand: true,
      },
      { anchor: "research-matrix", key: "targeting" },
    ],
  },
  {
    id: "planning",
    route: "/keywords/planning",
    steps: [
      { anchor: "planning-table", key: "whatIsIt" },
      {
        anchor: "planning-readiness",
        key: "readiness",
        underStickyBand: true,
      },
      { anchor: "planning-dispatch", key: "dispatch" },
    ],
  },
];

/** Correspondance EXACTE : un préfixe rattacherait un sous-écran (un détail,
 *  une modale routée) au tour de sa page parente. */
export function tourForRoute(pathname: string): TourDef | null {
  return TOURS.find((t) => t.route === pathname) ?? null;
}