Initial implementation of Stagger

Author: ivan-magda

.gitignore

@@ -27,7 +27,7 @@ playground.xcworkspace
 #
 # Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
 # hence it is not needed unless you have added a package configuration file to your project
-# .swiftpm
+.swiftpm
 
 .build/
 
@@ -59,4 +59,4 @@ Carthage/Build/
 fastlane/report.xml
 fastlane/Preview.html
 fastlane/screenshots/**/*.png
-fastlane/test_output
+fastlane/test_output

.swiftlint.yml

@@ -0,0 +1,64 @@
+included:
+  - Sources
+  - Tests
+excluded:
+  - Tests/LinuxMain.swift
+  - .build
+  - Examples
+
+opt_in_rules:
+  - empty_count
+  - empty_string
+  - conditional_returns_on_newline
+  - closure_spacing
+  - contains_over_first_not_nil
+  - discouraged_optional_boolean
+  - explicit_init
+  - fatal_error_message
+  - first_where
+  - force_unwrapping
+  - implicit_return
+  - implicitly_unwrapped_optional
+  - joined_default_parameter
+  - modifier_order
+  - multiline_parameters
+  - operator_usage_whitespace
+  - overridden_super_call
+  - prohibited_super_call
+  - sorted_first_last
+  - trailing_closure
+  - unneeded_parentheses_in_closure_argument
+  - vertical_parameter_alignment_on_call
+  - yoda_condition
+
+disabled_rules:
+  - identifier_name
+  - nesting
+  - function_parameter_count
+
+line_length:
+  warning: 120
+  error: 150
+  ignores_comments: true
+
+file_length:
+  warning: 500
+  error: 1200
+
+type_body_length:
+  warning: 400
+  error: 600
+
+function_body_length:
+  warning: 50
+  error: 100
+
+large_tuple:
+  warning: 3
+  error: 5
+
+cyclomatic_complexity:
+  warning: 10
+  error: 20
+
+reporter: "xcode"

Package.swift

@@ -0,0 +1,25 @@
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+    name: "Stagger",
+    platforms: [
+        .iOS(.v17),
+        .macOS(.v14),
+        .tvOS(.v17)
+    ],
+    products: [
+        .library(
+            name: "Stagger",
+            targets: ["Stagger"]
+        )
+    ],
+    targets: [
+        .target(name: "Stagger"),
+        .testTarget(
+            name: "StaggerTests",
+            dependencies: ["Stagger"]
+        )
+    ]
+)

README.md

