docs: improve guides and branding

.github/ISSUE_TEMPLATE/bug_report.md

@@ -15,7 +15,7 @@ Hello! Thanks for contributing.  For the fastest response and resolution, please
 
  - For build issues: Can you reproduce it on a clean install of the example app? Please include full steps to reproduce from `react-native init`
 
- - Include a link to a minimal demonstration of the bug, ideally a single component with one MapView. Use an example like [PointInMapView](/example/src/examples/Map/PointInMapView.js) as a starting point.
+ - Include a link to a minimal demonstration of the bug, ideally a single component with one MapView. Use an example like [PointInMapView](/packages/examples/src/BugReportPage.js) as a starting point.
 
  - Ensure you can reproduce the bug using the latest release.
 
@@ -37,15 +37,16 @@ Hello! Thanks for contributing.  For the fastest response and resolution, please
 
 ### Screenshots (if applicable)
 
-### Version(s) affected
+### Environment
 
 - Platform: [e.g. Android, iOS]
-- OS version: [e.g. Android 9, iOS 10]
-- Device type: [e.g. iPhone6]
-- Emulator/ Simulator: [yes/ no]
-- Development OS: [e.g. OSX 11.0.1, Win10]
-- maplibre-react-native Version [e.g. 7.0.9]
-- MapLibre GL version [e.g. 6.3.0]
-- React Native Version [e.g. 0.59]
+- OS version: [e.g. Android 15, iOS 18]
+- Device type: [e.g. iPhone 16]
+- Emulator or Simulator: [yes/no]
+- Development OS: [e.g. macOS 15.0.0, Windows 11]
+- `@maplibre/maplibre-react-native` Version: [e.g. 10.0.0]
+- MapLibre Native Version: [e.g. 6.7.0]
+- `react-native` Version: [e.g. 0.75.0]
+- `expo` Version: [e.g. 51.0.0]
 
 ### Additional context

.github/pull_request_template.md

@@ -22,7 +22,7 @@ Added `your feature` that allows ...
 - [ ] I have run tests via `yarn test` in the root folder
 - [ ] I updated the documentation with running `yarn generate` in the root folder
 - [ ] I mentioned this change in `CHANGELOG.md`
-- [ ] I added/updated a sample (`/example`)
+- [ ] I added/updated a sample (`/packages/examples`)
 
 ## Screenshot OR Video
 

.gitignore

@@ -41,11 +41,9 @@ node_modules
 *.log
 .nvm
 /bots/node_modules/
