@botiverse/porthole 0.14.11 → 0.14.12
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/CHANGELOG.md +16 -0
- package/dist/annotate/types.d.ts +4 -2
- package/dist/annotate/types.js +2 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +8 -0
- package/dist/host/types.d.ts +11 -0
- package/dist/react/frame.d.ts +6 -0
- package/dist/react/frame.js +6 -0
- package/dist/react/view.js +1 -0
- package/dist/shell/annotate.d.ts +13 -3
- package/dist/shell/annotate.js +60 -10
- package/docs/ADOPTING.md +23 -4
- package/docs/DECISIONS.md +105 -1
- package/docs/DESIGN.md +11 -8
- package/docs/THREAT_MODEL.md +33 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +4 -2
- package/src/host/create-host.ts +8 -0
- package/src/host/types.ts +11 -0
- package/src/react/frame.tsx +12 -0
- package/src/react/view.tsx +1 -0
- package/src/shell/annotate.ts +61 -10
package/src/react/frame.tsx
CHANGED
|
@@ -497,6 +497,12 @@ export interface PortholeFrameHandle {
|
|
|
497
497
|
* `"annotations"` (the core's call throws; this never does).
|
|
498
498
|
*/
|
|
499
499
|
clearSelection(): void;
|
|
500
|
+
/**
|
|
501
|
+
* Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
|
|
502
|
+
* once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
|
|
503
|
+
* while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`.
|
|
504
|
+
*/
|
|
505
|
+
focusMark(id: string): void;
|
|
500
506
|
/**
|
|
501
507
|
* Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
|
|
502
508
|
* or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
|
|
@@ -812,6 +818,12 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
812
818
|
attempt(() => now.annotations.clearSelection(), own.current);
|
|
813
819
|
}
|
|
814
820
|
},
|
|
821
|
+
focusMark(id) {
|
|
822
|
+
const now = display.current;
|
|
823
|
+
if (now !== null) {
|
|
824
|
+
attempt(() => now.annotations.focusMark(id), own.current);
|
|
825
|
+
}
|
|
826
|
+
},
|
|
815
827
|
find(query, options) {
|
|
816
828
|
try {
|
|
817
829
|
checkFindQuery(query, options);
|
package/src/react/view.tsx
CHANGED
|
@@ -253,6 +253,7 @@ function InstanceView(props: PortholeViewProps): ReactElement | null {
|
|
|
253
253
|
ref,
|
|
254
254
|
(): PortholeFrameHandle => ({
|
|
255
255
|
clearSelection: () => shown.current?.clearSelection(),
|
|
256
|
+
focusMark: (id) => shown.current?.focusMark(id),
|
|
256
257
|
find: (query, options) =>
|
|
257
258
|
shown.current?.find(query, options) ?? Promise.resolve("unsupported"),
|
|
258
259
|
clearFind: () => shown.current?.clearFind(),
|
package/src/shell/annotate.ts
CHANGED
|
@@ -34,14 +34,37 @@ export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
|
|
|
34
34
|
return best;
|
|
35
35
|
}`;
|
|
36
36
|
|
|
37
|
+
/**
|
|
38
|
+
* What a marker is called (P133, P134), to whoever can't see it, spliced into the runtime: what it
|
|
39
|
+
* is, and the words it is on, in quotes. In English, whatever the page's language: the shell has no
|
|
40
|
+
* words of the host's. `anchor.label` stays as the host stores it (it is the host's to show): an
|
|
41
|
+
* element's starts with its tag (`describe`, "p#intro.lead Words"), so an element's words are its
|
|
42
|
+
* quote, cut where the label's are and marked so, or for one with no text of its own (an image's
|
|
43
|
+
* `alt`) what follows the tag in the label. An element with neither has no words.
|
|
44
|
+
*/
|
|
45
|
+
export const MARKER_NAME = String.raw`(mark) => {
|
|
46
|
+
const squash = (text) => String(text).replace(/\s+/g, " ").trim();
|
|
47
|
+
const anchor = mark.anchor;
|
|
48
|
+
const label = typeof anchor.label === "string" ? squash(anchor.label).slice(0, 120) : "";
|
|
49
|
+
let words = label;
|
|
50
|
+
if (anchor.kind === "element") {
|
|
51
|
+
const quote = anchor.selectors.filter((each) => each && each.type === "TextQuoteSelector")[0];
|
|
52
|
+
const said = quote && typeof quote.exact === "string" ? squash(quote.exact.slice(0, 300)) : "";
|
|
53
|
+
const space = label.indexOf(" ");
|
|
54
|
+
words = said.length > 40 ? said.slice(0, 40).trim() + "\u2026" : said !== "" ? said : space === -1 ? "" : label.slice(space + 1);
|
|
55
|
+
}
|
|
56
|
+
const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
|
|
57
|
+
return words === "" ? what : what + ' on "' + words + '"';
|
|
58
|
+
}`;
|
|
59
|
+
|
|
37
60
|
/**
|
|
38
61
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
39
62
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
40
63
|
* functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
|
|
41
64
|
* in one).
|
|
42
65
|
*
|
|
43
|
-
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`)
|
|
44
|
-
* reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
66
|
+
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
67
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
45
68
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
46
69
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
47
70
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -56,7 +79,8 @@ export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
|
|
|
56
79
|
* in the line's gutter), an element's on its corner; a click on it, or Enter or Space with the
|
|
57
80
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
58
81
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
59
|
-
* or without a count;
|
|
82
|
+
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
83
|
+
* tells nothing back;
|
|
60
84
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
61
85
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
62
86
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -87,6 +111,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
87
111
|
track: "porthole/annotate.track",
|
|
88
112
|
tracked: "porthole/annotate.tracked",
|
|
89
113
|
clearSelection: "porthole/annotate.clearSelection",
|
|
114
|
+
focusMark: "porthole/annotate.focusMark",
|
|
90
115
|
};
|
|
91
116
|
// The DOM's own functions, taken before content runs.
|
|
92
117
|
const elementFromPoint = Document.prototype.elementFromPoint;
|
|
@@ -97,6 +122,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
97
122
|
const createElementNS = Document.prototype.createElementNS;
|
|
98
123
|
const selectionOf = Document.prototype.getSelection;
|
|
99
124
|
const removeAllRanges = Selection.prototype.removeAllRanges;
|
|
125
|
+
const focusElement = HTMLElement.prototype.focus;
|
|
100
126
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
101
127
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
102
128
|
const rangeRects = Range.prototype.getClientRects;
|
|
@@ -401,13 +427,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
401
427
|
const markerWidth = (label) => Math.max(MARKER_HEIGHT, 23 + (label === "" ? 0 : 3 + label.length * 7));
|
|
402
428
|
// Compact (P105): the number alone, or the glyph alone for none, with less padding.
|
|
403
429
|
const compactWidth = (label) => (label === "" ? 21 : Math.max(MARKER_HEIGHT, 10 + label.length * 7));
|
|
404
|
-
|
|
405
|
-
// on. In English, whatever the page's language: the shell has no words of the host's.
|
|
406
|
-
const nameOf = (mark) => {
|
|
407
|
-
const words = typeof mark.anchor.label === "string" ? squash(mark.anchor.label).slice(0, LIMIT.label) : "";
|
|
408
|
-
const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
|
|
409
|
-
return words === "" ? what : what + " on " + words;
|
|
410
|
-
};
|
|
430
|
+
const nameOf = ${MARKER_NAME};
|
|
411
431
|
// A rect's last line with words on it: its last box with a width, else any with a size.
|
|
412
432
|
const lastBox = (rects) => {
|
|
413
433
|
let any = null;
|
|
@@ -1054,6 +1074,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1054
1074
|
// mark), nor before a run of changes settles; a focus asked for meanwhile waits for it.
|
|
1055
1075
|
let waitingForContent = false;
|
|
1056
1076
|
let pendingFocus = null;
|
|
1077
|
+
let pendingMarker = null;
|
|
1057
1078
|
const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
|
|
1058
1079
|
const scheduleAnchor = (all) => {
|
|
1059
1080
|
if (all) {
|
|
@@ -1092,6 +1113,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1092
1113
|
pendingFocus = null;
|
|
1093
1114
|
focus(id);
|
|
1094
1115
|
}
|
|
1116
|
+
if (pendingMarker !== null) {
|
|
1117
|
+
const id = pendingMarker;
|
|
1118
|
+
pendingMarker = null;
|
|
1119
|
+
focusMark(id);
|
|
1120
|
+
}
|
|
1095
1121
|
}, wait);
|
|
1096
1122
|
};
|
|
1097
1123
|
new MutationObserver((records) => {
|
|
@@ -1196,6 +1222,27 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1196
1222
|
report([{ mark, result: resultOf(mark, null, scroll) }], scroll);
|
|
1197
1223
|
};
|
|
1198
1224
|
|
|
1225
|
+
// The focus on a mark's marker, at the host's word (P134). Marks a show just replaced have no
|
|
1226
|
+
// markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
|
|
1227
|
+
// stepped aside for picking, is nothing to do. The kept function, so a page that patched
|
|
1228
|
+
// focus isn't handed the marker from inside the closed root. The shell's focus listener
|
|
1229
|
+
// lights it and brings it into view; nothing is told.
|
|
1230
|
+
const focusMark = (id) => {
|
|
1231
|
+
if (settling()) {
|
|
1232
|
+
pendingMarker = id;
|
|
1233
|
+
return;
|
|
1234
|
+
}
|
|
1235
|
+
if (mode.elements || !isShown(id)) {
|
|
1236
|
+
return;
|
|
1237
|
+
}
|
|
1238
|
+
for (let i = 0; i < markers.length; i += 1) {
|
|
1239
|
+
if (markers[i].id === id) {
|
|
1240
|
+
callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
|
|
1241
|
+
return;
|
|
1242
|
+
}
|
|
1243
|
+
}
|
|
1244
|
+
};
|
|
1245
|
+
|
|
1199
1246
|
// A marker's click (P104). The layer takes no pointer but on its markers, so a press whose
|
|
1200
1247
|
// target is the layer is on a marker: the content's handlers never see it (this listener
|
|
1201
1248
|
// runs before any of theirs), nor does what lies under it, and a click is reported. A press
|
|
@@ -1630,9 +1677,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1630
1677
|
}
|
|
1631
1678
|
break;
|
|
1632
1679
|
}
|
|
1680
|
+
case M.focusMark:
|
|
1681
|
+
focusMark(String(params.id));
|
|
1682
|
+
break;
|
|
1633
1683
|
case M.clear:
|
|
1634
1684
|
track(null);
|
|
1635
1685
|
pendingFocus = null;
|
|
1686
|
+
pendingMarker = null;
|
|
1636
1687
|
marks = [];
|
|
1637
1688
|
active = null;
|
|
1638
1689
|
hot = null;
|