@seamless-co/pagemark 0.0.0-stage → 0.5.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.
Files changed (150) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +25 -2
  3. package/behaviours/behaviour.d.ts +43 -0
  4. package/behaviours/behaviour.js +84 -0
  5. package/behaviours/comparison.d.ts +62 -0
  6. package/behaviours/comparison.js +129 -0
  7. package/behaviours/document-viewer.d.ts +9 -0
  8. package/behaviours/document-viewer.js +9 -0
  9. package/behaviours/hidden.d.ts +24 -0
  10. package/behaviours/hidden.js +38 -0
  11. package/behaviours/hover.d.ts +34 -0
  12. package/behaviours/hover.js +49 -0
  13. package/behaviours/index.d.ts +24 -0
  14. package/behaviours/index.js +14 -0
  15. package/behaviours/linked-viewers.d.ts +14 -0
  16. package/behaviours/linked-viewers.js +25 -0
  17. package/behaviours/links.d.ts +4 -0
  18. package/behaviours/links.js +4 -0
  19. package/behaviours/marks.d.ts +64 -0
  20. package/behaviours/marks.js +33 -0
  21. package/behaviours/quotes.d.ts +7 -0
  22. package/behaviours/quotes.js +9 -0
  23. package/behaviours/region.d.ts +27 -0
  24. package/behaviours/region.js +40 -0
  25. package/behaviours/search.d.ts +38 -0
  26. package/behaviours/search.js +63 -0
  27. package/behaviours/selection.d.ts +30 -0
  28. package/behaviours/selection.js +41 -0
  29. package/behaviours/text.d.ts +8 -0
  30. package/behaviours/text.js +24 -0
  31. package/behaviours/viewer-state.d.ts +36 -0
  32. package/behaviours/viewer-state.js +58 -0
  33. package/browser/blob-pieces.d.ts +9 -0
  34. package/browser/blob-pieces.js +50 -0
  35. package/browser/browser-source.d.ts +25 -0
  36. package/browser/browser-source.js +62 -0
  37. package/browser/index.d.ts +2 -0
  38. package/browser/index.js +1 -0
  39. package/browser/local-pdf.d.ts +27 -0
  40. package/browser/local-pdf.js +61 -0
  41. package/browser/worker-engine.d.ts +21 -0
  42. package/browser/worker-engine.js +1 -0
  43. package/browser/worker.d.ts +1 -0
  44. package/browser/worker.js +51 -0
  45. package/core/compare.d.ts +55 -0
  46. package/core/compare.js +350 -0
  47. package/core/find.d.ts +12 -0
  48. package/core/find.js +177 -0
  49. package/core/hidden.d.ts +12 -0
  50. package/core/hidden.js +26 -0
  51. package/core/index.d.ts +11 -0
  52. package/core/index.js +6 -0
  53. package/core/links.d.ts +7 -0
  54. package/core/links.js +19 -0
  55. package/core/locate.d.ts +21 -0
  56. package/core/locate.js +140 -0
  57. package/core/paragraphs.d.ts +37 -0
  58. package/core/paragraphs.js +141 -0
  59. package/core/types.d.ts +89 -0
  60. package/core/types.js +1 -0
  61. package/document/document.d.ts +83 -0
  62. package/document/document.js +215 -0
  63. package/document/handover-source.d.ts +18 -0
  64. package/document/handover-source.js +39 -0
  65. package/document/index.d.ts +10 -0
  66. package/document/index.js +5 -0
  67. package/document/reading-source.d.ts +7 -0
  68. package/document/reading-source.js +16 -0
  69. package/document/server-source.d.ts +10 -0
  70. package/document/server-source.js +23 -0
  71. package/document/source.d.ts +21 -0
  72. package/document/source.js +1 -0
  73. package/document/split-source.d.ts +9 -0
  74. package/document/split-source.js +25 -0
  75. package/document/store.d.ts +12 -0
  76. package/document/store.js +21 -0
  77. package/engine/engine-thread.d.ts +10 -0
  78. package/engine/engine-thread.js +1 -0
  79. package/engine/index.d.ts +2 -0
  80. package/engine/index.js +1 -0
  81. package/engine/pdfium.d.ts +16 -0
  82. package/engine/pdfium.js +222 -0
  83. package/engine/remote.d.ts +51 -0
  84. package/engine/remote.js +109 -0
  85. package/package.json +65 -4
  86. package/react/hooks.d.ts +128 -0
  87. package/react/hooks.js +129 -0
  88. package/react/index.d.ts +3 -0
  89. package/react/index.js +2 -0
  90. package/react/viewer.d.ts +48 -0
  91. package/react/viewer.js +127 -0
  92. package/reader/assemble.d.ts +4 -0
  93. package/reader/assemble.js +29 -0
  94. package/reader/index.d.ts +7 -0
  95. package/reader/index.js +5 -0
  96. package/reader/layer-page.d.ts +30 -0
  97. package/reader/layer-page.js +40 -0
  98. package/reader/layer-words.d.ts +4 -0
  99. package/reader/layer-words.js +102 -0
  100. package/reader/letter-edges.d.ts +13 -0
  101. package/reader/letter-edges.js +60 -0
  102. package/reader/links.d.ts +7 -0
  103. package/reader/links.js +22 -0
  104. package/reader/seams.d.ts +92 -0
  105. package/reader/seams.js +3 -0
  106. package/reader/seen.d.ts +16 -0
  107. package/reader/seen.js +67 -0
  108. package/reader/trust.d.ts +9 -0
  109. package/reader/trust.js +34 -0
  110. package/viewer/attachments.d.ts +11 -0
  111. package/viewer/attachments.js +104 -0
  112. package/viewer/dom.d.ts +14 -0
  113. package/viewer/dom.js +38 -0
  114. package/viewer/events.d.ts +17 -0
  115. package/viewer/events.js +20 -0
  116. package/viewer/index.d.ts +17 -0
  117. package/viewer/index.js +8 -0
  118. package/viewer/links.d.ts +16 -0
  119. package/viewer/links.js +59 -0
  120. package/viewer/marks.d.ts +24 -0
  121. package/viewer/marks.js +171 -0
  122. package/viewer/page-layers.d.ts +13 -0
  123. package/viewer/page-layers.js +33 -0
  124. package/viewer/pictures.d.ts +24 -0
  125. package/viewer/pictures.js +293 -0
  126. package/viewer/pointer.d.ts +21 -0
  127. package/viewer/pointer.js +244 -0
  128. package/viewer/stage.d.ts +21 -0
  129. package/viewer/stage.js +31 -0
  130. package/viewer/text-between.d.ts +13 -0
  131. package/viewer/text-between.js +28 -0
  132. package/viewer/text.d.ts +20 -0
  133. package/viewer/text.js +180 -0
  134. package/viewer/tile-grid.d.ts +20 -0
  135. package/viewer/tile-grid.js +36 -0
  136. package/viewer/tiles.d.ts +15 -0
  137. package/viewer/tiles.js +190 -0
  138. package/viewer/turn.d.ts +18 -0
  139. package/viewer/turn.js +40 -0
  140. package/viewer/types.d.ts +238 -0
  141. package/viewer/types.js +1 -0
  142. package/viewer/view-over.d.ts +21 -0
  143. package/viewer/view-over.js +191 -0
  144. package/viewer/view.d.ts +59 -0
  145. package/viewer/view.js +1 -0
  146. package/viewer/viewer.css +301 -0
  147. package/viewer/viewer.d.ts +11 -0
  148. package/viewer/viewer.js +104 -0
  149. package/viewer/viewport.d.ts +37 -0
  150. package/viewer/viewport.js +429 -0
