@cat-factory/app 0.196.1 → 0.198.0

package/app/utils/tutorial.ts

@@ -0,0 +1,246 @@
+import type { NavGates } from '~/modular/nav-contributions'
+
+/**
+ * In-app tutorial tours: the pure data model + geometry, shared by the tour catalog
+ * (`modular/tutorial-tours.ts`), the tutorial store, and the coach-mark overlay
+ * (`components/tutorial/TutorialOverlay.vue`).
+ *
+ * A tour is DATA, not components: an ordered list of steps, each pointing at an existing
+ * on-screen control by its `data-testid` and carrying i18n keys for what to tell the user.
+ * That keeps tours declarative (a consumer deployment contributes its own through the
+ * `tutorialTours` slot via `registerAppModule`, exactly like nav items) and keeps the whole
+ * runtime — anchor tracking, tooltip placement, advance handling — in ONE overlay component
+ * that every tour shares.
+ */
+
+/** How a step advances to the next one. */
+export type TutorialAdvance =
+  /** The user reads and presses the tooltip's Next button (the default). */
+  | 'next'
+  /**
+   * The user clicks the highlighted control itself — the "now click this" steps. The
+   * tooltip shows a click hint instead of a Next button, so the app reacts to the real
+   * click (opening the real modal, creating the real task) and the tour follows along.
+   */
+  | 'target-click'
+
+/** Preferred tooltip side relative to the anchor; the overlay falls back when it can't fit. */
+export type TutorialPlacement = 'top' | 'bottom' | 'left' | 'right'
+
+export interface TutorialStep {
+  /** Stable id, unique within the tour (progress display + specs key off it). */
+  id: string
+  /**
+   * `data-testid` of the control this step points at. Absent = a centered card (intro /
+   * wrap-up steps). Reusing the e2e anchor vocabulary is deliberate: those ids are already
+   * the stable, behaviour-neutral way to name a control, and a tour stop is the same kind
+   * of consumer as a spec.
+   *
+   * A target names a KIND of control, not one instance: where several are on screen (one
+   * `task-card` per task, one `frame-add-task` per service) the first VISIBLE match wins,
+   * which may not be the one the user just produced. That is accepted rather than worked
+   * around — a tour teaches an affordance, and every match demonstrates the same one — so
+   * step copy must read correctly against any of them ("this is a task card", not "this is
+   * the task you just made").
+   */
+  target?: string
+  /**
+   * Fallback `data-testid`s tried in order when {@link target} is absent from the DOM —
+   * for controls that render under a different id in some states (e.g. a frame's add-task
+   * button on an empty frame).
+   */
+  altTargets?: readonly string[]
+  titleKey: string
+  bodyKey: string
+  /**
+   * Interpolation values for {@link bodyKey}'s `{named}` placeholders.
+   *
+   * The reason this exists rather than the value living in the catalogs: a step that names
+   * something FIXED and untranslatable — the sample repository a tour tells you to search
+   * for — would otherwise be spelled out in `en.json` and copied into nine other locales,
+   * where it reads as prose to translate and drifts the moment the value changes. Declared
+   * here it is written once, in code, beside the tour that needs it.
+   *
+   * Prose still belongs in the catalog: this is for proper nouns and code-shaped literals,
+   * the same split `frontend/app/README.md` states for inline placeholders in components.
+   */
+  bodyParams?: Record<string, string | number>
+  placement?: TutorialPlacement
+  /** Defaults to `'next'`. */
+  advanceOn?: TutorialAdvance
+  /**
+   * How long the overlay waits for the target to appear before SKIPPING the step
+   * (ms, default {@link DEFAULT_TARGET_WAIT_MS}). A missing anchor is expected, not an
+   * error: the control may be RBAC-hidden, tier-hidden, or simply not part of this
+   * deployment, and a tour must degrade to the steps that do apply. Steps whose target
+   * only appears after the previous step's click (inside a just-opened modal) may need a
+   * longer wait.
+   */
+  waitForTargetMs?: number
+  /**
+   * Applicability gate over the same reactive {@link NavGates} the tour's own `when` reads.
+   * A step this rejects is DROPPED from the tour before it runs; absent = always included.
+   *
+   * Deliberately distinct from the anchor skip above, because the two are different facts
+   * and only one of them is a defect in the tour. A skip means "this step's control should
+   * be here and isn't", which is what the final card reports as an abridged walkthrough. A
+   * `when` says "this branch of the flow is not what this board is doing" — a run parked on
+   * a decision has no approval gate to point at, and vice versa. Rendering the second as
+   * the first would tell a user who saw exactly the right walkthrough that they missed
+   * half of it, every single time.
+   *
+   * Use it only for a step whose ABSENCE is expected on a legitimate board; an anchor that
+   * merely might be slow keeps the wait budget instead.
+   */
+  when?: (gates: NavGates) => boolean
+}
+
+export interface TutorialTour {
+  /** Stable id; completion is persisted against it, so renaming one resets its state. */
+  id: string
+  titleKey: string
+  descriptionKey: string
+  icon?: string
+  /** Sort key in the tour list; ties break on `id` so the order is deterministic. */
+  order: number
+  /**
+   * Availability gate over the same reactive {@link NavGates} the nav catalog uses, so a
+   * tour about a surface the caller can't reach (no board write, no GitHub) never shows.
+   * Absent = always offered.
+   */
+  when?: (gates: NavGates) => boolean
+  steps: readonly TutorialStep[]
+}
+
+/** How long the overlay polls for a step's anchor before auto-skipping the step. */
+export const DEFAULT_TARGET_WAIT_MS = 4000
+
+/** How often the overlay re-queries / re-measures its anchor (canvas pans, panels open). */
+export const TARGET_TRACK_INTERVAL_MS = 150
+
+/** Deterministic tour-list order: `order`, then `id`. */
+export function sortTours(tours: readonly TutorialTour[]): TutorialTour[] {
+  return [...tours].sort((a, b) => a.order - b.order || a.id.localeCompare(b.id))
+}
+
+/**
+ * Resolve every tour against the gates: drop the tours whose own `when` rejects them, drop
+ * the steps whose `when` rejects them, and then drop a tour left with no steps at all.
+ *
+ * That last rule is what makes per-step gating safe to reach for. A tour whose every step
+ * is branch-specific (the parked-run tour: some boards have a decision waiting, some an
+ * approval) would otherwise survive its own `when` and open on an empty cursor — which the
+ * overlay ends immediately, so the user presses Start and nothing happens.
+ *
+ * Pure and total, so `navSlotFilter` (which runs inside a reactive computed, once per gate
+ * flip) stays a straight fold and the rules above are unit-testable without a Vue runtime.
+ */
+export function resolveTours(tours: readonly TutorialTour[], gates: NavGates): TutorialTour[] {
+  const out: TutorialTour[] = []
+  for (const tour of tours) {
+    if (tour.when && !tour.when(gates)) continue
+    const steps = tour.steps.filter((s) => (s.when ? s.when(gates) : true))
+    if (steps.length === 0) continue
+    // Reuse the original object when nothing was dropped: the prompt keys its list on the
+    // tour, and a fresh object per gate read would re-render it on every unrelated flip.
+    out.push(steps.length === tour.steps.length ? tour : { ...tour, steps })
+  }
+  return out
+}
+
+/** A DOMRect-shaped box, structurally typed so the geometry below is unit-testable. */
+export interface TutorialRect {
+  top: number
+  left: number
+  width: number
+  height: number
+}
+
+export interface CoachMarkLayout {
+  top: number
+  left: number
+  /** The side actually used (a preferred side that doesn't fit falls back), or centered. */
+  placement: TutorialPlacement | 'center'
+}
+
+/** Gap between the anchor's highlight ring and the tooltip card. */
+const TOOLTIP_GAP = 12
+/** Minimum distance the tooltip keeps from the viewport edges. */
+const VIEWPORT_MARGIN = 8
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), Math.max(min, max))
+
+/**
+ * Where the tooltip card goes for a given anchor. Pure geometry so the fallback rules are
+ * pinned by unit tests rather than eyeballed:
+ *
+ *  - no anchor ⇒ centered (intro / wrap-up steps);
+ *  - the preferred side is used when the card fits between anchor and viewport edge,
+ *    otherwise sides are tried `bottom → top → right → left`;
+ *  - nothing fits (tiny viewport) ⇒ the bottom position, clamped — partially covering the
+ *    anchor beats disappearing off-screen;
+ *  - the cross-axis is centered on the anchor and clamped to the viewport margin.
+ */
+export function computeCoachMarkLayout(
+  target: TutorialRect | null,
+  tooltip: { width: number; height: number },
+  viewport: { width: number; height: number },
+  preferred?: TutorialPlacement,
+): CoachMarkLayout {
+  if (!target) {
+    return {
+      top: Math.max(VIEWPORT_MARGIN, (viewport.height - tooltip.height) / 2),
+      left: Math.max(VIEWPORT_MARGIN, (viewport.width - tooltip.width) / 2),
+      placement: 'center',
+    }
+  }
+
+  const fits: Record<TutorialPlacement, boolean> = {
+    top: target.top - TOOLTIP_GAP - tooltip.height >= VIEWPORT_MARGIN,
+    bottom:
+      target.top + target.height + TOOLTIP_GAP + tooltip.height <=
+      viewport.height - VIEWPORT_MARGIN,
+    left: target.left - TOOLTIP_GAP - tooltip.width >= VIEWPORT_MARGIN,
+    right:
+      target.left + target.width + TOOLTIP_GAP + tooltip.width <= viewport.width - VIEWPORT_MARGIN,
+  }
+  const fallbackOrder: TutorialPlacement[] = ['bottom', 'top', 'right', 'left']
+  const placement =
+    preferred && fits[preferred]
+      ? preferred
+      : (fallbackOrder.find((side) => fits[side]) ?? 'bottom')
+
+  const centeredLeft = target.left + target.width / 2 - tooltip.width / 2
+  const centeredTop = target.top + target.height / 2 - tooltip.height / 2
+  const maxLeft = viewport.width - tooltip.width - VIEWPORT_MARGIN
+  const maxTop = viewport.height - tooltip.height - VIEWPORT_MARGIN
+
+  switch (placement) {
+    case 'top':
+      return {
+        top: target.top - TOOLTIP_GAP - tooltip.height,
+        left: clamp(centeredLeft, VIEWPORT_MARGIN, maxLeft),
+        placement,
+      }
+    case 'bottom':
+      return {
+        // Clamped: this is also the "nothing fits" fallback, where overlap is accepted.
+        top: clamp(target.top + target.height + TOOLTIP_GAP, VIEWPORT_MARGIN, maxTop),
+        left: clamp(centeredLeft, VIEWPORT_MARGIN, maxLeft),
+        placement,
+      }
+    case 'left':
+      return {
+        top: clamp(centeredTop, VIEWPORT_MARGIN, maxTop),
+        left: target.left - TOOLTIP_GAP - tooltip.width,
+        placement,
+      }
+    case 'right':
+      return {
+        top: clamp(centeredTop, VIEWPORT_MARGIN, maxTop),
+        left: target.left + target.width + TOOLTIP_GAP,
+        placement,
+      }
+  }
+}

