@neshan-maps-platform/mapbox-gl-react 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+<div dir="rtl">
+
+# نسخه‌ی رسمی `@neshan-maps-platform/mapbox-gl` برای `ReactJS`
+
+این پکیج، `wrapper` رسمی نشان برای `@neshan-maps-platform/mapbox-gl` جهت استفاده در پروژه‌های ساخته شده با `ReactJS` است.
+به کمک این پکیج، شما به راحتی می‌توانید درون پروژه‌ی `ReactJS` خود، از `mapbox-gl`، با استایل‌های نقشه‌ی نشان، به همراه قابلیت نمایش ترافیک
+و POIها، استفاده کنید.
+
+## Dependencies -- وابستگی‌ها
+
+- `@neshan-maps-platform/mapbox-gl`: ورژن `1.0.10` یا بالاتر
+- `@types/mapbox-gl`: ورژن `2.7.15` یا بالاتر
+- `react`: ورژن `18.2.0` یا بالاتر
+- `react-dom`: ورژن `18.2.0` یا بالاتر
+
+## Installation guide -- شیوه‌ی نصب
+
+- با استفاده از `npm`:
+
+`npm install @neshan-maps-platform/mapbox-gl-react`
+
+- با استفاده از `yarn`:
+
+`yarn add @neshan-maps-platform/mapbox-gl-react`
+
+## Usage -- شیوه‌ی استفاده
+
+1. ابتدا با ساخت حساب کاربری در [پلتفرم نقشه‌ی نشان](https://platform.neshan.org/)، یک API_KEY برای خود بسازید. توضیحات لازم در وبسایت پلتفرم نقشه‌ی نشان داده شده است.
+2. سپس، با استفاده از package managerای که دارید استفاده می‌کنید، این پکیج را در پروژه‌ی خود نصب کنید.
+3. بعد از نصب کردن پکیج در پروژه‌ی خود، می‌توانید با استفاده از کامپوننت `MapComponent`، از نقشه استفاده کنید:
+
+<div dir="ltr">
+
+```jsx
+// Your imports
+import {MapComponent, MapTypes} from "@neshan-maps-platform/mapbox-gl-react";
+import "@neshan-maps-platform/mapbox-gl-react/dist/style.css";
+
+function App() {
+    // Your Code
+    return (
+        {/*Your Component Structure*/}
+        <MapComponent options={{mapKey: "YOUR_API_KEY", mapType: MapTypes.neshanRasterNight}}/>
+        {/*Your Component Structure*/}
+    );
+}
+
+export default App;
+```
+</div>
+
+در ادامه با هم پارامترهای ورودی این کامپوننت را بررسی می‌کنیم:
+
+## Component Props -- ورودی‌های کامپوننت
+
+### `options: MapboxComponentInputOptions (object)`
+
+یک `object` است که شامل مقادیر ورودی مورد نیاز برای `mapbox-gl` است. تمامی `property`های زیر، اختیاری هستند و مقدار پیش‌فرض آنها نیز ذکر شده. **تنها ارائه‌ی `mapKey` برای کار کردن کامپوننت، اجباری است!**
+
+- `mapKey`: از نوع `string` است. مقدار آن نشان دهنده‌ی API_KEYای که از وبسایت پلتفرم نشان دریافت می‌کنید، است.  در صورتی که مقدار آن، درست نباشد، نمی‌توانید از کامپوننت استفاده کنید. همچنین در console، با اروری مبنی بر درست نبودن مقدار آن مواجه خواهی شد.
+- `mapType`: از نوع `string` است. و نوع استایل نقشه را مشخص می‌کند. در حال حاضر، صرفا چهار استایل برای نقشه موجود است: `neshanVector`, `neshanVectorNight`, `neshanRaster`, `neshanRasterNight`.
+  برای مقدار دهی این `property`، می‌توانید از `MapTypes` که یک `enum` است و در همین پروژه موجود است، استفاده کنید.(به مثال بالا مراجعه کنید).
+مقدار پیش‌فرض این `property` برابر `neshanVector` است.
+- `poi`: از نوع `boolean` است. مشخص می‌کند که در ابتدا و بعد از لود شدن نقشه، poiها روی نقشه نمایش داده شوند یا نه.
+مقدار پیش‌فرض آن برابر `false` است.
+- `traffic`: از نوع `boolean` است. مشخص می‌کند که در ابتدا و بعد از لود شدن نقشه، لایه‌ی ترافیک فعال باشد یا خیر.
+مقدار پیش‌فرض آن برابر `false` است.
+- `isTouchPlatform` : از نوع `boolean` است. و نوع دستگاه(تاچ و موبایل یا دسکتاپ) را مشخص می‌کند. مقدار پیش‌فرض آن `false` است.
+- `mapTypeControllerStatus`: از نوع `object` است. مشخص می‌کند که آیا کنترل لایه‌ها و استایل‌های نقشه نمایش داده شود یا خیر. و همچنین موقعیت آن را مشخص می‌کند:
+<div dir="ltr">
+
+```js
+interface mapTypeControllerStatus {
+    show: boolean,
+        position: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
+}
+```
+</div>
+
+مقدار پیش‌فرض `show` برابر `true` و مقدار پیش‌فرض `position` برابر `bottom-left` است. می‌توان هر یک از این دو `property` را overwrite کرد.
+
+دیگر `property`های موجود در `options`، مربوط به خود `mapbox-gl` هستند. برای دیدن آنها به مستندات خود کتابخانه‌ی `mapbox-gl` مراجعه کنید.
+
+*نکته: شما نمی‌توانید مقداری برای `property` تعیین کننده‌ی `container` پاس دهید.*
+### `mapSetter: (map: SDKMap) => void (optional)`
+
+از نوع تابع است و صرفا یک ورودی می‌گیرد. پاس دادن آن، اختیاری است. این تابع برای دسترسی شما به instance ایجاد شده از کلاس Map است. بعد از ایجاد شدن Map، مقدار آن به عنوان ورودی به این تابع، پاس داده می‌شود.
+
+### `containerElementSetter: (el: HTMLDivElement) => void (optional)`
+
+از نوع تابع است و صرفا یک ورودی می‌گیرد. پاس دادن آن، اختیاری است. این تابع برای دسترسی شما به elementای که Map در آن رندر می‌شود، است. بعد از ایجاد شدن Map و رندر شدن آن، خود containerElement به عنوان ورودی به این تابع، پاس داده می‌شود.
+
+### دیگر موارد
+
+سه موردی که ذکر شد، `prop`هایی بودند که مستقیما در عملکرد نقشه نقش داشتند و یا با نقشه سروکار دارند. اما این کامپوننت، `prop`های دیگری نیز می‌پذیرد. شما می‌توانید همه‌ی `prop`هایی که یک `HTMLDivElement` قبول می‌کند را به کامپوننت پاس بدهید. همه‌ی این `prop`ها، به `container` نقشه پاس داده خواهند شد.
+
+### استفاده از کلاس‌های MapboxGL
+
+همانطور که در بخش وابستگی‌ها مشاهده می‌شود، این کتابخانه از پکیج `@neshan-maps-platform/mapbox-gl` استفاده می‌کند. برای استفاده از دیگر کلاس‌ها و `property`های MapboxGL، مانند `Marker` و ...، باید آنها را از مسیر `@neshan-maps-platform/mapbox-gl`، در جایی که می‌خواهید، `import` کنید. مانند مثال زیر: 
+<div dir="ltr">
+
+```tsx
+//...
+import nmp_mapboxgl from '@neshan-maps-platform/mapbox-gl';
+
+function MyComponent(...){
+  //Your code here
+  const marker = new nmp_mapboxgl.Marker(...);
+  return (...);
+}
+
+export default MyComponent
+```
+</div>
+</div>

package/dist/Components/MapComponent/MapComponent.d.ts

@@ -0,0 +1,3 @@
+import { MapComponentProps } from "../../Types";
+declare function MapComponent(props: MapComponentProps): import("react/jsx-runtime").JSX.Element | null;
+export default MapComponent;

package/dist/Types/Components/MapComponent/MapComponentProps.d.ts

@@ -0,0 +1,9 @@
+import { HTMLAttributes } from "react";
+import SDKMap from "@neshan-maps-platform/mapbox-gl/dist/src/core/Map";
+import { MapBoxSKDOptionsModel } from "@neshan-maps-platform/mapbox-gl/dist/src/parameters/parameters";
+export type MapboxComponentInputOptions = Omit<MapBoxSKDOptionsModel, 'container'>;
+export interface MapComponentProps extends HTMLAttributes<HTMLDivElement> {
+    options: MapboxComponentInputOptions;
+    mapSetter?: (map: SDKMap) => void;
+    containerElementSetter?: (el: HTMLDivElement) => void;
+}

package/dist/Types/index.d.ts

@@ -0,0 +1 @@
+export type { MapComponentProps, MapboxComponentInputOptions } from './Components/MapComponent/MapComponentProps.ts';

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { default as MapComponent } from './Components/MapComponent/MapComponent.tsx';
+export declare enum MapTypes {
+    neshanVector = "neshanVector",
+    neshanVectorNight = "neshanVectorNight",
+    neshanRaster = "neshanRaster",
+    neshanRasterNight = "neshanRasterNight"
+}