docs: fix docs for web

sargunv · Dec 31, 2024 · 20c9d10 · 20c9d10
1 parent 723e692
commit 20c9d10
Show file tree

Hide file tree

Showing 5 changed files with 76 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -4,38 +4,35 @@
 [![Documentation](https://img.shields.io/badge/Documentation-blue?logo=MaterialForMkDocs&logoColor=white)](https://sargunv.github.io/maplibre-compose/)
 [![API Reference](https://img.shields.io/badge/API_Reference-blue?logo=Kotlin&logoColor=white)](https://sargunv.github.io/maplibre-compose/api/)
 
-# MapLibre for Compose
+# MapLibre for Compose Multiplatform
 
-This project is a
-[Compose Multiplatform](https://www.jetbrains.com/compose-multiplatform/)
-library for [MapLibre](https://maplibre.org/). You can use it to embed an
-interactive vector map in your Compose app.
+## Introduction
+
+MapLibre Compose is a [Compose Multiplatform][compose] wrapper around the
+[MapLibre][maplibre] SDKs for rendering interactive maps. You can use it to add
+maps to your Compose UIs across Android, iOS, Desktop, and Web.
 
 <p float="left">
-  <img src="https://github.com/user-attachments/assets/997cf8a4-2841-40c8-b5a1-ef98193b21b2" width="200"/>
-  <img src="https://github.com/user-attachments/assets/e450f689-e254-48b7-bd91-3d3042faa290" width="200"/>
+  <img src="https://github.com/user-attachments/assets/997cf8a4-2841-40c8-b5a1-ef98193b21b2" width="200" alt="iOS Screenshot"/>
+  <img src="https://github.com/user-attachments/assets/e450f689-e254-48b7-bd91-3d3042faa290" width="200" alt="Android Screenshot"/>
 </p>
 
 ## Usage
 
-See the
-[Getting Started guide](https://sargunv.github.io/maplibre-compose/getting-started/)
-in the documentation.
+- [Getting Started](https://sargunv.github.io/maplibre-compose/getting-started/)
+- [API Reference](https://sargunv.github.io/maplibre-compose/api/)
+- [Demo App](./demo-app)
 
 ## Status
 
-Many common use cases are already supported, but the full breadth of the
-MapLibre SDKs is not yet covered. What is already supported may have bugs. API
-stability is not yet guaranteed; as we're still exploring how best to express an
-interactive map API in Compose.
-
-Android and iOS support is implemented with
-[MapLibre Native](https://github.com/maplibre/maplibre-native). A broad set of
-features are supported.
+A large subset of MapLibre's features are already supported, but the full
+breadth of the MapLibre SDKs is not yet covered. What is already supported may
+have bugs. API stability is not yet guaranteed; we're still exploring how best
+to express an interactive map API in Compose.
 
-Desktop support is implemented with
-[MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js) and
-[KCEF](https://github.com/DatL4g/KCEF). It's currently **very** limited and
-experimental.
+See [the status table][status] for a breakdown of supported features on each platform. Android and iOS have
+the most complete support, while Desktop and Web are still catching up.
 
-Web is not yet supported.
+[compose]: https://www.jetbrains.com/compose-multiplatform/
+[maplibre]: https://maplibre.org/
+[status]: https://sargunv.github.io/maplibre-compose/#status
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -22,8 +22,9 @@ tasks.withType<MkdocsTask>().configureEach {
     mapOf(
       "release_version" to releaseVersion,
       "snapshot_version" to snapshotVersion,
-      "maplibre_ios_version" to libs.versions.maplibre.ios.get(),
       "maplibre_android_version" to libs.versions.maplibre.android.sdk.get(),
+      "maplibre_ios_version" to libs.versions.maplibre.ios.get(),
+      "maplibre_js_version" to libs.versions.maplibre.js.get(),
     )
   )
 }

diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -96,12 +96,29 @@ androidMain.dependencies {
 }
 ```
 
+## Set up Web (JS)
+
+!!! warning
+
+    Web support is not yet at feature parity with Android and iOS. Check the [status table](index.md#status) for more info.
+
+For Web, you'll additionally need to add the MapLibre CSS to your page. The
+easiest way to do this is via the CDN:
+
+```kotlin title="index.html"
+<!doctype html>
+<html lang="en">
+  <head>
+    <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@{{ gradle.maplibre_js_version }}/dist/maplibre-gl.css'/>
+  </head>
+</html>
+```
+
 ## Set up Desktop (JVM)
 
 !!! warning
 
-    Desktop support is not yet at feature parity with Android and iOS. Feel free to try it out,
-    but don't expect it to work well yet. Check the [status table](index.md#status) for more info.
+    Desktop support is not yet at feature parity with Android and iOS. Check the [status table](index.md#status) for more info.
 
 On desktop, we use [DATL4g/KCEF][kcef] to embed a Chromium based browser. It
 requires some special configuration.

diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -4,7 +4,7 @@
 
 MapLibre Compose is a [Compose Multiplatform][compose] wrapper around the
 [MapLibre][maplibre] SDKs for rendering interactive maps. You can use it to add
-maps to your Compose UIs on Android and iOS.
+maps to your Compose UIs on Android, iOS, Desktop, and Web.
 
 ## Usage
 
@@ -19,35 +19,33 @@ breadth of the MapLibre SDKs is not yet covered. What is already supported may
 have bugs. API stability is not yet guaranteed; we're still exploring how best
 to express an interactive map API in Compose.
 
-Android and iOS support is implemented with [MapLibre Native][maplibre-native].
-
-Desktop support is implemented with [MapLibre GL JS][maplibre-js] and
-[KCEF][kcef].
-
-| Feature                                           | Android            | iOS                | Desktop            | Web |
-| ------------------------------------------------- | ------------------ | ------------------ | ------------------ | --- |
-| Render a map                                      | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| Overlay Compose UI over the map                   | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Load Compose resource URIs                        | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| Configure ornaments (compass, logo, attribution)  | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| Configure gestures (pan, zoom, rotate, pitch)     | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| Respond to a map click or long click              | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Query visible map features                        | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Get, set, and animate the camera position         | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Convert between screen and geographic coordinates | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Get the currently visible region and bounding box | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Insert, remove, and replace layers                | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Configure layers with expressions                 | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Add data sources by URI or GeoJSON                | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Add images to the style                           | :white_check_mark: | :white_check_mark: | :x:                | :x: |
-| Add annotations                                   | :x:                | :x:                | :x:                | :x: |
-| Snapshot the map as an image                      | :x:                | :x:                | :x:                | :x: |
-| Configure the offline cache                       | :x:                | :x:                | :x:                | :x: |
-| Configure layer transitions                       | :x:                | :x:                | :x:                | :x: |
+We don't yet support Wasm because one of our dependencies, [Spatial-K][spatial-k], doesn't support it.
+
+| Feature                                           | Android            | iOS                    | Desktop (JVM)                         | Web (JS)              | Web (Wasm) |
+|---------------------------------------------------|--------------------|------------------------|---------------------------------------|-----------------------|------------|
+| Renderer                                          | [MapLibre Native][MLN]      | [MapLibre Native][MLN] | [MapLibre JS][MLJS] in [KCEF][kcef] | [MapLibre JS][MLJS] | :x:        |
+| Load Compose resource URIs                        | :white_check_mark: | :white_check_mark:     | :white_check_mark:                    | :white_check_mark:    | :x:        |
+| Configure ornaments (compass, logo, attribution)  | :white_check_mark: | :white_check_mark:     | :white_check_mark:                    | :x:                   | :x:        |
+| Configure gestures (pan, zoom, rotate, pitch)     | :white_check_mark: | :white_check_mark:     | :white_check_mark:                    | :x:                   | :x:        |
+| Respond to a map click or long click              | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Query visible map features                        | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Get, set, and animate the camera position         | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Convert between screen and geographic coordinates | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Get the currently visible region and bounding box | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Insert, remove, and replace layers                | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Configure layers with expressions                 | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Add data sources by URI or GeoJSON                | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Add images to the style                           | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Add Material 3 controls                           | :white_check_mark: | :white_check_mark:     | :x:                                   | :x:                   | :x:        |
+| Add Compose UI annotations                        | :x:                | :x:                    | :x:                                   | :x:                   | :x:        |
+| Snapshot the map as an image                      | :x:                | :x:                    | :x:                                   | :x:                   | :x:        |
+| Configure the offline cache                       | :x:                | :x:                    | :x:                                   | :x:                   | :x:        |
+| Configure layer transitions                       | :x:                | :x:                    | :x:                                   | :x:                   | :x:        |
 
 [compose]: https://www.jetbrains.com/compose-multiplatform/
 [maplibre]: https://maplibre.org/
-[maplibre-native]: https://github.com/maplibre/maplibre-native
-[maplibre-js]: https://github.com/maplibre/maplibre-gl-js
+[MLN]: https://github.com/maplibre/maplibre-native
+[MLJS]: https://github.com/maplibre/maplibre-gl-js
 [kcef]: https://github.com/DatL4g/KCEF
 [repo-demo]: https://github.com/sargunv/maplibre-compose/tree/main/demo-app
+[spatial-k]: https://github.com/dellisd/spatial-k
diff --git a/docs/docs/material3.md b/docs/docs/material3.md
@@ -1,5 +1,14 @@
 # Material 3 extensions
 
+!!! warning
+
+    While this module is available across all platforms, you won't be able to display them on top of
+    the map on Web or Desktop due to technical limitations in Compose Multiplatform. See YouTrack
+    issue [CMP-6001](https://youtrack.jetbrains.com/issue/CMP-6001) and
+    [CMP-6856](https://youtrack.jetbrains.com/issue/CMP-6856).
+
+    Android and iOS are not affected by this limitation.
+
 ## Getting Started
 
 We provide reimplementations of certain ornaments using Material 3. These are