@quran.ws/qvp-react-native 0.7.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.
Files changed (32) hide show
  1. package/README.md +86 -32
  2. package/android/build.gradle +16 -8
  3. package/android/src/main/java/ws/quran/qvp/rn/Codes.kt +34 -0
  4. package/android/src/main/java/ws/quran/qvp/rn/Marshal.kt +78 -30
  5. package/android/src/main/java/ws/quran/qvp/rn/QvpModule.kt +105 -50
  6. package/android/src/main/java/ws/quran/qvp/rn/QvpPageViewManager.kt +1 -0
  7. package/android/src/main/java/ws/quran/qvp/rn/QvpRnPageView.kt +55 -14
  8. package/android/src/main/java/ws/quran/qvp/rn/QvpRnWords.kt +26 -0
  9. package/ios/QvpModule.m +167 -0
  10. package/ios/QvpModule.swift +508 -0
  11. package/ios/QvpRnBytes.swift +66 -0
  12. package/ios/QvpRnCodes.swift +33 -0
  13. package/ios/QvpRnMarshal.swift +360 -0
  14. package/ios/QvpRnPageView.swift +467 -0
  15. package/ios/QvpRnPassageView.swift +160 -0
  16. package/ios/vendor/QvpEngine.json +4 -0
  17. package/ios/vendor/QvpKit/QvpDress.swift +390 -0
  18. package/ios/vendor/QvpKit/QvpEngine.swift +55 -0
  19. package/ios/vendor/QvpKit/QvpPage.swift +469 -0
  20. package/ios/vendor/QvpKit/QvpPageCache.swift +176 -0
  21. package/ios/vendor/QvpKit/QvpPageCanvas.swift +1031 -0
  22. package/ios/vendor/QvpKit/QvpPageView.swift +711 -0
  23. package/ios/vendor/QvpKit/QvpPassage.swift +240 -0
  24. package/ios/vendor/QvpKit/QvpViewPolicy.swift +26 -0
  25. package/ios/vendor/QvpKit/QvpZoom.swift +200 -0
  26. package/ios/vendor/QvpKit/QvpZoomSpring.swift +22 -0
  27. package/ios/vendor/QvpKit/Types.swift +440 -0
  28. package/ios/vendor-qvpkit.sh +36 -0
  29. package/package.json +10 -3
  30. package/qvp-react-native.podspec +97 -0
  31. package/src/codes.ts +33 -0
  32. package/src/index.tsx +171 -55
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
  */
@@ -15,18 +15,26 @@ import {
15
15
  type NativeSyntheticEvent,
16
16
  type ViewProps,
17
17
  } from 'react-native';
18
+ import { SELECTOR, TARGET } from './codes';
18
19
 
19
20
  // ── constants (mirror qvp.h) ─────────────────────────────────────────────────────────────────
20
- 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. */
21
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_*). */
22
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;
23
- 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. */
24
30
  export const LAYER = { BASE: 0, THEME: 10, HIGHLIGHT: 50, SELECTION: 60, TOP: 100 } as const;
31
+ /** The divisions of the mushaf (QVP_DIVISION_*). */
25
32
  export const DIVISION = { JUZ: 0, HIZB: 1, NISF: 2, RUBU_AL_HIZB: 3 } as const;
26
33
  /** The three kinds of ornament a page can be dressed in, in engine order. Pass one to `find` or `ofKind`. */
27
34
  export const ORNAMENT_KIND = ['ayah_mark', 'surah_header', 'page_frame'] as const;
28
35
 
29
36
  // ── colours ──────────────────────────────────────────────────────────────────────────────────
37
+ /** A colour: '#rgb', '#rrggbb', '#rrggbbaa', or a 0xRRGGBBAA number. */
30
38
  export type Color = string | number;
31
39
  /** Any accepted colour ('#rgb' | '#rrggbb' | '#rrggbbaa' | 0xRRGGBBAA) → '#rrggbbaa'. */
