feat(react-components): release useViewport hook (#631)

awslabs · Mar 2, 2023 · 794b4a4 · 794b4a4
1 parent c0e1f34
commit 794b4a4
Show file tree

Hide file tree

Showing 4 changed files with 79 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -5,11 +5,11 @@
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@iot-app-kit/core)](https://bundlephobia.com/package/@iot-app-kit/core)
 [![Downloads](https://img.shields.io/npm/dw/@iot-app-kit/core)](https://npmjs.org/package/@iot-app-kit/core)
 
-IoT Application Kit is a development library for creating web applications to visualize industrial data.
+IoT Application Kit is a development library for building Industrial IoT web based applications. 
 
 <img width="1170" alt="IoT App Kit Demo" src="https://user-images.githubusercontent.com/6397726/159107236-ea95e7ba-a89c-43e6-a34c-c5ea1dd37e8b.png">
 
-# Documentation table of contents
+# Table of contents
 
 [What is IoT Application Kit?](https://github.com/awslabs/iot-app-kit/tree/main/docs/WhatIs.md)
 
@@ -29,17 +29,24 @@ IoT Application Kit is a development library for creating web applications to vi
 * [Video Player](https://github.com/awslabs/iot-app-kit/blob/main/docs/VideoPlayer.md)
 * [Time Sync](https://github.com/awslabs/iot-app-kit/blob/main/docs/TimeSync.md)
 
+## React hooks (For building custom IoT App Kit components)
+
+* [useViewport](https://github.com/awslabs/iot-app-kit/blob/main/docs/useViewport.md)
+
+## Utilities
+
+* [Viewport manager](https://github.com/awslabs/iot-app-kit/tree/main/docs/ViewportManager.md) - Learn how to make your custom IoT App Kit components synchronize with viewport groups
+
 ## Data sources
 
-[AWS IoT SiteWise source](https://github.com/awslabs/iot-app-kit/tree/main/docs/AWSIoTSiteWiseSource.md) - Learn how to connect the IoT App Kit components with AWS IoT SiteWise
+* [AWS IoT SiteWise source](https://github.com/awslabs/iot-app-kit/tree/main/docs/AWSIoTSiteWiseSource.md) - Learn how to connect the IoT App Kit components with AWS IoT SiteWise
 
-[AWS IoT TwinMaker source](https://github.com/awslabs/iot-app-kit/blob/main/docs/AWSIoTTwinMakerSource.md) - Learn how to connect the IoT App Kit components with AWS IoT TwinMaker
+* [AWS IoT TwinMaker source](https://github.com/awslabs/iot-app-kit/blob/main/docs/AWSIoTTwinMakerSource.md) - Learn how to connect the IoT App Kit components with AWS IoT TwinMaker
 
 ## Data source features built into AWS IoT SiteWise and AWS IoT TwinMaker
 
 [Time series data features](https://github.com/awslabs/iot-app-kit/tree/main/docs/TimeSeriesDataFeatures.md) - Learn about what IoT App Kit does for you when managing time series data around caching, TTLs, buffering, etc.
 
-[Viewport manager](https://github.com/awslabs/iot-app-kit/tree/main/docs/ViewportManager.md) - Learn how to make your custom IoT App Kit components synchronize with viewport groups
 
 ## For IoT App Kit contributors
 
@@ -49,7 +56,7 @@ IoT Application Kit is a development library for creating web applications to vi
 
 ## Packages
 
-The IoT Application Kit mono-repo containing the following public packages:
+The IoT Application Kit containing the following public packages:
 
 ### @iot-app-kit/react-components
 `@iot-app-kit/react-components` exposes the core iot-app-kit web components as React components.

diff --git a/docs/TimeSync.md b/docs/TimeSync.md
@@ -77,57 +77,10 @@ Type: String
 
 Type: Object
 
-## Using viewport with `useViewport` hook
-When building custom components, it can be useful to have access to the current viewport, as well as the ability to update the viewport of the viewport group. `useViewport` provides this functionality. To brush up on react hooks, please refer to https://reactjs.org/docs/hooks-intro.html.
+# Utilizing the synchronized time across IoT App Kit components
 
-Below is an example of how to use the `useViewport` hook:
-
-```
-
-const MyWidget = () => {
-  const { viewport, update } = useViewport();
-  
-  return (
-    <div>
-      {JSON.stringify(viewport)}
-      <button onClick={() => {update({ viewport: '5m' )}}>
-        Show last 5 minutes
-      </button>
-    </div>
-  )
-}
-```
-
-This widget will now work as expected when wrapped in a `TimeSync`, as shown below:
-```
-<TimeSync>
-  <MyWidget />
-</TimeSync>
-```
-
-if we now have multiple of the widgets, they will stay in sync and all display the same viewport:
-```
-<TimeSync>
-  <MyWidget />
-  <MyWidget />
-  <MyWidget />
-</TimeSync>
-```
-
-### useViewport API Summary
-
-The `useViewport` takes no inputs, and returns an object containing the following fields:
-
-### viewport
-
-The current viewport for the viewport group subscribed to. Will be undefined if the hook is used outside of the context of a `<TimeSync />`.
-Will also be undefined if the associated viewport group has no associated viewport.
-
-Type: Object or undefined
-
-### `update: (viewport) => void`
-
-A function which you pass a viewport to set the current viewport group to. When called, the viewport group will update and all consumers of the viewport group will immediately receive the updated viewport provided.
+The synchronized time can be utilized and updated within components by utilizing the `useViewport` hook.
+[Learn more about the useViewport hook here](https://github.com/awslabs/iot-app-kit/tree/main/docs/useViewport.md).
 
 # Programmatically control your viewports (without react)
 

diff --git a/docs/useViewport.md b/docs/useViewport.md
@@ -0,0 +1,62 @@
+# useViewport react hook
+The `useViewport` react hook is a function which can be used within react components to utilize and update a shared time frame within a group of
+IoT App Kit widgets.
+
+`useViewport` should be used within the context of a `<TimeSync />`. [Learn more about Time Sync](https://github.com/awslabs/iot-app-kit/blob/main/docs/TimeSync.md)
+
+NOTE: This documentation assumes you are familiar with react and react-hooks. If you need to brush up, learn more at https://reactjs.org/docs/hooks-intro.html
+
+#  Example usage
+Below is an example of a simple component which displays the current viewport, and provides a button to set the viewport
+to the last 5 minutes:
+```
+const BasicComponent = () => {
+  const { viewport, setViewport } = useViewport();
+  return (
+    <div>
+      {JSON.stringify(viewport)}
+      <button onClick={() => setViewport({ duration: '5m' })}>Set viewport</button>
+    </div>
+  )
+}
+```
+
+This component can then be used as follows in junction with the `<TimeSync />` component:
+
+```
+import { TimeSync } from '@iot-app-kit/react-components';
+
+
+<TimeSync initialViewport={{ duration: '10m' }}>
+  <BasicComponent />
+</TimeSync>
+```
+
+To demonstrate the synchronizing of viewports, we can utilize multiple of the newly created `<BasicComponent />`, which will all display the same viewport:
+
+```
+import { TimeSync } from '@iot-app-kit/react-components';
+
+
+<TimeSync initialViewport={{ duration: '10m' }}>
+  <BasicComponent />
+  <BasicComponent />
+  <BasicComponent />
+</TimeSync>
+```
+
+### API Summary
+
+The `useViewport` takes no inputs, and returns an object containing the following fields:
+
+### `viewport`
+
+The current viewport for the viewport group subscribed to. Will be undefined if the hook is used outside of the context of a `<TimeSync />`.
+Will also be undefined if the associated viewport group has no associated viewport.
+
+Type: Object or undefined
+
+### `setViewport: (viewport) => void`
+
+A function which you pass a viewport to set the current viewport group to. When called, the viewport group will update and all consumers of the viewport group will immediately receive the updated viewport provided.
+
diff --git a/packages/react-components/src/index.ts b/packages/react-components/src/index.ts
@@ -10,4 +10,5 @@ export {
   ResourceExplorer,
   Kpi,
 } from './components';
+export { useViewport } from './hooks/useViewport';
 export { TimeSync } from './components/time-sync';