@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
@@ -0,0 +1,176 @@
1
+ // Page lifecycle for hosts that show many pages (a pager over the whole
2
+ // mushaf): permanent controllers, cycling page data.
3
+ //
4
+ // The invariant that makes blank pages impossible to express: a view takes
5
+ // its page's controller ONCE and keeps it for life — the cache never hands a
6
+ // page number two different controllers. Only the heavy `QvpPage` data moves:
7
+ // it is loaded on demand, evicted least-recently-used under memory pressure,
8
+ // and REATTACHED to the same permanent controller when the page comes back
9
+ // into reach. `QvpPageCanvas` observes its controller, so a reattach redraws
10
+ // with no view participation.
11
+ //
12
+ // The host supplies two closures: `data` reads a page's `.qvp` bytes (the
13
+ // cache never guesses at bundles), and `configure` applies host styling to a
14
+ // freshly attached page (ink, crop, layout mode). Call `setCurrentPage` from
15
+ // the pager so neighbors preload and stay off the eviction list; call
16
+ // `reconfigure()` after a theme change to recolorStyle every live page.
17
+ #if canImport(SwiftUI)
18
+ import SwiftUI
19
+
20
+ /// The pages of a pager: one controller per page number for life, with the page data loaded
21
+ /// on demand and evicted least recently used.
22
+ @available(iOS 17.0, macOS 14.0, *)
23
+ @MainActor @Observable
24
+ public final class QvpPageCache {
25
+
26
+ @ObservationIgnored private var controllers: [Int: QvpCanvasController] = [:]
27
+ @ObservationIgnored private var pages: [Int: QvpPage] = [:]
28
+ @ObservationIgnored private var loads: [Int: Task<Void, Never>] = [:]
29
+ /// LRU order of page numbers, freshest last.
30
+ @ObservationIgnored private var recency: [Int] = []
31
+ /// Where the pager is, once the host has said; nil until then, so nothing is
32
+ /// protected from eviction and no distance is ever computed against a sentinel.
33
+ @ObservationIgnored private var currentPage: Int? = nil
34
+ /// How many pages the host shows at once, from the same call.
35
+ @ObservationIgnored private var span: Int = 1
36
+
37
+ @ObservationIgnored private let capacity: Int
38
+ @ObservationIgnored private let pageRange: ClosedRange<Int>
39
+ @ObservationIgnored private let data: (Int) async -> Data?
40
+ @ObservationIgnored private let configure: (QvpPage, QvpCanvasController) -> Void
41
+
42
+ /// - Parameters:
43
+ /// - capacity: live `QvpPage`s kept at most (the pages on screen and the
44
+ /// screens either side are never evicted, whatever their age — three
45
+ /// pages at one per screen, six at two).
46
+ /// - pageRange: valid page numbers (`setCurrentPage` preloads inside it).
47
+ /// - data: reads one page's `.qvp` bytes; called off the main actor's
48
+ /// critical path, may do file IO.
49
+ /// - configure: host styling applied every time a page is (re)attached.
50
+ public init(capacity: Int = 12,
51
+ pageRange: ClosedRange<Int> = 1...604,
52
+ data: @escaping (Int) async -> Data?,
53
+ configure: @escaping (QvpPage, QvpCanvasController) -> Void = { _, _ in }) {
54
+ self.capacity = max(capacity, 4)
55
+ self.pageRange = pageRange
56
+ self.data = data
57
+ self.configure = configure
58
+ }
59
+
60
+ /// The PERMANENT controller for a page — same instance for the life of
61
+ /// the cache. Ensures the page data is loaded and attached, now or as
62
+ /// soon as the load lands.
63
+ public func controller(for pageNumber: Int) -> QvpCanvasController {
64
+ let controller: QvpCanvasController
65
+ if let existing = controllers[pageNumber] {
66
+ controller = existing
67
+ } else {
68
+ controller = QvpCanvasController()
69
+ controllers[pageNumber] = controller
70
+ }
71
+ ensureLoaded(pageNumber)
72
+ return controller
73
+ }
74
+
75
+ /// The live page data for a page number, if currently attached.
76
+ public func page(for pageNumber: Int) -> QvpPage? { pages[pageNumber] }
77
+
78
+ /// Tell the cache where the pager is: the pages on screen and the screens
79
+ /// either side are (re)loaded — which also restores a previously evicted
80
+ /// page onto a still-living view — and become ineligible for eviction.
81
+ ///
82
+ /// `span` is how many pages the host shows at once and `pageNumber` the
83
+ /// first of them, so a host laying two pages side by side passes the
84
+ /// spread's first page and 2: the screen before it, the screen, and the
85
+ /// screen after it are all kept ready, and a swipe never lands on a blank
86
+ /// half. At the default 1 this is the page and its two neighbors, as it
87
+ /// always was.
88
+ public func setCurrentPage(_ pageNumber: Int, span: Int = 1) {
89
+ currentPage = pageNumber
90
+ self.span = max(span, 1)
91
+ for neighbor in protectedRange(around: pageNumber) where pageRange.contains(neighbor) {
92
+ ensureLoaded(neighbor)
93
+ }
94
+ trim()
95
+ }
96
+
97
+ /// The pages kept ready around `page`: one screen before it, its own
98
+ /// screen, and one screen after — `page − span` through
99
+ /// `page + 2·span − 1`. Takes the page rather than reading `currentPage`,
100
+ /// so there is no "no current page yet" case to stand for: a `ClosedRange`
101
+ /// has no empty value, and one written to mean empty traps where it is
102
+ /// built, not where it is used.
103
+ private func protectedRange(around page: Int) -> ClosedRange<Int> {
104
+ (page - span)...(page + 2 * span - 1)
105
+ }
106
+
107
+ /// Re-run the host's `configure` on every live page and redraw — call
108
+ /// after a theme change.
109
+ public func reconfigure() {
110
+ for (pageNumber, page) in pages {
111
+ guard let controller = controllers[pageNumber] else { continue }
112
+ configure(page, controller)
113
+ controller.invalidate()
114
+ }
115
+ }
116
+
117
+ /// Load a page's engine data and attach it to the permanent controller,
118
+ /// unless it is already live or already loading.
119
+ private func ensureLoaded(_ pageNumber: Int) {
120
+ touch(pageNumber)
121
+ guard pages[pageNumber] == nil, loads[pageNumber] == nil else { return }
122
+ loads[pageNumber] = Task { [weak self] in
123
+ // Single exit: the pending-load slot is ALWAYS cleared, so one
124
+ // failed load can never poison its page number forever.
125
+ await self?.performLoad(pageNumber)
126
+ self?.loads[pageNumber] = nil
127
+ }
128
+ }
129
+
130
+ private func performLoad(_ pageNumber: Int) async {
131
+ guard let bytes = await data(pageNumber), let page = try? QvpPage(bytes: bytes) else { return }
132
+ // Raced by a concurrent load that landed first: keep the winner.
133
+ guard pages[pageNumber] == nil else { page.close(); return }
134
+ _ = page.buildPaths()
135
+ let controller = controller(for: pageNumber)
136
+ configure(page, controller)
137
+ pages[pageNumber] = page
138
+ // Attaching redraws any live canvas showing this controller.
139
+ controller.page = page
140
+ touch(pageNumber)
141
+ trim()
142
+ }
143
+
144
+ /// Most-recently-used order: last element = freshest.
145
+ private func touch(_ pageNumber: Int) {
146
+ recency.removeAll { $0 == pageNumber }
147
+ recency.append(pageNumber)
148
+ }
149
+
150
+ /// The pages on screen and the screens either side are never evicted.
151
+ /// Nothing is protected until the host has said where the pager is.
152
+ private func isProtected(_ pageNumber: Int) -> Bool {
153
+ guard let current = currentPage else { return false }
154
+ return protectedRange(around: current).contains(pageNumber)
155
+ }
156
+
157
+ /// Close least-recently-used pages beyond capacity. Never a page on
158
+ /// screen or on the screens either side of it.
159
+ private func trim() {
160
+ while pages.count > capacity {
161
+ guard let victim = recency.first(where: { !isProtected($0) && pages[$0] != nil }),
162
+ let evicted = pages.removeValue(forKey: victim) else { return }
163
+ // DETACH before closing: the permanent controller stays with any
164
+ // view that holds it; its canvas draws nothing until the page is
165
+ // reattached by a later ensureLoaded.
166
+ controllers[victim]?.page = nil
167
+ evicted.close()
168
+ recency.removeAll { $0 == victim }
169
+ }
170
+ }
171
+
172
+ // No deinit close: `QvpPage` frees its native data when its last reference goes,
173
+ // so a controller retained by a surviving view keeps its page open after the
174
+ // cache itself is released.
175
+ }
176
+ #endif