KarrotListKit

The CollectionViewAdapter acts as the bridge between UICollectionView logic and the KarrotListKit declarative logic. It encapsulates the core implementation of the framework.

To set it up, you typically need a CollectionViewAdapterConfiguration, a UICollectionView, and a CollectionViewLayoutAdapter (which provides the sectionLayout for a UICollectionViewCompositionalLayout).

private let configuration = CollectionViewAdapterConfiguration()
private let layoutAdapter = CollectionViewLayoutAdapter()

private lazy var collectionViewAdapter = CollectionViewAdapter(
  configuration: configuration,
  collectionView: collectionView,
  layoutAdapter: layoutAdapter
)

private lazy var collectionView = UICollectionView(
  frame: .zero,
  collectionViewLayout: UICollectionViewCompositionalLayout(
    sectionProvider: layoutAdapter.sectionLayout
  )
)

Components can represent their own size via an estimate using layoutMode. For precise sizing, the underlying Content (the view) should override sizeThatFits(_:).

Additionally, SectionLayout can be customized by providing an NSCollectionLayoutSection via the .withSectionLayout modifier on a Section.

struct ButtonComponent: Component {
  typealias Content = Button
  // ...
  var layoutMode: ContentLayoutMode {
    .flexibleHeight(estimatedHeight: 44.0)
  }
}

final class Button: UIControl {
  // ...
  override func sizeThatFits(_ size: CGSize) -> CGSize {
    // return size of a Button
  }
}

// Customizing section layout
Section(id: "Section1") {
  // ...
}
.withSectionLayout { [weak self] context -> NSCollectionLayoutSection? in
  // return NSCollectionLayoutSection object
}

Use the .onReachEnd modifier on a List to trigger actions when the user scrolls near the end of the content.

The offset parameter uses ReachedEndEvent.OffsetFromEnd to define the trigger condition:

• relativeToContainerSize(multiplier: CGFloat): Triggers when the scroll position is within a multiple of the content view's height from the end. (Default is 2.0).
• absolute(CGFloat): Triggers when the scroll position is within an absolute point value from the end.

The handler is a closure that performs the asynchronous action (e.g., fetching more data).

List(sections: [])
  .onReachEnd(
    offset: .absolute(100.0),
    handler: { _ in
      // Closure Trigger when reached end of list.
    }
  )

To install KarrotListKit, use Swift Package Manager in Xcode:

1. Open Xcode and navigate to Project -> Package dependencies -> Add Package Dependency (+).
2. Enter the repository URL: https://github.com/daangn/KarrotListKit.
3. Specify your desired version.
4. Click Next and Finish.

After installation, import the framework in your Swift files:

import KarrotListKit

The CollectionViewAdapter conforms to UICollectionViewDataSourcePrefetching. You can improve performance by providing prefetchingPlugins during CollectionViewAdapter initialization.

To support prefetching, your components should conform to relevant protocols (e.g., ComponentRemoteImagePrefetchable) and expose the necessary data (e.g., remoteImageURLs).

let collectionViewAdapter = CollectionViewAdapter(
  configuration: .init(),
  collectionView: collectionView,
  layoutAdapter: CollectionViewLayoutAdapter(),
  prefetchingPlugins: [
    RemoteImagePrefetchingPlugin(
      remoteImagePrefetcher: RemoteImagePrefetcher()
    )
  ]
)

extension ImagePrefetchableComponent: ComponentRemoteImagePrefetchable {
  var remoteImageURLs: [URL] {
    [
      URL(string: "imageURL"),
      URL(string: "imageURL"),
      URL(string: "imageURL")
    ]
  }
}

The updateStrategy parameter in collectionViewAdapter.apply determines how the collection view transitions to the new state. Use the CollectionViewAdapterUpdateStrategy enum:

• animatedBatchUpdates: (Default) Performs animated batch updates using performBatchUpdates(...). Animates insertions, deletions, and moves.
• nonanimatedBatchUpdates: Performs batch updates without animation using UIView.performWithoutAnimation(...). More performant than reloadData() as it avoids full reconfiguration.
• reloadData: Performs a full reloadData(). Reconfigures all visible cells; generally discouraged for performance reasons.