@gxp-dev/app-ui 0.1.6

package/src/composables/useNfcListener.test.ts

@@ -0,0 +1,311 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { useNfcListener, simulateNfcScan } from './useNfcListener'
+import type { NfcScanData } from './useNfcListener'
+import { flushPromises } from '@vue/test-utils'
+
+// Helper to dispatch a message event directly (more reliable than postMessage in jsdom)
+const dispatchNfcMessage = (data: any) => {
+  const event = new MessageEvent('message', {
+    data,
+    origin: window.location.origin,
+  })
+  window.dispatchEvent(event)
+}
+
+// Helper to wait for message event to propagate
+const waitForMessage = async () => {
+  await flushPromises()
+  await new Promise((resolve) => setTimeout(resolve, 10))
+}
+
+describe('useNfcListener', () => {
+  let cleanupFunctions: Array<() => void> = []
+
+  afterEach(() => {
+    // Clean up all registered handlers to prevent leaking state between tests
+    cleanupFunctions.forEach((cleanup) => cleanup())
+    cleanupFunctions = []
+  })
+
+  it('registerHandler returns a cleanup function', () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn()
+
+    const cleanup = registerHandler(handler)
+
+    expect(cleanup).toBeTypeOf('function')
+    cleanupFunctions.push(cleanup)
+  })
+
+  it('handler is called when NFC scan message is posted', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn()
+
+    const cleanup = registerHandler(handler)
+    cleanupFunctions.push(cleanup)
+
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler).toHaveBeenCalledTimes(1)
+  })
+
+  it('handler receives correct uid and tagType', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn<[NfcScanData]>()
+
+    const cleanup = registerHandler(handler)
+    cleanupFunctions.push(cleanup)
+
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler).toHaveBeenCalledWith({
+      uid: 'ABC123',
+      tagType: 'TAG_ISO_14443_3',
+      timestamp: 12345,
+    })
+  })
+
+  it('cleanup function removes the handler', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn()
+
+    const cleanup = registerHandler(handler)
+
+    // Call cleanup to remove the handler
+    cleanup()
+
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('ignores non-nfc:scan messages', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn()
+
+    const cleanup = registerHandler(handler)
+    cleanupFunctions.push(cleanup)
+
+    dispatchNfcMessage({
+      type: 'some-other-message',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('ignores messages without uid', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn()
+
+    const cleanup = registerHandler(handler)
+    cleanupFunctions.push(cleanup)
+
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('handles multiple handlers', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler1 = vi.fn()
+    const handler2 = vi.fn()
+
+    const cleanup1 = registerHandler(handler1)
+    const cleanup2 = registerHandler(handler2)
+    cleanupFunctions.push(cleanup1, cleanup2)
+
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler1).toHaveBeenCalledTimes(1)
+    expect(handler2).toHaveBeenCalledTimes(1)
+  })
+
+  it('removes only the cleaned up handler', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler1 = vi.fn()
+    const handler2 = vi.fn()
+
+    const cleanup1 = registerHandler(handler1)
+    const cleanup2 = registerHandler(handler2)
+    cleanupFunctions.push(cleanup2)
+
+    // Remove only handler1
+    cleanup1()
+
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler1).not.toHaveBeenCalled()
+    expect(handler2).toHaveBeenCalledTimes(1)
+  })
+
+  it('handles errors in handlers gracefully', async () => {
+    const { registerHandler } = useNfcListener()
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const errorHandler = vi.fn(() => {
+      throw new Error('Handler error')
+    })
+    const normalHandler = vi.fn()
+
+    const cleanup1 = registerHandler(errorHandler)
+    const cleanup2 = registerHandler(normalHandler)
+    cleanupFunctions.push(cleanup1, cleanup2)
+
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+      timestamp: 12345,
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(errorHandler).toHaveBeenCalled()
+    expect(normalHandler).toHaveBeenCalled()
+    expect(consoleErrorSpy).toHaveBeenCalled()
+
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('provides default timestamp if not provided', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn<[NfcScanData]>()
+
+    const cleanup = registerHandler(handler)
+    cleanupFunctions.push(cleanup)
+
+    const beforePost = Date.now()
+    dispatchNfcMessage({
+      type: 'nfc:scan',
+      data: { uid: 'ABC123', tagType: 'TAG_ISO_14443_3' },
+    })
+
+    // Wait for async message event to fire
+    await waitForMessage()
+    const afterPost = Date.now()
+
+    expect(handler).toHaveBeenCalled()
+    const receivedData = handler.mock.calls[0][0]
+    expect(receivedData.timestamp).toBeGreaterThanOrEqual(beforePost)
+    expect(receivedData.timestamp).toBeLessThanOrEqual(afterPost)
+  })
+
+  it('returns a no-op cleanup function for non-function handlers', () => {
+    const { registerHandler } = useNfcListener()
+
+    // @ts-expect-error Testing invalid input
+    const cleanup = registerHandler('not a function')
+
+    expect(cleanup).toBeTypeOf('function')
+    expect(() => cleanup()).not.toThrow()
+  })
+})
+
+describe('simulateNfcScan', () => {
+  let cleanupFunctions: Array<() => void> = []
+  let originalPostMessage: typeof window.postMessage
+
+  beforeEach(() => {
+    // Save original postMessage
+    originalPostMessage = window.postMessage
+
+    // Mock postMessage to use dispatchEvent instead (more reliable in jsdom)
+    window.postMessage = vi.fn((data: any, origin: string) => {
+      dispatchNfcMessage(data)
+    })
+  })
+
+  afterEach(() => {
+    cleanupFunctions.forEach((cleanup) => cleanup())
+    cleanupFunctions = []
+
+    // Restore original postMessage
+    window.postMessage = originalPostMessage
+  })
+
+  it('dispatches an NFC scan event that triggers handlers', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn()
+
+    const cleanup = registerHandler(handler)
+    cleanupFunctions.push(cleanup)
+
+    simulateNfcScan('TEST123', 'TAG_ISO_14443_4')
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        uid: 'TEST123',
+        tagType: 'TAG_ISO_14443_4',
+      }),
+    )
+  })
+
+  it('uses default tagType if not provided', async () => {
+    const { registerHandler } = useNfcListener()
+    const handler = vi.fn<[NfcScanData]>()
+
+    const cleanup = registerHandler(handler)
+    cleanupFunctions.push(cleanup)
+
+    simulateNfcScan('TEST123')
+
+    // Wait for async message event to fire
+    await waitForMessage()
+
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        uid: 'TEST123',
+        tagType: 'TAG_ISO_14443_3',
+      }),
+    )
+  })
+})