-/example/package-lock.json
 
 # Yarn
 .yarn/*
-example/.yarn/*
 !.yarn/patches
 !.yarn/plugins
 !.yarn/releases

CONTRIBUTING.md

@@ -8,26 +8,32 @@ your dev environment and streamline the review process.
 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.
+This project uses `yarn` as a package manager.
+
+> [!CAUTION]
+> 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.
 
 Make sure to correctly configure your Editor following [this docs](https://yarnpkg.com/getting-started/editor-sdks).
 
 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.
+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`
+The metro bundlers under [`/packages/react-native-app`](/packages/react-native-app) and [
+`/packages/expo-app`](/packages/expo-app) is set up to use the libraries files under root.
+Which means, when you change something within [
+`/javascript/components/UserLocation.tsx`](/javascript/components/UserLocation.tsx)
 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
+## 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).
@@ -42,14 +48,14 @@ can mitigate some of the pain with this.
 - 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 [`/packages/examples`](/packages/examples) for others to
+  see/test it
 
 ## Documentation
 
-Documentation is generated from code blocks and comments.
-It will be auto-generated when you commit changes.
-If any changes are generated from your edits, the changed files will need to be added using `git add` before attempting the commit again.
-To manually generate the changes, run `yarn generate`.
+Documentation is generated from code blocks and comments. It will be auto-generated when you commit changes. If any
+changes are generated from your edits, the changed files will need to be added using `git add` before attempting the
+commit again. To manually generate the changes, run `yarn generate`.
 
-Notice, that changing the documentation in the individual <COMPONENT>.md within `/docs` will not suffice.
-The correct way is the above described
+Notice, that changing the documentation in the individual <COMPONENT>.md within `/docs` will not suffice. The correct
+way is the above described

README.md

@@ -1,23 +1,17 @@
----
-
 [![MapLibre Logo](https://maplibre.org/img/maplibre-logo-big.svg)](https://maplibre.org)
 
+# MapLibre React Native
 
-# MapLibre GL SDK for React Native
-
-_A React Native library for building maps with   
-the [MapLibre GL Native SDK for iOS & Android](https://github.com/maplibre/maplibre-gl-native)_.
+_React Native library for creating maps with [MapLibre Native for Android & iOS](https://github.com/maplibre/maplibre-gl-native)_.
 
 This project originated as a fork of [rnmapbox](https://github.com/rnmapbox/maps), a community-maintained
-React Native Library for building maps with the Mapbox iOS and Android mobile SDKs. The original product
+React Native library for building maps with the Mapbox iOS and Android mobile SDKs. The original product
 supported both Mapbox and MapLibre for some time, but as the MapLibre and Mapbox SDKs have
 diverged, it has become necessary to separate the projects into specific wrappers by underlying renderer.
 
 ---
 
-[![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)  
+[![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)
 
 ---
 
@@ -34,7 +28,12 @@ diverged, it has become necessary to separate the projects into specific wrapper
 
 ## Documentation
 
-[Getting Started (start here)](/docs/GettingStarted.md)
+- [Getting Started](/docs/GettingStarted.md)
+- Installation
+  - React Native  
+    - [Android](/android/install.md)
+    - [iOS](/ios/install.md)
+  - [Expo](/plugin/install.md)
 
 ### Components
 
@@ -79,8 +78,8 @@ diverged, it has become necessary to separate the projects into specific wrapper
 ## Contributing / local 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 dev environment.
+set up your local development environment.
 
 ## Community
 
-Join the #maplibre-react-native or #maplibre Slack channels at OSMUS: get an invite at https://slack.openstreetmap.us/
+Join the `#maplibre-react-native` or `#maplibre` [Slack channels at OSMUS](https://slack.openstreetmap.us/).

android/install.md

@@ -2,10 +2,11 @@
 
 ## Access tokens
 
-Note that the Android SDK is slightly peculiar in that it
+> [!NOTE]
+> 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,
-you have to have a line like this in your code before using the SDK.
+you have to have a line like this in your code before using the library.
 You can put this near the top of your `App.js` for convenience.
 
 ```javascript

docs/Camera.md

@@ -19,7 +19,7 @@
 | maxZoomLevel | `number` | `none` | `false` | The maximun zoom level of the map |
 | maxBounds | `CameraBounds` | `none` | `false` | Restrict map panning so that the center is within these bounds |
 | followUserLocation | `boolean` | `none` | `false` | Should the map orientation follow the user's. |
-| followUserMode | `UserTrackingMode` | `none` | `false` | The mode used to track the user location on the map. One of; "normal", "compass", "course". Each mode string is also available as a member on the `MapLibreGL.UserTrackingModes` object. `Follow` (normal), `FollowWithHeading` (compass), `FollowWithCourse` (course). NOTE: `followUserLocation` must be set to `true` for any of the modes to take effect. [Example](../example/src/examples/Camera/SetUserTrackingModes.js) |
+| followUserMode | `UserTrackingMode` | `none` | `false` | The mode used to track the user location on the map. One of; "normal", "compass", "course". Each mode string is also available as a member on the `MapLibreGL.UserTrackingModes` object. `Follow` (normal), `FollowWithHeading` (compass), `FollowWithCourse` (course). NOTE: `followUserLocation` must be set to `true` for any of the modes to take effect. [Example](/packages/examples/src/examples/Camera/SetUserTrackingModes.js) |
 | followZoomLevel | `number` | `none` | `false` | The zoomLevel on map while followUserLocation is set to `true` |
 | followPitch | `number` | `none` | `false` | The pitch on map while followUserLocation is set to `true` |
 | followHeading | `number` | `none` | `false` | The heading on map while followUserLocation is set to `true` |

docs/GettingStarted.md

@@ -1,8 +1,7 @@
 # Getting Started
 
-Congratulations, you successfully installed maplibre-react-native! 🎉
-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.
+This quickstart guide provides a zero-to-map intro using React Native. From there you can check out the
+[examples](/packages/examples) folder if you want to jump in the deep end.
 
 ## Prerequisites
 
@@ -41,7 +40,7 @@ yarn add @maplibre/maplibre-react-native
 npm install @maplibre/maplibre-react-native --save
 ```
 
-### Review platform specific info
+### Review platform specific Details
 
 Check out the installation guide(s) for additional information about platform-specific setup, quirks,
 and steps required before running.

docs/MapView.md

@@ -1,6 +1,6 @@
 <!-- This file was autogenerated from MapView.js do not modify -->
 ## <MapLibreGL.MapView />
-### MapView backed by MapLibre GL Native
+### MapView backed by MapLibre Native
 
 ### props
 | Prop | Type | Default | Required | Description |

docs/docs.json

@@ -528,7 +528,7 @@
         "required": false,
         "type": "UserTrackingMode",
         "default": "none",
-        "description": "The mode used to track the user location on the map. One of; \"normal\", \"compass\", \"course\". Each mode string is also available as a member on the `MapLibreGL.UserTrackingModes` object. `Follow` (normal), `FollowWithHeading` (compass), `FollowWithCourse` (course). NOTE: `followUserLocation` must be set to `true` for any of the modes to take effect. [Example](../example/src/examples/Camera/SetUserTrackingModes.js)"
+        "description": "The mode used to track the user location on the map. One of; \"normal\", \"compass\", \"course\". Each mode string is also available as a member on the `MapLibreGL.UserTrackingModes` object. `Follow` (normal), `FollowWithHeading` (compass), `FollowWithCourse` (course). NOTE: `followUserLocation` must be set to `true` for any of the modes to take effect. [Example](/packages/examples/src/examples/Camera/SetUserTrackingModes.js)"
       },
       {
         "name": "followZoomLevel",
@@ -2068,7 +2068,7 @@
     ]
   },
   "MapView": {
-    "description": "MapView backed by MapLibre GL Native",
+    "description": "MapView backed by MapLibre Native",
     "displayName": "MapView",
     "methods": [
       {

ios/install.md

@@ -26,7 +26,7 @@ You are good to go!
 
 ## Note on iOS Simulator issues
 
-MapLibre GL Native has some issues on iOS Simulators in many
+MapLibre Native has some issues on iOS Simulators in many
 environments. The map either does not render at all or appears garbled when panning and zooming.
 It is best to test on a real device if at all possible at this time
 until this is fixed upstream. iOS devs can open the workspace in Xcode and run from there.

javascript/components/Camera.tsx

@@ -165,7 +165,7 @@ interface CameraProps extends Omit<ViewProps, "style">, CameraStop {
   followUserLocation?: boolean;
 
   /**
-   * The mode used to track the user location on the map. One of; "normal", "compass", "course". Each mode string is also available as a member on the `MapLibreGL.UserTrackingModes` object. `Follow` (normal), `FollowWithHeading` (compass), `FollowWithCourse` (course). NOTE: `followUserLocation` must be set to `true` for any of the modes to take effect. [Example](../example/src/examples/Camera/SetUserTrackingModes.js)
+   * The mode used to track the user location on the map. One of; "normal", "compass", "course". Each mode string is also available as a member on the `MapLibreGL.UserTrackingModes` object. `Follow` (normal), `FollowWithHeading` (compass), `FollowWithCourse` (course). NOTE: `followUserLocation` must be set to `true` for any of the modes to take effect. [Example](/packages/examples/src/examples/Camera/SetUserTrackingModes.js)
    */
   followUserMode?: UserTrackingMode;
 

