From 7336c6709739cee0ffedb4709ede78cfb94dce59 Mon Sep 17 00:00:00 2001 From: Kamran Ahmed Date: Thu, 16 Jul 2026 21:04:35 +0100 Subject: [PATCH] Lead the hints examples with the overlay and drop the em dashes The Dimming the page sample moves to the top of Styling Hints. The em dashes across the hints docs copy, the demo component and the changelog entries are rephrased with plain punctuation. --- apps/docs/src/components/HintsSample.tsx | 2 +- apps/docs/src/content/guides/changelog.mdx | 8 +- apps/docs/src/content/guides/hints.mdx | 18 ++-- .../docs/src/content/guides/styling-hints.mdx | 90 +++++++++---------- 4 files changed, 59 insertions(+), 59 deletions(-) diff --git a/apps/docs/src/components/HintsSample.tsx b/apps/docs/src/components/HintsSample.tsx index 2541017..da64a5a 100644 --- a/apps/docs/src/components/HintsSample.tsx +++ b/apps/docs/src/components/HintsSample.tsx @@ -67,7 +67,7 @@ export function HintsSample(props: HintsSampleProps) {

- Revenue is up 12% quarter over quarter. Click the beacons to explore what changed — the page stays fully + Revenue is up 12% quarter over quarter. Click the beacons to explore what changed. The page stays fully interactive while they are shown.

diff --git a/apps/docs/src/content/guides/changelog.mdx b/apps/docs/src/content/guides/changelog.mdx index 2e7c954..56dde28 100644 --- a/apps/docs/src/content/guides/changelog.mdx +++ b/apps/docs/src/content/guides/changelog.mdx @@ -12,12 +12,12 @@ ships, these entries move under a versioned heading. ### Added -- Hints — pulsing beacons that open a popover on click; no overlay, the page - stays interactive. New `driver.js/hints` entry, ~5KB gzip. +- Hints: pulsing beacons that open a popover on click. No overlay by default, + the page stays interactive. New `driver.js/hints` entry, ~5KB gzip. [Guide](/docs/hints). ([#363](https://github.com/nilbuild/driver.js/issues/363)) - `--driver-hint-size` and `--driver-hint-color` CSS variables to style the beacons. -- Optional hint overlay (`overlay`, `overlayColor`, `overlayOpacity`) — dims the - page around the open hint's element, tour-style cutout included. +- Optional hint overlay (`overlay`, `overlayColor`, `overlayOpacity`) that dims + the page around the open hint's element, tour-style cutout included. - `sideEffects` field in package.json for better tree-shaking. ### Changed diff --git a/apps/docs/src/content/guides/hints.mdx b/apps/docs/src/content/guides/hints.mdx index a7e1d29..238acd5 100644 --- a/apps/docs/src/content/guides/hints.mdx +++ b/apps/docs/src/content/guides/hints.mdx @@ -1,6 +1,6 @@ --- title: "Hints" -description: "Add pulsing hint beacons to your UI with Driver.js. Users click a beacon to open a popover explaining the feature — no tour, no overlay, and the page stays fully interactive." +description: "Add pulsing hint beacons to your UI with Driver.js. Users click a beacon to open a popover explaining the feature. No tour, no overlay, and the page stays fully interactive." groupTitle: "Introduction" sort: 6 --- @@ -10,10 +10,10 @@ import { HintsSample } from "../../components/HintsSample.tsx"; Tours walk users through your product step by step. Hints do the opposite: they sit quietly on the page as pulsing beacons, and the user decides which ones to open, in any order, whenever they want. There is no overlay and nothing is -blocked — the page stays fully interactive. +blocked. The page stays fully interactive. Hints ship as their own entry, so tour-only users never load them. Import the -module and its stylesheet — the stylesheet is self-contained, so you don't need +module and its stylesheet. The stylesheet is self-contained, so you don't need `driver.css` unless you also use tours: ```js @@ -82,9 +82,9 @@ productHints.show(); The two are deliberately different: -- Closing — clicking the beacon again, clicking anywhere outside, or pressing +- Closing: clicking the beacon again, clicking anywhere outside, or pressing Escape closes the popover. The beacon stays, and the hint can be opened again. -- Dismissing — clicking the _Got it_ button removes the beacon entirely and +- Dismissing: clicking the _Got it_ button removes the beacon entirely and fires `onDismiss`. The hint is gone for the session. Only one hint popover is open at a time; opening another swaps it. @@ -92,7 +92,7 @@ Only one hint popover is open at a time; opening another swaps it. ## Remembering dismissals Driver.js keeps dismissals in memory for the session and stays out of the -storage business — `onDismiss` with stable `id`s is the hook, storage is yours: +storage business. `onDismiss` with stable `id`s is the hook, and storage is yours: ```js const dismissed = new Set(JSON.parse(localStorage.getItem("hints") ?? "[]")); @@ -110,7 +110,7 @@ productHints.show(); ## Beacon placement and styling -A beacon sits on one of twelve anchor points of its element's box — a `side` +A beacon sits on one of twelve anchor points of its element's box: a `side` (`top`, `right`, `bottom`, `left`) plus an `align` (`start`, `center`, `end`). The default is the top-right corner. Set `animate: false` for a static dot; the pulse also pauses automatically for users who prefer reduced motion. @@ -126,7 +126,7 @@ Size and colour come from CSS variables: ## Dimming the page -Pass `overlay: true` to dim the page while a hint is open — the hint reads +Pass `overlay: true` to dim the page while a hint is open. The hint reads exactly like a tour step: the element is cut out of the dim and stays interactive, the popover anchors to the element rather than the beacon, and the beacon itself steps aside while its popover is up. Everything else, @@ -147,7 +147,7 @@ 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: +`onPopoverRender` work too. A common pattern is a hint that launches the tour: ```js const tour = driver({ steps: [...] }); diff --git a/apps/docs/src/content/guides/styling-hints.mdx b/apps/docs/src/content/guides/styling-hints.mdx index f969c2e..4c33eb6 100644 --- a/apps/docs/src/content/guides/styling-hints.mdx +++ b/apps/docs/src/content/guides/styling-hints.mdx @@ -1,6 +1,6 @@ --- title: "Styling Hints" -description: "Customize Driver.js hint beacons and their popovers — colors, sizes, animation, button text, and fully themed popovers." +description: "Customize Driver.js hint beacons and their popovers: colors, sizes, animation, button text, and fully themed popovers." groupTitle: "Examples" sort: 6 --- @@ -11,9 +11,50 @@ Everything about a hint can be customized: the beacon's color, size and animation through CSS variables, and the popover through the same theming that tours use. If you haven't read the [Hints guide](/docs/hints) yet, start there. +## Dimming the page + +With `overlay: true` an open hint reads exactly like a tour step: the element +is spotlighted and stays interactive, the popover frames the element (the +beacon steps aside while it is up), and the other beacons wait under the +overlay. Clicking the dimmed page closes the hint. + + + +```js +const productHints = hints({ + overlay: true, + overlayOpacity: 0.5, + hints: [...], +}); +``` + ## Beacon color and size -Beacons read two CSS variables — set them globally on `.driver-hint`, or give +Beacons read two CSS variables. Set them globally on `.driver-hint`, or give individual beacons a `className` and scope the variables to it: - -```js -const productHints = hints({ - overlay: true, - overlayOpacity: 0.5, - hints: [...], -}); -``` - ## Theming the popover Hint popovers are regular Driver.js popovers, so `popoverClass` and the -[popover styling](/docs/styling-popover) techniques apply unchanged — here with +[popover styling](/docs/styling-popover) techniques apply unchanged, shown here with the same theme used across these docs: