@gxp-dev/app-ui 0.1.0

package/src/composables/useAnimations.ts

@@ -0,0 +1,108 @@
+/**
+ * Page-transition animation helpers. Maps a `page_animation_speed` +
+ * `page_animation_type` global setting to the matching `animate.css`
+ * classes and exposes `animatePage()` to drive the in/out transition
+ * between portal pages.
+ */
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+
+export interface AnimationSettings {
+  page_animation_speed?: string
+  page_animation_type?: string
+}
+
+export interface UseAnimationsReturn {
+  animatingClasses: ComputedRef<string[]>
+  pageAnimation: Ref<string>
+  init: (props: { globalSettings?: AnimationSettings }) => void
+  animatePage: (vars?: AnimationVars, reverse?: boolean) => Promise<void>
+}
+
+interface AnimationVars {
+  pluginVars: {
+    animate_next?: boolean
+    animate_prev?: boolean
+  }
+}
+
+const timingLookup: Record<string, number> = {
+  animate__slower: 3000,
+  animate__slow: 2000,
+  animate__normal: 1000,
+  animate__fast: 800,
+  animate__faster: 500,
+}
+
+const correspondingAnimationLookup: Record<string, string> = {
+  animate__fadeIn: 'animate__fadeOut',
+  animate__flipInX: 'animate__flipOutX',
+  animate__backInRight: 'animate__backOutLeft',
+  animate__slideInUp: 'animate__slideOutUp',
+  animate__zoomIn: 'animate__zoomOut',
+  animate__slideInDown: 'animate__slideOutDown',
+  animate__backInLeft: 'animate__backOutRight',
+}
+
+const reverseAnimationLookup: Record<string, string> = {
+  animate__fadeIn: 'animate__fadeIn',
+  animate__flipInX: 'animate__flipInX',
+  animate__backInRight: 'animate__backInLeft',
+  animate__slideInUp: 'animate__slideInDown',
+  animate__zoomIn: 'animate__zoomIn',
+}
+
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+const pageAnimation = ref('')
+const speed = ref('')
+const type = ref('')
+
+const animatingClasses = computed(() => [
+  'animate__animated',
+  speed.value,
+  pageAnimation.value,
+])
+
+let currentVars: AnimationVars | undefined
+
+export function useAnimations(): UseAnimationsReturn {
+  const init = (props: { globalSettings?: AnimationSettings }) => {
+    if (props.globalSettings) {
+      speed.value = props.globalSettings.page_animation_speed ?? ''
+      type.value = props.globalSettings.page_animation_type ?? ''
+    }
+  }
+
+  const animateNextPage = async (animationType: string) => {
+    pageAnimation.value = animationType
+    await delay(timingLookup[speed.value] ?? 1000)
+    pageAnimation.value = ''
+  }
+
+  const animatePage = async (vars?: AnimationVars, reverse = false) => {
+    if (vars) currentVars = vars
+    if (!currentVars) return
+    if (type.value === 'none') return
+
+    const shouldAnimate = type.value && speed.value && (
+      (!reverse && (currentVars.pluginVars.animate_next ?? true)) ||
+      (reverse && (currentVars.pluginVars.animate_prev ?? true))
+    )
+
+    if (shouldAnimate) {
+      const finalType = reverse
+        ? reverseAnimationLookup[type.value] ?? type.value
+        : type.value
+      pageAnimation.value = correspondingAnimationLookup[finalType] ?? ''
+      await delay(timingLookup[speed.value] ?? 1000)
+      await animateNextPage(finalType)
+    }
+  }
+
+  return {
+    init,
+    animatingClasses,
+    pageAnimation,
+    animatePage,
+  }
+}

