@botiverse/porthole 0.14.10 → 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.
@@ -578,6 +578,14 @@ export function createHost(config, options = {}) {
578
578
  needsAnnotate("clearSelection");
579
579
  toFrame(ANNOTATE_METHODS.clearSelection, {});
580
580
  },
581
+ focusMark(id) {
582
+ // Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
583
+ // marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
584
+ needsAnnotate("focusMark");
585
+ if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
586
+ toFrame(ANNOTATE_METHODS.focusMark, { id });
587
+ }
588
+ },
581
589
  };
582
590
  const hostContext = () => {
583
591
  const width = container.getBoundingClientRect().width;
@@ -326,6 +326,17 @@ export interface AnnotationControls {
326
326
  * a frame that runs later (it has no selection to clear).
327
327
  */
328
328
  clearSelection(): void;
329
+ /**
330
+ * Puts the keyboard back on a mark's marker in the frame (P134): for after Escape closed the
331
+ * host's own view of that mark, and for nothing else. No content goes with it, and no report
332
+ * comes of it. Nothing happens, and nothing throws, for an id no mark with a marker is shown
333
+ * under, or if the frame has no such marker now (its words are gone, elements are being picked):
334
+ * the display's own `focus()` isn't used, so the frame takes no focus for a marker it hasn't got.
335
+ * Call it once the view is closed: from one of the page's text fields that still has focus, the
336
+ * move is the frame's own to the focus guard, undone and counted (P109). The page can take the
337
+ * focus back at once. Not kept for a frame that runs later.
338
+ */
339
+ focusMark(id: string): void;
329
340
  }
330
341
  export interface DisplayControls {
331
342
  readonly displayId: string;
@@ -154,6 +154,12 @@ export interface PortholeFrameHandle {
154
154
  * `"annotations"` (the core's call throws; this never does).
155
155
  */
156
156
  clearSelection(): void;
157
+ /**
158
+ * Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
159
+ * once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
160
+ * while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`.
161
+ */
162
+ focusMark(id: string): void;
157
163
  /**
158
164
  * Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
159
165
  * or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
@@ -349,6 +349,12 @@ export function PortholeFrame(props) {
349
349
  attempt(() => now.annotations.clearSelection(), own.current);
350
350
  }
351
351
  },
352
+ focusMark(id) {
353
+ const now = display.current;
354
+ if (now !== null) {
355
+ attempt(() => now.annotations.focusMark(id), own.current);
356
+ }
357
+ },
352
358
  find(query, options) {
353
359
  try {
354
360
  checkFindQuery(query, options);
@@ -129,6 +129,7 @@ function InstanceView(props) {
129
129
  const shown = useRef(null);
130
130
  useImperativeHandle(ref, () => ({
131
131
  clearSelection: () => shown.current?.clearSelection(),
132
+ focusMark: (id) => shown.current?.focusMark(id),
132
133
  find: (query, options) => shown.current?.find(query, options) ?? Promise.resolve("unsupported"),
133
134
  clearFind: () => shown.current?.clearFind(),
134
135
  }), []);
@@ -7,14 +7,23 @@
7
7
  * centre is nearest the point. No built-in is called (content may have patched them).
8
8
  */
9
9
  export declare const MARKER_HIT: string;
10
+ /**
11
+ * What a marker is called (P133, P134), to whoever can't see it, spliced into the runtime: what it
12
+ * is, and the words it is on, in quotes. In English, whatever the page's language: the shell has no
13
+ * words of the host's. `anchor.label` stays as the host stores it (it is the host's to show): an
14
+ * element's starts with its tag (`describe`, "p#intro.lead Words"), so an element's words are its
15
+ * quote, cut where the label's are and marked so, or for one with no text of its own (an image's
16
+ * `alt`) what follows the tag in the label. An element with neither has no words.
17
+ */
18
+ export declare const MARKER_NAME: string;
10
19
  /**
11
20
  * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
12
21
  * the config declares `annotate`, so it runs before any content does, with the DOM's own
13
22
  * functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
14
23
  * in one).
15
24
  *
16
- * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`) and it
17
- * reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
25
+ * The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
26
+ * and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
18
27
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
19
28
  * click or tap picks it, and the content's own handlers never see that click (unless the content
20
29
  * patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
@@ -24,17 +33,22 @@ export declare const MARKER_HIT: string;
24
33
  * was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
25
34
  * shell's own (a closed shadow root), again whenever the content changes; what can't be found
26
35
  * is reported `orphaned`;
27
- * - markers (P104): a mark with a count gets a small bubble with the number beside its anchor's
28
- * last line (P105: in the line's gutter); a click on it is reported (`activated`), and the
29
- * content's own handlers never see it; a draft (P107) is drawn apart, a dashed line and a hollow
30
- * bubble with no number, and has a marker with or without a count;
36
+ * - markers (P104): a mark with a count gets a small button with the number, a bubble: a text
37
+ * anchor's at its paragraph's end (P133), a draft's (P107) beside its anchor's last line (P105:
38
+ * in the line's gutter), an element's on its corner; a click on it, or Enter or Space with the
39
+ * focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
40
+ * draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
41
+ * or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
42
+ * tells nothing back;
31
43
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
32
44
  * settles, the marks that moved since the host was last told are reported, at most once a
33
45
  * second, so the host's own UI beside a mark can follow;
34
46
  * - places in the document (P132): each result's box also in the document's coordinates
35
47
  * (`documentRect`), with how far the document was scrolled as it was read (`scroll`), and the
36
48
  * followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
37
- * them placed as the document scrolls, from one report and the followed mark's scroll.
49
+ * them placed as the document scrolls, from one report and the followed mark's scroll;
50
+ * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
51
+ * too (`lastLineDocumentRect`), so a host places its UI after them.
38
52
  *
39
53
  * It shares the realm with the content, which can interfere with all of it: the host takes its
40
54
  * reports as UI hints only.