Tiamat Destinations
-------------------

> [!IMPORTANT]
> This is experimental api

Tiamat destinations library allow to generate destination list for navController automatically
by applying `InstallIn` annotation on `navDestiantions`

## Setup

```kotlin
// Apply compiler plugin in the plugins section
plugins {
    id("io.github.composegears.tiamat.destinations.compiler") version "$version"
}

```

```kotlin
// Add dependency
sourceSets {
    commonMain.dependencies {
        implementation("io.github.composegears:tiamat-destinations:$version")
    }
}

```

## Usage

Create graph `object` extends from `TiamatGraph`

```kotlin
object Graph : TiamatGraph
```

Annotate `navDestination` with `InstallIn` annotation (multiple installations allowed), here is some valid options:

```kotlin
// Using delegate
@InstallIn(Graph::class)
val Screen1 by navDestination<Args> { }

// Using constructor
@InstallIn(Graph::class)
val Screen2 = NavDestination<Unit>(name = "Screen2", extensions = emptyList()) {}

// using object
@InstallIn(Graph::class)
object Screen3 : NavDestination<Int> {
    override val name: String = "Screen3"
    override val extensions: List<Extension<Int>> = emptyList()

    @Composable
    override fun NavDestinationScope<Int>.Content() {
    }
}

// NOT ALLOWED — produces a compile error
// @InstallIn on a non-object class is rejected by the compiler plugin.
// Use a top-level property instead (see Screen4 below).
class Screen4Class : NavDestination<Int> {
    override val name: String = "Screen4"
    override val extensions: List<Extension<Int>> = emptyList()

    @Composable
    override fun NavDestinationScope<Int>.Content() {
    }
}

// Using global instance property
@InstallIn(Graph::class)
@InstallIn(SomneOtherGraph::class)
val Screen4 = Screen4Class()
```

> [!NOTE]
> Applying duplicate `@InstallIn(SameGraph::class)` annotations on the
> same property or object produces a compile **warning**. The destination
> is registered only once per graph.

Use graph instead of `destinations`

```kotlin
val nc = rememberNavController(...)
Navigation(
    navController = nc,
    graph = Graph
)
```

Multiple graphs usage also allowed

```kotlin
///...
object Graph1 : TiamatGraph
object Graph2 : TiamatGraph

//...
Navigation(
    navController = nc,
    graph = Graph1 + Graph2
)
```

## Graph debug dump

The compiler plugin can write the resolved graph as markdown for review.
Set the Gradle property `tiamat.destinations.dumpDir` to a directory path
(relative to the project root or absolute):

```properties
# gradle.properties
tiamat.destinations.dumpDir=build/tiamat-graph
```

## Emergency case

In case the plugin problems, there is backport solution: override graph `destinations` function manually and disable
compiler plugin

```kotlin
object Graph : TiamatGraph {
    override fun destinations(): Array<NavDestination<*>> = arrayOf(
        Screen1, Screen2, Screen3
    )
}
```

## Plugin & Kotlin versions compatibility

| Plugin Version | Kotlin Version |
|----------------|:--------------:|
| 1.5.2          |     2.2.0      |
| 2.1.0          |     2.3.20     |
| 2.2.0          |     2.3.20     |
| 2.3.0          |     2.3.20     |