javascript/components/MapView.tsx

@@ -33,7 +33,7 @@ import { getFilter } from "../utils/filterUtils";
 const MapLibreGL = NativeModules.MLNModule;
 if (MapLibreGL == null) {
   console.error(
-    "Native part of Mapbox React Native libraries were not registered properly, double check our native installation guides.",
+    "Native module of @maplibre/maplibre-react-native library was not registered properly, please consult the docs: https://github.com/maplibre/maplibre-react-native",
   );
 }
 
@@ -281,9 +281,8 @@ export interface MapViewRef {
 }
 
 /**
- * MapView backed by MapLibre GL Native
+ * MapView backed by MapLibre Native
  */
-
 const MapView = memo(
   React.forwardRef<MapViewRef, MapViewProps>(
     (

javascript/components/Style.tsx

@@ -281,7 +281,7 @@ function asSourceComponent(
       return getShapeSource(id, source);
   }
 
-  console.warn(`Maplibre source type '${source.type}' is not supported`);
+  console.warn(`MapLibre source type '${source.type}' is not supported`);
 
   return null;
 }

javascript/utils/StyleValue.ts

@@ -28,7 +28,9 @@ export function transformStyle(
     if (styleType === "color" && typeof rawStyle === "string") {
       const color = processColor(rawStyle);
       if (color === null || color === undefined || typeof color === "symbol") {
-        console.error(`RNMaplibre: Invalid color value: ${rawStyle} using red`);
+        console.error(
+          `@maplibre/maplibre-react-native: Invalid color value ${rawStyle}, using #ff0000 (red) instead`,
+        );
         rawStyle = "ff0000";
       } else {
         rawStyle = color;

maplibre-react-native.podspec

@@ -61,14 +61,14 @@ def $RCTMLN.post_install(installer)
 end
 
 Pod::Spec.new do |s|
-  s.name		= "maplibre-react-native"
-  s.summary		= "React Native Component for Maplibre Native"
+  s.name		  = "maplibre-react-native"
+  s.summary		= "React Native library for creating maps with MapLibre Native"
   s.version		= package['version']
-  s.authors		= { "Ian Wagner" => "[email protected]" }  # TODO: MapLibre email?
-  s.homepage    	= "https://github.com/maplibre/maplibre-react-native"
-  s.source      	= { :git => "https://github.com/maplibre/maplibre-react-native.git" }
-  s.license     	= "MIT"
-  s.platform    	= :ios, "8.0"
+  s.authors   = { "MapLibre" => "" }
+  s.homepage  = "https://github.com/maplibre/maplibre-react-native"
+  s.source    = { :git => "https://github.com/maplibre/maplibre-react-native.git" }
+  s.license   = "MIT"
+  s.platform  = :ios, "8.0"
 
   s.dependency 'React-Core'
   s.dependency 'React'

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplibre/maplibre-react-native",
-  "description": "A MapLibre GL Native plugin for creating maps in React Native",
+  "description": "React Native library for creating maps with MapLibre Native for Android & iOS",
   "version": "10.0.0-alpha.22",
   "publishConfig": {
     "access": "public"

packages/expo-app/README.md

@@ -0,0 +1,16 @@
+# MapLibre Expo Example App
+
+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.
+
+## Development Setup
+
+1. Install all monorepo dependencies by running `yarn install` from the root directory
+2. Switch to the `packages/expo-app` directory
+3. Build and run a platform:
+   - `yarn android` for building and running Android
+   - `yarn ios` for building and running iOS
+
+After you've built a development client, you can use `yarn start` to just reload the apps without another native build.