@gxp-dev/app-ui 0.1.0

package/src/composables/useChatMedia.ts

@@ -0,0 +1,298 @@
+/**
+ * Captures and uploads chat attachments (image, audio, video). Wraps the
+ * media access + upload pipeline so a `MessageComposer` can drop the
+ * resulting URL into a message payload.
+ */
+import { ref, computed, onBeforeUnmount, type ComputedRef, type Ref } from 'vue'
+
+export type ChatTrackKind = 'audio' | 'video' | 'screen'
+
+export interface ChatTrackHandlers {
+  /** Called when a new local track is started. Wire it to your transport here. */
+  onTrackStarted?: (track: MediaStreamTrack, kind: ChatTrackKind) => void | Promise<void>
+  /** Called right before a local track is stopped, so you can close the producer. */
+  onTrackStopping?: (kind: ChatTrackKind) => void | Promise<void>
+  /** Called when an audio producer is paused (mute). */
+  onAudioPaused?: () => void | Promise<void>
+  /** Called when an audio producer is resumed (unmute). */
+  onAudioResumed?: () => void | Promise<void>
+  /** Called when a video producer is paused (camera off). */
+  onVideoPaused?: () => void | Promise<void>
+  /** Called when a video producer is resumed (camera on). */
+  onVideoResumed?: () => void | Promise<void>
+}
+
+export interface UseChatMediaOptions {
+  audioConstraints?: MediaTrackConstraints
+  videoConstraints?: MediaTrackConstraints
+  screenConstraints?: DisplayMediaStreamOptions
+  handlers?: ChatTrackHandlers
+}
+
+export interface ChatConnectionQuality {
+  rtt: number | null
+  packetLoss: number | null
+  jitter: number | null
+}
+
+export interface UseChatMediaReturn {
+  // Local streams
+  localAudioStream: Ref<MediaStream | null>
+  localVideoStream: Ref<MediaStream | null>
+  localScreenStream: Ref<MediaStream | null>
+
+  // State
+  isMuted: Ref<boolean>
+  isVideoOff: Ref<boolean>
+  isScreenSharing: Ref<boolean>
+
+  // Computed conveniences
+  hasAudio: ComputedRef<boolean>
+  hasVideo: ComputedRef<boolean>
+
+  // Remote participant streams (keyed by participant id)
+  participantStreams: Ref<Map<string, MediaStream>>
+
+  // Local lifecycle
+  startAudioCapture: (constraints?: MediaTrackConstraints) => Promise<MediaStream>
+  stopAudioCapture: () => Promise<void>
+  startVideoCapture: (constraints?: MediaTrackConstraints) => Promise<MediaStream>
+  stopVideoCapture: () => Promise<void>
+  startScreenShare: (options?: DisplayMediaStreamOptions) => Promise<MediaStream>
+  stopScreenShare: () => Promise<void>
+  toggleMute: () => Promise<void>
+  toggleVideo: () => Promise<void>
+
+  // Participant streams
+  setParticipantStream: (participantId: string, stream: MediaStream) => void
+  addParticipantTrack: (participantId: string, track: MediaStreamTrack) => MediaStream
+  removeParticipant: (participantId: string) => void
+  getParticipantStream: (participantId: string) => MediaStream | undefined
+
+  // Cleanup
+  cleanup: () => void
+}
+
+const DEFAULT_AUDIO: MediaTrackConstraints = {
+  echoCancellation: true,
+  noiseSuppression: true,
+  autoGainControl: true,
+}
+
+const DEFAULT_VIDEO: MediaTrackConstraints = {
+  width: { ideal: 1280 },
+  height: { ideal: 720 },
+  frameRate: { ideal: 30 },
+}
+
+const DEFAULT_SCREEN: DisplayMediaStreamOptions = {
+  video: {
+    width: { ideal: 1920 },
+    height: { ideal: 1080 },
+    frameRate: { ideal: 30 },
+  } as MediaTrackConstraints,
+  audio: false,
+}
+
+/**
+ * Headless multi-participant chat media manager.
+ *
+ * Owns local audio/video/screen capture lifecycle and a registry of remote
+ * participant streams. Transport (Mediasoup, plain WebRTC peerconnections,
+ * server-relayed RTC, …) is your concern: provide `handlers.onTrackStarted`
+ * to push the local tracks to your producers, and call `addParticipantTrack`
+ * when a remote track arrives.
+ */
+export function useChatMedia(options: UseChatMediaOptions = {}): UseChatMediaReturn {
+  const handlers = options.handlers ?? {}
+  const audioConstraints = { ...DEFAULT_AUDIO, ...options.audioConstraints }
+  const videoConstraints = { ...DEFAULT_VIDEO, ...options.videoConstraints }
+  const screenOptions = { ...DEFAULT_SCREEN, ...options.screenConstraints }
+
+  const localAudioStream = ref<MediaStream | null>(null)
+  const localVideoStream = ref<MediaStream | null>(null)
+  const localScreenStream = ref<MediaStream | null>(null)
+
+  const isMuted = ref(false)
+  const isVideoOff = ref(true)
+  const isScreenSharing = ref(false)
+
+  const participantStreams = ref<Map<string, MediaStream>>(new Map())
+
+  const hasAudio = computed(() => localAudioStream.value !== null)
+  const hasVideo = computed(() => localVideoStream.value !== null)
+
+  const startAudioCapture = async (
+    constraints: MediaTrackConstraints = {},
+  ): Promise<MediaStream> => {
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: { ...audioConstraints, ...constraints },
+    })
+    localAudioStream.value = stream
+    isMuted.value = false
+    const track = stream.getAudioTracks()[0]
+    if (track) await handlers.onTrackStarted?.(track, 'audio')
+    return stream
+  }
+
+  const stopAudioCapture = async (): Promise<void> => {
+    if (!localAudioStream.value) return
+    await handlers.onTrackStopping?.('audio')
+    localAudioStream.value.getTracks().forEach((t) => t.stop())
+    localAudioStream.value = null
+    isMuted.value = false
+  }
+
+  const startVideoCapture = async (
+    constraints: MediaTrackConstraints = {},
+  ): Promise<MediaStream> => {
+    const stream = await navigator.mediaDevices.getUserMedia({
+      video: { ...videoConstraints, ...constraints },
+    })
+    localVideoStream.value = stream
+    isVideoOff.value = false
+    const track = stream.getVideoTracks()[0]
+    if (track) await handlers.onTrackStarted?.(track, 'video')
+    return stream
+  }
+
+  const stopVideoCapture = async (): Promise<void> => {
+    if (!localVideoStream.value) return
+    await handlers.onTrackStopping?.('video')
+    localVideoStream.value.getTracks().forEach((t) => t.stop())
+    localVideoStream.value = null
+    isVideoOff.value = true
+  }
+
+  const startScreenShare = async (
+    optionsOverride: DisplayMediaStreamOptions = {},
+  ): Promise<MediaStream> => {
+    const stream = await navigator.mediaDevices.getDisplayMedia({
+      ...screenOptions,
+      ...optionsOverride,
+    })
+    localScreenStream.value = stream
+    isScreenSharing.value = true
+    const track = stream.getVideoTracks()[0]
+    if (track) {
+      track.onended = () => {
+        void stopScreenShare()
+      }
+      await handlers.onTrackStarted?.(track, 'screen')
+    }
+    return stream
+  }
+
+  const stopScreenShare = async (): Promise<void> => {
+    if (!localScreenStream.value) return
+    await handlers.onTrackStopping?.('screen')
+    localScreenStream.value.getTracks().forEach((t) => t.stop())
+    localScreenStream.value = null
+    isScreenSharing.value = false
+  }
+
+  const toggleMute = async (): Promise<void> => {
+    if (!localAudioStream.value) return
+    if (isMuted.value) {
+      localAudioStream.value.getAudioTracks().forEach((t) => (t.enabled = true))
+      isMuted.value = false
+      await handlers.onAudioResumed?.()
+    } else {
+      localAudioStream.value.getAudioTracks().forEach((t) => (t.enabled = false))
+      isMuted.value = true
+      await handlers.onAudioPaused?.()
+    }
+  }
+
+  const toggleVideo = async (): Promise<void> => {
+    if (isVideoOff.value) {
+      if (!localVideoStream.value) {
+        await startVideoCapture()
+      } else {
+        localVideoStream.value.getVideoTracks().forEach((t) => (t.enabled = true))
+        await handlers.onVideoResumed?.()
+      }
+      isVideoOff.value = false
+    } else {
+      if (localVideoStream.value) {
+        localVideoStream.value.getVideoTracks().forEach((t) => (t.enabled = false))
+        await handlers.onVideoPaused?.()
+      }
+      isVideoOff.value = true
+    }
+  }
+
+  const setParticipantStream = (participantId: string, stream: MediaStream): void => {
+    participantStreams.value.set(participantId, stream)
+  }
+
+  const addParticipantTrack = (participantId: string, track: MediaStreamTrack): MediaStream => {
+    let stream = participantStreams.value.get(participantId)
+    if (!stream) {
+      stream = new MediaStream()
+      participantStreams.value.set(participantId, stream)
+    }
+    stream.addTrack(track)
+    return stream
+  }
+
+  const removeParticipant = (participantId: string): void => {
+    const stream = participantStreams.value.get(participantId)
+    if (stream) {
+      stream.getTracks().forEach((t) => t.stop())
+      participantStreams.value.delete(participantId)
+    }
+  }
+
+  const getParticipantStream = (participantId: string): MediaStream | undefined =>
+    participantStreams.value.get(participantId)
+
+  const cleanup = (): void => {
+    if (localAudioStream.value) {
+      localAudioStream.value.getTracks().forEach((t) => t.stop())
+      localAudioStream.value = null
+    }
+    if (localVideoStream.value) {
+      localVideoStream.value.getTracks().forEach((t) => t.stop())
+      localVideoStream.value = null
+    }
+    if (localScreenStream.value) {
+      localScreenStream.value.getTracks().forEach((t) => t.stop())
+      localScreenStream.value = null
+    }
+    participantStreams.value.forEach((stream) => {
+      stream.getTracks().forEach((t) => t.stop())
+    })
+    participantStreams.value.clear()
+    isMuted.value = false
+    isVideoOff.value = true
+    isScreenSharing.value = false
+  }
+
+  onBeforeUnmount(cleanup)
+
+  return {
+    localAudioStream,
+    localVideoStream,
+    localScreenStream,
+    isMuted,
+    isVideoOff,
+    isScreenSharing,
+    hasAudio,
+    hasVideo,
+    participantStreams,
+    startAudioCapture,
+    stopAudioCapture,
+    startVideoCapture,
+    stopVideoCapture,
+    startScreenShare,
+    stopScreenShare,
+    toggleMute,
+    toggleVideo,
+    setParticipantStream,
+    addParticipantTrack,
+    removeParticipant,
+    getParticipantStream,
+    cleanup,
+  }
+}