@@ -0,0 +1,190 @@
1
+ import { pageLayer } from "./page-layers.js";
2
+ import { TILE_PIXELS, tileScale, tilesOver } from "./tile-grid.js";
3
+ const MAX_TILE_LOADS = 6;
4
+ const MAX_LOAD_FAILURES = 2;
5
+ /** NOTE: loaded tiles this many tiles outside the pane are kept, so a short move back shows them with nothing fetched. */
6
+ const KEPT_AROUND = 1;
7
+ const SAME = 0.01;
8
+ function overlaps(first, second) {
9
+ return first.x < second.x + second.width && second.x < first.x + first.width && first.y < second.y + second.height && second.y < first.y + first.height;
10
+ }
11
+ export function createTiles(view, options) {
12
+ const held = new Map();
13
+ const layers = new Map();
14
+ let needs = new Map();
15
+ let loading = 0;
16
+ /** NOTE: the part of a page inside the pane, in page units, or null when none of it is. */
17
+ const viewOf = (index) => {
18
+ const page = view.pages[index];
19
+ const place = page ? view.inContent(index, { x: 0, y: 0, width: page.size.width, height: page.size.height }) : null;
20
+ if (!place)
21
+ return null;
22
+ const pane = view.paneBox();
23
+ const left = Math.max(pane.x, place.x);
24
+ const top = Math.max(pane.y, place.y);
25
+ const right = Math.min(pane.x + pane.width, place.x + place.width);
26
+ const bottom = Math.min(pane.y + pane.height, place.y + place.height);
27
+ if (right <= left || bottom <= top)
28
+ return null;
29
+ return view.inPage(index, { x: left, y: top, width: right - left, height: bottom - top });
30
+ };
31
+ const layerOf = (index) => {
32
+ const page = view.pages[index];
33
+ if (!page)
34
+ return null;
35
+ const known = layers.get(index);
36
+ if (known)
37
+ return known;
38
+ const layer = pageLayer(page, "tiles");
39
+ layers.set(index, layer);
40
+ return layer;
41
+ };
42
+ const remove = (tile) => {
43
+ tile.load?.abort();
44
+ tile.image?.remove();
45
+ if (tile.url !== null)
46
+ options.releaseImage?.(tile.url);
47
+ held.delete(tile.key);
48
+ };
49
+ const isSettled = (tile) => tile !== undefined && (tile.image !== null || tile.failures >= MAX_LOAD_FAILURES);
50
+ /** NOTE: tiles of an earlier zoom stay over the page until every tile of this one is there, so zooming never shows the soft picture underneath for a moment. */
51
+ const dropOutgrown = (page) => {
52
+ const need = needs.get(page);
53
+ if (!need || ![...need.keys].every((key) => isSettled(held.get(key))))
54
+ return;
55
+ for (const tile of [...held.values()])
56
+ if (tile.page === page && tile.scale !== need.scale)
57
+ remove(tile);
58
+ };
59
+ const fetchTile = async (tile, signal) => {
60
+ const url = await options.tileUrl(tile.page, tile.scale, tile.tile.box, signal);
61
+ const image = new Image();
62
+ /** NOTE: a browser fetches an image itself and takes no signal, so a tile no longer wanted is stopped by taking its address away. */
63
+ const stop = () => image.removeAttribute("src");
64
+ signal.addEventListener("abort", stop, { once: true });
65
+ try {
66
+ if (signal.aborted)
67
+ throw new DOMException("The tile is no longer wanted.", "AbortError");
68
+ image.src = url;
69
+ await image.decode();
70
+ if (signal.aborted)
71
+ throw new DOMException("The tile is no longer wanted.", "AbortError");
72
+ }
73
+ catch (error) {
74
+ options.releaseImage?.(url);
75
+ throw error;
76
+ }
77
+ finally {
78
+ signal.removeEventListener("abort", stop);
79
+ }
80
+ return { image, url };
81
+ };
82
+ const show = (tile, image, url) => {
83
+ const page = view.pages[tile.page];
84
+ const layer = layerOf(tile.page);
85
+ if (!page || !layer)
86
+ return;
87
+ const { box } = tile.tile;
88
+ image.className = "pm-tile";
89
+ image.alt = "";
90
+ image.draggable = false;
91
+ image.dataset.scale = String(tile.scale);
92
+ image.style.left = `${(box.x / page.size.width) * 100}%`;
93
+ image.style.top = `${(box.y / page.size.height) * 100}%`;
94
+ image.style.width = `${(box.width / page.size.width) * 100}%`;
95
+ image.style.height = `${(box.height / page.size.height) * 100}%`;
96
+ layer.append(image);
97
+ tile.image = image;
98
+ tile.url = url;
99
+ };
100
+ /** NOTE: the tile nearest the middle of the pane is fetched first, so what a reader is looking at turns sharp before its surroundings. */
101
+ const nextToLoad = () => {
102
+ let nearest = null;
103
+ let least = Number.POSITIVE_INFINITY;
104
+ for (const tile of held.values()) {
105
+ const need = needs.get(tile.page);
106
+ if (tile.image || tile.load || tile.failures >= MAX_LOAD_FAILURES || !need?.keys.has(tile.key))
107
+ continue;
108
+ const { box } = tile.tile;
109
+ const apart = Math.hypot(box.x + box.width / 2 - need.middle.x, box.y + box.height / 2 - need.middle.y) * view.zoom;
110
+ if (apart < least) {
111
+ least = apart;
112
+ nearest = tile;
113
+ }
114
+ }
115
+ return nearest;
116
+ };
117
+ const load = () => {
118
+ for (let tile = nextToLoad(); tile && loading < MAX_TILE_LOADS; tile = nextToLoad()) {
119
+ const wanted = tile;
120
+ const fetching = new AbortController();
121
+ wanted.load = fetching;
122
+ loading += 1;
123
+ fetchTile(wanted, fetching.signal).then(({ image, url }) => {
124
+ loading -= 1;
125
+ wanted.load = null;
126
+ if (held.get(wanted.key) === wanted) {
127
+ show(wanted, image, url);
128
+ dropOutgrown(wanted.page);
129
+ }
130
+ else {
131
+ options.releaseImage?.(url);
132
+ }
133
+ load();
134
+ }, () => {
135
+ loading -= 1;
136
+ wanted.load = null;
137
+ if (!fetching.signal.aborted)
138
+ wanted.failures += 1;
139
+ if (held.get(wanted.key) === wanted)
140
+ dropOutgrown(wanted.page);
141
+ load();
142
+ });
143
+ }
144
+ };
145
+ return {
146
+ cover(pages, needed, heldScale) {
147
+ needs = new Map();
148
+ for (const index of pages) {
149
+ const page = view.pages[index];
150
+ const shown = page ? viewOf(index) : null;
151
+ if (!page || !shown)
152
+ continue;
153
+ const sharpest = page.size.sharpest ?? Number.POSITIVE_INFINITY;
154
+ if (heldScale(index) >= Math.min(needed, sharpest) - SAME)
155
+ continue;
156
+ const scale = tileScale(needed, sharpest);
157
+ const margin = (TILE_PIXELS / scale) * KEPT_AROUND;
158
+ const keys = new Set();
159
+ for (const tile of tilesOver(page.size, scale, shown)) {
160
+ const key = `${index}/${scale}/${tile.column}/${tile.row}`;
161
+ keys.add(key);
162
+ if (!held.has(key))
163
+ held.set(key, { key, page: index, scale, tile, image: null, url: null, load: null, failures: 0 });
164
+ }
165
+ needs.set(index, {
166
+ scale,
167
+ keys,
168
+ around: { x: shown.x - margin, y: shown.y - margin, width: shown.width + margin * 2, height: shown.height + margin * 2 },
169
+ middle: { x: shown.x + shown.width / 2, y: shown.y + shown.height / 2 },
170
+ });
171
+ }
172
+ for (const tile of [...held.values()]) {
173
+ const need = needs.get(tile.page);
174
+ if (need?.keys.has(tile.key))
175
+ continue;
176
+ if (!need || !tile.image || !overlaps(tile.tile.box, need.around))
177
+ remove(tile);
178
+ }
179
+ for (const page of needs.keys())
180
+ dropOutgrown(page);
181
+ load();
182
+ },
183
+ destroy() {
184
+ for (const tile of [...held.values()])
185
+ remove(tile);
186
+ for (const layer of layers.values())
187
+ layer.remove();
188
+ },
189
+ };
190
+ }
@@ -0,0 +1,18 @@
1
+ import type { Box } from "../core/index.js";
2
+ import type { ViewerPage, ViewerRotation } from "./types.js";
3
+ /**
4
+ * NOTE: where things are on a page that is shown turned. A page keeps its own units however it is shown: a word's
5
+ * box never changes. These go between a page's own units and the units of the page as it stands on the screen,
6
+ * measured from the top-left corner it has there.
7
+ */
8
+ type Point = {
9
+ x: number;
10
+ y: number;
11
+ };
12
+ export declare function turnedSize(size: ViewerPage, rotation: ViewerRotation): ViewerPage;
13
+ export declare function turnedPoint(size: ViewerPage, rotation: ViewerRotation, { x, y }: Point): Point;
14
+ export declare function unturnedPoint(size: ViewerPage, rotation: ViewerRotation, { x, y }: Point): Point;
15
+ /** NOTE: an upright box stays upright through a quarter turn, so the box of two opposite corners is the whole of it. */
16
+ export declare function turnedBox(size: ViewerPage, rotation: ViewerRotation, box: Box): Box;
17
+ export declare function unturnedBox(size: ViewerPage, rotation: ViewerRotation, box: Box): Box;
18
+ export {};
package/viewer/turn.js ADDED
@@ -0,0 +1,40 @@
1
+ export function turnedSize(size, rotation) {
2
+ return rotation === 90 || rotation === 270 ? { width: size.height, height: size.width } : size;
3
+ }
4
+ export function turnedPoint(size, rotation, { x, y }) {
5
+ if (rotation === 90)
6
+ return { x: size.height - y, y: x };
7
+ if (rotation === 180)
8
+ return { x: size.width - x, y: size.height - y };
9
+ if (rotation === 270)
10
+ return { x: y, y: size.width - x };
11
+ return { x, y };
12
+ }
13
+ export function unturnedPoint(size, rotation, { x, y }) {
14
+ if (rotation === 90)
15
+ return { x: y, y: size.height - x };
16
+ if (rotation === 180)
17
+ return { x: size.width - x, y: size.height - y };
18
+ if (rotation === 270)
19
+ return { x: size.width - y, y: x };
20
+ return { x, y };
21
+ }
22
+ const boxOf = (first, second) => ({
23
+ x: Math.min(first.x, second.x),
24
+ y: Math.min(first.y, second.y),
25
+ width: Math.abs(first.x - second.x),
26
+ height: Math.abs(first.y - second.y),
27
+ });
28
+ const cornersOf = (box) => [
29
+ { x: box.x, y: box.y },
30
+ { x: box.x + box.width, y: box.y + box.height },
31
+ ];
32
+ /** NOTE: an upright box stays upright through a quarter turn, so the box of two opposite corners is the whole of it. */
33
+ export function turnedBox(size, rotation, box) {
34
+ const [first, second] = cornersOf(box);
35
+ return boxOf(turnedPoint(size, rotation, first), turnedPoint(size, rotation, second));
36
+ }
37
+ export function unturnedBox(size, rotation, box) {
38
+ const [first, second] = cornersOf(box);
39
+ return boxOf(unturnedPoint(size, rotation, first), unturnedPoint(size, rotation, second));
40
+ }
@@ -0,0 +1,238 @@
1
+ import type { Box } from "../core/index.js";
2
+ export type ViewerPage = {
3
+ width: number;
4
+ height: number;
5
+ /**
6
+ * NOTE: the most pixels for each page unit the page has to show: 1 for a photograph, whose units are its own pixels.
7
+ * Left out, the page can be drawn as sharp as asked, as a PDF's can.
8
+ */
9
+ sharpest?: number;
10
+ };
11
+ export type ViewerMark<Of = unknown> = {
12
+ /** NOTE: tells the mark from every other in the viewer, and names it to bring it into focus. It says nothing of what the mark is. */
13
+ id: string;
14
+ page: number;
15
+ rects: ReadonlyArray<Box>;
16
+ /** NOTE: names the mark's look; it becomes the class `pm-mark-<tone>`. */
17
+ tone?: string;
18
+ /**
19
+ * NOTE: what a screen reader says for the mark, such as "Match 2 of 7". A mark with one can be reached with the
20
+ * keyboard and pressed with Enter. One without is drawn and passed over, as a mark that follows the pointer should be.
21
+ */
22
+ label?: string;
23
+ /** NOTE: what the mark stands for, of the caller's own choosing. The viewer keeps it with the mark and never reads it. */
24
+ of?: Of;
25
+ };
26
+ /**
27
+ * NOTE: one line of a page's text, for a reader to select: its words in reading order, each at its own box, and the
28
+ * line's box, whose top and height every word on it shares.
29
+ */
30
+ export type ViewerTextLine = {
31
+ box: Box;
32
+ words: ReadonlyArray<{
33
+ text: string;
34
+ box: Box;
35
+ }>;
36
+ };
37
+ /**
38
+ * NOTE: a link over a page, as a PDF's own: where it lies, and where it leads, an address or another page counted
39
+ * from 0. `label` is what a screen reader says for it; left out, it is the address, or the page's number.
40
+ */
41
+ export type ViewerLink = {
42
+ page: number;
43
+ box: Box;
44
+ label?: string;
45
+ } & ({
46
+ url: string;
47
+ } | {
48
+ toPage: number;
49
+ });
50
+ /** NOTE: a place on a page, in page units from the page's top-left corner. */
51
+ export type PagePoint = {
52
+ page: number;
53
+ x: number;
54
+ y: number;
55
+ };
56
+ export type ViewerDrag = {
57
+ phase: "start" | "move" | "end";
58
+ page: number;
59
+ from: {
60
+ x: number;
61
+ y: number;
62
+ };
63
+ /** NOTE: held inside the page the drag started on. */
64
+ to: {
65
+ x: number;
66
+ y: number;
67
+ };
68
+ };
69
+ /** NOTE: `over` covers the place and scales with the page; the others sit beside it at the element's own size. */
70
+ export type Placement = "over" | "above" | "below" | "left" | "right";
71
+ export type Place = {
72
+ page: number;
73
+ box: Box;
74
+ };
75
+ /** NOTE: an element of the caller's own, held at a place on a page through zoom and scroll. */
76
+ export type Attachment = {
77
+ move(place: Place): void;
78
+ remove(): void;
79
+ };
80
+ export type ScreenBox = {
81
+ left: number;
82
+ top: number;
83
+ width: number;
84
+ height: number;
85
+ };
86
+ /** NOTE: one change of what the pane shows. */
87
+ export type ViewMove = {
88
+ /** NOTE: screen pixels per page unit, after the change. */
89
+ zoom: number;
90
+ /** NOTE: how far the pages moved under the pane, in page units; both are 0 for a zoom or a resize. */
91
+ x: number;
92
+ y: number;
93
+ /** NOTE: false for a move the viewer made itself: bringing a mark into view, going to a page, or `moveBy`. */
94
+ byReader: boolean;
95
+ };
96
+ /** NOTE: what a zoom is held to: the width of the widest page, or a whole page. */
97
+ export type ViewerFit = "width" | "page";
98
+ /** NOTE: how far the pages are shown turned, clockwise, in degrees. */
99
+ export type ViewerRotation = 0 | 90 | 180 | 270;
100
+ /** NOTE: how many pages stand side by side: one, or two as in an open book, the first page on the left. */
101
+ export type ViewerSpread = "single" | "double";
102
+ export type ViewerOptions = {
103
+ pages: ReadonlyArray<ViewerPage>;
104
+ /**
105
+ * NOTE: the address of a page's image drawn at `scale` pixels per page unit. It may be a plain address a server
106
+ * answers, or a promise of one for a source that draws the page itself and hands back an object address. `signal`
107
+ * aborts once the page is no longer wanted.
108
+ */
109
+ imageUrl: (page: number, scale: number, signal: AbortSignal) => string | Promise<string>;
110
+ /**
111
+ * NOTE: the address of the image of one box of a page, in page units, drawn at exactly `scale`. Given, the viewer
112
+ * stays sharp however far in it is zoomed: it keeps a whole page's picture to a modest size and lays tiles of this
113
+ * over the part on screen. Left out, a page is as sharp as its whole picture and no sharper.
114
+ */
115
+ tileUrl?: (page: number, scale: number, box: Box, signal: AbortSignal) => string | Promise<string>;
116
+ /** NOTE: called when the viewer stops using an address `imageUrl` or `tileUrl` gave, so a source can free what it made for it. */
117
+ releaseImage?: (url: string) => void;
118
+ scales?: ReadonlyArray<number>;
119
+ /** NOTE: names the scrolling pane, which a keyboard reaches, for a screen reader. Left out, the pane has no name. */
120
+ label?: string;
121
+ /** NOTE: what the zoom is held to as the viewer opens: the width of the widest page, the default, or a whole page. */
122
+ fit?: ViewerFit;
123
+ };
124
+ /**
125
+ * NOTE: what a viewer tells of, and what a listener to each is called with. A listener asks with `viewer.on(name,
126
+ * listener)`, at any time, and any number may ask for the same event.
127
+ */
128
+ export type ViewerEvents = {
129
+ /** NOTE: after each zoom, with screen pixels per page unit. */
130
+ zoom: [zoom: number];
131
+ /** NOTE: when the page at the middle of the pane changes. */
132
+ pageInView: [page: number];
133
+ /** NOTE: the point under the pointer while no button is held, or null once it leaves the pages. */
134
+ pointer: [point: PagePoint | null];
135
+ /** NOTE: whenever the set of marks under the pointer changes; empty once it is over none. */
136
+ pointerMarks: [marks: ReadonlyArray<ViewerMark>, point: PagePoint | null];
137
+ /** NOTE: a press that did not become a drag, with the marks under it, each as the caller set it. */
138
+ press: [point: PagePoint, marks: ReadonlyArray<ViewerMark>];
139
+ drag: [drag: ViewerDrag];
140
+ /** NOTE: after every zoom, scroll and resize: for a caller that places its own drawings with `toScreen`, and how two viewers are kept in step. */
141
+ view: [move: ViewMove];
142
+ /** NOTE: each time every page on screen has become as sharp as it needs to be, a good moment for a caller to start its own background downloads. */
143
+ idle: [];
144
+ /** NOTE: every page left with no picture after its tries failed, each time one fails or stops being failed. */
145
+ failures: [pages: ReadonlyArray<number>];
146
+ /** NOTE: the pages on screen and within a pane's height of it, in page order, each time they change: the pages a reader can reach soon, whose words a document fetches. */
147
+ pagesNear: [pages: ReadonlyArray<number>];
148
+ };
149
+ export type Viewer = {
150
+ /** NOTE: screen pixels per page unit. */
151
+ readonly zoom: number;
152
+ /** NOTE: how far out and how far in the viewer zooms, in screen pixels per page unit; a zoom asked past either stops there. */
153
+ readonly minZoom: number;
154
+ readonly maxZoom: number;
155
+ /** NOTE: the page at the middle of the pane, counted from 0, or -1 until the pane first has a size. */
156
+ readonly pageInView: number;
157
+ readonly pageCount: number;
158
+ /** NOTE: the pages left with no picture after their tries failed, counted from 0. Each page's element carries `data-failed` too. */
159
+ readonly failedPages: ReadonlyArray<number>;
160
+ /** NOTE: tries a failed page again, or every failed page when none is named. */
161
+ retry(page?: number): void;
162
+ /**
163
+ * NOTE: what the zoom is held to while the pane changes size, or null after a zoom the reader chose. A viewer
164
+ * starts held to its `fit` option, the width unless told. It changes only as the viewer zooms, so a listener to
165
+ * `zoom` hears of every change.
166
+ */
167
+ readonly fit: ViewerFit | null;
168
+ /** NOTE: how far every page is shown turned. Like `fit`, it changes only as the viewer zooms. */
169
+ readonly rotation: ViewerRotation;
170
+ /** NOTE: whether pages stand one to a row or two. Like `fit`, it changes only as the viewer zooms. */
171
+ readonly spread: ViewerSpread;
172
+ /**
173
+ * NOTE: the element that scrolls the pages and takes the keyboard. It is the caller's to name, describe and
174
+ * listen on, such as for keys of its own. What is inside it is the viewer's.
175
+ */
176
+ readonly pane: HTMLElement;
177
+ /** NOTE: calls `listener` each time the viewer tells of `event`, until the function it returns is called. */
178
+ on<Name extends keyof ViewerEvents>(event: Name, listener: (...values: ViewerEvents[Name]) => void): () => void;
179
+ /** NOTE: replaces the marks of one named layer; layers are drawn independently, so a hover can change without touching the rest. */
180
+ setLayer(layer: string, marks: ReadonlyArray<ViewerMark>): void;
181
+ setMarks(marks: ReadonlyArray<ViewerMark>): void;
182
+ /**
183
+ * NOTE: lays links over the pages. One with an address opens it in a new tab, and only when the address is a web,
184
+ * mail or telephone address; one to a page goes there. A press on a link is the browser's and is not reported.
185
+ */
186
+ setLinks(links: ReadonlyArray<ViewerLink>): void;
187
+ /**
188
+ * NOTE: gives the pages text a reader can select and copy as on any web page, and a screen reader can read: one
189
+ * list of lines for each page, in page order. A page left out, or `null` for all of them, has none. A drag that
190
+ * starts on a word then selects text and is not reported by `onDrag`.
191
+ */
192
+ setText(text: ReadonlyArray<ReadonlyArray<ViewerTextLine> | undefined> | null): void;
193
+ /** NOTE: several marks may be in focus at once, as the pieces of one change are; `reveal` brings the first into view. */
194
+ focusMark(id: string | ReadonlyArray<string> | null, options?: {
195
+ reveal?: boolean;
196
+ }): void;
197
+ revealRect(page: number, rect: Box): void;
198
+ /** NOTE: puts the caller's element at a place on a page and keeps it there; the element's content and behaviour stay the caller's. */
199
+ attach(element: HTMLElement, place: Place, options?: {
200
+ placement?: Placement;
201
+ gap?: number;
202
+ }): Attachment;
203
+ /** NOTE: where a place on a page is on the screen right now, in the window's coordinates. */
204
+ toScreen(page: number, box: Box): ScreenBox | null;
205
+ /** NOTE: the point of a page under a screen position, or null when it is over no page. */
206
+ toPage(clientX: number, clientY: number): PagePoint | null;
207
+ goToPage(page: number): void;
208
+ zoomIn(): void;
209
+ zoomOut(): void;
210
+ zoomTo(zoom: number, anchor?: {
211
+ x: number;
212
+ y: number;
213
+ }): void;
214
+ /** NOTE: zooms until the widest page is as wide as the pane, and keeps it so while the pane changes size. */
215
+ fitWidth(): void;
216
+ /**
217
+ * NOTE: zooms until any page fits the pane whole, puts the page in view in the middle of it, and keeps the zoom
218
+ * so while the pane changes size. Pages of several sizes share the one zoom, at which the largest fits.
219
+ */
220
+ fitPage(): void;
221
+ /**
222
+ * NOTE: shows every page turned a quarter further, clockwise or back, for a scan fed in sideways. A place on a
223
+ * page stays the same place, so marks, text and links turn with their page. What is at the middle of the pane
224
+ * stays there, and a zoom held to the pane is fitted again.
225
+ */
226
+ rotateRight(): void;
227
+ rotateLeft(): void;
228
+ rotateTo(rotation: ViewerRotation): void;
229
+ /**
230
+ * NOTE: stands the pages one to a row or two. Two are a pair as in an open book: the first and second page, the
231
+ * third and fourth, and a last page alone on the left. What is at the middle of the pane stays there, and a zoom
232
+ * held to the pane is fitted again, to the pair. With two to a row, the page in view is the left one of the pair.
233
+ */
234
+ setSpread(spread: ViewerSpread): void;
235
+ /** NOTE: moves the pages under the pane by a distance in page units along the screen, at once and without gliding. */
236
+ moveBy(x: number, y: number): void;
237
+ destroy(): void;
238
+ };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,21 @@
1
+ import type { ViewerPage } from "./types.js";
2
+ import type { Part, View } from "./view.js";
3
+ /** NOTE: one page of an application's own frame: the element it laid out for the page, and the page's size in page units. */
4
+ export type FramePage = {
5
+ node: HTMLElement;
6
+ size: ViewerPage;
7
+ };
8
+ export type FrameOptions = {
9
+ /** NOTE: how the frame goes to a page, for a frame that pages its own way. Left out, the pane is scrolled to the page. */
10
+ goToPage?: (page: number) => void;
11
+ };
12
+ /**
13
+ * NOTE: a view over a frame an application built itself: its own scrolling element and its own page elements, laid
14
+ * out and zoomed its own way. Everything a part asks is measured from those elements, so the application implements
15
+ * nothing and says nothing when it zooms: the view sees the pages change size.
16
+ * CONSTRAINT: each page element's box is the page. It is as wide and as high as the page times one zoom, the same
17
+ * zoom for every page, with no border or padding of its own and no transform on it or around it.
18
+ * CONSTRAINT: `pane` is an element that scrolls and holds every page element. The pane and the page elements are
19
+ * given `position: relative` where they have no position, since the parts lay their layers inside them.
20
+ */
21
+ export declare function viewOver(pane: HTMLElement, pages: ReadonlyArray<FramePage>, options?: FrameOptions): View & Part;