PagerKit Skill

Overview

This skill provides expert guidance on PagerKit, a powerful SwiftUI library for creating highly customizable and cross-platform page-based navigation. It covers everything from basic usage and dynamic page generation to advanced customization of page indicators, event handling, and best practices. Use this skill to help developers effectively implement flexible and visually rich paging experiences in their SwiftUI applications across all Apple platforms.

Agent Behavior (Follow These Rules)

1. 1. Clarify Paging Requirements: Always ascertain the user's specific needs regarding page content, indicator style, navigation flow, and platform targets before offering solutions.
2. Prioritize idiomatic SwiftUI: Favor PagerKit's PKPageBuilder and ForEach for declarative page construction, aligning with SwiftUI's design principles.
3. Platform-Specific Advice: When discussing indicator images, progress, or UIPageViewController options, always specify platform availability and correct type (UIImage vs. Image, UIPageControlProgress).
4. Emphasize Modifiers: Direct users to the relevant PKPagesView or PKPage modifiers for customization, using full modifier signatures (e.g., .pkPageNavigationOrientation(_:)).
5. Contextual Code Examples: Provide concise code snippets that illustrate the recommended usage within a PKPagesView or PKPage context.
6. Highlight Cross-Platform: When possible, remind users of PagerKit's cross-platform consistency and how to handle platform-specific differences using #if os(...) directives.

Project Settings

PagerKit's behavior is influenced by the project's deployment targets and Swift version.

• - Deployment Targets: PagerKit supports iOS 14.0+, iPadOS 14.0+, macOS 14.0+, tvOS 14.0+, visionOS 1.0+, and watchOS 10.0+. Some features (e.g., UIPageControlProgress) are only available on specific platforms and OS versions.
• Swift Version: Requires Swift 5.9+.

If these are unknown, ask the developer to confirm them, especially when discussing platform-specific features.

Quick Decision Tree

When a developer needs PagerKit guidance, follow this decision tree:

1. 1. Setting up a new pager?

1. 2. Generating pages dynamically from data?

1. 3. Controlling page flow or structure?

1. 4. Customizing the page indicator (dots)?

1. 5. Handling page change events or state?

1. 6. Customizing individual page behavior?

Triage-First Playbook

• - "My pages are not showing or look incorrect."

• - "The page indicator is not positioned or styled correctly."

• - "I want to change the color of the active dot, but it's not working."

• - "Pages are not transitioning automatically."

• - "My conditional logic (if statements) inside PKPagesView is giving compiler errors."

• - "How can I tell if the user swiped forward or backward?"

Core Patterns Reference

Basic Pager Setup

CODEBLOCK0

Dynamic Pages with ForEach

CODEBLOCK1

Custom Page Indicator Styling

CODEBLOCK2

Handling Page Change Events

CODEBLOCK3

Integration Quick Guide

PagerKit is integrated via Swift Package Manager.

1. 1. Add Package Dependency: In Xcode, go to File > Add Package Dependency and enter https://github.com/SzpakKamil/PagerKit.git.
2. Import: import PagerKit in your Swift files.
3. Deployment Targets: Ensure your project targets iOS 14.0+, iPadOS 14.0+, macOS 14.0+, tvOS 14.0+, visionOS 1.0+, or watchOS 10.0+ (Swift 5.9+).

For detailed setup, see references/PagerKit.md.

Reference Files

Load these files as needed for specific topics:

• - PagerKit.md - General overview, setup, and core benefits.
• PKPagesView.md - Detailed information on the main pager container and its global modifiers.
• PKPage.md - Information on individual page creation and page-specific modifiers.
• ForEach.md - How to generate pages from collections of data.
• PKPageBuilder.md - Understanding the declarative content building for PKPagesView.
• PKPageControlBackgroundStyle.md - Options for the background style of the page indicator.
• PKPageControlDirection.md - Options for the layout direction of the page indicator dots.
• PKPageDirection.md - Understanding the direction of page transitions.
• _index.md - A comprehensive index for all PagerKit reference documentation.

Best Practices Summary

1. 1. Embrace Declarative UI: Use PKPageBuilder with ForEach for flexible and maintainable page construction.
2. Customize Thoughtfully: Leverage the extensive modifier API to match native platform aesthetics and app branding, avoiding over-customization that hinders usability.
3. Manage Pager State: Always bind pkCurrentPageIndex to external state (@State or @Binding) for programmatic control and observation.
4. Implement Event Handling: Utilize callbacks (e.g., .pkOnManualPageChange, .pkOnTransitionEnd) for analytics, haptic feedback, or custom logic in response to navigation.
5. Mind Platform Differences: Be aware of modifiers and features that behave differently or are only available on specific Apple platforms and OS versions.
6. Prioritize Accessibility: Ensure custom indicators and footers remain accessible (e.g., with VoiceOver support).

Note: This skill is based on the comprehensive documentation for PagerKit. For further details, visit the official documentation at documentation.kamilszpak.com/documentation/pagerkit/ or the project website at kamilszpak.com/pl/pagerkit.