diff --git a/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/GettingStarted.kt b/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/GettingStarted.kt new file mode 100644 index 00000000..a44291f6 --- /dev/null +++ b/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/GettingStarted.kt @@ -0,0 +1,13 @@ +@file:Suppress("unused") + +package dev.sargunv.maplibrecompose.demoapp.docs + +import androidx.compose.runtime.Composable +import dev.sargunv.maplibrecompose.compose.MaplibreMap + +// -8<- [start:app] +@Composable +fun MyApp() { + MaplibreMap() +} +// -8<- [end:simple-app] diff --git a/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/README.md b/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/README.md new file mode 100644 index 00000000..a765d622 --- /dev/null +++ b/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/README.md @@ -0,0 +1,3 @@ +The files in this package are not used by the demo app; they're just here to be +included as snippets in the documentation. By including them in the demo app +build, we can ensure that they're always up-to-date with the latest code. diff --git a/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt b/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt new file mode 100644 index 00000000..379782ae --- /dev/null +++ b/demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt @@ -0,0 +1,26 @@ +@file:Suppress("unused") + +package dev.sargunv.maplibrecompose.demoapp.docs + +import androidx.compose.foundation.isSystemInDarkTheme +import androidx.compose.runtime.Composable +import dev.sargunv.maplibrecompose.compose.MaplibreMap +import dev.sargunv.maplibrecompose.demoapp.generated.Res +import org.jetbrains.compose.resources.ExperimentalResourceApi + +@OptIn(ExperimentalResourceApi::class) +@Composable +fun Styling() { + // -8<- [start:simple] + MaplibreMap(styleUrl = "https://tiles.openfreemap.org/styles/liberty") + // -8<- [end:simple] + + // -8<- [start:dynamic] + val variant = if (isSystemInDarkTheme()) "dark" else "light" + MaplibreMap(styleUrl = "https://api.protomaps.com/styles/v4/$variant/en.json?key=MY_KEY") + // -8<- [end:dynamic] + + // -8<- [start:local] + MaplibreMap(styleUrl = Res.getUri("files/style.json")) + // -8<- [end:local] +} diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index dbd03406..1b07bfa2 100644 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -73,10 +73,7 @@ cocoapods { In your Composable UI, add a map: ```kotlin title="App.kt" -@Composable -fun App() { - MaplibreMap() -} +-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/GettingStarted.kt:app" ``` When you run your app, you should see the default [demotiles] map. To learn how diff --git a/docs/docs/styling.md b/docs/docs/styling.md index 3e90761b..c8e491b0 100644 --- a/docs/docs/styling.md +++ b/docs/docs/styling.md @@ -1 +1,47 @@ # Styling + +## Acquiring a style + +Every MapLibre map requires a style to be displayed. The style is a JSON object +that describes what data to display and how to display it. Typically, vector +tile providers create styles designed to work with their data, and provide them +as a URL. You can also create your own styles using [Maputnik][maputnik], a +visual style editor for MapLibre styles. + +There are a variety of free and commercial map tile providers available. See the +[awesome-maplibre][awesome-maplibre] repository for a list of tile providers. +This documentation primarily uses OpenFreeMap and Protomaps. Both of these are +free tile providers with their own styles. + +## Using a style + +To use a style, you can pass the `styleUrl` of the style to the `MaplibreMap` +composable: + +```kotlin +-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt:simple" +``` + +## Dark mode + +You can select a style at runtime based on regular Compose logic. MapLibre will +automatically animate the transition between styles: + +```kotlin +-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt:dynamic" +``` + +## Local styles + +While styles are typically hosted on the internet, you can also load a style +from a Compose resource URI: + +```kotlin +-8<- "demo-app/src/commonMain/kotlin/dev/sargunv/maplibrecompose/demoapp/docs/Styling.kt:local" +``` + +[maputnik]: https://maputnik.github.io/ +[awesome-maplibre]: + https://github.com/maplibre/awesome-maplibre#maptile-providers +[openfreemap]: https://openfreemap.org/ +[protomaps]: https://protomaps.com/ diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 2b224f88..dcb1c1e3 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -65,7 +65,9 @@ markdown_extensions: - pymdownx.keys - pymdownx.mark - pymdownx.smartsymbols - - pymdownx.snippets + - pymdownx.snippets: + base_path: ../ + dedent_subsections: true - pymdownx.superfences - pymdownx.tabbed: alternate_style: true