A cross-platform spotlight tutorial system for Compose Multiplatform.

PiscesSpotlight is a Kotlin Multiplatform library that provides an elegant solution for implementing interactive user tutorials in Compose applications. The library enables developers to create step-by-step guides that highlight specific UI components and display contextual information through positioned tooltips.

• Cross-platform support for Android, iOS, and Desktop
• Type-safe target system with compile-time verification
• Smart tooltip positioning with automatic edge detection
• Reactive state management using Compose primitives
• Support for multiple concurrent tutorial configurations
• Clean, flat API structure without nested dependencies

Add PiscesSpotlight to your Compose Multiplatform project:

commonMain.dependencies {
    implementation("io.github.xcodebn:pisces-spotlight:0.1.0")
}

For detailed installation instructions, see the library documentation.

import io.piscesbn.xcodebn.piscespotlight.spotlight.*

// Define targets
data object LoginButton : SpotlightTarget

// Configure tutorial
@Composable
fun App() {
    PiscesSpotlightContainer(
        tutorials = listOf(
            PiscesTutorialConfig(
                id = "onboarding",
                steps = listOf(
                    SpotlightStep(
                        LoginButton,
                        "Login",
                        "Tap here to access your account"
                    )
                )
            )
        ),
        onTutorialComplete = { id ->
            println("Tutorial $id completed")
        }
    ) {
        Button(
            onClick = { },
            modifier = Modifier.piscesSpotlightTarget(LoginButton)
        ) {
            Text("Login")
        }
    }
}

piscespotlight/
├── spotlight/              # Library module
│   ├── src/
│   │   └── commonMain/
│   │       └── kotlin/
│   │           └── io/piscesbn/xcodebn/piscespotlight/
│   │               ├── PiscesSpotlight.kt
│   │               ├── SpotlightStep.kt
│   │               └── SpotlightTarget.kt
│   ├── build.gradle.kts
│   └── README.md          # Comprehensive library documentation
├── demo/                  # Demo application
│   └── src/
│       └── commonMain/
│           └── kotlin/
│               └── io/piscesbn/xcodebn/piscespotlight/
│                   ├── App.kt
│                   └── DemoTargets.kt
└── build.gradle.kts

• Library Documentation: Comprehensive API reference and usage guide in spotlight/README.md
• Demo Documentation: Demo application guide in demo/README.md

• JDK 11 or higher
• Android Studio or IntelliJ IDEA
• Kotlin 2.2.20 or higher

# Build all targets
./gradlew build

# Build library only
./gradlew :spotlight:build

# Build demo application
./gradlew :demo:build

# Publish to Maven Local
./gradlew :spotlight:publishToMavenLocal

# Run tests
./gradlew test

The demo module contains a fully functional demo showcasing the library's capabilities. The demo simulates a PDF summarizer application with a comprehensive 7-step onboarding tutorial demonstrating real-world integration patterns.

To run the demo:

# Android
./gradlew :demo:installDebug

# iOS (macOS only)
./gradlew :demo:iosSimulatorArm64Test

See demo/README.md for detailed demo documentation.

Contributions are welcome. Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/your-feature)
5. Create a Pull Request

• Follow Kotlin coding conventions
• Add KDoc comments for public APIs
• Include unit tests for new features
• Update documentation as needed
• Verify cross-platform compatibility

This project uses Semantic Versioning. Version history:

• 0.1.0 (Current) - Initial release
  • Core spotlight functionality
  • Type-safe and string-based targets
  • Smart tooltip positioning
  • Multiple tutorial support
  • State management improvements

Copyright 2025 Hassan Bazzoun

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

See the LICENSE file for details.

Hassan Bazzoun

• Email: hassan.bazzoundev@gmail.com
• GitHub: @xcodebn

• Built with Kotlin Multiplatform
• Powered by Compose Multiplatform
• Published to Maven Central

For bug reports and feature requests, please use the GitHub issue tracker.

For questions and discussions, please use GitHub Discussions.