@botiverse/porthole 0.8.0 → 0.9.0

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.
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * Annotations (P053): a person points at part of a display (an element, or text they select) to
3
- * comment on it, and the host marks the anchors already made. The host drives the shell with
3
+ * comment on it, and the host marks the anchors already made, each with a clickable marker and a
4
+ * number where it gives a count (P104). The host drives the shell with
4
5
  * Porthole's own messages (`porthole/annotate.*`); the shell answers with anchors and where they
5
6
  * are. An anchor is a set of W3C Web Annotation selectors, so it can be found again after the
6
7
  * content changes; finding it is best-effort, and says so (`orphaned`).
@@ -40,7 +41,11 @@ export interface AnnotationAnchor {
40
41
  /** A short description for the host to show ("h2#revenue Revenue grew 12%"); the content's. */
41
42
  readonly label: string;
42
43
  }
43
- /** A box in the frame's viewport, CSS px: add the frame element's position to place it on the page. */
44
+ /**
45
+ * A box in the frame's viewport, CSS px: add the frame element's position to place it on the page.
46
+ * The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
47
+ * outside is a box of no size on the nearest edge. A positioning hint only.
48
+ */
44
49
  export interface AnnotationRect {
45
50
  readonly x: number;
46
51
  readonly y: number;
@@ -54,10 +59,21 @@ export interface AnnotateMode {
54
59
  /** Text, by selecting it: each settled selection is reported, and its clearing. */
55
60
  readonly text?: boolean;
56
61
  }
57
- /** An anchor the host marks in the frame, under its own id. */
62
+ /**
63
+ * An anchor the host marks in the frame, under its own id. Everything here is sent into the
64
+ * frame, so the content can read it: give ids that say nothing (never a person's name or the
65
+ * comment's words).
66
+ */
58
67
  export interface AnnotationMark {
59
68
  readonly id: string;
60
69
  readonly anchor: AnnotationAnchor;
70
+ /**
71
+ * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
72
+ * `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
73
+ * text anchor and the top right of an element. The person can click it: the frame reports
74
+ * `activated`. The content can read the number; give one only where the page may know it.
75
+ */
76
+ readonly count?: number;
61
77
  }
62
78
  /** Whether a mark's anchor was found in the content as it is now. */
63
79
  export type AnchorState = "attached" | "orphaned";
@@ -83,10 +99,26 @@ export type AnnotationReport =
83
99
  | {
84
100
  readonly type: "cancelled";
85
101
  }
86
- /** Where the marked anchors are now, after `show`, `focus`, or a change of the content. */
102
+ /**
103
+ * Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
104
+ * every mark when the content changed one's state, and, while any mark has a `count`, once a
105
+ * scroll, a resize or a change of the content has settled, only the marks that moved since the
106
+ * host was last told, at most once a second (P104).
107
+ */
87
108
  | {
88
109
  readonly type: "anchored";
89
110
  readonly results: readonly AnchorResult[];
111
+ }
112
+ /**
113
+ * The person clicked the marker of a mark the host shows with a `count` (P104); `rect` is the
114
+ * marker's box, to open the host's own UI beside it. The content can fake it for any mark the
115
+ * host shows with a count, and can tell a real one happened: open the host's own view of that
116
+ * mark, never act on it.
117
+ */
118
+ | {
119
+ readonly type: "activated";
120
+ readonly id: string;
121
+ readonly rect: AnnotationRect;
90
122
  };
91
123
  /** Porthole's own messages for annotations (own-prefixed, P002). */
92
124
  export declare const ANNOTATE_METHODS: {
@@ -105,6 +137,8 @@ export declare const ANNOTATE_METHODS: {
105
137
  readonly unselected: "porthole/annotate.unselected";
106
138
  readonly cancelled: "porthole/annotate.cancelled";
107
139
  readonly anchored: "porthole/annotate.anchored";
140
+ /** Frame → host: a mark's marker was clicked (P104). */
141
+ readonly activated: "porthole/annotate.activated";
108
142
  };
109
143
  /** The most of each part of an anchor or report the host takes. */
110
144
  export declare const ANNOTATION_LIMITS: {
@@ -117,4 +151,6 @@ export declare const ANNOTATION_LIMITS: {
117
151
  readonly id: 128;
118
152
  readonly position: 50000000;
119
153
  readonly coordinate: 10000000;
154
+ /** The largest `count` a mark's marker takes (P104). */
155
+ readonly count: 999;
120
156
  };
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * Annotations (P053): a person points at part of a display (an element, or text they select) to
3
- * comment on it, and the host marks the anchors already made. The host drives the shell with
3
+ * comment on it, and the host marks the anchors already made, each with a clickable marker and a
4
+ * number where it gives a count (P104). The host drives the shell with
4
5
  * Porthole's own messages (`porthole/annotate.*`); the shell answers with anchors and where they
5
6
  * are. An anchor is a set of W3C Web Annotation selectors, so it can be found again after the
6
7
  * content changes; finding it is best-effort, and says so (`orphaned`).
@@ -27,6 +28,8 @@ export const ANNOTATE_METHODS = {
27
28
  unselected: "porthole/annotate.unselected",
28
29
  cancelled: "porthole/annotate.cancelled",
29
30
  anchored: "porthole/annotate.anchored",
31
+ /** Frame → host: a mark's marker was clicked (P104). */
32
+ activated: "porthole/annotate.activated",
30
33
  };
31
34
  /** The most of each part of an anchor or report the host takes. */
32
35
  export const ANNOTATION_LIMITS = {
@@ -39,4 +42,6 @@ export const ANNOTATION_LIMITS = {
39
42
  id: 128,
40
43
  position: 50_000_000,
41
44
  coordinate: 10_000_000,
45
+ /** The largest `count` a mark's marker takes (P104). */
46
+ count: 999,
42
47
  };
@@ -3,6 +3,16 @@ import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type Ann
3
3
  export declare function parseAnchor(value: unknown): AnnotationAnchor | null;
4
4
  /** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
5
5
  export declare function parseRect(value: unknown): AnnotationRect | null;
6
+ /**
7
+ * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
8
+ * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
9
+ * wholly outside becomes a box of no size on the nearest edge. Where the viewport isn't known, a
10
+ * box of no size at the frame's corner. The page still chooses any point inside its own frame.
11
+ */
12
+ export declare function clampRect(rect: AnnotationRect, viewport: {
13
+ readonly width: number;
14
+ readonly height: number;
15
+ } | undefined): AnnotationRect;
6
16
  /** A report from the frame, checked; null if malformed (it is then dropped). */
7
17
  export declare function parseReport(value: unknown): AnnotationReport | null;
8
18
  /** What the host may start with: elements, text, or both (default both). */
@@ -82,6 +82,22 @@ export function parseRect(value) {
82
82
  }
83
83
  return { x, y, width, height };
84
84
  }
85
+ /**
86
+ * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
87
+ * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
88
+ * wholly outside becomes a box of no size on the nearest edge. Where the viewport isn't known, a
89
+ * box of no size at the frame's corner. The page still chooses any point inside its own frame.
90
+ */
91
+ export function clampRect(rect, viewport) {
92
+ const width = viewport !== undefined && Number.isFinite(viewport.width) ? viewport.width : 0;
93
+ const height = viewport !== undefined && Number.isFinite(viewport.height) ? viewport.height : 0;
94
+ const within = (value, most) => Math.min(Math.max(value, 0), Math.max(0, most));
95
+ const left = within(rect.x, width);
96
+ const top = within(rect.y, height);
97
+ const right = within(rect.x + rect.width, width);
98
+ const bottom = within(rect.y + rect.height, height);
99
+ return { x: left, y: top, width: right - left, height: bottom - top };
100
+ }
85
101
  const markId = (value) => text(value, LIMITS.id, 1);
86
102
  function results(value) {
87
103
  if (!Array.isArray(value) || value.length > LIMITS.marks) {
@@ -126,6 +142,10 @@ export function parseReport(value) {
126
142
  const checked = results(value.results);
127
143
  return checked === null ? null : { type: "anchored", results: checked };
128
144
  }
145
+ case "activated": {
146
+ const rect = parseRect(value.rect);
147
+ return !markId(value.id) || rect === null ? null : { type: "activated", id: value.id, rect };
148
+ }
129
149
  default:
130
150
  return null;
131
151
  }
@@ -150,7 +170,10 @@ export function checkMarks(marks) {
150
170
  if (!markId(mark?.id) || seen.has(mark.id) || anchor === null) {
151
171
  throw new TypeError(`annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`);
152
172
  }
173
+ if (mark.count !== undefined && !count(mark.count, LIMITS.count)) {
174
+ throw new TypeError(`annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`);
175
+ }
153
176
  seen.add(mark.id);
154
- return { id: mark.id, anchor };
177
+ return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
155
178
  });
156
179
  }