TextView Core (macOS & iOS)
Dokumentasi teknis mendalam untuk implementasi custom TextView pada Maktabah (macOS & iOS), yang bertugas me-render teks Arab kompleks, menangani tasykil (harakat), mengelola sinkronisasi anotasi, dan mengoordinasikan rendering dengan antrean task mandiri.
Alur Arsitektur (Architecture Pipeline)
Alur perenderan pada TextView melibatkan ViewModel, cache halaman, pemroses teks (Core Engine), penyimpanan lokal, dan pembungkus spesifik platform (AppKit / UIKit).
flowchart TD
subgraph Core ["Core Text Processing & State"]
VM["ReaderViewModel"] -->|"Fetch Page"| Cache[("BookPageCache (LRU)")]
VM -->|"Fetch Anotasi"| AnnStore[("AnnotationStore")]
VM -->|"Raw Content"| TR["ArabicTextRenderer"]
State["TextViewState<br/>(Font, Harakat, LineHeight)"] -->|"Konfigurasi Style"| TR
Calc["ArabicRangeCalculator<br/>(Display ↔ Source Mapping)"]
end
Core ~~~ Mac_Platform
subgraph Mac_Platform ["macOS Platform (AppKit)"]
MTV["IbarotTextView (NSTextView)"]
CALFMac["CachedArabicLayoutFragment<br/>(CGLayer Offscreen Buffer)"]
MenuMac["NSMenu Custom Context Menu"]
MTV --> CALFMac
MenuMac -.->|"Remap Range"| Calc
end
Mac_Platform ~~~ IOS_Platform
subgraph IOS_Platform ["iOS Platform (UIKit & SwiftUI)"]
IOSW["iOSIbarotTextView<br/>(SwiftUI UIViewRepresentable)"]
ITV["iOSCustomIbarotTextView (UITextView)"]
CALFIOS["CachedArabicLayoutFragment<br/>(TextKit 2 Buffer)"]
MenuIOS["UIEditMenuInteraction & UIMenu"]
IOSW -->|"Update UIView"| ITV
ITV --> CALFIOS
MenuIOS -.->|"Remap Range"| Calc
end
TR -->|"ArabicRenderResult"| MTV
TR -->|"ArabicRenderResult"| IOSW
classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;
class MTV,CALFMac,MenuMac,IOSW,ITV,CALFIOS,MenuIOS ui;
class VM vm;
class TR,Calc,State store;
class Cache,AnnStore db;
Penggunaan SerialTask (SerialTaskQueue) di dalam TextView
Pengelolaan konkurensi di IbarotTextView (khusus macOS) dikelola menggunakan SerialTaskQueue. Class ini memastikan task-task berat di background thread dieksekusi secara serial dan berurutan, guna menghindari race condition saat antarmuka me-render atau melompat ke lokasi teks tertentu.
Contoh penggunaan:
-
Pemuatan Teks (
loadIbarotText): Menyusun dan menerapkan teks Arab berukuran panjang memerlukan pemrosesan fonetis dan ligatur. Ketika pengguna berpindah halaman dengan cepat, task sebelumnya dapat dibatalkan (taskQueue.cancelAll()) dan digantikan oleh rendering halaman baru yang berjalan di antrean terpisah sebelum dikembalikan ke@MainActor. -
Pencarian & Anotasi (
highlightAndScrollToAnns,highlightAndScrollToText): Operasi ini menunggu proses layouting dokumen selesai. Membungkus fungsi perenderan ke antrean serial menjamin bahwa layoutManager sudah tuntas menghitung metrik sebelumscrollRangeToVisible(_:)dipanggil.
Penjelasan Detail Mengenai CachedArabicLayoutFragment
CachedArabicLayoutFragment adalah turunan spesifik dari NSTextLayoutFragment pada framework TextKit 2, yang difungsikan baik di platform AppKit (IbarotTextView) maupun UIKit (iOSCustomIbarotTextView).
Alur Kerja Utama:
- Mengambil alih proses
draw(at:in:)dengan membuat offscreenCGLayersebagai memori penyangga (buffer). - Jika layer belum ada (karena teks baru di-scroll atau baru dimuat), sistem akan membuat konteks grafis mandiri, me-render paragraf di layer tersebut, kemudian menyimpannya ke memori cache.
- Untuk setiap frame berulang di lokasi layar yang sama (misalnya saat scrolling di paragraf sebelahnya tanpa mengubah paragraf bersangkutan), fragment hanya akan melakukan operasi draw berkecepatan tinggi dari
CGLayeryang disimpan tanpa memicu ulang perenderan font/ligatur kompleks (seperti font KFGQPC Uthman Taha). - Begitu terjadi seleksi (highlight), penyuntingan teks, atau perubahan warna, metode
invalidateLayout()otomatis dipanggil untuk menyetel nilaicachedLayer = nil, memaksa siklus pembuatan cache diulang.
Enhanced Underline & Skip-Ink (EnhancedUnderlineRenderer)
Pada beberapa font kaligrafi Arab (khususnya Lateef dan Arabic Typesetting), tabel metrik OpenType (post table) memiliki nilai underlineThickness yang sangat tipis sehingga garis bawah bawaan CoreText/TextKit 2 nyaris transparan (hairline).
Untuk mengatasi hal ini tanpa merusak rendering font standar (seperti Scheherazade New atau KFGQPC), Maktabah mengimplementasikan EnhancedUnderlineRenderer:
flowchart TD
A["CachedArabicLayoutFragment<br/>(TextKit 2 & CGLayer Buffer)"] -->|"Delegates drawing"| B["EnhancedUnderlineRenderer<br/>(CoreText Vector Pipeline)"]
B --> C["1. Scan & Filter<br/>(Bypass font standar jika bukan isThinUnderlineFont)"]
B --> D["2. Line Geometry<br/>(Envelope minX..maxX, baseline + 0.32 em, trim spasi)"]
B --> E["3. Vector Bézier Skip-Ink<br/>(CTFontCreatePathForGlyph + clip + clear cutout)"]
- Zero-Cost Bypass:
Sebelum memproses paragraf, sistem memeriksa
TextViewState.shared.isThinUnderlineFont(thickness / pointSize < 0.025). Font standar akan 100% menggunakan rendering garis bawah native AppKit/UIKit. - Geometri Stabil & Berkelanjutan:
- Garis ditempatkan secara linier pada jarak
0.32 emdi bawah baseline (UnderlineMetrics.offsetEm = 0.32), menjaga garis tetap berada di bawah harakat kasrah/kasratain pada seluruh ukuran font. - Menghitung rentang visual horizontal
minX...maxXdari seluruh karakter anotasi, sehingga garis bawah berjalan mulus dan solid melintasi spasi antarkata. - Bézier Vector Path Skip-Ink:
- Mengekstrak kurva garis luar glyph menggunakan
CTFontCreatePathForGlyph. - Hanya glyph yang ujung tintanya menembus pita garis bawah (
descent > bandTopBelowBaseline - gap) yang diproses. - Memotong kurva tinta pada pita garis bawah dengan mode
.cleardan batas clipping ketat. Hal ini mempertahankan garis bawah pada rongga/sela huruf (seperti hurufعatauح) persis seperti perilaku native CoreText.
Manipulasi Anotasi
Manipulasi anotasi membutuhkan konversi indeks rentang (range mapping) yang tepat antara string sumber asli (basis data) dan string yang dimodifikasi oleh ArabicTextRenderer (yang menghapus tag HTML, membersihkan tasykil, atau merender ligatur).
Proses Manipulasi:
-
Pemetaan Rentang (Range Mapping): Saat anotasi diambil dari
AnnotationStore, model memiliki propertirangedanrangeDiacritics. Bergantung pada status aktif harakat (dariTextViewState.shared.showHarakat), rentang yang sesuai dipetakan ulang melaluiArabicRenderResult.remapDisplayedRange(_:). -
Penerapan Atribut Dasar: Fungsi internal menerapkan
NSAttributedString.Key.backgroundColor(untuk Highlight) atau.underlineStyle(untuk Underline) pada ruang indeks yang telah dipetakan tersebut. -
Penyematan Metadata Tautan (Link & Annotation ID): Apabila anotasi dikonfigurasi untuk dapat diklik (berdasarkan preferensi
clickableAnnotation), rentang anotasi disuntikkan atribut.linkdengan URL kustom (annotation://{id}) serta disematkan atribut khususannotationID.
Menu Kontekstual (iOS / macOS)
Menu interaksi dikustomisasi untuk membatasi opsi bawaan yang tidak relevan dengan pengalaman teks RTL serta menyuntikkan menu pengelolaan Highlight dan Note.
Di AppKit, menu utama ditangani melalui override menu(for event: NSEvent) -> NSMenu?.
- Membuang opsi Substitution, Speaking, atau operasi mutasi (Cut, Paste) karena teks bersifat read-only.
- Menambahkan baris menu warna yang direpresentasikan melalui View khusus (
AnnotationColorMenuView). - Menu mendeteksi apakah indeks karakter di bawah kursor (dihitung menggunakan koordinat kursor dan
textLayoutManager) memiliki anotasi (dengan mengambil nilaiannotationID). - Jika ada, menu Edit Note dan Delete ditambahkan. Jika belum, dimunculkan menu Add Note.
- Menyediakan fitur salin rujukan (Copy with Reference) khusus.
Di UIKit (iOS 16+), pembuatan menu berpusat di delegasi editMenuForTextIn dari UITextViewDelegate.
- Menu menerima sekumpulan
suggestedActionsdan menambahkan opsi melalui objekUIMenu. - Daftar warna highlight yang terakhir dipakai diambil (sebanyak batas maksimal
maxRecentColors) lalu diwujudkan sebagai daftar opsiUIAction. - Menu
UIActionjuga disuntikkan untuk melakukan Share with Reference menggunakan antarmukaUIActivityViewControllerdengan mengambilsourceTextyang telah dipetakan kembali dari komponen layar ke rentang asli basis data.
Bedah Struct, Class, dan Enum
Berikut adalah struktur kode inti untuk manipulasi ViewModel, Status Pembacaan, dan Pemrosesan Teks Arab.
1. Annotation (Struct) - Model Anotasi
Menyimpan data penuh anotasi beserta konteksnya untuk diterapkan ke NSAttributedString.
struct Annotation: Sendable {
var id: Int64? // (1)!
let bkId: Int // (2)!
let contentId: Int // (3)!
var range: NSRange // (4)!
let rangeDiacritics: NSRange // (5)!
var colorHex: String // (6)!
var type: AnnotationMode // (7)!
var note: String? // (8)!
let createdAt: Int64
let context: String
let page: Int
let part: Int
var pageArb: String?
var partArb: String?
var tags: [String] = []
// CloudKit Sync Support
var ckRecordId: String?
var lastModified: Int64?
}
- Nilai
nilmenandakan bahwa objek ini baru dan belum pernah disimpan ke database. - Menyimpan ID Buku.
- ID halaman atau baris dari tabel konten (
BookContent). - Rentang NSRange berdasarkan teks asli tanpa harakat (Gundul).
- Rentang NSRange berdasarkan teks dengan harakat utuh.
- Direpresentasikan dalam format HEX, misalnya
#FFCC00. - Jenis anotasi, highlight atau underline.
- Teks catatan khusus tambahan dari pengguna (opsional).
2. AnnotationMode (Enum) - Status Mode Anotasi
Mengindikasikan model penerapan grafis untuk anotasi (Highlight / Underline).
enum AnnotationMode: Int, Sendable {
case highlight
case underline
static func from(int: Int) -> AnnotationMode {
switch int {
case 0: highlight
case 1: underline
default: highlight
}
}
}
3. ArabicRenderResult (Struct) - Pengolahan Data Layar
Struct yang dikembalikan oleh perender (ArabicTextRenderer) kepada TextView. Melalui tipe ini, TextView dapat membedakan teks sumber di basis data dan teks grafis yang sudah dibersihkan.
struct ArabicRenderResult {
let sourceText: String // (1)!
let attributedString: NSAttributedString // (2)!
let replacementEvents: [HonorificReplacementEvent] // (3)!
let footnoteRanges: [NSRange] // (4)!
func remapDisplayedRange(_ range: NSRange) -> NSRange { /* ... */ }
func remapSourceRange(_ range: NSRange) -> NSRange { /* ... */ }
}
- Teks sumber murni (string asli sebelum format teks disesuaikan).
- Objek grafis teks terformat (sudah dibersihkan, diwarnai, dan ligatur ditangani).
- Daftar events penggantian (contoh: teks "رحمه الله" yang disederhanakan menjadi satu glif ligatur font Arab tunggal, mengurangi panjang string layar).
- Pemetaan lokasi catatan kaki jika dokumen memilikinya, untuk format ukuran font yang lebih kecil.
4. ViewModelState (Enum)
Didefinisikan dalam modul Protocols sebagai standar pengukur aktivitas pemuatan pada seluruh ViewModel.
public enum ViewModelState: Equatable, Sendable {
case idle
case loading
case loaded
case error(String)
}
stateDiagram-v2
[*] --> idle: Inisialisasi
idle --> loading: Request Load Halaman
loading --> loaded: Sukses Merender Teks
loading --> error: Gagal Membaca DB / Cache
error --> loading: Retry Muat Ulang
loaded --> loading: Navigasi Halaman Baru
5. TextViewState (Class) - Status TextView Global
Manajer pusat dari preferensi tipografi pembacaan (Line Height, Font Size, Mode Gelap, Harakat Aktif) yang menyinkronkan status UserDefaults dengan Observer (@Observable).
@Observable
class TextViewState: @unchecked Sendable {
static let shared = TextViewState()
private(set) var showHarakat: Bool { ... }
private(set) var lineHeight: Double { ... }
private(set) var fontSize: CGFloat { ... }
private(set) var fontName: String { ... }
private(set) var backgroundColorIndex: Int { ... }
private(set) var clickableAnnotation: Bool { ... }
var backgroundColor: BackgroundColor { BackgroundColor(rawValue: backgroundColorIndex) ?? .white }
var isDarkMode: Bool { backgroundColor.isDark }
var currentFont: PlatformFont { ... }
var paragraphStyle: NSParagraphStyle { ... }
var defaultAttributes: [NSAttributedString.Key: Any] { ... }
func toggleHarakat() { ... }
func setLineHeight(_ newHeight: Double) { ... }
func setBackgroundColorIndex(_ index: Int) { ... }
func setBackgroundColor(_ color: BackgroundColor) { ... }
func pushRecentHighlightColor(_ color: PlatformColor) { ... }
}
6. ReaderViewModel (Class) - Pengelola Data Pembacaan
Penghubung (Mediator) utama dalam lapisan UI Maktabah yang menghubungkan basis data dokumen buku yang sedang dibuka dengan antarmuka pembacaan.
@Observable
class ReaderViewModel: ViewModelBase {
var currentBook: BooksData?
var currentPage: Int?
var currentPart: Int?
var currentContentId: Int = 0
var recordHistory: Bool = true
var contentText: String = ""
var state: ViewModelState = .idle
// Dependensi Eksternal
let bookConnectionMutex = Mutex(BookConnection())
let historyVM: HistoryViewModel = .shared
let annotationStore: AnnotationStore = .shared
// Status Sinkronisasi Eksternal
var currentBookContent: BookContent? { ... }
var diacriticsText: String { ... }
// Fungsi Utama Pembaruan
func updateContentState(with content: BookContent) {
// - Menyimpan posisi teks
// - Merekam riwayat baru (HistoryViewModel)
// - Memuat Anotasi ke memori (AnnotationStore)
// - Mengirimkan notifikasi perubahan antar UI Platform (macOS / iOS)
// - Mereset searchEvent & annotationEvent jika berpindah ke halaman lain
}
}
7. Siklus Hidup Sorotan & Animasi Pencarian (iOS)
Pada iOSIbarotTextView:
1. Pencocokan Halaman Ketat (Strict Content ID): Sorotan teks pencarian (highlightSearchText) hanya diterapkan jika searchEvent.contentId == viewModel.currentContentId. Ini mencegah kebocoran atribut warna kuning ke halaman lain saat berpindah halaman.
2. Penghindaran Animasi Berulang (De-duplication) & Isolasi Tab: Animasi popupText dan auto-scroll divalidasi menggunakan coordinator.lastHandledSearchEventId dan coordinator.lastHandledAnnotationEventId. Pelacakan event dibatasi pada instance Coordinator aktif dengan verifikasi jendela aktif (textView.window != nil), sehingga background tab di iPhone tidak menelan event sebelum view aktif sempat menampilkannya.
3. Resolusi Tata Letak TextKit 2 & Isolasi Paragraf: Sebelum menghitung jalur animasi loncat (bounce animation), batas geometri dipastikan telah terhitung secara penuh melalui NSTextLayoutManager.ensureLayout(for: paragraphRange) dengan isolasi paragraf pembungkus. Langkah ini mengeliminasi masalah lazy layout drift pada TextKit 2 yang mengembalikan batas kosong (.zero) atau koordinat bergeser pada halaman yang baru dimuat, sekaligus menjangkar titik asal (anchor origin) overlay ke batas seleksi lokal.
4. Retensi Event Selama Sesi Halaman & Pembersihan Otomatis: Sorotan teks pencarian dan anotasi dipertahankan selama pengguna berada di halaman yang sama tanpa penghapusan instan (immediate clearing). De-duplikasi animasi berulang diproteksi menggunakan pembanding event ID (lastHandledSearchEventId, lastHandledAnnotationEventId). Pembersihan otomatis (searchEvent = nil, annotationEvent = nil) hanya terjadi saat pembaca berpindah ke content.id yang berbeda melalui updateContentState(with:).
5. Navigasi Judul TOC & Flash Indikator Lintas Platform:
- macOS (IbarotTextView): Implementasi scrollToTOC(title:) memanfaatkan string.findTOCMatchingRange(title:) untuk mencari rentang judul bab. Jendela teks digulir ke rentang tersebut (scrollRangeToVisible), lalu memancarkan efek visual bawaan AppKit melalui showFindIndicator(for: charRange).
- iOS (iOSIbarotTextView): Ketika ReaderHighlightEvent.isTOC bernilai true, rentang judul bab yang ditemukan langsung memicu animasi loncat teks sementara (popupText) tanpa menyimpan objek anotasi permanen ke AnnotationStore.
6. Guard Relayout TextKit 2 & Isolasi Sheet (iOS):
- Pada metode updateUIView, pembaruan properti perataan teks (textAlignment) dan atribut semantik diproteksi dengan guard pengecekan kesamaan nilai saat ini. Langkah ini mencegah pembatalan hierarki tata letak TextKit 2 yang membebani CPU saat lembaran modal (sheet presentation) dimunculkan di atas halaman panjang.
- Tampilan pembaca diekstrak ke dalam komponen terisolasi ReaderTextContentView: View, Equatable guna mengeliminasi evaluasi ulang teks deklaratif SwiftUI akibat mutasi state kontainer induk.
7. Presisi Tata Letak Teks & Sinkronisasi Viewport (macOS):
- Pada IbarotTextView, alur navigasi (scrollAndShowFindIndicator) mengombinasikan textLayoutManager?.ensureLayout(for: range), scrollRangeToVisible(range), pemaksaan tata letak kontainer gulir (enclosingScrollView?.contentView.layoutSubtreeIfNeeded()), dan sinkronisasi instan fragmen viewport via textLayoutManager?.textViewportLayoutController.layoutViewport(). Pendekatan ini mempertahankan lazy layout di sisa dokumen dengan performa konstan $\mathcal{O}(1)$ (~12 ms), sekaligus menjamin indikator sorotan (showFindIndicator) diletakkan dengan koordinat yang presisi tanpa memicu tata letak dokumen penuh (full document layout).
- Pada fungsi IbarotTextView.scrollTo(_:), operasi digulirkan secara asinkron melalui antrean taskQueue.enqueue. Sebelum posisi gulir disetel, sistem mengiterasi fragmen tata letak via textLayoutManager.enumerateTextLayoutFragments dari awal dokumen hingga ketinggian target targetY = scrollPos.y + viewportHeight dengan opsi [.ensuresLayout]. Hal ini memastikan seluruh fragmen teks dihitung secara presisi hingga batas area pandang yang akan ditampilkan sebelum contentView.scroll(to:) dipanggil, mengeliminasi deviasi estimasi tinggi baris TextKit 2 pada font non-default.
- Pengecekan tampilan cetak (printView) dimigrasikan menggunakan NSTextView(usingTextLayoutManager: true) untuk menjamin perenderan konsisten berbasis TextKit 2 tanpa fallback ke mesin lama TextKit 1.