Declarative compositional collection views for iOS and macOS.
You describe a model of sections and items. Mosaic owns the collection view, the
diffable data source, and the diffing. Items are identified by a stable id and
re-rendered in place when their contentHash changes, so a cell is never torn
down just because its content changed. One API surface backs UICollectionView on
iOS and NSCollectionView on macOS, and the model, layout DSL, and item callbacks
compile unchanged on both.
Reach for it when you want collection view behavior that SwiftUI's List and
LazyVGrid don't expose, without giving up a declarative model:
- Compositional layouts. Orthogonal sections, custom groups, pinned boundary
items, decorations, and anything else
NSCollectionLayoutSectioncan express. - An explicit identity and refresh contract. Stable IDs drive the diffing, and a projection of exactly the state a cell renders drives reconfiguration.
- Cell reuse you control. Real cells, prefetching hooks, lifecycle callbacks, and SwiftUI content hosted inside any of them.
- One codebase, two platforms. The same feed, grid, or browser runs on UIKit and AppKit.
A gallery app in Examples/ runs the same source on both platforms:
feed, shelves, list, a layout gallery, decorations, and a screen that renders
MosaicPlatformCapabilities so the platform differences are visible side by side.
open Examples/MosaicExamples.xcodeproj # run MosaicExamples-iOS or -macOSdependencies: [
.package(url: "https://github.com/min/mosaic", from: "0.1.0")
].target(name: "MyApp", dependencies: ["Mosaic"])Start with a value and a cell that renders it:
import Mosaic
struct Article: Hashable, Identifiable {
let id: Int
let title: String
}
final class ArticleCell: MosaicCell {
func render(_ article: Article) { /* ... */ }
}Build a model and apply it. Sections and items support if, for, and arrays:
let model = MosaicModel {
MosaicSection("featured", layout: .carousel(itemHeight: .absolute(180))) {
for article in featured {
MosaicItem.cell(ArticleCell.self, article) { cell, article in
cell.render(article)
}
}
}
if !archive.isEmpty {
MosaicSection("archive", layout: .grid(columns: 2)) {
for article in archive {
MosaicItem.cell(ArticleCell.self, article) { cell, article in
cell.render(article)
}
}
}
}
}
mosaicView.apply(model, animate: true)MosaicView is a plain UIView on iOS and a plain NSView on macOS. Add it to a
view controller and call apply(_:animate:) whenever your data changes.
MosaicViewRepresentable wraps the same view. Its builder receives the current width
so layouts can adapt:
MosaicViewRepresentable { width in
MosaicModel {
MosaicSection("grid", layout: .grid(columns: width > 700 ? 3 : 2)) {
for article in articles {
MosaicItem.cell(article) { article in
Text(article.title) // hosted SwiftUI content
}
}
}
}
}For row types you use often, the macro generates the factory boilerplate. Attach it to
a SwiftUI view with a value property, a MosaicCell subclass with render(value:),
or a plain platform view with render(value:):
@MosaicItem
struct ArticleRow: View {
let value: Article
var body: some View { Text(value.title) }
}
MosaicSection("articles") {
for article in articles {
ArticleRow.mosaicItem(article)
}
}@MosaicListItem is the list-cell variant.
Identity decides how items are diffed. contentHash decides whether a visible cell
needs reconfiguring. Keep the two separate: conform to MosaicRefreshable and project
only the fields the cell actually renders.
struct Article: Hashable, Identifiable, MosaicRefreshable {
let id: Int
let title: String
let fetchedAt: Date // not rendered, so not in the projection
var mosaicRefreshValue: String { title }
}
MosaicItem.cell(ArticleCell.self, article) // identity + refresh derived from the valueUse the explicit refreshOn: overload when refresh state also comes from captured
context such as selection or presentation mode.
| Layout | Shape |
|---|---|
.list(style:) |
Rows. List appearances and swipe actions on iOS, a plain compositional list on macOS |
.grid(columns:itemHeight:) |
Fixed column count, uniform item height |
.adaptiveGrid(minItemWidth:) |
Column count derived from the available width |
.waterfall(columns:estimatedHeight:) |
Equal-width columns with estimated heights. Rows stay aligned rather than staggered |
.carousel(itemHeight:behavior:) |
Horizontally scrolling section with paging behaviors |
.custom(_:) / MosaicLayout.section { ... } |
Anything compositional layout can express |
Layouts refine with contentInsets, interGroupSpacing, orthogonalScrollingBehavior,
sectionHeader/sectionFooter, and decorated(by:). A raw
NSCollectionLayoutSection drops in directly via MosaicLayout(_:).
Factory results are typed, so chained callbacks receive your cell and value types:
MosaicItem.cell(ArticleCell.self, article) { cell, article in
cell.render(article)
}
.willDisplay { cell, article in imageLoader(article) }
.prefetchItemAt { article in imageLoader(article) }
.didSelectItemAt { openDetail() }
.onDelete(title: "Remove") { article in store.delete(article) }Also available: didEndDisplaying, didReconfigure, cancelPrefetchingForItemAt,
shouldSelect/shouldDeselect/didDeselect, highlight callbacks, and full
leading/trailing swipe-action configurations.
A section carries at most one supplementary view per element kind. The layout supplies the boundary item and the section supplies the view:
MosaicSection(
"archive",
layout: .grid(columns: 2).sectionHeader(),
header: .header("Archive") { title in
Text(title).font(.headline)
}
) { /* items */ }Supplementary views host SwiftUI (.header { ... }) or platform views
(.header(HeaderView.self, ...)), and visible ones are reconfigured in place on every
apply. Section backgrounds register through MosaicDecorationRegistration and
layout.decorated(by:).
Platform types are reached through aliases, so a cell written against
UICollectionViewCell on iOS already satisfies MosaicCell:
| Mosaic | iOS | macOS |
|---|---|---|
MosaicCell, MosaicListCell |
UICollectionViewCell, UICollectionViewListCell |
NSCollectionViewItem subclass |
MosaicReusableView |
UICollectionReusableView |
NSView & NSCollectionViewElement |
MosaicPlatformView / Color / Image |
UIView / UIColor / UIImage |
NSView / NSColor / NSImage |
MosaicCollectionView |
UICollectionView |
NSCollectionView (in MosaicView.scrollView) |
MosaicViewRepresentable |
UIViewRepresentable |
NSViewRepresentable |
The whole NSCollectionLayout* family and diffable data sources exist on both
platforms, so layouts, decorations, supplementary views, and prefetching behave
identically.
A few UIKit behaviors have no AppKit counterpart. Rather than splitting the API,
Mosaic accepts them everywhere and leaves them inert on macOS, so shared call sites
need no #if. Query them through MosaicPlatformCapabilities:
- Swipe actions.
NSCollectionViewhas no swipe affordance, soonDelete(_:)and the leading/trailing swipe configurations are stored but never invoked. - List configuration. There is no
UICollectionLayoutListConfiguration, so everyMosaicListStylerenders as a plain compositional list andMosaicListCellis the same type asMosaicCell(no separators or accessories). - Interactive reordering.
NSCollectionViewDiffableDataSourcehas noreorderingHandlers, socanReorderSectionItemandonSectionItemsReorderedare stored but never invoked. contentInsetAdjustmentBehavior.NSScrollViewhas no equivalent, so the value is ignored.- Snapshot reconfiguration. AppKit has no
reconfigureItems, so Mosaic re-runs the item'sconfigureclosure against the visible cell instead. The observable contract is the same: the cell updates in place and is never torn down.
Two smaller notes. AppKit loads an item's view lazily, so the hosted cells force the
load at init to match UIKit's lifecycle. SwiftUI content is hosted through
UIHostingConfiguration on iOS and through NSHostingView on macOS.
swift test # macOS, native
xcodebuild test -scheme Mosaic \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' # any installed simulatorUIKit-only behavior (swipe delivery, list content configuration, accessories) is
covered by tests behind #if canImport(UIKit). Everything else runs on both
platforms. See CONTRIBUTING.md for the repository layout, style
rules, and design ground rules.
MIT. See LICENSE.