@daybook/feedback 1.2.1 → 1.2.3
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 +74 -3
- package/dist/clearance.d.ts +73 -0
- package/dist/clearance.js +154 -0
- package/dist/feedback.js +128 -46
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/types.d.ts +32 -0
- package/dist/widget.d.ts +90 -10
- package/dist/widget.js +457 -132
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -227,7 +227,15 @@ three days later when the reporter has moved on.
|
|
|
227
227
|
- **Breadcrumbs** — the last 40 navigations, clicks, console errors and failed or slow requests.
|
|
228
228
|
- **A screenshot**, if the reporter ticks "Capture the screen" and consents to the browser's share
|
|
229
229
|
prompt. The widget hides itself for the frame, so the picture is of the page underneath rather
|
|
230
|
-
than of the form that was just filled in
|
|
230
|
+
than of the form that was just filled in — and if the reporter pinned an element, that element is
|
|
231
|
+
ringed in the picture.
|
|
232
|
+
|
|
233
|
+
The ring is the difference between a report you can act on and one you have to reconstruct. A
|
|
234
|
+
selector and a text snapshot tell you which node; they do not tell you which of the forty things
|
|
235
|
+
on that screen the sentence is about. It is drawn in the widget's own layer, never on your page:
|
|
236
|
+
no style of yours is touched, nothing reflows, and there is no undo to get wrong. The rest of the
|
|
237
|
+
page is left exactly as it was — no dimming — because the screenshot is also the record of what
|
|
238
|
+
the page looked like, and a report about a colour should not arrive with the colours changed.
|
|
231
239
|
|
|
232
240
|
`screenshots` decides what the composer offers, and takes three values:
|
|
233
241
|
|
|
@@ -240,10 +248,47 @@ three days later when the reporter has moved on.
|
|
|
240
248
|
There is no setting that shows the control and then ignores it. A tick box that does nothing is
|
|
241
249
|
worse than no tick box.
|
|
242
250
|
|
|
251
|
+
## Where it sits
|
|
252
|
+
|
|
253
|
+
`placement` puts the widget in a corner: `bottom-right` (the default), `bottom-left`, `top-right`
|
|
254
|
+
or `top-left`. Set here it overrides the corner chosen in the workspace's own settings, which is
|
|
255
|
+
the right way round — the workspace owner is choosing a default for every install, and whoever
|
|
256
|
+
writes this line is looking at the page.
|
|
257
|
+
|
|
258
|
+
```js
|
|
259
|
+
init({ ingestKey: '...', placement: 'bottom-left' })
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### It moves out of your other buttons' way
|
|
263
|
+
|
|
264
|
+
Most pages already have something in the bottom-right corner: a chat bubble, a back-to-top arrow,
|
|
265
|
+
a cookie notice. The widget looks at what is painted in the corner it is about to occupy and stacks
|
|
266
|
+
above it rather than on it — including things that are not there yet, like a back-to-top button that
|
|
267
|
+
appears once the reporter scrolls, which is re-checked on scroll and whenever the page changes.
|
|
268
|
+
|
|
269
|
+
There is no list of selectors involved and there will not be one: what a chat bubble and a
|
|
270
|
+
back-to-top button have in common is not a class name, it is being fixed, painted and small in the
|
|
271
|
+
corner. Anything larger than a quarter of the viewport is treated as scenery — a modal backdrop is
|
|
272
|
+
not something to politely stack above — and if getting clear would mean moving more than a third of
|
|
273
|
+
the way up the page, it stays put and overlaps instead.
|
|
274
|
+
|
|
275
|
+
Turn it off with `avoidOverlap: false` if your page positions things by measuring ours, or if the
|
|
276
|
+
movement bothers you more than the overlap would.
|
|
277
|
+
|
|
243
278
|
## Moving the panel
|
|
244
279
|
|
|
245
|
-
The composer is dragged by its header and
|
|
246
|
-
|
|
280
|
+
The composer is dragged by its header, and lands against whichever side of the window it is let go
|
|
281
|
+
nearest — only that axis pins, so dragging it to the left edge halfway down leaves it halfway down.
|
|
282
|
+
A double-click on the header puts it back.
|
|
283
|
+
|
|
284
|
+
**A drag lasts for one report.** Sending resets it, so does closing, and the next report opens where
|
|
285
|
+
`placement` says. It used to be remembered across visits, which sounds helpful and is not: the
|
|
286
|
+
widget then turns up somewhere different on every page, and the somewhere is wherever it was last
|
|
287
|
+
shoved aside — a position chosen to be temporary.
|
|
288
|
+
|
|
289
|
+
The confirmation always appears at home, never where the panel was dragged to. The reporter moved
|
|
290
|
+
the panel to see what was under it; putting the receipt back over that same spot answers a question
|
|
291
|
+
nobody asked and covers the thing they moved it for.
|
|
247
292
|
|
|
248
293
|
It closes on the cross or on Cancel, and on nothing else — not Escape, not a click on the page
|
|
249
294
|
behind it. Every one of those gestures gets pressed while a report is being written, and each of
|
|
@@ -288,6 +333,32 @@ await pm.report('Checkout threw', { // a caught error, no user present
|
|
|
288
333
|
|
|
289
334
|
`report()` takes no screenshot: there is nobody there to consent to a screen share.
|
|
290
335
|
|
|
336
|
+
## The look is set in Daybook, not in code
|
|
337
|
+
|
|
338
|
+
Everything about the widget's appearance lives on the integration, so it is changed on the Feedback
|
|
339
|
+
widget page in Daybook and takes effect on every install of that key without a deploy:
|
|
340
|
+
|
|
341
|
+
| | |
|
|
342
|
+
|---|---|
|
|
343
|
+
| Button style | `pill`, `pill-icon`, `icon`, `text`, `outline` |
|
|
344
|
+
| Button text | Anything up to 24 characters. Defaults to "Feedback" |
|
|
345
|
+
| Colour scheme | `auto` (the default), `light`, `dark` |
|
|
346
|
+
| Corner | Bottom right by default — and `placement` in `init()` overrides it |
|
|
347
|
+
| Accent | Any CSS colour |
|
|
348
|
+
|
|
349
|
+
**Auto is the default and is the one to keep.** The widget is a guest on your page, and your page is
|
|
350
|
+
already light or dark for that reader; following their own setting is almost always right. Pin it
|
|
351
|
+
only when your app is one or the other regardless of the system.
|
|
352
|
+
|
|
353
|
+
The five button styles exist because one button cannot be right for every page. A product with its
|
|
354
|
+
own bold chat bubble does not want a second bold pill beside it; a spare documentation site does not
|
|
355
|
+
want a filled button at all; a dense application usually wants the smallest possible mark. All five
|
|
356
|
+
keep the same hit area in the same corner, so nothing else about the widget changes with the choice.
|
|
357
|
+
|
|
358
|
+
If you are building your own settings screen, `previewLauncher(element, theme)` draws the real
|
|
359
|
+
button — the real stylesheet, in a shadow root — so a preview cannot drift from the thing it
|
|
360
|
+
previews.
|
|
361
|
+
|
|
291
362
|
## Theming, but not styling
|
|
292
363
|
|
|
293
364
|
The widget renders in a shadow root. A host page's `* { }` reset, its `button { all: unset }`, or its
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Getting out of the way of the host page's own floating furniture.
|
|
3
|
+
*
|
|
4
|
+
* A launcher pinned to the bottom-right corner is pinned to the same corner every other widget on
|
|
5
|
+
* the web chose: a chat bubble, a cookie bar's dismiss, a back-to-top arrow. On a page that already
|
|
6
|
+
* has one, ours lands on top of it, and the reporter is left with two controls sharing one square of
|
|
7
|
+
* screen — usually with theirs underneath, since we deliberately sit high in the stacking order.
|
|
8
|
+
*
|
|
9
|
+
* So before rendering, we look at what is already there and stack above it.
|
|
10
|
+
*
|
|
11
|
+
* <h3>Looking, not guessing</h3>
|
|
12
|
+
*
|
|
13
|
+
* There is no list of selectors here and there should not be one. `.intercom-launcher`,
|
|
14
|
+
* `#hubspot-messages-iframe-container`, `.crisp-client` — a list like that is a promise to keep
|
|
15
|
+
* chasing other people's class names, and it answers nothing about the bespoke button somebody's
|
|
16
|
+
* designer added last week. What every one of them has in common is not a name: it is being
|
|
17
|
+
* painted, fixed, and small, in the corner we want. That is a question the browser can answer
|
|
18
|
+
* directly, so we ask it — elementsFromPoint over the corner we are about to occupy.
|
|
19
|
+
*
|
|
20
|
+
* <h3>The one that is not there yet</h3>
|
|
21
|
+
*
|
|
22
|
+
* Back-to-top buttons are the hard case, and the common one: they do not exist, or are hidden, until
|
|
23
|
+
* the reporter scrolls. A measurement taken once at startup sees nothing and is wrong for the rest
|
|
24
|
+
* of the visit — which is precisely when somebody is deep in a page and wants to report something.
|
|
25
|
+
*
|
|
26
|
+
* The answer is to keep asking: on scroll, on resize, and when the DOM changes. All three are cheap
|
|
27
|
+
* because the probe is a fixed handful of hit tests rather than a walk of the document, and the
|
|
28
|
+
* caller throttles them into one measurement per frame at most.
|
|
29
|
+
*
|
|
30
|
+
* <h3>Measured from home, always</h3>
|
|
31
|
+
*
|
|
32
|
+
* The probe reads the corner the widget was CONFIGURED into, never the corner it has been pushed to.
|
|
33
|
+
* Reading its own current position would make the measurement depend on its own last answer: shift
|
|
34
|
+
* up to clear a chat bubble, and the next probe finds the space below newly empty and shifts back
|
|
35
|
+
* down onto it, for ever. Measuring the fixed home makes the answer a property of the page.
|
|
36
|
+
*/
|
|
37
|
+
export interface Slot {
|
|
38
|
+
/** The home corner's box, in viewport coordinates. */
|
|
39
|
+
left: number;
|
|
40
|
+
right: number;
|
|
41
|
+
top: number;
|
|
42
|
+
bottom: number;
|
|
43
|
+
/** Which edge the offset is measured from — the side we would grow away from. */
|
|
44
|
+
v: 'top' | 'bottom';
|
|
45
|
+
}
|
|
46
|
+
export interface Box {
|
|
47
|
+
top: number;
|
|
48
|
+
bottom: number;
|
|
49
|
+
left: number;
|
|
50
|
+
right: number;
|
|
51
|
+
}
|
|
52
|
+
export interface Viewport {
|
|
53
|
+
width: number;
|
|
54
|
+
height: number;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* How far to shift, given what is in the way.
|
|
58
|
+
*
|
|
59
|
+
* Pure, and exported for that reason: the arithmetic is the part with the off-by-one in it, and it
|
|
60
|
+
* is the part that can be tested without a browser.
|
|
61
|
+
*/
|
|
62
|
+
export declare function shiftFor(slot: Slot, boxes: Box[], viewport: Viewport): number;
|
|
63
|
+
/**
|
|
64
|
+
* What is painted in the corner we want, right now.
|
|
65
|
+
*
|
|
66
|
+
* elementsFromPoint rather than a query: it answers with what the browser would actually hit,
|
|
67
|
+
* through shadow roots and whatever the host's stacking order turned out to be, and it costs a hit
|
|
68
|
+
* test rather than a walk. It skips `pointer-events: none`, which is the correct bias — something
|
|
69
|
+
* the reporter cannot click is something we are not stealing a click from.
|
|
70
|
+
*/
|
|
71
|
+
export declare function obstructions(slot: Slot, ours: Element, viewport: Viewport): Box[];
|
|
72
|
+
/** The whole question in one call: how far out of the way to move, in pixels. */
|
|
73
|
+
export declare function measureClearance(slot: Slot, ours: Element): number;
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Getting out of the way of the host page's own floating furniture.
|
|
3
|
+
*
|
|
4
|
+
* A launcher pinned to the bottom-right corner is pinned to the same corner every other widget on
|
|
5
|
+
* the web chose: a chat bubble, a cookie bar's dismiss, a back-to-top arrow. On a page that already
|
|
6
|
+
* has one, ours lands on top of it, and the reporter is left with two controls sharing one square of
|
|
7
|
+
* screen — usually with theirs underneath, since we deliberately sit high in the stacking order.
|
|
8
|
+
*
|
|
9
|
+
* So before rendering, we look at what is already there and stack above it.
|
|
10
|
+
*
|
|
11
|
+
* <h3>Looking, not guessing</h3>
|
|
12
|
+
*
|
|
13
|
+
* There is no list of selectors here and there should not be one. `.intercom-launcher`,
|
|
14
|
+
* `#hubspot-messages-iframe-container`, `.crisp-client` — a list like that is a promise to keep
|
|
15
|
+
* chasing other people's class names, and it answers nothing about the bespoke button somebody's
|
|
16
|
+
* designer added last week. What every one of them has in common is not a name: it is being
|
|
17
|
+
* painted, fixed, and small, in the corner we want. That is a question the browser can answer
|
|
18
|
+
* directly, so we ask it — elementsFromPoint over the corner we are about to occupy.
|
|
19
|
+
*
|
|
20
|
+
* <h3>The one that is not there yet</h3>
|
|
21
|
+
*
|
|
22
|
+
* Back-to-top buttons are the hard case, and the common one: they do not exist, or are hidden, until
|
|
23
|
+
* the reporter scrolls. A measurement taken once at startup sees nothing and is wrong for the rest
|
|
24
|
+
* of the visit — which is precisely when somebody is deep in a page and wants to report something.
|
|
25
|
+
*
|
|
26
|
+
* The answer is to keep asking: on scroll, on resize, and when the DOM changes. All three are cheap
|
|
27
|
+
* because the probe is a fixed handful of hit tests rather than a walk of the document, and the
|
|
28
|
+
* caller throttles them into one measurement per frame at most.
|
|
29
|
+
*
|
|
30
|
+
* <h3>Measured from home, always</h3>
|
|
31
|
+
*
|
|
32
|
+
* The probe reads the corner the widget was CONFIGURED into, never the corner it has been pushed to.
|
|
33
|
+
* Reading its own current position would make the measurement depend on its own last answer: shift
|
|
34
|
+
* up to clear a chat bubble, and the next probe finds the space below newly empty and shifts back
|
|
35
|
+
* down onto it, for ever. Measuring the fixed home makes the answer a property of the page.
|
|
36
|
+
*/
|
|
37
|
+
/** Space left between us and whatever we are stacking above. */
|
|
38
|
+
const GAP = 12;
|
|
39
|
+
/**
|
|
40
|
+
* The most we will move.
|
|
41
|
+
*
|
|
42
|
+
* Past this the cure is worse than the overlap: a widget a third of the way up someone's page reads
|
|
43
|
+
* as broken, and a chat panel somebody has OPENED is full height, which would otherwise push us off
|
|
44
|
+
* the top of the screen. Beyond the cap we stay home and overlap, which at least looks deliberate.
|
|
45
|
+
*/
|
|
46
|
+
const MAX_SHIFT = 0.35;
|
|
47
|
+
/**
|
|
48
|
+
* How far apart the hit tests are, across and up. Smaller finds smaller furniture; larger costs less.
|
|
49
|
+
*
|
|
50
|
+
* The first version sampled three columns — both edges and the middle — and missed a 60px chat
|
|
51
|
+
* bubble sitting between two of them, which is the single most common thing this exists to avoid.
|
|
52
|
+
* A grid only has to TOUCH a candidate once, since the element's own rect is what gets measured
|
|
53
|
+
* afterwards, but it does have to touch it: the spacing has to be smaller than the smallest thing
|
|
54
|
+
* worth dodging, not smaller than the area being searched.
|
|
55
|
+
*/
|
|
56
|
+
const STEP = 32;
|
|
57
|
+
/**
|
|
58
|
+
* Anything bigger than this share of the viewport is scenery, not furniture.
|
|
59
|
+
*
|
|
60
|
+
* A modal backdrop, a cookie wall, a sticky header spanning the page — none of them are things to
|
|
61
|
+
* politely stack above, and treating one as furniture would launch us into the middle of the page.
|
|
62
|
+
*/
|
|
63
|
+
const MAX_AREA = 0.25;
|
|
64
|
+
/**
|
|
65
|
+
* How far to shift, given what is in the way.
|
|
66
|
+
*
|
|
67
|
+
* Pure, and exported for that reason: the arithmetic is the part with the off-by-one in it, and it
|
|
68
|
+
* is the part that can be tested without a browser.
|
|
69
|
+
*/
|
|
70
|
+
export function shiftFor(slot, boxes, viewport) {
|
|
71
|
+
let taken = 0;
|
|
72
|
+
for (const box of boxes) {
|
|
73
|
+
// Only what actually sits in our column. A button in the opposite corner is not our problem.
|
|
74
|
+
if (box.right <= slot.left || box.left >= slot.right)
|
|
75
|
+
continue;
|
|
76
|
+
// How far the obstruction reaches from our edge towards the middle of the screen.
|
|
77
|
+
const reach = slot.v === 'bottom' ? viewport.height - box.top : box.bottom;
|
|
78
|
+
if (reach > taken)
|
|
79
|
+
taken = reach;
|
|
80
|
+
}
|
|
81
|
+
if (taken === 0)
|
|
82
|
+
return 0;
|
|
83
|
+
// Our own edge already clears part of it: the shift is only what is left over.
|
|
84
|
+
const occupied = slot.v === 'bottom' ? viewport.height - slot.bottom : slot.top;
|
|
85
|
+
const shift = Math.round(taken + GAP - occupied);
|
|
86
|
+
if (shift <= 0)
|
|
87
|
+
return 0;
|
|
88
|
+
return shift > viewport.height * MAX_SHIFT ? 0 : shift;
|
|
89
|
+
}
|
|
90
|
+
/** Whether an element is furniture we should stack above, rather than scenery or ourselves. */
|
|
91
|
+
function isFurniture(element, ours, viewport) {
|
|
92
|
+
if (element === ours || ours.contains(element) || element.contains(ours))
|
|
93
|
+
return false;
|
|
94
|
+
if (element === document.body || element === document.documentElement)
|
|
95
|
+
return false;
|
|
96
|
+
const style = getComputedStyle(element);
|
|
97
|
+
// Only what floats. Anything in the normal flow scrolls away on its own and is not competing for
|
|
98
|
+
// this corner — it merely happens to be under the point we sampled.
|
|
99
|
+
if (style.position !== 'fixed' && style.position !== 'sticky')
|
|
100
|
+
return false;
|
|
101
|
+
if (style.visibility === 'hidden' || style.display === 'none')
|
|
102
|
+
return false;
|
|
103
|
+
if (Number(style.opacity) === 0)
|
|
104
|
+
return false;
|
|
105
|
+
const rect = element.getBoundingClientRect();
|
|
106
|
+
if (rect.width < 8 || rect.height < 8)
|
|
107
|
+
return false;
|
|
108
|
+
if ((rect.width * rect.height) > viewport.width * viewport.height * MAX_AREA)
|
|
109
|
+
return false;
|
|
110
|
+
return true;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* What is painted in the corner we want, right now.
|
|
114
|
+
*
|
|
115
|
+
* elementsFromPoint rather than a query: it answers with what the browser would actually hit,
|
|
116
|
+
* through shadow roots and whatever the host's stacking order turned out to be, and it costs a hit
|
|
117
|
+
* test rather than a walk. It skips `pointer-events: none`, which is the correct bias — something
|
|
118
|
+
* the reporter cannot click is something we are not stealing a click from.
|
|
119
|
+
*/
|
|
120
|
+
export function obstructions(slot, ours, viewport) {
|
|
121
|
+
if (typeof document.elementsFromPoint !== 'function')
|
|
122
|
+
return [];
|
|
123
|
+
const found = new Map();
|
|
124
|
+
const xs = [];
|
|
125
|
+
for (let x = slot.left + 4; x < slot.right; x += STEP)
|
|
126
|
+
xs.push(x);
|
|
127
|
+
xs.push(slot.right - 4);
|
|
128
|
+
const limit = viewport.height * MAX_SHIFT;
|
|
129
|
+
for (let away = 0; away <= limit; away += STEP) {
|
|
130
|
+
const y = slot.v === 'bottom' ? slot.bottom - away : slot.top + away;
|
|
131
|
+
if (y < 0 || y > viewport.height)
|
|
132
|
+
break;
|
|
133
|
+
for (const x of xs) {
|
|
134
|
+
if (x < 0 || x > viewport.width)
|
|
135
|
+
continue;
|
|
136
|
+
for (const element of document.elementsFromPoint(x, y)) {
|
|
137
|
+
if (found.has(element))
|
|
138
|
+
continue;
|
|
139
|
+
if (!isFurniture(element, ours, viewport))
|
|
140
|
+
continue;
|
|
141
|
+
const rect = element.getBoundingClientRect();
|
|
142
|
+
found.set(element, {
|
|
143
|
+
top: rect.top, bottom: rect.bottom, left: rect.left, right: rect.right,
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
return [...found.values()];
|
|
149
|
+
}
|
|
150
|
+
/** The whole question in one call: how far out of the way to move, in pixels. */
|
|
151
|
+
export function measureClearance(slot, ours) {
|
|
152
|
+
const viewport = { width: window.innerWidth, height: window.innerHeight };
|
|
153
|
+
return shiftFor(slot, obstructions(slot, ours, viewport), viewport);
|
|
154
|
+
}
|