Align VS Code tour better with web tour and move around some steps / add some steps to show intent clearer.

Author: EzraBerendsen

apps/adr-manager/cypress/e2e/adrManagerTest/Tour.cy.ts

@@ -33,22 +33,37 @@ context("First-time tour", () => {
         });
 
         cy.get("[data-cy=tourNext]").click();
-        cy.get("[data-cy=tourStepTitle]").should("contain", "Search and filter ADRs");
+        cy.get("[data-cy=tourStepTitle]").should("contain", "Search ADRs");
+        cy.get("[data-cy=adr-filter-toggle]").should("be.visible");
 
         cy.get("[data-cy=tourNext]").click();
+        cy.get("[data-cy=tourStepTitle]").should("contain", "Filter ADRs");
+        cy.get("[data-cy=adr-filter-panel]").should("be.visible");
+
+        cy.get("[data-cy=tourNext]").click();
+        cy.get("[data-cy=tourStepTitle]").should("contain", "Apply a filter");
+        cy.get("[data-cy=adr-filter-panel] .filter-chip.active").should("have.length", 1);
+
+        cy.get("[data-cy=tourNext]").click();
+        cy.get("[data-cy=adr-filter-panel]").should("not.exist");
         cy.get("[data-cy=tourStepTitle]").should("contain", "Switch repositories");
 
+        cy.get("[data-cy=tourNext]").click();
+        cy.get("[data-cy=tourStepTitle]").should("contain", "Delete an ADR");
+
         cy.get("[data-cy=tourNext]").click();
         cy.get("[data-cy=tourStepTitle]").should("contain", "Create a new ADR");
 
         cy.get("[data-cy=tourNext]").click();
-        cy.get("[data-cy=tourStepTitle]").should("contain", "Edit with structured fields");
-        cy.get("[data-cy=titleAdr]").should("exist");
+        cy.get("[data-cy=tourStepTitle]").should("contain", "Choose the MADR version");
+        cy.get("[data-cy=versionSelect]").should("contain", "MADR 2.1.2");
+        cy.get("[data-cy=versionOption]").should("have.length.greaterThan", 1);
 
         cy.get("[data-cy=tourNext]").click();
-        cy.get("[data-cy=tourStepTitle]").should("contain", "Live Markdown preview");
+        cy.get("[data-cy=versionOption]").should("not.exist");
+        cy.get("[data-cy=tourStepTitle]").should("contain", "Edit with structured fields");
+        cy.get("[data-cy=titleAdr]").should("exist");
 
-        // The toggle-fields step forces professional mode while it is shown.
         cy.get("[data-cy=tourNext]").click();
         cy.get("[data-cy=tourStepTitle]").should("contain", "Toggle optional fields");
         cy.get("[data-cy=decisionDriversPro]").should("exist");