package/i18n/locales/de.json

@@ -2132,7 +2132,8 @@
         "sandbox": "Sandbox öffnen",
         "shortcuts": "Tastenkürzel",
         "bugHunt": "Fehlerjagd",
-        "toggleUiMode": "Oberflächenmodus wechseln"
+        "toggleUiMode": "Oberflächenmodus wechseln",
+        "tutorial": "Tour starten"
       },
       "keywords": {
         "newPipeline": "pipeline agents chain",
@@ -2154,7 +2155,8 @@
         "sandbox": "sandbox prompt model test experiment judge fixture benchmark evaluate",
         "shortcuts": "keyboard shortcuts keys hotkeys cheatsheet help",
         "bugHunt": "fehler bug jagd triage backlog tracker nicht zugewiesen",
-        "toggleUiMode": "oberfläche modus einfach erweitert anzeigen ausblenden"
+        "toggleUiMode": "oberfläche modus einfach erweitert anzeigen ausblenden",
+        "tutorial": "tutorial tour einführung hilfe onboarding lernen grundlagen"
       }
     },
     "shortcuts": {
@@ -5906,5 +5908,210 @@
       "titleAny": "cat-factory mit Ihren Repositorys verbinden",
       "intro": "cat-factory funktioniert, indem es Pull Requests in Ihren Repositorys öffnet. Verbinden Sie Ihren Repository-Anbieter, um fortzufahren."
     }
