@quran.ws/qvp-react-native 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.
package/src/index.tsx CHANGED
@@ -2,7 +2,7 @@
2
2
  * @quran.ws/qvp-react-native — typed JS API over the native module.
3
3
  *
4
4
  * Names follow docs/API.md. Nothing here decides anything: targets, selectors and colours are marshalled
5
- * to the Kotlin library (`ws.quran.qvp`), which is JNI over crates/qvp-ffi/include/qvp.h.
5
+ * to the Kotlin library (`ws.quran.qvp`) on Android and to QvpKit on iOS, both over crates/qvp-ffi/include/qvp.h.
6
6
  * Declarative props (`highlights`, `styles`, `theme`, `mask`, `reveal`) are reconciled against engine
7
7
  * handles on the native side, so JS never sees a handle.
8
8
  */
@@ -18,16 +18,23 @@ import {
18
18
  import { SELECTOR, TARGET } from './codes';
19
19
 
20
20
  // ── constants (mirror qvp.h) ─────────────────────────────────────────────────────────────────
21
- export const KIND = { BODY: 0, MARK: 1, AYAH_NUMBER: 2, AYAH_MARK_ORNAMENT: 3, HEADER_INK: 4, OTHER: 255 } as const;
21
+ /** The path kinds (QVP_KIND_*): what a path draws. */
22
+ export const KIND = { BODY: 0, MARK: 1, AYAH_NUMBER: 2, AYAH_MARK_ORNAMENT: 3, HEADER_INK: 4, ORNAMENT: 5, PAGE_NUMBER: 6, RUNNING_HEAD: 7, OTHER: 255 } as const;
23
+ /** The mark families (QVP_FAMILY_*) that a theme colours as one. */
22
24
  export const FAMILY = { NONE: 0, DIACRITIC: 1, TANWIN: 2, DOTS: 3, WAQF: 4, SIFR: 5, SAJDAH: 6, READING_SIGN: 7 } as const;
25
+ /** The mark categories (QVP_CATEGORY_*). */
23
26
  export const CATEGORY = { NONE: 0, HARAKAH: 1, TANWIN: 2, LETTER_DOT: 3, ORTHOGRAPHIC: 4, DABT: 5, WAQF: 6, READING_SIGN: 7, STANDALONE: 8 } as const;
24
- export const DECORATION = { AYAH_MARK: 0, SURAH_NAME: 1, BASMALAH: 2, DIVISION_MARK: 3, SAJDAH_MARK: 4 } as const;
27
+ /** The decoration kinds (QVP_DECORATION_*): the page's ornaments and furniture. */
28
+ export const DECORATION = { AYAH_MARK: 0, SURAH_NAME: 1, BASMALAH: 2, DIVISION_MARK: 3, SAJDAH_MARK: 4, PAGE_NUMBER: 5, RUNNING_HEAD: 6, OTHER: 255 } as const;
29
+ /** The style layers (QVP_LAYER_*). A rule on a higher layer wins over one below it. */
25
30
  export const LAYER = { BASE: 0, THEME: 10, HIGHLIGHT: 50, SELECTION: 60, TOP: 100 } as const;
31
+ /** The divisions of the mushaf (QVP_DIVISION_*). */
26
32
  export const DIVISION = { JUZ: 0, HIZB: 1, NISF: 2, RUBU_AL_HIZB: 3 } as const;
27
33
  /** The three kinds of ornament a page can be dressed in, in engine order. Pass one to `find` or `ofKind`. */
28
34
  export const ORNAMENT_KIND = ['ayah_mark', 'surah_header', 'page_frame'] as const;
29
35
 
30
36
  // ── colours ──────────────────────────────────────────────────────────────────────────────────
37
+ /** A colour: '#rgb', '#rrggbb', '#rrggbbaa', or a 0xRRGGBBAA number. */
31
38
  export type Color = string | number;
32
39
  /** Any accepted colour ('#rgb' | '#rrggbb' | '#rrggbbaa' | 0xRRGGBBAA) → '#rrggbbaa'. */
33
40
  export function css(c: Color | null | undefined): string | undefined {
@@ -46,10 +53,12 @@ export function rgba(c: Color, alpha: number): string {
46
53
 
47
54
  // ── targets and selectors (same shapes as web/qvp.js T / Sel) ────────────────────────────────
48
55
  // The codes come from qvp.h through codes.ts, which scripts/gen-rn-enums.py writes; the Android
49
- // module reads them back with the same table.
56
+ // and iOS modules read them back with the same table.
57
+ /** A target as `T` makes it: a QVP_TARGET_* code and its arguments. */
50
58
  export interface TargetObj { target: number; a?: number; b?: number; c?: number; words?: number[] }
51
59
  /** 'page' | '2:255' | '2:255:3' | '2:255-257' | 'line:7' | 'surah:2' | word index | [indices] | T.* */
52
60
  export type Target = string | number | number[] | TargetObj;
61
+ /** Make a target: what resolves to a word list. A word is its index on the page, a line its printed number from 1. */
53
62
  export const T = {
54
63
  page: (): TargetObj => ({ target: TARGET.page }),
55
64
  word: (i: number): TargetObj => ({ target: TARGET.word, a: i }),
@@ -60,7 +69,9 @@ export const T = {
60
69
  surah: (s: number): TargetObj => ({ target: TARGET.surah, a: s }),
61
70
  range: (a: number, b: number): TargetObj => ({ target: TARGET.range, a, b }),
62
71
  };
72
+ /** A selector as `Sel` makes it: a QVP_SELECTOR_* code and its arguments. */
63
73
  export interface Selector { selector: number; a?: number; b?: number; c?: number; mark?: string }
74
+ /** Make a selector: what a style rule applies to. A mark, category, family or kind is an id or a name; a line is its printed number from 1. */
64
75
  export const Sel = {
65
76
  page: (): Selector => ({ selector: SELECTOR.page }),
66
77
  path: (p: number): Selector => ({ selector: SELECTOR.path, a: p }),
@@ -82,43 +93,78 @@ export const Sel = {
82
93
  };
83
94
 
84
95
  // ── records ──────────────────────────────────────────────────────────────────────────────────
96
+ /** A text form. Every form but `rasmUthmani` needs the words sidecar (`wordsUri`). */
85
97
  export type Form = 'rasmUthmani' | 'rasmImlai' | 'qpc' | 'rasm' | 'search';
98
+ /** What a highlight paints: the words' ink, a band behind them, or both. */
86
99
  export type HighlightMode = 'ink' | 'band' | 'both';
100
+ /** How a mask covers a word: it hides the ink, or draws a block or a blur over it. */
87
101
  export type MaskMode = 'hide' | 'block' | 'blur';
102
+ /** A division of the mushaf by name. */
88
103
  export type DivisionKind = 'juz' | 'hizb' | 'nisf' | 'rubuAlHizb';
104
+ /** One path of a word: its kind, its mark, and the mark's category and family, by id and by name. */
89
105
  export interface WordPath { index: number; kind: number; kindName: string; mark: number; markName: string; nthMark: number; nthInWord: number; category: number; categoryName: string; family: number; familyName: string; line: number }
106
+ /** One word of the page. The box is in page units; `forms` holds the text forms the page has. */
90
107
  export interface Word {
91
108
  index: number; surah: number; ayah: number; word: number; line: number; lineIndex: number; ayahIndex: number;
92
109
  x0: number; y0: number; x1: number; y1: number; text: string; firstPath: number; nPaths: number;
93
110
  wordKey: string; ayahKey: string; forms: Partial<Record<Form, string>>; label: string; paths: WordPath[];
94
111
  }
112
+ /** One decoration of the page: an ayah mark, a surah name, a basmalah or other furniture. The box is in page units. */
95
113
  export interface Deco { index: number; decoration: number; decorationName: string; surah: number; ayah: number; line: number; x0: number; y0: number; x1: number; y1: number; text: string; firstPath: number; nPaths: number }
96
114
  /** The one hit shape for every hit test; the exact variants report distance 0. `isExact` is true only when the point is inside an outline. */
97
115
  export interface Hit { word: number; path: number; decoration: number; line: number; distance: number; isExact: boolean; wordKey: string | null; ayahKey: string | null }
116
+ /** The part of one ayah that is on this page: `fragment` of `fragments`, with its words and its box in page units. */
98
117
  export interface Ayah { index: number; surah: number; ayah: number; fragment: number; fragments: number; flags: number; rubuAlHizb: number; firstWord: number; nWords: number; ayahMarkDecoration: number; bbox: number[] }
118
+ /** One printed line: its words, its box, and its band, in page units. */
99
119
  export interface Line { index: number; lineNumber: number; isHeader: boolean; firstWord: number; nWords: number; bbox: number[]; bandY0: number; bandY1: number; centre: number }
120
+ /** The selected words, their text, and the citation of the selection. */
100
121
  export interface SelectionInfo { words: number[]; text: string; citation: string; textWithCitation: string }
122
+ /** What a loaded page is: its number, its size in page units, its record counts, and the text forms it has. */
101
123
  export interface PageInfo { page: number; width: number; height: number; nLines: number; nAyahs: number; nWords: number; nPaths: number; nDecorations: number; lineSpacing: number; forms: Form[]; loadMs: number; bytes: number; uri?: string }
124
+ /** One search match. `isLooseMatch` is true when only the loose pass found it, and a UI should say so. */
102
125
  export interface Match { word: number; index: number; isLooseMatch: boolean; wordKey: string; text: string }
126
+ /** One surah with text on the page: its ayah count, its banner and basmalah flags, its place and its names. */
103
127
  export interface Surah { number: number; ayahCount: number; hasBanner: boolean; hasBasmalah: boolean; place: string; bannerDecoration: number; arabic: string; latin: string; english: string }
128
+ /** A division that starts on this page, and the ayah and line it starts at. */
104
129
  export interface Division { division: DivisionKind; number: number; surah: number; ayah: number; line: number; ayahIndex: number }
130
+ /** One ayah-mark medallion: its centre and radius, and its ornament and numeral paths. */
105
131
  export interface Marker { decoration: number; surah: number; ayah: number; line: number; cx: number; cy: number; r: number; ornamentPath: number; numeralPath: number }
132
+ /** A surah heading: the box a frame fills, and the title ink inside it. */
106
133
  export interface SurahHeader { decoration: number; surah: number; line: number; x0: number; y0: number; x1: number; y1: number; titleX0: number; titleY0: number; titleX1: number; titleY1: number }
134
+ /** One drawn hizb rosette, with the division numbers it marks. */
107
135
  export interface Rosette { decoration: number; surah: number; ayah: number; juz: number; hizb: number; nisf: number; rubuAlHizb: number; rubuAlHizbInHizb: number }
136
+ /** One sajdah sign on the page, and the ayah it belongs to. */
108
137
  export interface Sajdah { decoration: number; surah: number; ayah: number; signPath: number }
138
+ /** The crop rectangle of a target, and how many words it holds. */
109
139
  export interface CropBox { x0: number; y0: number; x1: number; y1: number; nWords: number; ayahMarkDecoration: number }
110
140
  /** A zoom and pan of the page: the scale and the offset of its origin. */
111
141
  export interface ViewState { scale: number; offsetX: number; offsetY: number }
142
+ /**
143
+ * Page to viewport. On a printed page, viewX = offsetX + x · scale and viewY = offsetY + (y + lineDy[line]) · scale.
144
+ * A reflowed page, which the default stepped zoom gives once the reader zooms in, moves words, not lines, so `lineDy`
145
+ * places nothing there and `lineDy` and `slots` hold the rows: ask `wordBoundsView` where a word is, and `hitTestView`
146
+ * what is under a point. Draw at fitX + fitScale · viewX, fitY + fitScale · viewY, and put the pan and zoom on top.
147
+ * The fit shows a box: the content, plus the dress overflow on each side when the page is dressed (`DressInfo`). On a
148
+ * printed page `fitScale` shrinks the box to fit both the viewport width and height (never above 1), and the box is
149
+ * centred. On a reflowed page `fitScale` is 1 and the content scrolls: the box is centred across the viewport, and its
150
+ * top is at the top of the viewport. `fitX` and `fitY` place the content's own origin, so the overflow sits to their
151
+ * left and above them.
152
+ */
112
153
  export interface Layout { scale: number; offsetX: number; offsetY: number; contentW: number; contentH: number; lineSpacing: number; fitScale: number; fitX: number; fitY: number; lineDy: number[]; slots: number[][] }
154
+ /** Timings and counts of the last frame and the page load, for a debug overlay. */
113
155
  export interface Stats { loadMs: number; bytes: number; baseMs: number; overlayMs: number; basePaths: number; overlayPaths: number; bands: number; hitUs: number; animating: boolean; styleHandles: number; highlightHandles: number; engineVersion: string; viewScale: number; layout: Layout | null }
156
+ /** One surah of the atlas: the page it starts on, its ayah count, its place and its names. */
114
157
  export interface AtlasSurah { number: number; page: number; ayahCount: number; place: string; arabic: string; latin: string; english: string }
158
+ /** Where a division starts: the ayah and the page. */
115
159
  export interface AtlasRubuAlHizb { rubuAlHizb: number; surah: number; ayah: number; page: number; ayahKey: string }
116
160
 
161
+ /** How a highlight looks. The paddings and the radius are page units, and `ms` is the transition time. */
117
162
  export interface HighlightStyle { mode?: HighlightMode; ink?: Color; band?: Color; height?: 'lineSpacing' | 'ink'; padX?: number; padY?: number; radius?: number; seam?: number; ms?: number; layer?: number }
118
163
  /** One declarative highlight; the native side keeps id → handle and calls highlight / moveHighlight / restyleHighlight / removeHighlight on diff. */
119
164
  export interface Highlight { id: string; target: Target; style?: HighlightStyle }
120
165
  /** One declarative style rule: `selector` (→ page.style) or `target` (→ page.styleTarget); `hide` → page.hide(selector). */
121
166
  export interface StyleRule { id: string; selector?: Selector; target?: Target; color?: Color; ms?: number; layer?: number; hide?: boolean }
167
+ /** Colours by mark family, and by mark name in `marks`. A colour left out keeps what the page has. */
122
168
  export interface Theme { ink?: Color; diacritics?: Color; dots?: Color; waqf?: Color; sifr?: Color; ayahMark?: Color; numeral?: Color; headers?: Color; marks?: Record<string, Color>; ms?: number }
123
169
  /** `from` masks every word from that index to the end of the page instead of `target`. */
124
170
  export interface Mask { target?: Target; from?: number; mode?: MaskMode; blockColor?: Color; padX?: number; padY?: number; radius?: number; reverse?: boolean }
@@ -134,6 +180,7 @@ export type Lineage = 'scan' | 'font';
134
180
  export interface OrnamentPart { index: number; color: number; stroke: boolean; name: string }
135
181
  /** What an ornament may be redistributed under. Read it before you publish a dressed page. */
136
182
  export interface Licence { id: string; status: string; redistributable: boolean; attribution: string }
183
+ /** One ornament of a set: a medallion, a band or a border, from a mushaf or a font. */
137
184
  export interface Ornament { index: number; kind: OrnamentKind; lineage: Lineage; style: string; riwayah: string; hasSlices: boolean; licence: Licence; parts: OrnamentPart[] }
138
185
  /** One mushaf or font of a set, with the ornament it has of each kind or null. */
139
186
  export interface OrnamentStyle { style: string; riwayah: string; lineage: Lineage; ayahMark: Ornament | null; surahHeader: Ornament | null; pageFrame: Ornament | null }
@@ -154,7 +201,7 @@ export interface DressSpec {
154
201
  colors?: [Ornament | number, number, Color][];
155
202
  }
156
203
  /** The engine's readout of a dressed page. `viewBox` is [x, y, w, h] in page units; `overflow` is
157
- * [left, top, right, bottom] in viewport px, how far the border reaches past the content. */
204
+ * [left, top, right, bottom] in layout px, how far the border reaches past the content. */
158
205
  export interface DressInfo {
159
206
  ayahMark: number | null; surahHeader: number | null; pageFrame: number | null;
160
207
  ayahMarks: number; surahHeaders: number; frameRepeats: number; frameStretched: boolean;
@@ -164,13 +211,14 @@ export interface DressInfo {
164
211
  export interface Dress extends DressSpec { ornaments: QvpOrnaments | number }
165
212
 
166
213
  // ── the view ─────────────────────────────────────────────────────────────────────────────────
167
- /** What a pinch does to the page: the engine owns the policy, this names which one. */
168
214
  /** How the words are broken onto rows. */
169
215
  export type Breaks = 'greedy' | 'even' | 'fitted' | 'printed';
216
+ /** What a pinch does to the page: the engine owns the policy, this names which one. */
170
217
  export type ZoomMode = 'stepped' | 'continuous' | 'magnify';
171
218
  /** Where the reader's zoom control stands: the mode, the step, and the size in force. */
172
219
  export interface Zoom { mode: ZoomMode; step: number; zoom: number }
173
220
 
221
+ /** The props of `QvpPageView`. Lengths are dp; the declarative props are reconciled on the native side. */
174
222
  export interface QvpPageViewProps extends ViewProps {
175
223
  /** 'asset://pages/042.qvp' | 'file:///…' | '/abs/path' | 'base64:…' — the package ships no page data. */
176
224
  pageUri?: string;
@@ -249,6 +297,7 @@ function normColors<X>(o: X): X {
249
297
  /** Imperative handle: the page-bound module API plus the react tag. */
250
298
  export type QvpPageViewHandle = PageApi & { tag: () => number };
251
299
 
300
+ /** One mushaf page, drawn natively. Give it a ref to call the page-bound API, or use `useQvp`. */
252
301
  export const QvpPageView = forwardRef<QvpPageViewHandle, QvpPageViewProps>(function QvpPageView(props, ref) {
253
302
  const native = useRef<any>(null);
254
303
  const { theme, styles, highlights, mask, reveal, dress, paperColor, defaultInk, selectionBand, onWordTap, onDecorationTap, onEmptyTap, onSelectionChanged, onPageLoad, onRevealChanged, onSwipe, onZoomChanged, onDressChanged, onError, ...rest } = props;
@@ -290,13 +339,16 @@ export const QvpPageView = forwardRef<QvpPageViewHandle, QvpPageViewProps>(funct
290
339
  // ── the passage view ─────────────────────────────────────────────────────────────────────────
291
340
  /** Where the rows of a passage start: at the right edge, in the middle, or across the width. */
292
341
  export type PassageAlign = 'right' | 'center' | 'justified';
342
+ /** One row of a laid-out passage, in dp: the box of its ink, and `baseline`, the y its words sit on. */
293
343
  export interface PassageRow { x0: number; y0: number; x1: number; y1: number; baseline: number }
294
344
  /** One word of a laid-out passage with its signs, in dp: its key, the page it is printed on and its row.
295
345
  * `x0`…`y1` is the word and its signs; `wordX0`…`wordY1` is the word alone, which leaves out the signs:
296
346
  * the word that closes an ayah leaves its medallion out. */
297
347
  export interface PassageWord { surah: number; ayah: number; word: number; wordKey: string; page: number; row: number; x0: number; y0: number; x1: number; y1: number;
298
348
  wordX0: number; wordY0: number; wordX1: number; wordY1: number }
349
+ /** The box of the shown words of one ayah of a laid-out passage, in dp. */
299
350
  export interface PassageAyah { surah: number; ayah: number; x0: number; y0: number; x1: number; y1: number }
351
+ /** One ayah of a passage, with its text from the page's own word records. */
300
352
  export interface PassageText { surah: number; ayah: number; text: string }
301
353
  /** A laid-out passage, in dp. `printedLineSpacing` is the passage's printed line, in page units: what
302
354
  * `lineHeight` divides by. `ellipsis` is where the view drew the ellipsis after a cut. */
@@ -305,6 +357,7 @@ export interface PassageLayout {
305
357
  isTruncated: boolean; ellipsis: number[] | null;
306
358
  rows: PassageRow[]; words: PassageWord[]; ayahs: PassageAyah[]; texts: PassageText[];
307
359
  }
360
+ /** The props of `QvpPassageView`. Lengths are dp. */
308
361
  export interface QvpPassageViewProps extends ViewProps {
309
362
  /** The pages that print the range, in any order; the same URI schemes as `pageUri`. */
310
363
  pageUris: string[];
@@ -357,7 +410,7 @@ export function QvpPassageView(props: QvpPassageViewProps) {
357
410
  const M = NativeModules.QvpModule as any;
358
411
  // Before the first use: reading the constants of a missing module is a TypeError, and this
359
412
  // message says what to do instead.
360
- if (!M) throw new Error('@quran.ws/qvp-react-native: native module QvpModule not linked (Android only for now; see README)');
413
+ if (!M) throw new Error('@quran.ws/qvp-react-native: native module QvpModule not linked; rebuild the app (on iOS, run pod install first; see README)');
361
414
 
362
415
  /** The native module's constants: the engine's name tables, and its defaults by camelCase name
363
416
  * (`QVP_DEFAULT_*` in qvp.h; colours as unsigned 0xRRGGBBAA). */
@@ -368,12 +421,13 @@ const KIND_NAMES: string[] = NAMES.kinds ?? [];
368
421
  const FAMILY_NAMES: string[] = NAMES.families ?? [];
369
422
  const CATEGORY_NAMES: string[] = NAMES.categories ?? [];
370
423
  const DECORATION_NAMES: string[] = NAMES.decorations ?? [];
424
+ /** Every mark name, from the engine; the index is the mark's id. */
371
425
  export const MARKS: string[] = NAMES.marks ?? [];
372
426
  /** One default from the native module. No fallback: a missing key means the native module
373
427
  * predates this package, and the error says so. */
374
428
  const nativeDefault = (key: string): number => {
375
429
  const v = NAMES.defaults?.[key];
376
- if (typeof v !== 'number') throw new Error(`@quran.ws/qvp-react-native: native module QvpModule is older than this package (no default ${key}); rebuild the Android app`);
430
+ if (typeof v !== 'number') throw new Error(`@quran.ws/qvp-react-native: native module QvpModule is older than this package (no default ${key}); rebuild the app`);
377
431
  return v;
378
432
  };
379
433
  const SNAKE = (camel: string) => camel.replace(/([A-Z])/g, '_$1').toUpperCase();
@@ -395,14 +449,19 @@ export const DEFAULTS: Readonly<Record<string, number>> & {
395
449
  REFLOW_MAX_STRETCH: nativeDefault('reflowMaxStretch'),
396
450
  SELECTION_PAD_X: nativeDefault('selectionPadX'),
397
451
  });
398
- /** A name's id in a table; 255 when the table has no such name. */
452
+ /** A name table of the engine (QVP_NAMES_*). */
399
453
  export type NameTable = 'marks' | 'kinds' | 'families' | 'categories' | 'decorations' | 'divisions' | 'places';
400
454
  const named = (v: string | number, names: string[]) => { if (typeof v === 'number') return v; const i = names.indexOf(v); return i < 0 ? 255 : i; };
455
+ /** Get a mark's id by its name; 255 when the engine has no such mark. A number passes through. */
401
456
  export function markId(name: string | number): number { return named(name, MARKS); }
402
457
 
458
+ /** How `search` matches: the form, the mode, whether it normalises, whether it tries the loose pass, and the most matches (0 for all). */
403
459
  export interface SearchOptions { form?: Form; mode?: 'includes' | 'exact' | 'prefix'; normalize?: boolean; looseMatch?: boolean; limit?: number }
460
+ /** How `text` joins the words: the form, and the separators between words and between lines. */
404
461
  export interface TextOptions { form?: Form; wordSep?: string; lineSep?: string }
462
+ /** How a crop is cut: the padding in page units, whether the ayah marks stay, and the background. */
405
463
  export interface CropOptions { pad?: number; keepAyahMarks?: boolean; background?: Color }
464
+ /** How a gap-aware hit test resolves a point: the farthest distance (0 for no bound), the gap bias, and whether an exact hit wins. */
406
465
  export interface HitOptions { maxDistance?: number; gapBias?: number; preferExact?: boolean }
407
466
 
408
467
  /** Page-bound queries; `tag` is the react tag of a mounted `<QvpPageView />` (`findNodeHandle`). */
@@ -423,6 +482,7 @@ export const Qvp = {
423
482
  surahHeaders: (tag: number): Promise<SurahHeader[]> => M.surahHeaders(tag),
424
483
  surahHeadersView: (tag: number): Promise<SurahHeader[]> => M.surahHeadersView(tag),
425
484
  ayahMarks: (tag: number): Promise<Marker[]> => M.ayahMarks(tag),
485
+ ayahMarksView: (tag: number): Promise<Marker[]> => M.ayahMarksView(tag),
426
486
  rosettes: (tag: number): Promise<Rosette[]> => M.rosettes(tag),
427
487
  sajdahs: (tag: number): Promise<Sajdah[]> => M.sajdahs(tag),
428
488
  ayahKeys: (tag: number): Promise<{ surah: number; ayah: number; ayahKey: string }[]> => M.ayahKeys(tag),
@@ -527,22 +587,37 @@ export class QvpAtlas {
527
587
  private freed = false;
528
588
  /** The native id. Throws once the atlas is freed, so every call after `free()` rejects. */
529
589
  private get h(): number { if (this.freed) throw new Error('QvpAtlas was freed'); return this.id; }
590
+ /** Load the atlas from a URI (the same schemes as `pageUri`). */
530
591
  static async load(uri: string): Promise<QvpAtlas> { return new QvpAtlas(await Qvp.loadAtlas(uri)); }
531
592
  /** Free the native atlas. A second call does nothing. */
532
593
  async free(): Promise<void> { if (this.freed) return; this.freed = true; await Qvp.freeAtlas(this.id); }
594
+ /** Get the page an ayah is on, or null. */
533
595
  async pageOf(s: number, a: number) { return Qvp.atlasPageOf(this.h, s, a); }
596
+ /** Get the first and last ayah of a page, or null. */
534
597
  async pageRange(page: number) { return Qvp.atlasPageRange(this.h, page); }
598
+ /** Get how many pages the atlas covers. */
535
599
  async pageCount() { return Qvp.atlasPageCount(this.h); }
600
+ /** Get a surah by number, or null. */
536
601
  async surah(n: number) { return Qvp.atlasSurah(this.h, n); }
602
+ /** Get every surah, in order. */
537
603
  async surahs() { return Qvp.atlasSurahs(this.h); }
604
+ /** Get the page a surah starts on, or null. */
538
605
  async pageOfSurah(n: number) { return Qvp.atlasPageOfSurah(this.h, n); }
606
+ /** Get where a division starts, or null. */
539
607
  async division(division: DivisionKind, n: number) { return Qvp.atlasDivision(this.h, division, n); }
608
+ /** Get where a juz starts, or null. */
540
609
  async juz(n: number) { return Qvp.atlasDivision(this.h, 'juz', n); }
610
+ /** Get where a hizb starts, or null. */
541
611
  async hizb(n: number) { return Qvp.atlasDivision(this.h, 'hizb', n); }
612
+ /** Get where a rubu_al_hizb starts, or null. */
542
613
  async rubuAlHizb(n: number) { return Qvp.atlasDivision(this.h, 'rubuAlHizb', n); }
614
+ /** Get the number of the division that holds an ayah, or null. */
543
615
  async divisionOf(division: DivisionKind, s: number, a: number) { return Qvp.atlasDivisionOf(this.h, division, s, a); }
616
+ /** Get the number of the juz that holds an ayah, or null. */
544
617
  async juzOf(s: number, a: number) { return Qvp.atlasJuzOf(this.h, s, a); }
618
+ /** Get the first and last page of a juz, or null. */
545
619
  async pagesOfJuz(n: number) { return Qvp.atlasPagesOfJuz(this.h, n); }
620
+ /** Search the surah names in Arabic, Latin or English, or by number. */
546
621
  async searchSurahs(text: string) { return Qvp.atlasSearchSurahs(this.h, text); }
547
622
  }
548
623
 
@@ -605,8 +680,9 @@ function dressSpec(spec: DressSpec): object {
605
680
  }
606
681
 
607
682
  type Tail<F> = F extends (tag: number, ...rest: infer R) => infer Ret ? (...rest: R) => Ret : never;
608
- const pageMethods = ['info', 'words', 'word', 'ayahs', 'lines', 'decorations', 'findWord', 'targetWords', 'wordForm', 'hasForm', 'attachWords', 'surahs', 'divisions', 'surahHeaders', 'surahHeadersView', 'ayahMarks', 'rosettes', 'sajdahs', 'ayahKeys', 'ayahWordCount', 'reciteMap', 'wordLabel', 'ayahLabel', 'text', 'search', 'citation', 'hitTestExact', 'hitTest', 'hitTestExactView', 'hitTestView', 'layoutLineSpacingToFill', 'layoutWastedFraction', 'layoutPrintedHeight', 'grid', 'wordBoundsView', 'currentLayout', 'relayout', 'resetView', 'stats', 'select', 'clearSelection', 'selection', 'selectionText', 'unmaskNext', 'maskBack', 'unmaskWord', 'maskWord', 'unmaskAll', 'maskAll', 'maskHidden', 'maskWords', 'revealStepCount', 'revealPosition', 'revealStepOf', 'cropBounds', 'cropSvg', 'dress', 'undress', 'dressClamp', 'dressView', 'dressInfo', 'dressRevision'] as const;
683
+ const pageMethods = ['info', 'words', 'word', 'ayahs', 'lines', 'decorations', 'findWord', 'targetWords', 'wordForm', 'hasForm', 'attachWords', 'surahs', 'divisions', 'surahHeaders', 'surahHeadersView', 'ayahMarks', 'ayahMarksView', 'rosettes', 'sajdahs', 'ayahKeys', 'ayahWordCount', 'reciteMap', 'wordLabel', 'ayahLabel', 'text', 'search', 'citation', 'hitTestExact', 'hitTest', 'hitTestExactView', 'hitTestView', 'layoutLineSpacingToFill', 'layoutWastedFraction', 'layoutPrintedHeight', 'grid', 'wordBoundsView', 'currentLayout', 'relayout', 'resetView', 'stats', 'select', 'clearSelection', 'selection', 'selectionText', 'unmaskNext', 'maskBack', 'unmaskWord', 'maskWord', 'unmaskAll', 'maskAll', 'maskHidden', 'maskWords', 'revealStepCount', 'revealPosition', 'revealStepOf', 'cropBounds', 'cropSvg', 'dress', 'undress', 'dressClamp', 'dressView', 'dressInfo', 'dressRevision'] as const;
609
684
  type PageMethod = (typeof pageMethods)[number];
685
+ /** The page-bound part of `Qvp`, with the tag already bound. */
610
686
  export type PageApi = { [K in PageMethod]: Tail<(typeof Qvp)[K]> };
611
687
  function bindPage(tag: () => number): PageApi {
612
688
  const out: any = {};