@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 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 pins to whichever side it is let go near; a double-click
246
- on the header puts it back. Where it was left is remembered, so the next report opens there.
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
+ }