32
40
  export function css(c: Color | null | undefined): string | undefined {
@@ -40,82 +48,123 @@ export function css(c: Color | null | undefined): string | undefined {
40
48
  /** Colour with a replaced alpha (0..1). */
41
49
  export function rgba(c: Color, alpha: number): string {
42
50
  const h = css(c)!;
43
- return h.slice(0, 7) + Math.round(Math.max(0, Math.min(1, alpha)) * 255).toString(16).padStart(2, '0');
51
+ return h.slice(0, 7) + Math.round((Number.isNaN(alpha) ? 0 : Math.max(0, Math.min(1, alpha))) * 255).toString(16).padStart(2, '0');
44
52
  }
45
53
 
46
54
  // ── targets and selectors (same shapes as web/qvp.js T / Sel) ────────────────────────────────
55
+ // The codes come from qvp.h through codes.ts, which scripts/gen-rn-enums.py writes; the Android
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. */
47
58
  export interface TargetObj { target: number; a?: number; b?: number; c?: number; words?: number[] }
48
59
  /** 'page' | '2:255' | '2:255:3' | '2:255-257' | 'line:7' | 'surah:2' | word index | [indices] | T.* */
49
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. */
50
62
  export const T = {
51
- page: (): TargetObj => ({ target: 0 }),
52
- word: (i: number): TargetObj => ({ target: 1, a: i }),
53
- words: (ws: number[]): TargetObj => ({ target: 2, words: ws }),
54
- ayah: (s: number, a: number): TargetObj => ({ target: 3, a: s, b: a }),
55
- ayahRange: (s: number, a: number, b: number): TargetObj => ({ target: 4, a: s, b: a, c: b }),
56
- line: (n: number): TargetObj => ({ target: 5, a: n }),
57
- surah: (s: number): TargetObj => ({ target: 6, a: s }),
58
- range: (a: number, b: number): TargetObj => ({ target: 7, a, b }),
63
+ page: (): TargetObj => ({ target: TARGET.page }),
64
+ word: (i: number): TargetObj => ({ target: TARGET.word, a: i }),
65
+ words: (ws: number[]): TargetObj => ({ target: TARGET.words, words: ws }),
66
+ ayah: (s: number, a: number): TargetObj => ({ target: TARGET.ayah, a: s, b: a }),
67
+ ayahRange: (s: number, a: number, b: number): TargetObj => ({ target: TARGET.ayahRange, a: s, b: a, c: b }),
68
+ line: (n: number): TargetObj => ({ target: TARGET.line, a: n }),
69
+ surah: (s: number): TargetObj => ({ target: TARGET.surah, a: s }),
70
+ range: (a: number, b: number): TargetObj => ({ target: TARGET.range, a, b }),
59
71
  };
72
+ /** A selector as `Sel` makes it: a QVP_SELECTOR_* code and its arguments. */
60
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. */
61
75
  export const Sel = {
62
- page: (): Selector => ({ selector: 0 }),
63
- path: (p: number): Selector => ({ selector: 1, a: p }),
64
- wordPath: (w: number, nth: number): Selector => ({ selector: 2, a: w, b: nth }),
76
+ page: (): Selector => ({ selector: SELECTOR.page }),
77
+ path: (p: number): Selector => ({ selector: SELECTOR.path, a: p }),
78
+ wordPath: (w: number, nth: number): Selector => ({ selector: SELECTOR.wordPath, a: w, b: nth }),
65
79
  /** nth mark of the word (0-based, marks only) */
66
- wordMark: (w: number, nth: number): Selector => ({ selector: 3, a: w, b: nth }),
67
- wordMarkNamed: (w: number, mark: string, nth = 0): Selector => ({ selector: 4, a: w, b: markId(mark), c: nth, mark }),
68
- wordBody: (w: number): Selector => ({ selector: 5, a: w }),
69
- wordMarks: (w: number): Selector => ({ selector: 6, a: w }),
70
- word: (w: number): Selector => ({ selector: 7, a: w }),
71
- ayah: (s: number, a: number): Selector => ({ selector: 8, a: s, b: a }),
72
- line: (n: number): Selector => ({ selector: 9, a: n }),
73
- mark: (m: string | number): Selector => ({ selector: 10, a: markId(m) }),
74
- category: (c: string | number): Selector => ({ selector: 11, a: named(c, CATEGORY_NAMES) }),
75
- family: (f: string | number): Selector => ({ selector: 12, a: named(f, FAMILY_NAMES) }),
76
- kind: (k: string | number): Selector => ({ selector: 13, a: named(k, KIND_NAMES) }),
77
- decoration: (k: string | number): Selector => ({ selector: 14, a: named(k, DECORATION_NAMES) }),
78
- decorationIndex: (d: number): Selector => ({ selector: 15, a: d }),
80
+ wordMark: (w: number, nth: number): Selector => ({ selector: SELECTOR.wordMark, a: w, b: nth }),
81
+ wordMarkNamed: (w: number, mark: string, nth = 0): Selector => ({ selector: SELECTOR.wordMarkNamed, a: w, b: markId(mark), c: nth, mark }),
82
+ wordBody: (w: number): Selector => ({ selector: SELECTOR.wordBody, a: w }),
83
+ wordMarks: (w: number): Selector => ({ selector: SELECTOR.wordMarks, a: w }),
84
+ word: (w: number): Selector => ({ selector: SELECTOR.word, a: w }),
85
+ ayah: (s: number, a: number): Selector => ({ selector: SELECTOR.ayah, a: s, b: a }),
86
+ line: (n: number): Selector => ({ selector: SELECTOR.line, a: n }),
87
+ mark: (m: string | number): Selector => ({ selector: SELECTOR.mark, a: markId(m) }),
88
+ category: (c: string | number): Selector => ({ selector: SELECTOR.category, a: named(c, CATEGORY_NAMES) }),
89
+ family: (f: string | number): Selector => ({ selector: SELECTOR.family, a: named(f, FAMILY_NAMES) }),
90
+ kind: (k: string | number): Selector => ({ selector: SELECTOR.kind, a: named(k, KIND_NAMES) }),
91
+ decoration: (k: string | number): Selector => ({ selector: SELECTOR.decoration, a: named(k, DECORATION_NAMES) }),
92
+ decorationIndex: (d: number): Selector => ({ selector: SELECTOR.decorationIndex, a: d }),
79
93
  };
80
94
 
81
95
  // ── records ──────────────────────────────────────────────────────────────────────────────────
96
+ /** A text form. Every form but `rasmUthmani` needs the words sidecar (`wordsUri`). */
82
97
  export type Form = 'rasmUthmani' | 'rasmImlai' | 'qpc' | 'rasm' | 'search';
98
+ /** What a highlight paints: the words' ink, a band behind them, or both. */
83
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. */
84
101
  export type MaskMode = 'hide' | 'block' | 'blur';
102
+ /** A division of the mushaf by name. */
85
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. */
86
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. */
87
107
  export interface Word {
88
108
  index: number; surah: number; ayah: number; word: number; line: number; lineIndex: number; ayahIndex: number;
89
109
  x0: number; y0: number; x1: number; y1: number; text: string; firstPath: number; nPaths: number;
90
110
  wordKey: string; ayahKey: string; forms: Partial<Record<Form, string>>; label: string; paths: WordPath[];
91
111
  }
112
+ /** One decoration of the page: an ayah mark, a surah name, a basmalah or other furniture. The box is in page units. */
92
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 }
93
- /** The one hit shape for every hit test; the exact variants report distance 0 and `isExact`. */
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. */
94
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. */
95
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. */
96
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. */
97
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. */
98
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. */
99
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. */
100
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. */
101
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. */
102
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. */
103
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. */
104
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. */
105
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. */
106
139
  export interface CropBox { x0: number; y0: number; x1: number; y1: number; nWords: number; ayahMarkDecoration: number }
107
140
  /** A zoom and pan of the page: the scale and the offset of its origin. */
108
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
+ */
109
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. */
110
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. */
111
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. */
112
159
  export interface AtlasRubuAlHizb { rubuAlHizb: number; surah: number; ayah: number; page: number; ayahKey: string }
113
160
 
161
+ /** How a highlight looks. The paddings and the radius are page units, and `ms` is the transition time. */
114
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 }
115
163
  /** One declarative highlight; the native side keeps id → handle and calls highlight / moveHighlight / restyleHighlight / removeHighlight on diff. */
