@hopara/react 0.1.119 → 0.2.0

package/README.md

@@ -0,0 +1,187 @@
+# @hopara/react
+This package provides the react component to add [Hopara](https://hopara.io) visualizations to your project.
+
+## Requirements
+The [Hopara](https://hopara.io) component is built on top of [React](https://react.dev/) and [React-Redux](https://react-redux.js.org/). It requires the following depencies:
+
+- react >= 18.2
+- react-redux >= 8.0
+- redux >= 4.2
+
+## Installing
+### Package manager
+Using npm:
+```shell
+$ npm install --save @hopara/react
+```
+
+Using yarn:
+```shell
+$ yarn add @hopara/react
+```
+
+Once installed, you can import the library using import or require approach:
+```jsx
+import {Hopara} from '@hopara/react';
+```
+
+## Authentication
+The component requires a valid `accessToken`. Use the `Auth API` to fetch it, as explained in our [documentation website](https://docs.hopara.app/docs/external-integration/authentication-integration.html)
+
+## Examples
+### Basic usage
+```jsx
+<div className="HoparaEmbedded">
+  <Hopara
+    app="your-app-id"
+    accessToken="your-access-token"
+  />
+</div>
+```
+
+## Module API
+You can further customize the integration by using the component props:
+
+```typescript
+type HoparaProps = {
+  // The app id
+  app: string
+
+  // The accessToken fetched from the auth API
+  accessToken: string
+
+  // Overwrites the data at render time
+  dataLoaders: DataLoader[] | undefined
+
+  // Provides a custom ways to update data
+  dataUpdaters: DataUpdaters[] | undefined
+
+  // The initial position to load the visualization
+  initialPosition: InitialPosition | undefined
+
+  // The initial row (e.g. asset) to load the visualization
+  initialRow: InitialRow | undefined
+}
+```
+
+### Data Loader
+By default Hopara will load the same visualization and data as seen as in hopara.app. You can use the data loader prop to provide a custom way to load the data.
+
+```typescript
+type DataLoader = {
+  // query name
+  name: string
+
+  // data source name
+  source: string
+
+  // callback to be used on data load
+  loader: (filterSet: {limit: number, offset:number, filters: any[]}) => Promise<Record<string, any>[]>
+}
+```
+
+
+#### Example
+
+```jsx
+const dataLoaders = [{
+  name: 'queryName',
+  source: 'dataSourceName',
+  loader: () => {
+    return [
+      {
+        id: 1,
+        name: 'Eiffel Tower',
+        country: 'France',
+        longitude: 48.85845461500544,
+        latitude: 2.294467845588995
+      },
+      {
+        id: 2,
+        name: 'Liberty Statue',
+        country: 'USA',
+        longitude: 40.68815550804761,
+        latitude: -74.02620077137483
+      },
+      {
+        id: 3,
+        name: 'Great Wall of China',
+        country: 'China',
+        longitude: 40.43211592595951,
+        latitude: 116.57040708445938,
+      }
+    ]
+  }
+}]
+...
+<div className="HoparaEmbedded">
+  <Hopara
+    app="your-app-id"
+    accessToken="your-access-token"
+    dataLoaders={dataLoaders}
+  />
+```
+
+### Data Updater
+By default Hopara will update the visualization in the same database configured in hopara.app. You can use the data updater prop to provide a custom way to update the data.
+
+The data updater is called when placing objetcs in a visualization and when resizing images.
+
+```typescript
+type DataUpdater = {
+  // query name
+  name: string
+
+  // data source name
+  source: string
+
+  // callback to be used on data update
+  updater: (updatedRow: Record<string, any>, originalRow: Record<string, any>, diff: Partial<Record<string, any>>) => Promise<void>
+}
+```
+
+```jsx
+const dataUpdaters = [{
+  name: 'queryName',
+  source: 'dataSourceName',
+  updater: (newRow) => {
+    const rowIndex = dataInMemory.findIndex((row) => row.id === newRow.id)
+    dataInMemory[rowIndex] = newRow
+  }
+}]
+
+...
+
+<div className="HoparaEmbedded">
+  <Hopara
+    app="your-app-id"
+    accessToken="your-access-token"
+    dataUpdaters={dataUpdaters}
+  />
+</div>
+```
+
+### Initial Position
+The initial position prop overrides the initial position of the visualization.
+
+```typescript
+type InitialPosition = {
+  latitude: number | undefined
+  longitude: number | undefined
+  x: number | undefined
+  y: number | undefined
+  z: number | undefined
+  zoom: number | undefined
+  bearing: number | undefined
+}
+```
+
+### Initial Row
+The initial row prop centers the visualization around a specific row (e.g. asset, facility).
+
+```typescript
+type InitialRow = {
+  entityId: string
+  rowId: string
+}
+```