@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.
@@ -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);
@@ -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(),
@@ -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`) and it
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
- // What a marker is called (P133), to whoever can't see it: what it is, and the words it is
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;