+  },
+  "tutorial": {
+    "prompt": {
+      "title": "Eine kurze Tour machen?",
+      "intro": "Geführte Touren zeigen dir die App direkt auf diesem Bildschirm: Sie heben die echten Bedienelemente hervor und sagen dir, was du anklicken sollst.",
+      "start": "Starten",
+      "restart": "Wiederholen",
+      "completed": "Abgeschlossen",
+      "decline": "Nein danke",
+      "later": "Vielleicht später",
+      "empty": "Für deine Rolle auf diesem Board sind noch keine Touren verfügbar."
+    },
+    "overlay": {
+      "next": "Weiter",
+      "back": "Zurück",
+      "skip": "Tour beenden",
+      "done": "Fertig",
+      "progress": "Schritt {current} von {total}",
+      "ariaLabel": "Tutorial-Schritt",
+      "abridged": "1 Schritt wurde übersprungen: dieses Element gehört nicht zu diesem Board. | {count} Schritte wurden übersprungen: diese Elemente gehören nicht zu diesem Board.",
+      "searching": "Suche das hervorgehobene Element...",
+      "clickHint": "Klicke auf das hervorgehobene Element, um fortzufahren"
+    },
+    "tours": {
+      "boardBasics": {
+        "title": "Board-Grundlagen",
+        "description": "Orientierung: das Board, die Seitenleiste und die Befehlspalette.",
+        "steps": {
+          "welcome": {
+            "title": "Willkommen!",
+            "body": "Das ist dein Delivery-Board: Hier planst du Arbeit, Agenten übernehmen sie, und du prüfst die Ergebnisse. Diese kurze Tour zeigt dir die wichtigsten Bedienelemente."
+          },
+          "canvas": {
+            "title": "Das Board",
+            "body": "Services, Module und Aufgaben liegen auf dieser Fläche. Ziehe zum Verschieben, scrolle zum Zoomen und klicke auf eine Karte, um Details zu sehen."
+          },
+          "sidebar": {
+            "title": "Die Seitenleiste",
+            "body": "Alles Weitere findest du hier: Pipelines erstellen, Repositories und Integrationen verbinden, Workspace-Einstellungen."
+          },
+          "commandBar": {
+            "title": "Die Befehlspalette",
+            "body": "Der schnellste Weg zu jeder Aktion: öffnen und lostippen. Von dort kannst du dieses Tutorial jederzeit neu starten."
+          },
+          "toolbar": {
+            "title": "Board-Steuerung",
+            "body": "Mit diesen Steuerelementen zoomst du hinein und heraus oder bringst das ganze Board ins Bild."
+          },
+          "interfaceTier": {
+            "title": "Einfach und erweitert",
+            "body": "Die Oberfläche startet im einfachen Modus, der die alltäglichen Arbeitsflächen zeigt. Wechsle hier auf erweitert, wenn du zusätzlich die Flächen für Experimente, Bootstrap und Betrieb brauchst."
+          },
+          "finish": {
+            "title": "Das war die Übersicht",
+            "body": "Jetzt kennst du dich aus. Probiere die nächste Tour, um deine erste Aufgabe zu erstellen und auszuführen, oder komm später über die Befehlspalette zurück."
+          }
+        }
+      },
+      "addService": {
+        "title": "Erstes Repository hinzufügen",
+        "description": "Verknüpfe ein Repository, damit das Board einen Service hat, für den du Arbeit planen kannst.",
+        "steps": {
+          "intro": {
+            "title": "Beginne mit einem Repository",
+            "body": "Arbeit passiert am Code, also braucht ein Board mindestens einen Service, bevor ein Agent irgendwo arbeiten kann. Diese Tour verknüpft einen."
+          },
+          "open": {
+            "title": "Service aus Repository",
+            "body": "Das öffnet die Repository-Auswahl. Sie listet die Repositories, die die Verbindung dieses Workspace sehen kann."
+          },
+          "search": {
+            "title": "Repository auswählen",
+            "body": "Suche nach einem deiner eigenen Repositories. Wenn du lieber an etwas Kleinem üben möchtest: {repo} ist ein Beispiel-Service, der für diese Touren absichtlich unfertig bleibt."
+          },
+          "add": {
+            "title": "Hinzufügen",
+            "body": "Das Repository wird zu einem Service-Rahmen auf dem Board. Später kannst du weitere hinzufügen, in einem Monorepo auch einen Service pro Ordner."
+          },
+          "finish": {
+            "title": "Du hast einen Service",
+            "body": "In diesem Rahmen leben die Aufgaben. Die nächste Tour legt eine hinein."
+          }
+        }
+      },
+      "firstTask": {
+        "title": "Erstelle deine erste Aufgabe",
+        "description": "Füge einem Service eine Aufgabe hinzu und sieh zu, wie sie auf dem Board erscheint.",
+        "steps": {
+          "intro": {
+            "title": "Lass uns eine Aufgabe erstellen",
+            "body": "Eine Aufgabe beschreibt ein gewünschtes Ergebnis; eine Agenten-Pipeline liefert es. Diese Tour führt dich Schritt für Schritt durch das Erstellen einer echten Aufgabe."
+          },
+          "addTask": {
+            "title": "Aufgabe hinzufügen",
+            "body": "Jeder Service-Rahmen hat einen Hinzufügen-Button in seiner Kopfzeile."
+          },
+          "describe": {
+            "title": "Beschreibe das Ergebnis",
+            "body": "Gib der Aufgabe einen kurzen Titel, der sagt, was am Ende erreicht sein soll. Normale Sprache genügt."
+          },
+          "create": {
+            "title": "Erstelle die Aufgabe",
+            "body": "Wenn die Beschreibung passt, erstelle die Aufgabe."
+          },
+          "card": {
+            "title": "Aufgabenkarten",
+            "body": "Das ist eine Aufgabenkarte. Von ihr aus startest du die Pipeline, verfolgst den Fortschritt und öffnest Ergebnisse."
+          },
+          "finish": {
+            "title": "Gut gemacht",
+            "body": "Das ist der Kernablauf: Aufgabe beschreiben, ausführen, Ergebnis prüfen. Entdecke die weiteren Touren, wann immer du magst."
+          }
+        }
+      },
+      "runTask": {
+        "title": "Aufgabe ausführen",
+        "description": "Öffne eine Aufgabe, wähle ihre Pipeline und lass die Agenten loslegen.",
+        "steps": {
+          "intro": {
+            "title": "Von der Aufgabe zum Lauf",
+            "body": "Eine Aufgabe auf dem Board ist eine Anfrage. Wenn du sie öffnest, siehst du die Pipeline, die sie liefert, und die Bedienelemente, die sie starten."
+          },
+          "openTask": {
+            "title": "Aufgabe öffnen",
+            "body": "Ein Klick auf eine Karte öffnet ihren Inspektor, in dem alles zu dieser Aufgabe steht."
+          },
+          "inspector": {
+            "title": "Der Inspektor",
+            "body": "Status, Repository, Pipeline und der Lauf selbst: dieses Panel ist die ganze Geschichte der Aufgabe."
+          },
+          "pipeline": {
+            "title": "Pipeline wählen",
+            "body": "Eine Pipeline ist die Abfolge von Agenten, die die Arbeit erledigen: Spezifikation schreiben, umsetzen, prüfen, Checks laufen lassen, mergen. Wähle die, die zur Aufgabe passt."
+          },
+          "start": {
+            "title": "Einen Lauf starten",
+            "body": "Das startet die Pipeline wirklich, und Agenten verbrauchen Modellbudget. Deshalb bleibt der Klick bei dir: drücke ihn, wann du bereit bist, während dieser Tour oder danach."
+          },
+          "steps": {
+            "title": "Beim Arbeiten zusehen",
+            "body": "Jeder Schritt meldet seinen Fortschritt hier, live übertragen. Klicke einen Schritt an, um zu lesen, was der Agent tatsächlich produziert hat."
+          },
+          "finish": {
+            "title": "Das ist der Kreislauf",
+            "body": "Aufgabe planen, Pipeline wählen, starten, zusehen. Wenn ein Lauf etwas von dir braucht, hält er an und sagt es, was die nächste Tour behandelt."
+          }
+        }
+      },
+      "answerPark": {
+        "title": "Wartenden Lauf beantworten",
+        "description": "Ein Lauf pausiert und wartet auf einen Menschen. Sieh, wo er fragt und wie du antwortest.",
+        "steps": {
+          "intro": {
+            "title": "Ein Lauf wartet auf dich",
+            "body": "Manche Schritte halten an und fragen: eine Rückfrage zu den Anforderungen, ein Plan zur Freigabe, eine Wahl zwischen Ansätzen. Ein pausierter Lauf wartet unbegrenzt auf eine Antwort, also bewegt sich nichts, bis du antwortest."
+          },
+          "resolve": {
+            "title": "Wo er fragt",
+            "body": "Eine Aufgabe, die auf einen Menschen wartet, zeigt das auf ihrer Karte und bietet diese Aktion an. Sie bringt dich direkt zu dem, was gefragt wird."
+          },
+          "decide": {
+            "title": "Eine Antwort wählen",
+            "body": "Jede Option ist eine echte Anweisung an den Lauf: wähle eine, und die Pipeline macht mit deiner Wahl weiter."
+          },
+          "approve": {
+            "title": "Die Arbeit freigeben",
+            "body": "Gib frei, damit der Lauf weitergeht, oder fordere Änderungen an, um den Schritt mit deinen Anmerkungen zurückzuschicken. Beides sind Antworten, und der Lauf läuft so oder so weiter."
+          },
+          "finish": {
+            "title": "Nichts wartet stillschweigend",
+            "body": "Wartende Aufgaben sind auf dem Board markiert und in der Werkzeugleiste gezählt, damit du sie findest, ohne zu suchen."
+          }
+        }
+      },
+      "reviewMerge": {
+        "title": "Prüfen und mergen",
+        "description": "Lies, was ein fertiger Lauf produziert hat, und bring es in den Hauptzweig.",
+        "steps": {
+          "intro": {
+            "title": "Ein Lauf ist fertig",
+            "body": "Fertig ist nicht dasselbe wie ausgeliefert. Eine Aufgabe ist erledigt, wenn ihr Pull Request gemergt ist, also geht es hier um die letzte Meile."
+          },
+          "openTask": {
+            "title": "Aufgabe öffnen",
+            "body": "Öffne eine Aufgabe, deren Lauf fertig ist. Ihr Inspektor enthält die vollständige Schrittliste."
+          },
+          "openStep": {
+            "title": "Schritt öffnen",
+            "body": "Ein Klick auf einen Schritt zeigt, was dieser Agent produziert hat: seinen Bericht, seine Befunde und was er geändert hat."
+          },
+          "result": {
+            "title": "Das Ergebnis lesen",
+            "body": "Das ist die eigene Darstellung des Agenten. Review-Schritte listen Befunde, ein Tester meldet Urteile, der Merger erklärt, wie er die Änderung bewertet hat."
+          },
+          "merge": {
+            "title": "Mergen",
+            "body": "Wenn ein Lauf einen Pull Request öffnet, bietet der Inspektor hier den Merge an. Eine Pipeline mit Merger-Schritt kann auch selbst mergen, wenn die Änderung über deinem Schwellenwert liegt."
+          },
+          "finish": {
+            "title": "Ausgeliefert",
+            "body": "Gemergte Arbeit markiert die Aufgabe auf dem Board als erledigt. Das ist der ganze Kreislauf: planen, ausführen, antworten, prüfen, mergen."
+          }
+        }
+      }
+    }
   }
 }