UI & Platform Integration
Dokumentasi ini merangkum jembatan arsitektur dan pola integrasi antarmuka fitur Annotations pada macOS dan iOS, menghubungkan logika data bersama (Core Engine) dengan presentasi bawaan (native) di masing-masing platform.
Sumber kode:
- macOS:
Source/Features/Annotations/macOS/ - iOS:
Source/Features/Annotations/iOS/ - Shared Components:
Source/Features/Annotations/macOS/TagFilterSelectionView.swift
Arsitektur Integrasi Lintas Platform
Fitur Annotations berbagi logika bisnis, persistensi, dan pemodelan data yang sama (AnnotationViewModel, AnnotationStore, AnnotationCoordinator), namun menggunakan paradigma UI yang dioptimalkan untuk karakteristik masing-masing OS:
A. Hierarki Integrasi Arsitektur Lintas Platform
flowchart TD
CORE["Shared Core (AnnotationViewModel & Store)"]
STORE[("Annotations.sqlite")]
CORE --> STORE
CORE ~~~ MAC
MAC["macOS UI (AnnotationsVC & NSOutlineView)"]
CORE -->|"Combine & Data Source"| MAC
MAC -->|"AnnotationDelegate"| MRDR["macOS Reader (IbarotTextVC)"]
MAC ~~~ IOS
IOS["iOS UI (AnnotationListView & iOSAnnotationVC)"]
CORE -->|"Bindings & Snapshots"| IOS
IOS -->|"iOSNavigationManager"| IRDR["iOS Reader (iOSReaderView)"]
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 MAC,MRDR,IOS,IRDR ui;
class CORE store;
class STORE db;
B. Taksonomi Komponen Bersama (Shared Assets)
mindmap
root((Shared Annotations))
Logika Inti
AnnotationStore["In-memory cache & synchronizer"]
AnnotationViewModel["Publisher data reaktif Combine"]
ArabicRangeCalculator["Kalkulasi offset teks berharakat"]
Komponen UI Bersama
TagFilterSelectionView["Chips filter tag multiplatform (SwiftUI)"]
AnnotationJsonSerializer["Serialisasi ekspor/impor dokumen JSON"]
Sinkronisasi CloudKit
PrivateZone["Custom zone sync pada iCloud"]
ConflictResolution["Penyelesaian konflik timestamp mutasi"]
Jembatan Integrasi Pembaca (Reader Navigation Bridge)
Saat pengguna memilih baris catatan, sistem menavigasi pembaca ke kitab dan halaman target:
macOS: Delegasi AppKit
- Protocol: AnnotationDelegate.
- Alur:
NSOutlineViewmendeteksi pergantian baris $\rightarrow$AnnotationsOutlineDelegate.outlineViewSelectionDidChange$\rightarrow$ memanggildataSource.delegate?.didSelect(annotation:)$\rightarrow$ ditangkap olehIbarotTextVCyang dihubungkan melaluiSplitVC. - Aksi: Reader memuat kitab target jika belum terbuka, membuka halaman via
contentId, dan menggeser viewport teks kehighlightRange.
iOS: SwiftUI Coordinator & Navigation Manager
- Alur: Pengguna mengetuk sel $\rightarrow$
iOSAnnotationViewController.didSelectItemAt$\rightarrow$ memicu closureonAnnotationSelected$\rightarrow$ diterima olehAnnotationViewControllerWrapper.Coordinator.handleSelection(_:). - Pemeriksaan Kitab: Coordinator memeriksa ketersediaan kitab via
LibraryDataManager.shared.getBook([ann.bkId]):- Jika tersedia: Menjalankan
iOSNavigationManager.openBook(book, initialContentId: Int(ann.contentId), targetAnnotation: ann). - Jika belum diunduh: Mengirimkan
Notification.Name.annotationMissingBookuntuk memunculkan modal peringatan di level SwiftUIAnnotationListView.
- Jika tersedia: Menjalankan
Komponen Bersama (Multiplatform Component)
TagFilterSelectionView (Struct)
Meskipun tersimpan di direktori Source/Features/Annotations/macOS/, komponen ini dirancang multiplatform dengan kompilasi kondisional (#if os(macOS) dan #if os(iOS)):
- macOS: Ditampilkan di dalam popover pemilihan tag dengan batasan lebar 220–300 pt.
- iOS: Dipresentasikan sebagai lembar modal adaptif (
UISheetPresentationController) dengan detents.medium()dan.large(). - Fitur: Pencarian nama tag secara instan, pemilihan mode logika AND/OR, penyediaan tag yang tersedia (available tags provider), serta tombol aksi Select All / Deselect All.
Ekspor, Impor & Pertukaran Data
- Pertukaran Data JSON (macOS & iOS):
- Menggunakan
AnnotationJsonSerializeruntuk serialisasi format dokumen JSON mandiri (AnnotationJsonDocument). - Di iOS, antarmuka ekspor/impor terintegrasi pada toolbar
AnnotationListViewvia SwiftUI.fileExporterdan.fileImporterlengkap dengan dialog konfirmasi penanganan duplikat (overwrite atau skip). - Di macOS, proses ekspor dan impor diakses melalui menu berbagi pada toolbar
AnnotationsVC.
- Menggunakan
- Ekspor RTF (Khusus macOS):
- Komponen
AnnotationRTFExportermenyusun anotasi terpilih ke dalam format RTF (Rich Text Format). - Menjaga atribut tipografi teks Arab, nomor jilid/halaman, catatan kaki, serta warna sorotan teks untuk siap disalin ke clipboard atau dicetak.
- Komponen
Integrasi Ekstensi Widget
Modul anotasi menyediakan data untuk target Widget Extension:
- Timeline Provider: Mengakses kutipan dan catatan harian melalui snapshot JSON terkoordinasi pada Shared App Group (
group.com.Drn.maktabah) yang dikompilasi olehWidgetUpdateCoordinator. - PlatformColor: Konversi warna heksadesimal yang platform-agnostic menjamin representasi visual sorotan dan garis bawah seragam di widget Home Screen maupun Lock Screen.
Tabel Perbandingan UX Lintas Platform
| Fitur | macOS (AppKit) | iOS (SwiftUI + UIKit) |
|---|---|---|
| Bentuk Tampilan | Popover tersemat atau Panel melayang (NSPanel) |
Tab / Navigation View hierarkis |
| Mesin Daftar | NSOutlineView (Expandable rows) |
UICollectionView (Hierarchical section snapshot) |
| Kalkulasi Tinggi | AnnotationRowHeightCalculator manual |
Auto-layout via UIContentConfiguration |
| Aksi Geser (Swipe) | Trailing swipe action untuk Hapus (NSTableViewRowAction) |
Trailing swipe action untuk Hapus (trailingSwipeActionsConfigurationProvider) |
| Pengeditan Anotasi | Langsung di sidebar via AnnotationMenu (cellAnchor) & AnnotationEditorVC |
Di dalam Reader view dan langsung dari daftar sidebar/toolbar via menu konteks (iOSAnnotationEditorSheet) |
| Filter Tag | Bilah horizontal di titlebar accessory (NSTitlebarAccessoryViewController) |
Supplementary header view dengan teknik inversi matriks LTR/RTL |