package/src/composables/useNfcListener.ts

@@ -0,0 +1,90 @@
+/**
+ * NFC scan dispatcher. Listens for `nfc:scan` window messages from the
+ * host kiosk app and fans them out to any registered in-page handlers.
+ */
+export interface NfcScanData {
+  uid: string
+  tagType: string
+  timestamp: number
+}
+
+export type NfcHandler = (data: NfcScanData) => void
+
+export interface UseNfcListenerReturn {
+  registerHandler: (handler: NfcHandler) => () => void
+}
+
+const handlers = new Set<NfcHandler>()
+
+const handleMessage = (event: MessageEvent) => {
+  if (event.origin !== window.location.origin) return
+  if (event.data?.type !== 'nfc:scan') return
+
+  const { data, timestamp } = event.data
+
+  if (!data?.uid) return
+
+  handlers.forEach((handler) => {
+    try {
+      handler({
+        uid: data.uid,
+        tagType: data.tagType,
+        timestamp: timestamp || Date.now(),
+      })
+    } catch (error) {
+      console.error('[useNfcListener] Handler error:', error)
+    }
+  })
+}
+
+let globalListenerActive = false
+
+const startGlobalListener = () => {
+  if (!globalListenerActive) {
+    window.addEventListener('message', handleMessage)
+    globalListenerActive = true
+  }
+}
+
+const stopGlobalListener = () => {
+  if (globalListenerActive && handlers.size === 0) {
+    window.removeEventListener('message', handleMessage)
+    globalListenerActive = false
+  }
+}
+
+export function useNfcListener(): UseNfcListenerReturn {
+  const registerHandler = (handler: NfcHandler): (() => void) => {
+    if (typeof handler !== 'function') {
+      return () => {}
+    }
+
+    handlers.add(handler)
+    startGlobalListener()
+
+    return () => {
+      handlers.delete(handler)
+      if (handlers.size === 0) {
+        stopGlobalListener()
+      }
+    }
+  }
+
+  return { registerHandler }
+}
+
+/**
+ * Utility for testing: simulate an NFC scan event
+ */
+export function simulateNfcScan(uid: string, tagType = 'TAG_ISO_14443_3') {
+  if (typeof window === 'undefined') return
+
+  window.postMessage(
+    {
+      type: 'nfc:scan',
+      data: { uid, tagType },
+      timestamp: Date.now(),
+    },
+    window.location.origin,
+  )
+}

