Antarmuka Pengguna iOS Anotasi
Implementasi antarmuka anotasi di iOS dan iPadOS mengadopsi arsitektur hibrida (hybrid) yang menggabungkan paradigma deklaratif SwiftUI untuk level kontainer dan UIKit modern (UICollectionViewCompositionalLayout & UICollectionViewDiffableDataSource) untuk performa tinggi daftar hierarki teks Arab.
Arsitektur Hibrida & Diagram Alur Data
Alur rendering dan pembagian tanggung jawab antarkomponen diatur sebagai berikut:
flowchart TD
ALV["AnnotationListView (SwiftUI Root)"]
AVW["AnnotationViewControllerWrapper"]
ALV --> AVW
AVW ~~~ VC
VC["iOSAnnotationViewController (UIKit)"]
DS["UICollectionViewDiffableDataSource"]
SS["NSDiffableDataSourceSectionSnapshot"]
CV["UICollectionView"]
AVW -->|"Injeksi VC & Callbacks"| VC
VC --> DS
DS --> SS
DS --> CV
CV ~~~ NM
NM["iOSNavigationManager"]
VM["AnnotationViewModel"]
VM -->|"Data Updates"| AVW
VC -->|"onAnnotationSelected"| AVW
AVW -->|"handleSelection"| NM
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 ALV,AVW,VC,DS,SS,CV ui;
class VM vm;
class NM store;
Routing Interaksi Gestur & Aksi Baris
flowchart TD
GESTURE(["Pengguna Berinteraksi pada Sel Anotasi"]) --> CHECK{"Jenis Aksi?"}
CHECK -->|"Ketuk Baris"| NAV["Buka Kitab pada Halaman Target"]
NAV --> CALL_NAV["iOSNavigationManager.openBook()"]
CHECK -->|"Trailing Swipe (Hapus)"| DEL["Hapus Anotasi dari Basis Data"]
DEL --> DB_MUTATE[("Annotations.sqlite")]
CHECK -->|"Trailing Swipe (Sunting Tag/Warna)"| EDIT["Buka Lembar Editor"]
EDIT --> MODAL["Tampilkan iOSAnnotationEditorSheet"]
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 GESTURE event;
class CHECK,NAV,EDIT,MODAL ui;
class CALL_NAV,DEL store;
class DB_MUTATE db;
Pembagian Tanggung Jawab Komponen
AnnotationListView(SwiftUI Root Container):- Mengatur toolbar atas: Menu pengelompokan (Group By: Book, Tag, Timeline) dan pengurutan (Sort By & Order).
- Mengintegrasikan pencarian bawaan via modifier
.searchabledengan placement.navigationBarDrawer(displayMode: .always)serta pemilih cakupan.searchScopes($viewModel.searchScope)untuk seluruh kasusAnnotationSearchScope(all,book,context,note,tag). - Menangani ekspor dan impor JSON melalui modifier
.fileExporterdan.fileImporter(AnnotationJsonDocument). - Menampilkan dialog konfirmasi penggantian saat impor (overwrite duplicate confirmation dialog).
- Menangkap notifikasi
.annotationMissingBookuntuk memunculkan modal peringatan jika buku belum terunduh di perangkat.
AnnotationViewControllerWrapper(Bridge Layer):- Menghubungkan state dan callback
AnnotationViewModel(onIncrementalUpdate,onTreeUpdate,onTagsChanged) ke metode diiOSAnnotationViewController. - Memiliki
Coordinatoryang menangani delegasi seleksi anotasi dan memicuiOSNavigationManager.openBook(..., options:). - Mengatur integrasi pull-to-refresh menuju
CloudKitSyncManager.shared.fetchChanges().
- Menghubungkan state dan callback
iOSAnnotationViewController(UIKit Presentation Layer):- Mengelola tampilan koleksi hierarki, expandable snapshot per grup, header tag chips, dan pembaruan visual inkremental.
Diffing Snapshot Data
Untuk menyajikan daftar anotasi yang dinamis, aplikasi memanfaatkan UICollectionViewDiffableDataSource yang dikombinasikan dengan NSDiffableDataSourceSectionSnapshot.
-
Pembaruan Skala Penuh (Full Rebuild): Saat pengguna mengganti mode pengelompokan (Grouping Mode) atau memuat data awal, kontroler membuat ulang seluruh snapshot. Daftar section diterapkan langsung ke tingkat root, kemudian
NSDiffableDataSourceSectionSnapshotdibuat untuk setiap grup, memasukkan parent node beserta child nodes anotasinya. -
Pembaruan Inkremental (Incremental Update): Untuk pembaruan seperti penambahan, pengubahan, atau penghapusan tunggal, sistem tidak memuat ulang seluruh data:
- Jika anotasi dihapus, elemen tersebut dicari di seluruh section snapshot, lalu dihapus secara terarah.
- Jika pembaruan menyebabkan sebuah grup menjadi kosong, grup tersebut akan dihapus dari tingkat root secara otomatis.
Pencarian Scope & Pembaruan Snapshot
Pada iOS, pencarian anotasi terhubung secara reaktif antara SwiftUI dan UIKit:
- Integrasi SwiftUI Searchable:
AnnotationListViewmemasang modifier.searchabledan.searchScopesyang terikat (two-way binding) keviewModel.searchTextdanviewModel.searchScope. - Auto-Expand Hasil Pencarian: Ketika teks pencarian aktif,
iOSAnnotationViewControllersecara otomatis membuka seluruh grup (section snapshot) dengan memanggilsnapshot.expand(snapshot.rootItems)sebelum menerapkan data kedataSource. Hal ini menjamin seluruh item anotasi yang cocok langsung terlihat tanpa mengharuskan pengguna membuka grup satu per satu. - Penyaringan Reaktif: Setiap pergantian cakupan (scope) atau kata kunci memicu
AnnotationTreeFiltermelaluiviewModel.applyFilter(), yang kemudian memancarkan pembaruan pohon hierarki melalui closureonTreeUpdate.
Mode Pengelompokan & Filter Tag Chip
Antarmuka mendukung tata letak dinamis yang disesuaikan berdasarkan dua konsep:
-
Mode Pengelompokan (Grouping Mode): Pengguna dapat mengelompokkan anotasi berdasarkan Buku (Book), Label (Tag), atau Linimasa (Timeline). Komponen
AnnotationContentConfigurationmenerima status mode ini untuk menentukan teks sekunder:- Bila diurutkan berdasarkan Tag atau Linimasa, tampilan daftar anotasi menonjolkan judul buku.
- Saat dikelompokkan berdasarkan Buku, tampilan menonjolkan daftar tag yang terkait.
-
Filter Tag Chip: Komponen
iOSTagFilterHeaderViewdisematkan sebagai header koleksi (Collection Header).- Menampilkan deretan chips yang dapat digulir secara horizontal.
- Memiliki mode pergantian logika (AND/OR) yang ditandai dengan perubahan ikon.
- Diperbarui secara asinkron sehingga elemen baru disisipkan pada indeks yang tepat tanpa mengganggu status gulir elemen lainnya.
Penanganan Arah Teks (Force LTR)
Aplikasi Maktabah dirancang untuk mengakomodasi teks Arab sehingga secara alami memakai orientasi Kanan-ke-Kiri (RTL). Namun, pada elemen metadata tertentu, tata letak diarahkan secara eksplisit ke Kiri-ke-Kanan (Force LTR).
-
Manipulasi Semantik Kontainer: Pada
Konfigurasi ini memastikan posisi indikator halaman tetap konsisten di pojok kiri.AnnotationContentView, kontainer bawah yang memuat label nomor halaman diatur secara spesifik: -
Inversi Gulir Matriks: Pada header filter tag di dalam
Inversi ganda ini menukar sumbu horizontal tanpa membalik teks, sehingga arah gulir bekerja harmonis dalam antarmuka RTL.UIScrollView:
Interaksi Seleksi, Navigasi Reader & Kitab Belum Terunduh
Ketika pengguna mengetuk item di UICollectionView:
- Pembedaan Grup vs. Node Anotasi (
didSelectItemAt):- Baris Grup: Memanggil
toggleGroup(_:). Indeks section snapshot dibuka (expand) atau ditutup (collapse), serta statusnya dicatat dalamexpandedGroups. - Item Anotasi: Memancarkan callback
onAnnotationSelected(node).
- Baris Grup: Memanggil
- Navigasi Reader via Coordinator:
AnnotationViewControllerWrapper.Coordinatormenerima anotasi terpilih:- Memeriksa apakah data kitab telah terpasang melalui
LibraryDataManager.shared.getBook([ann.bkId]). - Jika kitab ditemukan, memanggil
navigationManager.openBook(book, options: OpenBookOptions(contentId: Int(ann.contentId), annotationEvent: ReaderAnnotationEvent(annotation: ann)))untuk membuka halaman dan menyorot teks padaiOSReaderView. - Jika kitab belum diunduh, memancarkan notifikasi
Notification.Name.annotationMissingBook.
- Memeriksa apakah data kitab telah terpasang melalui
- Peringatan Kitab Belum Terunduh (Missing Book Alert):
AnnotationListViewdi lapisan SwiftUI mengamati notifikasi tersebut melalui.onReceive(NotificationCenter.default.publisher(for: .annotationMissingBook))dan memunculkan dialog peringatan bahwa kitab terkait perlu diunduh terlebih dahulu.
Aksi Geser Hapus (Trailing Swipe Action)
Daftar mengadopsi kemampuan aksi geser bawaan melalui UICollectionLayoutListConfiguration.trailingSwipeActionsConfigurationProvider:
listConfig.trailingSwipeActionsConfigurationProvider = { [weak self] indexPath in
guard let self, let dataSource,
let item = dataSource.itemIdentifier(for: indexPath),
case let .annotation(node) = item
else { return nil }
let delete = UIContextualAction(style: .destructive, title: "Delete") { [weak self] _, _, _ in
guard let self else { return }
var snap = dataSource.snapshot()
snap.deleteItems([item])
dataSource.apply(snap, animatingDifferences: true)
onAnnotationDeleted?(node)
}
delete.image = UIImage(systemName: "trash")
return UISwipeActionsConfiguration(actions: [delete])
}
- Filter Tipe Item: Aksi geser hanya disematkan pada baris leaf node anotasi (
case let .annotation(node)), sedangkan baris header grup tidak dapat digeser. - Animasi Cepat & Sinkronisasi: Item langsung dihapus dari snapshot lokal secara visual (
snap.deleteItems([item])), kemudian pemicuonAnnotationDeleted?(node)diteruskan keviewModel.deleteAnnotation(id:).
Mekanisme Pengeditan Anotasi di iOS
- Menu Konteks Interaktif & Aksi Geser (Swipe):
Pengguna dapat mengelola anotasi langsung dari daftar baris melalui dua jalur:
- Aksi Geser (Swipe Action): Menggeser sel ke kiri (trailing edge) memunculkan tombol hapus destruktif instan.
- Menu Konteks Tekan-Lama (
UIContextMenuConfiguration): Menekan lama pada sel anotasi diiOSAnnotationViewControlleratau pada daftar anotasi bukuiOSBookAnnotationsViewmemunculkan menu konteks dengan aksi: - "Edit Anotasi" (
pencil): Membuka lembar modaliOSAnnotationEditorSheetuntuk menyunting teks catatan (note), warna sorotan, gaya garis bawah (underline), dan tag. - "Hapus" (
trash, destruktif): Menghapus anotasi dari penyimpananAnnotationStore.
- Pengeditan Langsung di Reader (
iOSAnnotationEditorSheet): Selain dari daftar, pengeditan juga dapat dipicu dari dalam tampilan membaca (iOSReaderView) saat teks beranotasi diketuk. Pemilihan warna beradaptasi secara dinamis dengan status toggle underline: menyajikan palet warna teks (.label/ dynamic text color) dan warna garis bawah terdedikasi saat underline aktif. Penyimpanan otomatis memperbaruirecentUnderlineColorsdiUserDefaults. - Menu Seleksi Teks & Palette SF Symbol:
Aksi underline pada menu seleksi teks (
UIActiondiiOSIbarotTextView) dikonfigurasi menggunakan SF Symbol denganUIImage.SymbolConfiguration(paletteColors:)sesuai warna terakhir darirecentUnderlineColors(fallback ke.label).
Alur Persistensi Warna Anotasi iOS (Highlight & Underline)
flowchart TD
UI_Menu["iOSIbarotTextView<br>(UIMenu Underline Action dengan palette symbol)"] -->|"onAddAnnotation(.underline)"| ReaderVM["ReaderViewModel"]
UI_Sheet["iOSAnnotationEditorSheet<br>(Palet Warna Adaptif & Toggle)"] -->|"saveAnnotation"| ReaderVM
ReaderVM -->|"recentUnderlineColors.first"| Coord["AnnotationCoordinator.saveHighlight"]
Coord --> Store["AnnotationStore"]
ReaderVM -->|"updateAnnotation"| Store
Store --> Push["pushRecentColor()"]
Push -->|"type == .highlight"| TVS_H["TextViewState.pushRecentHighlightColor"]
Push -->|"type == .underline"| TVS_U["TextViewState.pushRecentUnderlineColor"]
TVS_H --> UD_H[("UserDefaults: recentHighlightColors")]
TVS_U --> UD_U[("UserDefaults: recentUnderlineColors")]
Modal Sheet Filter Tag (TagFilterSelectionView)
Saat tombol filter pada iOSTagFilterHeaderView diketuk:
- Fungsi
presentTagFilterSheet()menginisialisasi tampilan SwiftUITagFilterSelectionView. - Tampilan dibungkus ke dalam
UIHostingControllerdan dikonfigurasi menggunakanUISheetPresentationController: - Pengguna dapat mencari tag secara instan, memilih mode relasi logika (AND/OR), serta memilih atau mengosongkan tag secara massal (Select All / Deselect All).
Sinkronisasi CloudKit & Pull-to-Refresh
iOSAnnotationViewControllermenyematkan komponenUIRefreshControlpadacollectionView.- Saat pengguna melakukan gestur tarik-untuk-memperbarui (pull-to-refresh), pemicu
onRefreshRequestedmemanggilCloudKitSyncManager.shared.fetchChanges(). - Animasi penyegaran dihentikan secara otomatis setelah proses penarikan data selesai melalui
endRefreshing().