@@ -1 +1,168 @@
-# swiftui-stagger-animation
+# Stagger
+
+A SwiftUI library for creating beautiful staggered animations with minimal code.
+
+This project is based on the [objc.io Swift Talk episode "Staggered Animations Revisited"](https://talk.objc.io/episodes/S01E443-staggered-animations-revisited).
+
+[![Swift](https://img.shields.io/badge/Swift-6.0-orange.svg)](https://swift.org)
+[![iOS](https://img.shields.io/badge/iOS-17.0+-blue.svg)](https://developer.apple.com/ios)
+[![macOS](https://img.shields.io/badge/macOS-14.0+-blue.svg)](https://developer.apple.com/macos)
+[![tvOS](https://img.shields.io/badge/tvOS-17.0+-blue.svg)](https://developer.apple.com/tvos)
+[![MIT](https://img.shields.io/badge/license-MIT-black.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🌊 **Simple API**: Add staggered animations with just a single view modifier
+- 🔄 **Customizable**: Control animation timing, order, and transitions
+- 📱 **Accessibility**: Respects reduced motion settings
+- 🧩 **Composable**: Works with any SwiftUI transition
+- 🔍 **Smart sorting**: Order by position, priority, or custom criteria
+
+## Installation
+
+### Swift Package Manager
+
+Add the following to your `Package.swift` file:
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/ivan-magda/swiftui-stagger-animation.git", from: "1.0.0")
+]
+```
+
+Or add it in Xcode:
+1. Go to File → Add Packages...
+2. Paste the repository URL: `https://github.com/ivan-magda/swiftui-stagger-animation.git`
+3. Click "Add Package"
+
+## Usage
+
+### Basic Usage
+
+```swift
+VStack {
+    ForEach(items) { item in
+        ItemView(item: item)
+            .stagger() // Default opacity transition
+    }
+}
+.staggerContainer() // Required to coordinate animations
+```
+
+### Custom Transitions
+
+```swift
+// Single transition
+Text("Hello").stagger(transition: .move(edge: .leading))
+
+// Combined transitions
+Image(systemName: "star")
+    .stagger(transition: .scale.combined(with: .opacity))
+```
+
+### Controlling Animation Order
+
+```swift
+// Setting animation priority (higher values animate first)
+Text("First").stagger(priority: 10)
+Text("Second").stagger(priority: 5)
+Text("Third").stagger(priority: 0)
+
+// Configure stagger container
+VStack {
+    // Your views...
+}
+.staggerContainer(
+    configuration: StaggerConfiguration(
+        baseDelay: 0.1, // Time between each item
+        animationCurve: .spring(response: 0.5),
+        calculationStrategy: .priorityThenPosition(.topToBottom)
+    )
+)
+```
+
+### Animation Strategies
+
+```swift
+// Available calculation strategies
+.priorityThenPosition(.leftToRight) // Default
+.priorityOnly
+.positionOnly(.topToBottom)
+.custom { lhs, rhs in
+    // Your custom sorting logic
+}
+
+// Available directions
+.leftToRight
+.rightToLeft
+.topToBottom
+.bottomToTop
+```
+
+### Animation Curves
+
+```swift
+// Available animation curves
+.default
+.easeIn
+.easeOut
+.easeInOut
+.spring(response: 0.5, dampingFraction: 0.8)
+.custom(Animation.interpolatingSpring(mass: 1, stiffness: 100, damping: 10))
+```
+
+## Example
+
+```swift
+struct ContentView: View {
+    @State private var isVisible = false
+    
+    let colors: [Color] = [.red, .orange, .yellow, .green, .blue, .purple]
+    
+    var body: some View {
+        VStack(spacing: 16) {
+            Text("Stagger Animation Demo")
+                .font(.largeTitle)
+                .stagger(
+                    transition: .move(edge: .top).combined(with: .opacity),
+                    priority: 10
+                )
+            
+            LazyVGrid(columns: [GridItem(.adaptive(minimum: 80))], spacing: 16) {
+                ForEach(colors.indices, id: \.self) { index in
+                    RoundedRectangle(cornerRadius: 12)
+                        .fill(colors[index])
+                        .frame(height: 80)
+                        .stagger(transition: .scale.combined(with: .opacity))
+                }
+            }
+            
+            Button("Reset") {
+                isVisible.toggle()
+            }
+            .padding()
+        }
+        .padding()
+        .staggerContainer(
+            configuration: StaggerConfiguration(
+                baseDelay: 0.08,
+                animationCurve: .spring(response: 0.6)
+            )
+        )
+    }
+}
+```
+
+## Requirements
+
+- iOS 17.0+ / macOS 14.0+ / tvOS 17.0+
+- Swift 6.0+
+- Xcode 15.0+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+Stagger is available under the MIT license. See the LICENSE file for more info.

Sources/Stagger/Preview.swift

@@ -0,0 +1,50 @@
+#if DEBUG
+import SwiftUI
+
+struct MyColor: Identifiable {
+    var id = UUID()
+    var color: Color
+}
+
+let sampleColors = (0..<10).map { ix in
+    MyColor(color: .init(hue: .init(ix) / 20, saturation: 0.8, brightness: 0.8))
+}
+
+@available(iOS 16.0, *)
+struct ContentView: View {
+    @State private var colors = sampleColors
+
+    var body: some View {
+        let rect = RoundedRectangle(cornerRadius: 16)
+        VStack(spacing: 16) {
+            rect.fill(.blue.gradient)
+                .frame(height: 120)
+                .stagger(
+                    transition: .move(edge: .top).combined(with: .opacity),
+                    priority: -1
+                )
+
+            LazyVGrid(columns: [.init(.adaptive(minimum: 80), spacing: 16)], spacing: 16) {
+                ForEach(colors) { color in
+                    rect.fill(color.color.gradient)
+                        .frame(height: 80)
+                        .stagger(transition: .scale.combined(with: .opacity))
+                }
+            }
+
+            Button("Add") {
+                for _ in 0..<5 {
+                    colors.append(.init(color: Color(hue: .random(in: 0...1), saturation: 0.6, brightness: 0.6)))
+                }
+            }
+        }
+        .padding()
+        .staggerContainer()
+    }
+}
+
+@available(iOS 16.0, *)
+#Preview {
+    ContentView()
+}
+#endif

Sources/Stagger/Stagger+View.swift

@@ -0,0 +1,66 @@
+import SwiftUI
+
+extension View {
+    /// Applies a staggered fade-in animation to this view.
+    ///
+    /// Views modified with `stagger()` will animate in sequence when contained
+    /// within a view that has the `staggerContainer()` modifier.
+    ///
+    /// Example:
+    /// ```swift
+    /// Text("Hello, World!")
+    ///     .stagger(priority: 1)
+    /// ```
+    ///
+    /// - Parameter priority: Animation priority (higher values animate first). Default is 0.
+    /// - Returns: A view with staggered animation applied.
+    public func stagger(priority: Double = 0) -> some View {
+        modifier(StaggerViewModifier(transition: .opacity, priority: priority))
+    }
+
+    /// Applies a staggered animation with a custom transition to this view.
+    ///
+    /// This allows for more complex animations like sliding, scaling, or rotating.
+    ///
+    /// Example:
+    /// ```swift
+    /// Text("Hello, World!")
+    ///     .stagger(transition: .move(edge: .bottom).combined(with: .opacity), priority: 1)
+    /// ```
+    ///
+    /// - Parameters:
+    ///   - transition: The SwiftUI transition to apply.
+    ///   - priority: Animation priority (higher values animate first). Default is 0.
+    /// - Returns: A view with staggered animation applied.
+    public func stagger<T: Transition>(transition: T, priority: Double = 0) -> some View {
+        modifier(StaggerViewModifier(transition: transition, priority: priority))
+    }
+
+    /// Enables staggered animations for child views.
+    ///
+    /// Apply this modifier to a container view to enable staggered animations
+    /// for any child views that use the `stagger()` modifier.
+    ///
+    /// Example:
+    /// ```swift
+    /// VStack {
+    ///     Text("Title").stagger(priority: 1)
+    ///     Text("Subtitle").stagger()
+    ///     Button("Action") { }.stagger(priority: -1)
+    /// }
+    /// .staggerContainer(
+    ///     configuration: StaggerConfiguration(
+    ///         baseDelay: 0.2,
+    ///         animationCurve: .spring()
+    ///     )
+    /// )
+    /// ```
+    ///
+    /// - Parameter configuration: Configuration for customizing animation behavior. Default is `.init()`.
+    /// - Returns: A view that coordinates staggered animations for its children.
+    public func staggerContainer(
+        configuration: StaggerConfiguration = .init()
+    ) -> some View {
+        modifier(StaggerContainerViewModifier(configuration: configuration))
+    }
+}