@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/host/create-host.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { ANNOTATE_METHODS
|
|
2
|
-
import { annotateMode, checkMarks, clampRect, hasMarker, parseReport, } from "../annotate/validate.js";
|
|
1
|
+
import { ANNOTATE_METHODS } from "../annotate/types.js";
|
|
2
|
+
import { annotateMode, checkMarks, clampRect, followsSelection, hasMarker, inViewport, parseReport, } from "../annotate/validate.js";
|
|
3
3
|
import { FIND_LIMITS, FIND_METHODS } from "../find/types.js";
|
|
4
4
|
import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.js";
|
|
5
5
|
import { createBridge, onceConsent, } from "../bridge/bridge.js";
|
|
@@ -45,6 +45,7 @@ const REPORTS = {
|
|
|
45
45
|
[ANNOTATE_METHODS.anchored]: "anchored",
|
|
46
46
|
[ANNOTATE_METHODS.activated]: "activated",
|
|
47
47
|
[ANNOTATE_METHODS.tracked]: "tracked",
|
|
48
|
+
[ANNOTATE_METHODS.selectionTracked]: "selectionTracked",
|
|
48
49
|
};
|
|
49
50
|
/** What the frame says of find in page unasked (P131), by method. */
|
|
50
51
|
const FIND_REPORTS = {
|
|
@@ -164,8 +165,11 @@ export function createHost(config, options = {}) {
|
|
|
164
165
|
let annotating = null;
|
|
165
166
|
let marks = [];
|
|
166
167
|
let activeMark = null;
|
|
167
|
-
// The mark the host follows (P112),
|
|
168
|
+
// The mark the host follows (P112), or whether it follows the selection instead (P138), and
|
|
169
|
+
// when it took each `tracked` or `selectionTracked` in the last second: one followed thing
|
|
170
|
+
// at a time, one rate for both.
|
|
168
171
|
let tracking = null;
|
|
172
|
+
let trackingSelection = false;
|
|
169
173
|
const trackedTimes = [];
|
|
170
174
|
// Find in page (P131): the query shown (for the content it was asked of only: a new run or
|
|
171
175
|
// other content forgets it), whether the host takes the shortcut (kept for every frame the
|
|
@@ -275,6 +279,10 @@ export function createHost(config, options = {}) {
|
|
|
275
279
|
if (tracking !== null) {
|
|
276
280
|
toFrame(ANNOTATE_METHODS.track, { id: tracking });
|
|
277
281
|
}
|
|
282
|
+
// A new frame has no selection: it answers `orphaned` (P138).
|
|
283
|
+
if (trackingSelection) {
|
|
284
|
+
toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
|
|
285
|
+
}
|
|
278
286
|
};
|
|
279
287
|
/**
|
|
280
288
|
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
@@ -324,6 +332,16 @@ export function createHost(config, options = {}) {
|
|
|
324
332
|
case "activated":
|
|
325
333
|
case "tracked":
|
|
326
334
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
335
|
+
case "selectionTracked":
|
|
336
|
+
// In view only where the page says so and its box, as the host reads the viewport,
|
|
337
|
+
// reaches into it (P138): a box the clamp puts on an edge is never in view.
|
|
338
|
+
return report.state === "orphaned"
|
|
339
|
+
? report
|
|
340
|
+
: {
|
|
341
|
+
...report,
|
|
342
|
+
rect: clampRect(report.rect, viewport),
|
|
343
|
+
inView: report.inView && inViewport(report.rect, viewport),
|
|
344
|
+
};
|
|
327
345
|
case "anchored":
|
|
328
346
|
return {
|
|
329
347
|
...report,
|
|
@@ -352,6 +370,12 @@ export function createHost(config, options = {}) {
|
|
|
352
370
|
if (type === undefined) {
|
|
353
371
|
return;
|
|
354
372
|
}
|
|
373
|
+
// The followed selection (P138) only while the host follows it, and dropped unread
|
|
374
|
+
// otherwise (P140): a host that doesn't follow it takes it as 0.14.14 took a method it
|
|
375
|
+
// didn't know, so a malformed one is no refusal either.
|
|
376
|
+
if (type === "selectionTracked" && !trackingSelection) {
|
|
377
|
+
return;
|
|
378
|
+
}
|
|
355
379
|
let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
|
|
356
380
|
if (report === null) {
|
|
357
381
|
void through.call("annotate", null);
|
|
@@ -376,6 +400,20 @@ export function createHost(config, options = {}) {
|
|
|
376
400
|
emit("annotation", withinFrame(report));
|
|
377
401
|
return;
|
|
378
402
|
}
|
|
403
|
+
// The followed selection (P138): only while the host follows it (above), on the same 60 a
|
|
404
|
+
// second (one followed thing at a time), past the bridge's rate as the followed mark's.
|
|
405
|
+
if (report.type === "selectionTracked") {
|
|
406
|
+
const at = Date.now();
|
|
407
|
+
while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
|
|
408
|
+
trackedTimes.shift();
|
|
409
|
+
}
|
|
410
|
+
if (trackedTimes.length >= TRACKED_PER_SECOND) {
|
|
411
|
+
return;
|
|
412
|
+
}
|
|
413
|
+
trackedTimes.push(at);
|
|
414
|
+
emit("annotation", withinFrame(report));
|
|
415
|
+
return;
|
|
416
|
+
}
|
|
379
417
|
switch (report.type) {
|
|
380
418
|
case "selected": {
|
|
381
419
|
const kind = report.anchor.kind;
|
|
@@ -385,7 +423,7 @@ export function createHost(config, options = {}) {
|
|
|
385
423
|
}
|
|
386
424
|
// A pick ends with it; holding a block (P112) lasts until the host stops it.
|
|
387
425
|
if (kind === "element" && annotating.elements === true) {
|
|
388
|
-
annotating = annotating.text ? { elements: false
|
|
426
|
+
annotating = annotating.text ? { ...annotating, elements: false } : null;
|
|
389
427
|
}
|
|
390
428
|
break;
|
|
391
429
|
}
|
|
@@ -401,7 +439,7 @@ export function createHost(config, options = {}) {
|
|
|
401
439
|
return;
|
|
402
440
|
}
|
|
403
441
|
if (annotating.elements === true) {
|
|
404
|
-
annotating = annotating.text ? { elements: false
|
|
442
|
+
annotating = annotating.text ? { ...annotating, elements: false } : null;
|
|
405
443
|
}
|
|
406
444
|
break;
|
|
407
445
|
case "anchored": {
|
|
@@ -540,6 +578,7 @@ export function createHost(config, options = {}) {
|
|
|
540
578
|
if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
|
|
541
579
|
activeMark = null;
|
|
542
580
|
}
|
|
581
|
+
// A followed selection (P138) isn't a mark: a show leaves it.
|
|
543
582
|
if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
|
|
544
583
|
tracking = null;
|
|
545
584
|
toFrame(ANNOTATE_METHODS.track, { id: null });
|
|
@@ -557,12 +596,22 @@ export function createHost(config, options = {}) {
|
|
|
557
596
|
activeMark = id;
|
|
558
597
|
toFrame(ANNOTATE_METHODS.focus, { id });
|
|
559
598
|
},
|
|
560
|
-
track(
|
|
599
|
+
track(target) {
|
|
561
600
|
needsAnnotate("track");
|
|
601
|
+
// The selection (P138), under `id: null`: an older shell follows nothing.
|
|
602
|
+
if (followsSelection(target)) {
|
|
603
|
+
tracking = null;
|
|
604
|
+
trackingSelection = true;
|
|
605
|
+
trackedTimes.length = 0;
|
|
606
|
+
toFrame(ANNOTATE_METHODS.track, { id: null, selection: true });
|
|
607
|
+
return;
|
|
608
|
+
}
|
|
609
|
+
const id = target;
|
|
562
610
|
if (id !== null && !marks.some((mark) => mark.id === id)) {
|
|
563
611
|
throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
|
|
564
612
|
}
|
|
565
613
|
tracking = id;
|
|
614
|
+
trackingSelection = false;
|
|
566
615
|
trackedTimes.length = 0;
|
|
567
616
|
toFrame(ANNOTATE_METHODS.track, { id });
|
|
568
617
|
},
|
|
@@ -571,6 +620,7 @@ export function createHost(config, options = {}) {
|
|
|
571
620
|
marks = [];
|
|
572
621
|
activeMark = null;
|
|
573
622
|
tracking = null;
|
|
623
|
+
trackingSelection = false;
|
|
574
624
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
575
625
|
},
|
|
576
626
|
clearSelection() {
|
package/dist/host/types.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
1
|
+
import type { AnnotateMode, AnnotationMark, AnnotationReport, AnnotationTrackTarget } from "../annotate/types.ts";
|
|
2
2
|
import type { FindOptions, FindResult } from "../find/types.ts";
|
|
3
3
|
import type { Refused } from "../bridge/refusal.ts";
|
|
4
4
|
import type { Confirm, CapabilityHandlers, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
|
|
@@ -301,7 +301,11 @@ export interface FindControls {
|
|
|
301
301
|
* given to every frame the display runs (a reload, a navigation recovered from).
|
|
302
302
|
*/
|
|
303
303
|
export interface AnnotationControls {
|
|
304
|
-
/**
|
|
304
|
+
/**
|
|
305
|
+
* Lets the person point at elements, select text, or both (default both). With
|
|
306
|
+
* `keepSelection: true` (P140) the frame keeps what is selected for `track({ selection: true })`;
|
|
307
|
+
* without it, nothing is kept and a pick's outline goes with the pick.
|
|
308
|
+
*/
|
|
305
309
|
start(mode?: AnnotateMode): void;
|
|
306
310
|
stop(): void;
|
|
307
311
|
/** Marks these anchors (replacing the marks before); the frame reports where they are. */
|
|
@@ -315,8 +319,25 @@ export interface AnnotationControls {
|
|
|
315
319
|
* Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
|
|
316
320
|
* shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
|
|
317
321
|
* following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
|
|
322
|
+
*
|
|
323
|
+
* `{ selection: true }` (P138) follows the selection the frame last reported as `selected` (the
|
|
324
|
+
* element picked, or the words selected) instead, for a composer that stays beside it: the frame
|
|
325
|
+
* highlights it while it is followed (an element in the outline it had while it was picked) and
|
|
326
|
+
* reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
|
|
327
|
+
* `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
|
|
328
|
+
* The frame keeps a selection to follow only for a host that said so at `start`
|
|
329
|
+
* (`keepSelection`, P140), or one that already follows the selection as it is made: without
|
|
330
|
+
* either, a follow asked after `selected` has nothing to follow and answers `orphaned`. A `show`
|
|
331
|
+
* leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
|
|
332
|
+
* or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
|
|
333
|
+
* newer shell answers at its next animation frame; an older one sends nothing (it reads the
|
|
334
|
+
* message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
|
|
335
|
+
* Kept for a frame that runs later, which has no selection: it answers `orphaned`. Under
|
|
336
|
+
* `keepSelection` the element just picked stays outlined until then, so call it before a `start`
|
|
337
|
+
* or `stop` sent with it (a stop ends that outline); while followed, `selected` isn't re-sent
|
|
338
|
+
* after a scroll (Tenny's review).
|
|
318
339
|
*/
|
|
319
|
-
track(
|
|
340
|
+
track(target: AnnotationTrackTarget): void;
|
|
320
341
|
/** Removes every mark. */
|
|
321
342
|
clear(): void;
|
|
322
343
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -47,7 +47,7 @@ export { admitContent, admitFiles, type AdmitFilesResult, answerGuide, checkTool
|
|
|
47
47
|
export { writeClipboard } from "./host/clipboard.ts";
|
|
48
48
|
export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
|
|
49
49
|
export type { AnnotationControls, FindControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
|
|
50
|
-
export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationScroll, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
|
|
50
|
+
export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationScroll, type AnnotationSelector, type AnnotationTrackTarget, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
|
|
51
51
|
export { parseAnchor, parseRect, parseReport, parseScroll } from "./annotate/validate.ts";
|
|
52
52
|
export { FIND_LIMITS, FIND_METHODS, type FindDirection, type FindOptions, type FindReport, type FindResult, } from "./find/types.ts";
|
|
53
53
|
export { parseFindReport, parseFindResult } from "./find/validate.ts";
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -311,7 +311,8 @@ export interface PortholeFrameProps {
|
|
|
311
311
|
/**
|
|
312
312
|
* Annotations, where the config declares `annotate` (P053): what the person may point at now
|
|
313
313
|
* (elements, text, or both), or null to stop. A picked element ends element picking: set it
|
|
314
|
-
* again to pick again.
|
|
314
|
+
* again to pick again. `keepSelection` is set for you on a start made while `trackedSelection` is
|
|
315
|
+
* given (P140).
|
|
315
316
|
*/
|
|
316
317
|
readonly annotating?: AnnotateMode | null;
|
|
317
318
|
/**
|
|
@@ -338,6 +339,24 @@ export interface PortholeFrameProps {
|
|
|
338
339
|
* stop the following, as the core's `show` does; it starts again once they have it back.
|
|
339
340
|
*/
|
|
340
341
|
readonly trackedAnnotation?: string | null;
|
|
342
|
+
/**
|
|
343
|
+
* Follow the selection instead (`annotations.track({ selection: true })`, P138): while true, the
|
|
344
|
+
* element the person picked, or the words they selected, as the last `selected` reported them, is
|
|
345
|
+
* highlighted in the frame and `onAnnotation` gets `{ type: "selectionTracked", ... }` as it moves
|
|
346
|
+
* (the boxes `tracked` has, and `inView`; or `state: "orphaned"` while it isn't in the page), for
|
|
347
|
+
* a composer that stays beside it. It takes `trackedAnnotation`'s place while true (one followed
|
|
348
|
+
* thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
|
|
349
|
+
* composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
|
|
350
|
+
* `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
|
|
351
|
+
*
|
|
352
|
+
* Give it from the first render, `false` until the composer opens (P140): each start of
|
|
353
|
+
* `annotating` made while it is given carries `keepSelection`, so the frame keeps what is picked
|
|
354
|
+
* or selected (and the picked element outlined) for the follow. It is read as a mode starts:
|
|
355
|
+
* giving it, or leaving it out, later restarts nothing, and counts from the next start. Left out
|
|
356
|
+
* when the mode started, the frame keeps nothing, and a follow asked after the pick has nothing
|
|
357
|
+
* to follow (`orphaned`).
|
|
358
|
+
*/
|
|
359
|
+
readonly trackedSelection?: boolean;
|
|
341
360
|
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
342
361
|
readonly ref?: Ref<PortholeFrameHandle>;
|
|
343
362
|
/**
|
package/dist/react/frame.js
CHANGED
|
@@ -439,7 +439,8 @@ export function PortholeFrame(props) {
|
|
|
439
439
|
function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, run, }) {
|
|
440
440
|
const holder = useRef(null);
|
|
441
441
|
const handle = useRef(null);
|
|
442
|
-
// The mark the display follows now, as the core keeps it (P118), and
|
|
442
|
+
// The mark the display follows now, or the selection (P138), as the core keeps it (P118), and
|
|
443
|
+
// the props as last seen.
|
|
443
444
|
const following = useRef(null);
|
|
444
445
|
const asked = useRef(null);
|
|
445
446
|
const [ready, setReady] = useState(false);
|
|
@@ -649,9 +650,10 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
|
|
|
649
650
|
if (config.capabilities.annotate !== undefined) {
|
|
650
651
|
applyAnnotations(display, first);
|
|
651
652
|
}
|
|
652
|
-
// The followed mark, once the marks are shown; without `annotate`, the core's
|
|
653
|
+
// The followed mark or selection, once the marks are shown; without `annotate`, the core's
|
|
654
|
+
// error.
|
|
653
655
|
following.current = null;
|
|
654
|
-
const wanted = first
|
|
656
|
+
const wanted = followedOf(first);
|
|
655
657
|
asked.current = wanted;
|
|
656
658
|
if (wanted !== null) {
|
|
657
659
|
attempt(() => {
|
|
@@ -727,50 +729,67 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
|
|
|
727
729
|
: JSON.stringify([focusedAnnotation]);
|
|
728
730
|
// By value: the same marks given again don't mark them again.
|
|
729
731
|
const annotations = useByValue(frame.annotations);
|
|
732
|
+
// The mode, by value: what the person may point at, and the host's own `keepSelection`. Not
|
|
733
|
+
// whether `trackedSelection` is given (P140, Ferryman's review): that is read at each start, so
|
|
734
|
+
// a composer's prop that appears or goes restarts no mode (which would turn a pick that ended
|
|
735
|
+
// back on, for the person's next click to pick again).
|
|
730
736
|
const mode = annotating === undefined || annotating === null
|
|
731
737
|
? ""
|
|
732
|
-
: JSON.stringify([
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
}
|
|
738
|
-
const wanted = mode === "" ? null : JSON.parse(mode);
|
|
739
|
-
attempt(() => wanted === null
|
|
740
|
-
? display.annotations.stop()
|
|
741
|
-
: display.annotations.start({ elements: wanted[0], text: wanted[1] }), latest());
|
|
742
|
-
}, [annotates, mode]);
|
|
738
|
+
: JSON.stringify([
|
|
739
|
+
annotating.elements ?? true,
|
|
740
|
+
annotating.text ?? true,
|
|
741
|
+
annotating.keepSelection === true,
|
|
742
|
+
]);
|
|
743
743
|
useEffect(() => {
|
|
744
744
|
const display = handle.current;
|
|
745
745
|
if (annotates && display !== null) {
|
|
746
746
|
attempt(() => {
|
|
747
747
|
display.annotations.show(annotations ?? []);
|
|
748
|
-
// A show without the followed mark stops the following (the core's own)
|
|
749
|
-
|
|
748
|
+
// A show without the followed mark stops the following (the core's own); the selection
|
|
749
|
+
// stays followed (P138).
|
|
750
|
+
if (typeof following.current === "string" && !shown(annotations, following.current)) {
|
|
750
751
|
following.current = null;
|
|
751
752
|
}
|
|
752
753
|
}, latest());
|
|
753
754
|
}
|
|
754
755
|
}, [annotates, annotations]);
|
|
755
|
-
// The followed mark follows its
|
|
756
|
-
|
|
756
|
+
// The followed mark, or the selection (P138), follows its props (after the marks above, so the
|
|
757
|
+
// two can change together).
|
|
758
|
+
const followed = followedOf(frame);
|
|
757
759
|
useEffect(() => {
|
|
758
760
|
const display = handle.current;
|
|
759
|
-
const changed =
|
|
760
|
-
asked.current =
|
|
761
|
-
if (display === null ||
|
|
761
|
+
const changed = followed !== asked.current;
|
|
762
|
+
asked.current = followed;
|
|
763
|
+
if (display === null || followed === following.current) {
|
|
762
764
|
return;
|
|
763
765
|
}
|
|
764
766
|
// Its mark was taken off (the error, if any, was told when the prop said it): followed again
|
|
765
767
|
// once the marks have it back.
|
|
766
|
-
if (!changed &&
|
|
768
|
+
if (!changed && typeof followed === "string" && !shown(annotations, followed)) {
|
|
767
769
|
return;
|
|
768
770
|
}
|
|
769
771
|
attempt(() => {
|
|
770
|
-
display.annotations.track(
|
|
771
|
-
following.current =
|
|
772
|
+
display.annotations.track(followed);
|
|
773
|
+
following.current = followed;
|
|
772
774
|
}, latest());
|
|
773
|
-
}, [
|
|
775
|
+
}, [followed, annotations]);
|
|
776
|
+
// The mode follows its prop, after the following above (P138, Tenny's review): a host that
|
|
777
|
+
// follows the selection and ends picking in one render has the frame follow it first, so the
|
|
778
|
+
// pick's outline goes straight to the follow's highlight, never through the stop's gap.
|
|
779
|
+
useEffect(() => {
|
|
780
|
+
const display = handle.current;
|
|
781
|
+
if (!annotates || display === null) {
|
|
782
|
+
return;
|
|
783
|
+
}
|
|
784
|
+
const wanted = mode === "" ? null : JSON.parse(mode);
|
|
785
|
+
attempt(() => wanted === null
|
|
786
|
+
? display.annotations.stop()
|
|
787
|
+
: display.annotations.start({
|
|
788
|
+
elements: wanted[0],
|
|
789
|
+
text: wanted[1],
|
|
790
|
+
...(wanted[2] || keepsSelection(latest()) ? { keepSelection: true } : {}),
|
|
791
|
+
}), latest());
|
|
792
|
+
}, [annotates, mode]);
|
|
774
793
|
useEffect(() => {
|
|
775
794
|
const display = handle.current;
|
|
776
795
|
const id = focusOf(latest().focusedAnnotation);
|
|
@@ -852,7 +871,7 @@ function applyAnnotations(display, frame) {
|
|
|
852
871
|
display.annotations.focus(focused);
|
|
853
872
|
}
|
|
854
873
|
if (frame.annotating !== undefined && frame.annotating !== null) {
|
|
855
|
-
display.annotations.start(frame.annotating);
|
|
874
|
+
display.annotations.start(keepsSelection(frame) ? { ...frame.annotating, keepSelection: true } : frame.annotating);
|
|
856
875
|
}
|
|
857
876
|
}, frame);
|
|
858
877
|
}
|
|
@@ -865,6 +884,20 @@ function useByValue(value) {
|
|
|
865
884
|
const key = value === undefined ? "" : JSON.stringify(value);
|
|
866
885
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
|
|
867
886
|
}
|
|
887
|
+
/**
|
|
888
|
+
* Whether a start keeps what is selected for a follow (P140): while `trackedSelection` is given
|
|
889
|
+
* (true or false), or the host's own `keepSelection` says so. Read at each start, never a reason
|
|
890
|
+
* for one.
|
|
891
|
+
*/
|
|
892
|
+
function keepsSelection(frame) {
|
|
893
|
+
return frame.annotating?.keepSelection === true || frame.trackedSelection !== undefined;
|
|
894
|
+
}
|
|
895
|
+
/** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
|
|
896
|
+
const SELECTION = Object.freeze({ selection: true });
|
|
897
|
+
/** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
|
|
898
|
+
function followedOf(frame) {
|
|
899
|
+
return frame.trackedSelection === true ? SELECTION : (frame.trackedAnnotation ?? null);
|
|
900
|
+
}
|
|
868
901
|
/** Whether `marks` has a mark `id`. */
|
|
869
902
|
function shown(marks, id) {
|
|
870
903
|
return (marks ?? []).some((mark) => mark.id === id);
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -33,7 +33,7 @@ export declare const WORD_LATE: string;
|
|
|
33
33
|
* in one).
|
|
34
34
|
*
|
|
35
35
|
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
36
|
-
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
36
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked|selectionTracked`):
|
|
37
37
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
38
38
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
39
39
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -59,7 +59,13 @@ export declare const WORD_LATE: string;
|
|
|
59
59
|
* followed mark's (`tracked`) too, so a host places marks scrolled out of the frame, and keeps
|
|
60
60
|
* them placed as the document scrolls, from one report and the followed mark's scroll;
|
|
61
61
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
62
|
-
* too (`lastLineDocumentRect`), so a host places its UI after them
|
|
62
|
+
* too (`lastLineDocumentRect`), so a host places its UI after them;
|
|
63
|
+
* - the selection followed (P138): what the last `selected` reported (the element picked, or the
|
|
64
|
+
* words selected) is kept while the host follows the selection (`track` with `selection`) or said
|
|
65
|
+
* at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
|
|
66
|
+
* it is drawn in the layer and its boxes are reported as a followed mark's are
|
|
67
|
+
* (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
|
|
68
|
+
* focus and no key.
|
|
63
69
|
*
|
|
64
70
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
65
71
|
* reports as UI hints only.
|