diff --git a/docs/Table.md b/docs/Table.md index 1b46afa70..187136304 100644 --- a/docs/Table.md +++ b/docs/Table.md @@ -1,7 +1,7 @@ # Table -The table component allows for a compact form to view one or more data streams from one or more time series data sources. +The table component provides a compact form for viewing one or more data streams from one or more time series data sources. -To view and interact with a table example, visit [Table](https://synchrocharts.com/#/Components/Table) in the Synchro Charts documentation. +To migrate from previous API, check [Migrate from previous API](#migrate-from-previous-api) ## Examples @@ -19,20 +19,45 @@ const { query } = initialize({ iotsitewiseClient }); ``` @@ -72,20 +99,45 @@ const { query } = initialize({ iotsitewiseClient }); ``` ## Properties -The table component contains the following properties that you can customize. +The table component contains the following customizable properties: -### `tableColumns` +Note: Since the table component built over the `@awsui/components-react` table component, please refer to [AWS-UI/table](https://github.com/aws/awsui-documentation/blob/main/components/table.md) about most of the available properties. Differences between AWSUI/Table and this Table component are listed below. -Specifies the row and column structure for the table, provides a mechanism to map the time series data queried for, into the cells of your choice -Type: Array +### `items` +Specifies the data displayed in rows. Each item contains the data for one row. The display of a row is handled by the cell property of each column definition in the columnDefinitions property. -Each table column contains the following properties +Type: Array of [Item](#item) objects -`header` +Required: Yes -The text to be displays as the column header, the first row of the table +#### `item` +An item maps its own properties to dataStreams. A special property name [$cellRef](#cellref) can be used to refer to a datastream. +Other properties of an item will remain unchanged. +```typescript jsx +// If we have defined items like below +const items: Item[] = [{ + rpm: { + $cellRef: { + id: 'dataStream-1', + resolution: 0 + } + }, + wind_speed: { + $cellRef: { + id: 'dataStream-2', + resolution: 0 + } + }, + other: { static_value: 42 } +}] + +// Table will receive the actual value of each $cellRef: +[{ + rpm: 15, + wind_speed: 30, + other: { static_value: 42 } +}] +``` -Type: string -`rows` +#### `$cellRef` +$cellRef is a special keyword in Item. We use it to find the according dataStream. For the above example, +the item has two properties. Both of them are using `$cellRef` to map properties to data stream. + +Type: Object +- `id` + A string representing the id of a time series data stream, which you can get by utilizing the time series data source of choices toId helper, for example, with AWS IoT SiteWise, you can refer to an id with the following code: + - Type: String + - Required: Yes +```typescript jsx +import { toId } from '@iot-app-kit/source-sitewise'; +const item = [ + { + wind_speed: { + $cellRef: { + id: toId({ assetId: 'engine-2', propertyId: 'temperature' }), + resolution: 0 + } + }, + } +] +``` +- `resolution` +The resolution, in milliseconds, at which the data should be aggregated. + - Type: Number + - Required: Yes + +Required: No -Array of content of each cell within the respective column. Rows are defined in order, the first row item corresponds to the first row on the table that doesn't represent column headers. +### `columnDefinitions` -Type: string or undefined +Configures various column properties. The properties mirror [columnDefinitions](https://github.com/aws/awsui-documentation/blob/main/components/table.md#columnDefinitions) +with the following changes: -Each item must be one of the following: +- `key`: string - Determines how each column looks up data from an `Item`. +- (Optional)`cell` (item) => React.ReactNode* - For overriding the default [cell](link-to-default-cell-function) function. +- (Optional)`formatter` (data:Primitive) => Primitive - Determines the display of a cell's content for formatting the data. -* A string representing the id of a time series data stream, which you can get by utilizing the time series data source of choices `toId` helper, for example, with AWS IoT SiteWise, you can refer to an id with the following code: -``` -import { toId } from '@iot-app-kit/source-sitewise'; -const column = { - header: 'some-header', - rows: [toId({ assetId: 'my-asset', propertyId: 'property-id' })] -} -``` +Type: Array of Object -* `undefined`, which will cause the corresponding table cell to be empty. +Required: Yes -### `viewport` +### `sorting` -Specifies a time range. The table only supports showing the latest value. If the `viewport` is configured to visualize historical data, the table displays the disabled state. +Specifies sorting configuration. If you want to use sorting with default settings, provide an empty object. This feature is only applicable for the table component. -Type: Object +- `defaultState` : Object - initial sorting state on the first render. This is an object with two properties: + - `sortingColumn` [TableProps.ColumnDefinition]: currently sorted column. + - `isDescending` [boolean, optional]: direction of sorting. + +Type: Object + +Required: No +### `propertyFiltering` + +Specifies property filtering configuration. + +- `filteringProperties` : Array - Array of properties by which the data set is going to be filtered. Individual items have following properties: + - key [string]: The identifier of this property. Refer to a property name in type T of the data item to enable built-in filtering. + - groupValuesLabel [string]: Localized string to display for the 'Values' group label for a specific property. For example: EC2 instance values. + - propertyLabel [string]: A human-readable string for the property. + - (Optional) operators [ReadonlyArray, optional]: A list of all operators supported by this property. Equals operator should always be supported, even if you omit it in the list. + - (Optional) group [string, optional]: Optional identifier of a custom group that this filtering option is assigned to. Use to create additional groups below the default one. Make sure to also define labels for the group in the customGroupsText property. Notice that only one level of options nesting is supported. + - (Optional)`filteringFunction`: (item: TableItem, query: Query) => boolean; - Custom function to filter items. The default value is a function that takes values under the FilteringProperty['key'] in individual items, and matches them against current filteringText. + - (Optional)`defaultQuery`: Query - Initial query on the first render. + - (Optional)`empty` - React.ReactNode* - Content to display in the table/cards empty slot when there are no items initially provided. + - (Optional)`noMatch` - React.ReactNode* - Content to display in the table/cards empty slot when filtering returns no matched items. + +Type: Object + +Required: No + +### `viewport` + +Specifies a time range. The table only supports showing the latest value. If the `viewport` is configured to visualize historical data, the table displays the disabled state. + +Type: Object A viewport contains the following fields: @@ -173,34 +306,169 @@ A viewport contains the following fields: Type: String +Required: Yes + +### `annotations` -### `annotations` +Defines thresholds for the table. To view and interact with an annotation example, see [Annotation](https://synchrocharts.com/#/Features/Annotation) in the Synchro Charts documentation. For more information about the `annotations` API, see [Properties](https://synchrocharts.com/#/API/Properties) in the Synchro Charts documentation. -(Optional) Defines thresholds for the table. To view and interact with an annotation example, see [Annotation](https://synchrocharts.com/#/Features/Annotation) in the Synchro Charts documentation. For more information about the `annotations` API, see [Properties](https://synchrocharts.com/#/API/Properties) in the Synchro Charts documentation. Type: Object +Required: No + ### `queries` -Selects what data to visualize. Learn more about queries, see [Core](https://github.com/awslabs/iot-app-kit/tree/main/docs/Core.md). -Type: Array +Selects what data to visualize. Learn more about queries, see [Core](https://github.com/awslabs/iot-app-kit/tree/main/docs/Core.md). +Type: Array + +Required: Yes ### `styleSettings` -(Optional) A map of `refId` to style settings for the table. Learn more about reference IDs, see [Core](https://github.com/awslabs/iot-app-kit/tree/main/docs/Core.md). +A map of `refId` to style settings for the table. Learn more about reference IDs, see [Core](https://github.com/awslabs/iot-app-kit/tree/main/docs/Core.md). The table chart provides the following style settings that you can customize: * `name` string - (Optional) Specify a name to replace the name of the data set given by its source. + (Optional) Specify a name to replace the name of the data set given by its source. * `unit` string - (Optional) The unit given to the data (for example, `"m/s"` and `"count"`). + (Optional) The unit given to the data (for example, `"m/s"` and `"count"`). * `detailedName` string - (Optional) A detailed name that is presented in the tooltip. + (Optional) A detailed name that is presented in the tooltip. + +Required: No -### `widgetId` string +### `widgetId` -(Optional) The ID of the widget. A widget is a visualization that you use the table component to create. +The ID of the widget. A widget is a visualization that you use the table component to create. + +Type: String + +Required: No ----- +## Migrate from previous API + +Property `tableColumns` has been replaced by two new APIs, `items` and `columnDefinitions`, where `items` defines objects of each row, +and `columnDefinitions` defines how table maps `items` to columns. For more details, check [Properties](#properties). + +```typescript jsx +// previous +import { initialize, toId } from '@iot-app-kit/source-iotsitewise'; +import { Table } from '@iot-app-kit/react-components'; +const { IoTSiteWiseClient } = require('@aws-sdk/client-iotsitewise'); +const iotsitewiseClient = new IoTSiteWiseClient({ region: "REGION" }); + +const { query } = initialize({ iotsitewiseClient }); +
+``` +```typescript jsx +// now +import { initialize, toId } from '@iot-app-kit/source-iotsitewise'; +import { Table } from '@iot-app-kit/react-components'; +const { IoTSiteWiseClient } = require('@aws-sdk/client-iotsitewise'); +const iotsitewiseClient = new IoTSiteWiseClient({ region: "REGION" }); + +const { query } = initialize({ iotsitewiseClient }); +
+``` + + +***Note: Due to the difference between Stencil and React, providing JSX object from Web Component to React is not supported. Try to use string or number instead of ReactNode.*** -***NOTE: Table currently only supports raw data*** diff --git a/packages/table/README.md b/packages/table/README.md new file mode 100644 index 000000000..5674e9ee1 --- /dev/null +++ b/packages/table/README.md @@ -0,0 +1,32 @@ +# Table + +`@iot-app-kit/table` is a table component built over `@awsui/components-react` components providing client-side sorting, property filtering. + +Presents data in a two-dimensional table format, arranged in columns and rows in a rectangular form. + +## Development + +### Local Setup + +#### Install +In the root folder of `iot-app-kit`, run +```bash +lerna bootstrap +``` +to install dependencies. + +#### Build +In the package folder, run +```bash +yarn build +``` + +### Jest + +Jest tests are set up to run with `yarn test`. + + +### TypeScript + +`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs. +