116
164
  export interface Highlight { id: string; target: Target; style?: HighlightStyle }
117
165
  /** One declarative style rule: `selector` (→ page.style) or `target` (→ page.styleTarget); `hide` → page.hide(selector). */
118
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. */
119
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 }
120
169
  /** `from` masks every word from that index to the end of the page instead of `target`. */
121
170
  export interface Mask { target?: Target; from?: number; mode?: MaskMode; blockColor?: Color; padX?: number; padY?: number; radius?: number; reverse?: boolean }
@@ -131,6 +180,7 @@ export type Lineage = 'scan' | 'font';
131
180
  export interface OrnamentPart { index: number; color: number; stroke: boolean; name: string }
132
181
  /** What an ornament may be redistributed under. Read it before you publish a dressed page. */
133
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. */
134
184
  export interface Ornament { index: number; kind: OrnamentKind; lineage: Lineage; style: string; riwayah: string; hasSlices: boolean; licence: Licence; parts: OrnamentPart[] }
135
185
  /** One mushaf or font of a set, with the ornament it has of each kind or null. */
136
186
  export interface OrnamentStyle { style: string; riwayah: string; lineage: Lineage; ayahMark: Ornament | null; surahHeader: Ornament | null; pageFrame: Ornament | null }
@@ -151,7 +201,7 @@ export interface DressSpec {
151
201
  colors?: [Ornament | number, number, Color][];
152
202
  }