package/src/composables/useChatMessages.stories.ts

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseChatMessagesDemo from './__demo__/UseChatMessagesDemo.vue'
+
+const meta = {
+  title: 'Composables/useChatMessages',
+  component: UseChatMessagesDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:chat', 'pattern:headless'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useChatMessages({ api })\` is a **headless state container** for chat-style
+message lists. It owns the reactive list, pagination cursor, reply / edit UI
+state, and a set of push-event handlers (\`handleNewMessage\`,
+\`handleReactionAdded\`, etc.) you call from your WebSocket / SSE / polling
+layer.
+
+I/O is **your** responsibility — you pass in an \`api\` object with
+\`loadHistory\`, \`sendMessage\`, \`editMessage\`, etc., and the composable
+wraps those calls with optimistic local updates. This lets you back the chat
+with REST, GraphQL, RPC, or a fully in-memory store.
+
+The composable is decoupled from any specific store or HTTP client, so the
+same code runs in plugins, tests, and Storybook demos without modification.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Building a chat UI (group chat, support inbox, AI assistant transcript)',
+        'You need reply + edit + reaction state plus push-event sync',
+        'You want optimistic local updates without rolling your own',
+      ],
+      whenNotToUse: [
+        'Single-turn message form — a ref is enough',
+        'Server-side rendered transcript with no live updates — pre-render the list',
+      ],
+      related: ['MessageList', 'MessageComposer', 'ChatTranscript', 'useWebSocket'],
+    },
+  },
+} satisfies Meta<typeof UseChatMessagesDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Wired against a self-contained in-memory mock api. Try sending a message,
+ * clicking reactions, deleting, and "Simulate inbound" to trigger a push-event
+ * handler.
+ */
+export const InMemoryDemo: Story = {}

package/src/composables/useChatMessages.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi } from 'vitest'
+import { useChatMessages, type ChatMessagesApi, type ChatMessage } from './useChatMessages'
+
+const makeApi = (): ChatMessagesApi => ({
+  loadHistory: vi.fn(async () => ({ messages: [] as ChatMessage[], hasMore: false })),
+  sendMessage: vi.fn(async (input) => ({ id: 99, content: input.content })),
+  editMessage: vi.fn(async () => undefined),
+  deleteMessage: vi.fn(async () => undefined),
+  addReaction: vi.fn(async () => undefined),
+  removeReaction: vi.fn(async () => undefined),
+})
+
+describe('useChatMessages', () => {
+  it('loadHistory replaces the list on initial load', async () => {
+    const api = makeApi()
+    api.loadHistory = vi.fn(async () => ({
+      messages: [
+        { id: 1, content: 'hi' },
+        { id: 2, content: 'there' },
+      ],
+      hasMore: false,
+    }))
+    const chat = useChatMessages({ api })
+    await chat.loadHistory()
+    expect(chat.messages.value).toHaveLength(2)
+    expect(chat.hasMore.value).toBe(false)
+  })
+
+  it('loadHistory prepends older messages when beforeId is set', async () => {
+    const api = makeApi()
+    api.loadHistory = vi
+      .fn()
+      .mockResolvedValueOnce({ messages: [{ id: 5, content: 'newer' }], hasMore: true })
+      .mockResolvedValueOnce({ messages: [{ id: 3, content: 'older' }], hasMore: false })
+    const chat = useChatMessages({ api })
+    await chat.loadHistory()
+    await chat.loadHistory({ beforeId: 5 })
+    expect(chat.messages.value.map((m) => m.id)).toEqual([3, 5])
+  })
+
+  it('sendMessage clears the reply state and forwards reply_to', async () => {
+    const api = makeApi()
+    const chat = useChatMessages({ api })
+    chat.setReplyTo({ id: 1, content: 'q' })
+    await chat.sendMessage('a')
+    expect(api.sendMessage).toHaveBeenCalledWith({ content: 'a', reply_to: 1, attachments: [] })
+    expect(chat.replyingTo.value).toBeNull()
+  })
+
+  it('editMessage updates content optimistically', async () => {
+    const api = makeApi()
+    const chat = useChatMessages({ api })
+    chat.handleNewMessage({ id: 1, content: 'old' })
+    chat.setEditing(chat.messages.value[0])
+    await chat.editMessage(1, 'new')
+    expect(chat.messages.value[0].content).toBe('new')
+    expect(chat.messages.value[0].is_edited).toBe(true)
+    expect(chat.editingMessage.value).toBeNull()
+  })
+
+  it('deleteMessage marks the message deleted with configurable placeholder', async () => {
+    const api = makeApi()
+    const chat = useChatMessages({ api, deletedPlaceholder: '(removed)' })
+    chat.handleNewMessage({ id: 1, content: 'old' })
+    await chat.deleteMessage(1)
+    expect(chat.messages.value[0].is_deleted).toBe(true)
+    expect(chat.messages.value[0].content).toBe('(removed)')
+  })
+
+  it('handleNewMessage dedupes by id', () => {
+    const chat = useChatMessages({ api: makeApi() })
+    chat.handleNewMessage({ id: 1, content: 'x' })
+    chat.handleNewMessage({ id: 1, content: 'x' })
+    expect(chat.messages.value).toHaveLength(1)
+  })
+
+  it('handleReactionAdded creates or updates the reaction entry', () => {
+    const chat = useChatMessages({ api: makeApi() })
+    chat.handleNewMessage({ id: 1, content: 'x' })
+    chat.handleReactionAdded({ messageId: 1, emoji: '👍', participantId: 'a' })
+    chat.handleReactionAdded({ messageId: 1, emoji: '👍', participantId: 'b' })
+    chat.handleReactionAdded({ messageId: 1, emoji: '🎉', participantId: 'a' })
+    const reactions = chat.messages.value[0].reactions!
+    expect(reactions).toHaveLength(2)
+    expect(reactions.find((r) => r.emoji === '👍')!.count).toBe(2)
+  })
+
+  it('handleReactionRemoved drops the reaction when its count hits zero', () => {
+    const chat = useChatMessages({ api: makeApi() })
+    chat.handleNewMessage({ id: 1, content: 'x' })
+    chat.handleReactionAdded({ messageId: 1, emoji: '👍', participantId: 'a' })
+    chat.handleReactionRemoved({ messageId: 1, emoji: '👍', participantId: 'a' })
+    expect(chat.messages.value[0].reactions).toHaveLength(0)
+  })
+
+  it('clearMessages wipes state', () => {
+    const chat = useChatMessages({ api: makeApi() })
+    chat.handleNewMessage({ id: 1, content: 'x' })
+    chat.setReplyTo({ id: 1, content: 'x' })
+    chat.clearMessages()
+    expect(chat.messages.value).toEqual([])
+    expect(chat.replyingTo.value).toBeNull()
+    expect(chat.hasMore.value).toBe(true)
+  })
+})