@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/README.md +78 -35
- package/android/build.gradle +16 -8
- package/android/src/main/java/ws/quran/qvp/rn/QvpModule.kt +1 -0
- package/ios/QvpModule.m +167 -0
- package/ios/QvpModule.swift +508 -0
- package/ios/QvpRnBytes.swift +66 -0
- package/ios/QvpRnCodes.swift +33 -0
- package/ios/QvpRnMarshal.swift +360 -0
- package/ios/QvpRnPageView.swift +467 -0
- package/ios/QvpRnPassageView.swift +160 -0
- package/ios/vendor/QvpEngine.json +4 -0
- package/ios/vendor/QvpKit/QvpDress.swift +390 -0
- package/ios/vendor/QvpKit/QvpEngine.swift +55 -0
- package/ios/vendor/QvpKit/QvpPage.swift +469 -0
- package/ios/vendor/QvpKit/QvpPageCache.swift +176 -0
- package/ios/vendor/QvpKit/QvpPageCanvas.swift +1031 -0
- package/ios/vendor/QvpKit/QvpPageView.swift +711 -0
- package/ios/vendor/QvpKit/QvpPassage.swift +240 -0
- package/ios/vendor/QvpKit/QvpViewPolicy.swift +26 -0
- package/ios/vendor/QvpKit/QvpZoom.swift +200 -0
- package/ios/vendor/QvpKit/QvpZoomSpring.swift +22 -0
- package/ios/vendor/QvpKit/Types.swift +440 -0
- package/ios/vendor-qvpkit.sh +36 -0
- package/package.json +10 -3
- package/qvp-react-native.podspec +97 -0
- package/src/index.tsx +86 -10
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`)
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
|
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 (
|
|
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
|
|
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
|
|
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 = {};
|