Narrator iOS Implementation (SwiftUI & UIKit)
Di iOS, fitur Narrator (Rijāl al-Hadīts) beradaptasi dengan lingkungan hibrida: navigasi silsilah perawi yang dalam dieksekusi menggunakan UIKit modern (UICollectionView dengan Diffable Section Snapshot), sementara presentasi profil dan lembar biografi dikelola secara deklaratif di SwiftUI.
Sumber kode: Source/Features/Narrator/iOS/
1. Arsitektur Komponen Visual
Arsitektur antarmuka perawi pada iOS memadukan komponen UIKit hierarkis dengan presentasi profil SwiftUI:
A. Hierarki Komponen Hybrid
flowchart TD
RSB["iOSRowiSidebarView (SwiftUI Wrapper)"]
HVC["iOSRowiHierarchicalCollectionViewController (UIKit)"]
DS["UICollectionViewDiffableDataSource"]
RSB --> HVC
HVC --> DS
DS ~~~ DET
DET["NarratorDetailView (SwiftUI Profile)"]
CHIPS["Relationships Bar (Shuyukh / Talamidz)"]
B_LIST["TarjamahSourcesList (Biographical Books)"]
HVC -->|"onSelectRowi"| DET
DET --> CHIPS
DET --> B_LIST
B_LIST ~~~ NM
NM["iOSNavigationManager"]
RV["iOSReaderView (Reader Engine)"]
ITV["iOSIbarotTextView (UITextView)"]
B_LIST -->|"openTarjamahBook"| NM
NM --> RV
RV --> ITV
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 RSB,HVC,DS,DET,CHIPS,B_LIST,RV,ITV ui;
class NM store;
B. Taksonomi Arsitektur Hybrid
mindmap
root((Penjelajah Perawi iOS))
Daftar Hierarki UIKit
tabaqahNode["Node Induk Tabaqah (folder.fill)"]
narratorNode["Node Anak Perawi (person.fill)"]
loadMoreNode["Node Paginasi Asinkron (.loadMore)"]
sectionSnapshot["NSDiffableDataSourceSectionSnapshot"]
Profil & Biografi SwiftUI
narratorProfile["NarratorDetailView"]
relationshipBar["Bilah Hubungan Guru & Murid"]
sourceBooks["Daftar Kitab Rujukan Biografi"]
Jembatan Pembaca
navigationManager["Injeksi @Environment navigasi"]
readerPresentation["Pembukaan lembar bacaan iOSReaderView"]
2. Alur Interaksi: Dari Aksi Klik Perawi / Tarjamah ke TextView
Alur interaksi mencakup dua fase: ekspansi/paginasi daftar di sidebar, lalu pembukaan kitab tarjamah ke mesin pembaca:
A. Routing Interaksi Klik Sidebar
flowchart TD
CLICK(["Pengguna Mengetuk Baris"]) --> CHK{"Tipe Node Diklik?"}
CHK -->|"Tombol Load More"| MORE_ACT["HVC.didSelectItemAt (.loadMore)"]
MORE_ACT --> REQ_BATCH["NarratorViewModel.loadMoreNarrators()"]
REQ_BATCH --> APPEND_SS["Snapshot Menyelipkan Batch Baru"]
CHK -->|"Baris Nama Perawi"| ROWI_ACT["HVC.didSelectItemAt (Perawi)"]
ROWI_ACT --> SHOW_DET["SwiftUI Membuka NarratorDetailView"]
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 CLICK event;
class CHK,MORE_ACT,APPEND_SS,ROWI_ACT,SHOW_DET ui;
class REQ_BATCH vm;
B. Alur Buka Sumber Tarjamah ke TextView
sequenceDiagram
autonumber
actor User as Pengguna
participant Tarj as TarjamahDetailView
participant Nav as iOSNavigationManager
participant Rdr as iOSReaderView
User->>+Tarj: Ketuk sumber kitab tarjamah
Tarj->>+Nav: openBook(tarjamahBook, initialContentId: page)
Nav->>+Rdr: Tampilkan lembar pembaca (SwiftUI)
deactivate Rdr
deactivate Nav
deactivate Tarj
sequenceDiagram
autonumber
participant Rdr as iOSReaderView
participant VM as ReaderViewModel
participant DB as BookConnection
participant TV as iOSIbarotTextView
Rdr->>+VM: loadContent(contentId: page, narratorName: name)
VM->>+DB: getContent(contentId)
DB-->>-VM: sourceText biografi
VM->>VM: ArabicTextRenderer.render() & hitung sorotan perawi
VM-->>-Rdr: State diperbarui (@Observable contentText)
Rdr->>+TV: updateUIView(attributedText)
TV->>TV: UITextView.attributedText = renderedBiographyText
TV->>TV: Melompat ke paragraf biografi
deactivate TV
3. Bedah Komponen & Logika Antarmuka
1. iOSRowiHierarchicalCollectionViewController (Class)
Class turunan dari BaseHierarchicalListViewController yang bertugas menampilkan struktur hierarki generasi perawi:
- Diffable Section Snapshot: Menggunakan
NSDiffableDataSourceSectionSnapshotuntuk mengelola hubungan bertingkat antara Tabaqah (Induk) dan Perawi (Anak). - Mekanisme "Load More" Paginasi:
- Untuk tabaqah dengan ratusan perawi, daftar tidak memuat seluruh rekaman sekaligus ke memori.
- Sistem menyuntikkan sel interaktif khusus dengan identifikasi
.loadMore(tabaqahId)di posisi akhir section snapshot. - Ketika sel ini diketuk, kontroler meminta batch berikutnya ke
special.sqlite, lalu menyisipkan elemen-elemen baru tepat sebelum tombol "Load More". - Indentation Level Visual: Mengatur
indentationLevelbawaan UIKit untuk menghasilkan indentasi visual yang presisi tanpa peretasan margin (margin hack).
2. iOSRowiSidebarView (Struct)
Komponen pembungkus bertipe UIViewControllerRepresentable:
- Pengikatan Coordinator: Menjembatani delegasi ketukan seleksi perawi di
UICollectionViewmenuju ekosistem SwiftUINarratorDetailView. - Integrasi
.searchable(): Mendeteksi status.isSearchingdan mengirim kueri pencarian teks secara langsung keNarratorViewModeluntuk penyaringan instan (instant filtering).
3. NarratorDetailView (Struct) & Tarjamah Source Navigation
- Menampilkan kartu biografi komprehensif: nama lengkap, nasab, laqab, tahun wafat, serta derajat jarh wa ta'dil.
- Menyediakan daftar kitab tarjamah yang memuat biografi perawi tersebut. Setiap baris kitab memuat nomor juz dan halaman, yang saat diketuk akan langsung memanggil
navigationManager.openBookuntuk membuka halaman primer kitab biografi terkait.