@@ -58,12 +73,9 @@ context("First-time tour", () => {
         cy.get("[data-cy=fieldsBtn]").should("be.visible");
 
         cy.get("[data-cy=tourNext]").click();
-        cy.get("[data-cy=tourStepTitle]").should("contain", "Delete an ADR");
+        cy.get("[data-cy=tourStepTitle]").should("contain", "Live Markdown preview");
         cy.get("[data-cy=decisionDriversPro]").should("not.exist");
 
-        cy.get("[data-cy=tourNext]").click();
-        cy.get("[data-cy=tourStepTitle]").should("contain", "The ADR directory");
-
         cy.get("[data-cy=tourNext]").click();
         cy.get("[data-cy=tourStepTitle]").should("contain", "Commit your changes");
 

apps/adr-manager/src/components/MadrVersionSelect.vue

@@ -1,6 +1,6 @@
 <template>
-    <div ref="wrap" class="verselect">
-        <button type="button" data-cy="versionSelect" class="verselect-btn" @click="open = !open">
+    <div ref="wrap" class="verselect" data-tour="template-version" @tour-version-menu="setTourMenuOpen">
+        <button type="button" data-cy="versionSelect" class="verselect-btn" :aria-expanded="open" @click="open = !open">
             <span class="mdi mdi-file-tree-outline" aria-hidden="true"></span>
             <span class="vlabel">MADR {{ modelValue }}</span>
             <span class="ver-pill">TEMPLATE</span>
@@ -45,6 +45,10 @@ function select(version: MadrTemplateVersion): void {
     emit("update:modelValue", version);
     open.value = false;
 }
+
+function setTourMenuOpen(event: Event): void {
+    open.value = (event as CustomEvent<boolean>).detail;
+}
 </script>
 
 <style scoped>

apps/adr-manager/src/composables/useTour.ts

@@ -1,6 +1,6 @@
 import { computed, readonly, ref } from "vue";
 import { injectDemo, snapshotEditorState, teardownDemo } from "@/plugins/tour/demoRepository";
-import { tourSteps } from "@/plugins/tour/steps";
+import { resetTourFilterDemonstration, tourSteps } from "@/plugins/tour/steps";
 import { store } from "@/plugins/store";
 import type { TourSnapshot } from "@/plugins/tour/demoRepository";
 
@@ -37,6 +37,7 @@ export function useTour() {
             return;
         }
         currentStep.value?.onExit?.();
+        resetTourFilterDemonstration();
         active.value = false;
         if (snapshot) {
             // Safe in both modes: without demo state the snapshot matches the live state.

apps/adr-manager/src/plugins/tour/demoRepository.ts

@@ -4,12 +4,13 @@
  * step can point at real UI. It is removed on teardown and (via the `transient`
  * filter in the store) never written to localStorage.
  */
-import { ArchitecturalDecisionRecord, Repository } from "@/plugins/classes";
-import { adr2md } from "@/plugins/parser";
+import { Repository } from "@/plugins/classes";
+import { serializeMadr } from "@/plugins/parser";
 import { store } from "@/plugins/store";
 import { DEMO_REPO_FULL_NAME } from "@/plugins/tour/constants";
 import type { AdrFile } from "@/types/adr";
 import type { Mode } from "@/types/store";
+import { buildPrimaryDemoAdrFixture, setTagsInMd } from "@adr-manager/core";
 
 export interface TourSnapshot {
     currentRepository: Repository | undefined;
@@ -18,44 +19,15 @@ export interface TourSnapshot {
 }
 
 /**
- * The markdown is generated with adr2md from a constructed record (never hand-written)
+ * The markdown is serialized from the shared demo fixture (never hand-written)
  * so it survives the round-trip check in useAdrEditor and opens in the form editor
  * instead of the convert view. Professional-only fields (drivers, consequences) are
  * populated so the Basic/Professional tour step visibly reveals content.
  */
 export function buildDemoRepository(): Repository {
-    const record = new ArchitecturalDecisionRecord({
-        title: "Use Markdown Architectural Decision Records",
-        status: "accepted",
-        date: "2024-03-18",
-        deciders: "Ada Lovelace, Grace Hopper",
-        contextAndProblemStatement:
-            "We want to record the architectural decisions made in this project, " +
-            "so that new team members can understand why the system looks the way it does.",
-        decisionDrivers: [
-            "Decisions should live next to the code they affect",
-            "The format should be reviewable in pull requests"
-        ],
-        consideredOptions: [
-            {
-                title: "MADR",
-                description: "Markdown Architectural Decision Records.",
-                pros: ["Plain Markdown, works with any Git host", "Lightweight template"],
-                cons: ["Needs discipline to keep up to date"]
-            },
-            { title: "A wiki", pros: ["Easy to edit"], cons: ["Drifts away from the code"] },
-            { title: "No documentation" }
-        ],
-        decisionOutcome: {
-            chosenOption: "MADR",
-            explanation: "it keeps the decision history versioned together with the code",
-            positiveConsequences: ["Every decision is reviewable and traceable"],
-            negativeConsequences: ["Writing a record takes a little time"]
-        },
-        links: []
-    });
-    const md = adr2md(record);
-    const path = "docs/decisions/0001-use-markdown-architectural-decision-records.md";
+    const fixture = buildPrimaryDemoAdrFixture();
+    const md = setTagsInMd(serializeMadr(fixture.record, fixture.templateVersion), fixture.tags);
+    const path = `docs/decisions/${fixture.fileName}`;
     const adrFile: AdrFile = {
         originalMd: md,
         editedMd: md,

apps/adr-manager/src/plugins/tour/steps.ts

@@ -1,5 +1,6 @@
 import { store } from "@/plugins/store";
 import type { Mode } from "@/types/store";
+import { TOUR_COPY } from "@adr-manager/core";
 
 export interface TourStep {
     id: string;
@@ -14,15 +15,49 @@ export interface TourStep {
 
 let modeBeforeToggleStep: Mode | undefined;
 let modeBeforeFieldVisibilityStep: Mode | undefined;
+let demonstratedFilter: HTMLButtonElement | undefined;
+
+function setFilterPanelOpen(open: boolean): void {
+    const button = document.querySelector<HTMLButtonElement>('[data-cy="adr-filter-toggle"]');
+    if (button && (button.getAttribute("aria-expanded") === "true") !== open) {
+        button.click();
+    }
+}
+
+function setExampleFilterActive(active: boolean): void {
+    if (active) {
+        setFilterPanelOpen(true);
+        demonstratedFilter =
+            document.querySelector<HTMLButtonElement>(".filter-panel .filter-chip:not(.tags-more-btn):not(.active)") ??
+            undefined;
+        demonstratedFilter?.click();
+        return;
+    }
+    if (demonstratedFilter?.getAttribute("aria-pressed") === "true") {
+        demonstratedFilter.click();
+    }
+    demonstratedFilter = undefined;
+    setFilterPanelOpen(false);
+}
+
+function setTemplateVersionMenuOpen(open: boolean): void {
+    const wrap = document.querySelector<HTMLElement>('[data-tour="template-version"]');
+    wrap?.dispatchEvent(new CustomEvent<boolean>("tour-version-menu", { detail: open }));
+}
+
+export function resetTourFilterDemonstration(): void {
+    setExampleFilterActive(false);
+    setFilterPanelOpen(false);
+    setTemplateVersionMenuOpen(false);
+}
 
 export const tourSteps: TourStep[] = [
     {
         id: "intro",
         title: "Architectural Decision Records",
         body:
-            "An ADR is a short Markdown document that captures one architectural decision, the context behind it, " +
-            "the options that were considered and the outcome. ADR Manager lets you create, edit and commit ADRs " +
-            "in the MADR format directly in your Git repositories."
+            TOUR_COPY.adrDefinition +
+            " ADR Manager lets you create, edit and commit ADRs in the MADR format directly in your Git repositories."
     },
     {
         id: "explorer",
@@ -37,10 +72,25 @@ export const tourSteps: TourStep[] = [
         id: "adr-search",
         target: '[data-tour="adr-search"]',
         placement: "right",
-        title: "Search and filter ADRs",
-        body:
-            "Type in the search bar to find ADRs by title across all your repositories. Use the filter button " +
-            "to narrow down decisions by status, tags, or other criteria."
+        title: "Search ADRs",
+        body: TOUR_COPY.search
+    },
+    {
+        id: "adr-filter",
+        target: '[data-cy="adr-filter-toggle"]',
+        placement: "right",
+        title: "Filter ADRs",
+        body: TOUR_COPY.filter,
+        onEnter: () => setFilterPanelOpen(true)
+    },
+    {
+        id: "adr-filter-example",
+        target: () => document.querySelector(".filter-panel .filter-chip:not(.tags-more-btn)"),
+        placement: "right",
+        title: "Apply a filter",
+        body: "Selecting a status or tag immediately narrows the ADR list. Select it again to remove the filter.",
+        onEnter: () => setExampleFilterActive(true),
+        onExit: () => setExampleFilterActive(false)
     },
     {
         id: "switch-repository",
@@ -52,43 +102,47 @@ export const tourSteps: TourStep[] = [
             "Click a repository to expand it and make it active. You can keep several repositories open " +
             "and switch between them at any time."
     },
+    {
+        id: "delete-adr",
+        target: '[data-cy="deleteAdrBtn"]',
+        placement: "right",
+        title: "Delete an ADR",
+        body:
+            "Hover an ADR in the explorer and click the trash icon to delete it. The deletion is staged " +
+            "locally and only applied to the repository when you commit."
+    },
     {
         id: "create-adr",
         target: '[data-cy="newADR"]',
         placement: "right",
         title: "Create a new ADR",
         body:
             "New ADR adds a numbered Markdown file based on the MADR template to the repository's " +
-            "ADR directory and opens it in the editor."
+            "ADR directory and opens it in the editor. New setups default to docs/decisions; the status bar " +
+            "shows the full path and active branch."
+    },
+    {
+        id: "template-version",
+        target: '[data-tour="template-version"]',
+        placement: "bottom",
+        title: "Choose the MADR version",
+        body: TOUR_COPY.templateVersion,
+        onEnter: () => setTemplateVersionMenuOpen(true),
+        onExit: () => setTemplateVersionMenuOpen(false)
     },
     {
         id: "edit-adr",
         target: '[data-tour="editor"]',
         placement: "over",
         title: "Edit with structured fields",
-        body:
-            "The editor turns the MADR template into a form with fields like title, context, considered options " +
-            "and decision outcome. Everything you type is converted to Markdown as you go, and the title also " +
-            "becomes the file name."
-    },
-    {
-        id: "preview",
-        target: '[data-tour="preview"]',
-        placement: "left",
-        title: "Live Markdown preview",
-        body:
-            "This pane shows the generated Markdown in real time. You can also edit the raw Markdown here, " +
-            "the form and the source stay in sync."
+        body: TOUR_COPY.editorIntro
     },
     {
         id: "toggle-fields",
         target: '[data-tour="mode-toggle"]',
         placement: "bottom",
         title: "Toggle optional fields",
-        body:
-            "This switch toggles the optional MADR fields. Professional mode reveals decision drivers, pros and " +
-            "cons per option and detailed consequences, while Basic keeps only the essentials. Hidden fields are " +
-            "kept in the file.",
+        body: TOUR_COPY.modeToggle,
         onEnter: () => {
             modeBeforeToggleStep = store.mode;
             // Direct assignment so the demonstration does not persist a mode change.
@@ -106,7 +160,7 @@ export const tourSteps: TourStep[] = [
         target: '[data-tour="field-visibility"]',
         placement: "bottom",
         title: "Customize visible fields",
-        body: "The Fields button is a Professional mode feature that lets you toggle individual Professional mode sections on or off to match your personal preferences.",
+        body: TOUR_COPY.fieldVisibility,
         onEnter: () => {
             modeBeforeFieldVisibilityStep = store.mode;
             store.mode = "professional";
@@ -119,23 +173,13 @@ export const tourSteps: TourStep[] = [
         }
     },
     {
-        id: "delete-adr",
-        target: '[data-cy="deleteAdrBtn"]',
-        placement: "right",
-        title: "Delete an ADR",
-        body:
-            "Hover an ADR in the explorer and click the trash icon to delete it. The deletion is staged " +
-            "locally and only applied to the repository when you commit."
-    },
-    {
-        id: "adr-directory",
-        target: '[data-tour="adr-path"]',
-        placement: "top",
-        title: "The ADR directory",
+        id: "preview",
+        target: '[data-tour="preview"]',
+        placement: "left",
+        title: "Live Markdown preview",
         body:
-            "Each repository keeps its ADRs in one directory, which ADR Manager detects automatically " +
-            "(new setups default to docs/decisions). The status bar shows the full path of the open ADR " +
-            "and the branch you are working on."
+            "This pane shows the generated Markdown in real time. You can also edit the raw Markdown here, " +
+            "the form and the source stay in sync."
     },
     {
         id: "commit",

apps/adr-manager/tests/tour-demo.test.ts

@@ -1,4 +1,4 @@
-import { matchesIgnoringFormatting } from "@adr-manager/core";
+import { matchesIgnoringFormatting, parseTagsFromMd, stripTagComment } from "@adr-manager/core";
 import { Repository } from "@/plugins/classes";
 import { adr2md, md2adr } from "@/plugins/parser";
 import { store } from "@/plugins/store";
@@ -17,7 +17,8 @@ test("the demo ADR round-trips through the MADR parser", () => {
     const repo = buildDemoRepository();
     const md = repo.adrs[0]?.editedMd ?? "";
     // A failed round-trip would open the demo in the convert view and break the tour anchors.
-    expect(matchesIgnoringFormatting(md, adr2md(md2adr(md)))).toBe(true);
+    expect(matchesIgnoringFormatting(stripTagComment(md), adr2md(md2adr(md)))).toBe(true);
+    expect(parseTagsFromMd(md).length).toBeGreaterThan(0);
 });
 
 test("the demo repository is transient and opens its sample ADR", () => {

apps/adr-manager/tests/use-tour.test.ts

@@ -29,6 +29,26 @@ afterEach(() => {
     localStorage.clear();
 });
 
+test("tour steps stay grouped by screen section", () => {
+    expect(tourSteps.map((step) => step.id)).toEqual([
+        "intro",
+        "explorer",
+        "adr-search",
+        "adr-filter",
+        "adr-filter-example",
+        "switch-repository",
+        "delete-adr",
+        "create-adr",
+        "template-version",
+        "edit-adr",
+        "toggle-fields",
+        "field-visibility",
+        "preview",
+        "commit",
+        "replay"
+    ]);
+});
+
 test("starting over an empty workspace injects the demo repository", () => {
     tour.start();