Antarmuka Anotasi macOS
Pendahuluan: Interaksi Komponen UI
Arsitektur antarmuka anotasi pada platform macOS didesain dengan memisahkan logika presentasi dari manajemen data. AnnotationsVC bertindak sebagai pengontrol utama tampilan, sedangkan AnnotationOutlineDataSource menangani abstraksi data dan manipulasi hierarki untuk NSOutlineView. Komunikasi dengan mesin pembaca (IbarotTextVC) dijembatani oleh protocol AnnotationDelegate.
flowchart TD
VC["AnnotationsVC (Popover / NSPanel)"] --> DS["AnnotationOutlineDataSource"]
DS --> OV["NSOutlineView"]
OV --> CV["AnnotationCellView"]
OV --> TV["TimelineGroupCellView"]
CV ~~~ Del
TV ~~~ Del
DS -->|"didSelect(annotation:)"| Del["AnnotationDelegate"]
Del --> Reader["IbarotTextVC (Reader Engine)"]
Reader ~~~ VM
Store["AnnotationStore"] -->|"Combine Events"| VM["AnnotationViewModel"]
VM -->|"onIncrementalUpdate"| DS
VC -->|"Aksi Pengguna"| ACTION(["Mutasi Anotasi (Hapus/Tag/Edit)"])
ACTION --> Store
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 VC,OV,CV,TV,Reader ui;
class DS,Del,Store store;
class VM vm;
class ACTION event;
Mode Windowing: Popover vs. NSPanel
AnnotationsVC memiliki fleksibilitas mode tampilan untuk mendukung multitasking di macOS:
stateDiagram-v2
[*] --> Popover: Buka dari Toolbar (SharedPopover)
Popover --> FloatingPanel: Pengguna Memilih "Detach to Panel" (openAsPanel)
FloatingPanel --> Popover: Panel Ditutup / Kembalikan ke Toolbar
state Popover {
[*] --> AnchorToToolbar
AnchorToToolbar --> AutoDismissOnOutsideClick
}
state FloatingPanel {
[*] --> SetupNSPanel
SetupNSPanel --> InjectTitlebarAccessory
InjectTitlebarAccessory --> KeepOnTopWhenFloating
}
-
Mode Popover Tersemat: Secara bawaan, tampilan anotasi muncul sebagai popover (
SharedPopover.annotationsPopover) yang melekat pada toolbar jendela utama pembaca. -
Mode Panel Melayang (
openAsPanel): Pengguna dapat melepaskan popover menjadi jendela utilitas mandiri menggunakanNSPanel(utilityWindow,resizable,closable).isFloatingPanel: Bila opsi float aktif, panel selalu berada di atas jendela dokumen (UserDefaults.standard.annotationFloatWindow).hidesOnDeactivate: Mengontrol apakah panel otomatis disembunyikan saat aplikasi Maktabah kehilangan fokus (NSWindow.hidesOnDeactivate).- Injeksi Titlebar Accessory: Saat bertransformasi menjadi panel mandiri (
setupLayoutPanel),titlebarRootStack(yang berisi kolom pencarian dan filter tag) dicabut dari hierarkirootStackViewdan disematkan ke bawah titlebar panel menggunakanNSTitlebarAccessoryViewController(layoutAttribute = .bottom).
Custom TableCellView
Komponen AnnotationCellView adalah turunan dari NSTableCellView yang dirancang untuk merender detail anotasi secara kustom.
-
Tipografi Arab: Menggunakan
BundledArabicTextFieldpada variabelcontext,note, danpagePart. Konfigurasi ini secara otomatis mengimplementasikan perataan teks dari kanan ke kiri (RTL) yang sesuai dengan aturan tipografi Arab. -
Tata Letak: Elemen antarmuka disusun menggunakan
NSStackViewvertikal dengan batasan fleksibel (contentStackLeadingConstraintdancontentStackTrailingConstraint) untuk menyesuaikan ruang margin secara dinamis. -
Elemen Linimasa: Sel memiliki
timelineRaildantimelineDot. Elemen ini dimunculkan saat antarmuka beralih ke mode linimasa melalui fungsisetTimelineInset(_:). -
Pembatas Sisi: Terdapat batas dekoratif (border box) pada sisi kanan dan bawah untuk memisahkan antarkolom dan baris pada mode non-linimasa.
TimelineOutlineViews
Berkas TimelineOutlineViews.swift bertanggung jawab atas elemen visual penunjuk linimasa pada judul grup.
-
TimelineNodeView: Subclass
NSViewkustom yang berfungsi menggambar titik node secara manual menggunakan jalurNSBezierPath. -
TimelineGroupCellView: Digunakan khusus untuk baris grup saat mode linimasa aktif. Sel ini menggabungkan
topTimelineRaildanbottomTimelineRailuntuk menciptakan jalur vertikal yang tersambung antar-sel.
Logika Grouping Modes
NSOutlineView dapat mengelompokkan data berdasarkan Buku, Tag, atau Linimasa. Transisi antarmode dikelola oleh AnnotationOutlineDataSource.
- Konfigurasi Visual:
Metode
applyOutlineViewConfiguration()menyesuaikan tata letak tabel ketika terjadi perpindahan mode:- Mode Linimasa: Properti
floatsGroupRowsdiaktifkan agar header grup melayang saat digulir, parameterindentationPerLeveldisetel ke 0, dan jarak antar-sel dihilangkan. - Mode Standar: Parameter
indentationPerLeveldisetel ke 13 guna memberikan indentasi margin pada struktur hierarki.
- Mode Linimasa: Properti
- Penyusunan Hierarki (Tree Builder):
Data dari pengontrol hierarki direpresentasikan dalam bentuk struktur hierarki oleh
AnnotationTreeBuilder. Relasi parent-child ini dibaca olehNSOutlineViewuntuk merender baris sesuai mode yang aktif.
Kalkulasi Tinggi Baris Dinamis (AnnotationRowHeightCalculator)
Karena kutipan teks Arab, catatan pengguna, serta daftar tag memiliki panjang yang bervariasi, penentuan tinggi baris dilakukan melalui @MainActor enum AnnotationRowHeightCalculator:
- Pengukuran Komponen Teks (
measuredHeight):- Kutipan teks Arab (
context): Dihitung dengan font Arab bawaan dan dibatasi oleh nilai preferensiUserDefaults.standard.ctxMaxNumberOfLines. - Catatan tambahan (
note): Dihitung menggunakan font sistem dan dibatasi olehUserDefaults.standard.annMaxNumberOfLines. - Metadata (
pagePart): Menghitung ruang untuk nomor jilid/halaman dan tag chips.
- Kutipan teks Arab (
- Formula Padding & Spacing:
Menghitung tinggi total secara presisi dengan formula:
$$\text{Total Height} = \lceil 20 + \max(\text{contextHeight}, \text{dateHeight} + 8) + \text{pagePartHeight} + \text{noteHeight} + \text{stackSpacing} \rceil$$
Metode ini dipanggil langsung oleh
outlineView(_:heightOfRowByItem:)padaAnnotationsOutlineDelegatesehingga penghitungan tinggi baris berjalan mulus tanpa jeda saat pengguliran cepat.
Interaksi Pengguna & Navigasi Reader
Saat pengguna berinteraksi dengan daftar baris:
-
Seleksi Anotasi: Ketika baris anotasi dipilih, delegasi
outlineViewSelectionDidChange(_:)mendeteksi perubahan. Jika item yang dipilih adalah leaf node (AnnotationNodeyang memiliki objekAnnotation), delegasi memanggil: -
Penanganan di Mesin Reader: Objek
AnnotationOutlineDataSource.delegatedihubungkan keIbarotTextVColehSplitVC. SaatdidSelect(annotation:)diterima:- Kitab yang sesuai dimuat jika belum aktif.
- Halaman target dibuka melalui
contentId. - Kursor dan posisi gulir diarahkan ke rentang teks anotasi yang bersangkutan (
highlightRange).
Aksi Baris, Menu Konteks & Pengeditan
macOS menyediakan interaksi langsung dari sidebar:
- Trailing Swipe Action (Hapus):
Mengimplementasikan
NSTableViewDelegate.tableView(_:rowActionsForRow:edge:)pada sisi.trailing. Menyediakan aksi geser dengan ikontrash.slash.filluntuk menghapus anotasi terpilih secara instan. - Menu Konteks Baris (
AnnotationMenu): Menyediakan aksi klik kanan: Salin teks (copyMenuItem), Sunting Anotasi (editMenuItem— hanya aktif pada satu baris anotasi terpilih dan menyajikan popoverAnnotationEditorVCyang dijangkarkan secara presisi pada sel viaoutlineView.cellAnchor(forRow:)), Tambah/Hapus Tag, Ubah Tipe (Highlight vs. Underline), serta opsi hapus. - Menu Palet Warna Cepat (
AnnotationColorMenuView): Menampilkan deretan titik warna di dalam menu konteks untuk highlight serta tombol underline terdedikasi. Ikon underline dikonfigurasi menggunakan SF Symbol denganNSImage.SymbolConfiguration(paletteColors:)yang mencerminkan warna terakhir darirecentUnderlineColors(fallback ke.labelColor). - Panel Editor Anotasi (
AnnotationEditorVC): Panel popover untuk mengedit catatan teks lengkap, mengubah tipe (highlight vs. underline), memilih warna dariNSColorWell, serta mengatur tag melaluiNSTokenField. Nilai warna disinkronkan secara otomatis: jika tipe underline aktif, warna disimpan dan dipush keUserDefaults.standard.recentUnderlineColors, sehingga pembuatan underline berikutnya secara konsisten memakai warna tersebut.
Alur Persistensi Warna Anotasi (Highlight & Underline)
flowchart TD
UI_Menu["AnnotationColorMenuView<br>(underlineBtn dengan palette symbol)"] -->|"underlineSelection"| Reader["IbarotTextView"]
UI_Editor["AnnotationEditorVC<br>(NSColorWell & underLine toggle)"] -->|"saveTapped"| Store["AnnotationStore"]
Reader -->|"recentUnderlineColors.first"| Coord["AnnotationCoordinator.saveHighlight"]
Coord --> 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")]
Pencarian & Scope Panel Melayang
- Kolom Pencarian (
DSFSearchField): Terintegrasi dengan debounce diAnnotationViewModel.searchText. Perubahan teks secara asinkron menyaring struktur hierarki anotasi. - Scope Panel Melayang (
scopePanel): Ketika kolom pencarian aktif, sebuahNSPanelmelayang tak berbingkai (level = .popUpMenu) muncul tepat di bawah kolom pencarian. Panel ini memuat kontrol segmen (NSSegmentedControl) yang membatasi cakupan pencarian berdasarkanAnnotationSearchScope: Semua (All), Kitab (Book), Konteks (Context), Catatan (Notes), atau Tag (Tags). Ketika kueri atau cakupan berganti, hierarki disaring secara seketika (real-time) dan item induk diperluas (expanded) agar hasil yang cocok langsung terlihat.
Manajemen Filter Tag & Penggabungan Tag
- Penyusunan Bilah Filter (
createTagFilterBar): Antarmuka filter dirancang menggunakanNSStackViewsecara programatik, mencakup tombol filter, sakelar logika (AND/OR), serta area gulir horizontal (NSScrollView) untuk menampung tag chips. - Penyematan Aksesori (Accessory Injection):
Saat dalam mode panel mandiri,
NSStackViewtersebut dibungkus sebagaiviewutama milikNSTitlebarAccessoryViewController(layoutAttribute = .bottom), melekat di bawah titlebar. - Tag Popover (
AnnotationTagVC): Ditampilkan saat aksi penambahan atau penghapusan tag dipicu dari menu baris atau toolbar. - Penggabungan Tag (
TagMergePopoverVC): Menyediakan dialog popover untuk menggabungkan (merge) dua tag berbeda menjadi satu nama tag di seluruh basis data anotasi.
Penerimaan Event Combine
Aplikasi memanfaatkan observasi Combine untuk merespons pembaruan status secara efisien tanpa memuat ulang antarmuka secara keseluruhan.
Mekanisme Pembaruan Inkremental
Setiap perubahan data memicu pengiriman objek AnnotationTreeDiff melalui metode onIncrementalUpdate. Objek diff ini memberikan pedoman rinci bagi data source perihal baris spesifik yang perlu dimodifikasi.
- Saat Menghapus Anotasi:
- Tindakan hapus memperbarui
AnnotationStore, yang kemudian memicu ViewModel menghasilkan objek diff dengan tipe.deleted. AnnotationOutlineDataSourcemenerima objek diff ini dan mengeksekusi metodehandleDeletedAnnotation().- Fungsi ini mencari posisi indeks baris spesifik dan menghapusnya menggunakan
removeItems(at:inParent:withAnimation:)disertai animasi pergeseranslideUp. - Apabila parent node menjadi kosong akibat penghapusan child node, metode
cleanupEmptyParentNode()membersihkan nama grup tersebut dari layar.
- Tindakan hapus memperbarui
- Saat Membuka Popover Tag:
- Permintaan manipulasi tag memancarkan sinyal
onAddTagsRequestedatauonRemoveTagsRequested. - Lapisan kontrol
AnnotationsVCmerespons dengan menampilkan popover pemilihan tag. - Saat pengguna menyimpan perubahan tag, sistem menyusun objek
TagUpdateDiff. - Metode
handleTagModeUpdate()memproses perubahan di antara blokbeginUpdates()danendUpdates()menggunakan animasislideDown.
- Permintaan manipulasi tag memancarkan sinyal