@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.
- package/README.md +86 -32
- package/android/build.gradle +16 -8
- package/android/src/main/java/ws/quran/qvp/rn/Codes.kt +34 -0
- package/android/src/main/java/ws/quran/qvp/rn/Marshal.kt +78 -30
- package/android/src/main/java/ws/quran/qvp/rn/QvpModule.kt +105 -50
- package/android/src/main/java/ws/quran/qvp/rn/QvpPageViewManager.kt +1 -0
- package/android/src/main/java/ws/quran/qvp/rn/QvpRnPageView.kt +55 -14
- package/android/src/main/java/ws/quran/qvp/rn/QvpRnWords.kt +26 -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/codes.ts +33 -0
- 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`)
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
52
|
-
word: (i: number): TargetObj => ({ target:
|
|
53
|
-
words: (ws: number[]): TargetObj => ({ target:
|
|
54
|
-
ayah: (s: number, a: number): TargetObj => ({ target:
|
|
55
|
-
ayahRange: (s: number, a: number, b: number): TargetObj => ({ target:
|
|
56
|
-
line: (n: number): TargetObj => ({ target:
|
|
57
|
-
surah: (s: number): TargetObj => ({ target:
|
|
58
|
-
range: (a: number, b: number): TargetObj => ({ target:
|
|
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:
|
|
63
|
-
path: (p: number): Selector => ({ selector:
|
|
64
|
-
wordPath: (w: number, nth: number): Selector => ({ selector:
|
|
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:
|
|
67
|
-
wordMarkNamed: (w: number, mark: string, nth = 0): Selector => ({ selector:
|
|
68
|
-
wordBody: (w: number): Selector => ({ selector:
|
|
69
|
-
wordMarks: (w: number): Selector => ({ selector:
|
|
70
|
-
word: (w: number): Selector => ({ selector:
|
|
71
|
-
ayah: (s: number, a: number): Selector => ({ selector:
|
|
72
|
-
line: (n: number): Selector => ({ selector:
|
|
73
|
-
mark: (m: string | number): Selector => ({ selector:
|
|
74
|
-
category: (c: string | number): Selector => ({ selector:
|
|
75
|
-
family: (f: string | number): Selector => ({ selector:
|
|
76
|
-
kind: (k: string | number): Selector => ({ selector:
|
|
77
|
-
decoration: (k: string | number): Selector => ({ selector:
|
|
78
|
-
decorationIndex: (d: number): Selector => ({ selector:
|
|
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
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
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
|
-
|
|
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
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
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
|
-
|
|
527
|
-
|
|
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 = {};
|