@gxp-dev/app-ui 0.1.0

package/src/composables/useQuestion.ts

@@ -0,0 +1,130 @@
+/**
+ * Single-question state for branched experiences — current question,
+ * answer payload, validation, and navigation to the next question. Used
+ * by the experience runtime to drive question flow.
+ */
+import { computed, type ComputedRef } from 'vue'
+
+/**
+ * Shape any question definition should provide. Most fields are optional —
+ * the composable accepts a few aliases (label vs question, hint vs description)
+ * so it can wrap heterogeneous backend schemas without a translation layer.
+ */
+export interface QuestionDefinition {
+  label?: string
+  question?: string
+  hint?: string
+  description?: string
+  points?: number
+  custom_settings?: { points?: number; [key: string]: unknown }
+  feedbackCorrect?: string
+  feedbackIncorrect?: string
+  explanation?: string
+}
+
+export interface UseQuestionOption {
+  id: string
+  value: string
+  label: string
+}
+
+export interface UseQuestionInputProps<T = unknown> {
+  question: QuestionDefinition
+  modelValue?: T
+  disabled?: boolean
+  readonly?: boolean
+  showResult?: boolean
+  isCorrect?: boolean | null
+  feedback?: string | null
+}
+
+export interface UseQuestionEmit<T = unknown> {
+  (event: 'update:modelValue', value: T): void
+  (event: 'answer', value: T): void
+}
+
+export interface UseQuestionReturn<T = unknown> {
+  questionText: ComputedRef<string>
+  questionHint: ComputedRef<string>
+  points: ComputedRef<number>
+  isInteractive: ComputedRef<boolean>
+  resultClass: ComputedRef<'question--correct' | 'question--incorrect' | ''>
+  displayFeedback: ComputedRef<string | null>
+  explanation: ComputedRef<string | null>
+  updateAnswer: (value: T) => void
+  submitAnswer: (value?: T) => void
+  normalizeOptions: (options: ReadonlyArray<string | UseQuestionOption>) => UseQuestionOption[]
+}
+
+/**
+ * Shared logic for question-shaped components (radio, multiple choice, essay, …).
+ * Pulls common state out so each component can focus on its own rendering.
+ *
+ * @example
+ *   const props = defineProps<UseQuestionInputProps<string>>()
+ *   const emit = defineEmits<UseQuestionEmit<string>>()
+ *   const q = useQuestion(props, emit)
+ */
+export function useQuestion<T = unknown>(
+  props: UseQuestionInputProps<T>,
+  emit: UseQuestionEmit<T>,
+): UseQuestionReturn<T> {
+  const questionText = computed(() => props.question.label || props.question.question || '')
+
+  const questionHint = computed(() => props.question.hint || props.question.description || '')
+
+  const points = computed(
+    () => props.question.points ?? props.question.custom_settings?.points ?? 0,
+  )
+
+  const isInteractive = computed(
+    () => !props.disabled && !props.readonly && !props.showResult,
+  )
+
+  const resultClass = computed<'question--correct' | 'question--incorrect' | ''>(() => {
+    if (!props.showResult || props.isCorrect === null || props.isCorrect === undefined) return ''
+    return props.isCorrect ? 'question--correct' : 'question--incorrect'
+  })
+
+  const displayFeedback = computed<string | null>(() => {
+    if (props.feedback) return props.feedback
+    if (!props.showResult) return null
+    return props.isCorrect
+      ? props.question.feedbackCorrect ?? 'Correct!'
+      : props.question.feedbackIncorrect ?? 'Incorrect'
+  })
+
+  const explanation = computed<string | null>(() => {
+    if (!props.showResult) return null
+    return props.question.explanation ?? null
+  })
+
+  const updateAnswer = (value: T): void => {
+    emit('update:modelValue', value)
+  }
+
+  const submitAnswer = (value?: T): void => {
+    emit('answer', value ?? (props.modelValue as T))
+  }
+
+  const normalizeOptions = (
+    options: ReadonlyArray<string | UseQuestionOption>,
+  ): UseQuestionOption[] => {
+    return (options ?? []).map((opt) =>
+      typeof opt === 'string' ? { id: opt, value: opt, label: opt } : opt,
+    )
+  }
+
+  return {
+    questionText,
+    questionHint,
+    points,
+    isInteractive,
+    resultClass,
+    displayFeedback,
+    explanation,
+    updateAnswer,
+    submitAnswer,
+    normalizeOptions,
+  }
+}

