feature/documentation

README.md

@@ -93,9 +93,6 @@ dependencies {
 
 <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
 
-    <!-- For displaying an Activity over other apps/lock screen -->
-<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
-
     <!-- Permissions for scheduling exact alarms -->
 <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
 ```

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/intro.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+**TriggerX** is a modular, developer-friendly alarm execution library for Android. It simplifies
+scheduling exact alarms and showing user-facing UIs at a specific time, even when your App has been
+killed. You don't need to worry about managing foreground-services, wake-locks, lock-screen flags or
+permission management
+
+## ❓Why TriggerX?
+
+If you’ve ever tried to show a UI screen at an exact time on Android, you probably know the pain.
+
+You set up an alarm. You test it a couple of times. It works. You ship it. And then—nothing. The App
+was killed. The phone was in Doze mode or the system silently blocked your foreground service. No
+screen shows up. No user interaction. Just silence.
+
+We’ve been there too. Way too many times.
+
+At [Meticha](https://meticha.com), we were building features that really depended on reliable,
+time-based UI triggers. But we didn’t want to keep fighting the system every time. So we created
+TriggerX, a library that just works. Even if the app is cleared from recent apps. Even if the device
+is locked or idle. It’s built with Kotlin and Jetpack Compose and made for developers who care about
+experience and reliability.
+
+## 📱 What about the Play Store?
+
+That was one of our top concerns too.
+
+TriggerX **only** asks for permissions that are **absolutely necessary**. Things like
+`SCHEDULE_EXACT_ALARM` or `SYSTEM_ALERT_WINDOW` are used carefully, and only when required. We’ve
+designed it in a way that aligns with Android’s background execution limits, and we’ve tested it
+against Play Store guidelines.
+
+So yes, you can use TriggerX in apps you plan to publish on the Play Store. And we’ve included
+helper methods to handle permission flows gracefully, so you’re always in control of what the user
+sees and when.
+
+TriggerX isn’t just a tool. It’s the developer experience we wished existed when we needed to show
+something right when it mattered.

docs/docs/tutorial-basics/1-installation.md

@@ -0,0 +1,47 @@
+---
+title: 🛠 Installation
+description: Installing TriggerX on your project
+sidebar_position: 1
+---
+
+You can install TriggerX using either Gradle dependencies or Version Catalogs, depending on how your
+project is set up.
+
+## Option 1: Gradle (Kotlin DSL)
+
+Add this to your `build.gradle.kts`:
+
+```kotlin
+dependencies {
+    implementation("com.meticha:triggerx:0.0.5")
+}
+```
+
+## Option 2: Version Catalog (`libs.versions.toml`)
+If you're using Version Catalogs:
+1. In your `libs.versions.toml`:
+
+```toml
+[versions]
+triggerx = "0.0.5"
+
+[libraries]
+triggerx = { module = "com.meticha:triggerx", version.ref = "triggerx" }
+```
+
+2. Then, use it in your module’s `build.gradle.kts`:
+```kotlin
+dependencies {
+    implementation(libs.triggerx)
+}
+```
+
+## 🛡️ Required Permissions
+
+```xml
+<!-- Required to avoid getting blocked by battery optimizations -->
+<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+
+<!-- Allows scheduling of exact alarms -->
+<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
+```

docs/docs/tutorial-basics/2-set-custom-alarm-activity.md

@@ -0,0 +1,66 @@
+---
+title: 🎬 Set Your Custom Alarm Activity
+description: Before anything else, tell TriggerX what to show when the alarm fires. 
+sidebar_position: 2
+---
+
+Before anything else, tell TriggerX what to show when the alarm fires. This is done by passing your
+custom `Activity` class, typically one that extends `TriggerXActivity`. This activity becomes the
+entry point for your UI, even when the app is killed or in the background.
+
+Once you extend your class with `TriggerXActivity`, you can override the `AlarmContent` composable
+and put your custom UI over there. Also, since `TriggerxActivity` extends the `ComponentActivity`
+itself, you can also do all sorts of things that you might be doing in other activities. Like playing
+the music in the background while the activity is showing 😉
+
+Here's an example of a custom `AppAlarmActivity`:
+
+```kotlin
+class AppAlarmActivity : TriggerXActivity() {
+
+    @Composable
+    override fun AlarmContent() {
+        Box(
+            modifier = Modifier.fillMaxSize()
+        ) {
+            Column(
+                modifier = Modifier
+                    .fillMaxSize()
+                    .background(
+                        color = Color.White,
+                        shape = RoundedCornerShape(32.dp)
+                    )
+                    .padding(32.dp),
+                verticalArrangement = Arrangement.Center,
+                horizontalAlignment = Alignment.CenterHorizontally
+            ) {
+                Icon(
+                    imageVector = Icons.Default.Notifications,
+                    contentDescription = "Trigger Icon",
+                    tint = Color(0xFF111111),
+                    modifier = Modifier.size(80.dp)
+                )
+
+                Spacer(modifier = Modifier.height(24.dp))
+
+                Text(
+                    text = "TriggerX",
+                    fontSize = 42.sp,
+                    fontWeight = FontWeight.Bold,
+                    color = Color(0xFF111111)
+                )
+
+                Spacer(modifier = Modifier.height(12.dp))
+
+                Text(
+                    text = "Example",
+                    fontSize = 20.sp,
+                    fontWeight = FontWeight.Medium,
+                    color = Color(0xFF333333),
+                    textAlign = TextAlign.Center
+                )
+            }
+        }
+    }
+}
+```

docs/docs/tutorial-basics/3-configure-triggerx-dsl.md

@@ -0,0 +1,48 @@
+---
+title: 🧩 Configuring TriggerX with DSL
+description: "Setting up TriggerX is as simple as declaring what you want—literally. Using a `Kotlin DSL`"
+sidebar_position: 3
+---
+
+Setting up TriggerX is as simple as declaring what you want—literally. Using a `Kotlin DSL`, you can
+customize the alarm behavior, the UI to be shown, notifications, and even pass dynamic data when the
+alarm fires. This setup usually goes inside your Application class and takes just a few lines to get
+things rolling.
+
+In your `Application` class, configure the TriggerX library like this:
+
+```kotlin
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+
+        TriggerX.init(this) {
+
+            /* UI that opens when the alarm fires */
+            activityClass = MyAlarmActivity::class.java
+
+            /* Foreground-service notification */
+            useDefaultNotification(
+                title = "Alarm running",
+                message = "Tap to open",
+                channelName = "Alarm Notifications"
+            )
+        }
+    }
+}
+```
+
+This is the most essential setup you need to get TriggerX working in your app. Let’s break it down:
+
+- `TriggerX.init(this) { ... }` initializes the library inside your Application class. It should be
+  called once at App startup.
+
+- `activityClass = MyAlarmActivity::class.java` tells TriggerX which Activity to launch when the
+  alarm fires. This should be a class that extends `TriggerXActivity`, where you define the UI shown
+  to the user.
+
+- `useDefaultNotification(...)` sets up a default notification. This is required when alarms fire
+  while your app is in the background or killed. The notification helps the system prioritize your
+  alarm and ensures **compliance** with foreground execution policies.
+
+

docs/docs/tutorial-basics/4-permission-handling.mdx

@@ -0,0 +1,51 @@
+---
+title: 🔐 Requesting Permissions
+description: Your app needs a few permissions to show the custom UI
+sidebar_position: 4
+---
+
+Before TriggerX can schedule alarms or show UI over the lock screen, your app needs a few permissions.
+The library provides a helper `rememberAppPermissionState()` that makes permission handling simple and
+Compose-friendly.
+
+Here’s how to request permissions and schedule an alarm:
+
+```kotlin
+@Composable
+fun HomeScreen() {
+    val context = LocalContext.current
+    val permissionState = rememberAppPermissionState()
+
+    Scaffold { paddingValues ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(paddingValues)
+                .padding(16.dp),
+            verticalArrangement = Arrangement.Center,
+            horizontalAlignment = Alignment.CenterHorizontally
+        ) {
+            ElevatedButton(
+                onClick = {
+                    if (permissionState.allRequiredGranted()) {
+                        // do stuff
+                    } else {
+                        permissionState.requestPermission()
+                    }
+                }
+            ) {
+                Text("Schedule Activity")
+            }
+        }
+    }
+}
+```
+
+## 💡 What This Does
+- `rememberAppPermissionState()` tracks the required permissions
+- On button tap:
+    - If all permissions are granted, then we can schedule the alarm
+    - If not, it triggers the permission request flow
+
+
+