feat(v-quicksight-generative-qna): add new component v-quicksight-generative-qna

Author: d-koppenhagen

docs/.vitepress/config.mts

@@ -27,7 +27,8 @@ export default defineConfig({
           { text: 'v-quicksight-dashboard', link: '/v-quicksight-dashboard' },
           { text: 'v-quicksight-visual', link: '/v-quicksight-visual' },
           { text: 'v-quicksight-console', link: '/v-quicksight-console' },
-          { text: 'v-quicksight-search', link: '/v-quicksight-search' }
+          { text: 'v-quicksight-search', link: '/v-quicksight-search' },
+          { text: 'v-quicksight-generative-qna', link: '/v-quicksight-generative-qna' },
         ]
       }
     ],

docs/v-quicksight-generative-qna.md

@@ -0,0 +1,58 @@
+# v-quicksight-generative-qna
+
+<script setup>
+import GenerativeQnAOne from "@demos/GenerativeQnAOne.vue"
+</script>
+
+<ClientOnly>
+  <!-- <GenerativeQnAOne /> -->
+</ClientOnly>
+
+::: code-group
+
+<<< ../src/demos/GenerativeQnAOne.vue
+
+:::
+
+## Props
+
+All of the following properties are passed with their default values from the `amazon-quicksight-embedding-sdk` one by one:
+
+- [Common `ContentOptions` for All Embedding Experiences
+](https://github.com/awslabs/amazon-quicksight-embedding-sdk#common-properties-of-contentoptions-for-all-embedding-experiences)
+- [Common `FrameOptions` for All Embedding Experiences
+](https://github.com/awslabs/amazon-quicksight-embedding-sdk#common-properties-of-frameoptions-for-all-embedding-experiences)
+- [Visual Embedding ContentOptions](https://github.com/awslabs/amazon-quicksight-embedding-sdk#contentoptions-4)
+- [Visual Embedding FrameOptions](https://github.com/awslabs/amazon-quicksight-embedding-sdk#frameoptions-4)
+
+**Additional and important properties**
+
+| **property** | **type**     | **required** | **default**                                            | **description**                                                                                                |
+|--------------|--------------|--------------|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| `container`  | `string`     | no           | The default container created by the component itself. | The container where the `iframe` for embedding is created.                                                     |
+| `id`         | `string`     | no           | `v-quicksight-visual-${nanoid(6)}`                     | The `id` for the created `iframe` container element (parent)                                                   |
+| `question`   | `string`     | no           | `undefined`                                            | The question to ask or a nullish value if the search should be closed. This property is watched for changes.   |
+
+## Events
+
+**`change`**
+
+Emits a generic event containing the changes as well as optionally the meta data of the frame.
+
+```ts
+type VQuicksightChange = {
+  changeEvent: SimpleChangeEvent;
+  metadata?: ExperienceFrameMetadata;
+}
+```
+
+**`message`**
+
+Emits a generic event containing the message as well as optionally the meta data of the frame.
+
+```ts
+type VQuicksightMessage = {
+  messageEvent: SimpleMessageEvent;
+  experienceMetadata?: ExperienceFrameMetadata;
+}
+```

src/components/VQuicksightGenerativeQnA.vue

@@ -0,0 +1,112 @@
+<script setup lang="ts">
+import type { VQuicksightGenerativeQnAContentOptions, VQuicksightFrameOptions } from '../types'
+import type {
+  GenerativeQnAContentOptions,
+  GenerativeQnAExperience,
+  EmbeddingContext,
+  ExperienceFrameMetadata,
+  FrameOptions,
+  EmbeddingEvents
+} from 'amazon-quicksight-embedding-sdk'
+import { nanoid } from 'nanoid'
+import type { Ref } from 'vue'
+import { computed, inject, ref, watch } from 'vue'
+import { EmbeddingContextInjectionKey } from '../symbols'
+
+const props = withDefaults(
+  defineProps<
+    VQuicksightFrameOptions &
+      VQuicksightGenerativeQnAContentOptions & {
+        container?: string | HTMLElement // override from FrameOptions and make it optional
+        id?: string
+        question?: string
+      }
+  >(),
+  {
+    width: '100%',
+    height: '100%',
+    withIframePlaceholder: false,
+    showTopicName: true,
+    showPinboard: true,
+    allowTopicSelection: true,
+    allowFullscreen: true
+  }
+)
+
+const emit = defineEmits<{
+  (e: 'change', data: { changeEvent: EmbeddingEvents; metadata?: ExperienceFrameMetadata }): void
+  (
+    e: 'message',
+    data: { messageEvent: EmbeddingEvents; experienceMetadata?: ExperienceFrameMetadata }
+  ): void
+}>()
+
+const embeddingContext = inject<Ref<EmbeddingContext>>(EmbeddingContextInjectionKey)
+
+const qnaFrame = ref<GenerativeQnAExperience>()
+
+const containerId = computed(() => props.id || `v-quicksight-generative-qna-${nanoid(6)}`)
+const frameOptions = computed<FrameOptions>(() => {
+  return {
+    url: props.url,
+    container: props.container || `#${containerId.value}`,
+    height: props.height,
+    width: props.width,
+    className: props.className,
+    withIframePlaceholder: props.withIframePlaceholder,
+    onChange: (changeEvent, metadata) => {
+      emit('change', { changeEvent, metadata })
+    }
+  }
+})
+const contentOptions = computed<GenerativeQnAContentOptions>(() => {
+  return {
+    showTopicName: props.showTopicName,
+    showPinboard: props.showPinboard,
+    allowTopicSelection: props.allowTopicSelection,
+    allowFullscreen: props.allowFullscreen,
+    searchPlaceholderText: props.searchPlaceholderText,
+    panelOptions: props.panelOptions,
+    themeOptions: props.themeOptions,
+    onMessage: async (messageEvent, experienceMetadata) => {
+      emit('message', { messageEvent, experienceMetadata })
+    }
+  }
+})
+
+async function embedQnA(ctx: EmbeddingContext) {
+  qnaFrame.value = await ctx.embedGenerativeQnA(frameOptions.value, contentOptions.value)
+}
+
+async function setQuestion(frame: GenerativeQnAExperience, question?: string) {
+  if (question) {
+    return await frame.setQuestion(question)
+  } else {
+    return await frame.close()
+  }
+}
+
+watch(
+  () => embeddingContext?.value,
+  (newValue, oldValue) => {
+    if (newValue && !oldValue) {
+      embedQnA(newValue)
+    }
+  },
+  { immediate: true }
+)
+
+watch(
+  () => props.question,
+  (newValue) => {
+    if (qnaFrame.value) {
+      setQuestion(qnaFrame.value, newValue)
+    }
+  },
+  { immediate: true }
+)
+</script>
+
+<template>
+  <div class="v-quicksight-generative-qna" :id="containerId"></div>
+</template>

src/components/__tests__/VQuicksightGenerativeQnA.spec.ts

@@ -0,0 +1,107 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+
+import { EmbeddingContextInjectionKey } from '../../symbols'
+import VQuicksightGenerativeQnA from '../VQuicksightGenerativeQnA.vue'
+
+const frameOptions = {
+  container: '#custom-el',
+  width: '300px',
+  height: '700px',
+  withIframePlaceholder: true,
+  className: 'my-custom-class'
+}
+const contentOptions = {
+  showTopicName: false,
+  showPinboard: false,
+  allowTopicSelection: false,
+  allowFullscreen: false,
+  searchPlaceholderText: ''
+}
+
+describe('VQuicksightGenerativeQnA', () => {
+  function setupComponent(props: Record<string, any> = {}) {
+    const qnaFrame = {
+      close: vi.fn().mockResolvedValue({ success: true }),
+      setQuestion: vi.fn().mockResolvedValue({ success: true })
+    }
+    const embeddingContext = {
+      embedGenerativeQnA: vi.fn().mockResolvedValue(qnaFrame)
+    }
+
+    const component = mount(VQuicksightGenerativeQnA, {
+      global: {
+        provide: {
+          [EmbeddingContextInjectionKey]: ref(embeddingContext)
+        }
+      },
+      props: {
+        ...props,
+        url: 'https://my-embed-url.example.org',
+        id: 'v-quicksight-qna-1'
+      }
+    })
+    return { component, qnaFrame, embeddingContext }
+  }
+
+  it('renders as expected', () => {
+    const { component } = setupComponent()
+    expect(component.element).toMatchSnapshot()
+  })
+
+  it('should call embedQSearchBar with default parameters', async () => {
+    const { embeddingContext } = setupComponent()
+    await nextTick()
+    expect(embeddingContext.embedGenerativeQnA).toHaveBeenCalledOnce()
+    expect(embeddingContext.embedGenerativeQnA).toHaveBeenCalledWith(
+      {
+        className: undefined,
+        container: '#v-quicksight-qna-1',
+        height: '100%',
+        onChange: expect.anything(),
+        url: 'https://my-embed-url.example.org',
+        width: '100%',
+        withIframePlaceholder: false
+      },
+      {
+        showTopicName: true,
+        showPinboard: true,
+        allowTopicSelection: true,
+        allowFullscreen: true,
+        onMessage: expect.anything()
+      }
+    )
+  })
+
+  it('should call embedQSearchBar with customized parameters', () => {
+    const { embeddingContext } = setupComponent({ ...frameOptions, ...contentOptions })
+    expect(embeddingContext.embedGenerativeQnA).toHaveBeenCalledOnce()
+    expect(embeddingContext.embedGenerativeQnA).toHaveBeenCalledWith(
+      {
+        ...frameOptions,
+        onChange: expect.anything(),
+        url: 'https://my-embed-url.example.org'
+      },
+      {
+        ...contentOptions,
+        onMessage: expect.anything()
+      }
+    )
+  })
+
+  it('should call setQuestion when the passed question name changes', async () => {
+    const { qnaFrame, component } = setupComponent()
+    await nextTick() // wait until first setup is finished
+    await component.setProps({ url: '', question: 'How many apples were sold?' })
+    expect(qnaFrame.setQuestion).toHaveBeenCalledOnce()
+    expect(qnaFrame.setQuestion).toHaveBeenCalledWith('How many apples were sold?')
+  })
+
+  it('should call close when the question changes to a nullish value', async () => {
+    const { qnaFrame, component } = setupComponent({ question: 'How many apples were sold?' })
+    await nextTick() // wait until first setup is finished
+    await component.setProps({ url: '', question: '' })
+    expect(qnaFrame.close).toHaveBeenCalled()
+  })
+})

src/components/__tests__/__snapshots__/VQuicksightGenerativeQnA.spec.ts.snap

@@ -0,0 +1,8 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`VQuicksightGenerativeQnA > renders as expected 1`] = `
+<div
+  class="v-quicksight-generative-qna"
+  id="v-quicksight-qna-1"
+/>
+`;

src/components/index.ts

@@ -5,13 +5,15 @@ import VQuicksightDashboard from './VQuicksightDashboard.vue'
 import VQuicksightVisual from './VQuicksightVisual.vue'
 import VQuicksightConsole from './VQuicksightConsole.vue'
 import VQuicksightSearch from './VQuicksightSearch.vue'
+import VQuicksightGenerativeQnA from '@/components/VQuicksightGenerativeQnA.vue'
 
 function install(app: App) {
   app.component('v-quicksight', VQuicksight)
   app.component('v-quicksight-dashboard', VQuicksightDashboard)
   app.component('v-quicksight-visual', VQuicksightVisual)
   app.component('v-quicksight-console', VQuicksightConsole)
   app.component('v-quicksight-search', VQuicksightSearch)
+  app.component('v-quicksight-generative-qna', VQuicksightGenerativeQnA)
 }
 
 export default install
@@ -22,5 +24,6 @@ export {
   VQuicksightDashboard,
   VQuicksightVisual,
   VQuicksightConsole,
-  VQuicksightSearch
+  VQuicksightSearch,
+  VQuicksightGenerativeQnA
 }

src/demos/GenerativeQnAOne.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const question = ref('How many apples were sold?')
+
+const quickSightEmbedUrl = ref(
+  'https://eu-central-1.quicksight.aws.amazon.com/embed/12345/dashboards/67890?code=...'
+)
+
+function log($event: any) {
+  console.log('change', $event)
+}
+</script>
+
+<template>
+  <v-quicksight>
+    <v-quicksight-generative-qna
+      class="report-dashboard"
+      :url="quickSightEmbedUrl"
+      :question="question"
+      @change="log" />
+  </v-quicksight>
+</template>

src/types.ts

@@ -3,7 +3,8 @@ import type {
   FrameOptions,
   VisualContentOptions,
   ConsoleContentOptions,
-  QSearchContentOptions
+  QSearchContentOptions,
+  GenerativeQnAContentOptions
 } from 'amazon-quicksight-embedding-sdk'
 export type { ThemeConfiguration } from '@aws-sdk/client-quicksight/dist-types'
 
@@ -12,3 +13,4 @@ export type VQuicksightDashboardContentOptions = Omit<DashboardContentOptions, '
 export type VQuicksightVisualContentOptions = Omit<VisualContentOptions, 'onMessage'>
 export type VQuicksightConsoleContentOptions = Omit<ConsoleContentOptions, 'onMessage'>
 export type VQuicksightSearchContentOptions = Omit<QSearchContentOptions, 'onMessage'>
+export type VQuicksightGenerativeQnAContentOptions = Omit<GenerativeQnAContentOptions, 'onMessage'>