@gxp-dev/app-ui 0.1.0

package/src/composables/useChatMessages.ts

@@ -0,0 +1,295 @@
+/**
+ * Reactive chat-message store with paginated history loading, optimistic
+ * send, and incoming-message merging. Wraps the WebSocket + REST channel
+ * into a single subscribable store.
+ */
+import { ref, computed, type ComputedRef, type Ref } from 'vue'
+
+export interface ChatReaction {
+  emoji: string
+  count: number
+  participant_ids: Array<string | number>
+}
+
+export interface ChatMessage {
+  id: string | number
+  content: string
+  /** Optional fields recognised by the helpers below. Anything else is preserved. */
+  is_edited?: boolean
+  edited_at?: string | null
+  is_deleted?: boolean
+  reply_to?: string | number | null
+  reactions?: ChatReaction[]
+  [key: string]: unknown
+}
+
+export interface LoadHistoryOptions {
+  beforeId?: string | number
+  limit?: number
+}
+
+export interface SendMessageInput {
+  content: string
+  reply_to?: string | number | null
+  attachments?: File[]
+}
+
+export interface ChatMessagesApi {
+  loadHistory: (opts: LoadHistoryOptions) => Promise<{ messages: ChatMessage[]; hasMore: boolean }>
+  sendMessage: (input: SendMessageInput) => Promise<ChatMessage>
+  editMessage: (id: string | number, newContent: string) => Promise<void>
+  deleteMessage: (id: string | number) => Promise<void>
+  addReaction: (id: string | number, emoji: string) => Promise<void>
+  removeReaction: (id: string | number, emoji: string) => Promise<void>
+}
+
+export interface UseChatMessagesOptions {
+  api: ChatMessagesApi
+  /** When set, replace `[Message deleted]` with your own placeholder text. */
+  deletedPlaceholder?: string
+  /** Default page size for `loadHistory`. */
+  defaultLimit?: number
+}
+
+export interface UseChatMessagesReturn {
+  // State
+  messages: Ref<ChatMessage[]>
+  isLoading: Ref<boolean>
+  hasMore: Ref<boolean>
+  replyingTo: Ref<ChatMessage | null>
+  editingMessage: Ref<ChatMessage | null>
+
+  // Computed
+  messageCount: ComputedRef<number>
+  oldestMessageId: ComputedRef<ChatMessage['id'] | undefined>
+  newestMessageId: ComputedRef<ChatMessage['id'] | undefined>
+
+  // Actions
+  loadHistory: (opts?: LoadHistoryOptions) => Promise<ChatMessage[]>
+  sendMessage: (content: string, attachments?: File[]) => Promise<ChatMessage>
+  editMessage: (id: ChatMessage['id'], newContent: string) => Promise<void>
+  deleteMessage: (id: ChatMessage['id']) => Promise<void>
+  addReaction: (id: ChatMessage['id'], emoji: string) => Promise<void>
+  removeReaction: (id: ChatMessage['id'], emoji: string) => Promise<void>
+
+  // UI state helpers
+  setReplyTo: (message: ChatMessage | null) => void
+  cancelReply: () => void
+  setEditing: (message: ChatMessage | null) => void
+  cancelEditing: () => void
+  clearMessages: () => void
+
+  // WebSocket / push-event handlers (mutate local state)
+  handleNewMessage: (message: ChatMessage) => void
+  handleMessageEdited: (data: {
+    messageId: ChatMessage['id']
+    content: string
+    editedAt?: string
+  }) => void
+  handleMessageDeleted: (messageId: ChatMessage['id']) => void
+  handleReactionAdded: (data: {
+    messageId: ChatMessage['id']
+    emoji: string
+    participantId: string | number
+  }) => void
+  handleReactionRemoved: (data: {
+    messageId: ChatMessage['id']
+    emoji: string
+    participantId: string | number
+  }) => void
+}
+
+/**
+ * Headless chat-message state container.
+ *
+ * Owns the reactive message list, pagination cursor, reply/edit UI state, and
+ * push-event handlers. I/O is your responsibility — pass in an `api` object
+ * whose methods talk to your backend (REST, GraphQL, RPC, …) and the composable
+ * wraps them with optimistic local updates.
+ */
+export function useChatMessages(options: UseChatMessagesOptions): UseChatMessagesReturn {
+  const { api, deletedPlaceholder = '[Message deleted]', defaultLimit = 50 } = options
+
+  const messages = ref<ChatMessage[]>([])
+  const isLoading = ref(false)
+  const hasMore = ref(true)
+  const replyingTo = ref<ChatMessage | null>(null)
+  const editingMessage = ref<ChatMessage | null>(null)
+
+  const findMessage = (id: ChatMessage['id']): ChatMessage | undefined =>
+    messages.value.find((m) => m.id === id)
+
+  const loadHistory = async (opts: LoadHistoryOptions = {}): Promise<ChatMessage[]> => {
+    if (isLoading.value) return []
+    isLoading.value = true
+    try {
+      const { beforeId, limit = defaultLimit } = opts
+      const result = await api.loadHistory({ beforeId, limit })
+      if (beforeId) {
+        messages.value = [...result.messages, ...messages.value]
+      } else {
+        messages.value = result.messages
+      }
+      hasMore.value = result.hasMore
+      return result.messages
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  const sendMessage = async (content: string, attachments: File[] = []): Promise<ChatMessage> => {
+    const message = await api.sendMessage({
+      content,
+      reply_to: replyingTo.value?.id ?? null,
+      attachments,
+    })
+    replyingTo.value = null
+    return message
+  }
+
+  const editMessage = async (id: ChatMessage['id'], newContent: string): Promise<void> => {
+    await api.editMessage(id, newContent)
+    const message = findMessage(id)
+    if (message) {
+      message.content = newContent
+      message.is_edited = true
+    }
+    editingMessage.value = null
+  }
+
+  const deleteMessage = async (id: ChatMessage['id']): Promise<void> => {
+    await api.deleteMessage(id)
+    const message = findMessage(id)
+    if (message) {
+      message.is_deleted = true
+      message.content = deletedPlaceholder
+    }
+  }
+
+  const addReaction = async (id: ChatMessage['id'], emoji: string): Promise<void> => {
+    await api.addReaction(id, emoji)
+  }
+
+  const removeReaction = async (id: ChatMessage['id'], emoji: string): Promise<void> => {
+    await api.removeReaction(id, emoji)
+  }
+
+  const setReplyTo = (message: ChatMessage | null): void => {
+    replyingTo.value = message
+  }
+  const cancelReply = (): void => {
+    replyingTo.value = null
+  }
+  const setEditing = (message: ChatMessage | null): void => {
+    editingMessage.value = message
+  }
+  const cancelEditing = (): void => {
+    editingMessage.value = null
+  }
+
+  const clearMessages = (): void => {
+    messages.value = []
+    hasMore.value = true
+    replyingTo.value = null
+    editingMessage.value = null
+  }
+
+  const handleNewMessage = (message: ChatMessage): void => {
+    if (messages.value.some((m) => m.id === message.id)) return
+    messages.value.push(message)
+  }
+
+  const handleMessageEdited = (data: {
+    messageId: ChatMessage['id']
+    content: string
+    editedAt?: string
+  }): void => {
+    const message = findMessage(data.messageId)
+    if (!message) return
+    message.content = data.content
+    message.is_edited = true
+    if (data.editedAt) message.edited_at = data.editedAt
+  }
+
+  const handleMessageDeleted = (messageId: ChatMessage['id']): void => {
+    const message = findMessage(messageId)
+    if (!message) return
+    message.is_deleted = true
+    message.content = deletedPlaceholder
+  }
+
+  const handleReactionAdded = (data: {
+    messageId: ChatMessage['id']
+    emoji: string
+    participantId: string | number
+  }): void => {
+    const message = findMessage(data.messageId)
+    if (!message) return
+    if (!message.reactions) message.reactions = []
+    const existing = message.reactions.find((r) => r.emoji === data.emoji)
+    if (existing) {
+      if (!existing.participant_ids.includes(data.participantId)) {
+        existing.participant_ids.push(data.participantId)
+        existing.count += 1
+      }
+    } else {
+      message.reactions.push({
+        emoji: data.emoji,
+        count: 1,
+        participant_ids: [data.participantId],
+      })
+    }
+  }
+
+  const handleReactionRemoved = (data: {
+    messageId: ChatMessage['id']
+    emoji: string
+    participantId: string | number
+  }): void => {
+    const message = findMessage(data.messageId)
+    if (!message?.reactions) return
+    const idx = message.reactions.findIndex((r) => r.emoji === data.emoji)
+    if (idx === -1) return
+    const reaction = message.reactions[idx]
+    reaction.participant_ids = reaction.participant_ids.filter(
+      (id) => id !== data.participantId,
+    )
+    reaction.count -= 1
+    if (reaction.count <= 0) {
+      message.reactions.splice(idx, 1)
+    }
+  }
+
+  const messageCount = computed(() => messages.value.length)
+  const oldestMessageId = computed<ChatMessage['id'] | undefined>(() => messages.value[0]?.id)
+  const newestMessageId = computed<ChatMessage['id'] | undefined>(
+    () => messages.value[messages.value.length - 1]?.id,
+  )
+
+  return {
+    messages,
+    isLoading,
+    hasMore,
+    replyingTo,
+    editingMessage,
+    messageCount,
+    oldestMessageId,
+    newestMessageId,
+    loadHistory,
+    sendMessage,
+    editMessage,
+    deleteMessage,
+    addReaction,
+    removeReaction,
+    setReplyTo,
+    cancelReply,
+    setEditing,
+    cancelEditing,
+    clearMessages,
+    handleNewMessage,
+    handleMessageEdited,
+    handleMessageDeleted,
+    handleReactionAdded,
+    handleReactionRemoved,
+  }
+}

package/src/composables/useErrors.stories.ts

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseErrorsDemo from './__demo__/UseErrorsDemo.vue'
+
+const meta = {
+  title: 'Composables/useErrors',
+  component: UseErrorsDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:shared-state'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useErrors()\` is a **module-scoped shared state** composable. It returns a
+single \`errorMessages: Ref<string[]>\` plus \`addError\`, \`removeError\`,
+\`clearErrors\`. Every component that calls \`useErrors()\` sees the same
+array.
+
+Pattern: call \`addError(msg)\` from anywhere in your app, render
+\`errorMessages\` once in a toast / banner component.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'You want a single global error queue any component can append to',
+        'Multi-component error surface (banner + log + analytics)',
+      ],
+      whenNotToUse: [
+        'Form-field-level validation errors — keep those local',
+        'You need per-component error isolation — useErrors is global',
+      ],
+      related: ['useToast', 'ExperienceFlow (onError)'],
+    },
+  },
+} satisfies Meta<typeof UseErrorsDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Add messages one at a time, remove individually, or clear the lot. The JSON
+ * dump shows the live state of `errorMessages`.
+ */
+export const SharedQueue: Story = {}

package/src/composables/useErrors.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useErrors } from './useErrors'
+
+describe('useErrors', () => {
+  beforeEach(() => {
+    // Clear shared state between tests
+    const { clearErrors } = useErrors()
+    clearErrors()
+  })
+
+  it('initializes with empty errorMessages array', () => {
+    const { errorMessages } = useErrors()
+    expect(errorMessages.value).toEqual([])
+  })
+
+  it('addError adds a message', () => {
+    const { errorMessages, addError } = useErrors()
+    addError('Error message 1')
+    expect(errorMessages.value).toEqual(['Error message 1'])
+  })
+
+  it('addError adds multiple messages', () => {
+    const { errorMessages, addError } = useErrors()
+    addError('Error message 1')
+    addError('Error message 2')
+    addError('Error message 3')
+    expect(errorMessages.value).toEqual([
+      'Error message 1',
+      'Error message 2',
+      'Error message 3',
+    ])
+  })
+
+  it('removeError removes by index', () => {
+    const { errorMessages, addError, removeError } = useErrors()
+    addError('Error message 1')
+    addError('Error message 2')
+    addError('Error message 3')
+
+    removeError(1)
+    expect(errorMessages.value).toEqual(['Error message 1', 'Error message 3'])
+
+    removeError(0)
+    expect(errorMessages.value).toEqual(['Error message 3'])
+  })
+
+  it('clearErrors resets to empty', () => {
+    const { errorMessages, addError, clearErrors } = useErrors()
+    addError('Error message 1')
+    addError('Error message 2')
+    expect(errorMessages.value.length).toBe(2)
+
+    clearErrors()
+    expect(errorMessages.value).toEqual([])
+  })
+
+  it('shared state across multiple calls (both calls return same ref)', () => {
+    const instance1 = useErrors()
+    const instance2 = useErrors()
+
+    // Verify they share the same ref
+    expect(instance1.errorMessages).toBe(instance2.errorMessages)
+
+    // Add error from instance1
+    instance1.addError('Error from instance 1')
+    expect(instance2.errorMessages.value).toEqual(['Error from instance 1'])
+
+    // Add error from instance2
+    instance2.addError('Error from instance 2')
+    expect(instance1.errorMessages.value).toEqual([
+      'Error from instance 1',
+      'Error from instance 2',
+    ])
+
+    // Clear from instance1 affects instance2
+    instance1.clearErrors()
+    expect(instance2.errorMessages.value).toEqual([])
+  })
+})

package/src/composables/useErrors.ts

@@ -0,0 +1,36 @@
+/**
+ * Tiny shared error-banner store. Components call `addError(msg)` from
+ * anywhere; a top-level banner reads `errorMessages` and shows them with
+ * `removeError` / `clearErrors` controls.
+ */
+import { ref, type Ref } from 'vue'
+
+export interface UseErrorsReturn {
+  errorMessages: Ref<string[]>
+  addError: (message: string) => void
+  removeError: (index: number) => void
+  clearErrors: () => void
+}
+
+const errorMessages = ref<string[]>([])
+
+export function useErrors(): UseErrorsReturn {
+  const addError = (message: string) => {
+    errorMessages.value.push(message)
+  }
+
+  const removeError = (index: number) => {
+    errorMessages.value.splice(index, 1)
+  }
+
+  const clearErrors = () => {
+    errorMessages.value = []
+  }
+
+  return {
+    errorMessages,
+    addError,
+    removeError,
+    clearErrors,
+  }
+}

package/src/composables/useExperience.stories.ts

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseExperienceDemo from './__demo__/UseExperienceDemo.vue'
+
+const meta = {
+  title: 'Composables/useExperience',
+  component: UseExperienceDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:state-machine', 'pattern:experience-flow'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useExperience({ pages, api?, initialContext?, onComplete?, onError? })\` is
+the headless orchestrator that powers the [Experience Flow](?path=/docs/experience-experienceflow--docs)
+system. It owns the page index, a reactive \`context\` object, busy/error
+state, and the action-dispatch pipeline.
+
+Pass it an ordered array of \`{ name, component, props?, when?, action?,
+resultKey? }\` definitions. Pages emit \`next(data)\` to advance and \`back()\`
+to retreat. Each page can:
+
+- Be **skipped reactively** via \`when: (ctx) => boolean\`
+- Trigger an **action** between steps: a named operation on the api adapter,
+  an inline async function, or \`false\` to disable
+- Stash the action's return value into \`context[resultKey]\` (defaults to
+  page name)
+
+Returns refs you can drive any UI off of: \`currentPage\`, \`pageName\`,
+\`index\`, \`isFirst\`, \`isLast\`, \`busy\`, \`error\`. Use
+\`<ExperienceFlow :flow>\` for the standard renderer, or roll your own.
+
+See [the Experience Flow guide](https://gramercytech.github.io/gxp-documentation/gx-appui/experience-flow/overview)
+for the full reference.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Multi-stage kiosk / photo-booth / AI experience flows',
+        'You need branching, skipping, async actions between steps',
+        'You want a reactive shared context across pages without a store',
+      ],
+      whenNotToUse: [
+        'Single-page forms — useForm is enough',
+        'Free-form router-driven app — use vue-router',
+      ],
+      related: [
+        'ExperienceFlow',
+        'useExperienceApi',
+        'withExperienceDefaults',
+        'WelcomePage',
+        'TermsPage',
+        'CameraPage',
+        'FinalPage',
+      ],
+    },
+  },
+} satisfies Meta<typeof UseExperienceDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Three-page sandbox with a side panel that shows the orchestrator's state
+ * live. The side buttons jump directly via \`flow.goTo(name)\`. "next" emits
+ * advance and lets the flow's onComplete loop you back to start.
+ */
+export const StateInspector: Story = {}

package/src/composables/useMedia.stories.ts

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseMediaDemo from './__demo__/UseMediaDemo.vue'
+
+const meta = {
+  title: 'Composables/useMedia',
+  component: UseMediaDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:media', 'pattern:webrtc'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useMedia()\` is the swiss-army-knife composable for plugin-side
+camera + microphone + recording. It encapsulates:
+
+- **Device enumeration** (\`devices\`, \`setVideoDevice\`, \`setAudioDevice\`)
+- **Live streams** (\`videoStream\`, \`audioStream\`)
+- **MediaRecorder** wrapper with \`startRecording\` / \`stopRecording\`,
+  webm-duration fix, and auto-revoke of object URLs
+- **Photo capture** (\`photoBlob\`, \`photoURL\`)
+- **Canvas helpers** — \`scaleCanvas\`, \`drawToCanvas\` — for compositing
+  mirrored / aspect-corrected frames
+
+Everything is reactive, so binding any of the refs to your template "just
+works." Wrap your camera/mic logic on top of this rather than calling
+\`getUserMedia\` directly.
+
+The experience-flow's CameraPage, VideoCapturePage, and AudioCapturePage are
+all built on top of this — read those for reference patterns.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Photo-booth / video-capture / audio-recording features',
+        'You want device enumeration with reactive switching',
+        'Aspect-corrected canvas rendering of captured frames',
+      ],
+      whenNotToUse: [
+        'Streaming AI voice with PCM chunks — use useStreamingAudio',
+        'Multi-participant WebRTC chat — use useChatMedia',
+        'Just need a still photo from a single getUserMedia call — fine to write directly',
+      ],
+      related: ['CameraPage', 'VideoCapturePage', 'AudioCapturePage', 'AudioVisualizer', 'useStreamingAudio', 'useChatMedia'],
+    },
+  },
+} satisfies Meta<typeof UseMediaDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Click "camera" / "mic" to request permission and start the streams. The
+ * "photo" button uses \`scaleCanvas\` + \`drawToCanvas\` to capture a still
+ * frame from the video element. "start record" → "stop record" produces an
+ * audio/video Blob (whose URL appears below).
+ */
+export const FullSurface: Story = {}

package/src/composables/useMedia.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useMedia } from './useMedia'
+
+describe('useMedia', () => {
+  let media: ReturnType<typeof useMedia>
+
+  beforeEach(() => {
+    media = useMedia()
+  })
+
+  it('should return all expected properties', () => {
+    expect(media).toHaveProperty('devices')
+    expect(media).toHaveProperty('videoStream')
+    expect(media).toHaveProperty('videoDeviceId')
+    expect(media).toHaveProperty('audioStream')
+    expect(media).toHaveProperty('audioDeviceId')
+    expect(media).toHaveProperty('changingDevice')
+    expect(media).toHaveProperty('videoBlob')
+    expect(media).toHaveProperty('videoURL')
+    expect(media).toHaveProperty('audioBlob')
+    expect(media).toHaveProperty('audioURL')
+    expect(media).toHaveProperty('audioVolumeWave')
+    expect(media).toHaveProperty('photoBlob')
+    expect(media).toHaveProperty('photoURL')
+    expect(media).toHaveProperty('facingMode')
+    expect(media).toHaveProperty('currentFacingMode')
+    expect(media).toHaveProperty('getTrack')
+    expect(media).toHaveProperty('setVideoDevice')
+    expect(media).toHaveProperty('setAudioDevice')
+    expect(media).toHaveProperty('startRecording')
+    expect(media).toHaveProperty('stopRecording')
+    expect(media).toHaveProperty('processUploadedVideo')
+    expect(media).toHaveProperty('scaleCanvas')
+    expect(media).toHaveProperty('drawToCanvas')
+    expect(media).toHaveProperty('resetState')
+    expect(media).toHaveProperty('requestCameraPermission')
+    expect(media).toHaveProperty('requestDevicePermission')
+    expect(media).toHaveProperty('getAvailableDevices')
+    expect(media).toHaveProperty('isMobileDevice')
+  })
+
+  it('should have correct initial state for reactive refs', () => {
+    expect(media.devices.value).toEqual([])
+    expect(media.videoStream.value).toBeNull()
+    expect(media.audioStream.value).toBeNull()
+    expect(media.changingDevice.value).toBe(false)
+    expect(media.videoBlob.value).toBeNull()
+    expect(media.videoURL.value).toBeNull()
+    expect(media.audioBlob.value).toBeNull()
+    expect(media.audioURL.value).toBeNull()
+    expect(media.audioVolumeWave.value).toEqual([])
+    expect(media.photoBlob.value).toBeNull()
+    expect(media.photoURL.value).toBeNull()
+    expect(media.currentFacingMode.value).toBe('user')
+  })
+
+  it('should have undefined initial values for computed refs', () => {
+    expect(media.videoDeviceId.value).toBeUndefined()
+    expect(media.audioDeviceId.value).toBeUndefined()
+    expect(media.facingMode.value).toBeUndefined()
+  })
+
+  it('should return false for isMobileDevice in jsdom', () => {
+    expect(media.isMobileDevice()).toBe(false)
+  })
+
+  it('should reset state when resetState is called', () => {
+    // Modify some state
+    media.changingDevice.value = true
+    media.videoBlob.value = new Blob(['test'], { type: 'video/webm' })
+    media.audioBlob.value = new Blob(['audio'], { type: 'audio/webm' })
+    media.audioVolumeWave.value = [0.5, 0.7, 0.3]
+    media.photoBlob.value = new Blob(['photo'], { type: 'image/png' })
+
+    // Reset
+    media.resetState()
+
+    // Verify reset
+    expect(media.changingDevice.value).toBe(false)
+    expect(media.videoBlob.value).toBeNull()
+    expect(media.audioBlob.value).toBeNull()
+    expect(media.audioVolumeWave.value).toEqual([])
+    expect(media.photoBlob.value).toBeNull()
+  })
+
+  it('should have function properties with correct types', () => {
+    expect(typeof media.getTrack).toBe('function')
+    expect(typeof media.setVideoDevice).toBe('function')
+    expect(typeof media.setAudioDevice).toBe('function')
+    expect(typeof media.startRecording).toBe('function')
+    expect(typeof media.stopRecording).toBe('function')
+    expect(typeof media.processUploadedVideo).toBe('function')
+    expect(typeof media.scaleCanvas).toBe('function')
+    expect(typeof media.drawToCanvas).toBe('function')
+    expect(typeof media.resetState).toBe('function')
+    expect(typeof media.requestCameraPermission).toBe('function')
+    expect(typeof media.requestDevicePermission).toBe('function')
+    expect(typeof media.getAvailableDevices).toBe('function')
+    expect(typeof media.isMobileDevice).toBe('function')
+  })
+
+  it('should return undefined when getTrack is called with null stream', () => {
+    const result = media.getTrack(null)
+    expect(result).toBeUndefined()
+  })
+})