mirror of
https://github.com/kamranahmedse/driver.js.git
synced 2026-10-30 19:27:40 +08:00
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.
This commit is contained in:
Kamran Ahmed
@@ -67,7 +67,7 @@ export function HintsSample(props: HintsSampleProps) {
|
||||
</span>
|
||||
</div>
|
||||
<p id={`${idPrefix}-summary`} className="m-0 text-sm text-gray-600">
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
<kbd>Escape</kbd> 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: [...] });
|
||||
|
||||
@@ -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.
|
||||
|
||||
<HintsSample
|
||||
idPrefix="overlay"
|
||||
config={{ overlay: true, overlayOpacity: 0.5 }}
|
||||
hints={[
|
||||
{
|
||||
element: "#overlay-export",
|
||||
id: "export",
|
||||
popover: {
|
||||
title: "Focus mode",
|
||||
description: "The Export button is spotlighted and still clickable; the rest of the page is dimmed.",
|
||||
},
|
||||
},
|
||||
{
|
||||
element: "#overlay-summary",
|
||||
id: "summary",
|
||||
beacon: { side: "left", align: "center" },
|
||||
popover: {
|
||||
title: "One at a time",
|
||||
description: "The other beacons wait under the dim. Close this hint to get back to them.",
|
||||
side: "bottom",
|
||||
},
|
||||
},
|
||||
]}
|
||||
client:load
|
||||
/>
|
||||
|
||||
```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:
|
||||
|
||||
<HintsSample
|
||||
@@ -69,7 +110,7 @@ const productHints = hints({
|
||||
|
||||
## Static beacons
|
||||
|
||||
Set `animate: false` on a hint — or on the instance-level `beacon` defaults —
|
||||
Set `animate: false` on a hint (or on the instance-level `beacon` defaults)
|
||||
for a still dot without the pulse. Users who prefer reduced motion get the
|
||||
still dot automatically.
|
||||
|
||||
@@ -144,51 +185,10 @@ const productHints = hints({
|
||||
});
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
<HintsSample
|
||||
idPrefix="overlay"
|
||||
config={{ overlay: true, overlayOpacity: 0.5 }}
|
||||
hints={[
|
||||
{
|
||||
element: "#overlay-export",
|
||||
id: "export",
|
||||
popover: {
|
||||
title: "Focus mode",
|
||||
description: "The Export button is spotlighted and still clickable; the rest of the page is dimmed.",
|
||||
},
|
||||
},
|
||||
{
|
||||
element: "#overlay-summary",
|
||||
id: "summary",
|
||||
beacon: { side: "left", align: "center" },
|
||||
popover: {
|
||||
title: "One at a time",
|
||||
description: "The other beacons wait under the dim. Close this hint to get back to them.",
|
||||
side: "bottom",
|
||||
},
|
||||
},
|
||||
]}
|
||||
client:load
|
||||
/>
|
||||
|
||||
```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:
|
||||
|
||||
<HintsSample
|
||||
|
||||
Reference in New Issue
Block a user