diff --git a/README.md b/README.md index 630e733cf..3909153f8 100644 --- a/README.md +++ b/README.md @@ -15,66 +15,65 @@ supported both Mapbox and MapLibre for some time, but as the MapLibre and Mapbox diverged, it has become necessary to separate the projects into specific wrappers by underlying renderer.

- Indoor Building Map Android - Indoor Building Map iOS

## Documentation -- [Getting Started](/docs/GettingStarted.md) +- [Getting Started](/docs/guides/setup/GettingStarted.md) - Installation - React Native - - [Android](/android/install.md) - - [iOS](/ios/install.md) - - [Expo](/plugin/install.md) + - [Android](/docs/guides/setup/Android.md) + - [iOS](/docs/guides/setup/iOS.md) + - [Expo](/docs/guides/setup/Expo.md) ### Components -- [MapView](/docs/MapView.md) -- [Light](/docs/Light.md) -- [StyleSheet](/docs/StyleSheet.md) -- [PointAnnotation](/docs/PointAnnotation.md) -- [MarkerView](/docs/MarkerView.md) -- [Callout](/docs/Callout.md) -- [Camera](docs/Camera.md) -- [UserLocation](docs/UserLocation.md) -- [Images](docs/Images.md) +- [MapView](/docs/components/MapView.md) +- [Light](/docs/components/Light.md) +- [PointAnnotation](/docs/components/PointAnnotation.md) +- [MarkerView](/docs/components/MarkerView.md) +- [Callout](/docs/components/Callout.md) +- [Camera](docs/components/Camera.md) +- [UserLocation](docs/components/UserLocation.md) +- [Images](docs/components/Images.md) ### Sources -- [VectorSource](/docs/VectorSource.md) -- [ShapeSource](/docs/ShapeSource.md) -- [RasterSource](/docs/RasterSource.md) +- [VectorSource](/docs/components/VectorSource.md) +- [ShapeSource](/docs/components/ShapeSource.md) +- [RasterSource](/docs/components/RasterSource.md) ### Layers -- [BackgroundLayer](/docs/BackgroundLayer.md) -- [CircleLayer](/docs/CircleLayer.md) -- [FillExtrusionLayer](/docs/FillExtrusionLayer.md) -- [FillLayer](/docs/FillLayer.md) -- [LineLayer](/docs/LineLayer.md) -- [RasterLayer](/docs/RasterLayer.md) -- [SymbolLayer](/docs/SymbolLayer.md) -- [HeatmapLayer](/docs/HeatmapLayer.md) +- [BackgroundLayer](/docs/components/BackgroundLayer.md) +- [CircleLayer](/docs/components/CircleLayer.md) +- [FillExtrusionLayer](/docs/components/FillExtrusionLayer.md) +- [FillLayer](/docs/components/FillLayer.md) +- [LineLayer](/docs/components/LineLayer.md) +- [RasterLayer](/docs/components/RasterLayer.md) +- [SymbolLayer](/docs/components/SymbolLayer.md) +- [HeatmapLayer](/docs/components/HeatmapLayer.md) -### Offline +### Modules -- [OfflineManager](/docs/OfflineManager.md) -- [SnapshotManager](/docs/snapshotManager.md) +- [OfflineManager](/docs/modules/offlineManager.md) +- [SnapshotManager](/docs/modules/snapshotManager.md) ### Misc -- [MapLibreGL](/docs/MapLibreGL.md) -- [CustomHttpHeaders](/docs/CustomHttpHeaders.md) -- [Logger](/docs/Logger.md) +- [MapLibreGL](/docs/guides/MapLibreGL.md) +- [Custom HTTP Headers](/docs/guides/CustomHTTPHeaders.md) +- [Logger](/docs/guides/Logger.md) -## Contributing / local development +## Contributing & Development Read the [CONTRIBUTING.md](CONTRIBUTING.md) guide in order to get familiar with how we do things around here and set up your local development environment. diff --git a/docs/Annotations.md b/docs/Annotations.md deleted file mode 100644 index 0b37063e5..000000000 --- a/docs/Annotations.md +++ /dev/null @@ -1,12 +0,0 @@ -Comparsion of various annotations available in MapLibre React Native: - -|*Feature* | *SymbolLayer* |*PointAnnotation* |*MarkerView* |*CircleLayer* | -|-----------------------|--------------------|--------------------------------------|-------------------------|---------------------| -|Can use images | ✓ | | | | -|RN Views as childern | iOS: static |iOS: interactive
android: static|interactive | | -|Interactions | click |iOS: full
android: click & drag & callout | supports full interactivity in the sense that inside MarkerViews one can place any RN View, which can be interacted with. Not to be misunderstood with drag n drop interactivity. | click | -|Control Z-index | ✓ |iOS: always on top, android: n/a |always on top | ✓ | -|Clustering | ✓ | | | ✓ | -|Style with expressions | ✓ | | | ✓ | -|iOS implementation | [MLNSymbolStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNSymbolStyleLayer.html) |[MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) |[MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) |[MLNCircleStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNCircleStyleLayer.html) | -|android implementation | [SymbolLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/SymbolLayer.html)|[annotation.Symbol](https://docs.mapbox.com/android/api/plugins/annotation/0.8.0/com/mapbox/mapboxsdk/plugins/annotation/Symbol.html)|[annotation.Marker](https://docs.mapbox.com/android/api/plugins/markerview/0.4.0/com/mapbox/mapboxsdk/plugins/markerview/MarkerView.html) |[CircleLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/CircleLayer.html)| diff --git a/docs/Logger.md b/docs/Logger.md deleted file mode 100644 index c7c5f2fca..000000000 --- a/docs/Logger.md +++ /dev/null @@ -1,23 +0,0 @@ -## Logger -### - -### methods -#### setLogLevel(LogLevel) - -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `LogLevel` | `String` | `Yes` | required level of logging, can be `"error" | "warning" | "info" | "debug" | "verbose"` | - -##### Description -sets the amount of logging - -#### setLogCallback(LogCallback) - -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `LogCallback` | `function` | `Yes` | callback taking a log object `{ message: String, level: LogLevel, tag: String }` as param. If callback return falsy value then default logging will take place. | - -##### Description -overwrite logging - good to mute specific errors/ warnings \ No newline at end of file diff --git a/docs/MapLibreGL.md b/docs/MapLibreGL.md deleted file mode 100644 index 48179c6d9..000000000 --- a/docs/MapLibreGL.md +++ /dev/null @@ -1,65 +0,0 @@ -## MapLibreGL -### - -### methods -#### setAccessToken(accessToken) - -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` for other tile hosts | - -##### Description -sets the accessToken, which is required when you want to use mapbox tiles -not required when using other tiles - -#### getAccessToken() - -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` if for other tile hosts | - -##### Description -gets the accessToken - - -#### addCustomHeader(headerName, headerValue) - -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `headerName` | `String` | `Yes` | name for customHeader | -| `headerValue` | `String` | `Yes` | value for customHeader | - -##### Description -also see [CustomHttpHeaders](/docs/CustomHttpHeaders.md) - - -#### removeCustomHeader(headerName) - -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `headerName` | `String` | `Yes` | name of customHeader to be removed | - -##### Description -also see [CustomHttpHeaders](/docs/CustomHttpHeaders.md) - - -### Android only -#### requestAndroidLocationPermissions() -##### Description -Opens Android Location Permission prompt. -Returns a Promise which resolves into a boolean. -Either permission was granted or denied. - - -#### setConnected(connected) -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `connected` | `Boolean` | `Yes` | whether or not the SDK should assume it is online | - -#### Description -If you want to fully block map tile requests over the network, such as for a low-data / offline application. diff --git a/docs/StyleSheet.md b/docs/StyleSheet.md deleted file mode 100644 index 42a7e898c..000000000 --- a/docs/StyleSheet.md +++ /dev/null @@ -1,451 +0,0 @@ -## StyleSheet - - -### Stylesheet is now a JS object, see [CHANGELOG.md](../CHANGELOG.md) for more details - -See (MapLibre expression specs)[https://maplibre.org/maplibre-gl-js-docs/style-spec/expressions/] for reference on expressions. - -### Style functions - -#### zoom based expressions (replaces camera(stops[, interpolationMode])) - -This is a value function defining a style value that changes as the zoom level changes. The layout and paint attribute properties of the layer can be set to style function objects. Use a camera function to create the illusion of depth and control data density. - -new: -```js -// color would change based on zoom level keys. -[ - 'interpolate', - ['exponential', 1.5], - ['zoom'], - 0, 'blue', - 10, 'green', - 20, 'yellow' -]; - -// Example of use inside stylesheet -{ - fillColor: [ - 'step', - ['zoom'], - 'blue', - 20, 'green' - ] -} -``` - -old: - -```js -// color would change based on zoom level keys. -MapLibreGL.StyleSheet.camera({ - 0: 'blue', - 10: 'green', - 20: 'yellow', -}, MapLibreGL.InterpolationMode.Exponential); - -// Example of use inside stylesheet -MapLibreGL.StyleSheet.create({ - fillColor: MapLibreGL.StyleSheet.camera({ - 15: 'blue', - 20: 'green', - }, MapLibreGL.InterpolationMode.Interval), -}); -``` - -#### attribute based expressions (replaces source(stops, attributeName[, interpolationMode])) - -This is a value function defining a style value that changes with its properties. The layout and paint attribute properties of the layer can be set to style function objects. Use source functions to visually differentate types of features within the same layer or create data visualizations. - -new: -```js -// would color the layer based the property rating=[1, 5] -[ - 'step', - ['get', 'rating'], - 'red', - 2, 'orange', - 3, 'yellow', - 4, 'yellowgreen', - 5, 'green', -]; - -// Example of use inside stylesheet -{ - circleColor: [ - 'step', - ['get', 'rating'], - 'red', - 2, 'orange', - 3, 'yellow', - 4, 'yellowgreen', - 5, 'green', - ], -} -``` - - -old: - -```js -// would color the layer based the property rating=[1, 5] -MapLibreGL.StyleSheet.source([ - [1, 'red'], - [2, 'orange'], - [3, 'yellow'], - [4, 'yellowgreen'], - [5, 'green'], -], 'rating', MapLibreGL.InterpolationMode.Categorical); - -// Example of use inside stylesheet -MapLibreGL.StyleSheet.create({ - circleColor: MapLibreGL.StyleSheet.source([ - [1, 'red'], - [2, 'orange'], - [3, 'yellow'], - [4, 'yellowgreen'], - [5, 'green'], - ], 'rating', MapLibreGL.InterpolationMode.Categorical), -}); -``` - -#### nested expressions (replaces composite(stops, attributeName[, interpolationMode])) - -This is a value function defining a style value that changes with the feature attributes at each map zoom level. The layout and paint attribute properties of the layer can be set to style function objects. Use composite functions to allow the appearance of a map feature to change with both its attributes and the map zoom level. Note that support for composite functions is not yet complete in the Android/iOS SDK's. - -new: -```js -// would change based on the zoom level and rating value -// {zoom_level}: [{value}, {style_value}] -[ - 'step', - ['zoom'], - [ - 'step', - ['get','rating'], - 0, - 5, 5 - ], - 20, [ - 'step', - ['get','rating'], - 0, - 5, 20 - ] -] - -{ - circleRadius: [ - 'step', - ['zoom'], - [ 'step', - ['get','rating'], - 0, - 5, 5 - ], - 20, [ 'step', - ['get','rating'], - 0, - 5, 20 - ], -] -}; -``` - - -old: - -```js -// would change based on the zoom level and rating value -// {zoom_level}: [{value}, {style_value}] -MapLibreGL.StyleSheet.composite({ - 0: [0, 0], - 0: [5, 5], - 20: [0, 0], - 20: [5, 20], -}, 'rating', MapLibreGL.InterpolationMode.Interval); - -MapLibreGL.StyleSheet.create({ - circleRadius: MapLibreGL.StyleSheet.composite({ - 0: [0, 0], - 0: [5, 5], - 20: [0, 0], - 20: [5, 20], - }, 'rating', MapLibreGL.InterpolationMode.Interval), -}); -``` - -### Simple expressions - -#### ['get', attributeName] - replaces identity(attributeName) - -This is just a source style function under the hood. For example say if you had a feature property with an attribute height. Identity means that it will just equal the attribute value, so there is no need to provide any stops - -new: -```js -{ - fillExtrusionHeight: ['get', 'height'], -} -``` - -old: - -```js -MapLibreGL.StyleSheet.create({ - fillExtrusionHeight: MapLibreGL.StyleSheet.identity('height'), -}); -``` - -### StyleSheet Examples - - -#### new: - -```js -const styles = { - buildings: { - fillColor: 'blue', - }, - street: { - lineColor: 'green', - } -}; - -... - - - -``` - -```js -const layerStyles = { - singlePoint: { - circleColor: 'green', - circleOpacity: 0.84, - circleStrokeWidth: 2, - circleStrokeColor: 'white', - circleRadius: 5, - }, - - clusteredPoints: { - circleColor: [ - 'interpolate', - ['exponential', 1.5], - ['get','point_count'], - 25, 'yellow', - 50, 'red', - 75, 'blue', - 100, 'orange', - 300, 'pink', - 750, 'white', - ], - - circleRadius: [ - 'interpolate', - ['exponential', 1.5], - ['get','point_count'], - [0, 15], - [100, 20], - [750, 30], - ], - - circleOpacity: 0.84, - circleStrokeWidth: 2, - circleStrokeColor: 'white', - }, - - clusterCount: { - textField: ['get', 'point_count'], - textSize: 12, - }, -}); - -... - - - - - - -``` - -```javascript -const layerStyles = MapLibreGL.StyleSheet.create({ - building: { - fillExtrusionOpacity: 1, - fillExtrusionHeight: ['get', 'height'], - fillExtrusionBase: ['get', 'min_height'], - fillExtrusionColor: [ - 'interpolate', - ['exponential', 1.5], - ['get', 'height'], - [0, 'white'], - [50, 'blue'], - [100, 'red'], - ], - }, - fillExtrusionColorTransition: { duration: 2000, delay: 0 }, - }, - streets -: -{ - lineColor: 'blue', - lineWidth -: - 2, - lineOpacity -: - 0.50, - lineJoin -: - MapLibreGL.LineJoin.Round, - lineCap -: - MapLibreGL.LineCap.Round, - lineDasharray -: - [2, 2], -} -, -}) -; - -... - - - - -``` - -#### old: - -```js -const styles = MapLibreGL.StyleSheet.create({ - buildings: { - fillColor: 'blue', - }, - street: { - lineColor: 'green', - } -}); - -... - - - -``` - -```js -const layerStyles = MapLibreGL.StyleSheet.create({ - singlePoint: { - circleColor: 'green', - circleOpacity: 0.84, - circleStrokeWidth: 2, - circleStrokeColor: 'white', - circleRadius: 5, - }, - - clusteredPoints: { - circleColor: MapLibreGL.StyleSheet.source([ - [25, 'yellow'], - [50, 'red'], - [75, 'blue'], - [100, 'orange'], - [300, 'pink'], - [750, 'white'], - ], 'point_count', MapLibreGL.InterpolationMode.Exponential), - - circleRadius: MapLibreGL.StyleSheet.source([ - [0, 15], - [100, 20], - [750, 30], - ], 'point_count', MapLibreGL.InterpolationMode.Exponential), - - circleOpacity: 0.84, - circleStrokeWidth: 2, - circleStrokeColor: 'white', - }, - - clusterCount: { - textField: '{point_count}', - textSize: 12, - }, -}); - -... - - - - - - -``` - -```javascript -const layerStyles = MapLibreGL.StyleSheet.create({ - building: { - fillExtrusionOpacity: 1, - fillExtrusionHeight: MapLibreGL.StyleSheet.identity('height'), - fillExtrusionBase: MapLibreGL.StyleSheet.identity('min_height'), - fillExtrusionColor: MapLibreGL.StyleSheet.source([ - [0, 'white'], - [50, 'blue'], - [100, 'red'], - ], 'height', MapLibreGL.InterpolationMode.Exponential), - fillExtrusionColorTransition: { duration: 2000, delay: 0 }, - }, - streets: { - lineColor: 'blue', - lineWidth: 2, - lineOpacity: 0.50, - lineJoin: MapLibreGL.LineJoin.Round, - lineCap: MapLibreGL.LineCap.Round, - lineDasharray: [2, 2], - }, -}); - -... - - - - -``` - diff --git a/docs/assets/device-android.png b/docs/assets/device-android.png new file mode 100644 index 000000000..69f3d30a8 Binary files /dev/null and b/docs/assets/device-android.png differ diff --git a/docs/assets/device-ios.png b/docs/assets/device-ios.png new file mode 100644 index 000000000..4ffa376d4 Binary files /dev/null and b/docs/assets/device-ios.png differ diff --git a/docs/assets/indoor-building-map-android.png b/docs/assets/indoor-building-map-android.png deleted file mode 100644 index 8ad8d94af..000000000 Binary files a/docs/assets/indoor-building-map-android.png and /dev/null differ diff --git a/docs/assets/indoor-building-map-ios.png b/docs/assets/indoor-building-map-ios.png deleted file mode 100644 index 966c6d402..000000000 Binary files a/docs/assets/indoor-building-map-ios.png and /dev/null differ diff --git a/docs/Annotation.md b/docs/components/Annotation.md similarity index 100% rename from docs/Annotation.md rename to docs/components/Annotation.md diff --git a/docs/BackgroundLayer.md b/docs/components/BackgroundLayer.md similarity index 100% rename from docs/BackgroundLayer.md rename to docs/components/BackgroundLayer.md diff --git a/docs/Callout.md b/docs/components/Callout.md similarity index 100% rename from docs/Callout.md rename to docs/components/Callout.md diff --git a/docs/Camera.md b/docs/components/Camera.md similarity index 100% rename from docs/Camera.md rename to docs/components/Camera.md diff --git a/docs/CircleLayer.md b/docs/components/CircleLayer.md similarity index 100% rename from docs/CircleLayer.md rename to docs/components/CircleLayer.md diff --git a/docs/FillExtrusionLayer.md b/docs/components/FillExtrusionLayer.md similarity index 100% rename from docs/FillExtrusionLayer.md rename to docs/components/FillExtrusionLayer.md diff --git a/docs/FillLayer.md b/docs/components/FillLayer.md similarity index 100% rename from docs/FillLayer.md rename to docs/components/FillLayer.md diff --git a/docs/HeadingIndicator.md b/docs/components/HeadingIndicator.md similarity index 100% rename from docs/HeadingIndicator.md rename to docs/components/HeadingIndicator.md diff --git a/docs/HeatmapLayer.md b/docs/components/HeatmapLayer.md similarity index 100% rename from docs/HeatmapLayer.md rename to docs/components/HeatmapLayer.md diff --git a/docs/ImageSource.md b/docs/components/ImageSource.md similarity index 100% rename from docs/ImageSource.md rename to docs/components/ImageSource.md diff --git a/docs/Images.md b/docs/components/Images.md similarity index 100% rename from docs/Images.md rename to docs/components/Images.md diff --git a/docs/Light.md b/docs/components/Light.md similarity index 100% rename from docs/Light.md rename to docs/components/Light.md diff --git a/docs/LineLayer.md b/docs/components/LineLayer.md similarity index 100% rename from docs/LineLayer.md rename to docs/components/LineLayer.md diff --git a/docs/MapView.md b/docs/components/MapView.md similarity index 100% rename from docs/MapView.md rename to docs/components/MapView.md diff --git a/docs/MarkerView.md b/docs/components/MarkerView.md similarity index 100% rename from docs/MarkerView.md rename to docs/components/MarkerView.md diff --git a/docs/NativeUserLocation.md b/docs/components/NativeUserLocation.md similarity index 100% rename from docs/NativeUserLocation.md rename to docs/components/NativeUserLocation.md diff --git a/docs/PointAnnotation.md b/docs/components/PointAnnotation.md similarity index 100% rename from docs/PointAnnotation.md rename to docs/components/PointAnnotation.md diff --git a/docs/RasterLayer.md b/docs/components/RasterLayer.md similarity index 100% rename from docs/RasterLayer.md rename to docs/components/RasterLayer.md diff --git a/docs/RasterSource.md b/docs/components/RasterSource.md similarity index 100% rename from docs/RasterSource.md rename to docs/components/RasterSource.md diff --git a/docs/ShapeSource.md b/docs/components/ShapeSource.md similarity index 100% rename from docs/ShapeSource.md rename to docs/components/ShapeSource.md diff --git a/docs/Style.md b/docs/components/Style.md similarity index 100% rename from docs/Style.md rename to docs/components/Style.md diff --git a/docs/SymbolLayer.md b/docs/components/SymbolLayer.md similarity index 100% rename from docs/SymbolLayer.md rename to docs/components/SymbolLayer.md diff --git a/docs/UserLocation.md b/docs/components/UserLocation.md similarity index 100% rename from docs/UserLocation.md rename to docs/components/UserLocation.md diff --git a/docs/VectorSource.md b/docs/components/VectorSource.md similarity index 100% rename from docs/VectorSource.md rename to docs/components/VectorSource.md diff --git a/docs/docs.json b/docs/docs.json index 70aa44398..c422f2e3d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -81,6 +81,7 @@ "description": "FIX ME NO DESCRIPTION" } ], + "type": "component", "filePath": "src/components/Annotation.tsx", "name": "Annotation" }, @@ -108,6 +109,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/BackgroundLayer.tsx", "name": "BackgroundLayer", "styles": [ @@ -237,6 +239,7 @@ "composes": [ "Omit" ], + "type": "component", "filePath": "src/components/Callout.tsx", "name": "Callout" }, @@ -547,6 +550,7 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/Camera.tsx", "name": "Camera" }, @@ -574,6 +578,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/CircleLayer.tsx", "name": "CircleLayer", "styles": [ @@ -877,6 +882,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/FillExtrusionLayer.tsx", "name": "FillExtrusionLayer", "styles": [ @@ -1091,6 +1097,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/FillLayer.tsx", "name": "FillLayer", "styles": [ @@ -1290,6 +1297,7 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/HeadingIndicator.tsx", "name": "HeadingIndicator" }, @@ -1317,6 +1325,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/HeatmapLayer.tsx", "name": "HeatmapLayer", "styles": [ @@ -1493,6 +1502,7 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/ImageSource.tsx", "name": "ImageSource" }, @@ -1546,6 +1556,7 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/Images.tsx", "name": "Images" }, @@ -1566,6 +1577,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/Light.tsx", "name": "Light", "styles": [ @@ -1678,6 +1690,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/LineLayer.tsx", "name": "LineLayer", "styles": [ @@ -2558,6 +2571,7 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/MapView.tsx", "name": "MapView" }, @@ -2623,6 +2637,7 @@ "composes": [ "ViewProps" ], + "type": "component", "filePath": "src/components/MarkerView.tsx", "name": "MarkerView" }, @@ -2653,6 +2668,7 @@ "description": "Android only. Set max FPS at which location animators can output updates. Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on the device's CPU which can directly improve battery life, without sacrificing UX." } ], + "type": "component", "filePath": "src/components/NativeUserLocation.tsx", "name": "NativeUserLocation" }, @@ -2757,6 +2773,7 @@ "description": "FIX ME NO DESCRIPTION" } ], + "type": "component", "filePath": "src/components/PointAnnotation.tsx", "name": "PointAnnotation" }, @@ -2784,6 +2801,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/RasterLayer.tsx", "name": "RasterLayer", "styles": [ @@ -3037,6 +3055,7 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/RasterSource.tsx", "name": "RasterSource" }, @@ -3345,6 +3364,7 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/ShapeSource.tsx", "name": "ShapeSource" }, @@ -3361,6 +3381,7 @@ "description": "A JSON object conforming to the schema described in the MapLibre Style Specification, or a URL to such JSON." } ], + "type": "component", "filePath": "src/components/Style.tsx", "name": "Style" }, @@ -3395,6 +3416,7 @@ "BaseProps", "BaseLayerProps" ], + "type": "component", "filePath": "src/components/SymbolLayer.tsx", "name": "SymbolLayer", "styles": [ @@ -4846,6 +4868,7 @@ "description": "Custom location icon of type mapbox-gl-native components\n\nNOTE: Forking maintainer does not understand the above comment." } ], + "type": "component", "filePath": "src/components/UserLocation.tsx", "name": "UserLocation" }, @@ -5009,11 +5032,13 @@ "composes": [ "BaseProps" ], + "type": "component", "filePath": "src/components/VectorSource.tsx", "name": "VectorSource" }, "coordinates": { "name": "coordinates", + "type": "module", "filePath": "src/modules/location/locationManager.ts", "description": "Coorinates sent by locationManager", "props": [], @@ -5022,6 +5047,7 @@ }, "location": { "name": "location", + "type": "module", "filePath": "src/modules/location/locationManager.ts", "description": "Location sent by locationManager", "props": [], @@ -5030,6 +5056,7 @@ }, "offlineManager": { "name": "offlineManager", + "type": "module", "filePath": "src/modules/offline/offlineManager.ts", "description": "OfflineManager implements a singleton (shared object) that manages offline packs.\nAll of this class’s instance methods are asynchronous, reflecting the fact that offline resources are stored in a database.\nThe shared object maintains a canonical collection of offline packs.", "props": [], @@ -5357,6 +5384,7 @@ }, "snapshotManager": { "name": "snapshotManager", + "type": "module", "filePath": "src/modules/snapshot/snapshotManager.ts", "description": "The snapshotManager generates static raster images of the map.\nEach snapshot image depicts a portion of a map defined by an SnapshotOptions object you provide.\nThe snapshotter generates the snapshot asynchronous.", "props": [], diff --git a/docs/guides/Annotations.md b/docs/guides/Annotations.md new file mode 100644 index 000000000..d1e423af1 --- /dev/null +++ b/docs/guides/Annotations.md @@ -0,0 +1,14 @@ +# Annotations + +Comparison of various annotations available in MapLibre React Native: + +| Feature | `SymbolLayer` | `PointAnnotation` | `MarkerView` | `CircleLayer` | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| Can use images | ✓ | | | | +| RN Views as childern | iOS: static | iOS: interactive
android: static | interactive | | +| Interactions | click | iOS: full
android: click & drag & callout | supports full interactivity in the sense that inside MarkerViews one can place any RN View, which can be interacted with. Not to be misunderstood with drag n drop interactivity. | click | +| Control Z-index | ✓ | iOS: always on top, android: n/a | always on top | ✓ | +| Clustering | ✓ | | | ✓ | +| Style with expressions | ✓ | | | ✓ | +| iOS implementation | [MLNSymbolStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNSymbolStyleLayer.html) | [MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) | [MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) | [MLNCircleStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNCircleStyleLayer.html) | +| android implementation | [SymbolLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/SymbolLayer.html) | [annotation.Symbol](https://docs.mapbox.com/android/api/plugins/annotation/0.8.0/com/mapbox/mapboxsdk/plugins/annotation/Symbol.html) | [annotation.Marker](https://docs.mapbox.com/android/api/plugins/markerview/0.4.0/com/mapbox/mapboxsdk/plugins/markerview/MarkerView.html) | [CircleLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/CircleLayer.html) | diff --git a/docs/CustomHttpHeaders.md b/docs/guides/CustomHTTPHeaders.md similarity index 61% rename from docs/CustomHttpHeaders.md rename to docs/guides/CustomHTTPHeaders.md index e4890c876..d3c419b1b 100644 --- a/docs/CustomHttpHeaders.md +++ b/docs/guides/CustomHTTPHeaders.md @@ -1,23 +1,23 @@ -## Custom http headers +# Custom HTTP Headers -### Intro +## Intro -Custom headers are implemented using OkHttp interseptor for android and method swizzling for iOS. +Custom headers are implemented using OkHttp interceptor for android and method swizzling for iOS. [Method swizzling](https://en.wikipedia.org/wiki/Monkey_patch) is done on the `[NSMutableURLRequest requestWithURL:]` to allow adding headers during runtime. -### Prerequisites +## Prerequisites -#### Android +### Android None -#### IOS +### iOS To enable this on iOS you need to call `[[MLRNCustomHeaders sharedInstance] initHeaders]` pretty early in the lifecycle of the application. This will swizzle the custom method. Suggested location is `[AppDelegate application: didFinishLaunchingWithOptions:]` -#### Working example (AppDelegate.m) +### Working Example `AppDelegate.m` ```obj-c // (1) Include the header file @@ -45,43 +45,34 @@ Suggested location is `[AppDelegate application: didFinishLaunchingWithOptions:] @end ``` -### Sending custom http headers with the tile requests +## Sending custom HTTP Headers with the Tile Requests -You can configure sending of custom http headers to your tile server. This is to support custom authentication or custom metadata which can't be included in the url. +You can configure sending of custom HTTP headers to your tile server. This is to support custom authentication or custom metadata which can't be included in the url. You can add and remove headers at runtime. -#### To add a header +### Adding a Header ```javascript - MapLibreGL.addCustomHeader('Authorization', '{auth header}'); +MapLibreGL.addCustomHeader("Authorization", "{auth header}"); ``` -#### To remove a header +### Removing a Header ```javascript - MapLibreGL.removeCustomHeader('Authorization'); +MapLibreGL.removeCustomHeader("Authorization"); ``` -#### Working example +### Working Example ```javascript -export default class HelloWorldApp extends Component { - componentDidMount () { - MapLibreGL.addCustomHeader('Authorization', '{auth header}'); - } - - render () { - MapLibreGL.addCustomHeader('X-Some-Header', 'my-value'); - return ( - - - - - - ); - } +export default function App() { + useEffect(() => { + MapLibreGL.addCustomHeader("Authorization", "{auth header}"); + }, []); + + MapLibreGL.addCustomHeader("X-Some-Header", "my-value"); + + return ; } ``` diff --git a/docs/guides/Logger.md b/docs/guides/Logger.md new file mode 100644 index 000000000..8c1a0b276 --- /dev/null +++ b/docs/guides/Logger.md @@ -0,0 +1,23 @@ +# Logger + +## Methods + +### `setLogLevel(LogLevel)` + +Sets the amount of logging. + +#### Arguments + +| Name | Type | Required | Description | +| ---------- | :------: | :------: | :----------------------------------------: | --------- | ------ | ------- | ---------- | +| `LogLevel` | `String` | `Yes` | required level of logging, can be `"error" | "warning" | "info" | "debug" | "verbose"` | + +### `setLogCallback(LogCallback)` + +Overwrite logging, possibility to mute specific errors/warnings. + +#### Arguments + +| Name | Type | Required | Description | +| ------------- | :--------: | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| `LogCallback` | `function` | `Yes` | callback taking a log object `{ message: String, level: LogLevel, tag: String }` as param. If callback return falsy value then default logging will take place. | diff --git a/docs/guides/MapLibreGL.md b/docs/guides/MapLibreGL.md new file mode 100644 index 000000000..f93e5b097 --- /dev/null +++ b/docs/guides/MapLibreGL.md @@ -0,0 +1,59 @@ +# MapLibreGL + +## Methods + +### `setAccessToken(accessToken)` + +sets the accessToken, which is required when you want to use mapbox tiles +not required when using other tiles + +#### Arguments + +| Name | Type | Required | Description | +| ------------- | :------: | :------: | :--------------------------------------------------------------------------: | +| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` for other tile hosts | + +### `getAccessToken()` + +gets the accessToken + +#### Arguments + +| Name | Type | Required | Description | +| ------------- | :------: | :------: | :-----------------------------------------------------------------------------: | +| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` if for other tile hosts | + +### `addCustomHeader(headerName, headerValue)` + +#### Arguments + +also see [Custom HTTP Headers](/docs/guides/CustomHTTPHeaders.md) + +| Name | Type | Required | Description | +| ------------- | :------: | :------: | :--------------------: | +| `headerName` | `String` | `Yes` | name for customHeader | +| `headerValue` | `String` | `Yes` | value for customHeader | + +### `removeCustomHeader(headerName)` + +Also see [Custom HTTP Headers](/docs/guides/CustomHTTPHeaders.md) + +#### Arguments + +| Name | Type | Required | Description | +| ------------ | :------: | :------: | :--------------------------------: | +| `headerName` | `String` | `Yes` | name of customHeader to be removed | + +### `requestAndroidLocationPermissions()` + +Android only, opens Location Permission prompt. Returns a Promise which resolves into a boolean. Either permission was granted or denied. + +### `setConnected(connected)` + +If you want to fully block map tile requests over the network, such as for a low-data / offline application. + +#### arguments + +| Name | Type | Required | Description | +| ----------- | :-------: | :------: | :-----------------------------------------------: | +| `connected` | `Boolean` | `Yes` | whether or not the SDK should assume it is online | diff --git a/android/install.md b/docs/guides/setup/Android.md similarity index 97% rename from android/install.md rename to docs/guides/setup/Android.md index f57e8a1e5..3369c2e7d 100644 --- a/android/install.md +++ b/docs/guides/setup/Android.md @@ -1,8 +1,8 @@ -# Android Installation +# Android Setup ## Access tokens -> [!NOTE] +> [!IMPORTANT] > MapLibre Native for Android is slightly peculiar in that it _requires_ setting an access token, even though it will be `null` for most users (only Mapbox authenticates this way). Even if it feels odd, diff --git a/plugin/install.md b/docs/guides/setup/Expo.md similarity index 98% rename from plugin/install.md rename to docs/guides/setup/Expo.md index f500de833..f8a67f703 100644 --- a/plugin/install.md +++ b/docs/guides/setup/Expo.md @@ -1,4 +1,4 @@ -# Expo Installation +# Expo Setup NOTE: This package cannot be used in the "Expo Go" app because [it requires custom native code](https://docs.expo.io/workflow/customizing/). diff --git a/docs/GettingStarted.md b/docs/guides/setup/GettingStarted.md similarity index 66% rename from docs/GettingStarted.md rename to docs/guides/setup/GettingStarted.md index 9904c80e2..9835338f8 100644 --- a/docs/GettingStarted.md +++ b/docs/guides/setup/GettingStarted.md @@ -45,48 +45,24 @@ npm install @maplibre/maplibre-react-native --save Check out the installation guide(s) for additional information about platform-specific setup, quirks, and steps required before running. -- [Android](/android/install.md) -- [iOS](/ios/install.md) -- [Expo](/plugin/install.md) +- [Android](/docs/guides/setup/Android.md) +- [iOS](/docs/guides/setup/iOS.md) +- [Expo](/docs/guides/setup/Expo.md) ## Adding a map -Here is an example minimal App.js +Here is an example minimal `App.tsx`: -```js -import React, {Component} from 'react'; -import {StyleSheet, View} from 'react-native'; -import MapLibreGL from '@maplibre/maplibre-react-native'; +```tsx +import React from "react"; +import MapLibreGL from "@maplibre/maplibre-react-native"; // Will be null for most users (only Mapbox authenticates this way). // Required on Android. See Android installation notes. MapLibreGL.setAccessToken(null); -const styles = StyleSheet.create({ - page: { - flex: 1, - justifyContent: 'center', - alignItems: 'center', - backgroundColor: '#F5FCFF', - }, - map: { - flex: 1, - alignSelf: 'stretch', - }, -}); - -export default class App extends Component { - render() { - return ( - - - - ); - } +export default function App() { + return ; } ``` diff --git a/ios/install.md b/docs/guides/setup/iOS.md similarity index 98% rename from ios/install.md rename to docs/guides/setup/iOS.md index 0f70aabbc..a08f573c9 100644 --- a/ios/install.md +++ b/docs/guides/setup/iOS.md @@ -1,4 +1,4 @@ -# iOS Installation +# iOS Setup The following assumes, that you're using autolinking and installed `@maplibre/maplibre-react-native` via `npm` or `yarn`. diff --git a/docs/coordinates.md b/docs/modules/coordinates.md similarity index 100% rename from docs/coordinates.md rename to docs/modules/coordinates.md diff --git a/docs/location.md b/docs/modules/location.md similarity index 100% rename from docs/location.md rename to docs/modules/location.md diff --git a/docs/offlineManager.md b/docs/modules/offlineManager.md similarity index 100% rename from docs/offlineManager.md rename to docs/modules/offlineManager.md diff --git a/docs/snapshotManager.md b/docs/modules/snapshotManager.md similarity index 100% rename from docs/snapshotManager.md rename to docs/modules/snapshotManager.md diff --git a/packages/expo-app/README.md b/packages/expo-app/README.md index 6990c0f4b..2b5777832 100644 --- a/packages/expo-app/README.md +++ b/packages/expo-app/README.md @@ -2,8 +2,8 @@ This is an app to demonstrate the possibilities of `@maplibre/maplibre-react-native` within Expo. -> [!NOTE] -> This app is configured through a monorepo for easy native development of the library. Follow the [Getting Started](/docs/GettingStarted.md) guide for regular installation steps. +> [!IMPORTANT] +> This app is configured through a monorepo for easy native development of the library. Follow the [Getting Started](/docs/guides/setup/GettingStarted.md) guide for regular installation steps. ## Development Setup diff --git a/packages/react-native-app/README.md b/packages/react-native-app/README.md index 1cf475200..1e51e9adf 100644 --- a/packages/react-native-app/README.md +++ b/packages/react-native-app/README.md @@ -2,8 +2,8 @@ This is an app to demonstrate the possibilities of `@maplibre/maplibre-react-native` within React Native. -> [!NOTE] -> This app is configured through a monorepo for easy native development of the library. Follow the [Getting Started](/docs/GettingStarted.md) guide for regular installation steps. +> [!IMPORTANT] +> This app is configured through a monorepo for easy native development of the library. Follow the [Getting Started](/docs/guides/setup/GettingStarted.md) guide for regular installation steps. ## Development Setup diff --git a/plugin/src/withMapLibre.ts b/plugin/src/withMapLibre.ts index d81edf360..a6e608769 100644 --- a/plugin/src/withMapLibre.ts +++ b/plugin/src/withMapLibre.ts @@ -27,7 +27,7 @@ type InstallerBlockName = "pre" | "post"; * Dangerously adds the custom installer hooks to the Podfile. * In the future this should be removed in favor of some custom hooks provided by Expo autolinking. * - * https://github.com/maplibre/maplibre-react-native/blob/main/ios/install.md + * https://github.com/maplibre/maplibre-react-native/blob/main/docs/guides/setup/iOS.md * @param config * @returns */ diff --git a/scripts/utils/DocJSONBuilder.ts b/scripts/utils/DocJSONBuilder.ts index d40f4ca65..829a22f5d 100644 --- a/scripts/utils/DocJSONBuilder.ts +++ b/scripts/utils/DocJSONBuilder.ts @@ -390,6 +390,7 @@ export class DocJSONBuilder { results[path.parse(base).name] = { ...parsed, + type: "component", filePath: path.relative( WORKSPACE_ROOT, path.join(COMPONENT_DIRECTORY, base), @@ -419,6 +420,7 @@ export class DocJSONBuilder { results[name] = { name, + type: "module", filePath: path.relative(WORKSPACE_ROOT, module.context.file), description: node.getText(), props: [], diff --git a/scripts/utils/MarkdownBuilder.ts b/scripts/utils/MarkdownBuilder.ts index 5851be282..c8b2f060a 100644 --- a/scripts/utils/MarkdownBuilder.ts +++ b/scripts/utils/MarkdownBuilder.ts @@ -20,7 +20,14 @@ export class MarkdownBuilder { helpers: TemplateHelpers, }); await fs.writeFile( - path.join(__dirname, "..", "..", "docs", `${componentName}.md`), + path.join( + __dirname, + "..", + "..", + "docs", + `${docJSON[componentName].type}s`, + `${componentName}.md`, + ), fileContents, ); }