From 794b4a49c70824836ac0fadf8008d0937059d16d Mon Sep 17 00:00:00 2001 From: db <77755322+diehbria@users.noreply.github.com> Date: Thu, 2 Mar 2023 11:28:05 -0800 Subject: [PATCH] feat(react-components): release useViewport hook (#631) --- README.md | 19 +++++--- docs/TimeSync.md | 53 ++-------------------- docs/useViewport.md | 62 ++++++++++++++++++++++++++ packages/react-components/src/index.ts | 1 + 4 files changed, 79 insertions(+), 56 deletions(-) create mode 100644 docs/useViewport.md diff --git a/README.md b/README.md index 1f9cb118e..b84f15040 100644 --- 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. IoT App Kit Demo -# 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 index a22a54240..4713ba8f7 100644 --- 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 ( -
- {JSON.stringify(viewport)} - -
- ) -} -``` - -This widget will now work as expected when wrapped in a `TimeSync`, as shown below: -``` - - - -``` - -if we now have multiple of the widgets, they will stay in sync and all display the same viewport: -``` - - - - - -``` - -### 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 ``. -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 new file mode 100644 index 000000000..cd8683a39 --- /dev/null +++ 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 ``. [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 ( +
+ {JSON.stringify(viewport)} + +
+ ) +} +``` + +This component can then be used as follows in junction with the `` component: + +``` +import { TimeSync } from '@iot-app-kit/react-components'; + + + + + +``` + +To demonstrate the synchronizing of viewports, we can utilize multiple of the newly created ``, which will all display the same viewport: + +``` +import { TimeSync } from '@iot-app-kit/react-components'; + + + + + + + +``` + +### 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 ``. +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 index 4880ab838..5f9e3eb2a 100644 --- 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';