@maplibre/maplibre-react-native 8.6.0-beta.0 → 8.6.0-beta.1

package/CONTRIBUTING.md

@@ -1,18 +1,39 @@
 # Contributing
 
-## Setup for creating pull requests
+PRs are most welcome! This doc covers some basic things you'll need to know to set up
+your dev environment and streamline the review process. 
 
-- Fork this project
-- In your fork, create a branch, for example: `fix/camera-update`
-- Add your changes
-- Push and open a PR with your branch
+## Environment Setup
 
-## Testing changes
+This project includes `.nvmrc`. You should use nvm so that you're always developing for the correct
+version of Node.
+
+This project uses `yarn` as a package manager. DO NOT install `yarn` using `npm` as that will install
+the outdated 1.x branch. Full instructions are in the [yarn docs](https://yarnpkg.com/getting-started/install),
+but here's the quick checklist at the time of this writing.
+
+1. `corepack enable`
+2. `corepack prepare yarn@stable --activate`
+3. On first install, the above may change your yarn config away from `pnp`; check your git working copy for changes and revert if necessary.
+4. `yarn install`
+
+## Testing
 
 The metro bundler under `/example` is set up to use the libraries files under root.  
 Which means, when you change something within `javascript/components/UserLocation.js`  
 it will be reflected in any scene in example that uses that component.
 
+TODO: A better overview of how we use jest, detox, etc. (issue #22)
+
+## Optional: Local development with yalc
+
+It is often desirable to test in the context of an external project (for example,
+if you have a complex application using a map and want to test your changes directly).
+While it's not easy to do this out of the box with `yarn` or `npm`.
+[`yalc`](https://www.viget.com/articles/how-to-use-local-unpublished-node-packages-as-project-dependencies/)
+can mitigate some of the pain with this.
+
+
 ## Best practices for PRs
 
 - If you add a feature, make sure you add it to the documentation
@@ -20,7 +41,7 @@ it will be reflected in any scene in example that uses that component.
 - Make sure to use small concise commits
 - Use meaningful commit messages
 - Make sure to update/ add new tests for your changes
-- If you add a new feature make sure to add a scene in `/example` for others to see/ test it
+- If you add a new feature, make sure to add a scene in `/example` for others to see/ test it
 
 ## Documentation
 
@@ -31,4 +52,3 @@ To manually generate the changes, run `npm run generate`.
 
 Notice, that changing the documentation in the individual <COMPONENT>.md within `/docs` will not suffice.  
 The correct way is the above described
- 

package/README.md

@@ -17,9 +17,7 @@ diverged, it has become necessary to separate the projects into specific wrapper
 
 ---
 
-_TODO: update NPM badge_
-
-[![npm version](https://badge.fury.io/js/%40react-native-mapbox-gl%2Fmaps.svg)](https://badge.fury.io/js/%40react-native-mapbox-gl%2Fmaps)  
+[![npm version](https://badge.fury.io/js/%40maplibre%2Fmaplibre-react-native.svg)](https://badge.fury.io/js/%40maplibre%2Fmaplibre-react-native)  
 [![Android Build](https://github.com/maplibre/maplibre-react-native/actions/workflows/android-actions.yml/badge.svg)](https://github.com/maplibre/maplibre-react-native/actions/workflows/android-actions.yml)  
 [![iOS Build](https://github.com/maplibre/maplibre-react-native/actions/workflows/ios-actions.yml/badge.svg)](https://github.com/maplibre/maplibre-react-native/actions/workflows/ios-actions.yml)  
 
@@ -36,103 +34,10 @@ _TODO: update NPM badge_
      height="300"
       />
 
-# Quickstart for app developers
-
-## Prerequisites
-
-1. On Android we support from version 6 (API 23) upwards
-2. You will need a vector tile source (such as Stadia Maps or MapTiler) for production use; a demonstration URL is used in the below example.
-
-
-## Dependencies
-
-- [node](https://nodejs.org)
-- [npm](https://www.npmjs.com/)
-- [React Native](https://facebook.github.io/react-native/) (0.60+)
-
-
-## Installation
-
-### Step 1 - Install Package:
-
-```sh
-# install with Yarn
-yarn add @maplibre/maplibre-react-native
-
-
-# or install with NPM
-npm install @maplibre/maplibre-react-native --save
-```
-
-### Step 2 - Installation Guides:
-
-- [Android](/android/install.md)
-- [iOS](/ios/install.md)
-- [Expo](/plugin/install.md)
-- [Example](/example)
-
-
-### Getting Started
-For more information, check out our [Getting Started](/docs/GettingStarted.md) section
-
-## Run Project
-Before you run your project be sure you have completed the Installation Guides for Android or iOS.
-
-### Run iOS Simulator
-```sh
-# Run with yarn
-yarn run ios
-
-# or Run with NPM
-npm run ios
-```
-
-### Run Android Emulator
-```sh
-# Run with yarn
-yarn run android
-
-# or Run with NPM
-npm run android
-```
-
-## Adding a map
-
-```js
-import React, {Component} from 'react';
-import {StyleSheet, View} from 'react-native';
-import MapboxGL from '@maplibre/maplibre-react-native';
-
-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 (
-      <View style={styles.page}>
-        <MapboxGL.MapView
-          style={styles.map}
-          logoEnabled={false}
-          styleURL="https://demotiles.maplibre.org/style.json"
-        />
-      </View>
-    );
-  }
-}
-```
-
 ## Documentation
 
+[Getting Started (start here)](/docs/GettingStarted.md)
+
 ### Components
 
 - [MapView](/docs/MapView.md)
@@ -177,48 +82,11 @@ export default class App extends Component {
 
 This package is not available in the [Expo Go](https://expo.io/client) app. Learn how you can use it with [custom dev clients](/plugin/install.md).
 
-# Quickstart for contributors
-
-## Environment Setup
-
-This project includes `.nvmrc`. You should use nvm so that you're always developing for the correct
-version of Node.
-
-This project uses `yarn` as a package manager. DO NOT install `yarn` using `npm` as that will install
-the outdated 1.x branch. Full instructions are in the [yarn docs](https://yarnpkg.com/getting-started/install),
-but here's the quick checklist at the time of this writing.
-
-1. `corepack enable`
-2. `corepack prepare yarn@stable --activate`
-3. On first install, the above may change your yarn config away from `pnp`; check your git working copy for changes and revert if necessary.
-4. `yarn install`
-
-### JetBrains IDE Setup
-
-Your JetBrains IDE (such as IntelliJ) needs to be set to use yarn under Preferences > Languages & Frameworks > Node.js.
-This may require a manual change if you did not have yarn previously installed.
-
-## Testing with Jest
-
-This library provides some mocks which are necessary for running tests.
-
-Example:
-
-```json
-"jest": {
-  "preset": "react-native",
-  "setupFilesAfterEnv": ["@maplibre/maplibre-react-native/setup-jest"]
-}
-```
-
-## Optional: Local development with yalc
+## Contributing / local development
 
-When developing locally, it is often desirable to test in the context of an external project.
-However, it's not easy to do this out of the box with `yarn` or `npm`.
-[`yalc`](https://www.viget.com/articles/how-to-use-local-unpublished-node-packages-as-project-dependencies/)
-can mitigate some of the pain with this.
+Read the [CONTRIBUTING.md](CONTRIBUTING.md) guide in order to get familiar with how we do things around here and
+set up your local dev environment.
 
 ## Community
 
 Join the #maplibre-native Slack channel at OSMUS: get an invite at https://slack.openstreetmap.us/
-Read the [CONTRIBUTING.md](CONTRIBUTING.md) guide in order to get familiar with how we do things around here.

package/RELEASE.md

@@ -11,7 +11,7 @@ Once you verified, that `master` isn't broken, go on and increase the `version`
 
 ## Update the CHANGELOG accordingly
 
-Our [`CHANGELOG.md`](https://github.com/maplibre/maplibre-react-native/blob/master/CHANGELOG.md) should be updated whenever a PR is merged/ noteworthy changes are commited to `master`.  
+Our [`CHANGELOG.md`](https://github.com/maplibre/maplibre-react-native/blob/master/CHANGELOG.md) should be updated whenever a PR is merged/ noteworthy changes are committed to `master`.  
 Prior to a release, the changes should be documented under the `UNRELEASED` section.  
 Once it's clear, that a release is about to be published, move the items under `UNRELEASED` to _this_ releases sections.  
 Let your actions be guided by the previous release entries.

package/android/install.md

@@ -1,16 +1,31 @@
 # Android Installation
 
-We've set up the default MapLibre dependencies for you, and no
-special installation is required!
+## Access tokens
 
-Feel free to check out the `/example` projects [`android/build.gradle`](https://github.com/maplibre/maplibre-react-native/blob/main/example/)
-projects for inspiration to get started.
-
-Note that the Android SDK is slightly peculiar in that it absolutely
-requires setting an access token, even though it will be `null` for
-most users (non-Mapbox-users). Simply add something like this near
-the top of your `App.js`.
+Note that the Android SDK 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,
+you have to have a line like this in your code before using the SDK.
+You can put this near the top of your `App.js` for convenience.
 
 ```javascript
 MapboxGL.setAccessToken(null);
-```
+```
+
+## Setting connection status
+
+TODO: check if this is still an issue with MapLibre Native on Android (issue #21).
+
+If you are hosting styles and sources on localhost, you might need to set
+the connection status manually for the SDK to be able to use them.
+See [mapbox/mapbox-gl-native#12819](https://github.com/mapbox/mapbox-gl-native/issues/12819).
+
+Manually sets the connectivity state of the app, bypassing any checks to the
+`ConnectivityManager`. Set to `true` for connected, `false` for disconnected,
+and `null` for the normal `ConnectivityManager` behavior.
+
+```js
+import MapboxGL from "@maplibre/maplibre-react-native";
+
+MapboxGL.setConnected(true);
+```

package/docs/GettingStarted.md

@@ -1,72 +1,116 @@
 # Getting Started
 
 Congratulations, you successfully installed maplibre-react-native! 🎉
-Where to go from here?
-You can head straight to [examples](/example) folder if you want to jump into the deep end.
-However, if you prefer an easier ramp-up, then make sure to stick around and check out the guides below.
+This quickstart guide provides a zero-to-map intro, and from there you can check out the
+[examples](/example) folder if you want to jump in the deep end.
 
-## Setting your accessToken
+## Prerequisites
 
-FIXME: Rewrite this guide, but esp this section.
+1. On Android we support API 23 and higher
+2. You will need a vector tile source (such as Stadia Maps or MapTiler) for production use; a demonstration URL is used in the below example.
 
-In order to work, mapbox requires you to create an accessToken and set it in your app.
-If you haven't created one yet, make sure to sign up for an account [here](https://www.mapbox.com/signup/)
-You can create and manage your access tokens on your [Mapbox Account page](https://www.mapbox.com/account/)
-Once you have your accessToken, set it like this
+## Dependencies
 
-```js
-import MapboxGL from "@maplibre/maplibre-react-native";
+- [node](https://nodejs.org)
+- [npm](https://www.npmjs.com/)
+- [React Native](https://facebook.github.io/react-native/) (0.60+)
+
+## Installation
+
+### Step 0: Set up a React Native project
 
-MapboxGL.setAccessToken("<YOUR_ACCESSTOKEN>");
+If you don't have an existing React Native project, create one:
+
+```shell
+npx react-native init MyApp --version 0.68
 ```
 
-## Setting connection status [Android only]
+TODO: See if latest version works
 
-If you are hosting styles and sources on localhost, you might need to set the connection status manually for Mapbox to be able to use them. See [mapbox/mapbox-gl-native#12819](https://github.com/mapbox/mapbox-gl-native/issues/12819).
+### Install Package
 
-Manually sets the connectivity state of the app, bypassing any checks to the ConnectivityManager. Set to `true` for connected, `false` for disconnected, and `null` for ConnectivityManager to determine.
+From your React Native project's root directory, add the package via
+either `yarn` or `npm` (pick one).
 
-```js
-import MapboxGL from "@maplibre/maplibre-react-native";
+```shell
+# install with Yarn
+yarn add @maplibre/maplibre-react-native
+
+```
 
-MapboxGL.setConnected(true);
+```shell
+# install with NPM
+npm install @maplibre/maplibre-react-native --save
 ```
 
-## Show a map
+### Review platform specific info
+
+Check out the installation guide(s) for additional information about platform-specific setup, quirks,
+and steps requried before running.
+
+- [Android](/android/install.md)
+- [iOS](/ios/install.md)
+- [Expo](/plugin/install.md)
+
+## Adding a map
+
+Here is an example minimal App.js
 
 ```js
-import React, { Component } from "react";
-import { StyleSheet, View } from "react-native";
-import MapboxGL from "@maplibre/maplibre-react-native";
+import React, {Component} from 'react';
+import {StyleSheet, View} from 'react-native';
+import MapboxGL from '@maplibre/maplibre-react-native';
 
-MapboxGL.setAccessToken("<YOUR_ACCESSTOKEN>");
+// Will be null for most users (only Mapbox authenticates this way).
+// Required on Android. See Android installation notes.
+MapboxGL.setAccessToken(null);
 
 const styles = StyleSheet.create({
   page: {
     flex: 1,
-    justifyContent: "center",
-    alignItems: "center",
-    backgroundColor: "#F5FCFF"
-  },
-  container: {
-    height: 300,
-    width: 300,
-    backgroundColor: "tomato"
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: '#F5FCFF',
   },
   map: {
-    flex: 1
-  }
+    flex: 1,
+    alignSelf: 'stretch',
+  },
 });
 
 export default class App extends Component {
   render() {
     return (
       <View style={styles.page}>
-        <View style={styles.container}>
-          <MapboxGL.MapView style={styles.map} />
-        </View>
+        <MapboxGL.MapView
+          style={styles.map}
+          logoEnabled={false}
+          styleURL="https://demotiles.maplibre.org/style.json"
+        />
       </View>
     );
   }
 }
 ```
+
+## Run it!
+
+### iOS
+
+```shell
+# Run with yarn
+yarn run ios
+
+# or Run with NPM
+npm run ios
+```
+
+### Android
+
+```shell
+# Run with yarn
+yarn run android
+
+# or Run with NPM
+npm run android
+```

package/index.d.ts

@@ -1,4 +1,4 @@
-declare module 'react-native-mapbox-gl__maps';
+declare module 'maplibre__maplibre-react-native';
 
 import {
   Component,

package/ios/install.md

@@ -1,8 +1,6 @@
 # iOS Installation
 
 The following assumes, that you're using autolinking and installed
-
-
 `@maplibre/maplibre-react-native` via `npm` or `yarn`.
 
 Add the following to your `ios/Podfile`:
@@ -17,7 +15,7 @@ Add the following to your `ios/Podfile`:
 Running `pod install` will add version `5.12.2` of the MapLibre SDK.
 
 ```sh
-# Go to the ios folder
+# Go to the ios directory
 cd ios
 
 # Run Pod Install

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maplibre/maplibre-react-native",
   "description": "A MapLibre GL Native plugin for creating maps in React Native",
-  "version": "8.6.0-beta.0",
+  "version": "8.6.0-beta.1",
   "publishConfig": {
     "access": "public"
   },

package/plugin/install.md

@@ -2,7 +2,7 @@
 
 > This package cannot be used in the "Expo Go" app because [it requires custom native code](https://docs.expo.io/workflow/customizing/).
 
-First install the package with yarn, npm, or [`expo install`](https://docs.expo.io/workflow/expo-cli/#expo-install).
+First install the package with `yarn`, `npm`, or [`expo install`](https://docs.expo.io/workflow/expo-cli/#expo-install).
 
 ```sh
 expo install @maplibre/maplibre-react-native