package/src/composables/useCameraBorder.stories.ts

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseCameraBorderDemo from './__demo__/UseCameraBorderDemo.vue'
+
+const meta = {
+  title: 'Composables/useCameraBorder',
+  component: UseCameraBorderDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:canvas', 'pattern:image'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useCameraBorder()\` composites a transparent PNG border on top of a captured
+image using a canvas. State: \`selectedBorder\` (mutable), \`canvasDimensions\`
+(set the output size). Method: \`drawBorder(imageSrc)\` returns a data URL of
+the composed image.
+
+Useful for photo booths and kiosk experiences with branded frame overlays. Set
+\`canvasDimensions\` once when you know the image size; switch
+\`selectedBorder\` between frames as the user picks.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Photo-booth flows with selectable branded frames',
+        'Compositing a logo / watermark onto a user-captured image',
+      ],
+      whenNotToUse: [
+        'Real-time video overlay — this composables operates on a static still',
+        'Complex multi-layer compositing — use a dedicated canvas library',
+      ],
+      related: ['CameraPage', 'CameraReviewPage', 'PhotoEditPage'],
+    },
+  },
+} satisfies Meta<typeof UseCameraBorderDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Pick a frame, click `drawBorder()` to composite it onto a sample photo, see
+ * the result. The reactive state is shown below.
+ */
+export const FrameComposite: Story = {}

package/src/composables/useCameraBorder.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { useCameraBorder } from './useCameraBorder'
+
+// Mock canvas context
+const mockContext = {
+  drawImage: vi.fn(),
+}
+
+// Mock canvas element
+const mockCanvas = {
+  width: 0,
+  height: 0,
+  getContext: vi.fn(() => mockContext),
+  toDataURL: vi.fn(() => 'data:image/png;base64,mockdata'),
+}
+
+// Track Image instances to resolve their onload
+let imageInstances: Array<{ src: string; crossOrigin: string; onload: (() => void) | null; onerror: ((err: unknown) => void) | null }> = []
+
+describe('useCameraBorder', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+    imageInstances = []
+
+    vi.spyOn(document, 'createElement').mockImplementation((tagName: string) => {
+      if (tagName === 'canvas') {
+        return mockCanvas as unknown as HTMLCanvasElement
+      }
+      // Fall through for other elements
+      return document.createElement.call(document, tagName) as HTMLElement
+    })
+
+    // Mock the global Image constructor
+    vi.stubGlobal('Image', class MockImage {
+      src = ''
+      crossOrigin = ''
+      onload: (() => void) | null = null
+      onerror: ((err: unknown) => void) | null = null
+
+      constructor() {
+        imageInstances.push(this)
+      }
+    })
+
+    mockContext.drawImage.mockClear()
+    mockCanvas.getContext.mockClear()
+    mockCanvas.toDataURL.mockClear()
+    mockCanvas.width = 0
+    mockCanvas.height = 0
+  })
+
+  it('returns all expected properties', () => {
+    const result = useCameraBorder()
+    expect(result).toHaveProperty('selectedBorder')
+    expect(result).toHaveProperty('canvasDimensions')
+    expect(result).toHaveProperty('drawBorder')
+    expect(result).toHaveProperty('reset')
+  })
+
+  it('has correct initial state', () => {
+    const { selectedBorder, canvasDimensions } = useCameraBorder()
+    expect(selectedBorder.value).toBeNull()
+    expect(canvasDimensions.value).toEqual({ width: 0, height: 0 })
+  })
+
+  describe('reset', () => {
+    it('clears selectedBorder and canvasDimensions', () => {
+      const { selectedBorder, canvasDimensions, reset } = useCameraBorder()
+
+      selectedBorder.value = { src: 'https://example.com/border.png', label: 'Gold' }
+      canvasDimensions.value = { width: 1920, height: 1080 }
+
+      reset()
+
+      expect(selectedBorder.value).toBeNull()
+      expect(canvasDimensions.value).toEqual({ width: 0, height: 0 })
+    })
+  })
+
+  describe('drawBorder', () => {
+    it('creates a canvas with correct dimensions', async () => {
+      const { canvasDimensions, drawBorder } = useCameraBorder()
+      canvasDimensions.value = { width: 800, height: 600 }
+
+      const promise = drawBorder('https://example.com/photo.png')
+
+      // Resolve the base image onload
+      expect(imageInstances.length).toBe(1)
+      expect(imageInstances[0].src).toBe('https://example.com/photo.png')
+      expect(imageInstances[0].crossOrigin).toBe('Anonymous')
+      imageInstances[0].onload!()
+
+      await promise
+
+      expect(mockCanvas.width).toBe(800)
+      expect(mockCanvas.height).toBe(600)
+    })
+
+    it('draws base image onto canvas', async () => {
+      const { canvasDimensions, drawBorder } = useCameraBorder()
+      canvasDimensions.value = { width: 400, height: 300 }
+
+      const promise = drawBorder('https://example.com/base.png')
+
+      imageInstances[0].onload!()
+      await promise
+
+      expect(mockContext.drawImage).toHaveBeenCalledTimes(1)
+      expect(mockContext.drawImage).toHaveBeenCalledWith(
+        imageInstances[0],
+        0,
+        0,
+        400,
+        300,
+      )
+    })
+
+    it('draws border overlay when selectedBorder is set', async () => {
+      const { selectedBorder, canvasDimensions, drawBorder } = useCameraBorder()
+      selectedBorder.value = { src: 'https://example.com/border.png', label: 'Fancy' }
+      canvasDimensions.value = { width: 400, height: 300 }
+
+      const promise = drawBorder('https://example.com/base.png')
+
+      // First image is the base
+      imageInstances[0].onload!()
+      // Wait for the base image promise to resolve, which triggers border load
+      await new Promise((r) => setTimeout(r, 0))
+      // Second image is the border
+      expect(imageInstances.length).toBe(2)
+      expect(imageInstances[1].src).toBe('https://example.com/border.png')
+      imageInstances[1].onload!()
+
+      await promise
+
+      expect(mockContext.drawImage).toHaveBeenCalledTimes(2)
+      // Second call is the border overlay
+      expect(mockContext.drawImage).toHaveBeenCalledWith(
+        imageInstances[1],
+        0,
+        0,
+        400,
+        300,
+      )
+    })
+
+    it('skips border overlay when selectedBorder is null', async () => {
+      const { canvasDimensions, drawBorder } = useCameraBorder()
+      canvasDimensions.value = { width: 400, height: 300 }
+
+      const promise = drawBorder('https://example.com/base.png')
+      imageInstances[0].onload!()
+      await promise
+
+      // Only one drawImage call (base image only)
+      expect(mockContext.drawImage).toHaveBeenCalledTimes(1)
+    })
+
+    it('returns a data URL', async () => {
+      const { canvasDimensions, drawBorder } = useCameraBorder()
+      canvasDimensions.value = { width: 100, height: 100 }
+
+      const promise = drawBorder('https://example.com/base.png')
+      imageInstances[0].onload!()
+      const result = await promise
+
+      expect(result).toBe('data:image/png;base64,mockdata')
+      expect(mockCanvas.toDataURL).toHaveBeenCalledWith('image/png')
+    })
+
+    it('throws when canvas context is null', async () => {
+      mockCanvas.getContext.mockReturnValueOnce(null)
+
+      const { canvasDimensions, drawBorder } = useCameraBorder()
+      canvasDimensions.value = { width: 100, height: 100 }
+
+      await expect(drawBorder('https://example.com/base.png')).rejects.toThrow(
+        'Could not get canvas context',
+      )
+    })
+
+    it('rejects when image fails to load', async () => {
+      const { canvasDimensions, drawBorder } = useCameraBorder()
+      canvasDimensions.value = { width: 100, height: 100 }
+
+      const promise = drawBorder('https://example.com/bad.png')
+      imageInstances[0].onerror!(new Error('Load failed'))
+
+      await expect(promise).rejects.toThrow('Load failed')
+    })
+  })
+})

package/src/composables/useCameraBorder.ts

@@ -0,0 +1,69 @@
+/**
+ * Draws a selected camera-overlay border onto a captured image and emits
+ * the composited result as a data URL. Used by the portal's
+ * photo-capture flow when the active experience has a branded border.
+ */
+import { ref, type Ref } from 'vue'
+
+export interface CameraBorder {
+  src: string
+  label?: string
+}
+
+export interface CanvasDimensions {
+  width: number
+  height: number
+}
+
+export interface UseCameraBorderReturn {
+  selectedBorder: Ref<CameraBorder | null>
+  canvasDimensions: Ref<CanvasDimensions>
+  drawBorder: (imageSrc: string) => Promise<string>
+  reset: () => void
+}
+
+const decodeImage = (src: string): Promise<HTMLImageElement> => {
+  const img = new Image()
+  img.crossOrigin = 'Anonymous'
+  img.src = src
+  return new Promise((resolve, reject) => {
+    img.onload = () => resolve(img)
+    img.onerror = reject
+  })
+}
+
+export function useCameraBorder(): UseCameraBorderReturn {
+  const selectedBorder = ref<CameraBorder | null>(null)
+  const canvasDimensions = ref<CanvasDimensions>({ width: 0, height: 0 })
+
+  const reset = () => {
+    selectedBorder.value = null
+    canvasDimensions.value = { width: 0, height: 0 }
+  }
+
+  const drawBorder = async (imageSrc: string): Promise<string> => {
+    const canvas = document.createElement('canvas')
+    canvas.width = canvasDimensions.value.width
+    canvas.height = canvasDimensions.value.height
+
+    const context = canvas.getContext('2d')
+    if (!context) throw new Error('Could not get canvas context')
+
+    const baseImage = await decodeImage(imageSrc)
+    context.drawImage(baseImage, 0, 0, canvas.width, canvas.height)
+
+    if (selectedBorder.value) {
+      const borderImage = await decodeImage(selectedBorder.value.src)
+      context.drawImage(borderImage, 0, 0, canvas.width, canvas.height)
+    }
+
+    return canvas.toDataURL('image/png')
+  }
+
+  return {
+    selectedBorder,
+    canvasDimensions,
+    drawBorder,
+    reset,
+  }
+}

package/src/composables/useChatMedia.stories.ts

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import UseChatMediaDemo from './__demo__/UseChatMediaDemo.vue'
+
+const meta = {
+  title: 'Composables/useChatMedia',
+  component: UseChatMediaDemo,
+  tags: ['autodocs', 'category:composable', 'pattern:webrtc', 'pattern:multi-participant'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+\`useChatMedia({ handlers })\` is a **transport-agnostic** local media manager
+plus a registry of remote participant streams. It handles \`getUserMedia\` for
+audio and video, \`getDisplayMedia\` for screen sharing, track lifecycle (start
+/ stop / mute / video-off), and tracks remote participants in a
+\`Map<participantId, MediaStream>\`.
+
+It does **not** know about Mediasoup, peer connections, or signaling — those
+plug in via the optional \`handlers\` object. When a local track starts,
+\`onTrackStarted(track, kind)\` fires; pipe the track into your producer
+there. When a remote track arrives, call \`addParticipantTrack(participantId,
+track)\` and the registry updates.
+
+The composable cleans up on unmount automatically. Stop everything early with
+\`cleanup()\`.
+        `,
+      },
+    },
+    usage: {
+      whenToUse: [
+        'Multi-participant audio/video chat with WebRTC',
+        'You want one place for camera/mic/screen lifecycle',
+        'You need a participant-stream registry that updates reactively',
+        'You want transport-agnostic media handling (Mediasoup, peer-to-peer, …)',
+      ],
+      whenNotToUse: [
+        'Single-user camera capture for photo/video — use useMedia instead',
+        'Just an audio analyser for visualization — use AudioVisualizer + useMedia',
+      ],
+      related: ['useMedia', 'useStreamingAudio', 'VideoGrid', 'VideoTile', 'LocalPreview', 'MediaControlBar'],
+    },
+  },
+} satisfies Meta<typeof UseChatMediaDemo>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Click the buttons to exercise each part of the API. The "handler log" shows
+ * which transport hooks fired — wire those to your producer creation /
+ * close / pause / resume calls.
+ *
+ * Permissions: the demo asks for camera/mic/screen the moment you tap a Start
+ * button. Use a browser session you can grant temporary permissions to.
+ */
+export const InteractiveSandbox: Story = {}

