From fe504ad6f059fbea25a8a400d28ad3e32eb20436 Mon Sep 17 00:00:00 2001
From: Kamran Ahmed <kamranahmed.se@gmail.com>
Date: Fri, 17 Jul 2026 11:59:37 +0100
Subject: [PATCH] Add a hints example to the homepage and simplify the
 hint-to-tour docs

The homepage examples grid gains a Hints button that toggles three
beacons on the hero: one plain dismissable hint, one whose button starts
a short tour through onButtonClick (showing the two features hand off to
each other), and one whose button leads to the hints guide. The last-row
label shrinks from 'and much more ...' to 'and more ...' so the row
keeps to one line.

The guide's hint-launches-tour example now uses buttonText plus
onButtonClick instead of hand-building a button in onPopoverRender,
which stays mentioned for additional buttons.
---
 apps/docs/src/components/Examples.astro | 87 ++++++++++++++++++++++++-
 apps/docs/src/content/guides/hints.mdx  | 19 +++---
 2 files changed, 95 insertions(+), 11 deletions(-)

diff --git a/apps/docs/src/components/Examples.astro b/apps/docs/src/components/Examples.astro
index 4c409a4..8098193 100644
--- a/apps/docs/src/components/Examples.astro
+++ b/apps/docs/src/components/Examples.astro
@@ -18,16 +18,19 @@ import { ExampleButton } from "./ExampleButton";
   <ExampleButton id="overlay-color" text="Overlay Color" />
   <ExampleButton id="popover-position" text="Popover Positioning" />
   <ExampleButton id="customizing-popover" text="Customizing Popover" />
+  <ExampleButton id="hints-example" text="Hints" />
   <ExampleButton id="hooks-everything" text="Hooks for Everything" />
   <a href="/docs/installation"
      class="cursor-pointer flex items-center rounded-xl border-2 border-black bg-yellow-300 px-5 py-2 text-base lg:text-lg font-medium text-black shadow-[3px_3px_0_0_#000] transition-all duration-100 hover:bg-yellow-400 active:translate-x-[2px] active:translate-y-[2px] active:shadow-[1px_1px_0_0_#000]">
-    and much more ...
+    and more ...
   </a>
 </div>
 
 <script>
   import { driver } from "driver.js";
   import "driver.js/dist/driver.css";
+  import { hints } from "driver.js/hints";
+  import "driver.js/dist/hints.css";
   import { mountDummyElement, removeDummyElement } from "../lib/dummyElement";
 
   function markDone(btn) {
@@ -506,6 +509,88 @@ import { ExampleButton } from "./ExampleButton";
     });
   });
 
+  const hintsBtn = document.getElementById('hints-example');
+  const hintsTour = driver({
+    popoverClass: 'driverjs-theme',
+    showButtons: ['next', 'previous'],
+    steps: [
+      {
+        element: '[data-hero-text]',
+        popover: {
+          title: "From Hint to Tour",
+          description: "A hint's button just started this tour through the <span class='font-medium'>onButtonClick</span> hook. Hints and tours work together without any wiring.",
+          side: 'bottom',
+          align: 'start'
+        }
+      },
+      {
+        element: '[data-example-btns]',
+        popover: {
+          title: "And Back Again",
+          description: "While a tour runs, the beacons wait; close this and they return on their own.",
+          side: 'top',
+          align: 'start'
+        }
+      }
+    ]
+  });
+
+  const demoHints = hints({
+    popoverClass: 'driverjs-theme',
+    hints: [
+      {
+        element: '[data-driver-name]',
+        id: 'what',
+        popover: {
+          title: "Hints, No Tour Required",
+          description: "Beacons sit quietly on the page and open on click, in any order. Nothing is blocked. The button below dismisses this hint for good.",
+          side: 'bottom',
+          align: 'start'
+        }
+      },
+      {
+        element: '[data-hero-text]',
+        id: 'tour',
+        beacon: { side: 'left', align: 'center' },
+        popover: {
+          title: "A Tour Inside a Hint",
+          buttonText: "Take the tour",
+          description: "A hint's button can do anything, including starting a tour.",
+          side: 'bottom',
+          align: 'start',
+          onButtonClick: (element, hint, { hints: instance }) => {
+            instance.close();
+            hintsTour.drive();
+          }
+        }
+      },
+      {
+        element: '[data-example-btns]',
+        id: 'docs',
+        popover: {
+          title: "Learn More",
+          buttonText: "Read the Hints guide",
+          description: "Dismissals, persistence, beacon styling and an optional spotlight overlay are covered in the docs.",
+          side: 'top',
+          align: 'start',
+          onButtonClick: () => {
+            window.location.href = '/docs/hints';
+          }
+        }
+      }
+    ]
+  });
+
+  hintsBtn.addEventListener('click', () => {
+    if (demoHints.isVisible()) {
+      demoHints.hide();
+      return;
+    }
+
+    demoHints.show();
+    markDone(hintsBtn);
+  });
+
   const hooksEverythingBtn = document.getElementById('hooks-everything');
   hooksEverythingBtn.addEventListener('click', () => {
     const driverObj = driver({
diff --git a/apps/docs/src/content/guides/hints.mdx b/apps/docs/src/content/guides/hints.mdx
index 9edaaf8..f1f5408 100644
--- a/apps/docs/src/content/guides/hints.mdx
+++ b/apps/docs/src/content/guides/hints.mdx
@@ -152,8 +152,8 @@ const productHints = hints({
 
 Hints and tours coexist without any wiring: while a tour is running, the
 beacons hide and any open hint closes; when the tour ends, the beacons return
-on their own. Since hint popovers are regular Driver.js popovers, hooks like
-`onPopoverRender` work too. A common pattern is a hint that launches the tour:
+on their own. A common pattern is a hint whose button launches the tour,
+using `onButtonClick` to take over the button:
 
 ```js
 const tour = driver({ steps: [...] });
@@ -166,14 +166,10 @@ const productHints = hints({
       popover: {
         title: "New dashboard",
         description: "Want a quick walkthrough?",
-        onPopoverRender: (popover, { hints: instance }) => {
-          const button = document.createElement("button");
-          button.innerText = "Take the tour";
-          button.addEventListener("click", () => {
-            instance.close();
-            tour.drive();
-          });
-          popover.footerButtons.prepend(button);
+        buttonText: "Take the tour",
+        onButtonClick: (element, hint, { hints: instance }) => {
+          instance.close();
+          tour.drive();
         },
       },
     },
@@ -181,6 +177,9 @@ const productHints = hints({
 });
 ```
 
+Since hint popovers are regular Driver.js popovers, `onPopoverRender` works
+too when you need additional buttons or custom markup, exactly like in tours.
+
 ## Options
 
 Configuration passed to `hints()`: