KLLazyGallery provides the state and loading contracts needed by a lazy media gallery. It keeps selection tied to stable IDs, requests media according to presentation lifetime, and exposes a near-end paging policy. It is intended for galleries where opening a detail view should not cause every thumbnail to be discarded and requested again.
On iOS, KLLazyGallery uses JXPhotoBrowser as its low-level paging and zooming engine. JXPhotoBrowser is an independent project by LiangJiongXing and is not authored by KLLazyGallery's maintainer. KLLazyGallery adds a host-owned data/loading contract, stable-ID snapshot reconciliation, request lifecycle and cancellation, near-end paging, windowed thumbnail navigation, media-specific presentation, and SwiftUI state coordination. It does not claim ownership of JXPhotoBrowser or repackage JXPhotoBrowser as original work.
The package keeps selection tied to host-provided IDs. The host retains ownership of media storage, persistent caching, paging cursors, retries, and application models.
KLLazyGalleryItem describes one media item with an ID, media kind, optional thumbnail data, and an accessibility label. KLLazyGallerySnapshot holds the ordered items and a hasMore flag.
KLLazyGalleryMediaLoading is the host loader contract. The host receives KLLazyGalleryImageRequest, including an image intent and maximum pixel size, and returns the image through its own storage and network policy.
KLLazyGalleryPagingPolicy.shouldRequestNextPage makes the near-end decision from the current index, item count, and hasMore state. KLLazyGalleryConfiguration sets prefetch distance, maximum zoom scale, maximum image pixel size, double-tap scale, and the thumbnail window radius.
KLLazyGallery is the SwiftUI bridge. It owns a UIKit presentation controller for the gallery lifetime and updates that controller from the current snapshot rather than rebuilding it for every state change. KLLazyGalleryTransitionSource can carry the source frame and thumbnail used for a controlled presentation transition.
struct GalleryHost: View {
@State private var selection: String?
var body: some View {
KLLazyGallery(
snapshot: snapshot,
selection: $selection,
loader: loader,
configuration: .standard
)
}
}The exact loader implementation remains application-specific. It should cancel work when the request is no longer needed and return a result keyed by the item ID.
dependencies: [
.package(
url: "https://github.com/KoenLee1023/KLLazyGallery.git",
from: "0.1.0"
)
]KLLazyGallery does not provide a network client, disk cache, image decoder, pagination service, or database. It also does not infer whether a media item has changed. Give each snapshot item a stable ID and update that ID or snapshot when the host has a real content change.
- iOS 17 or later
- macOS 14 or later for package-level model use
- Swift 6.0 or later
- MIT License
JXPhotoBrowser is distributed under its own MIT license. See Third-Party Notices for attribution.
API Documentation: DocC