@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.
- package/CHANGELOG.md +36 -0
- package/dist/annotate/types.d.ts +35 -15
- package/dist/annotate/types.js +3 -1
- package/dist/annotate/validate.js +28 -3
- 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 +21 -7
- package/dist/shell/annotate.js +277 -43
- package/dist/shell/find.d.ts +1 -1
- package/dist/shell/find.js +1 -1
- package/docs/ADOPTING.md +52 -5
- package/docs/ARCHITECTURE.md +4 -3
- package/docs/DECISIONS.md +243 -2
- package/docs/DESIGN.md +57 -23
- package/docs/THREAT_MODEL.md +55 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +35 -15
- package/src/annotate/validate.ts +33 -3
- 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 +278 -43
- package/src/shell/find.ts +1 -1
package/dist/host/create-host.js
CHANGED
|
@@ -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;
|
package/dist/host/types.d.ts
CHANGED
|
@@ -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;
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -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
|
package/dist/react/frame.js
CHANGED
|
@@ -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);
|
package/dist/react/view.js
CHANGED
|
@@ -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
|
}), []);
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -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`)
|
|
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
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
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.
|