From 949fceb79006f855a1d248846d0d4f99596bad3b Mon Sep 17 00:00:00 2001
From: Serafim <serafim@Serafims-MacBook-Pro.local>
Date: Mon, 14 Jul 2025 18:43:14 +0400
Subject: [PATCH 1/2] feat(interactive-tour): init

---
 package.json                                  |  1 +
 pnpm-lock.yaml                                |  7 +++
 .../InteractiveTour/InteractiveTour.svelte    |  2 +
 src/lib/ui/app/InteractiveTour/index.ts       |  1 +
 .../InteractiveTour/index.stories.ts          | 15 +++++
 .../InteractiveTour/index.svelte              | 59 +++++++++++++++++++
 6 files changed, 85 insertions(+)
 create mode 100644 src/lib/ui/app/InteractiveTour/InteractiveTour.svelte
 create mode 100644 src/lib/ui/app/InteractiveTour/index.ts
 create mode 100644 src/stories/Design System - App UI/InteractiveTour/index.stories.ts
 create mode 100644 src/stories/Design System - App UI/InteractiveTour/index.svelte

diff --git a/package.json b/package.json
index 512afbca3..94c45673f 100644
--- a/package.json
+++ b/package.json
@@ -157,6 +157,7 @@
     "@reown/appkit-adapter-wagmi": "^1.2.0",
     "@stripe/stripe-js": "^4.1.0",
     "drawer-svelte": "^0.1.3",
+    "driver.js": "^1.3.6",
     "eslint": "^9.28.0",
     "esm-env": "^1.2.2",
     "fast-glob": "^3.3.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f7819cf1c..63dd54180 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,6 +26,9 @@ dependencies:
   drawer-svelte:
     specifier: ^0.1.3
     version: 0.1.3(@melt-ui/svelte@0.86.0)(esm-env@1.2.2)(svelte-runes@0.0.7)(svelte@5.35.4)
+  driver.js:
+    specifier: ^1.3.6
+    version: 1.3.6
   eslint:
     specifier: ^9.28.0
     version: 9.28.0
@@ -5994,6 +5997,10 @@ packages:
       svelte-runes: 0.0.7(svelte@5.35.4)
     dev: false
 
+  /driver.js@1.3.6:
+    resolution: {integrity: sha512-g2nNuu+tWmPpuoyk3ffpT9vKhjPz4NrJzq6mkRDZIwXCrFhrKdDJ9TX5tJOBpvCTBrBYjgRQ17XlcQB15q4gMg==}
+    dev: false
+
   /dunder-proto@1.0.1:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
     engines: {node: '>= 0.4'}
