@botiverse/porthole 0.14.14 → 0.14.16
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 +58 -0
- package/dist/annotate/types.d.ts +50 -1
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +26 -3
- package/dist/annotate/validate.js +64 -2
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +56 -6
- package/dist/host/types.d.ts +24 -3
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +20 -1
- package/dist/react/frame.js +59 -26
- package/dist/shell/annotate.d.ts +8 -2
- package/dist/shell/annotate.js +178 -11
- package/dist/shell/runtime.d.ts +10 -0
- package/dist/shell/runtime.js +72 -26
- package/docs/ADOPTING.md +50 -1
- package/docs/DECISIONS.md +370 -4
- package/docs/DESIGN.md +37 -6
- package/docs/THREAT_MODEL.md +32 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +47 -1
- package/src/annotate/validate.ts +82 -3
- package/src/host/create-host.ts +59 -11
- package/src/host/types.ts +29 -3
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +91 -33
- package/src/shell/annotate.ts +178 -11
- package/src/shell/runtime.ts +73 -26
package/dist/shell/annotate.js
CHANGED
|
@@ -77,7 +77,7 @@ export const WORD_LATE = String.raw `(at, now) => {
|
|
|
77
77
|
* in one).
|
|
78
78
|
*
|
|
79
79
|
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
80
|
-
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
80
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
|
|
81
81
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
82
82
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
83
83
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -103,7 +103,13 @@ export const WORD_LATE = String.raw `(at, now) => {
|
|
|
103
103
|
* followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
|
|
104
104
|
* them placed as the document scrolls, from one report and the followed mark's scroll;
|
|
105
105
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
106
|
-
* too (`lastLineDocumentRect`), so a host places its UI after them
|
|
106
|
+
* too (`lastLineDocumentRect`), so a host places its UI after them;
|
|
107
|
+
* - the selection followed (P138): what the last `selected` reported (the element picked, or the
|
|
108
|
+
* words selected) is kept while the host follows the selection (`track` with `selection`) or said
|
|
109
|
+
* at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
|
|
110
|
+
* it is drawn in the layer and its boxes are reported as a followed mark's are
|
|
111
|
+
* (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
|
|
112
|
+
* focus and no key.
|
|
107
113
|
*
|
|
108
114
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
109
115
|
* reports as UI hints only.
|
|
@@ -124,6 +130,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
124
130
|
activated: "porthole/annotate.activated",
|
|
125
131
|
track: "porthole/annotate.track",
|
|
126
132
|
tracked: "porthole/annotate.tracked",
|
|
133
|
+
selectionTracked: "porthole/annotate.selectionTracked",
|
|
127
134
|
clearSelection: "porthole/annotate.clearSelection",
|
|
128
135
|
focusMark: "porthole/annotate.focusMark",
|
|
129
136
|
};
|
|
@@ -142,6 +149,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
142
149
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
143
150
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
144
151
|
const rangeRects = Range.prototype.getClientRects;
|
|
152
|
+
const cloneRange = Range.prototype.cloneRange;
|
|
145
153
|
const setStart = Range.prototype.setStart;
|
|
146
154
|
const setStartBefore = Range.prototype.setStartBefore;
|
|
147
155
|
const compareBoundaryPoints = Range.prototype.compareBoundaryPoints;
|
|
@@ -398,7 +406,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
398
406
|
// box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
|
|
399
407
|
// box, its border 1 px), so a tap a few px off still lands on the shell's layer. A marker is
|
|
400
408
|
// a real button (P133): what a browser gives one is taken off, a ring says it has the focus.
|
|
401
|
-
|
|
409
|
+
// The selection the host follows (P138) is drawn as what is picked is: an element in the
|
|
410
|
+
// picking outline, a little lighter and without its name; words with a light fill and a line
|
|
411
|
+
// under them, in the same blue, apart from the marks' yellow (no comment is there yet).
|
|
412
|
+
const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.held{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.06)}.held.text{outline:0;border-radius:2px;background:rgba(37,99,235,.12);box-shadow:inset 0 -2px 0 #2563eb}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
|
|
402
413
|
// Inline and important: the content's own style sheets can't hide, shrink or move it by
|
|
403
414
|
// accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
|
|
404
415
|
// content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
|
|
@@ -424,6 +435,36 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
424
435
|
|
|
425
436
|
let mode = { elements: false, text: false, hold: false };
|
|
426
437
|
let hover = null;
|
|
438
|
+
// The selection last reported as selected (P138): its anchor, and what it is in the page (the
|
|
439
|
+
// element picked, or a copy of the selection's range, which the page's changes keep up to
|
|
440
|
+
// date and which stays when the page's own selection goes). Followed while the host asks
|
|
441
|
+
// (track with selection), and drawn then. Each new selected replaces it. Kept only while the
|
|
442
|
+
// host follows the selection, or said at its last start that it will (keepSelection, P140):
|
|
443
|
+
// for any other host nothing is kept, as before P138.
|
|
444
|
+
let held = null;
|
|
445
|
+
let followingSelection = false;
|
|
446
|
+
let keeping = false;
|
|
447
|
+
const keeps = () => followingSelection || keeping;
|
|
448
|
+
// What the host was last told of it: "attached", "orphaned", or null (nothing yet).
|
|
449
|
+
let heldTold = null;
|
|
450
|
+
const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
|
|
451
|
+
const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
|
|
452
|
+
// The element just picked (P138, Tenny's review): for a host that will follow it
|
|
453
|
+
// (keepSelection, P140), it keeps its outline after selected, so there is no gap before the
|
|
454
|
+
// host follows it, and the follow's highlight takes over where it does. For any other host
|
|
455
|
+
// the outline goes with the pick, as before P138. Until the follow comes it ends as a
|
|
456
|
+
// selection does: the next pick or selection, the host's clearSelection, a mode started or
|
|
457
|
+
// stopped, clear, Escape, or the element leaving the page. Not unselected: a selection made
|
|
458
|
+
// after the pick has already ended it as it was reported, so the one unselected can clear is
|
|
459
|
+
// one from before, which the pick's own click takes away when text is selected too.
|
|
460
|
+
let picked = null;
|
|
461
|
+
const endPick = () => {
|
|
462
|
+
if (picked !== null) {
|
|
463
|
+
picked = null;
|
|
464
|
+
redraw();
|
|
465
|
+
}
|
|
466
|
+
};
|
|
467
|
+
const pickShown = () => picked !== null && !followingSelection && picked.isConnected;
|
|
427
468
|
let marks = [];
|
|
428
469
|
// The markers as last drawn, for a click to find: { id, element }. Each mark keeps its
|
|
429
470
|
// marker's node across draws, so a press that spans a redraw ends on the node it began on.
|
|
@@ -814,7 +855,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
814
855
|
return boxes;
|
|
815
856
|
};
|
|
816
857
|
const draw = () => {
|
|
817
|
-
if (marks.length === 0 && hover === null && layer === null) {
|
|
858
|
+
if (marks.length === 0 && hover === null && layer === null && !heldShown() && !pickShown()) {
|
|
818
859
|
return;
|
|
819
860
|
}
|
|
820
861
|
const root = ensureLayer();
|
|
@@ -909,6 +950,24 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
909
950
|
}
|
|
910
951
|
}
|
|
911
952
|
const outlines = [];
|
|
953
|
+
// The followed selection (P138), under the picking outline: no pointer, no focus, no name;
|
|
954
|
+
// before the host follows it, the element just picked, drawn the same way.
|
|
955
|
+
if (picked !== null && !picked.isConnected) {
|
|
956
|
+
picked = null;
|
|
957
|
+
}
|
|
958
|
+
const lit = heldShown() ? held.found : pickShown() ? { element: picked } : null;
|
|
959
|
+
if (lit !== null) {
|
|
960
|
+
const rects = lit.range ? Array.from(rangeRects.call(lit.range)).slice(0, LIMIT.boxes) : [elementRect.call(lit.element)];
|
|
961
|
+
for (const rect of rects) {
|
|
962
|
+
if (rect.width === 0 && rect.height === 0) {
|
|
963
|
+
continue;
|
|
964
|
+
}
|
|
965
|
+
const each = createElement.call(document, "div");
|
|
966
|
+
each.className = lit.range ? "held text" : "held";
|
|
967
|
+
each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
|
|
968
|
+
outlines.push(each);
|
|
969
|
+
}
|
|
970
|
+
}
|
|
912
971
|
if (hover !== null && hover.isConnected) {
|
|
913
972
|
const rect = elementRect.call(hover);
|
|
914
973
|
const outline = createElement.call(document, "div");
|
|
@@ -954,9 +1013,17 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
954
1013
|
let trackedBox = null;
|
|
955
1014
|
let trackedAt = 0;
|
|
956
1015
|
let trackFrame = 0;
|
|
1016
|
+
// The followed selection's viewport as last told (P138): a frame made smaller can leave it
|
|
1017
|
+
// out of view without moving it.
|
|
1018
|
+
let trackedView = null;
|
|
957
1019
|
const trackTick = () => {
|
|
958
1020
|
trackFrame = 0;
|
|
959
|
-
if (tracking === null) {
|
|
1021
|
+
if (tracking === null && !followingSelection) {
|
|
1022
|
+
return;
|
|
1023
|
+
}
|
|
1024
|
+
if (followingSelection) {
|
|
1025
|
+
followHeld();
|
|
1026
|
+
trackFrame = nextFrame(trackTick);
|
|
960
1027
|
return;
|
|
961
1028
|
}
|
|
962
1029
|
const mark = marks.find((each) => each.id === tracking);
|
|
@@ -975,12 +1042,84 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
975
1042
|
}
|
|
976
1043
|
trackFrame = nextFrame(trackTick);
|
|
977
1044
|
};
|
|
978
|
-
|
|
1045
|
+
// The followed selection (P138), as a followed mark is, and on its clock: where it is at each
|
|
1046
|
+
// animation frame where it moved, or the viewport changed size, with whether any of it is in
|
|
1047
|
+
// the viewport; orphaned once while it isn't in the page (a page that took the element out,
|
|
1048
|
+
// a re-render, the words gone), found again by its anchor at most twice a second meanwhile.
|
|
1049
|
+
// Geometry only: its anchor and words went with selected. Reads boxes, nothing else: no
|
|
1050
|
+
// focus, no selection, no listener.
|
|
1051
|
+
const followHeld = () => {
|
|
1052
|
+
const now = performance.now();
|
|
1053
|
+
if (held !== null && heldGone(held.found) && now - held.tried >= 500) {
|
|
1054
|
+
held.tried = now;
|
|
1055
|
+
let found = null;
|
|
1056
|
+
try {
|
|
1057
|
+
found = find(held.anchor, textIndex());
|
|
1058
|
+
} catch (_) {
|
|
1059
|
+
found = null;
|
|
1060
|
+
}
|
|
1061
|
+
if (found !== null && !heldGone(found)) {
|
|
1062
|
+
held.found = found;
|
|
1063
|
+
}
|
|
1064
|
+
}
|
|
1065
|
+
if (held === null || heldGone(held.found)) {
|
|
1066
|
+
if (heldTold !== "orphaned") {
|
|
1067
|
+
heldTold = "orphaned";
|
|
1068
|
+
trackedBox = null;
|
|
1069
|
+
tell(M.selectionTracked, { state: "orphaned" });
|
|
1070
|
+
redraw();
|
|
1071
|
+
}
|
|
1072
|
+
return;
|
|
1073
|
+
}
|
|
1074
|
+
const rect = box(rectOf(held.found));
|
|
1075
|
+
const root = document.documentElement;
|
|
1076
|
+
const view = { width: root ? root.clientWidth : 0, height: root ? root.clientHeight : 0 };
|
|
1077
|
+
const resized = trackedView === null || trackedView.width !== view.width || trackedView.height !== view.height;
|
|
1078
|
+
if ((heldTold !== "attached" || resized || apart(trackedBox, rect)) && now - trackedAt >= 16) {
|
|
1079
|
+
heldTold = "attached";
|
|
1080
|
+
trackedBox = rect;
|
|
1081
|
+
trackedView = view;
|
|
1082
|
+
trackedAt = now;
|
|
1083
|
+
const scroll = scrollOf();
|
|
1084
|
+
const lastLineDocumentRect = lastLineOf(held.found, scroll);
|
|
1085
|
+
const inView = rect.x < view.width && rect.x + rect.width > 0 && rect.y < view.height && rect.y + rect.height > 0;
|
|
1086
|
+
tell(M.selectionTracked, Object.assign({ state: "attached", rect, documentRect: inDocument(rect, scroll), scroll, inView }, lastLineDocumentRect === null ? {} : { lastLineDocumentRect }));
|
|
1087
|
+
// The highlight goes with it (a layout change moves it without a scroll).
|
|
1088
|
+
redraw();
|
|
1089
|
+
}
|
|
1090
|
+
};
|
|
1091
|
+
// A mark, the selection (P138), or nothing: one at a time, each replacing the last.
|
|
1092
|
+
const track = (id, selection) => {
|
|
1093
|
+
const was = heldShown() || pickShown();
|
|
979
1094
|
tracking = typeof id === "string" ? id : null;
|
|
1095
|
+
followingSelection = tracking === null && selection === true;
|
|
1096
|
+
// The follow's highlight takes the pick's outline over, in this draw (Tenny's review).
|
|
1097
|
+
if (followingSelection) {
|
|
1098
|
+
picked = null;
|
|
1099
|
+
}
|
|
1100
|
+
// Its end lets the selection go, unless the host said it follows it again (P140).
|
|
1101
|
+
if (!keeps()) {
|
|
1102
|
+
held = null;
|
|
1103
|
+
}
|
|
980
1104
|
trackedBox = null;
|
|
981
|
-
|
|
1105
|
+
trackedView = null;
|
|
1106
|
+
heldTold = null;
|
|
1107
|
+
if ((tracking !== null || followingSelection) && trackFrame === 0) {
|
|
982
1108
|
trackFrame = nextFrame(trackTick);
|
|
983
1109
|
}
|
|
1110
|
+
if (heldShown() || pickShown() || was) {
|
|
1111
|
+
draw();
|
|
1112
|
+
}
|
|
1113
|
+
};
|
|
1114
|
+
// A new selected (P138): what is followed, if the selection is, from the next frame on; kept
|
|
1115
|
+
// only for a host that follows it or will (P140).
|
|
1116
|
+
const holdSelected = (anchor, found) => {
|
|
1117
|
+
held = keeps() ? { anchor, found, tried: 0 } : null;
|
|
1118
|
+
if (followingSelection) {
|
|
1119
|
+
trackedBox = null;
|
|
1120
|
+
heldTold = null;
|
|
1121
|
+
redraw();
|
|
1122
|
+
}
|
|
984
1123
|
};
|
|
985
1124
|
|
|
986
1125
|
// Where each found mark starts in the document, in order (P112): its place in a list the host
|
|
@@ -1183,9 +1322,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1183
1322
|
sent += 1;
|
|
1184
1323
|
}
|
|
1185
1324
|
}
|
|
1325
|
+
// Not while the host follows the selection (P138, Tenny's review): its reports carry where
|
|
1326
|
+
// it is; a scroll after the following ends is re-sent as before.
|
|
1186
1327
|
if (selectionScrolled) {
|
|
1187
1328
|
selectionScrolled = false;
|
|
1188
|
-
if (reportSelection(true)) {
|
|
1329
|
+
if (!followingSelection && reportSelection(true)) {
|
|
1189
1330
|
sent += 1;
|
|
1190
1331
|
}
|
|
1191
1332
|
}
|
|
@@ -1455,6 +1596,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1455
1596
|
const stop = () => {
|
|
1456
1597
|
mode = { elements: false, text: false };
|
|
1457
1598
|
hover = null;
|
|
1599
|
+
picked = null;
|
|
1458
1600
|
reported = null;
|
|
1459
1601
|
reportedBox = null;
|
|
1460
1602
|
setCursor(false);
|
|
@@ -1522,6 +1664,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1522
1664
|
return;
|
|
1523
1665
|
}
|
|
1524
1666
|
swallowUntil = performance.now() + 2000;
|
|
1667
|
+
holdSelected(anchor, { element });
|
|
1668
|
+
picked = keeping && !followingSelection ? element : null;
|
|
1669
|
+
redraw();
|
|
1525
1670
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1526
1671
|
}, HOLD_MS),
|
|
1527
1672
|
};
|
|
@@ -1569,6 +1714,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1569
1714
|
mode = { elements: false, text: mode.text };
|
|
1570
1715
|
hover = null;
|
|
1571
1716
|
setCursor(false);
|
|
1717
|
+
holdSelected(anchor, { element });
|
|
1718
|
+
// Its outline stays (P138), now without its name, until the host follows it or it ends;
|
|
1719
|
+
// only for a host that will follow it (P140): for any other it goes with the pick.
|
|
1720
|
+
picked = keeping && !followingSelection ? element : null;
|
|
1572
1721
|
draw();
|
|
1573
1722
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1574
1723
|
}, true);
|
|
@@ -1576,6 +1725,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1576
1725
|
if (event.key !== "Escape") {
|
|
1577
1726
|
return;
|
|
1578
1727
|
}
|
|
1728
|
+
// The person wants out: a pick's outline goes (P138). The key is untouched by it.
|
|
1729
|
+
endPick();
|
|
1579
1730
|
if (mode.elements) {
|
|
1580
1731
|
event.preventDefault();
|
|
1581
1732
|
event.stopImmediatePropagation();
|
|
@@ -1629,6 +1780,8 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1629
1780
|
}
|
|
1630
1781
|
reported = key;
|
|
1631
1782
|
reportedBox = rect;
|
|
1783
|
+
holdSelected(anchor, { range: cloneRange.call(range) });
|
|
1784
|
+
endPick();
|
|
1632
1785
|
tell(M.selected, Object.assign({ anchor, rect }, placeOf({ range })));
|
|
1633
1786
|
return true;
|
|
1634
1787
|
};
|
|
@@ -1639,6 +1792,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1639
1792
|
}
|
|
1640
1793
|
});
|
|
1641
1794
|
window.addEventListener("scroll", () => {
|
|
1795
|
+
// Not while the host follows the selection (P138, Tenny's review).
|
|
1796
|
+
if (followingSelection) {
|
|
1797
|
+
return;
|
|
1798
|
+
}
|
|
1642
1799
|
if (reported !== null) {
|
|
1643
1800
|
selectionScrolled = true;
|
|
1644
1801
|
settle();
|
|
@@ -1657,7 +1814,15 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1657
1814
|
switch (data.method) {
|
|
1658
1815
|
case M.start:
|
|
1659
1816
|
mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
|
|
1817
|
+
// Whether the host will follow what is selected (P140): only then is it kept before
|
|
1818
|
+
// the host follows it. A stop leaves it, so a stop sent as the composer opens doesn't
|
|
1819
|
+
// take the selection away before the follow comes.
|
|
1820
|
+
keeping = params.keepSelection === true;
|
|
1821
|
+
if (!keeps()) {
|
|
1822
|
+
held = null;
|
|
1823
|
+
}
|
|
1660
1824
|
hover = null;
|
|
1825
|
+
picked = null;
|
|
1661
1826
|
reported = null;
|
|
1662
1827
|
reportedBox = null;
|
|
1663
1828
|
setCursor(mode.elements);
|
|
@@ -1689,18 +1854,19 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1689
1854
|
focus(String(params.id));
|
|
1690
1855
|
break;
|
|
1691
1856
|
case M.track:
|
|
1692
|
-
track(params.id);
|
|
1857
|
+
track(params.id, params.selection === true);
|
|
1693
1858
|
break;
|
|
1694
1859
|
case M.clearSelection: {
|
|
1695
1860
|
// The host used the person's selection (P115): it goes, and with it what the shell
|
|
1696
1861
|
// held of it (a report waiting to settle, the one last told, a scroll's follow-up), so
|
|
1697
1862
|
// nothing is told back: the host knows, and the selectionchange this makes finds
|
|
1698
|
-
// nothing to report. Marks, a pick and the mode stay as they are
|
|
1699
|
-
// selected, nothing changes.
|
|
1863
|
+
// nothing to report. Marks, a pick and the mode stay as they are, but a pick's outline
|
|
1864
|
+
// goes (P138). With nothing selected, nothing changes.
|
|
1700
1865
|
cancelLater(selectionTimer);
|
|
1701
1866
|
selectionTimer = 0;
|
|
1702
1867
|
reported = null;
|
|
1703
1868
|
reportedBox = null;
|
|
1869
|
+
endPick();
|
|
1704
1870
|
selectionScrolled = false;
|
|
1705
1871
|
const selection = selectionOf.call(document);
|
|
1706
1872
|
if (selection !== null) {
|
|
@@ -1713,6 +1879,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1713
1879
|
break;
|
|
1714
1880
|
case M.clear:
|
|
1715
1881
|
track(null);
|
|
1882
|
+
picked = null;
|
|
1716
1883
|
pendingFocus = null;
|
|
1717
1884
|
pendingMarker = null;
|
|
1718
1885
|
marks = [];
|
package/dist/shell/runtime.d.ts
CHANGED
|
@@ -29,6 +29,16 @@ export declare const PASSES_AS_IS: string;
|
|
|
29
29
|
* and nothing is forwarded): fail closed.
|
|
30
30
|
*/
|
|
31
31
|
export declare const ONCE: string;
|
|
32
|
+
/**
|
|
33
|
+
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
34
|
+
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
35
|
+
* its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
|
|
36
|
+
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
37
|
+
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
38
|
+
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
|
39
|
+
* `none()`; an answer that comes later still is taken.
|
|
40
|
+
*/
|
|
41
|
+
export declare const HANDSHAKE: string;
|
|
32
42
|
/**
|
|
33
43
|
* The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
|
|
34
44
|
* no imports and no build step, so every engine (a browser frame now, a native web view later)
|
package/dist/shell/runtime.js
CHANGED
|
@@ -88,6 +88,42 @@ export const ONCE = String.raw `(passesAsIs, toText) => (value) => {
|
|
|
88
88
|
}
|
|
89
89
|
return text;
|
|
90
90
|
}`;
|
|
91
|
+
/**
|
|
92
|
+
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
93
|
+
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
94
|
+
* its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
|
|
95
|
+
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
96
|
+
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
97
|
+
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
|
98
|
+
* `none()`; an answer that comes later still is taken.
|
|
99
|
+
*/
|
|
100
|
+
export const HANDSHAKE = String.raw `(topLevel, ask, answered, none, later) => {
|
|
101
|
+
if (topLevel === true) {
|
|
102
|
+
none();
|
|
103
|
+
return;
|
|
104
|
+
}
|
|
105
|
+
let initialized = false;
|
|
106
|
+
let tries = 0;
|
|
107
|
+
const initialize = () => {
|
|
108
|
+
if (initialized) {
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
if (tries >= 40) {
|
|
112
|
+
none();
|
|
113
|
+
return;
|
|
114
|
+
}
|
|
115
|
+
tries += 1;
|
|
116
|
+
ask().then((result) => {
|
|
117
|
+
if (initialized) {
|
|
118
|
+
return;
|
|
119
|
+
}
|
|
120
|
+
initialized = true;
|
|
121
|
+
answered(result);
|
|
122
|
+
}, () => {});
|
|
123
|
+
later(initialize, 250);
|
|
124
|
+
};
|
|
125
|
+
initialize();
|
|
126
|
+
}`;
|
|
91
127
|
/**
|
|
92
128
|
* The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
|
|
93
129
|
* no imports and no build step, so every engine (a browser frame now, a native web view later)
|
|
@@ -151,6 +187,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
151
187
|
// such name goes on the shell's own script element (data-porthole-unfixed, for a test or a
|
|
152
188
|
// person to see) and, once the shell can speak, to the host as an error report.
|
|
153
189
|
const shellScript = document.currentScript;
|
|
190
|
+
// The platform's own, kept before the shell's guards wrap it: the shell marks the document's root
|
|
191
|
+
// with it (data-porthole-host, P139).
|
|
192
|
+
const setAttributeOfShell = Element.prototype.setAttribute;
|
|
154
193
|
const unfixed = [];
|
|
155
194
|
let tellUnfixed = (_name) => {};
|
|
156
195
|
const lock = (target, name, value) => {
|
|
@@ -2228,36 +2267,43 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
2228
2267
|
whenLoaded(() => void render({ html: plan.document }));
|
|
2229
2268
|
}
|
|
2230
2269
|
|
|
2231
|
-
//
|
|
2232
|
-
|
|
2233
|
-
|
|
2234
|
-
|
|
2235
|
-
|
|
2236
|
-
|
|
2237
|
-
|
|
2238
|
-
|
|
2239
|
-
|
|
2240
|
-
|
|
2241
|
-
|
|
2242
|
-
|
|
2243
|
-
|
|
2244
|
-
|
|
2245
|
-
|
|
2246
|
-
|
|
2247
|
-
|
|
2248
|
-
|
|
2249
|
-
|
|
2250
|
-
|
|
2251
|
-
|
|
2252
|
-
|
|
2270
|
+
// The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
|
|
2271
|
+
// after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
|
|
2272
|
+
// hears it, and the runtime has nothing to offer from the start. How it ended goes on the
|
|
2273
|
+
// document's root element (data-porthole-host: "answered", or "none" where no host answered), for
|
|
2274
|
+
// a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
|
|
2275
|
+
// which a whole document's render takes out with the body it replaces, while the root stays (the
|
|
2276
|
+
// render adds the page's own attributes to it and removes none). The page's own word, never a
|
|
2277
|
+
// gate, set through the platform's setAttribute kept before the guards (setAttributeOfShell).
|
|
2278
|
+
const shellRoot = document.documentElement;
|
|
2279
|
+
const settled = (how) => {
|
|
2280
|
+
try {
|
|
2281
|
+
callOf(setAttributeOfShell, shellRoot, ["data-porthole-host", how]);
|
|
2282
|
+
} catch (_) {}
|
|
2283
|
+
};
|
|
2284
|
+
const handshake = ${HANDSHAKE};
|
|
2285
|
+
handshake(
|
|
2286
|
+
window.top === window,
|
|
2287
|
+
() =>
|
|
2288
|
+
request("ui/initialize", {
|
|
2289
|
+
protocolVersion: plan.protocolVersion,
|
|
2290
|
+
appInfo: { name: "porthole-shell", version: "1" },
|
|
2291
|
+
appCapabilities: {},
|
|
2292
|
+
}),
|
|
2293
|
+
(result) => {
|
|
2294
|
+
settled("answered");
|
|
2253
2295
|
const capabilities = result && result.hostCapabilities;
|
|
2254
2296
|
const experimental = capabilities && capabilities.experimental;
|
|
2255
2297
|
runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
|
|
2256
2298
|
applyTheme(result && result.hostContext);
|
|
2257
2299
|
notify("ui/notifications/initialized", {});
|
|
2258
2300
|
schedule();
|
|
2259
|
-
},
|
|
2260
|
-
|
|
2261
|
-
|
|
2262
|
-
|
|
2301
|
+
},
|
|
2302
|
+
() => {
|
|
2303
|
+
// No host answered (or none can): the runtime has nothing to offer.
|
|
2304
|
+
settled("none");
|
|
2305
|
+
runtimeOffer(null);
|
|
2306
|
+
},
|
|
2307
|
+
(run, ms) => setTimeout(run, ms),
|
|
2308
|
+
);
|
|
2263
2309
|
})();`;
|
package/docs/ADOPTING.md
CHANGED
|
@@ -289,7 +289,9 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
289
289
|
|
|
290
290
|
- **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
|
|
291
291
|
`annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
|
|
292
|
-
stops),
|
|
292
|
+
stops), `trackedSelection` (true while your composer is open: the selection is followed in the
|
|
293
|
+
mark's place, P138; give it from the first render, `false` until then, so the mode starts with
|
|
294
|
+
`keepSelection`, P140: it is read as the mode starts, and giving it later restarts nothing), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
|
|
293
295
|
ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
|
|
294
296
|
is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
|
|
295
297
|
no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
|
|
@@ -436,6 +438,53 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
436
438
|
composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
|
|
437
439
|
});
|
|
438
440
|
```
|
|
441
|
+
- **A composer that stays beside what it is for** (P138, P140): `selected` comes once for a pick
|
|
442
|
+
(and for words again only once a scroll settles), and by default a pick's outline goes with it
|
|
443
|
+
and the frame keeps nothing of it. To follow it, start with `keepSelection: true`
|
|
444
|
+
(`annotations.start({ elements: true, keepSelection: true })`; React does it while you give
|
|
445
|
+
`trackedSelection`), so the frame keeps what is picked or selected, then follow the selection
|
|
446
|
+
while your composer is open, `annotations.track({ selection: true })` (React:
|
|
447
|
+
`trackedSelection`). The frame highlights it (a picked element in the picking outline) and
|
|
448
|
+
reports `selectionTracked` as `tracked` reports a mark: at most 60 a second, its `rect` clamped,
|
|
449
|
+
`documentRect`, `lastLineDocumentRect` and `scroll` as above, and `inView`, so you hide the
|
|
450
|
+
composer (and show your own marker at the frame's edge, from `documentRect` and `scroll`, clipped)
|
|
451
|
+
while it is out of view. `state: "orphaned"`: it isn't in the page now (a re-render took it out;
|
|
452
|
+
a reload); keep the person's words, it may be found again. Without `keepSelection`, a follow
|
|
453
|
+
asked after `selected` has nothing to follow and answers `orphaned`; one asked before the pick
|
|
454
|
+
follows each selection made while it lasts. It follows the latest `selected`, so a new pick or
|
|
455
|
+
selection moves it. One thing is followed at a time: it takes a followed mark's place, and
|
|
456
|
+
`track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every close
|
|
457
|
+
(posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
|
|
458
|
+
clear the selection: the page reads when it starts and ends, so an end on every close says
|
|
459
|
+
nothing of what came of it. The composer moves at the page's word: guard it as below, armed
|
|
460
|
+
again each time it moves or shows again. An older shell sends nothing (and draws nothing): place
|
|
461
|
+
by `selected` until the first `selectionTracked`, which a newer one sends at its next animation
|
|
462
|
+
frame. Under `keepSelection` a newer shell keeps the picked element outlined from the pick on,
|
|
463
|
+
so there is no gap before the follow's highlight; ask for the follow before a `start` or `stop`
|
|
464
|
+
you send as the composer opens (React orders them so), or the stop ends that outline a moment
|
|
465
|
+
before the follow draws it again. Until the follow comes, the outline ends as a selection does
|
|
466
|
+
(the next pick, Escape, `clearSelection`, `start`, `stop`, `clear`). Without `keepSelection` the
|
|
467
|
+
outline goes with the pick, as before 0.14.15. While you follow the selection, `selected` isn't
|
|
468
|
+
re-sent after a scroll: read where it is from `selectionTracked`; and while you don't, a
|
|
469
|
+
`selectionTracked` from the page is dropped unread.
|
|
470
|
+
|
|
471
|
+
```js
|
|
472
|
+
display.annotations.start({ elements: true, text: true, keepSelection: true });
|
|
473
|
+
display.on("annotation", (report) => {
|
|
474
|
+
if (report.type === "selected") {
|
|
475
|
+
composer.openBeside(frame, report.rect, report.anchor); // as before: an older shell stops here
|
|
476
|
+
display.annotations.track({ selection: true });
|
|
477
|
+
}
|
|
478
|
+
if (report.type !== "selectionTracked") return;
|
|
479
|
+
if (report.state === "orphaned") return composer.detach(); // keep its words
|
|
480
|
+
if (!report.inView) return composer.collapseToMarker(report.documentRect, report.scroll);
|
|
481
|
+
if (composer.moveBeside(frame, report.rect) > 4) composerGuard.placed();
|
|
482
|
+
});
|
|
483
|
+
composer.onClose(() => {
|
|
484
|
+
display.annotations.track(null); // or the open card's mark: track(cardId)
|
|
485
|
+
display.annotations.clearSelection();
|
|
486
|
+
});
|
|
487
|
+
```
|
|
439
488
|
- **The keyboard** (P133): each marker is a button in the frame's Tab order, after the page's own
|
|
440
489
|
stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
|
|
441
490
|
the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The
|