@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/dist/widget.d.ts CHANGED
@@ -37,6 +37,41 @@ export declare class FeedbackWidget {
37
37
  */
38
38
  setTheme(theme: FeedbackTheme | null): void;
39
39
  private launcherLabel;
40
+ /** The corner the workspace chose, if it chose one. The init option outranks it. */
41
+ private themePlacement;
42
+ /** Which of the five shapes the launcher takes. */
43
+ private buttonStyle;
44
+ /** How far the host page's own floating buttons push us out of that corner. */
45
+ private clearance;
46
+ /** Where the widget lives: the caller's choice, then the workspace's, then the bottom right. */
47
+ private get placement();
48
+ /**
49
+ * Writes the corner, plus whatever room the page's own furniture needs, as four numbers.
50
+ *
51
+ * Numbers rather than a keyword because a custom property holds a value, not a property name —
52
+ * "put it bottom left" has to be four offsets. They are computed together because the clearance
53
+ * is an addition to one of them, and `calc(auto + 12px)` is not a length.
54
+ *
55
+ * This used to be a lookup table, which is what kept a server-sent position out of the stylesheet:
56
+ * an unrecognised key found nothing. Nothing is looked up now, and the same property holds for a
57
+ * better reason — the value itself never reaches the CSS. Only the words `left`, `right`, `top`
58
+ * and `bottom`, chosen here, and two numbers.
59
+ */
60
+ private applyPlacement;
61
+ /** The box the widget would occupy if nothing were in its way. What the probe measures. */
62
+ private homeSlot;
63
+ /**
64
+ * Keeps out of the way of whatever else is in the corner, as that changes.
65
+ *
66
+ * Re-measured rather than measured once, because the button most likely to collide with ours is
67
+ * the one that is not there yet: a back-to-top arrow appears on scroll, a chat bubble loads a
68
+ * second after the page. Scroll, resize and DOM changes all trigger a re-read, coalesced into at
69
+ * most one per frame.
70
+ *
71
+ * Never while the composer is open. Moving a form out from under somebody's cursor mid-sentence
72
+ * is a worse thing to do to them than overlapping a button they are not currently using.
73
+ */
74
+ private watchClearance;
40
75
  /**
41
76
  * What the widget is allowed to do, from the handshake.
42
77
  *
@@ -69,21 +104,50 @@ export declare class FeedbackWidget {
69
104
  /** Whether the composer offers screen capture at all, and whether it starts ticked. */
70
105
  private capture;
71
106
  /**
72
- * Takes the widget off the screen and hands back the undo.
107
+ * Takes the widget off the screen, rings what the report is about, and hands back the undo.
73
108
  *
74
- * For the screen capture. Everything here lives in one host element, so hiding is one property —
75
- * and it is `visibility`, not `display`, because removing the panel from layout would reflow the
76
- * host page underneath it and the picture would be of a page that never existed.
109
+ * For the screen capture. It is `visibility`, not `display`, because removing the panel from
110
+ * layout would reflow the host page underneath it and the picture would be of a page that never
111
+ * existed.
112
+ *
113
+ * The UI hides but the host element stays visible, because the ring is drawn inside it. That is
114
+ * the whole reason to do it here rather than on the page: a report used to arrive as a selector,
115
+ * a text snapshot and a picture of a whole screen, leaving whoever read it to work out which of
116
+ * forty things on that screen the sentence was about. Now the picture says.
77
117
  */
78
118
  conceal(): () => void;
79
119
  /**
80
- * Where the reporter dragged the panel to, if they did.
120
+ * A ring over the pinned element, drawn in our own shadow root.
121
+ *
122
+ * Not on the element itself. Setting a style on somebody else's node means fighting their
123
+ * specificity, risking a reflow that changes the picture being taken, and owning the undo — and
124
+ * the undo is the part that bites: hidePrivate already exists to blur private fields for a frame,
125
+ * and its comment is about exactly this, that a page left permanently altered because a capture
126
+ * threw is worse than the bug being reported. A rectangle in our own layer touches nothing.
81
127
  *
82
- * Remembered across reports and across visits, because somebody who moved it off the thing they
83
- * are documenting will want it there for the next report too — and having to move it every time
84
- * is the friction that stops the second report being written.
128
+ * No scrim over the rest, tempting as it is. A screenshot is also the record of what the page
129
+ * looked like, and dimming it changes the colours in a report that may well be about the colours.
130
+ * The ring is doubled — red, white, red — so it carries on a dark page and on a light one without
131
+ * altering either.
132
+ *
133
+ * Resolved at capture time rather than at pick time: the composer may have been open for a while,
134
+ * and where the element is NOW is where the picture will show it.
135
+ */
136
+ private ringAnchor;
137
+ /**
138
+ * Where the reporter dragged the panel to, if they did — for this report only.
139
+ *
140
+ * It used to be remembered in localStorage, across reports and across visits, on the reasoning
141
+ * that somebody who moved it once would want it moved next time. In use that is not what it feels
142
+ * like: the widget turns up in a different place on every page of the app with no explanation of
143
+ * why, and the place it turns up is wherever it was last shoved out of the way — a position
144
+ * chosen to be temporary. A home you can move things away from is easier to live with than a
145
+ * position that drifts.
146
+ *
147
+ * So a drag lasts as long as the report. Sending resets it, closing resets it, and the next
148
+ * report opens where the install said it would.
85
149
  */
86
- private placement;
150
+ private dragged;
87
151
  /**
88
152
  * Makes the panel draggable by its header, and snaps it to a side when it is let go near one.
89
153
  *
@@ -92,7 +156,7 @@ export declare class FeedbackWidget {
92
156
  * one corner, the only way to do that was to close the widget, which loses what they had written.
93
157
  */
94
158
  private movable;
95
- /** Applies the remembered placement, or hands the panel back to the theme's corner. */
159
+ /** Applies the drag, if there is one, or hands the panel back to its home corner. */
96
160
  private place;
97
161
  private render;
98
162
  /**
@@ -151,3 +215,19 @@ export declare class FeedbackWidget {
151
215
  * selection, and a selection made inside a shadow root is not the document's.
152
216
  */
153
217
  export declare function copyText(text: string): Promise<boolean>;
218
+ /**
219
+ * Draws the launcher, and only the launcher, inside an element you own.
220
+ *
221
+ * For a settings screen that has to show what a theme will look like before anybody saves it. It is
222
+ * the real button with the real stylesheet in a real shadow root: a second implementation in the
223
+ * console's own CSS would be a picture of the widget rather than the widget, and would begin lying
224
+ * the first time either one changed.
225
+ *
226
+ * Nothing else comes with it — no handshake, no listeners, no page-level positioning — so it is
227
+ * safe to call ten times on one screen. Call it again to change the theme; it replaces what it drew.
228
+ */
229
+ export declare function previewLauncher(into: HTMLElement, theme?: FeedbackTheme): void;
230
+ /** The button shapes a workspace can choose between. Anything else falls back to the first. */
231
+ declare const BUTTON_STYLES: readonly ["pill", "pill-icon", "icon", "text", "outline"];
232
+ export type ButtonStyle = (typeof BUTTON_STYLES)[number];
233
+ export {};