@panyam/tsappkit 0.7.6 → 0.7.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -61
- package/dist/index.d.mts +209 -90
- package/dist/index.d.ts +209 -90
- package/dist/index.js +377 -4
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +377 -5
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
- package/src/LCMComponent.ts +24 -77
- package/src/LifecycleController.ts +16 -13
- package/src/index.ts +15 -0
- package/src/tour/Tour.ts +316 -0
- package/src/tour/geometry.ts +113 -0
- package/src/tour/overlay.ts +178 -0
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
// The tour's DOM: a dimmed layer with holes cut by an even-odd clip-path, a ring round each target,
|
|
2
|
+
// and the step's panel. A clipped-away area isn't hit-tested, so input in a hole reaches the element
|
|
3
|
+
// under it untouched (hover, focus, drag), and input anywhere else lands on the layer and stops there.
|
|
4
|
+
import { holePath, placePanel, type Rect, unionRects } from "./geometry";
|
|
5
|
+
|
|
6
|
+
/** The panel's button labels, for an app that isn't in English. */
|
|
7
|
+
export interface TourLabels {
|
|
8
|
+
next: string;
|
|
9
|
+
done: string;
|
|
10
|
+
showMe: string;
|
|
11
|
+
close: string;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export const DEFAULT_LABELS: TourLabels = { next: "Next", done: "Done", showMe: "Show me", close: "End tour" };
|
|
15
|
+
|
|
16
|
+
/** What the panel shows for one step. */
|
|
17
|
+
export interface PanelView {
|
|
18
|
+
index: number;
|
|
19
|
+
count: number;
|
|
20
|
+
title?: string;
|
|
21
|
+
text: string;
|
|
22
|
+
next: boolean;
|
|
23
|
+
showMe: boolean;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
const STYLE_ATTR = "data-tsappkit-tour-style";
|
|
27
|
+
|
|
28
|
+
// Every color and size is a custom property with a fallback, so an app themes the tour by setting
|
|
29
|
+
// them on :root (or on .tsappkit-tour) without fighting this sheet's specificity.
|
|
30
|
+
const CSS = `
|
|
31
|
+
.tsappkit-tour { position: fixed; inset: 0; z-index: var(--tsappkit-tour-z, 2147483000); pointer-events: none; }
|
|
32
|
+
.tsappkit-tour-dim { position: absolute; inset: 0; pointer-events: auto; background: var(--tsappkit-tour-dim, rgba(2, 6, 23, .6)); }
|
|
33
|
+
.tsappkit-tour-ring { position: absolute; pointer-events: none; border-radius: var(--tsappkit-tour-ring-radius, 6px);
|
|
34
|
+
box-shadow: 0 0 0 2px var(--tsappkit-tour-accent, #3b82f6); }
|
|
35
|
+
.tsappkit-tour-panel { position: absolute; pointer-events: auto; box-sizing: border-box;
|
|
36
|
+
width: min(var(--tsappkit-tour-panel-width, 360px), calc(100vw - 32px)); padding: 12px 16px 14px;
|
|
37
|
+
border-radius: var(--tsappkit-tour-panel-radius, 10px); font: var(--tsappkit-tour-font, 14px/1.5 system-ui, sans-serif);
|
|
38
|
+
background: var(--tsappkit-tour-panel-bg, #ffffff); color: var(--tsappkit-tour-panel-fg, #0f172a);
|
|
39
|
+
box-shadow: 0 12px 32px rgba(0, 0, 0, .35); }
|
|
40
|
+
.tsappkit-tour-head { display: flex; align-items: center; justify-content: space-between; gap: 8px;
|
|
41
|
+
font-size: .85em; opacity: .75; }
|
|
42
|
+
.tsappkit-tour-close { all: unset; cursor: pointer; font-size: 1.4em; line-height: 1; padding: 0 4px; }
|
|
43
|
+
.tsappkit-tour-close:focus-visible, .tsappkit-tour-actions button:focus-visible {
|
|
44
|
+
outline: 2px solid var(--tsappkit-tour-accent, #3b82f6); outline-offset: 2px; }
|
|
45
|
+
.tsappkit-tour-title { font-weight: 600; margin: 4px 0 0; }
|
|
46
|
+
.tsappkit-tour-text { margin: 4px 0 0; }
|
|
47
|
+
.tsappkit-tour-actions { display: flex; justify-content: flex-end; gap: 8px; margin-top: 10px; }
|
|
48
|
+
.tsappkit-tour-actions:empty { display: none; }
|
|
49
|
+
.tsappkit-tour-actions button { font: inherit; cursor: pointer; padding: 4px 12px; border-radius: 6px;
|
|
50
|
+
border: 1px solid var(--tsappkit-tour-accent, #3b82f6); background: transparent; color: inherit; }
|
|
51
|
+
.tsappkit-tour-actions .tsappkit-tour-next { background: var(--tsappkit-tour-accent, #3b82f6); color: var(--tsappkit-tour-accent-fg, #ffffff); }
|
|
52
|
+
@media (prefers-color-scheme: dark) {
|
|
53
|
+
.tsappkit-tour-panel { background: var(--tsappkit-tour-panel-bg, #1e293b); color: var(--tsappkit-tour-panel-fg, #e2e8f0); }
|
|
54
|
+
}
|
|
55
|
+
`;
|
|
56
|
+
|
|
57
|
+
// Pointer input that misses the holes stops at the overlay, so an app's document-level listeners
|
|
58
|
+
// (close-on-outside-click, say) don't see it either.
|
|
59
|
+
const SWALLOWED = ["pointerdown", "pointerup", "mousedown", "mouseup", "click", "dblclick", "contextmenu"];
|
|
60
|
+
|
|
61
|
+
export class TourOverlay {
|
|
62
|
+
readonly root: HTMLElement;
|
|
63
|
+
private readonly dim: HTMLElement;
|
|
64
|
+
private readonly rings: HTMLElement;
|
|
65
|
+
readonly panel: HTMLElement;
|
|
66
|
+
private readonly count: HTMLElement;
|
|
67
|
+
private readonly title: HTMLElement;
|
|
68
|
+
private readonly text: HTMLElement;
|
|
69
|
+
private readonly actions: HTMLElement;
|
|
70
|
+
private key = "";
|
|
71
|
+
|
|
72
|
+
constructor(
|
|
73
|
+
private readonly doc: Document,
|
|
74
|
+
private readonly labels: TourLabels,
|
|
75
|
+
private readonly on: { close(): void; next(): void; showMe(): void },
|
|
76
|
+
) {
|
|
77
|
+
if (!doc.head.querySelector(`style[${STYLE_ATTR}]`)) {
|
|
78
|
+
const style = doc.createElement("style");
|
|
79
|
+
style.setAttribute(STYLE_ATTR, "");
|
|
80
|
+
style.textContent = CSS;
|
|
81
|
+
doc.head.prepend(style);
|
|
82
|
+
}
|
|
83
|
+
const el = (tag: string, cls: string, parent?: HTMLElement) => {
|
|
84
|
+
const e = doc.createElement(tag);
|
|
85
|
+
e.className = cls;
|
|
86
|
+
parent?.append(e);
|
|
87
|
+
return e;
|
|
88
|
+
};
|
|
89
|
+
this.root = el("div", "tsappkit-tour");
|
|
90
|
+
this.dim = el("div", "tsappkit-tour-dim", this.root);
|
|
91
|
+
this.rings = el("div", "tsappkit-tour-rings", this.root);
|
|
92
|
+
this.panel = el("div", "tsappkit-tour-panel", this.root);
|
|
93
|
+
this.panel.setAttribute("role", "dialog");
|
|
94
|
+
this.panel.setAttribute("aria-label", "Tour");
|
|
95
|
+
const head = el("div", "tsappkit-tour-head", this.panel);
|
|
96
|
+
this.count = el("span", "tsappkit-tour-count", head);
|
|
97
|
+
const close = el("button", "tsappkit-tour-close", head) as HTMLButtonElement;
|
|
98
|
+
close.type = "button";
|
|
99
|
+
close.textContent = "×";
|
|
100
|
+
close.setAttribute("aria-label", labels.close);
|
|
101
|
+
close.addEventListener("click", () => this.on.close());
|
|
102
|
+
this.title = el("div", "tsappkit-tour-title", this.panel);
|
|
103
|
+
this.text = el("p", "tsappkit-tour-text", this.panel);
|
|
104
|
+
this.text.setAttribute("aria-live", "polite");
|
|
105
|
+
this.actions = el("div", "tsappkit-tour-actions", this.panel);
|
|
106
|
+
|
|
107
|
+
for (const type of SWALLOWED) this.root.addEventListener(type, (e) => e.stopPropagation());
|
|
108
|
+
// Scrolling outside the holes would move the page under a reader who can't otherwise reach it.
|
|
109
|
+
const block = (e: Event) => e.preventDefault();
|
|
110
|
+
this.dim.addEventListener("wheel", block, { passive: false });
|
|
111
|
+
this.dim.addEventListener("touchmove", block, { passive: false });
|
|
112
|
+
doc.body.append(this.root);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** Puts a step's text and buttons in the panel. */
|
|
116
|
+
show(step: string, view: PanelView): void {
|
|
117
|
+
this.root.dataset.tourStep = step;
|
|
118
|
+
this.count.textContent = `${view.index + 1} of ${view.count}`;
|
|
119
|
+
this.title.textContent = view.title ?? "";
|
|
120
|
+
this.title.hidden = !view.title;
|
|
121
|
+
this.text.textContent = view.text;
|
|
122
|
+
this.actions.replaceChildren();
|
|
123
|
+
const button = (label: string, cls: string, click: () => void) => {
|
|
124
|
+
const b = this.doc.createElement("button");
|
|
125
|
+
b.type = "button";
|
|
126
|
+
b.className = cls;
|
|
127
|
+
b.textContent = label;
|
|
128
|
+
b.addEventListener("click", click);
|
|
129
|
+
this.actions.append(b);
|
|
130
|
+
};
|
|
131
|
+
if (view.showMe) button(this.labels.showMe, "tsappkit-tour-showme", () => this.on.showMe());
|
|
132
|
+
if (view.next) {
|
|
133
|
+
const last = view.index + 1 === view.count;
|
|
134
|
+
button(last ? this.labels.done : this.labels.next, "tsappkit-tour-next", () => this.on.next());
|
|
135
|
+
}
|
|
136
|
+
this.key = "";
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Cuts one hole per rect (already padded, in viewport coordinates) and places the panel clear of
|
|
141
|
+
* them. Cheap to call every frame: it only touches the DOM when the holes, the viewport or the
|
|
142
|
+
* panel's size changed.
|
|
143
|
+
*/
|
|
144
|
+
setHoles(rects: readonly Rect[]): void {
|
|
145
|
+
const vw = this.doc.documentElement.clientWidth;
|
|
146
|
+
const vh = this.doc.documentElement.clientHeight;
|
|
147
|
+
const pw = this.panel.offsetWidth;
|
|
148
|
+
const ph = this.panel.offsetHeight;
|
|
149
|
+
const key = `${vw}x${vh} ${pw}x${ph} ` + rects.map((r) => `${r.x},${r.y},${r.width},${r.height}`).join(" ");
|
|
150
|
+
if (key === this.key) return;
|
|
151
|
+
this.key = key;
|
|
152
|
+
|
|
153
|
+
const holes = unionRects(rects);
|
|
154
|
+
this.dim.style.clipPath = `path(evenodd, "${holePath(vw, vh, holes)}")`;
|
|
155
|
+
this.root.dataset.tourHoles = String(holes.length);
|
|
156
|
+
// One ring per hole after the union, so padded rows that overlap get one outline, not one each.
|
|
157
|
+
while (this.rings.children.length > holes.length) this.rings.lastElementChild!.remove();
|
|
158
|
+
while (this.rings.children.length < holes.length) {
|
|
159
|
+
const ring = this.doc.createElement("div");
|
|
160
|
+
ring.className = "tsappkit-tour-ring";
|
|
161
|
+
this.rings.append(ring);
|
|
162
|
+
}
|
|
163
|
+
holes.forEach((r, i) => {
|
|
164
|
+
const s = (this.rings.children[i] as HTMLElement).style;
|
|
165
|
+
s.left = `${r.x}px`;
|
|
166
|
+
s.top = `${r.y}px`;
|
|
167
|
+
s.width = `${r.width}px`;
|
|
168
|
+
s.height = `${r.height}px`;
|
|
169
|
+
});
|
|
170
|
+
const at = placePanel(rects, vw, vh, pw, ph);
|
|
171
|
+
this.panel.style.left = `${at.x}px`;
|
|
172
|
+
this.panel.style.top = `${at.y}px`;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
destroy(): void {
|
|
176
|
+
this.root.remove();
|
|
177
|
+
}
|
|
178
|
+
}
|