{"id":19190852,"url":"https://github.com/flocked/advancedcollectiontableview","last_synced_at":"2025-05-08T04:51:13.197Z","repository":{"id":135376553,"uuid":"578651075","full_name":"flocked/AdvancedCollectionTableView","owner":"flocked","description":"Extended NSCollectionView, NSTableView and NSOutlineView: Cell- \u0026 ItemRegistration, SwiftUI table cells/collection view items,…","archived":false,"fork":false,"pushed_at":"2025-03-21T21:29:50.000Z","size":28124,"stargazers_count":41,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T19:41:15.560Z","etag":null,"topics":["appkit","cocoa","macos","nscollectionview","nscollectionviewitem","nsoutlineview","nstablecellview","nstableview","swift","swiftui"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flocked.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-12-15T15:00:11.000Z","updated_at":"2025-04-10T23:44:31.000Z","dependencies_parsed_at":"2023-09-22T00:08:12.319Z","dependency_job_id":"2864e575-6b8e-4fd9-b35f-368eafcdfd75","html_url":"https://github.com/flocked/AdvancedCollectionTableView","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flocked%2FAdvancedCollectionTableView","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flocked%2FAdvancedCollectionTableView/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flocked%2FAdvancedCollectionTableView/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flocked%2FAdvancedCollectionTableView/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flocked","download_url":"https://codeload.github.com/flocked/AdvancedCollectionTableView/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253002841,"owners_count":21838637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appkit","cocoa","macos","nscollectionview","nscollectionviewitem","nsoutlineview","nstablecellview","nstableview","swift","swiftui"],"created_at":"2024-11-09T11:36:13.773Z","updated_at":"2025-05-08T04:51:13.149Z","avatar_url":"https://github.com/flocked.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Advance NSCollectionView and NSTableView\n\nA framework for NSCollectionView, NSTableView and NSOutlineView. It provides a collection of classes and extensions, many of them being ports of missing UIKit APIs.\n\n**Take a look at the included sample app which demonstrates most features.**\n\n**For a full documentation take a look at the** [Online Documentation](https://swiftpackageindex.com/flocked/AdvancedCollectionTableView/documentation/).\n\n## NSCollectionView ItemRegistration \u0026 NSTableView CellRegistration\n\nA registration for collection view items and table cells that greatly simplifies  configurating them. A port of `UICollectionView.CellRegistration`.\n\n```swift\nstruct GalleryItem {\n    let title: String\n    let image: NSImage\n}\n\nlet tableCellRegistration = NSTableView.CellRegistration\u003cNSTableCellView, GalleryItem\u003e { \n    tableCell, column, row, galleryItem in\n    \n    tableCell.textField.stringValue = galleryItem.title\n    tableCell.imageView.image = galleryItem.image\n    \n    // Gets called whenever the state of the item changes (e.g. on selection)\n    tableCell.configurationUpdateHandler = { tableCell, state in\n        // Updates the text color based on selection state.\n        tableCell.textField.textColor = state.isSelected ? .controlAccentColor : .labelColor\n    }\n}\n```\n\n## NSContentConfiguration\n\nConfigurates styling and content for a content view. A port of UIContentConfiguration`.\n\n`NSCollectionviewItem`, `NSTableCellView` and `NSTableRowView` provide `contentConfiguration` where you can apply them to configurate the content of the item/cell.\n\n### NSHostingConfiguration\n\nA content configuration suitable for hosting a hierarchy of SwiftUI views. \n\nWith this configuration you can easily display a SwiftUI view in a collection item and table cell:\n\n```swift\ncollectionViewItem.contentConfiguration = NSHostingConfiguration {\n    HStack {\n        Image(systemName: \"star\").foregroundStyle(.purple)\n        Text(\"Favorites\")\n        Spacer()\n    }\n}\n```\n### NSListContentConfiguration\n\nA content configuration for a table view cell.\n\n![NSListContentConfiguration](https://raw.githubusercontent.com/flocked/AdvancedCollectionTableView/main/Sources/AdvancedCollectionTableView/Documentation/AdvancedCollectionTableView.docc/Resources/NSListContentConfiguration.png)\n\n ```swift\n var content = tableCell.defaultContentConfiguration()\n\n // Configure content\n content.text = \"Text\"\n content.secondaryText = #\"SecondaryText\\\\nImage displays a system image named \"photo\"\"#\n content.image = NSImage(systemSymbolName: \"photo\")\n\n // Customize appearance\n content.textProperties.font = .body\n content.imageProperties.tintColor = .controlAccentColor\n\n tableCell.contentConfiguration = content\n ```\n \n ### NSItemContentconfiguration\n \nA content configuration for a collection view item.\n\n![NSItemContentconfiguration](https://raw.githubusercontent.com/flocked/AdvancedCollectionTableView/main/Sources/AdvancedCollectionTableView/Documentation/AdvancedCollectionTableView.docc/Resources/NSItemContentConfiguration.png)\n\n ```swift\n public var content = collectionViewItem.defaultContentConfiguration()\n\n // Configure content\n content.text = \"Text\"\n content.secondaryText = \"SecondaryText\"\n content.image = NSImage(systemSymbolName: \"Astronaut Cat\")\n\n // Customize appearance\n content.secondaryTextProperties.font = .callout\n\n collectionViewItem.contentConfiguration = content\n ```\n\n## NSCollectionView Reconfigure Items\n\nUpdates the data for the items without reloading and replacing them. It provides much better performance compared to reloading items. A port of `UICollectionView.reconfigureItems`.\n\nAny item that has been registered via  `ItemRegistration`, or by class using `register(_ itemClass: NSCollectionViewItem.Type)`, can be recofigurated.\n\n```swift\ncollectionView.reconfigureItems(at: indexPaths)\n```\n\n ## NSTableView Cell Registration by Class\n\nApple only allows registering `NSTableCellView` using `NSNib`. This framework lets you register table cell class.\n\n```swift\ntableView.register(NSTableCellView.self)\n\nlet dequeuedTableCell = tableView.makeView(for: NSTableCellView.self)\n```\n\n## NSCollectionView- \u0026 NSTableViewDiffableDataSource Item Deletion\n\nEnable deleting items via backspace via `DeletingHandlers`:\n\n```swift\n// Allow every item to be deleted\ndataSource.deletingHandlers.canDelete = { items in return true }\n\n// Update the backing store from the final item identifiers\ndataSource.deletingHandlers.didDelete = { [weak self] items, transaction in\n    guard let self = self else { return }\n         \n    self.backingStore = transaction.finalSnapshot.itemIdentifiers\n}\n```\n \n## NSDiffableDataSourceSnapshot Apply Options\n\n Apple's `apply(_:animatingDifferences:completion:)` provides two options for applying snapshots to a diffable data source depending on `animatingDifferences`:\n - `true` applies a diff of the old and new state and animates updates in the UI.\n - `false`  is equivalent to calling `reloadData()`. It reloads every item.\n \n  `NSDiffableDataSourceSnapshotApplyOption`  lets you perform a diff even without animations for much better performance compared to using Apple's `reloadData()`.\n\nIt also provides additional options:\n- **usingReloadData**: All items get reloaded.\n- **animated(withDuration: CGFloat)**: Changes get applied animated.\n- **nonAnimated**: Changes get applied immediatly.\n\n ```swift\ndiffableDataSource.apply(mySnapshot, .withoutAnimation)\n\ndiffableDataSource.apply(mySnapshot, .animated(3.0))\n ```\n \n## CollectionViewDiffableDataSource\n\nAn extended `NSCollectionViewDiffableDataSource that provides:\n - Reordering items by dragging them via `reorderingHandlers`\n - Deleting items via backspace via `deletingHandlers`\n - Quicklook previews of items via spacebar by providing items conforming to `QuicklookPreviewable`\n - Right click menu provider for selected items\n \n **It includes handlers for:**\n - Prefetching items\n - Selecting items\n - Highlighting items\n - Displaying items\n - Hovering items with the mouse.\n - Pinching of the collection view\n  \n ## TableViewDiffableDataSource\n \n Simliar to CollectionViewDiffableDataSource.\n \n  ## OutlineViewDiffableDataSource\n  \n  A diffable data source for NSOutlineView.\n  \n  Example usage of a data source with a String as `ItemIdentifierType`:\n \n ```swift\n    let dataSource = OutlineViewDiffableDataSource\u003cString\u003e(outlineView: outlineView, cellRegistration: cellRegistration)\n    \n    var snapshot = OutlineViewDiffableDataSourceSnapshot\u003cString\u003e()\n    let rootItems [\"Root 1\", \"Root 2\", \"Root 3\", \"Root 4\", \"Root 5\"]\n    snapshot.append(rootItems)\n    \n    rootItems.forEach { rootItem in\n        let childItems = (1...5).map { \"\\(rootItem).\\($0)\" }\n        snapshot.append(childItems, to: rootItem)\n        \n        childItems.forEach { childItem in\n            let grandchildItems = (1...5).map { \"\\(childItem).\\($0)\" }\n            snapshot.append(grandchildItems, to: childItem)\n        }\n    }\n    dataSource.apply(snapshot)\n ```\n\n## Quicklook for NSTableView \u0026 NSCollectionView\n\nNSCollectionView/NSTableView `isQuicklookPreviewable` enables quicklook of selected items/cells via spacebar.\n\nThere are several ways to provide quicklook previews (see [FZQuicklook](https://github.com/flocked/FZQuicklook) for an extended documentation): \n\n- Diffable collection view \u0026 table view datasource with an `ItemIdentifierType` conforming to `QuicklookPreviewable`:\n\n```swift\nstruct GalleryItem: QuicklookPreviewable {\n    let title: String\n    let imageURL: URL\n    \n    // The file url for the quicklook preview.\n    let previewItemURL: URL? {\n        return imageURL\n    }\n    \n    // The quicklook preview title displayed on the top of the Quicklook panel.\n    let previewItemTitle: String? {\n        return title\n    }\n}\n\nlet itemRegistration = NSCollectionView.ItemRegistration\u003cNSCollectionViewItem, GalleryItem\u003e() { collectionItem, indexPath, galleryItem in \n    // configurate …\n}\n  \ncollectionView.dataSource = NSCollectionViewDiffableDataSource\u003cSection, GalleryItem\u003e(collectionView: collectionView, itemRegistration: ItemRegistration)\n\ncollectionView.isQuicklookPreviewable = true\ncollectionView.quicklookSelectedItems()\n```\n\n- `NSCollectionViewItems`s \u0026 `NSTableCellView`s `quicklookPreview: QuicklookPreviewable?` property:\n\n```swift\ncollectionViewItem.quicklookPreview = URL(fileURLWithPath: \"someFile.png\")\n```\n\n## Installation\n\nAdd `AdvancedCollectionTableView` to your app's `Package.swift` file, or selecting `File -\u003e Add Package Dependencies in Xcode:\n\n```swift\n.package(url: \"https://github.com/flocked/AdvancedCollectionTableView\")\n```\n\nIf you clone the repo, you can run the sample app, which demonstrates most of the API`s.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflocked%2Fadvancedcollectiontableview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflocked%2Fadvancedcollectiontableview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflocked%2Fadvancedcollectiontableview/lists"}