package/src/composables/useChatMedia.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { useChatMedia } from './useChatMedia'
+
+class MockTrack {
+  enabled = true
+  kind: string
+  onended: (() => void) | null = null
+  constructor(kind: string) {
+    this.kind = kind
+  }
+  stop = vi.fn()
+}
+
+const makeStream = (kinds: string[]): MediaStream => {
+  const tracks = kinds.map((k) => new MockTrack(k))
+  return {
+    getTracks: () => tracks,
+    getAudioTracks: () => tracks.filter((t) => t.kind === 'audio'),
+    getVideoTracks: () => tracks.filter((t) => t.kind === 'video'),
+    addTrack: vi.fn(),
+  } as unknown as MediaStream
+}
+
+beforeEach(() => {
+  const audioStream = makeStream(['audio'])
+  const videoStream = makeStream(['video'])
+  const screenStream = makeStream(['video'])
+  ;(navigator as any).mediaDevices = {
+    getUserMedia: vi.fn(async (constraints: MediaStreamConstraints) =>
+      constraints.video ? videoStream : audioStream,
+    ),
+    getDisplayMedia: vi.fn(async () => screenStream),
+  }
+  // jsdom doesn't ship MediaStream; provide a minimal shim for addParticipantTrack
+  if (typeof (globalThis as any).MediaStream === 'undefined') {
+    ;(globalThis as any).MediaStream = class {
+      private tracks: MediaStreamTrack[] = []
+      getTracks() {
+        return this.tracks
+      }
+      addTrack(t: MediaStreamTrack) {
+        this.tracks.push(t)
+      }
+    }
+  }
+})
+
+describe('useChatMedia', () => {
+  it('startAudioCapture sets localAudioStream and fires onTrackStarted', async () => {
+    const onTrackStarted = vi.fn()
+    const media = useChatMedia({ handlers: { onTrackStarted } })
+    await media.startAudioCapture()
+    expect(media.localAudioStream.value).toBeTruthy()
+    expect(media.hasAudio.value).toBe(true)
+    expect(onTrackStarted).toHaveBeenCalledWith(expect.any(Object), 'audio')
+  })
+
+  it('toggleMute toggles the audio track and fires the right handlers', async () => {
+    const onAudioPaused = vi.fn()
+    const onAudioResumed = vi.fn()
+    const media = useChatMedia({ handlers: { onAudioPaused, onAudioResumed } })
+    await media.startAudioCapture()
+    await media.toggleMute()
+    expect(media.isMuted.value).toBe(true)
+    expect(onAudioPaused).toHaveBeenCalled()
+    await media.toggleMute()
+    expect(media.isMuted.value).toBe(false)
+    expect(onAudioResumed).toHaveBeenCalled()
+  })
+
+  it('startVideoCapture sets the stream and clears isVideoOff', async () => {
+    const media = useChatMedia()
+    await media.startVideoCapture()
+    expect(media.localVideoStream.value).toBeTruthy()
+    expect(media.isVideoOff.value).toBe(false)
+    expect(media.hasVideo.value).toBe(true)
+  })
+
+  it('toggleVideo starts capture when off and no stream exists', async () => {
+    const media = useChatMedia()
+    await media.toggleVideo()
+    expect(media.isVideoOff.value).toBe(false)
+    expect(media.localVideoStream.value).toBeTruthy()
+  })
+
+  it('toggleVideo disables tracks when on', async () => {
+    const onVideoPaused = vi.fn()
+    const media = useChatMedia({ handlers: { onVideoPaused } })
+    await media.startVideoCapture()
+    await media.toggleVideo()
+    expect(media.isVideoOff.value).toBe(true)
+    expect(onVideoPaused).toHaveBeenCalled()
+  })
+
+  it('startScreenShare sets the screen stream', async () => {
+    const media = useChatMedia()
+    await media.startScreenShare()
+    expect(media.isScreenSharing.value).toBe(true)
+    expect(media.localScreenStream.value).toBeTruthy()
+  })
+
+  it('participant registry add/get/remove', () => {
+    const media = useChatMedia()
+    const track = new MockTrack('audio') as unknown as MediaStreamTrack
+    media.addParticipantTrack('p1', track)
+    expect(media.getParticipantStream('p1')).toBeTruthy()
+    media.removeParticipant('p1')
+    expect(media.getParticipantStream('p1')).toBeUndefined()
+  })
+
+  it('cleanup stops all tracks and clears state', async () => {
+    const media = useChatMedia()
+    await media.startAudioCapture()
+    await media.startVideoCapture()
+    media.cleanup()
+    expect(media.localAudioStream.value).toBeNull()
+    expect(media.localVideoStream.value).toBeNull()
+    expect(media.isVideoOff.value).toBe(true)
+  })
+})