Drop Shelf Utility
Relevant source files
The following files were used as context for generating this wiki page:
- buddi/components/Shelf/Views/ShelfView.swift
- buddi/components/Shelf/Services/ShelfDropService.swift
- buddi/components/Shelf/Services/ShelfPersistenceService.swift
- buddi/components/Shelf/ViewModels/ShelfStateViewModel.swift
- buddi/components/Shelf/ViewModels/ShelfItemViewModel.swift
- buddi/components/Shelf/Views/ShelfItemView.swift
The Drop Shelf Utility is a file and content staging system built into the Buddi macOS notch interface. It serves as a temporary or persistent "staging area" where users can drag and drop files, URLs, or plain text to be stored for quick access or later use within the application's workflow. The utility integrates with the macOS file system using security-scoped bookmarks to ensure persistent access to files even after application restarts.
The utility is composed of a specialized view layer for rendering staged items, a view model for managing global shelf state, and background services for handling drag-and-drop ingestion, persistence, and complex file operations such as image conversion or PDF creation.
Sources: README.md:38, buddi/components/Shelf/Views/ShelfView.swift:14-25
Architecture and Data Flow
The Drop Shelf Utility follows an MVVM (Model-View-ViewModel) pattern, centered around a singleton state manager that coordinates between the UI and persistent storage.
Core Components
| Component | Responsibility |
|---|---|
ShelfView | The primary UI container for the shelf, handling the drop target area and horizontal scrolling of items. |
ShelfStateViewModel | A global @MainActor singleton that maintains the list of ShelfItem objects and coordinates saving/loading. |
ShelfDropService | A service responsible for extracting data from NSItemProvider during drag-and-drop operations. |
ShelfPersistenceService | Handles the serialization and deserialization of shelf items to a JSON file in Application Support. |
ShelfItemViewModel | Manages the logic for individual items, including context menus, sharing, and file-specific actions. |
Sources: buddi/components/Shelf/ViewModels/ShelfStateViewModel.swift:11-18, buddi/components/Shelf/Services/ShelfDropService.swift:10-20, buddi/components/Shelf/Services/ShelfPersistenceService.swift:13-25
Data Ingestion Flow
When a user drops content onto the shelf, the system processes the NSItemProvider array to identify the type of content (File, Link, or Text) and wraps it in a ShelfItem.
The ShelfDropService specifically attempts to create bookmarks for file URLs to maintain access across sessions. If raw data is dropped (without a file URL), it uses the TemporaryFileStorageService to create a local file before staging.
Sources: buddi/components/Shelf/Services/ShelfDropService.swift:23-55, buddi/components/Shelf/ViewModels/ShelfStateViewModel.swift:70-79
Item Management and Persistence
The utility ensures that staged items remain available between application launches through a JSON-based persistence layer.
Persistence Logic
The ShelfPersistenceService stores items in ~/Library/Application Support/buddi/Shelf/items.json. It uses JSONEncoder with ISO8601 date strategies and pretty-printed output for the backing file.
- Loading: On initialization, the
ShelfStateViewModelcallsload(). If the JSON is corrupted, the service attempts to recover valid individual items by parsing the data as a JSON array. - Saving: Any modification to the
itemsarray in the view model triggers a save operation via adidSetobserver.
Sources: buddi/components/Shelf/Services/ShelfPersistenceService.swift:18-35, buddi/components/Shelf/ViewModels/ShelfStateViewModel.swift:14-16
Security-Scoped Bookmarks
For file-based items, the utility uses macOS security-scoped bookmarks. The ShelfStateViewModel provides methods to resolve these bookmarks into usable URL objects.
resolveFileURL(for:): Resolves a bookmark and refreshes it if the data has become stale.cleanupInvalidItems(): Iterates through stored items and validates their bookmarks, removing files that are no longer accessible or have been deleted from the disk.
Sources: buddi/components/Shelf/ViewModels/ShelfStateViewModel.swift:81-99, buddi/components/Shelf/ViewModels/ShelfStateViewModel.swift:117-126
User Interface and Interaction
The shelf is rendered as a horizontal scrollable panel within the Buddi notch.
Drag and Drop Detection
The ShelfView uses a specialized RoundedRectangle with a dashed stroke to indicate it is a drop target.
- Targeting: When a drag enters the area,
vm.dragDetectorTargetingis set to true, changing the border color to the system accent color. - Ingestion: The view accepts
.fileURL,.url,.utf8PlainText,.plainText, and.data.
Sources: buddi/components/Shelf/Views/ShelfView.swift:27-31, buddi/components/Shelf/Views/ShelfView.swift:57-73
Item Actions and Context Menus
Individual items are managed by ShelfItemViewModel, which provides a robust context menu for macOS integration.
| Action | Description |
|---|---|
| Open With | Dynamically identifies compatible applications for the file type or URL scheme and allows the user to choose or browse for others. |
| Quick Look | Integrates with QuickLookService to provide native macOS file previews for files and links. |
| Image Actions | Specialized actions for image files, including "Remove Background", "Convert Image", and "Create PDF". |
| Compression | Allows users to create a ZIP archive of selected files, which is then added back to the shelf as a temporary item. |
| Sharing | Uses NSSharingServicePicker to send items to other macOS applications or services. |
Sources: buddi/components/Shelf/ViewModels/ShelfItemViewModel.swift:150-180, buddi/components/Shelf/ViewModels/ShelfItemViewModel.swift:195-250, buddi/components/Shelf/ViewModels/ShelfItemViewModel.swift:458-479
Selection Model
The ShelfSelectionModel (singleton) tracks multi-selection within the shelf.
- Selection: Supports single-click selection, command-click for toggling, and shift-click for range selection.
- Drags: When multiple items are selected, dragging any one item results in a multi-item drag session via
NSItemProvider.
Sources: buddi/components/Shelf/ViewModels/ShelfItemViewModel.swift:85-115, buddi/components/Shelf/Views/ShelfItemView.swift:147-158
Technical Implementation Details
Item Resolution Sequence
This sequence shows how the system handles the resolution of a file from the shelf when requested by an action (like "Open").
Image Processing Integration
The ShelfItemViewModel includes advanced handlers for image-specific operations. When "Convert Image" is selected, a modal NSAlert with an accessory view is presented to configure ImageConversionOptions, such as format (PNG, JPEG, HEIC), compression quality, and max dimensions.
Sources: buddi/components/Shelf/ViewModels/ShelfItemViewModel.swift:513-560
Conclusion
The Drop Shelf Utility provides a bridge between the Buddi application environment and the macOS file system. By leveraging persistence through security bookmarks and offering deep integration with system services like Quick Look and Sharing, it creates a powerful workspace for managing assets used in AI-assisted workflows.