Dokumentasi iOS Core UI (iOSMainView)
Dokumen ini membedah arsitektur dan implementasi antarmuka utama (Core UI) untuk platform iOS pada aplikasi Maktabah yang berpusat pada iOSMainView.
Arsitektur & Interaksi Komponen
Aliran data dan navigasi dimulai dari titik masuk aplikasi (MaktabahApp) menuju iOSMainView, yang kemudian membagi tata letak berdasarkan kelas ukuran layar (Size Class) antara iPhone dan iPad.
A. Hierarki Penentuan Tata Letak (Layout Router)
flowchart TD
App["MaktabahApp (@main)"] --> Main["iOSMainView"]
NavMgr["iOSNavigationManager"]
CloudKit["CloudKitSyncManager"]
Main <-->|"Environment"| NavMgr
Main -->|"Background Sync"| CloudKit
NavMgr ~~~ SizeCheck
Main --> SizeCheck{"horizontalSizeClass?"}
SizeCheck -->|"compact (iPhone)"| iPhone["iPhoneLayout (TabView)"]
SizeCheck -->|"regular (iPad)"| iPad["iPadLayout (NavigationSplitView)"]
iPhone ~~~ Target
iPad ~~~ Target
Target["Target: iOSReaderTabView / Sheet Destinations"]
iPhone --> Target
iPad --> Target
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 App,Main,iPhone,iPad,Target ui;
class NavMgr,CloudKit store;
class SizeCheck event;
B. Taksonomi Tab Navigasi (iOSTab)
mindmap
root((iOSTab))
Viewer
icon["books.vertical.fill"]
desc["Katalog pustaka & buku"]
Search
icon["magnifyingglass"]
desc["Pencarian teks FTS global"]
Author
icon["person.2.fill"]
desc["Daftar pengarang kitab"]
Annotations
icon["note.text"]
desc["Catatan, sorotan, & penanda"]
History
icon["clock.fill"]
desc["Riwayat bacaan & buku favorit"]
C. Siklus Transisi Tata Letak Responsif
stateDiagram-v2
[*] --> DetectSizeClass: Launch iOSMainView
DetectSizeClass --> CompactMode: sizeClass == .compact (iPhone)
DetectSizeClass --> RegularMode: sizeClass == .regular (iPad/Mac Catalyst)
state CompactMode {
[*] --> RenderTabView
RenderTabView --> SwitchTabs
SwitchTabs --> OpenReaderFullscreen
}
state RegularMode {
[*] --> RenderNavigationSplitView
RenderNavigationSplitView --> TwoColumnLayout
TwoColumnLayout --> SidebarNavigation
TwoColumnLayout --> EmbeddedReaderDetail
}
Komponen Inti: iOSMainView
iOSMainView adalah kontainer utama yang merespons perubahan environment dan menentukan tata letak yang sesuai.
iOSMainView (Struct)
Tanggung jawab utama iOSMainView:
- Routing Berbasis Lingkungan: Memeriksa
horizontalSizeClass. Jika bernilai.regular(iPad / Mac Catalyst), sistem merenderiPadLayout. Jika bernilai.compact(iPhone), sistem merenderiPhoneLayout. - Manajemen State Global: Mengelola
@Stateuntuk navigasi (iOSNavigationManager), tab yang dipilih (selectedTab), visibilitas kolom iPad, serta status tampilan sheet (Pengaturan / Donasi). Observer padaiOSNavigationManager(.bookIntegrateddan.libraryFolderChanged) menggunakan referensi[weak self]guna mencegah siklus retensi (retain cycle) memori saat navigasi tab berpindah. - Sentralisasi Lembaran Modal (Modal Sheet Centralization): Memusatkan presentasi modal pada tingkat kontainer tertinggi guna mencegah konflik hierarki tampilan deklaratif SwiftUI:
.sheet(item: $bManager.selectedBookForInfo): MenyajikaniOSBookInfoViewsaat pengguna memicu aksi "Informasi Kitab" dari berbagai layar (katalog perpustakaan, lembar filter pencarian, maupun kartu riwayat/favorit)..sheet(isPresented: $bManager.showingTabsList): MenyajikaniOSReaderTabsPopoverViewuntuk mengelola daftar tab pembaca aktif di iPhone, dipindahkan dari local stateiOSReaderViewkeiOSNavigationManagerterpusat.- Deep Linking: Menangani
.onOpenURLuntuk membuka anotasi tertentu atau riwayat bacaan berdasarkan URL WidgetKit. - Siklus Hidup (Lifecycle): Memantau perubahan
scenePhase. Saat bernilai.active, sistem memicu sinkronisasiCloudKitSyncManagerdan mencatat aktivasi aplikasi padaDonationManager.
Lifecycle
iOSMainView bereaksi pada fase scene .active untuk menyerap perubahan sinkronisasi CloudKit dan memperbarui status donasi secara otomatis.
iOSTab (Enum)
Enum iOSTab mendefinisikan menu navigasi utama dengan 5 pilihan:
viewer(Perpustakaan)search(Pencarian)author(Perawi / Narrators)annotations(Anotasi)history(Riwayat & Favorit)
Setiap case memiliki properti pendukung:
id: Nilai integer unik berbasisrawValue.title: Teks judul terlokalisasi.icon: Nama ikon SF Symbols.appMode: Pemetaan ke tipeAppModeglobal.
Navigasi dan Tata Letak
Pendekatan antarmuka Maktabah bersifat adaptif dengan memisahkan alur navigasi antara iPhone dan iPad:
iPhoneLayout (Struct)
Pada iPhone, aplikasi menggunakan bilah tab (TabView) di bagian bawah layar. iPhoneLayout membungkus setiap menu tab dengan NavigationStack tersendiri sehingga navigasi subhalaman di satu tab tidak memengaruhi tab lainnya.
Fitur utama:
- Penyimpanan State Tab: Menggunakan
@AppStorage("lastSelectedTab")agar aplikasi mempertahankan tab terakhir yang aktif saat dibuka kembali. - Pemilihan Tab (Tab Selection): Saat pengguna berpindah tab, blok
.onChangemenginstruksikaniOSNavigationManageruntuk mengganti mode viaswitchToMode(newValue.appMode). - Pencarian Terintegrasi: Setiap
NavigationStackmengimplementasikan modifier.searchable(...)yang terikat (binding) ke teks pencarian pada ViewModel masing-masing.
Struktur Tab:
- Library (Viewer): Memanggil
iOSLibraryView(). - Search: Memanggil
SearchModeView(). - Author: Memanggil
AuthorModeView(). - Annotations: Memanggil
AnnotationListView()dengan dukungan.searchScopes. - History: Memanggil
iOSHistoryView()dan menyertakan tombolHomeToolbarItemsuntuk menambah favorit.
iPadLayout (Struct)
Pada iPad, aplikasi menggunakan NavigationSplitView (tata letak 2–3 kolom) untuk memaksimalkan area layar lebar. Navigasi ditempatkan pada sidebar (kolom kiri) dan pembaca buku (Reader) pada kolom detail (kanan).
Fitur utama:
- Sidebar (Master): Menampilkan menu navigasi dalam format
ListdenganThemeList. - Integrasi Riwayat & Favorit: Pada iPad, bagian Riwayat dan Favorit langsung dimuat di dalam sidebar (menggunakan
HistorySectiondanFavoritesSection). - Filter Sidebar Lokal: Sidebar memiliki kolom pencarian khusus (
sidebarSearchText) untuk menyaring daftar buku favorit dan riwayat secara langsung (filterSidebarBooks). - Tujuan Navigasi (Destination): Memilih item sidebar akan memicu
.navigationDestinationuntuk memperbarui area konten dengan tampilan yang sesuai (libraryDestination,searchDestination, dll.). - Reader Persisten: Kolom detail kanan menampilkan
iOSReaderTabView()secara persisten sehingga perpindahan menu pada sidebar tidak menutup buku yang sedang dibaca.
Saat buku dibuka dari Riwayat atau Favorit, iPadLayout memanggil bManager.openBook(...) dengan ID konten terakhir.
Komponen UI Tambahan
Beberapa ekstensi dan struktur pembantu digunakan untuk menyeragamkan presentasi antarmuka:
-
Modifier
adaptiveReaderPush: Ekstensi padaViewyang mendeklarasikan.navigationDestination(item: ...)untuk membuka layar pembaca (iOSReaderView). Modifier ini secara cerdas mencari tab yang sudah terbuka diiOSNavigationManagerguna mempertahankan status ViewModel dan riwayat bacaan. -
Modifier
toolbarGeneral: Menambahkan tombol ikon pengaturan (gear) pada sisi leading toolbar di semua halaman tab. -
CustomToolbarSpacer: Komponen pembantuToolbarContentyang membungkusToolbarSpacerbawaan untuk memberikan spasi toolbar pada.topBarLeading. -
HomeToolbarItems: Kumpulan kontrol toolbar padaiPhoneLayout.swiftyang memuat tombol Pengaturan (kiri) dan tombol Tambah Favorit (kanan).