package/src/composables/useQuestion.stories.ts

@@ -0,0 +1,118 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseQuestionDemo from './__demo__/UseQuestionDemo.vue'
+
+const meta = {
+  title: 'Composables/useQuestion',
+  component: UseQuestionDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:headless', 'pattern:forms'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useQuestion(props, emit)\` is a **headless** composable that supplies the
+state every question-shaped component needs: derived label/hint/points, an
+\`isInteractive\` predicate, feedback resolution, and answer-submission emits.
+
+Designed to wrap heterogeneous backend schemas — accepts \`label\` or
+\`question\`, \`hint\` or \`description\`, \`points\` or
+\`custom_settings.points\`. Drop it inside any question type (MultipleChoice,
+Essay, Rating, etc.) and the surrounding plumbing is consistent.
+
+Returns refs so the component template stays declarative. No DOM, no styling —
+you bring those.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Building a multi-type question / quiz / survey component family',
+        'You want consistent feedback + read-only + result behavior across types',
+        'You need a clean update:modelValue + answer event contract',
+      ],
+      whenNotToUse: [
+        'Simple single-field input — use a plain ref',
+        'Complex multi-step wizards — use the experience-flow system instead',
+      ],
+      related: ['FormPage', 'PromptPage', 'OptionsPage', 'useChatMessages'],
+    },
+  },
+  argTypes: {
+    questionDef: { control: 'object', description: 'QuestionDefinition object (label, hint, points, feedback…)' },
+    disabled: { control: 'boolean' },
+    readonly: { control: 'boolean' },
+    showResult: { control: 'boolean' },
+    isCorrect: { control: 'radio', options: [null, true, false] },
+    feedback: { control: 'text' },
+  },
+} satisfies Meta<typeof UseQuestionDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Interactive question, no result yet. `isInteractive` is true; clicking
+ * Submit fires the `answer` event with the current modelValue.
+ */
+export const Interactive: Story = {
+  args: {
+    questionDef: { label: 'What is 2 + 2?', hint: '(basic arithmetic)', points: 5 },
+  },
+}
+
+/**
+ * Read-only mode — input disabled, no submission allowed. `isInteractive`
+ * becomes false. Use during result review or in viewer mode.
+ */
+export const Readonly: Story = {
+  args: {
+    questionDef: { label: 'What is 2 + 2?', points: 5 },
+    readonly: true,
+  },
+}
+
+/**
+ * Result view — correct. `displayFeedback` resolves to
+ * `question.feedbackCorrect`, `resultClass` becomes `question--correct`.
+ */
+export const ShowingCorrectResult: Story = {
+  args: {
+    questionDef: {
+      label: 'What is 2 + 2?',
+      points: 5,
+      feedbackCorrect: 'Nice — exactly right.',
+      explanation: 'Two plus two has been four since the agricultural revolution.',
+    },
+    showResult: true,
+    isCorrect: true,
+  },
+}
+
+/**
+ * Result view — incorrect. `displayFeedback` resolves to
+ * `question.feedbackIncorrect` (with sensible default).
+ */
+export const ShowingIncorrectResult: Story = {
+  args: {
+    questionDef: {
+      label: 'What is 2 + 2?',
+      points: 5,
+      feedbackIncorrect: 'Close, but not quite.',
+    },
+    showResult: true,
+    isCorrect: false,
+  },
+}
+
+/**
+ * Explicit `feedback` prop overrides whatever the question definition would
+ * suggest. Useful for runtime-computed feedback from the server.
+ */
+export const FeedbackOverride: Story = {
+  args: {
+    questionDef: { label: 'What is 2 + 2?', feedbackCorrect: 'Default correct' },
+    showResult: true,
+    isCorrect: true,
+    feedback: 'Server says: "Outstanding."',
+  },
+}

package/src/composables/useQuestion.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest'
+import { reactive } from 'vue'
+import { useQuestion, type UseQuestionInputProps } from './useQuestion'
+
+const makeProps = (
+  overrides: Partial<UseQuestionInputProps<string>> = {},
+): UseQuestionInputProps<string> =>
+  reactive({
+    question: { label: 'What is 2+2?', points: 5 },
+    modelValue: '',
+    disabled: false,
+    readonly: false,
+    showResult: false,
+    isCorrect: null,
+    feedback: null,
+    ...overrides,
+  })
+
+describe('useQuestion', () => {
+  it('prefers question.label over question.question for text', () => {
+    const props = makeProps({ question: { label: 'A', question: 'B' } })
+    const q = useQuestion(props, vi.fn())
+    expect(q.questionText.value).toBe('A')
+  })
+
+  it('falls back to question.question when label is missing', () => {
+    const props = makeProps({ question: { question: 'Fallback' } })
+    const q = useQuestion(props, vi.fn())
+    expect(q.questionText.value).toBe('Fallback')
+  })
+
+  it('reads points from custom_settings when top-level is missing', () => {
+    const props = makeProps({ question: { custom_settings: { points: 7 } } })
+    const q = useQuestion(props, vi.fn())
+    expect(q.points.value).toBe(7)
+  })
+
+  it('isInteractive is false when disabled/readonly/showResult', () => {
+    const props = makeProps()
+    const q = useQuestion(props, vi.fn())
+    expect(q.isInteractive.value).toBe(true)
+    props.disabled = true
+    expect(q.isInteractive.value).toBe(false)
+    props.disabled = false
+    props.showResult = true
+    expect(q.isInteractive.value).toBe(false)
+  })
+
+  it('resultClass reflects correctness only when showing results', () => {
+    const props = makeProps({ showResult: false, isCorrect: true })
+    const q = useQuestion(props, vi.fn())
+    expect(q.resultClass.value).toBe('')
+    props.showResult = true
+    expect(q.resultClass.value).toBe('question--correct')
+    props.isCorrect = false
+    expect(q.resultClass.value).toBe('question--incorrect')
+  })
+
+  it('displayFeedback prefers explicit feedback, then per-question, then default', () => {
+    const props = makeProps({
+      showResult: true,
+      isCorrect: true,
+      question: { feedbackCorrect: 'Nice', feedbackIncorrect: 'Nope' },
+    })
+    const q = useQuestion(props, vi.fn())
+    expect(q.displayFeedback.value).toBe('Nice')
+    props.feedback = 'Overridden'
+    expect(q.displayFeedback.value).toBe('Overridden')
+
+    props.feedback = null
+    props.isCorrect = false
+    expect(q.displayFeedback.value).toBe('Nope')
+
+    props.question = {}
+    expect(q.displayFeedback.value).toBe('Incorrect')
+  })
+
+  it('explanation only surfaces when showResult is true', () => {
+    const props = makeProps({ question: { explanation: 'because math' } })
+    const q = useQuestion(props, vi.fn())
+    expect(q.explanation.value).toBeNull()
+    props.showResult = true
+    expect(q.explanation.value).toBe('because math')
+  })
+
+  it('updateAnswer emits update:modelValue', () => {
+    const emit = vi.fn()
+    const q = useQuestion(makeProps(), emit)
+    q.updateAnswer('42')
+    expect(emit).toHaveBeenCalledWith('update:modelValue', '42')
+  })
+
+  it('submitAnswer falls back to modelValue when no value passed', () => {
+    const emit = vi.fn()
+    const q = useQuestion(makeProps({ modelValue: 'mv' }), emit)
+    q.submitAnswer()
+    expect(emit).toHaveBeenCalledWith('answer', 'mv')
+    q.submitAnswer('explicit')
+    expect(emit).toHaveBeenLastCalledWith('answer', 'explicit')
+  })
+
+  it('normalizeOptions handles both shapes', () => {
+    const q = useQuestion(makeProps(), vi.fn())
+    const result = q.normalizeOptions([
+      'plain',
+      { id: 'a', value: 'A', label: 'Letter A' },
+    ])
+    expect(result).toEqual([
+      { id: 'plain', value: 'plain', label: 'plain' },
+      { id: 'a', value: 'A', label: 'Letter A' },
+    ])
+  })
+})