chore: add assistant documentation, overview, kpi, gauge, chart, tabl…

…e, chatbot

packages/doc-site/.storybook/preview.js

@@ -16,6 +16,7 @@ const preview = {
           'Overview',
           'Data sources',
           'Components',
+          'Assistant',
           'Core',
           'React hooks',
         ],

packages/doc-site/common/cards.jsx

@@ -156,3 +156,92 @@ export const IntroductionSelectedDemosCards = () => {
       />
   );
 }
+
+export const AssistantComponentsCards = () => {
+  return (
+    <CloudscapeCards
+      ariaLabels={{
+        itemSelectionLabel: (e, t) => `select ${t.name}`,
+        selectionGroupLabel: "Item selection"
+      }}
+      cardDefinition={{
+        header: item => item.title,
+        sections: [
+          {
+            id: "name",
+            content: item => (
+              <CloudscapeLink href={item.link} >
+                {item.image ? <img
+                  style={{ height: "150px" }}
+                  src={item.image}
+                  alt="placeholder"
+                /> : null
+                }
+              </CloudscapeLink>
+            )
+          },
+          {
+            id: "description",
+            content: item => (
+              <>
+                {item.description}&nbsp;
+                <CloudscapeLink
+                  href={item.link}
+                >Learn more</CloudscapeLink>
+              </>
+            )
+          }
+        ]
+      }}
+      cardsPerRow={[
+        { cards: 1 },
+        { minWidth: 500, cards: 3 }
+      ]}
+      items={[
+        {
+          name: "Dashboard",
+          image: "/iot-app-kit/assets/DashboardPreview.jpg",
+          title: "Dashboard",
+          link: "/iot-app-kit/?path=/docs/assistant-components-dashboard---docs",
+          description: "Dashboard component allows you to easily create, modify, view, and organize widgets for a tailored experience to monitor your IoT data."
+        },
+        {
+          name: "KPI",
+          image: "/iot-app-kit/assets/KPIPreview.png",
+          title: "KPI",
+          link: "/iot-app-kit/?path=/docs/assistant-components-kpi--docs",
+          description: "The Key Performance Indicator (KPI) component provides a compact representation when you need an overview of your asset properties. This overview provides critical insights into the overall performance of your devices, equipment, and processes."
+        },
+        {
+          name: "Gauge",
+          image: "/iot-app-kit/assets/GaugePreview.png",
+          title: "Gauge",
+          link: "/iot-app-kit/?path=/docs/assistant-components-gauge--docs",
+          description: "The Gauge component provides a compact representation of an overview of your asset properties. Visualize critical insights into the overall performance of your devices, equipment, or processes."
+        },
+        {
+          name: "Chart",
+          image: "/iot-app-kit/assets/ChartPreview.png",
+          title: "Chart",
+          link: "/iot-app-kit/?path=/docs/assistant-components-chart--docs",
+          description: "The chart component is a way to visualize and navigate time series data from one or more data sources.Chart supports a rich set of features including trend cursors, thresholds, high performance live-streaming and smooth syncing across other IoT App Kit components."
+        },
+        {
+          name: "Chatbot",
+          image: "/iot-app-kit/assets/ChatbotPreview.png",
+          title: "Chatbot",
+          link: "/iot-app-kit/?path=/docs/assistant-components-chatbot--docs",
+          description: "The Assistant Chatbot component provides an interactive chat interface for conversational dive-deeps in IoT applications."
+        },
+        {
+          name: "Table",
+          title: "Table",
+          link: "/iot-app-kit/?path=/docs/assistant-components-table--docs",
+          description: "Presents data in a two-dimensional table format, arranged in columns and rows in a rectangular form."
+        },
+      ]}
+      loadingText="Loading resources"
+      empty={`No resources`}
+      />
+  );
+}

packages/doc-site/stories/assistant/Overview.mdx

