feat: tsdoc and seenFlows

workspaces/e2e/tests/arrow/arrow.ts

@@ -8,7 +8,7 @@ void init({
       steps: [
         {
           title: "Hello",
-          element: ".target",
+          targetElement: ".target",
           placement: new URLSearchParams(window.location.search).get(
             "placement",
           ) as unknown as "top",

workspaces/e2e/tests/async-flow/async-flow.spec.ts

@@ -6,7 +6,7 @@ test("Should not continue if flow is not fully loaded", async ({ page }) => {
       {
         id: "flow",
         location: "/",
-        steps: [{ title: "First", element: ".target" }],
+        steps: [{ title: "First", targetElement: ".target" }],
         _incompleteSteps: true,
       },
     ];
@@ -25,7 +25,7 @@ test("Should continue if flow is fully loaded", async ({ page }) => {
       {
         id: "flow",
         location: "/",
-        steps: [{ title: "First", element: ".target" }],
+        steps: [{ title: "First", targetElement: ".target" }],
         _incompleteSteps: true,
       },
     ];
@@ -36,8 +36,8 @@ test("Should continue if flow is fully loaded", async ({ page }) => {
       id: "flow",
       location: "/",
       steps: [
-        { title: "First", element: ".target" },
-        { title: "Second", element: ".target" },
+        { title: "First", targetElement: ".target" },
+        { title: "Second", targetElement: ".target" },
       ],
     };
     await route.fulfill({ json });

workspaces/e2e/tests/branch/branch.ts

@@ -5,34 +5,34 @@ const lastStep = new URLSearchParams(window.location.search).get("lastStep") ===
 
 const steps: FlowSteps = [
   {
-    element: ".target",
+    targetElement: ".target",
     title: "Hello",
     hideNext: true,
     wait: [
-      { element: ".enter-1", action: 0 },
-      { element: ".enter-2", action: 1 },
+      { clickElement: ".enter-1", targetBranch: 0 },
+      { clickElement: ".enter-2", targetBranch: 1 },
     ],
     footerActions: {
       right: [
-        { text: "1", action: 0 },
-        { text: "2", action: 1 },
+        { label: "1", targetBranch: 0 },
+        { label: "2", targetBranch: 1 },
       ],
     },
   },
   [
     [
       {
-        element: ".target",
+        targetElement: ".target",
         title: "Variant 1",
       },
     ],
     [
       {
-        element: ".target",
+        targetElement: ".target",
         title: "Variant 2",
       },
       {
-        element: ".target",
+        targetElement: ".target",
         title: "Var 2 last step",
       },
     ],
@@ -41,7 +41,7 @@ const steps: FlowSteps = [
 
 if (lastStep)
   steps.push({
-    element: ".target",
+    targetElement: ".target",
     title: "Last Step",
   });
 

workspaces/e2e/tests/buttons/buttons.spec.ts

@@ -43,7 +43,7 @@ test("Default next text", async ({ page }) => {
   await expect(page.locator(".flows-finish")).toHaveText("Finish");
 });
 test("Custom next text", async ({ page }) => {
-  await page.goto("/buttons/buttons.html?nextText=Next");
+  await page.goto("/buttons/buttons.html?nextLabel=Next");
   await expect(page.locator(".flows-continue")).toHaveText("Next");
   await page.locator(".flows-continue").click();
   await expect(page.locator(".flows-finish")).toHaveText("Next");
@@ -55,7 +55,7 @@ test("Default prev text", async ({ page }) => {
   await expect(page.locator(".flows-back")).toHaveText("Back");
 });
 test("Custom prev text", async ({ page }) => {
-  await page.goto("/buttons/buttons.html?prevText=Previous");
+  await page.goto("/buttons/buttons.html?prevLabel=Previous");
   await page.locator(".flows-continue").click();
   await expect(page.locator(".flows-back")).toHaveText("Previous");
 });

workspaces/e2e/tests/buttons/buttons.ts

@@ -4,8 +4,8 @@ import { init } from "@flows/js";
 const hideClose = new URLSearchParams(window.location.search).get("hideClose") === "true";
 const hidePrev = new URLSearchParams(window.location.search).get("hidePrev") === "true";
 const hideNext = new URLSearchParams(window.location.search).get("hideNext") === "true";
-const prevText = new URLSearchParams(window.location.search).get("prevText") ?? undefined;
-const nextText = new URLSearchParams(window.location.search).get("nextText") ?? undefined;
+const prevLabel = new URLSearchParams(window.location.search).get("prevLabel") ?? undefined;
+const nextLabel = new URLSearchParams(window.location.search).get("nextLabel") ?? undefined;
 const customLink = new URLSearchParams(window.location.search).get("customLink") === "true";
 const customExternalLink =
   new URLSearchParams(window.location.search).get("customExternalLink") === "true";
@@ -16,28 +16,28 @@ const customPrev = new URLSearchParams(window.location.search).get("customPrev")
 const footerActionsArray: NonNullable<FlowTooltipStep["footerActions"]>["left"] = [];
 if (customLink)
   footerActionsArray.push({
-    text: "Google",
+    label: "Google",
     href: "https://google.com",
   });
 if (customExternalLink)
   footerActionsArray.push({
-    text: "Google",
+    label: "Google",
     href: "https://google.com",
     external: true,
   });
 if (customAction)
   footerActionsArray.push({
-    text: "Action",
-    action: 0,
+    label: "Action",
+    targetBranch: 0,
   });
 if (customNext)
   footerActionsArray.push({
-    text: "My Next",
+    label: "My Next",
     next: true,
   });
 if (customPrev)
   footerActionsArray.push({
-    text: "My Prev",
+    label: "My Prev",
     prev: true,
   });
 const footerActions = {
@@ -54,22 +54,22 @@ void init({
       steps: [
         {
           title: "Hello",
-          element: ".target",
+          targetElement: ".target",
           hideClose,
           hidePrev,
           hideNext,
-          prevText,
-          nextText,
+          prevLabel,
+          nextLabel,
           footerActions,
         },
         {
           title: "Hello 2",
-          element: ".target",
+          targetElement: ".target",
           hideClose,
           hidePrev,
           hideNext,
-          prevText,
-          nextText,
+          prevLabel,
+          nextLabel,
         },
       ],
     },

workspaces/e2e/tests/error/error.ts

@@ -8,7 +8,7 @@ init({
       id: "flow",
       steps: [
         {
-          element: ".target",
+          targetElement: ".target",
           title: "Hello",
         },
       ],

workspaces/e2e/tests/frequency/frequency.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="stylesheet" href="/tests/reset.css" />
+    <link rel="stylesheet" href="/node_modules/@flows/js/css.min/flows.css" />
+  </head>
+  <body>
+    <button class="start-flow">Start flow</button>
+
+    <div
+      style="background-color: grey; width: 20px; height: 20px; margin: 40px"
+      class="target"
+    ></div>
+
+    <script type="module" src="./frequency.ts"></script>
+  </body>
+</html>

workspaces/e2e/tests/frequency/frequency.spec.ts

@@ -0,0 +1,58 @@
+import { expect, test } from "@playwright/test";
+
+test("should show up only once by default", async ({ page }) => {
+  await page.goto("/frequency/frequency.html");
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeVisible();
+  await page.locator(".flows-finish").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+});
+test("should show up only once with frequency once", async ({ page }) => {
+  await page.goto("/frequency/frequency.html?frequency=once");
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeVisible();
+  await page.locator(".flows-finish").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+});
+test("should show up multiple times when frequency is every time", async ({ page }) => {
+  await page.goto("/frequency/frequency.html?frequency=every-time");
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeVisible();
+  await page.locator(".flows-finish").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeVisible();
+});
+test("should show up again when page is reloaded", async ({ page }) => {
+  await page.goto("/frequency/frequency.html");
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeVisible();
+  await page.locator(".flows-finish").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.reload();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeVisible();
+});
+test("should not show up again when seenFlows are saved to localStorage", async ({ page }) => {
+  await page.goto("/frequency/frequency.html?saveSeenFlows=true");
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeVisible();
+  await page.locator(".flows-finish").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+  await page.reload();
+  await page.locator(".start-flow").click();
+  await expect(page.locator(".flows-tooltip")).toBeHidden();
+});

workspaces/e2e/tests/frequency/frequency.ts

@@ -0,0 +1,29 @@
+import { Flow, FlowsOptions, init } from "@flows/js";
+
+const frequency = new URLSearchParams(window.location.search).get("frequency") as Flow["frequency"];
+const saveSeenFlows = new URLSearchParams(window.location.search).get("saveSeenFlows") === "true";
+
+const flow: Flow = {
+  element: ".start-flow",
+  id: "flow",
+
+  steps: [
+    {
+      targetElement: ".target",
+      title: "Hello",
+    },
+  ],
+};
+if (frequency) flow.frequency = frequency as Flow["frequency"];
+
+const options: FlowsOptions = {
+  flows: [flow],
+};
+
+if (saveSeenFlows) {
+  options.seenFlows = JSON.parse(localStorage.getItem("flows-seen-flows") ?? "[]");
+  options.onSeenFlowsChange = (seenFlows) =>
+    localStorage.setItem("flows-seen-flows", JSON.stringify(seenFlows));
+}
+
+init(options);

workspaces/e2e/tests/html-content/html-content.ts

@@ -7,7 +7,7 @@ const step: FlowStep = {
   title: '<span class="span-in-title">span in title</span>',
   body: '<span class="span-in-body">span in body</span>',
 };
-if (tooltip) (step as FlowTooltipStep).element = ".target";
+if (tooltip) (step as FlowTooltipStep).targetElement = ".target";
 
 void init({
   flows: [

workspaces/e2e/tests/multi-page/multi-page.ts

@@ -7,11 +7,11 @@ init({
       steps: [
         {
           title: "First",
-          element: ".target",
+          targetElement: ".target",
         },
         {
           title: "Second",
-          element: ".target",
+          targetElement: ".target",
         },
       ],
     },

workspaces/e2e/tests/tooltip-missing-target/tooltip-missing-target.ts

@@ -16,7 +16,7 @@ void init({
       id: "flow",
       steps: [
         {
-          element: ".target",
+          targetElement: ".target",
           title: "Tooltip",
         },
       ],

workspaces/e2e/tests/tooltip-overlay/tooltip-overlay.ts

@@ -11,13 +11,13 @@ init({
       steps: [
         {
           title: "Hello",
-          element: ".target",
+          targetElement: ".target",
           overlay: true,
           closeOnOverlayClick,
         },
         {
           title: "World",
-          element: ".target",
+          targetElement: ".target",
         },
       ],
     },

workspaces/e2e/tests/wait/wait.ts

@@ -10,7 +10,7 @@ const anotherWaitWithWrongLocation =
   new URLSearchParams(window.location.search).get("anotherWaitWithWrongLocation") === "true";
 
 let wait: FlowWaitStep["wait"] = {};
-if (click) wait.element = ".target";
+if (click) wait.clickElement = ".target";
 if (change) wait.change = [{ element: ".input", value: "Hello World" }];
 if (multipleChange)
   wait.change = [
@@ -36,13 +36,13 @@ void init({
       steps: [
         {
           title: "First",
-          element: ".target",
+          targetElement: ".target",
           wait,
           hideNext: true,
         },
         {
           title: "Second",
-          element: ".target",
+          targetElement: ".target",
         },
       ],
     },

workspaces/js/src/document-change.ts

@@ -5,8 +5,8 @@ export const handleDocumentChange = (): void => {
     if (state.waitingForElement) state.render();
 
     const step = state.currentStep;
-    if (step && "element" in step) {
-      const el = document.querySelector(step.element);
+    if (step && "targetElement" in step) {
+      const el = document.querySelector(step.targetElement);
       const targetChanged = state.flowElement?.target && el !== state.flowElement.target;
       if (targetChanged) state.render();
     }