@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
|
@@ -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
|