package/src/composables/useScanning.stories.ts

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseScanningDemo from './__demo__/UseScanningDemo.vue'
+
+const meta = {
+  title: 'Composables/useScanning',
+  component: UseScanningDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:shared-state', 'pattern:scanner'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useScanning()\` provides shared open/closed state for a scanner UI (typically
+\`BarcodeScanner\`). State is module-scoped so anywhere can toggle it, and the
+composable listens for a global \`reset-all\` event on \`document.body\` to
+auto-close when the wider app is reset (kiosk flows often dispatch this).
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Coordinating a scanner overlay that any component can open',
+        'Kiosk flows that need to reset all UI state on idle timeout',
+      ],
+      whenNotToUse: [
+        'Scanner stays mounted permanently — just bind its open prop directly',
+      ],
+      related: ['BarcodeScanner', 'useNfcListener'],
+    },
+  },
+} satisfies Meta<typeof UseScanningDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Click the buttons to flip the shared state. The "Dispatch 'reset-all'"
+ * button fires the global event the composable listens for.
+ */
+export const SharedState: Story = {}

package/src/composables/useScanning.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { defineComponent, h } from 'vue'
+import { useScanning, type UseScanningReturn } from './useScanning'
+
+const TestComponent = defineComponent({
+  setup() {
+    return useScanning()
+  },
+  render() {
+    return h('div')
+  },
+})
+
+describe('useScanning', () => {
+  let wrapper: ReturnType<typeof mount>
+
+  beforeEach(() => {
+    wrapper = mount(TestComponent, {
+      attachTo: document.body,
+    })
+    // Reset state since it's shared globally
+    wrapper.vm.closeScanner()
+  })
+
+  afterEach(() => {
+    wrapper.unmount()
+    document.body.innerHTML = ''
+  })
+
+  it('initializes with scanIsOpen false', () => {
+    expect(wrapper.vm.scanIsOpen).toBe(false)
+  })
+
+  it('initializes with registeredQuagga false', () => {
+    expect(wrapper.vm.registeredQuagga).toBe(false)
+  })
+
+  it('initializes with ocr false', () => {
+    expect(wrapper.vm.ocr).toBe(false)
+  })
+
+  it('openScanner sets scanIsOpen to true', () => {
+    wrapper.vm.openScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(true)
+  })
+
+  it('closeScanner sets scanIsOpen to false', () => {
+    wrapper.vm.openScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(true)
+
+    wrapper.vm.closeScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(false)
+  })
+
+  it('resetScanState sets scanIsOpen to false', () => {
+    wrapper.vm.openScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(true)
+
+    wrapper.vm.resetScanState()
+    expect(wrapper.vm.scanIsOpen).toBe(false)
+  })
+
+  it('responds to reset-all event on document.body', () => {
+    wrapper.vm.openScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(true)
+
+    const resetEvent = new Event('reset-all')
+    document.body.dispatchEvent(resetEvent)
+
+    expect(wrapper.vm.scanIsOpen).toBe(false)
+  })
+
+  it('registers event listener on mount', () => {
+    // Open scanner first
+    wrapper.vm.openScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(true)
+
+    // Dispatch reset-all event
+    const resetEvent = new Event('reset-all')
+    document.body.dispatchEvent(resetEvent)
+
+    // Verify the listener is working
+    expect(wrapper.vm.scanIsOpen).toBe(false)
+  })
+
+  it('removes event listener on unmount', () => {
+    wrapper.vm.openScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(true)
+
+    // Unmount the component
+    wrapper.unmount()
+
+    // Dispatch reset-all event after unmount
+    const resetEvent = new Event('reset-all')
+    document.body.dispatchEvent(resetEvent)
+
+    // Since the component is unmounted, we can't check its state
+    // But we can verify no errors occur
+    expect(true).toBe(true)
+  })
+
+  it('shares state between multiple instances', () => {
+    const wrapper2 = mount(TestComponent, {
+      attachTo: document.body,
+    })
+
+    // Both instances should share the same state
+    expect(wrapper.vm.scanIsOpen).toBe(false)
+    expect(wrapper2.vm.scanIsOpen).toBe(false)
+
+    // Opening scanner in one instance affects both
+    wrapper.vm.openScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(true)
+    expect(wrapper2.vm.scanIsOpen).toBe(true)
+
+    // Closing in the other instance affects both
+    wrapper2.vm.closeScanner()
+    expect(wrapper.vm.scanIsOpen).toBe(false)
+    expect(wrapper2.vm.scanIsOpen).toBe(false)
+
+    wrapper2.unmount()
+  })
+
+  it('returns all expected properties and methods', () => {
+    const vm = wrapper.vm as UseScanningReturn
+
+    expect(vm).toHaveProperty('scanIsOpen')
+    expect(vm).toHaveProperty('registeredQuagga')
+    expect(vm).toHaveProperty('ocr')
+    expect(vm).toHaveProperty('openScanner')
+    expect(vm).toHaveProperty('closeScanner')
+    expect(vm).toHaveProperty('resetScanState')
+  })
+})

package/src/composables/useScanning.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared scanner-open state (barcode + OCR) for the portal. Exposes
+ * `openScanner` / `closeScanner` and tracks whether Quagga has been
+ * registered so multiple components don't re-initialise it.
+ */
+import { ref, onMounted, onBeforeUnmount, type Ref } from 'vue'
+
+export interface UseScanningReturn {
+  scanIsOpen: Ref<boolean>
+  registeredQuagga: Ref<boolean>
+  ocr: Ref<boolean>
+  openScanner: () => void
+  closeScanner: () => void
+  resetScanState: () => void
+}
+
+const scanIsOpen = ref(false)
+const registeredQuagga = ref(false)
+const ocr = ref(false)
+
+export function useScanning(): UseScanningReturn {
+  const resetScanState = () => {
+    scanIsOpen.value = false
+  }
+
+  const openScanner = () => {
+    scanIsOpen.value = true
+  }
+
+  const closeScanner = () => {
+    scanIsOpen.value = false
+  }
+
+  onMounted(() => {
+    document.body.addEventListener('reset-all', resetScanState)
+  })
+
+  onBeforeUnmount(() => {
+    document.body.removeEventListener('reset-all', resetScanState)
+  })
+
+  return {
+    scanIsOpen,
+    registeredQuagga,
+    ocr,
+    openScanner,
+    closeScanner,
+    resetScanState,
+  }
+}

package/src/composables/useStreamingAudio.stories.ts

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseStreamingAudioDemo from './__demo__/UseStreamingAudioDemo.vue'
+
+const meta = {
+  title: 'Composables/useStreamingAudio',
+  component: UseStreamingAudioDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:audio', 'pattern:streaming', 'pattern:ai-voice'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useStreamingAudio()\` is a continuous-stream audio I/O primitive built for
+real-time AI voice apps (Gemini Live, OpenAI Realtime, streaming TTS) and
+similar pipelines where audio arrives interleaved as PCM chunks.
+
+It provides:
+
+- **Mic capture** with EC/NS/AGC enabled and a smoothed \`audioLevel\` ref.
+- **Sequential PCM playback queue** — schedule incoming chunks via
+  \`playPCMChunk(int16, sampleRate)\` and they're stitched into seamless
+  playback through an AEC-compatible \`MediaStreamDestination\` so the
+  browser can echo-cancel the playback against the mic.
+- **Interruption** — \`interruptPlayback()\` stops everything queued
+  immediately. Useful for barge-in: the user starts speaking, you stop the AI
+  mid-sentence.
+- **Speech detection** — \`setSpeechDetectionCallback(cb)\` fires when the mic
+  level crosses a configurable threshold; pair with \`interruptPlayback\` for
+  natural turn-taking.
+- **Frequency / waveform readers** for visualisation.
+
+Unlike \`useMedia\`, this is purpose-built for streaming pipelines — it does
+not handle recording, video, or device enumeration.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Streaming AI voice (Gemini Live, OpenAI Realtime, etc.)',
+        'Real-time TTS where audio arrives in interleaved chunks',
+        'Conversational apps that need barge-in / interruption',
+        'You need echo-cancelled playback that doesn\'t get picked up by the mic',
+      ],
+      whenNotToUse: [
+        'Recording a single audio file — use useMedia',
+        'Playing a fixed asset — just use HTMLAudioElement',
+        'WebRTC peer connections for multi-party calls — use useChatMedia',
+      ],
+      related: ['useMedia', 'useChatMedia', 'AudioVisualizer'],
+    },
+  },
+} satisfies Meta<typeof UseStreamingAudioDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Interactive sandbox. Step through:
+ *
+ *   1. **Initialize** — create the AudioContext + analyser.
+ *   2. **Start capture** — grant mic permission; watch the level bar move.
+ *   3. **Play tone** — schedules a 250ms 440Hz PCM chunk. **Play 4-chunk
+ *      sequence** demonstrates seamless concatenation.
+ *   4. **Interrupt** — cuts off any queued audio mid-flight.
+ *   5. **Cleanup** — stops capture and closes the context.
+ *
+ * The log on the right shows speech-detection callback fires.
+ */
+export const InteractiveSandbox: Story = {}

package/src/composables/useStreamingAudio.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { useStreamingAudio } from './useStreamingAudio'
+
+class MockAnalyser {
+  fftSize = 2048
+  smoothingTimeConstant = 0.8
+  frequencyBinCount = 1024
+  getByteFrequencyData = vi.fn()
+  getByteTimeDomainData = vi.fn()
+}
+
+class MockBufferSource {
+  buffer: unknown = null
+  onended: (() => void) | null = null
+  connect = vi.fn()
+  start = vi.fn()
+  stop = vi.fn()
+}
+
+class MockAudioBuffer {
+  duration = 0.5
+  private data: Float32Array
+  constructor(public channels: number, public length: number, public rate: number) {
+    this.data = new Float32Array(length)
+  }
+  getChannelData(): Float32Array {
+    return this.data
+  }
+}
+
+class MockAudioContext {
+  currentTime = 0
+  destination = {}
+  createAnalyser = vi.fn(() => new MockAnalyser())
+  createMediaStreamSource = vi.fn(() => ({ connect: vi.fn() }))
+  createMediaStreamDestination = vi.fn(() => ({ stream: new (globalThis as any).MediaStream() }))
+  createBuffer = vi.fn((c, l, r) => new MockAudioBuffer(c, l, r))
+  createBufferSource = vi.fn(() => new MockBufferSource())
+  close = vi.fn(async () => undefined)
+}
+
+beforeEach(() => {
+  ;(globalThis as any).AudioContext = MockAudioContext
+  if (typeof (globalThis as any).MediaStream === 'undefined') {
+    ;(globalThis as any).MediaStream = class {
+      getTracks() {
+        return []
+      }
+      addTrack() {}
+    }
+  }
+  // Same track instance across getTracks/getAudioTracks calls so toggleMute's
+  // mutation of `enabled` is observable on the next invocation.
+  const track = { stop: vi.fn(), enabled: true, kind: 'audio' }
+  const stream = {
+    getTracks: () => [track],
+    getAudioTracks: () => [track],
+  }
+  ;(navigator as any).mediaDevices = {
+    getUserMedia: vi.fn(async () => stream),
+  }
+})
+
+describe('useStreamingAudio', () => {
+  it('initialize creates AudioContext + analyser', async () => {
+    const audio = useStreamingAudio({ sampleRate: 24000 })
+    const ctx = await audio.initialize()
+    expect(ctx).toBeTruthy()
+    expect(audio.audioContext.value).toBeTruthy()
+    expect(audio.analyser.value).toBeTruthy()
+  })
+
+  it('startCapture sets audioStream and toggles isCapturing', async () => {
+    const audio = useStreamingAudio()
+    await audio.startCapture()
+    expect(audio.audioStream.value).toBeTruthy()
+    expect(audio.isCapturing.value).toBe(true)
+  })
+
+  it('stopCapture stops tracks and clears refs', async () => {
+    const audio = useStreamingAudio()
+    await audio.startCapture()
+    audio.stopCapture()
+    expect(audio.audioStream.value).toBeNull()
+    expect(audio.isCapturing.value).toBe(false)
+  })
+
+  it('toggleMute disables the track and flips isMuted', async () => {
+    const audio = useStreamingAudio()
+    await audio.startCapture()
+    audio.toggleMute()
+    expect(audio.isMuted.value).toBe(true)
+    audio.toggleMute()
+    expect(audio.isMuted.value).toBe(false)
+  })
+
+  it('playPCMChunk schedules a buffer source', async () => {
+    const audio = useStreamingAudio()
+    await audio.initialize()
+    const chunk = new Int16Array(2400) // 100ms @ 24kHz
+    audio.playPCMChunk(chunk, 24000)
+    const ctx = audio.audioContext.value as unknown as MockAudioContext
+    expect(ctx.createBuffer).toHaveBeenCalled()
+    expect(ctx.createBufferSource).toHaveBeenCalled()
+  })
+
+  it('interruptPlayback stops all scheduled sources', async () => {
+    const audio = useStreamingAudio()
+    await audio.initialize()
+    const ctx = audio.audioContext.value as unknown as MockAudioContext
+    audio.playPCMChunk(new Int16Array(100), 24000)
+    audio.playPCMChunk(new Int16Array(100), 24000)
+    audio.interruptPlayback()
+    const sources = ctx.createBufferSource.mock.results.map((r) => r.value as MockBufferSource)
+    sources.forEach((s) => expect(s.stop).toHaveBeenCalled())
+  })
+
+  it('setSpeechDetectionCallback wires the callback', () => {
+    const audio = useStreamingAudio()
+    const cb = vi.fn()
+    audio.setSpeechDetectionCallback(cb)
+    audio.setSpeechDetectionCallback(null)
+    // No assertions beyond not throwing; behaviour is exercised via the level loop.
+    expect(true).toBe(true)
+  })
+
+  it('cleanup closes the context and clears refs', async () => {
+    const audio = useStreamingAudio()
+    await audio.initialize()
+    audio.cleanup()
+    expect(audio.audioContext.value).toBeNull()
+    expect(audio.analyser.value).toBeNull()
+  })
+})