Skip to content

Reader Data Models & Structures

Sumber kode: Source/Features/Reader/Models/


1. Model Konten Kitab & Cache

A. BookContent (Struct) - BookContent.swift

Entitas data mentah halaman kitab yang diambil dari tabel arsip b{id}:

struct BookContent: Sendable {
    let id: Int           // ID baris primer tabel b{id}
    let nash: String      // Teks halaman buku (hasil dekompresi LZString)
    let page: Int         // Nomor halaman cetak buku
    let part: Int         // Nomor jilid/juz buku
    var surah: Int?       // Penanda nomor surah (khusus kitab tafsir/Quran)
    var aya: Int?         // Penanda nomor ayat (khusus kitab tafsir/Quran)
}
  • Nilai default page dan part diinisialisasi ke 1 jika tidak didefinisikan secara eksplisit.
  • Properti surah dan aya diisi secara kontekstual untuk mendukung sinkronisasi navigasi mushaf pada kitab-kitab tafsir.

B. ProcessedArabicContent (Class) - ProcessedArabicContent.swift

Objek teks hasil pemrosesan tipografi yang siap dikonsumsi oleh Text View (NSTextView / UITextView):

final class ProcessedArabicContent {
    let sourceText: String
    let displayText: String
    let coloredRanges: [NSRange]
    let footnoteRanges: [NSRange]
    let replacementEvents: [HonorificReplacementEvent]
    let importedHeaderRanges: [NSRange]
    let ligatureRanges: [NSRange]
}
  • sourceText vs displayText: sourceText menyimpan teks Arab asli dari basis data, sedangkan displayText merupakan teks yang telah disesuaikan (misalnya: normalisasi harakat, penggantian simbol honorifik atau ligatur).
  • coloredRanges: Rentang karakter yang memerlukan warna khusus (seperti teks matan hadis, ayat Al-Qur'an, atau tanda baca khusus).
  • footnoteRanges: Rentang penanda catatan kaki (hasyiyah / ta'liq) di bagian bawah halaman.
  • replacementEvents: Riwayat penggantian frasa honorifik Islam (misalnya Shallallahu 'alaihi wa sallam, Radhiyallahu 'anhu) dengan glif font ligatur terpadu.

C. CleanedTextKey (Struct) - CleanedTextKey.swift

Kunci in-memory cache untuk membedakan varian rendering dari halaman yang sama:

struct CleanedTextKey: Hashable {
    let showHarakat: Bool
    let isMultiLanguage: Bool
    let isImported: Bool
}

Dengan menjadikan kombinasi boolean ini sebagai kunci hash, BookPageCache dapat menyimpan dan mengambil teks terformat tanpa perlu menghitung ulang (re-parsing) saat pengguna mengubah preferensi tampilan harakat.


2. Opsi & Payload Perenderan Teks

IbarotTextOptions (Struct)

Struct parameter yang diteruskan ke protocol TextViewRenderable:

struct IbarotTextOptions {
    var content: BookContent? = nil
    var color: PlatformColor? = nil        // NSColor di macOS, UIColor di iOS
    var isMultiLanguage: Bool? = nil
    var isImported: Bool? = nil
    var keepScrollPosition: Bool? = nil
}
  • keepScrollPosition: Menentukan apakah posisi gulir layar (scroll offset) dipertahankan saat teks dimuat ulang (reload), misalnya ketika pengguna mengubah ukuran font atau visibilitas harakat agar posisi baca tidak melompat ke atas.

ContentRenderPayload (Struct)

Paket muatan (render payload) untuk pembaruan teks AppKit/UIKit:

struct ContentRenderPayload: Equatable, Sendable {
    let bookId: Int?
    let text: String
    let content: BookContent?
    let keepScrollPosition: Bool
}
  • Komparasi Komposit: Operator == mengevaluasi bookId, content?.id, keepScrollPosition, dan text. Pengecekan ID buku dan ID baris sebelum teks mencegah terlewatinya pembaruan tampilan ketika berpindah ke halaman yang memiliki teks identik.

3. Daftar Isi / Table of Contents (TOC)

A. TOC (Struct) - TOC.swift

Representasi baris data mentah dari tabel daftar isi t{id} pada berkas arsip SQLite:

struct TOC {
    let bab: String    // Judul bab / sub-bab (kolom 'tit')
    let level: Int     // Kedalaman hierarki judul (kolom 'lvl')
    let sub: Int       // Penanda sub-elemen
    let id: Int        // Merujuk ke b{id}.id baris konten terkait
}

B. TOCNode (Class) - TOCNode.swift

Transformasi hierarkis node daftar isi untuk disajikan ke NSOutlineView atau SwiftUI OutlineGroup:

final class TOCNode: Identifiable, @unchecked Sendable {
    let bab: String
    let level: Int
    let sub: Int
    let id: Int
    var children: [TOCNode] = []
}
  • Imutabilitas Tree: Batas rentang halaman/baris antar-bab dihitung secara terpisah melalui struct TOCRange di BookTOCViewModel sehingga instance TOCNode yang di-cache tidak dimutasi lintas jendela.
  • Konversi Angka Arab: Nilai bab otomatis dinormalisasi angka Latin-nya menjadi angka Arab (convertToArabicDigits()).

4. ReaderState & Model Sesi Tab

ReaderState (Struct)

ReaderState merangkum seluruh status tampilan pembaca aktif, memungkinkan pemulihan posisi sesi (session restoration):

struct ReaderState: Codable, Equatable {
    var currentBook: BooksData?
    var currentPage: Int?
    var currentID: Int?
    var currentPart: Int?
    var currentRowi: Rowi?
    var isSidebarCollapsed: Bool = false

    // Navigasi & Scroll
    var scrollPosition: CGPoint?
    var selectedRange: NSRange?
    var expandedNodeIDs: [Int] = []
    var sidebarScrollPosition: CGPoint?

    // Author & Search Integration
    var authorDisplayMode: AuthorDisplayMode?
    var authorTarjamahResults: [TarjamahResult]?
    var searchResults: [SearchResultItem]?
    var searchQuery: String?
}
  • AuthorDisplayMode:
    • .rowiInfo: Menampilkan biografi perawi hadis (tarjamah rowi).
    • .bookContent: Menampilkan teks kitab karya pengarang tersebut.
  • hasContent: Properti terhitung untuk memvalidasi apakah layar pembaca sedang memuat naskah aktif atau dalam status kosong (placeholder).
  • Evaluasi Kesetaraan Kustom (Equatable):
    • Implementasi kustom static func == turut membandingkan lhs.scrollPosition == rhs.scrollPosition dan lhs.sidebarScrollPosition == rhs.sidebarScrollPosition. Hal ini menjamin bahwa status gulir terkini pembaca dan sidebar diikutsertakan dalam perbandingan snapshot sesi multi-tab untuk mencegah siklus simpan atau restorasi redundan.

TabStateSnapshot (Struct)

Model persistensi sesi multi-tab untuk mengisolasi memori navigasi antar-tab jendela macOS:

public struct TabStateSnapshot: Codable, Equatable {
    public var currentModeRaw: Int
    public var viewerState: ReaderState
    public var searchState: ReaderState
    public var authorState: ReaderState
}
  • Menyimpan state (viewerState, searchState, authorState) per-tab jendela secara terisolasi.

WindowTabsSession (Struct)

Model persistensi sesi tab jendela:

public struct WindowTabsSession: Codable, Equatable {
    public var selectedTabIndex: Int
    public var tabs: [TabStateSnapshot]
}
  • Mengemas seluruh daftar snapshot tab beserta indeks tab aktif (selectedTabIndex) untuk ditulis secara atomik ke tabs_session.json.

5. BackgroundColor (Enum) & BackgroundOptions - Tema Latar Belakang

Model tema visual pembaca yang diseragamkan untuk platform macOS (AppKit) dan iOS (SwiftUI):

A. BackgroundColor (Enum) - BackgroundColor.swift

enum BackgroundColor: Int, CaseIterable, Identifiable {
    case white
    case sepia
    case gray
    case darkSepia
    case black

    var id: Int { rawValue }

    var isDark: Bool { rawValue > 1 }

    /// PlatformColor (NSColor / UIColor) yang otomatis menyesuaikan mode terang/gelap sistem
    var nsColor: PlatformColor { ... }

    /// SwiftUI Color yang otomatis menyesuaikan mode terang/gelap sistem
    var color: Color { ... }
}
  • isDark: Penanda boolean terhitung (rawValue > 1) untuk menentukan apakah tema latar belakang tergolong gelap (gray, darkSepia, black), digunakan oleh komponen navigasi dan teks untuk membalik warna kontras.
  • nsColor & color: Properti terhitung yang mengembalikan warna lintas platform (PlatformColor untuk AppKit/UIKit dan Color untuk SwiftUI) menggunakan palet warna terpusat dari aset aplikasi (Assets.xcassets).

B. BackgroundOptions (Class) - BackgroundOptions.swift

Komponen kontrol kustom (NSControl) untuk rendering pilihan tema warna latar belakang lingkaran pada macOS. Sebelumnya berada pada modul Annotations dan kini dipindahkan ke Source/Features/Reader/Models/BackgroundOptions.swift.


6. Event Pemicu Navigasi & Sorotan (iOS)

ReaderHighlightEvent (Struct)

Event pemicu sorotan kata kunci hasil pencarian berbasis UUID sekali pakai:

struct ReaderHighlightEvent: Equatable {
    let id: UUID
    let query: String
    let contentId: Int?
    let mode: SearchMode?
    let nearDistance: Int
    var isTOC: Bool = false
}
  • Setiap ketukan hasil pencarian menghasilkan UUID baru yang menjamin iOSIbarotTextView merespons ketukan berulang (multi-tap) tanpa memerlukan pembersihan status manual.
  • isTOC: Properti penanda sorotan yang dipicu oleh navigasi daftar isi (TOC). Menampilkan animasi popup teks sementara tanpa menyimpan rekaman highlight permanen ke AnnotationStore.

ReaderAnnotationEvent (Struct)

Event pemicu navigasi dan animasi scroll-to-target pada anotasi:

struct ReaderAnnotationEvent: Equatable {
    let id: UUID
    let annotation: Annotation
}

OpenBookOptions (Struct)

Konfigurasi parameter pembukaan buku yang menyederhanakan interface navigasi antar-modul:

struct OpenBookOptions {
    var contentId: Int?
    var searchEvent: ReaderHighlightEvent?
    var annotationEvent: ReaderAnnotationEvent?
    var recordHistory: Bool = true
}