PiscesSpotlight


A cross-platform spotlight tutorial system for Compose Multiplatform.
About
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.
Key Features
- 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
Installation
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.
Quick Example
import io.piscesbn.xcodebn.piscespotlight.spotlight.*
data object LoginButton : SpotlightTarget
@Composable
fun App {
PiscesSpotlightContainer(
tutorials = listOf(
PiscesTutorialConfig(
id = ,
steps = listOf(
SpotlightStep(
LoginButton,
,
)
)
)
),
onTutorialComplete = { id ->
println()
}
) {
Button(
onClick = { },
modifier = Modifier.piscesSpotlightTarget(LoginButton)
) {
Text()
}
}
}
Project Structure
piscespotlight/
├── spotlight/
│ ├── src/
│ │ └── commonMain/
│ │ └── kotlin/
│ │ └── io/piscesbn/xcodebn/piscespotlight/
│ │ ├── PiscesSpotlight.kt
│ │ ├── SpotlightStep.kt
│ │ └── SpotlightTarget.kt
│ ├── build.gradle.kts
│ └── README.md
├── demo/
│ └── src/
│ └── commonMain/
│ └── kotlin/
│ └── io/piscesbn/xcodebn/piscespotlight/
│ ├── App.kt
│ └── DemoTargets.kt
└── build.gradle.kts
Documentation
- Library Documentation: Comprehensive API reference and usage guide in
spotlight/README.md
- Demo Documentation: Demo application guide in
demo/README.md
Platform Support
Building
Prerequisites
- JDK 11 or higher
- Android Studio or IntelliJ IDEA
- Kotlin 2.2.20 or higher
Build Commands
./gradlew build
./gradlew :spotlight:build
./gradlew :demo:build
./gradlew :spotlight:publishToMavenLocal
./gradlew test
Demo Application
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:
./gradlew :demo:installDebug
./gradlew :demo:iosSimulatorArm64Test
See demo/README.md for detailed demo documentation.
Contributing
Contributions are welcome. Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature)
- Commit your changes (
git commit -am 'Add new feature')
- Push to the branch (
git push origin feature/your-feature)
- Create a Pull Request
Development Guidelines
- Follow Kotlin coding conventions
- Add KDoc comments for public APIs
- Include unit tests for new features
- Update documentation as needed
- Verify cross-platform compatibility
Versioning
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
License
Copyright 2025 Hassan Bazzoun
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
See the LICENSE file for details.
Author
Hassan Bazzoun
Acknowledgments
Support
For bug reports and feature requests, please use the GitHub issue tracker.
For questions and discussions, please use GitHub Discussions.