@@ -0,0 +1,26 @@
+import { Meta, IconGallery, IconItem } from '@storybook/blocks';
+import { AssistantComponentsCards } from "../../common/cards";
+
+<Meta title="Assistant/Overview" />
+
+# AWS IoT SiteWise Assistant
+
+AWS IoT SiteWise Assistant, a generative AI-powered assistant in AWS IoT SiteWise that allows industrial users to gain insights, 
+solve problems, and take actions from their operational data and other data sources intuitively using natural language queries.
+
+## Get Started
+Please check our user guide about how to setup and enable the AWS IoT Sitewise assistant: [https://docs.aws.amazon.com/iot-sitewise/latest/userguide/assistant-get-started.html](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/assistant-get-started.html)
+
+## Features
+
+For more details, please read [Transforming industrial decision making with AWS IoT SiteWise Assistant](https://aws.amazon.com/blogs/industries/transforming-industrial-decision-making-with-aws-iot-sitewise-assistant/)
+
+- Summarization: Cut through the noise
+- Deep-dive: Uncover Insights with Q&A
+- Analysis: Accelerating Decision-Making
+- Seamless Integration and Accessibility
+- Security and Privacy
+
+## AI-aware app kit components 
+
+<AssistantComponentsCards />

packages/doc-site/stories/assistant/components/Chart.mdx

@@ -0,0 +1,86 @@
+import { Canvas, Meta, Story, Source, Markdown, IconItem } from '@storybook/blocks';
+
+import * as ChartStories from './Chart.stories';
+import { Icon } from '@cloudscape-design/components';
+
+<Meta of={ChartStories} />
+
+# Chart
+
+The chart component is a way to visualize and navigate time series data from one or more [data sources](/docs/core-datasources--docs).
+
+Chart supports a rich set of features including trend cursors, thresholds, high performance live-streaming and smooth syncing across other IoT App Kit components.
+
+This component can be used to draw both line (step-up, step-down, step-mid etc.) and scatter charts.
+
+## Assistant
+##### (object, optional)
+This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](https://aws.amazon.com/iot-sitewise/features/). 
+
+<Markdown>
+{`
+| Name         | Type         | Default        | Description         |
+| ------------ | ------------ | -------------- | ------------------- |
+| \`client\` | object, required | - | Specifies an instantiated assistant client \`IoTSitewiseAssistantClient\`, the assistant client is responsible for interfacing with the Assistant API.|
+| \`conversationId\` | string, required | - | Defines a conversation ID to be used as unique identifier for conversations with the assistant, the conversation ID can be the same for multiple components or unique, depending on use cases. |
+| \`componentId\` | string, required | - | Each component **must define an unique ID** which will be used by the assistant to manage state and assistant results. |
+| \`target\` | object, required | - | Defines the target for the assistant actions, the target options are \`dashboard\` and \`widget\`. For target \`dashboard\` all assistant results will be broadcasted to the Dashboard component, for target \`widget\` the assistant results will be display next to the component. |
+| \`enabled\` | boolean, optional | true | Allows to disable or enable the assistant at the component level. |
+| \`onAction\` | event, optional | - | Allows to pass a callback function to listen for any assistant action within the component. |
+`}
+</Markdown>
+
+<Canvas sourceState="none" story={{ height : '560px' }} of={ChartStories.Assistant} />
+<Source dark="true" code={`import React, { useEffect } from 'react';
+import { Chart, useAssistant } from '@iot-app-kit/react-components';
+import { IoTSitewiseAssistantClient } from '@iot-app-kit/core-util';
+
+const componentId = 'a1cdf292-8a1c-4809-9c9a-3485d88c447b';
+
+export const KPIWithAssistant = () => {
+  const client = new IoTSitewiseAssistantClient({
+    iotSiteWiseClient
+  });
+
+  const { generateSummary } = useAssistant({
+    assistantClient: client,
+  });
+
+  return (
+    <div style={{ height: '560px', width: '900px' }}>
+      Please, select an item in the table below: 
+      <Chart
+        {...{
+          ...props,
+          legend: {
+            visible: true,
+            enabled: true,
+            position: 'bottom',
+            visibleContent: { maxValue: true },
+            height: '110px',
+          },
+          size: { height: 450, width: 500 },
+        }}
+        id={componentId}
+        assistant={{
+          client,
+          enabled: true,
+          componentId,
+          conversationId: 'mockConversationId',
+          target: 'widget',
+          onAction:(event) => {
+            if (event.type === 'selection') {              
+              generateSummary({
+                componentId,
+                conversationId: crypto.randomUUID(),
+                target: 'widget',
+                utterance:
+                  'generate a summary and return the response in markdown format.',
+              });
+            }
+          }
+        }}
+      />
+    </div>
+  );
+};`} />

packages/doc-site/stories/assistant/components/Chart.stories.tsx

@@ -0,0 +1,77 @@
+import { Chart, useAssistant } from '@iot-app-kit/react-components';
+import {
+  mockSinWaveData,
+} from '@iot-app-kit/testing-util';
+import { IoTSitewiseAssistantClient } from '@iot-app-kit/core-util';
+import { type Meta, type StoryObj } from '@storybook/react';
+import { MockInvokeAssistant } from '../../mockAssistantAPI';
+
+// More on how to set up stories at: https://storybook.js.org/docs/7.0/react/writing-stories/introduction
+const meta: Meta<typeof Chart> = {
+  title: 'Assistant/Components/Chart',
+  component: Chart,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Chart>;
+
+const componentId1 = 'a1cdf292-8a1c-4809-9c9a-3485d88c447b';
+const componentId2 = 'a2cdf292-8a1c-4809-9c9a-3485d88c447b';
+const client = new IoTSitewiseAssistantClient({
+  iotSiteWiseClient: {
+    invokeAssistant: MockInvokeAssistant,
+  },
+  defaultContext: '',
+});
+
+export const Assistant: Story = {
+  render: (props) => {
+    const { generateSummary, clearAll } = useAssistant({
+      assistantClient: client,
+    });
+
+    return (
+      <div style={{ height: '560px', width: '900px' }}>
+        Please, select an item in the table below: 
+        <Chart
+          {...{
+            ...props,
+            legend: {
+              visible: true,
+              enabled: true,
+              position: 'bottom',
+              visibleContent: { maxValue: true },
+              height: '110px',
+            },
+            size: { height: 450, width: 500 },
+          }}
+          id={componentId1}
+          assistant={{
+            client,
+            enabled: true,
+            componentId: componentId1,
+            conversationId: 'mockConversationId',
+            target: 'widget',
+            onAction:(event) => {
+              if (event.type === 'selection') {   
+                clearAll();           
+                generateSummary({
+                  componentId: componentId1,
+                  conversationId: crypto.randomUUID(),
+                  target: 'widget',
+                  utterance:
+                    'generate a summary and return the response in markdown format.',
+                });
+              }
+            }
+          }}
+        />
+      </div>
+    )
+  },
+  args: {
+    queries: [mockSinWaveData()],
+    viewport: { duration: '30s' },
+  },
+};

packages/doc-site/stories/assistant/components/Gauge.mdx

@@ -0,0 +1,73 @@
+import { Canvas, Meta, Story, Source, Markdown } from '@storybook/blocks';
+import * as GaugeStories from './Gauge.stories';
+
+# Gauge
+
+The Gauge component provides a compact representation of an overview of your asset properties. 
+Visualize critical insights into the overall performance of your devices, equipment, or processes. 
+Interact with IoT data from one or more data sources with Gauge.
+
+<Meta title="Assistant/Components/Gauge" />
+
+## Assistant
+##### (object, optional)
+This specifies settings to enable the IoT Sitewise AI assistant within the component. Please refer to the [AWS documentation for more details about IoT Sitewise AI assistant](https://aws.amazon.com/iot-sitewise/features/). 
+
+<Markdown>
+{`
+| Name         | Type         | Default        | Description         |
+| ------------ | ------------ | -------------- | ------------------- |
+| \`client\` | object, required | - | Specifies an instantiated assistant client \`IoTSitewiseAssistantClient\`, the assistant client is responsible for interfacing with the Assistant API.|
+| \`conversationId\` | string, required | - | Defines a conversation ID to be used as unique identifier for conversations with the assistant, the conversation ID can be the same for multiple components or unique, depending on use cases. |
+| \`componentId\` | string, required | - | Each component **must define an unique ID** which will be used by the assistant to manage state and assistant results. |
+| \`target\` | object, required | - | Defines the target for the assistant actions, the target options are \`dashboard\` and \`widget\`. For target \`dashboard\` all assistant results will be broadcasted to the Dashboard component, for target \`widget\` the assistant results will be display next to the component. |
+| \`enabled\` | boolean, optional | true | Allows to disable or enable the assistant at the component level. |
+| \`onAction\` | event, optional | - | Allows to pass a callback function to listen for any assistant action within the component. |
+`}
+</Markdown>
+
+<Source dark="true" code={`import React, { useEffect } from 'react';
+import { Gauge, useAssistant } from '@iot-app-kit/react-components';
+import { IoTSitewiseAssistantClient } from '@iot-app-kit/core-util';
+
+export const GaugeWithAssistant = () => {
+  const client = new IoTSitewiseAssistantClient({
+    iotSiteWiseClient
+  });
+
+  const { generateSummary } = useAssistant({
+    assistantClient: client,
+  });
+
+  useEffect(() => {
+    generateSummary({
+      componentId: 'my-kpi-component-id',
+      conversationId: 'my-conversation-id',
+      target: 'widget',
+      utterance: 'generate a summary and return the response in markdown format.',
+    });
+  }, []);
+
+  return (
+    <Gauge
+      query: sitewise,
+      settings: {
+        gaugeThickness: 30,
+        showUnit: true,
+        showName: false,
+        fontSize: 40,
+        labelFontSize: 16,
+        unitFontSize: 16,
+        yMin: 0,
+        yMax: 100,
+      }
+      assistant={{
+        client,
+        enabled: true,
+        componentId: 'my-kpi-component-id',
+        conversationId: 'my-conversation-id',
+        target: 'widget',
+      }}
+    />
+  );
+};`} />