Showcase Component Architecture

This document provides an overview of the Showcase component architecture, including its key sub-components and their relationships.

Component Hierarchy Diagrams

Main Architecture Overview

MediaRenderer Component Breakdown

PlaybackControls Component Breakdown

AudioPlayer Dependencies

VideoPlayer Dependencies

Custom Hooks Used by Showcase

Component Annotations

Showcase (Main Component)

Location: components/showcase.tsx

The root component that orchestrates the entire media showcase experience. It manages:

• State Management: Current item index, controls visibility, fullscreen mode, theme preferences
• Navigation: Previous/Next item navigation, keyboard shortcuts (arrow keys, space, F for fullscreen, Esc)
• Touch Gestures: Swipe left/right for navigation on mobile devices
• Auto-hide Controls: Automatically fades out controls when video is playing and mouse is inactive
• Theme Support: Light/dark/system theme modes with system preference detection

Key Features:

• Fullscreen toggle functionality
• Click-outside-to-close for playback controls
• Mouse activity tracking for auto-hiding UI elements
• Responsive design with mobile support

MediaRenderer

Location: components/media-renderer.tsx

A router component that renders different media types based on the item.type property. Acts as a factory pattern for media rendering.

Supported Media Types:

• YouTube: Embeds YouTube videos via iframe with autoplay and mute controls
• Vimeo: Embeds Vimeo videos via iframe with autoplay and mute controls
• Video: Renders HTML5 video elements using VideoPlayer component
• Audio: Renders audio playback using AudioPlayer component
• Image: Displays images using Next.js Image component with loading/error states
• Teaser: Renders teaser content using TeaserContent component

Key Features:

• Loading indicators for all media types
• Error handling with user-friendly error messages
• Playback position restoration from localStorage
• Theme-aware styling

PlaybackControls

Location: components/playback-controls.tsx

A comprehensive control panel that slides up from the bottom when activated. Provides unified media playback and navigation controls.

Layout Structure:

1. Top Section: MediaProgress (timeline with time labels)
2. Middle Section: ProgressIndicator (carousel dots for navigation)
3. Bottom Section: Main controls row with:
   • Left: Previous, Play/Pause, Next buttons
   • Right: Volume slider, Fullscreen toggle, Keyboard shortcuts, External link

Key Features:

• Close button (X) in top-right corner
• Click-outside-to-close functionality
• Theme-aware styling (light/dark modes)
• Conditional rendering based on media type capabilities
• Smooth slide-up animation using Framer Motion

AudioPlayer

Location: components/audio-player.tsx

A dedicated audio playback component with album art display and comprehensive controls.

Features:

• Album Art Display: Shows cover image or placeholder
• Track Information: Title and artist display
• Playback Controls: Previous, Play/Pause, Next buttons
• Progress Bar: Clickable timeline with scrubbing support
• Volume Control: Vertical volume slider with mute toggle
• Full Frame Toggle: Fullscreen mode support
• Smart Previous Button: If playhead is at zero, goes to previous item instead of seeking

Key Functionality:

• Playback position persistence in localStorage
• Automatic next track on audio end
• Timeline scrubbing via useMediaScrubbing hook
• Click-outside-to-close for volume slider

VideoPlayer

Location: components/video-player.tsx

A video playback component with controls overlay and fullscreen support.

Features:

• Video Element: HTML5 video with custom controls
• Progress Bar: Clickable timeline with scrubbing support
• Control Overlay: Auto-hiding controls on mouse inactivity
• Volume Control: Vertical volume slider with mute toggle
• Fullscreen Toggle: Fullscreen mode support

Key Functionality:

• Playback position persistence in localStorage
• Automatic next video on end
• Timeline scrubbing via useMediaScrubbing hook
• Click-outside-to-close for volume slider
• Mouse activity tracking for control visibility

Logo

Location: components/logo.tsx

A toggle button component positioned in the bottom-left corner that opens/closes the PlaybackControls panel.

Features:

• Keyboard icon display
• Click handler to toggle controls visibility
• Fade-out animation when controls are hidden
• Positioned absolutely in bottom-left corner

MediaProgress

Location: components/media-progress.tsx

A timeline component that displays media progress with time labels and clickable scrubbing.

Features:

• Progress Bar: Visual representation of playback progress
• Time Labels: Current time and total duration (mm:ss format)
• Scrubbing: Click anywhere on timeline to seek to that position
• Theme Support: Light/dark mode styling
• Dynamic Updates: Updates every 250ms during playback

Note: Uses document.querySelector to find media elements dynamically, making it compatible with both AudioPlayer and VideoPlayer.

ProgressIndicator

Location: components/progress-indicator.tsx

A carousel navigation component displaying dots for each item in the showcase.

Features:

• Dot Navigation: Click any dot to jump to that item
• Current Item Highlight: Active dot is visually distinct
• Flexible Positioning: Can be absolute or relative positioned
• Theme Support: Light/dark mode styling
• Fade Animation: Can fade in/out based on visibility state

VerticalVolumeSlider

Location: components/vertical-volume-slider.tsx

A vertical volume control slider that appears above the volume button.

Features:

• Vertical Slider: Draggable volume control
• Visual Feedback: Shows current volume level
• Mute Indicator: Visual indication when muted
• Theme Support: Light/dark mode styling
• Smooth Animations: Fade in/out transitions

KeyboardShortcuts

Location: components/keyboard-shortcuts.tsx

A modal component that displays available keyboard shortcuts.

Features:

• Modal Display: Centered popup with backdrop
• Shortcut List: Displays key combinations and their actions
• Theme Support: Light/dark mode styling
• Click-outside-to-close: Click backdrop to dismiss
• Centered Layout: Vertically centered with proper padding

Keyboard Shortcuts Displayed:

• ← : Previous item
• → : Next item
• Space : Play/Pause media
• Esc : Close menus
• Tab : Navigate UI elements

TeaserContent

Location: components/teaser-content.tsx

A component for displaying teaser content with custom styling.

Features:

• Custom content rendering
• Theme-aware styling
• Flexible layout support

Custom Hooks

useMediaControls

Location: hooks/use-media-controls.ts

Centralized hook for managing media playback state (playing, muted, volume).

useClickOutside

Location: hooks/use-click-outside.ts

Reusable hook for detecting clicks outside a referenced element. Used for closing modals, dropdowns, and volume sliders.

useFullscreen

Location: hooks/use-fullscreen.ts

Centralized hook for managing fullscreen functionality. Handles entering/exiting fullscreen and state synchronization.

useMediaScrubbing

Location: hooks/use-media-scrubbing.ts

Hook for handling timeline scrubbing. Calculates click position, updates media element's currentTime, and manages localStorage persistence.

Data Flow

1. Showcase loads items from showcaseData JSON file
2. Showcase manages current index and passes current item to MediaRenderer
3. MediaRenderer routes to appropriate player component based on media type
4. Player components handle their own playback state but communicate through callbacks
5. PlaybackControls receives state from Showcase and provides unified control interface
6. User interactions flow back up through callbacks to Showcase for state updates

State Management

• Showcase maintains: currentIndex, showControls, isFullscreen, controlsVisible
• useMediaControls hook maintains: isPlaying, isMuted, volume
• Individual player components maintain: currentTime, duration, loading states
• localStorage persists: playback positions per item ID

Theme System

All components support light/dark/system theme modes:

• Theme preference can be set via props or config
• System preference is detected automatically
• All components use theme-aware CSS classes
• Consistent color schemes across all UI elements