153
203
  /** The engine's readout of a dressed page. `viewBox` is [x, y, w, h] in page units; `overflow` is
154
- * [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. */
155
205
  export interface DressInfo {
156
206
  ayahMark: number | null; surahHeader: number | null; pageFrame: number | null;
157
207
  ayahMarks: number; surahHeaders: number; frameRepeats: number; frameStretched: boolean;
@@ -161,11 +211,14 @@ export interface DressInfo {
161
211
  export interface Dress extends DressSpec { ornaments: QvpOrnaments | number }
162
212
 
163
213
  // ── the view ─────────────────────────────────────────────────────────────────────────────────
214
+ /** How the words are broken onto rows. */
215
+ export type Breaks = 'greedy' | 'even' | 'fitted' | 'printed';
164
216
  /** What a pinch does to the page: the engine owns the policy, this names which one. */
165
217
  export type ZoomMode = 'stepped' | 'continuous' | 'magnify';
166
218
  /** Where the reader's zoom control stands: the mode, the step, and the size in force. */
167
219
  export interface Zoom { mode: ZoomMode; step: number; zoom: number }
168
220
 
221
+ /** The props of `QvpPageView`. Lengths are dp; the declarative props are reconciled on the native side. */
169
222
  export interface QvpPageViewProps extends ViewProps {
170
223
  /** 'asset://pages/042.qvp' | 'file:///…' | '/abs/path' | 'base64:…' — the package ships no page data. */
171
224
  pageUri?: string;
@@ -177,6 +230,8 @@ export interface QvpPageViewProps extends ViewProps {
177
230
  lineSpacing?: number; fillHeight?: boolean;
178
231
  /** Draw source-native frames around surah names on the printed page. */
179
232
  surahFrames?: boolean;
233
+ /** Keep the printed rows or break them again as the reader zooms in. */
234
+ reflowBreaks?: Breaks;
180
235
  paperColor?: Color; defaultInk?: Color; selectionBand?: Color;
181
236
  selectionEnabled?: boolean; zoomEnabled?: boolean; hitMaxDistance?: number;
182
237
  /** What a pinch does to the page. `stepped` reflows onto the page's own zoom steps and is
@@ -242,6 +297,7 @@ function normColors<X>(o: X): X {
242
297
  /** Imperative handle: the page-bound module API plus the react tag. */
243
298
  export type QvpPageViewHandle = PageApi & { tag: () => number };
244
299
 
300
+ /** One mushaf page, drawn natively. Give it a ref to call the page-bound API, or use `useQvp`. */
245
301
  export const QvpPageView = forwardRef<QvpPageViewHandle, QvpPageViewProps>(function QvpPageView(props, ref) {
246
302
  const native = useRef<any>(null);
247
303
  const { theme, styles, highlights, mask, reveal, dress, paperColor, defaultInk, selectionBand, onWordTap, onDecorationTap, onEmptyTap, onSelectionChanged, onPageLoad, onRevealChanged, onSwipe, onZoomChanged, onDressChanged, onError, ...rest } = props;
@@ -283,13 +339,16 @@ export const QvpPageView = forwardRef<QvpPageViewHandle, QvpPageViewProps>(funct
283
339
  // ── the passage view ─────────────────────────────────────────────────────────────────────────
284
340
  /** Where the rows of a passage start: at the right edge, in the middle, or across the width. */
285
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. */
286
343
  export interface PassageRow { x0: number; y0: number; x1: number; y1: number; baseline: number }
287
344
  /** One word of a laid-out passage with its signs, in dp: its key, the page it is printed on and its row.
288
345
  * `x0`…`y1` is the word and its signs; `wordX0`…`wordY1` is the word alone, which leaves out the signs:
289
346
  * the word that closes an ayah leaves its medallion out. */
290
347
  export interface PassageWord { surah: number; ayah: number; word: number; wordKey: string; page: number; row: number; x0: number; y0: number; x1: number; y1: number;
291
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. */
292
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. */
293
352
  export interface PassageText { surah: number; ayah: number; text: string }
294
353
  /** A laid-out passage, in dp. `printedLineSpacing` is the passage's printed line, in page units: what
295
354
  * `lineHeight` divides by. `ellipsis` is where the view drew the ellipsis after a cut. */
@@ -298,6 +357,7 @@ export interface PassageLayout {
298
357
  isTruncated: boolean; ellipsis: number[] | null;
299
358
  rows: PassageRow[]; words: PassageWord[]; ayahs: PassageAyah[]; texts: PassageText[];
300
359
  }
360
+ /** The props of `QvpPassageView`. Lengths are dp. */
301
361
  export interface QvpPassageViewProps extends ViewProps {
302
362
  /** The pages that print the range, in any order; the same URI schemes as `pageUri`. */
303
363
  pageUris: string[];
@@ -348,28 +408,60 @@ export function QvpPassageView(props: QvpPassageViewProps) {
348
408
 
349
409
  // ── the module ───────────────────────────────────────────────────────────────────────────────
350
410
  const M = NativeModules.QvpModule as any;
411
+ // Before the first use: reading the constants of a missing module is a TypeError, and this
412
+ // message says what to do instead.
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)');
351
414
 
415
+ /** The native module's constants: the engine's name tables, and its defaults by camelCase name
416
+ * (`QVP_DEFAULT_*` in qvp.h; colours as unsigned 0xRRGGBBAA). */
417
+ interface NativeConstants { version?: string; formatVersion?: number; marks?: string[]; kinds?: string[]; families?: string[]; categories?: string[]; decorations?: string[]; divisions?: string[]; places?: string[]; defaults?: Record<string, number> }
352
418
  // The engine's name tables, read through the native module's constants; no table lives here.
353
- const NAMES = (M.getConstants?.() ?? {}) as { marks?: string[]; kinds?: string[]; families?: string[]; categories?: string[]; decorations?: string[]; divisions?: string[]; places?: string[] };
419
+ const NAMES = (M.getConstants?.() ?? {}) as NativeConstants;
354
420
  const KIND_NAMES: string[] = NAMES.kinds ?? [];
355
421
  const FAMILY_NAMES: string[] = NAMES.families ?? [];
356
422
  const CATEGORY_NAMES: string[] = NAMES.categories ?? [];
357
423
  const DECORATION_NAMES: string[] = NAMES.decorations ?? [];
424
+ /** Every mark name, from the engine; the index is the mark's id. */
358
425
  export const MARKS: string[] = NAMES.marks ?? [];
359
- /** The engine's defaults a host shows, read from the native module (QVP_DEFAULT_* in qvp.h). */
360
- export const DEFAULTS = {
361
- /** The size a scanned medallion takes when `ayahMarkScale` is 0, in rings. */
362
- AYAH_MARK_SCALE_SCAN: ((NAMES as any).defaults?.ayahMarkScaleScan ?? 0) as number,
426
+ /** One default from the native module. No fallback: a missing key means the native module
427
+ * predates this package, and the error says so. */
428
+ const nativeDefault = (key: string): number => {
429
+ const v = NAMES.defaults?.[key];
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`);
431
+ return v;
363
432
  };
364
- /** A name's id in a table; 255 when the table has no such name. */
433
+ const SNAKE = (camel: string) => camel.replace(/([A-Z])/g, '_$1').toUpperCase();
434
+ /** The engine's defaults (QVP_DEFAULT_* in qvp.h), read from the native module: every one under
435
+ * its header name, and the ones a host reads most with their own doc comments. */
436
+ export const DEFAULTS: Readonly<Record<string, number>> & {
437
+ /** The size a scanned medallion takes when `ayahMarkScale` is 0, in rings. */
438
+ readonly AYAH_MARK_SCALE_SCAN: number;
439
+ /** How far a reflowed row much shorter than its neighbours opens towards them. */
440
+ readonly REFLOW_RELAX: number;
441
+ /** How far a reflowed row's gaps may open, in word gaps. */
442
+ readonly REFLOW_MAX_STRETCH: number;
443
+ /** Side padding of the selection band, page units. */
444
+ readonly SELECTION_PAD_X: number;
445
+ } = Object.freeze({
446
+ ...Object.fromEntries(Object.entries(NAMES.defaults ?? {}).map(([k, v]) => [SNAKE(k), v])),
447
+ AYAH_MARK_SCALE_SCAN: nativeDefault('ayahMarkScaleScan'),
448
+ REFLOW_RELAX: nativeDefault('reflowRelax'),
449
+ REFLOW_MAX_STRETCH: nativeDefault('reflowMaxStretch'),
450
+ SELECTION_PAD_X: nativeDefault('selectionPadX'),
451
+ });
452
+ /** A name table of the engine (QVP_NAMES_*). */
365
453
  export type NameTable = 'marks' | 'kinds' | 'families' | 'categories' | 'decorations' | 'divisions' | 'places';
366
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. */
367
456
  export function markId(name: string | number): number { return named(name, MARKS); }
368
- if (!M) throw new Error('@quran.ws/qvp-react-native: native module QvpModule not linked (Android only for now; see README)');
369
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). */
370
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. */
371
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. */
372
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. */
373
465
  export interface HitOptions { maxDistance?: number; gapBias?: number; preferExact?: boolean }
374
466
 
375
467
  /** Page-bound queries; `tag` is the react tag of a mounted `<QvpPageView />` (`findNodeHandle`). */
@@ -390,6 +482,7 @@ export const Qvp = {
390
482
  surahHeaders: (tag: number): Promise<SurahHeader[]> => M.surahHeaders(tag),
391
483
  surahHeadersView: (tag: number): Promise<SurahHeader[]> => M.surahHeadersView(tag),
392
484
  ayahMarks: (tag: number): Promise<Marker[]> => M.ayahMarks(tag),
485
+ ayahMarksView: (tag: number): Promise<Marker[]> => M.ayahMarksView(tag),
393
486
  rosettes: (tag: number): Promise<Rosette[]> => M.rosettes(tag),
394
487
  sajdahs: (tag: number): Promise<Sajdah[]> => M.sajdahs(tag),
395
488
  ayahKeys: (tag: number): Promise<{ surah: number; ayah: number; ayahKey: string }[]> => M.ayahKeys(tag),
@@ -491,22 +584,41 @@ export const Qvp = {
491
584
  /** Cross-page lookup (atlas.qva). `const atlas = await QvpAtlas.load('asset://pages/atlas.qva')`. */
492
585
  export class QvpAtlas {
493
586
  private constructor(public readonly id: number) {}
587
+ private freed = false;
588
+ /** The native id. Throws once the atlas is freed, so every call after `free()` rejects. */
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`). */
494
591
  static async load(uri: string): Promise<QvpAtlas> { return new QvpAtlas(await Qvp.loadAtlas(uri)); }
495
- free() { return Qvp.freeAtlas(this.id); }
496
- pageOf(s: number, a: number) { return Qvp.atlasPageOf(this.id, s, a); }
497
- pageRange(page: number) { return Qvp.atlasPageRange(this.id, page); }
498
- pageCount() { return Qvp.atlasPageCount(this.id); }
499
- surah(n: number) { return Qvp.atlasSurah(this.id, n); }
500
- surahs() { return Qvp.atlasSurahs(this.id); }
501
- pageOfSurah(n: number) { return Qvp.atlasPageOfSurah(this.id, n); }
502
- division(division: DivisionKind, n: number) { return Qvp.atlasDivision(this.id, division, n); }
503
- juz(n: number) { return Qvp.atlasDivision(this.id, 'juz', n); }
504
- hizb(n: number) { return Qvp.atlasDivision(this.id, 'hizb', n); }
505
- rubuAlHizb(n: number) { return Qvp.atlasDivision(this.id, 'rubuAlHizb', n); }
506
- divisionOf(division: DivisionKind, s: number, a: number) { return Qvp.atlasDivisionOf(this.id, division, s, a); }
507
- juzOf(s: number, a: number) { return Qvp.atlasJuzOf(this.id, s, a); }
508
- pagesOfJuz(n: number) { return Qvp.atlasPagesOfJuz(this.id, n); }
509
- searchSurahs(text: string) { return Qvp.atlasSearchSurahs(this.id, text); }
592
+ /** Free the native atlas. A second call does nothing. */
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. */
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. */
597
+ async pageRange(page: number) { return Qvp.atlasPageRange(this.h, page); }
598
+ /** Get how many pages the atlas covers. */
599
+ async pageCount() { return Qvp.atlasPageCount(this.h); }
600
+ /** Get a surah by number, or null. */
601
+ async surah(n: number) { return Qvp.atlasSurah(this.h, n); }
602
+ /** Get every surah, in order. */
603
+ async surahs() { return Qvp.atlasSurahs(this.h); }
604
+ /** Get the page a surah starts on, or null. */
605
+ async pageOfSurah(n: number) { return Qvp.atlasPageOfSurah(this.h, n); }
606
+ /** Get where a division starts, or null. */
607
+ async division(division: DivisionKind, n: number) { return Qvp.atlasDivision(this.h, division, n); }
608
+ /** Get where a juz starts, or null. */
609
+ async juz(n: number) { return Qvp.atlasDivision(this.h, 'juz', n); }
610
+ /** Get where a hizb starts, or null. */
611
+ async hizb(n: number) { return Qvp.atlasDivision(this.h, 'hizb', n); }
612
+ /** Get where a rubu_al_hizb starts, or null. */
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. */
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. */
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. */
619
+ async pagesOfJuz(n: number) { return Qvp.atlasPagesOfJuz(this.h, n); }
620
+ /** Search the surah names in Arabic, Latin or English, or by number. */
621
+ async searchSurahs(text: string) { return Qvp.atlasSearchSurahs(this.h, text); }
510
622
  }
511
623
 
512
624
  /**
@@ -518,14 +630,17 @@ export class QvpOrnaments {
518
630
  /** Every ornament of the set, in the set's order. */
519
631
  readonly count: number;
520
632
  private constructor(public readonly id: number, public readonly list: Ornament[]) { this.count = list.length; }
633
+ private freed = false;
521
634
  /** Load a set from a URI (the same schemes as `pageUri`; `base64:…` for bytes in hand). */
522
635
  static async load(uri: string): Promise<QvpOrnaments> {
523
636
  const id = await Qvp.loadOrnaments(uri);
524
637
  return new QvpOrnaments(id, await Qvp.ornamentList(id));
525
638
  }
526
- free() { return Qvp.freeOrnaments(this.id); }
527
- /** The ornament of `kind` in `style`, or null; the engine looks it up. */
639
+ /** Free the native set. A second call does nothing. `list`, `ofKind` and `styles` stay readable. */
640
+ async free(): Promise<void> { if (this.freed) return; this.freed = true; await Qvp.freeOrnaments(this.id); }
641
+ /** The ornament of `kind` in `style`, or null; the engine looks it up. Rejects once the set is freed. */
528
642
  async find(kind: OrnamentKind, style: string): Promise<Ornament | null> {
643
+ if (this.freed) throw new Error('QvpOrnaments was freed');
529
644
  const i = await Qvp.ornamentFind(this.id, kind, style);
530
645
  return i < 0 ? null : this.list[i] ?? null;
531
646
  }
@@ -565,8 +680,9 @@ function dressSpec(spec: DressSpec): object {
565
680
  }
566
681
 
567
682
  type Tail<F> = F extends (tag: number, ...rest: infer R) => infer Ret ? (...rest: R) => Ret : never;
568
- 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;
569
684
  type PageMethod = (typeof pageMethods)[number];
685
+ /** The page-bound part of `Qvp`, with the tag already bound. */
570
686
  export type PageApi = { [K in PageMethod]: Tail<(typeof Qvp)[K]> };
571
687
  function bindPage(tag: () => number): PageApi {
572
688
  const out: any = {};