balochcodes/fluidislandhud

A fluid, Apple Dynamic Island and floating status HUD banner component for SwiftUI featuring organic spring expansions, animated progress bars, semantic notification presets, and interactive swipe-to-dismiss gestures.

✨ Features

🏝️ Authentic Dynamic Island Physics: Smoothly morphs from a compact pill into an expanded card using Apple-grade spring physics.
🚦 Semantic Notification Presets: Instant convenience methods for .success, .error, .warning, .info, and .loading.
📊 Animated Progress Bar: Real-time percentage indicator and smooth progress track for background sync and downloads.
👆 Interactive Gestures: Tap to expand/collapse and swipe upwards to instantly dismiss.
📳 Tactile Haptic Feedback: Native iOS haptics on banner presentation.
🎨 Deep Customization: Adjust background glass, border tints, typography, corner radii, and spring response via FluidIslandTheme.
⚡ Zero External Dependencies: Built 100% on native SwiftUI primitives.

📦 Installation

In Xcode (Recommended)

Open your project in Xcode and go to File ➔ Add Package Dependencies...
In the search box, paste the repository URL:

``text https://github.com/BalochCodes/FluidIslandHUD.git ``

Select Up to Next Major Version (1.0.0) and click Add Package.

In `Package.swift`

Add FluidIslandHUD to your dependencies:

dependencies: [
    .package(url: "https://github.com/BalochCodes/FluidIslandHUD.git", from: "1.0.0")
]

Import the framework:

import SwiftUI
import FluidIslandHUD

🚀 Usage Examples

1. Simple Setup with One-Liner Toasts

Attach .fluidIsland() to your root view, then trigger notifications from anywhere via FluidIslandManager.shared:

import SwiftUI
import FluidIslandHUD

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .fluidIsland() // Injects HUD overlay onto app root
        }
    }
}

struct ContentView: View {
    var body: some View {
        VStack(spacing: 20) {
            Button("Copy Link") {
                FluidIslandManager.shared.showSuccess(
                    "Copied to Clipboard",
                    subtitle: "Link ready to paste anywhere"
                )
            }

            Button("Simulate Error") {
                FluidIslandManager.shared.showError(
                    "Network Timeout",
                    subtitle: "Please check your internet connection"
                )
            }
        }
    }
}

2. Live Download / Sync Progress HUD

struct FileSyncView: View {
    @State private var downloadProgress: Double = 0.0

    var body: some View {
        Button("Start File Sync") {
            downloadProgress = 0.0
            
            Timer.scheduledTimer(withTimeInterval: 0.2, repeats: true) { timer in
                downloadProgress += 0.1
                
                FluidIslandManager.shared.showProgress(
                    "Syncing Assets...",
                    progress: downloadProgress
                )

                if downloadProgress >= 1.0 {
                    timer.invalidate()
                    FluidIslandManager.shared.showSuccess("Assets Synced!")
                }
            }
        }
    }
}

3. Custom Themed Floating Island

let customTheme = FluidIslandTheme(
    backgroundColor: Color(red: 0.1, green: 0.12, blue: 0.18),
    borderColor: Color.blue.opacity(0.3),
    compactCornerRadius: 28,
    expandedCornerRadius: 36,
    springResponse: 0.38,
    springDamping: 0.68
)

ContentView()
    .fluidIsland(theme: customTheme)

🛠️ API Reference

`FluidIslandManager`

`FluidIslandTheme`

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Created by Shahzain Baloch.

Package Metadata

Repository: balochcodes/fluidislandhud

Default branch: main

README: README.md