diff --git a/src/lib/ui/app/InteractiveTour/InteractiveTour.svelte b/src/lib/ui/app/InteractiveTour/InteractiveTour.svelte
new file mode 100644
index 000000000..0fbba9978
--- /dev/null
+++ b/src/lib/ui/app/InteractiveTour/InteractiveTour.svelte
@@ -0,0 +1,2 @@
+<script lang="ts">
+</script>
diff --git a/src/lib/ui/app/InteractiveTour/index.ts b/src/lib/ui/app/InteractiveTour/index.ts
new file mode 100644
index 000000000..34f985c7f
--- /dev/null
+++ b/src/lib/ui/app/InteractiveTour/index.ts
@@ -0,0 +1 @@
+export { default } from './InteractiveTour.svelte'
diff --git a/src/stories/Design System - App UI/InteractiveTour/index.stories.ts b/src/stories/Design System - App UI/InteractiveTour/index.stories.ts
new file mode 100644
index 000000000..f8a3ace3e
--- /dev/null
+++ b/src/stories/Design System - App UI/InteractiveTour/index.stories.ts	
@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '@storybook/svelte'
+
+import Component from './index.svelte'
+
+const meta = {
+  component: Component,
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<Component>
+type Story = StoryObj<typeof meta>
+
+export default meta
+
+export const InteractiveTour: Story = {}
diff --git a/src/stories/Design System - App UI/InteractiveTour/index.svelte b/src/stories/Design System - App UI/InteractiveTour/index.svelte
new file mode 100644
index 000000000..4351efb92
--- /dev/null
+++ b/src/stories/Design System - App UI/InteractiveTour/index.svelte	
@@ -0,0 +1,59 @@
+<script lang="ts">
+  import Button from '$ui/core/Button/Button.svelte'
+  import { driver } from 'driver.js'
+  import 'driver.js/dist/driver.css'
+
+  const ids = {
+    start: 'test-start',
+    feature1: 'test-feature1',
+    feature2: 'test-feature2',
+    feature3: 'test-feature3',
+  } as const
+
+  const driverObj = driver({
+    steps: [
+      {
+        element: ids.start,
+        popover: {
+          title: 'New master select',
+          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+        },
+      },
+      {
+        element: ids.feature1,
+        popover: {
+          title: 'First Feature',
+          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+        },
+      },
+      {
+        element: ids.feature2,
+        popover: {
+          title: 'Second Feature',
+          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+        },
+      },
+      {
+        element: ids.feature3,
+        popover: {
+          title: 'Third Feature',
+          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+        },
+      },
+    ].map(({ element, ...rest }) => ({ element: '#' + element, ...rest })),
+  })
+
+  function start() {
+    driverObj.drive()
+  }
+</script>
+
+<main class="p-8">
+  <Button id={ids.start} class="px-6" variant="border" onclick={start}>Test</Button>
+
+  <row class="mt-10 flex gap-10 [&>div]:rounded [&>div]:p-3 [&>div]:text-white">
+    <div class="bg-green" id={ids.feature1}>Feature 1</div>
+    <div class="bg-blue" id={ids.feature2}>Feature 2</div>
+    <div class="bg-purple" id={ids.feature3}>Feature 3</div>
+  </row>
+</main>

From d9fe561fd94b7a35db2b56fa018e9168ecff7654 Mon Sep 17 00:00:00 2001
From: Serafim <serafim@Serafims-MacBook-Pro.local>
Date: Wed, 16 Jul 2025 14:06:12 +0400
Subject: [PATCH 2/2] feat(interactive-tour): added interactive tour with
 analytics

---
 package.json                                  |   3 +-
 pnpm-lock.yaml                                |   8 +-
 .../InteractiveTour/InteractiveTour.svelte    |   2 -
 src/lib/ui/app/InteractiveTour/index.ts       |   1 -
 .../core/InteractiveTour/CustomPopover.svelte | 115 ++++++++++++++++++
 src/lib/ui/core/InteractiveTour/index.ts      |  26 ++++
 .../InteractiveTour/index.svelte              |  73 +++++------
 7 files changed, 186 insertions(+), 42 deletions(-)
 delete mode 100644 src/lib/ui/app/InteractiveTour/InteractiveTour.svelte
 delete mode 100644 src/lib/ui/app/InteractiveTour/index.ts
 create mode 100644 src/lib/ui/core/InteractiveTour/CustomPopover.svelte
 create mode 100644 src/lib/ui/core/InteractiveTour/index.ts

diff --git a/package.json b/package.json
index 94c45673f..bbbf7b03d 100644
--- a/package.json
+++ b/package.json
@@ -68,6 +68,7 @@
     "@wagmi/connectors": "^5.1.10",
     "@wagmi/core": "^2.13.5",
     "bits-ui": "^0.21.16",
+    "driver.js": "^1.3.6",
     "estree-walker": "^3.0.3",
     "graphql": "^16.8.2",
     "indicatorts": "^2.2.2",
@@ -109,6 +110,7 @@
     "@wagmi/core": "^2.14.1",
     "autoprefixer": "^10.4.19",
     "bits-ui": "^1.3.4",
+    "driver.js": "^1.3.6",
     "eslint-config-prettier": "^10.1.2",
     "eslint-import-resolver-typescript": "^4.3.4",
     "eslint-plugin-import": "^2.31.0",
@@ -157,7 +159,6 @@
     "@reown/appkit-adapter-wagmi": "^1.2.0",
     "@stripe/stripe-js": "^4.1.0",
     "drawer-svelte": "^0.1.3",
-    "driver.js": "^1.3.6",
     "eslint": "^9.28.0",
     "esm-env": "^1.2.2",
     "fast-glob": "^3.3.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 63dd54180..b44c181b0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,9 +26,6 @@ dependencies:
   drawer-svelte:
     specifier: ^0.1.3
     version: 0.1.3(@melt-ui/svelte@0.86.0)(esm-env@1.2.2)(svelte-runes@0.0.7)(svelte@5.35.4)
-  driver.js:
-    specifier: ^1.3.6
-    version: 1.3.6
   eslint:
     specifier: ^9.28.0
     version: 9.28.0
@@ -142,6 +139,9 @@ devDependencies:
   bits-ui:
     specifier: ^1.3.4
     version: 1.3.4(svelte@5.35.4)
+  driver.js:
+    specifier: ^1.3.6
+    version: 1.3.6
   eslint-config-prettier:
     specifier: ^10.1.2
     version: 10.1.2(eslint@9.28.0)
@@ -5999,7 +5999,7 @@ packages:
 
   /driver.js@1.3.6:
     resolution: {integrity: sha512-g2nNuu+tWmPpuoyk3ffpT9vKhjPz4NrJzq6mkRDZIwXCrFhrKdDJ9TX5tJOBpvCTBrBYjgRQ17XlcQB15q4gMg==}
-    dev: false
+    dev: true
 
   /dunder-proto@1.0.1:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
diff --git a/src/lib/ui/app/InteractiveTour/InteractiveTour.svelte b/src/lib/ui/app/InteractiveTour/InteractiveTour.svelte
deleted file mode 100644
index 0fbba9978..000000000
--- a/src/lib/ui/app/InteractiveTour/InteractiveTour.svelte
+++ /dev/null
@@ -1,2 +0,0 @@
-<script lang="ts">
-</script>
diff --git a/src/lib/ui/app/InteractiveTour/index.ts b/src/lib/ui/app/InteractiveTour/index.ts
deleted file mode 100644
index 34f985c7f..000000000
--- a/src/lib/ui/app/InteractiveTour/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from './InteractiveTour.svelte'
diff --git a/src/lib/ui/core/InteractiveTour/CustomPopover.svelte b/src/lib/ui/core/InteractiveTour/CustomPopover.svelte
new file mode 100644
index 000000000..b61179897
--- /dev/null
+++ b/src/lib/ui/core/InteractiveTour/CustomPopover.svelte
@@ -0,0 +1,115 @@
+<script lang="ts">
+  import type { Driver } from 'driver.js'
+
+  import { onMount } from 'svelte'
+
+  import { cn } from '$ui/utils/index.js'
+  import { trackEvent } from '$lib/analytics/index.js'
+
+  import Button from '../Button/Button.svelte'
+
+  type TProps = {
+    driver: Driver
+  }
+
+  const { driver }: TProps = $props()
+
+  const steps = driver.getConfig().steps || []
+  const state = driver.getState()
+  const popover = state.activeStep?.popover || {}
+
+  function trackWalkthrough(event: string, idx?: number) {
+    const index = idx ?? state.activeIndex
+    const step = steps[index]
+
+    const stepId =
+      typeof step?.element === 'string'
+        ? step.element
+        : step?.element instanceof Element
+          ? step.element.id || undefined
+          : undefined
+
+    trackEvent(`walkthrough_${event}`, {
+      category: 'Walkthrough',
+      current_step: index + 1,
+      total_steps: steps.length,
+      source_url: window.location.href,
+      step_id: stepId,
+    })
+  }
+
+  function handleMoveTo(index: number) {
+    driver.moveTo(index)
+
+    trackWalkthrough('set_step')
+  }
+
+  function handleClose() {
+    driver.destroy()
+
+    trackWalkthrough('close')
+  }
+
+  function handleMovePrev() {
+    driver.movePrevious()
+
+    trackWalkthrough('prev_step')
+  }
+
+  function handleMoveNext() {
+    driver.moveNext()
+
+    trackWalkthrough('next_step')
+  }
+
+  onMount(() => {
+    if (!state.previousStep) {
+      trackWalkthrough('start')
+    }
+  })
+</script>
+
+<div>
+  <header class="flex max-w-[400px] justify-between">
+    <h3 class="mb-3 text-lg font-medium">{@html popover.title}</h3>
+    <Button iconSize="12" size="sm" icon="close" onclick={handleClose}></Button>
+  </header>
+
+  <div class="mb-6">{@html popover.description}</div>
+
+  <footer class="flex items-center justify-between">
+    <div class="flex gap-2">
+      {#if steps.length > 1}
+        {#each steps as _, i}
+          <Button
+            aria-label="Go to step {i + 1}"
+            variant="plain"
+            onclick={() => handleMoveTo(i)}
+            class={cn(
+              'h-1.5 w-1.5 rounded-full bg-green-light-3 p-0',
+              state.activeIndex === i && 'bg-green',
+            )}
+          ></Button>
+        {/each}
+      {/if}
+    </div>
+
+    <div class="flex gap-2">
+      {#if !driver.isFirstStep()}
+        <Button variant="border" class="px-4" onclick={handleMovePrev}>Previous</Button>
+      {/if}
+
+      {#if driver.isLastStep()}
+        <Button variant="fill" onclick={handleClose}>Close</Button>
+      {:else}
+        <Button variant="fill" onclick={handleMoveNext}>Next</Button>
+      {/if}
+    </div>
+  </footer>
+</div>
+
+<style lang="postcss">
+  :global(.driver-popover) {
+    @apply !max-w-[400px] !px-6 !pb-8 !pt-5;
+  }
+</style>
diff --git a/src/lib/ui/core/InteractiveTour/index.ts b/src/lib/ui/core/InteractiveTour/index.ts
new file mode 100644
index 000000000..3d56c99c7
--- /dev/null
+++ b/src/lib/ui/core/InteractiveTour/index.ts
@@ -0,0 +1,26 @@
+import type { Config } from 'driver.js'
+
+import { mount } from 'svelte'
+
+import CustomPopover from './CustomPopover.svelte'
+
+export async function interactiveTour(initialConfig: Config) {
+  await import('driver.js/dist/driver.css')
+
+  const { driver: driverInstance } = await import('driver.js')
+
+  return driverInstance({
+    ...initialConfig,
+
+    onPopoverRender: (popover, { config: _, state: _s, driver }) => {
+      popover.wrapper.innerHTML = ''
+
+      mount(CustomPopover, {
+        target: popover.wrapper,
+        props: {
+          driver,
+        },
+      })
+    },
+  })
+}
diff --git a/src/stories/Design System - App UI/InteractiveTour/index.svelte b/src/stories/Design System - App UI/InteractiveTour/index.svelte
index 4351efb92..be6a8fe18 100644
--- a/src/stories/Design System - App UI/InteractiveTour/index.svelte	
+++ b/src/stories/Design System - App UI/InteractiveTour/index.svelte	
@@ -1,7 +1,6 @@
 <script lang="ts">
   import Button from '$ui/core/Button/Button.svelte'
-  import { driver } from 'driver.js'
-  import 'driver.js/dist/driver.css'
+  import { interactiveTour } from '$ui/core/InteractiveTour/index.js'
 
   const ids = {
     start: 'test-start',
@@ -10,50 +9,56 @@
     feature3: 'test-feature3',
   } as const
 
-  const driverObj = driver({
-    steps: [
-      {
-        element: ids.start,
-        popover: {
-          title: 'New master select',
-          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+  async function start() {
+    const id = (id: string) => `#${id}`
+
+    const tour = await interactiveTour({
+      steps: [
+        {
+          element: id(ids.start),
+          popover: {
+            title: 'New master select',
+            side: 'bottom',
+            description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+          },
         },
-      },
-      {
-        element: ids.feature1,
-        popover: {
-          title: 'First Feature',
-          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+        {
+          element: id(ids.feature1),
+          popover: {
+            title: 'First Feature',
+            side: 'bottom',
+            description: `<p class="mrg-l mrg--b">2) Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+          },
         },
-      },
-      {
-        element: ids.feature2,
-        popover: {
-          title: 'Second Feature',
-          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+        {
+          element: id(ids.feature2),
+          popover: {
+            title: 'Second Feature',
+            side: 'bottom',
+            description: `<p class="mrg-l mrg--b">3) Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+          },
         },
-      },
-      {
-        element: ids.feature3,
-        popover: {
-          title: 'Third Feature',
-          description: `<p class="mrg-l mrg--b">Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+        {
+          element: id(ids.feature3),
+          popover: {
+            title: 'Third Feature',
+            side: 'bottom',
+            description: `<p class="mrg-l mrg--b">4) Paste the concrete smart contract address for fetching relevant metrics for it</p>`,
+          },
         },
-      },
-    ].map(({ element, ...rest }) => ({ element: '#' + element, ...rest })),
-  })
+      ],
+    })
 
-  function start() {
-    driverObj.drive()
+    tour.drive()
   }
 </script>
 
 <main class="p-8">
   <Button id={ids.start} class="px-6" variant="border" onclick={start}>Test</Button>
 
-  <row class="mt-10 flex gap-10 [&>div]:rounded [&>div]:p-3 [&>div]:text-white">
+  <div class="mt-10 flex gap-10 [&>div]:rounded [&>div]:p-3 [&>div]:text-white">
     <div class="bg-green" id={ids.feature1}>Feature 1</div>
     <div class="bg-blue" id={ids.feature2}>Feature 2</div>
     <div class="bg-purple" id={ids.feature3}>Feature 3</div>
-  </row>
+  </div>
 </main>